RigidBody3D

继承: PhysicsBody3D < CollisionObject3D < Node3D < Node < Object

派生: VehicleBody3D

由物理仿真进行移动的 3D 物理体。

描述

RigidBody3D 实现了完整的 3D 物理。这个物理体无法直接控制,必须对其施加力(重力、冲量等),物理仿真将计算由此产生的移动、旋转、对碰撞的反应以及对沿路其他物理体的影响等。

可以使用 lock_rotationfreeze、和 freeze_mode 调整该物理体的行为。通过修改该对象的 mass 等属性,你可以控制物理仿真对其的影响。

即使施加了力,刚体也会始终维持自身的形状和大小。适用于环境中可交互的对象,例如能够推倒的树木或者能够被推动的一堆箱子。

如果你需要覆盖默认的物理行为,你可以编写自定义的力整合函数。见 custom_integrator

注意:频繁修改 RigidBody3D 的 3D 变换或 linear_velocity 可能导致无法预期的行为。如果你需要直接影响物理体,请优先使用 _integrate_forces,能够直接访问物理状态。

教程

属性

float

angular_damp

0.0

DampMode

angular_damp_mode

0

Vector3

angular_velocity

Vector3(0, 0, 0)

bool

can_sleep

true

Vector3

center_of_mass

Vector3(0, 0, 0)

CenterOfMassMode

center_of_mass_mode

0

Vector3

constant_force

Vector3(0, 0, 0)

Vector3

constant_torque

Vector3(0, 0, 0)

bool

contact_monitor

false

bool

continuous_cd

false

bool

custom_integrator

false

bool

freeze

false

FreezeMode

freeze_mode

0

float

gravity_scale

1.0

Vector3

inertia

Vector3(0, 0, 0)

float

linear_damp

0.0

DampMode

linear_damp_mode

0

Vector3

linear_velocity

Vector3(0, 0, 0)

bool

lock_rotation

false

float

mass

1.0

int

max_contacts_reported

0

PhysicsMaterial

physics_material_override

bool

sleeping

false

方法

void

_integrate_forces ( PhysicsDirectBodyState3D state ) virtual

void

add_constant_central_force ( Vector3 force )

void

add_constant_force ( Vector3 force, Vector3 position=Vector3(0, 0, 0) )

void

add_constant_torque ( Vector3 torque )

void

apply_central_force ( Vector3 force )

void

apply_central_impulse ( Vector3 impulse )

void

apply_force ( Vector3 force, Vector3 position=Vector3(0, 0, 0) )

void

apply_impulse ( Vector3 impulse, Vector3 position=Vector3(0, 0, 0) )

void

apply_torque ( Vector3 torque )

void

apply_torque_impulse ( Vector3 impulse )

Node3D[]

get_colliding_bodies ( ) const

int

get_contact_count ( ) const

Basis

get_inverse_inertia_tensor ( ) const

void

set_axis_velocity ( Vector3 axis_velocity )


信号

body_entered ( Node body )

当与另一个 PhysicsBody3DGridMap 发生碰撞时发出。需要将 contact_monitor 设置为 true,并将 max_contacts_reported 设置得足够高以检测所有碰撞。如果 MeshLibrary 具有碰撞 Shape3D,则 GridMap 会被检测。

body 是其他 PhysicsBody3DGridMapNode,如果该节点存在于树中。


body_exited ( Node body )

当与另一个 PhysicsBody3DGridMap 的碰撞结束时发出。需要将 contact_monitor 设置为 true,并将 max_contacts_reported 设置得足够高以检测所有碰撞。如果 MeshLibrary 具有碰撞 Shape3D,则 GridMap 会被检测。

body 是其他 PhysicsBody3DGridMapNode,如果该节点存在于树中。


body_shape_entered ( RID body_rid, Node body, int body_shape_index, int local_shape_index )

