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

教程

属性

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

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

属性说明

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 🔗

定义如何应用 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 🔗

定义设置物体质心的方式。可能的取值见 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 🔗

该物体的冻结模式。可以设置该物体在启用 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 获取计算出的惯量。

@onready var ball = $Ball

func get_ball_inertia():
    return 1.0 / PhysicsServer2D.body_get_direct_state(ball.get_rid()).inverse_inertia