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.

RigidBody3D

繼承: PhysicsBody3D < CollisionObject3D < Node3D < Node < Object

被繼承: VehicleBody3D

由物理模擬進行移動的 3D 物理體。

說明

RigidBody3D 實作了完整的 3D 物理。這個物理體無法直接控制,必須對其施加力(重力、衝量等),物理仿真將計算由此產生的移動、旋轉、對碰撞的反應以及對沿路其他物理體的影響等。

可以使用 lock_rotation、freeze 和 freeze_mode 調整該物理體的行為。通過修改該物件的 mass 等屬性,你可以控制物理仿真對其的影響。

即使施加了力,剛體也會始終維持自身的形狀和大小。適用於環境中可互動的物件,例如能夠推倒的樹木或者能夠被推動的一堆箱子。

如果你需要直接影響物體,請優先使用 _integrate_forces(),能夠直接存取物理狀態。

如果你需要覆蓋預設的物理行為,你可以編寫自訂的力整合函式。見 custom_integrator。

注意:頻繁修改 RigidBody3D 的 3D 變換或 linear_velocity 可能導致無法預期的行為。這也會發生在 RigidBody3D 是不斷移動的節點的子孫節點時,比如另一個 RigidBody3D,因為祖先移動時會導致設定全域變換。

教學

屬性

float

angular_damp

0.0

DampMode

angular_damp_mode

0

Vector3

angular_velocity

Vector3(0, 0, 0)

bool

can_sleep

true

Vector3

center_of_mass

Vector3(0, 0, 0)

CenterOfMassMode

center_of_mass_mode

0

Vector3

constant_force

Vector3(0, 0, 0)

Vector3

constant_torque

Vector3(0, 0, 0)

bool

contact_monitor

false

bool

continuous_cd

false

bool

custom_integrator

false

bool

freeze

false

FreezeMode

freeze_mode

0

float

gravity_scale

1.0

Vector3

inertia

Vector3(0, 0, 0)

float

linear_damp

0.0

DampMode

linear_damp_mode

0

Vector3

linear_velocity

Vector3(0, 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: PhysicsDirectBodyState3D) virtual

void

add_constant_central_force(force: Vector3)

void

add_constant_force(force: Vector3, position: Vector3 = Vector3(0, 0, 0))

void

add_constant_torque(torque: Vector3)

void

apply_central_force(force: Vector3)

void

apply_central_impulse(impulse: Vector3)

void

apply_force(force: Vector3, position: Vector3 = Vector3(0, 0, 0))

void

apply_impulse(impulse: Vector3, position: Vector3 = Vector3(0, 0, 0))

void

apply_torque(torque: Vector3)

void

apply_torque_impulse(impulse: Vector3)

Array[Node3D]

get_colliding_bodies() const

int

get_contact_count() const

Basis

get_inverse_inertia_tensor() const

Vector3

get_velocity_at_local_position(local_position: Vector3) const

Vector3

get_velocity_at_position(global_point: Vector3) const

void

set_axis_velocity(axis_velocity: Vector3)


訊號

body_entered(body: Node) 🔗

當與另一個 PhysicsBody3D 或 GridMap 發生碰撞時發出。需要將 contact_monitor 設定為 true,並將 max_contacts_reported 設定得足夠高以偵測所有碰撞。如果 MeshLibrary 具有碰撞 Shape3D,則 GridMap 會被偵測。

body 是其他 PhysicsBody3D 或 GridMap 的 Node,如果該節點存在於樹中。


body_exited(body: Node) 🔗

當與另一個 PhysicsBody3D 或 GridMap 的碰撞結束時發出。需要將 contact_monitor 設定為 true,並將 max_contacts_reported 設定得足夠高以偵測所有碰撞。如果 MeshLibrary 具有碰撞 Shape3D,則 GridMap 會被偵測。

body 是其他 PhysicsBody3D 或 GridMap 的 Node,如果該節點存在於樹中。


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

當該 RigidBody3D 的一個 Shape3D 與另一個 PhysicsBody3D 或 GridMap 的 Shape3D 碰撞時發出。需要將 contact_monitor 設定為 true,並將 max_contacts_reported 設定得足夠高以偵測所有碰撞。如果 MeshLibrary 具有 Collision Shape3D,則 GridMap 會被偵測到。

