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.

RigidBody2D

继承: PhysicsBody2D < CollisionObject2D < Node2D < CanvasItem < Node < Object

派生: PhysicalBone2D

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

描述

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

可以使用 lock_rotationfreezefreeze_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) 🔗

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

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


body_exited(body: Node) 🔗

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

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


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

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

body_ridPhysicsServer2D 使用的其他 PhysicsBody2DTileSetCollisionObject2DRID

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

body_shape_indexPhysicsServer2D 使用的其他 PhysicsBody2DTileMapShape2D 的索引。该 CollisionShape2D 节点可以使用 body.shape_owner_get_owner(body.shape_find_owner(body_shape_index)) 获取。

local_shape_indexPhysicsServer2D 使用的该 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 与另一个 PhysicsBody2DTileMapShape2D 之间的碰撞结束时发出。需要将 contact_monitor 设置为 true,并将 max_contacts_reported 设置得足够高以检测所有碰撞。如果 TileSet 具有 Collision Shape2D,则 TileMap 会被检测到。

body_ridPhysicsServer2D 使用的其他 PhysicsBody2DTileSetCollisionObject2DRID

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

body_shape_indexPhysicsServer2D 使用的其他 PhysicsBody2DTileMapShape2D 的索引。该 CollisionShape2D 节点可以使用 body.shape_owner_get_owner(body.shape_find_owner(body_shape_index)) 获取。

local_shape_indexPhysicsServer2D 使用的该 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_forceadd_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()

If true, the standard force integration (like gravity or damping) will be disabled for this body. Other than collision response, the body will only move as determined by the _integrate_forces method, if that virtual method is overridden.

Setting this property will call the method PhysicsServer2D.body_set_omit_force_integration internally.


bool freeze = false 🔗

  • void set_freeze_enabled(value: bool)

  • bool is_freeze_enabled()

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

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

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


FreezeMode freeze_mode = 0 🔗

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

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


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

float linear_damp = 0.0 🔗

  • void set_linear_damp(value: fl