Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

RigidBody2D

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

派生: PhysicalBone2D

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

描述

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

可以使用 lock_rotationfreeze、和 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 ( PhysicsDirectBodyState2D state ) virtual

void

add_constant_central_force ( Vector2 force )

void

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

void

add_constant_torque ( float torque )

void

apply_central_force ( Vector2 force )

void

apply_central_impulse ( Vector2 impulse=Vector2(0, 0) )

void

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

void

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

void

apply_torque ( float torque )

void

apply_torque_impulse ( float torque )

Node2D[]

get_colliding_bodies ( ) const

int

get_contact_count ( ) const

void

set_axis_velocity ( Vector2 axis_velocity )


信号

body_entered ( Node body )

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

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


body_exited ( Node body )

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

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


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

当该 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 ( RID body_rid, Node body, int body_shape_index, int local_shape_index )

当该 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 ( float value )

  • 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 ( DampMode value )

  • DampMode get_angular_damp_mode ( )

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


float angular_velocity = 0.0

  • void set_angular_velocity ( float value )

  • float get_angular_velocity ( )

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


bool can_sleep = true

  • void set_can_sleep ( bool value )

  • bool is_able_to_sleep ( )

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


Vector2 center_of_mass = Vector2(0, 0)

  • void set_center_of_mass ( Vector2 value )

  • 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 ( Vector2 value )

  • Vector2 get_constant_force ( )

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

add_constant_forceadd_constant_central_force


float constant_torque = 0.0

  • void set_constant_torque ( float value )

  • float get_constant_torque ( )

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

add_constant_torque


bool contact_monitor = false

  • void set_contact_monitor ( bool value )

  • bool is_contact_monitor_enabled ( )

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

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


CCDMode continuous_cd = 0

  • void set_continuous_collision_detection_mode ( CCDMode value )

  • CCDMode get_continuous_collision_detection_mode ( )

连续碰撞检测模式。

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


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,以设置冻结时,物体的行为。

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


FreezeMode freeze_mode = 0

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

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


float gravity_scale = 1.0

  • void set_gravity_scale ( float value )

  • float get_gravity_scale ( )

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


float inertia = 0.0

  • void set_inertia ( float value )

  • 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 ( float value )

  • 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 ( DampMode value )

  • DampMode get_linear_damp_mode ( )

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


Vector2 linear_velocity = Vector2(0, 0)

  • void set_linear_velocity ( Vector2 value )

  • Vector2 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 ( PhysicsDirectBodyState2D state ) virtual

允许你读取并安全地修改对象的模拟状态。如果你需要直接改变物体的 position 或其他物理属性,请使用它代替 Node._physics_process。默认情况下,它是在通常的物理行为之外工作的,但是 custom_integrator 允许你禁用默认行为并为一个物体编写自定义的合力。


void add_constant_central_force ( Vector2 force )

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

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


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

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

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


void add_constant_torque ( float torque )

添加一个恒定的旋转力矩,而不影响位置,该力会随着时间的推移不断施加,直到使用 constant_torque = 0 清除。


void apply_central_force ( Vector2 force )

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

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


void apply_central_impulse ( Vector2 impulse=Vector2(0, 0) )

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

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

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


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

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

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


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

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

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

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


void apply_torque ( float torque )

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

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


void apply_torque_impulse ( float torque )

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

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

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


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 ( Vector2 axis_velocity )

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