当该 RigidBody3D 的一个 Shape3D 与另一个 PhysicsBody3DGridMapShape3D 碰撞时发出。需要将 contact_monitor 设置为 true,并将 max_contacts_reported 设置得足够高以检测所有碰撞。如果 MeshLibrary 具有 Collision Shape3D,则 GridMap 会被检测到。

body_ridPhysicsServer3D 使用的其他 PhysicsBody3DMeshLibraryCollisionObject3DRID

body 其他 PhysicsBody3DGridMapNode,如果该节点存在于树中。

body_shape_indexPhysicsServer3D 使用的其他 PhysicsBody3DGridMapShape3D 的索引。该 CollisionShape3D 节点可以使用 body.shape_owner_get_owner(body.shape_find_owner(body_shape_index)) 获取。

local_shape_indexPhysicsServer3D 使用的该 RigidBody3D 的 Shape3D 的索引。该 CollisionShape3D 节点可以使用 self.shape_owner_get_owner(self.shape_find_owner(local_shape_index)) 获取。


body_shape_exited ( RID body_rid, Node body, int body_shape_index, int local_shape_index )

当该 RigidBody3D 的一个 Shape3D 与另一个 PhysicsBody3DGridMapShape3D 之间的碰撞结束时发出。需要将 contact_monitor 设置为 true,并将 max_contacts_reported 设置得足够高以检测所有碰撞。如果 MeshLibrary 具有碰撞 Shape3D,则 GridMap 将被检测。

body_ridPhysicsServer3D 使用的其他 PhysicsBody3DMeshLibraryCollisionObject3DRID。如果网格具有 Shape3D,则 GridMap 将被检测。

body 其他 PhysicsBody3DGridMapNode,如果该节点存在于树中。

body_shape_indexPhysicsServer3D 使用的其他 PhysicsBody3DGridMapShape3D 的索引。该 CollisionShape3D 节点可以使用 body.shape_owner_get_owner(body.shape_find_owner(body_shape_index)) 获取。

local_shape_indexPhysicsServer3D 使用的该 RigidBody3D 的 Shape3D 的索引。该 CollisionShape3D 节点可以使用 self.shape_owner_get_owner(self.shape_find_owner(local_shape_index)) 获取。


sleeping_state_changed ( )

当物理引擎改变物体的睡眠状态时发出。

注意:改变 sleeping 的值不会触发这个信号。只有当物理引擎改变了睡眠状态或者使用了 emit_signal("sleeping_state_changed") 时,它才会被发出。


枚举

enum FreezeMode:

FreezeMode FREEZE_MODE_STATIC = 0

静态物体冻结模式(默认)。物体不受重力和力的影响。它只能由用户的代码移动,并且其他物体沿其路径运动时,不会与之发生碰撞。

FreezeMode FREEZE_MODE_KINEMATIC = 1

运动物体的冻结模式。类似于 FREEZE_MODE_STATIC ,但是在移动时会与其路径上的其他物体发生碰撞。适用于需要动画的冻结物体。


enum CenterOfMassMode:

CenterOfMassMode CENTER_OF_MASS_MODE_AUTO = 0

在此模式下,该物体的质心将基于其形状自动计算。此处的前提是各个形状的原点也是对应的质心。

CenterOfMassMode CENTER_OF_MASS_MODE_CUSTOM = 1

在此模式下,物体的质心通过 center_of_mass 设置。默认为物体的原点位置。


enum DampMode:

DampMode DAMP_MODE_COMBINE = 0

在这种模式下,物体的阻尼值将被加到区域中设置的任何值或默认值。

DampMode DAMP_MODE_REPLACE = 1

在这种模式下,物体的阻尼值将替换掉区域中设置的任何值或默认值。


属性说明

float angular_damp = 0.0

  • void set_angular_damp ( float value )

  • float get_angular_damp ( )

