RigidBody2D

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，能够直接访问物理状态。

教程

属性

float	angular_damp	`0.0`
DampMode	angular_damp_mode	`0`
float	angular_velocity	`0.0`
bool	can_sleep	`true`
Vector2	center_of_mass	`Vector2(0, 0)`
CenterOfMassMode	center_of_mass_mode	`0`
Vector2	constant_force	`Vector2(0, 0)`
float	constant_torque	`0.0`
bool	contact_monitor	`false`
CCDMode	continuous_cd	`0`
bool	custom_integrator	`false`
bool	freeze	`false`
FreezeMode	freeze_mode	`0`
float	gravity_scale	`1.0`
float	inertia	`0.0`
float	linear_damp	`0.0`
DampMode	linear_damp_mode	`0`
Vector2	linear_velocity	`Vector2(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(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)
Array[Node2D]	get_colliding_bodies() const
int	get_contact_count() const
void	set_axis_velocity(axis_velocity: Vector2)

信号

body_entered(body: Node) 🔗

当与另一个 PhysicsBody2D 或 TileMap 发生碰撞时发出。需要将 contact_monitor 设置为 true，并将 max_contacts_reported 设置得足够高以检测所有碰撞。如果 TileSet 具有碰撞 Shape2D，则 TileMap 将被检测。

body 是其他 PhysicsBody2D 或 TileMap 的 Node，如果该节点存在于树中。

body_exited(body: 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，如果该节点存在于树中。

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 方法，也是最精确的。

属性说明

float angular_damp = 0.0 🔗

void set_angular_damp(value: float)
float get_angular_damp()

减缓物体的旋转。默认情况下，物体将使用 项目> 项目设置> 物理> 2D 中的默认角阻尼，或由 Area2D 设置的任何值覆盖。根据 angular_damp_mode，你可以设置 angular_damp_mode 以添加到或替换物体的阻尼值。

有关阻尼的更多详细信息，请参见 ProjectSettings.physics/2d/default_angular_damp 。

DampMode angular_damp_mode = 0 🔗

void set_angular_damp_mode(value: DampMode)
DampMode get_angular_damp_mode()

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

float angular_velocity = 0.0 🔗

void set_angular_velocity(value: float)
float get_angular_velocity()

物体的旋转速度，单位为弧度每秒。

bool can_sleep = true 🔗

void set_can_sleep(value: bool)
bool is_able_to_sleep()

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

Vector2 center_of_mass = Vector2(0, 0) 🔗

void set_center_of_mass(value: Vector2)
Vector2 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 🔗

void set_center_of_mass_mode(value: CenterOfMassMode)
CenterOfMassMode get_center_of_mass_mode()

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

Vector2 constant_force = Vector2(0, 0) 🔗

void set_constant_force(value: Vector2)
Vector2 get_constant_force()

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

见 add_constant_force 和 add_constant_central_force 。

float constant_torque = 0.0 🔗

void set_constant_torque(value: float)
float get_constant_torque()

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

见 add_constant_torque 。

bool contact_monitor = false 🔗

void set_contact_monitor(value: bool)
bool is_contact_monitor_enabled()

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

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

CCDMode continuous_cd = 0 🔗

void set_continuous_collision_detection_mode(value: CCDMode)
CCDMode get_continuous_collision_detection_mode()

连续碰撞检测模式。

连续碰撞检测尝试预测一个移动的物体会在哪里碰撞，而不是移动它并在碰撞后纠正它的运动。连续碰撞检测速度较慢，但更精确，并且与快速移动的小物体发生碰撞时遗漏更少。可以使用光线投射和形状投射方法。有关详细信息，请参阅 CCDMode。

bool custom_integrator = false 🔗

void set_use_custom_integrator(value: bool)
bool is_using_custom_integrator()

如果 true，则该物体的标准力积分（如重力或阻尼）将被禁用。除了碰撞响应之外，如果覆盖了 _integrate_forces 方法，则物体将仅按照该方法确定的方式移动。

设置该属性将在内部调用方法 PhysicsServer2D.body_set_omit_force_integration。

bool freeze = false 🔗

void set_freeze_enabled(value: bool)
bool is_freeze_enabled()

如果位 true，则物体被冻结。不再施加重力和力。

请参阅 freeze_mode，以设置冻结时，物体的行为。

对于始终冻结的物体，请改用 StaticBody2D 或 AnimatableBody2D。

FreezeMode freeze_mode = 0 🔗

void set_freeze_mode(value: FreezeMode)
FreezeMode get_freeze_mode()

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

对于始终冻结的物体，请改用 StaticBody3D 或 AnimatableBody3D。

float gravity_scale = 1.0 🔗

void set_gravity_scale(value: float)
float get_gravity_scale()

乘以施加在物体上的重力。物体的重力是由项目 > 项目设置 > 物理 > 2D 中的默认重力值和/或任何由 Area2D 应用的额外重力向量计算出来的。

float inertia = 0.0 🔗

void set_inertia(value: float)
float get_inertia()

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

设置为 0 时，会自动计算惯量（默认值）。

注意：自动计算出惯量后，这个值不会改变。请使用 PhysicsServer2D 获取计算出的惯量。

GDScriptC#

@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;
}

float linear_damp = 0.0 🔗

void set_linear_damp(value: float)
float get_linear_damp()

阻碍物体的运动。默认情况下，物体将使用 项目 > 项目设置 > 物理 > 2D 中的 默认线性阻尼或物体所在的 Area2D 设置的任何值覆盖。取决于 linear_damp_mode，你可以将 linear_damp 设置为添加或替换物体的阻尼值。

有关阻尼的更多详细信息，请参见 ProjectSettings.physics/2d/default_linear_damp。

DampMode linear_damp_mode = 0 🔗

void set_linear_damp_mode(value: DampMode)
DampMode get_linear_damp_mode()

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

Vector2 linear_velocity = Vector2(0, 0) 🔗

void set_linear_velocity(value: Vector2)
Vector2 get_linear_velocity()

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

bool lock_rotation = false 🔗

void set_lock_rotation_enabled(value: bool)
bool is_lock_rotation_enabled()

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

float mass = 1.0 🔗

void set_mass(value: float)
float get_mass()

实体的质量。

int max_contacts_reported = 0 🔗

void set_max_contacts_reported(value: int)
int get_max_contacts_reported()

将记录的最大接触点数。需要一个大于 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()

物体的物理材质。

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

bool sleeping = false 🔗

void set_sleeping(value: bool)
bool is_sleeping()

如果为 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) 🔗

设置物体在给定轴上的速度。给定矢量轴上的速度将设置为给定向量长度。这对于跳跃行为很有用。