body_rid 由 PhysicsServer3D 使用的其他 PhysicsBody3D 或 MeshLibrary 的 CollisionObject3D 的 RID。

body 其他 PhysicsBody3D 或 GridMap 的 Node,如果該節點存在於樹中。

body_shape_index 由 PhysicsServer3D 使用的其他 PhysicsBody3D 或 GridMap 的 Shape3D 的索引。該 CollisionShape3D 節點可以使用 body.shape_owner_get_owner(body.shape_find_owner(body_shape_index)) 取得。

local_shape_index 由 PhysicsServer3D 使用的該 RigidBody3D 的 Shape3D 的索引。該 CollisionShape3D 節點可以使用 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) 🔗

當該 RigidBody3D 的一個 Shape3D 與另一個 PhysicsBody3D 或 GridMap 的 Shape3D 之間的碰撞結束時發出。需要將 contact_monitor 設定為 true,並將 max_contacts_reported 設定得足夠高以偵測所有碰撞。如果 MeshLibrary 具有碰撞 Shape3D,則 GridMap 將被偵測。

body_rid 由 PhysicsServer3D 使用的其他 PhysicsBody3D 或 MeshLibrary 的 CollisionObject3D 的 RID。如果網格具有 Shape3D,則 GridMap 將被偵測。

body 其他 PhysicsBody3D 或 GridMap 的 Node,如果該節點存在於樹中。

body_shape_index 由 PhysicsServer3D 使用的其他 PhysicsBody3D 或GridMap 的Shape3D 的索引。該 CollisionShape3D 節點可以使用 body.shape_owner_get_owner(body.shape_find_owner(body_shape_index)) 取得。

local_shape_index 由 PhysicsServer3D 使用的該 RigidBody3D 的 Shape3D 的索引。該 CollisionShape3D 節點可以使用 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

在這種模式下,物體的阻尼值將替換掉區域中設定的任何值或預設值。


屬性說明

float angular_damp = 0.0 🔗

  • void set_angular_damp(value: float)

  • float get_angular_damp()

阻礙物體的旋轉。預設情況下,物體將使用專案設定 ProjectSettings.physics/3d/default_angular_damp,或物體所在的 Area3D 中設定的任何覆蓋值。取決於 angular_damp_mode,可以設定 angular_damp 以增加或替換物體的阻尼值。

有關阻尼的更多詳細資訊,請參閱 ProjectSettings.physics/3d/default_angular_damp。


DampMode angular_damp_mode = 0 🔗

定義如何應用 angular_damp。


Vector3 angular_velocity = Vector3(0, 0, 0) 🔗

  • void set_angular_velocity(value: Vector3)

  • Vector3 get_angular_velocity()

該 RigidBody3D 的旋轉速度,單位為弧度每秒。


bool can_sleep = true 🔗

  • void set_can_sleep(value: bool)

  • bool is_able_to_sleep()

若爲 true,則形體未運動時進入睡眠模式。參看 sleeping。


Vector3 center_of_mass = Vector3(0, 0, 0) 🔗

  • void set_center_of_mass(value: Vector3)

  • Vector3 get_center_of_mass()

當 center_of_mass_mode 設定為 CENTER_OF_MASS_MODE_CUSTOM 時,物體的自訂質心相對於物體原點位置的位置。這是物體的平衡點,只有施加在質心內的力才會引起線性加速度。施加在質心之外的力會引起角加速度。

當 center_of_mass_mode 設定為 CENTER_OF_MASS_MODE_AUTO(預設值)時,會自動確定質心,但這不會更新 center_of_mass 的值。


CenterOfMassMode center_of_mass_mode = 0 🔗

定義設定物體質心的方式。


Vector3 constant_force = Vector3(0, 0, 0) 🔗

  • void set_constant_force(value: Vector3)

  • Vector3 get_constant_force()

在每個物理更新期間施加到物體的總恒定位置的力。

見 add_constant_force() 和 add_constant_central_force() 。


Vector3 constant_torque = Vector3(0, 0, 0) 🔗

  • void set_constant_torque(value: Vector3)

  • Vector3 get_constant_torque()

在每個物理更新期間施加的物體的總恒定旋轉力。

見 add_constant_torque() 。


