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 implements full 2D physics. It cannot be controlled directly, instead, you must apply forces to it (gravity, impulses, etc.), and the physics simulation will calculate the resulting movement, rotation, react to collisions, and affect other physics bodies in its path.

The body's behavior can be adjusted via lock_rotation, freeze, and freeze_mode. By changing various properties of the object, such as mass, you can control how the physics simulation acts on it.

A rigid body will always maintain its shape and size, even when forces are applied to it. It is useful for objects that can be interacted with in an environment, such as a tree that can be knocked over or a stack of crates that can be pushed around.

If you need to directly affect the body, prefer _integrate_forces() as it allows you to directly access the physics state.

If you need to override the default physics behavior, you can write a custom force integration function. See custom_integrator.

Note: Changing the 2D transform or linear_velocity of a RigidBody2D very often may lead to some unpredictable behaviors. This also happens when a RigidBody2D is the descendant of a constantly moving node, like another RigidBody2D, as that will cause its global transform to be set whenever its ancestor moves.

教學

屬性

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

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 🔗

void set_angular_damp_mode(value: DampMode)
DampMode get_angular_damp_mode()

Defines how angular_damp is applied.

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

The body's custom center of mass, relative to the body's origin position, when center_of_mass_mode is set to CENTER_OF_MASS_MODE_CUSTOM. This is the balanced point of the body, where applied forces only cause linear acceleration. Applying forces outside of the center of mass causes angular acceleration.

When center_of_mass_mode is set to CENTER_OF_MASS_MODE_AUTO (default value), the center of mass is automatically determined, but this does not update the value of center_of_mass.

CenterOfMassMode center_of_mass_mode = 0 🔗

void set_center_of_mass_mode(value: CenterOfMassMode)
CenterOfMassMode get_center_of_mass_mode()

Defines the way the body's center of mass is set.

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

Continuous collision detection mode.

Continuous collision detection tries to predict where a moving body will collide instead of moving it and correcting its movement after collision. Continuous collision detection is slower, but more precise and misses fewer collisions with small, fast-moving objects. Raycasting and shapecasting methods are available.

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

If true, the body is frozen. Gravity and forces are not applied anymore.

See freeze_mode to set the body's behavior when frozen.

Note: For a body that is always frozen, use StaticBody2D or AnimatableBody2D instead.

FreezeMode freeze_mode = 0 🔗

void set_freeze_mode(value: FreezeMode)
FreezeMode get_freeze_mode()

The body's freeze mode. Determines the body's behavior when freeze is true.

Note: For a body that is always frozen, use StaticBody2D or AnimatableBody2D instead.

float gravity_scale = 1.0 🔗

void set_gravity_scale(value: float)
float get_gravity_scale()

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.

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

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

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 🔗

void set_linear_damp_mode(value: DampMode)
DampMode get_linear_damp_mode()

Defines how linear_damp is applied.

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 🔗

Called during physics processing, allowing you to read and safely modify the simulation state for the object. By default, it is called before the standard force integration, but the custom_integrator property allows you to disable the standard force integration and do fully custom force integration for a body.

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) 🔗

設定物體在給定軸上的速度。給定向量軸上的速度將設定為給定向量長度。這對於跳躍行為很有用。