Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
RigidBody2D
继承： PhysicsBody2D < CollisionObject2D < Node2D < CanvasItem < Node < Object
派生： PhysicalBone2D
由物理仿真进行移动的 2D 物理体。
描述
RigidBody2D 实现了完整的 2D 物理。这个物理体无法直接控制，必须对其施加力（重力、冲量等），物理仿真将计算由此产生的移动、旋转、对碰撞的反应以及对沿路其他物理体的影响等。
可以使用 lock_rotation、freeze 和 freeze_mode 调整该物理体的行为。通过修改该对象的 mass 等属性，你可以控制物理仿真对其的影响。
即使施加了力，刚体也会始终维持自身的形状和大小。适用于环境中可交互的对象，例如能够推倒的树木或者能够被推动的一堆箱子。
如果你需要覆盖默认的物理行为，你可以编写自定义的力整合函数。见 custom_integrator。
注意：频繁修改 RigidBody2D 的 2D 变换或 linear_velocity 可能导致无法预期的行为。如果你需要直接影响物理体，请优先使用 _integrate_forces，能够直接访问物理状态。
教程
属性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法
void |
_integrate_forces(state: PhysicsDirectBodyState2D) virtual |
void |
add_constant_central_force(force: Vector2) |
void |
add_constant_force(force: Vector2, position: Vector2 = Vector2(0, 0)) |
void |
add_constant_torque(torque: float) |
void |
apply_central_force(force: Vector2) |
void |
apply_central_impulse(impulse: Vector2 = Vector2(0, 0)) |
void |
apply_force(force: Vector2, position: Vector2 = Vector2(0, 0)) |
void |
apply_impulse(impulse: Vector2, position: Vector2 = Vector2(0, 0)) |
void |
apply_torque(torque: float) |
void |
apply_torque_impulse(torque: float) |
get_colliding_bodies() const |
|
get_contact_count() const |
|
void |
set_axis_velocity(axis_velocity: Vector2) |
信号
当与另一个 PhysicsBody2D 或 TileMap 发生碰撞时发出。需要将 contact_monitor 设置为 true，并将 max_contacts_reported 设置得足够高以检测所有碰撞。如果 TileSet 具有碰撞 Shape2D，则 TileMap 将被检测。
body 是其他 PhysicsBody2D 或 TileMap 的 Node，如果该节点存在于树中。
当与另一个 PhysicsBody2D 或 TileMap 的碰撞结束时发出。需要将 contact_monitor 设置为 true，并将 max_contacts_reported 设置得足够高以检测所有碰撞。如果 TileSet 具有碰撞 Shape2D，则 TileMap 将被检测。
body 是其他 PhysicsBody2D 或 TileMap 的 Node，如果该节点存在于树中。
body_shape_entered(body_rid: RID, body: Node, body_shape_index: int, local_shape_index: int) 🔗
当该 RigidBody2D 的一个 Shape2D 与另一个 PhysicsBody2D 或 TileMap 的 Shape2D 碰撞时发出。需要将 contact_monitor 设置为 true，并将 max_contacts_reported 设置得足够高以检测所有碰撞。如果 TileSet 具有 Collision Shape2D，则 TileMap 会被检测到。
body_rid 由 PhysicsServer2D 使用的其他 PhysicsBody2D 或 TileSet 的 CollisionObject2D 的 RID。
body 其他 PhysicsBody2D 或 TileMap 的 Node，如果该节点存在于树中。
body_shape_index 由 PhysicsServer2D 使用的其他 PhysicsBody2D 或 TileMap 的 Shape2D 的索引。该 CollisionShape2D 节点可以使用 body.shape_owner_get_owner(body.shape_find_owner(body_shape_index)) 获取。
local_shape_index 由 PhysicsServer2D 使用的该 RigidBody2D 的 Shape2D 的索引。该 CollisionShape2D 节点可以使用 self.shape_owner_get_owner(self.shape_find_owner(local_shape_index)) 获取。
body_shape_exited(body_rid: RID, body: Node, body_shape_index: int, local_shape_index: int) 🔗
当该 RigidBody2D 的一个 Shape2D 与另一个 PhysicsBody2D 或 TileMap 的 Shape2D 之间的碰撞结束时发出。需要将 contact_monitor 设置为 true，并将 max_contacts_reported 设置得足够高以检测所有碰撞。如果 TileSet 具有 Collision Shape2D，则 TileMap 会被检测到。
body_rid 由 PhysicsServer2D 使用的其他 PhysicsBody2D 或 TileSet 的 CollisionObject2D 的 RID。
body 其他 PhysicsBody2D 或 TileMap 的 Node，如果该节点存在于树中。
body_shape_index 由 PhysicsServer2D 使用的其他 PhysicsBody2D 或 TileMap 的 Shape2D 的索引。该 CollisionShape2D 节点可以使用 body.shape_owner_get_owner(body.shape_find_owner(body_shape_index)) 获取。
local_shape_index 由 PhysicsServer2D 使用的该 RigidBody2D 的 Shape2D 的索引。该 CollisionShape2D 节点可以使用 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
在这种模式下，物体的阻尼值将替换掉区域中设置的任何值或默认值。
enum CCDMode: 🔗
CCDMode CCD_MODE_DISABLED = 0
禁用连续碰撞检测。这是检测物体碰撞的最快方法，但可能会错过小型、快速移动的物体。
CCDMode CCD_MODE_CAST_RAY = 1
使用射线投射启用连续碰撞检测。这比形状投射快，但精度较低。
CCDMode CCD_MODE_CAST_SHAPE = 2
使用形状投射启用连续碰撞检测。这是最慢的 CCD 方法，也是最精确的。
属性说明
Damps the body's rotation. By default, the body will use the ProjectSettings.physics/2d/default_angular_damp setting or any value override set by an Area2D the body is in. Depending on angular_damp_mode, you can set angular_damp to be added to or to replace the body's damping value.
See ProjectSettings.physics/2d/default_angular_damp for more details about damping.
DampMode angular_damp_mode = 0 🔗
定义如何应用 angular_damp。可能的取值见 DampMode。
float angular_velocity = 0.0 🔗
物体的旋转速度，单位为弧度每秒。
如果为 true，则物体未运动时可以进入睡眠模式。见 sleeping 。
Vector2 center_of_mass = Vector2(0, 0) 🔗
当 center_of_mass_mode 设置为 CENTER_OF_MASS_MODE_CUSTOM 时，物体的自定义质心相对于物体原点位置的位置。这是物体的平衡点，只有施加在质心内的力才会引起线性加速度。施加在质心之外的力会引起角加速度。
当 center_of_mass_mode 设置为 CENTER_OF_MASS_MODE_AUTO（默认值）时，会自动计算质心。
CenterOfMassMode center_of_mass_mode = 0 🔗
void set_center_of_mass_mode(value: CenterOfMassMode)
CenterOfMassMode get_center_of_mass_mode()
定义设置物体质心的方式。可能的取值见 CenterOfMassMode。
Vector2 constant_force = Vector2(0, 0) 🔗
在每个物理更新期间施加到物体的总恒定位置的力。
见 add_constant_force 和 add_constant_central_force 。
在每个物理更新期间施加的物体的总恒定旋转力。
bool contact_monitor = false 🔗
如果为 true，则该 RigidBody2D 将在与其他物体碰撞时发出信号。
注意：默认情况下，报告的最大接触数被设置为 0，表示不会记录任何内容，见 max_contacts_reported。
void set_continuous_collision_detection_mode(value: CCDMode)
CCDMode get_continuous_collision_detection_mode()
连续碰撞检测模式。
连续碰撞检测尝试预测一个移动的物体会在哪里碰撞，而不是移动它并在碰撞后纠正它的运动。连续碰撞检测速度较慢，但更精确，并且与快速移动的小物体发生碰撞时遗漏更少。可以使用光线投射和形状投射方法。有关详细信息，请参阅 CCDMode。
bool custom_integrator = false 🔗
如果 true，则该物体的标准力积分（如重力或阻尼）将被禁用。除了碰撞响应之外，如果覆盖了 _integrate_forces 方法，则物体将仅按照该方法确定的方式移动。
设置该属性将在内部调用方法 PhysicsServer2D.body_set_omit_force_integration。
如果位 true，则物体被冻结。不再施加重力和力。
请参阅 freeze_mode，以设置冻结时，物体的行为。
对于始终冻结的物体，请改用 StaticBody2D 或 AnimatableBody2D。
FreezeMode freeze_mode = 0 🔗
void set_freeze_mode(value: FreezeMode)
FreezeMode get_freeze_mode()
该物体的冻结模式。可以设置该物体在启用 freeze 时的行为。可能的值见 FreezeMode。
对于始终冻结的物体，请改用 StaticBody3D 或 AnimatableBody3D。
Multiplies the gravity applied to the body. The body's gravity is calculated from the ProjectSettings.physics/2d/default_gravity project setting and/or any additional gravity vector applied by Area2Ds.
该物体的转动惯量。与质量类似，但用于旋转：用于确定需要施加多少力矩才能让该物体旋转。通常会自动根据质量和形状计算转动惯量，但这个属性能够让你设置自定义的值。
设置为 0 时，会自动计算惯量（默认值）。
注意：自动计算出惯量后，这个值不会改变。请使用 PhysicsServer2D 获取计算出的惯量。
@onready var ball = $Ball
func get_ball_inertia():
return 1.0 / PhysicsServer2D.body_get_direct_state(ball.get_rid()).inverse_inertia
private RigidBody2D _ball;
public override void _Ready()
{
_ball = GetNode<RigidBody2D>("Ball");
}
private float GetBallInertia()
{
return 1.0f / PhysicsServer2D.BodyGetDirectState(_ball.GetRid()).InverseInertia;
}
Damps the body's movement. By default, the body will use the ProjectSettings.physics/2d/default_linear_damp setting or any value override set by an Area2D the body is in. Depending on linear_damp_mode, you can set linear_damp to be added to or to replace the body's damping value.
See ProjectSettings.physics/2d/default_linear_damp for more details about damping.
DampMode linear_damp_mode = 0 🔗
定义如何应用 linear_damp。有关可能的值，请参阅 DampMode。
Vector2 linear_velocity = Vector2(0, 0) 🔗
该实体的线速度，单位为像素每秒。可以偶尔使用，但是不要每一帧都去设置，因为物理可能在另一个线程中运行，并且以不同的间隔。使用 _integrate_forces 作为你的进程循环，以精确控制物体状态。
如果为 true，则该物体不能旋转。重力和力只施加线性运动。
实体的质量。
int max_contacts_reported = 0 🔗
将记录的最大接触点数。需要一个大于 0 的值，并将 contact_monitor 设置为 true 以开始注册接触。使用 get_contact_count 检索计数或使用 get_colliding_bodies 检索已发生碰撞的物体。
注意：接触点的数量不同于碰撞的数量。平行边之间的碰撞将导致两个接触点（每个端点一个），平行面之间的碰撞将导致四个接触点（每个角落一个）。
PhysicsMaterial physics_material_override 🔗
void set_physics_material_override(value: PhysicsMaterial)
PhysicsMaterial get_physics_material_override()
物体的物理材质。
如果为该属性指定了一种材质，则将使用该材质代替任何其他物理材质，例如继承的材质。
如果为 true ，该刚体将不会移动，也不会计算受力，直到被另一个物体唤醒，例如通过碰撞或使用 apply_impulse 或 apply_force 方法。
方法说明
void _integrate_forces(state: PhysicsDirectBodyState2D) virtual 🔗
在物理处理过程中被调用，允许你读取并安全地修改对象的模拟状态。默认情况下，它在标准力积分之前调用，但 custom_integrator 属性允许你禁用标准力积分并对物体进行完全自定义的力积分。
void add_constant_central_force(force: Vector2) 🔗
在不影响旋转的情况下，添加一个定向的恒定力，该力会随着时间的推移而持续施加，直到使用 constant_force = Vector2(0, 0) 清除。
这相当于在物体的质心处，使用 add_constant_force。
void add_constant_force(force: Vector2, position: Vector2 = Vector2(0, 0)) 🔗
向实体添加一个恒定的定位力，持续施加，直到用 constant_force = Vector2(0, 0) 清除。
position 是在全局坐标中距实体原点的偏移量。
void add_constant_torque(torque: float) 🔗
添加一个恒定的旋转力矩，而不影响位置，该力会随着时间的推移不断施加，直到使用 constant_torque = 0 清除。
void apply_central_force(force: Vector2) 🔗
施加一个不影响旋转的定向力。该力是时间相关的，意味着每次物理更新都会施加。
这相当于在物体的质心处，使用 apply_force。
void apply_central_impulse(impulse: Vector2 = Vector2(0, 0)) 🔗
施加一个不影响的旋转定向冲量。
冲量与时间无关！每帧应用一个冲量，会产生一个依赖于帧速率的力。出于这个原因，它应该只在模拟一次性影响时使用（否则使用 “_force”函数）。
这相当于在物体的质心处，使用 apply_impulse。
void apply_force(force: Vector2, position: Vector2 = Vector2(0, 0)) 🔗
对实体施加一个定位力。力是时间相关的，意味着每次物理更新都会被施加。
position 是在全局坐标中距实体原点的偏移量。
void apply_impulse(impulse: Vector2, position: Vector2 = Vector2(0, 0)) 🔗
向实体施加一个定位冲量。
冲量是时间无关的！每帧施加一个冲量将产生一个依赖于帧速率的力。出于这个原因，它应该只在模拟一次性影响时使用（否则使用“_force”函数）。
position 是在全局坐标中距实体原点的偏移量。
void apply_torque(torque: float) 🔗
施加旋转力但不影响位置。力是与时间相关的，应该每次物理更新时都要进行施加。
注意：有 inertia 才能正常工作。要让 inertia 存在，必须有一个 CollisionShape2D 作为该节点的子节点，或者你也可以手动设置 inertia。
void apply_torque_impulse(torque: float) 🔗
在不影响位置的情况下，向实体施加一个旋转冲量。
冲量是时间无关的！每帧施加一个冲量将产生依赖于帧速率的力。出于这个原因，它应该只在模拟一次性影响时使用（否则使用“_force”函数）。
注意：需要 inertia 才能发挥作用。要具有 inertia，活动的 CollisionShape2D 必须是该节点的一个子节点，或者可以手动设置 inertia。
Array[Node2D] get_colliding_bodies() const 🔗
返回与此物体发生碰撞的物体的列表。需要将 contact_monitor 设置为 true，并将 max_contacts_reported 设置足够高以侦测所有碰撞。
注意：此测试的结果不会立即在移动物体后得出。为了提高性能，碰撞列表每帧更新一次，且在物理迭代之前进行。可考虑改用信号来代替。
int get_contact_count() const 🔗
返回此物体与其他物体的接触数。默认情况下，除非配置监视接触的物体（见 contact_monitor），否则返回 0。
注意：要获取正在碰撞的物体，请使用 get_colliding_bodies。
void set_axis_velocity(axis_velocity: Vector2) 🔗
设置物体在给定轴上的速度。给定矢量轴上的速度将设置为给定向量长度。这对于跳跃行为很有用。