bool contact_monitor = false 🔗

  • void set_contact_monitor(value: bool)

  • bool is_contact_monitor_enabled()

如果為 true,則該 RigidBody3D 將在與其他物體碰撞時發出訊號。

注意:預設情況下,報告的最大接觸數被設定為 0,表示不會記錄任何內容,見 max_contacts_reported。


bool continuous_cd = false 🔗

  • void set_use_continuous_collision_detection(value: bool)

  • bool is_using_continuous_collision_detection()

如果為 true,則使用連續碰撞偵測。

連續碰撞偵測嘗試預測一個移動的物體會在哪裡碰撞,而不是移動它並在它發生碰撞時糾正它的運動。連續碰撞偵測更精確,並且錯過了較小的、快速移動的物體的撞擊。不使用連續碰撞偵測的計算速度更快,但可能會錯過小的、快速移動的物體。


bool custom_integrator = false 🔗

  • void set_use_custom_integrator(value: bool)

  • bool is_using_custom_integrator()

如果為 true,則該物體的標準力積分(如重力或阻尼)將被停用。除了碰撞響應之外,如果覆蓋了 _integrate_forces() 方法,則物體將僅按照該方法確定的方式移動。

設定該屬性將在內部呼叫方法 PhysicsServer3D.body_set_omit_force_integration()。


bool freeze = false 🔗

  • void set_freeze_enabled(value: bool)

  • bool is_freeze_enabled()

如果為 true,則該物體被凍結。不再施加重力和力。

要設定凍結時物體的行為,見 freeze_mode。

注意:對於始終凍結的物體,請改用 StaticBody3D 或 AnimatableBody3D。


FreezeMode freeze_mode = 0 🔗

物體的凍結模式。freeze 為 true 時決定物體的行為。

注意:始終凍結的物體請改用 StaticBody3D 或 AnimatableBody3D。


float gravity_scale = 1.0 🔗

  • void set_gravity_scale(value: float)

  • float get_gravity_scale()

與 ProjectSettings.physics/3d/default_gravity 相乘,得到該物體的重力。例如取值為 1.0 就是正常重力,2.0 就是雙倍重力,0.5 會讓套用至這個物件的重力減半。


Vector3 inertia = Vector3(0, 0, 0) 🔗

該物體的轉動慣量。與質量類似,但用於旋轉:用於確定各個軸上需要施加多少力矩才能讓該物體旋轉。通常會自動根據質量和形狀計算轉動慣量,但這個屬效能夠讓你設定自訂的值。

設定為 Vector3.ZERO 時,會自動計算慣量(預設值)。

注意:自動計算出慣量後,這個值不會改變。請使用 PhysicsServer3D 取得計算出的慣量。

@onready var ball = $Ball

func get_ball_inertia():
    return PhysicsServer3D.body_get_direct_state(ball.get_rid()).inverse_inertia.inverse()

float linear_damp = 0.0 🔗

  • void set_linear_damp(value: float)

  • float get_linear_damp()

抑制物體的運動。預設情況下,物體將使用 ProjectSettings.physics/3d/default_linear_damp 設定或物體所在的 Area3D 的覆蓋值。取決於 linear_damp_mode,你可以將 linear_damp 設定為新增或替換物體的阻尼值。

有關阻尼的更多詳細資訊,請參閱 ProjectSettings.physics/3d/default_linear_damp。


DampMode linear_damp_mode = 0 🔗

定義如何應用 linear_damp。


Vector3 linear_velocity = Vector3(0, 0, 0) 🔗

  • void set_linear_velocity(value: Vector3)

  • Vector3 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 🔗

此實體的質量。


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 🔗

覆寫形體的物理材質。

若爲此屬性指定了某種材質,則會使用該材質代替其他物理材質(比如繼承而來的材質)。


bool sleeping = false 🔗

  • void set_sleeping(value: bool)

  • bool is_sleeping()

如果為 true ,該剛體將不會移動,也不會計算受力,直到被另一個物體喚醒,例如通過碰撞或使用 apply_impulse() 或 apply_force() 方法。


方法說明

void _integrate_forces(state: PhysicsDirectBodyState3D) virtual 🔗

在物理處理過程中被呼叫,允許你讀取並安全地修改物件的模擬狀態。預設情況下,它在標準力積分之前呼叫,但 custom_integrator 屬性允許你停用標準力積分並對物體進行完全自訂的力積分。