阻碍物体的旋转。默认情况下,物体将使用 项目 > 项目设置 > 物理 > 3d 中的默认角度阻尼,或物体所在的 Area3D 中设置的任何覆盖值。取决于 angular_damp_mode,可以设置 angular_damp 以增加或替换物体的阻尼值。

有关阻尼的更多详细信息,请参阅 ProjectSettings.physics/3d/default_angular_damp


DampMode angular_damp_mode = 0

  • void set_angular_damp_mode ( DampMode value )

  • DampMode get_angular_damp_mode ( )

定义如何应用 angular_damp。可能的取值见 DampMode


Vector3 angular_velocity = Vector3(0, 0, 0)

  • void set_angular_velocity ( Vector3 value )

  • Vector3 get_angular_velocity ( )

该 RigidBody3D 的旋转速度,单位为弧度每秒。


bool can_sleep = true

  • void set_can_sleep ( bool value )

  • bool is_able_to_sleep ( )

如果为 true,则物体未运动时可以进入睡眠模式。见 sleeping


Vector3 center_of_mass = Vector3(0, 0, 0)

  • void set_center_of_mass ( Vector3 value )

  • Vector3 get_center_of_mass ( )

center_of_mass_mode 设置为 CENTER_OF_MASS_MODE_CUSTOM 时,物体的自定义质心相对于物体原点位置的位置。这是物体的平衡点,只有施加在质心内的力才会引起线性加速度。施加在质心之外的力会引起角加速度。

center_of_mass_mode 设置为 CENTER_OF_MASS_MODE_AUTO(默认值)时,会自动计算质心。


CenterOfMassMode center_of_mass_mode = 0

定义设置物体质心的方式。可能的取值见 CenterOfMassMode


Vector3 constant_force = Vector3(0, 0, 0)

  • void set_constant_force ( Vector3 value )

  • Vector3 get_constant_force ( )

在每个物理更新期间施加到物体的总恒定位置的力。

add_constant_forceadd_constant_central_force


Vector3 constant_torque = Vector3(0, 0, 0)

  • void set_constant_torque ( Vector3 value )

  • Vector3 get_constant_torque ( )

在每个物理更新期间施加的物体的总恒定旋转力。

add_constant_torque


bool contact_monitor = false

  • void set_contact_monitor ( bool value )

  • bool is_contact_monitor_enabled ( )

如果为 true,则该 RigidBody3D 将在与其他物体碰撞时发出信号。

注意:默认情况下,报告的最大接触数被设置为 0,表示不会记录任何内容,见 max_contacts_reported


bool continuous_cd = false

  • void set_use_continuous_collision_detection ( bool value )

  • bool is_using_continuous_collision_detection ( )

如果为 true,则使用连续碰撞检测。

连续碰撞检测尝试预测一个移动的物体会在哪里碰撞,而不是移动它并在它发生碰撞时纠正它的运动。连续碰撞检测更精确,并且错过了较小的、快速移动的物体的撞击。不使用连续碰撞检测的计算速度更快,但可能会错过小的、快速移动的物体。


bool custom_integrator = false

  • void set_use_custom_integrator ( bool value )

  • bool is_using_custom_integrator ( )

如果为 true,则该物体的内力积分将被禁用(如重力或空气摩擦)。除了碰撞响应之外,物体将仅根据 _integrate_forces 函数确定的方式移动(如果已定义)。


bool freeze = false

  • void set_freeze_enabled ( bool value )

  • bool is_freeze_enabled ( )

如果为 true,则该物体被冻结。不再施加重力和力。

要设置冻结时物体的行为,见 freeze_mode

对于始终冻结的物体,请改用 StaticBody3DAnimatableBody3D


FreezeMode freeze_mode = 0

物体的冻结模式。可用于设置启用 freeze 时物体的行为。可能的取值见 FreezeMode

对于始终冻结的物体,请使用 StaticBody3DAnimatableBody3D


float gravity_scale = 1.0

  • void set_gravity_scale ( float value )

  • float get_gravity_scale ( )