void add_constant_central_force(force: Vector3) 🔗

在不影響旋轉的情況下,新增一個恒定的定向力,該力會隨著時間的推移而持續施加,直到使用 constant_force = Vector3(0, 0, 0) 清除。

這相當於在物體的質心處,使用 add_constant_force()。


void add_constant_force(force: Vector3, position: Vector3 = Vector3(0, 0, 0)) 🔗

向實體新增一個恒定的定位力,持續施加,直到用 constant_force = Vector3(0, 0, 0) 清除。

position 是在全域座標中距實體原點的偏移量。


void add_constant_torque(torque: Vector3) 🔗

在不影響位置的情況下,新增一個恒定的旋轉力,該力會隨著時間的推移而持續施加,直到使用 constant_torque = Vector3(0, 0, 0) 清除。


void apply_central_force(force: Vector3) 🔗

施加一個不影響旋轉的定向力。該力是時間相關的,意味著每次物理更新都會施加。

這相當於在物體的質心處,使用 apply_force()。


void apply_central_impulse(impulse: Vector3) 🔗

施加一個不影響的旋轉定向脈衝。

脈衝與時間無關!每影格套用一個脈衝,會產生一個依賴於畫面播放速率的力。出於這個原因,它應該只在模擬一次性影響時使用(否則使用 “_force”函式)。

這相當於在物體的質心處,使用 apply_impulse()。


void apply_force(force: Vector3, position: Vector3 = Vector3(0, 0, 0)) 🔗

對實體施加一個定位力。力是時間相關的,意味著每次物理更新都會被施加。

position 是在全域座標中距實體原點的偏移量。


void apply_impulse(impulse: Vector3, position: Vector3 = Vector3(0, 0, 0)) 🔗

向實體施加一個定位脈衝。

脈衝是時間無關的!每影格施加一個脈衝將產生一個依賴於畫面播放速率的力。出於這個原因,它應該只在模擬一次性影響時使用(否則使用“_force”函式)。

position 是在全域座標中距實體原點的偏移量。


void apply_torque(torque: Vector3) 🔗

施加旋轉力但不影響位置。力是與時間相關的,應該每次物理更新時都要進行施加。

注意:有 inertia 才能正常工作。要讓 inertia 存在,必須有一個 CollisionShape3D 作為該節點的子節點,或者你也可以手動設定 inertia。


void apply_torque_impulse(impulse: Vector3) 🔗

在不影響位置的情況下,向實體施加一個旋轉脈衝。

脈衝是時間無關的!每影格施加一個脈衝將產生一個依賴於畫面播放速率的力。出於這個原因,它應該只在模擬一次性影響時使用(否則使用“_force”函式)。

注意:需要 inertia 才能發揮作用。要具有 inertia,活動的 CollisionShape3D 必須是該節點的一個子節點,或者可以手動設定 inertia。


Array[Node3D] get_colliding_bodies() const 🔗

返回與此物體發生碰撞的物體的列表。需要將 contact_monitor 設定為 true,並將 max_contacts_reported 設定足夠高以偵測所有碰撞。

注意:此測試的結果不會立即在移動物體後得出。為了提高效能,碰撞列表每影格更新一次,且在物理步驟之前進行。可考慮改用訊號來代替。


int get_contact_count() const 🔗

返回此物體與其他物體的接觸數。預設情況下,除非配置監視接觸的物體(見 contact_monitor),否則返回 0。

注意:要取得正在碰撞的物體,請使用 get_colliding_bodies()。


Basis get_inverse_inertia_tensor() const 🔗

返回逆慣性張量基礎。這用於計算施加到 RigidBody3D 上的扭矩產生的角加速度。


Vector3 get_velocity_at_local_position(local_position: Vector3) const 🔗

Returns the body's velocity at the given relative position.

local_position is the offset from the body origin in global coordinates.

See also get_velocity_at_position().


Vector3 get_velocity_at_position(global_point: Vector3) const 🔗

Returns the body's velocity at the given global position.

This is equivalent to get_velocity_at_local_position(global_point - global_position).

See also get_velocity_at_local_position().


void set_axis_velocity(axis_velocity: Vector3) 🔗

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