此值将乘以在 项目 > 项目设置 > 物理 > 3D 中获取的全局 3D 重力设置,以产生 RigidBody3D 的重力。例如,值为 1 表示正常重力,值为 2 将施加双倍重力,而值为 0.5 将施加一半重力到该对象。


Vector3 inertia = Vector3(0, 0, 0)

该物体的惯性力矩。与质量类似,但适用于旋转:用于确定各个轴上需要施加多少扭矩才能让该物体旋转。通常会自动根据质量和形状计算惯性力矩,但这个属性能够让你设置自定义的值。

设置为 Vector3.ZERO 时,会自动计算惯性(默认值)。

注意:自动计算出惯性后,这个值不会改变。请使用 PhysicsServer3D 获取计算出的惯性。

GDScriptC#

  1. @onready var ball = $Ball
  2. func get_ball_inertia():
  3. return PhysicsServer3D.body_get_direct_state(ball.get_rid()).inverse_inertia.inverse()
  1. private RigidBody3D _ball;
  2. public override void _Ready()
  3. {
  4. _ball = GetNode<RigidBody3D>("Ball");
  5. }
  6. private Vector3 GetBallInertia()
  7. {
  8. return PhysicsServer3D.BodyGetDirectState(_ball.GetRid()).InverseInertia.Inverse();
  9. }

float linear_damp = 0.0

  • void set_linear_damp ( float value )

  • float get_linear_damp ( )

阻碍物体的运动。默认情况下,物体将使用 项目 > 项目设置 > 物理 > 3d 中的默认线性阻尼,或物体所在的 Area3D 中设置的任何覆盖值。取决于 linear_damp_mode,可以设置 linear_damp 以增加或替换物体的阻尼值。

有关阻尼的更多详细信息,请参阅 ProjectSettings.physics/3d/default_linear_damp


DampMode linear_damp_mode = 0

  • void set_linear_damp_mode ( DampMode value )

  • DampMode get_linear_damp_mode ( )

定义如何应用 linear_damp。有关可能的值,请参阅 DampMode


Vector3 linear_velocity = Vector3(0, 0, 0)

  • void set_linear_velocity ( Vector3 value )

  • Vector3 get_linear_velocity ( )

物体的线速度,单位为单位每秒。可以偶尔使用,但是不要每一帧都设置它,因为物理可能在另一个线程中运行,并且以不同的间隔。使用 _integrate_forces 作为你的进程循环,以精确控制物体状态。


bool lock_rotation = false

  • void set_lock_rotation_enabled ( bool value )

  • bool is_lock_rotation_enabled ( )

如果为 true,则该物体不能旋转。重力和力只施加线性运动。


float mass = 1.0

  • void set_mass ( float value )

  • float get_mass ( )

实体的质量。


int max_contacts_reported = 0

  • void set_max_contacts_reported ( int value )

  • int get_max_contacts_reported ( )

将记录的最大接触点数。需要一个大于 0 的值,并将 contact_monitor 设置为 true 以开始注册接触。使用 get_contact_count 检索计数或使用 get_colliding_bodies 检索已发生碰撞的物体。

注意:接触点的数量不同于碰撞的数量。平行边之间的碰撞将导致两个接触点(每个端点一个),平行面之间的碰撞将导致四个接触点(每个角落一个)。


PhysicsMaterial physics_material_override

物体的物理材质。

如果为该属性指定了一种材质,则将使用该材质代替任何其他物理材质,例如继承的材质。


bool sleeping = false

  • void set_sleeping ( bool value )

  • bool is_sleeping ( )

如果为 true ,该刚体将不会移动,也不会计算受力,直到被另一个物体唤醒,例如通过碰撞或使用 apply_impulseapply_force 方法。


方法说明

void _integrate_forces ( PhysicsDirectBodyState3D state ) virtual

在物理处理过程中被调用,允许你读取并安全地修改对象的模拟状态。默认情况下,它会和通常的物理行为一起生效,但是你可以通过 custom_integrator 属性禁用默认行为,为物体施加完全自定义的合力。


void add_constant_central_force ( Vector3 force )

在不影响旋转的情况下,添加一个恒定的定向力,该力会随着时间的推移而持续施加,直到使用 constant_force = Vector3(0, 0, 0) 清除。

这相当于在物体的质心处,使用 add_constant_force


void add_constant_force ( Vector3 force, Vector3 position=Vector3(0, 0, 0) )

向实体添加一个恒定的定位力,持续施加,直到用 constant_force = Vector3(0, 0, 0) 清除。

position 是在全局坐标中距实体原点的偏移量。


void add_constant_torque ( Vector3 torque )

在不影响位置的情况下,添加一个恒定的旋转力,该力会随着时间的推移而持续施加,直到使用 constant_torque = Vector3(0, 0, 0) 清除。


void apply_central_force ( Vector3 force )

施加一个不影响旋转的定向力。该力是时间相关的,意味着每次物理更新都会施加。

这相当于在物体的质心处,使用 apply_force


void apply_central_impulse ( Vector3 impulse )

施加一个不影响的旋转定向冲量。

冲量与时间无关!每帧应用一个冲量,会产生一个依赖于帧速率的力。出于这个原因,它应该只在模拟一次性影响时使用(否则使用 “_force”函数)。

这相当于在物体的质心处,使用 apply_impulse


void apply_force ( Vector3 force, Vector3 position=Vector3(0, 0, 0) )

对实体施加一个定位力。力是时间相关的,意味着每次物理更新都会被施加。

position 是在全局坐标中距实体原点的偏移量。


void apply_impulse ( Vector3 impulse, Vector3 position=Vector3(0, 0, 0) )

向实体施加一个定位冲量。

冲量是时间无关的!每帧施加一个冲量将产生一个依赖于帧速率的力。出于这个原因,它应该只在模拟一次性影响时使用(否则使用“_force”函数)。

position 是在全局坐标中距实体原点的偏移量。


void apply_torque ( Vector3 torque )

施加旋转力但不影响位置。力是与时间相关的,应该每次物理更新时都要进行施加。

注意:inertia 才能正常工作。要让 inertia 存在,必须有一个 CollisionShape3D 作为该节点的子节点,或者你也可以手动设置 inertia


void apply_torque_impulse ( Vector3 impulse )

在不影响位置的情况下,向实体施加一个旋转冲量。

冲量是时间无关的!每帧施加一个冲量将产生一个依赖于帧速率的力。出于这个原因,它应该只在模拟一次性影响时使用(否则使用“_force”函数)。

注意:需要 inertia 才能发挥作用。要具有 inertia,活动的 CollisionShape3D 必须是该节点的一个子节点,或者可以手动设置 inertia


Node3D[] get_colliding_bodies ( ) const

返回与此物体发生碰撞的物体的列表。需要将 contact_monitor 设置为 true,并将 max_contacts_reported 设置足够高以侦测所有碰撞。

注意:此测试的结果不会立即在移动物体后得出。为了提高性能,碰撞列表每帧更新一次,且在物理步骤之前进行。可考虑改用信号来代替。


int get_contact_count ( ) const

返回此物体与其他物体的接触数。默认情况下,除非配置监视接触的物体(见 contact_monitor),否则返回 0。

注意:要获取正在碰撞的物体,请使用 get_colliding_bodies


Basis get_inverse_inertia_tensor ( ) const

返回逆惯性张量基础。这用于计算施加到 RigidBody3D 上的扭矩产生的角加速度。


void set_axis_velocity ( Vector3 axis_velocity )

设置轴速度。给定向量轴上的速度将被设置为给定向量长度。这对跳跃行为很有用。

Previous Next


© 版权所有 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0). Revision b1c660f7.

Built with Sphinx using a theme provided by Read the Docs.