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...
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,因為祖先移動時會導致設定全域變換。
教學
屬性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法
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) |
get_colliding_bodies() const |
|
get_contact_count() const |
|
get_inverse_inertia_tensor() const |
|
get_velocity_at_local_position(local_position: Vector3) const |
|
get_velocity_at_position(global_point: Vector3) const |
|
void |
set_axis_velocity(axis_velocity: Vector3) |
訊號
當與另一個 PhysicsBody3D 或 GridMap 發生碰撞時發出。需要將 contact_monitor 設定為 true,並將 max_contacts_reported 設定得足夠高以偵測所有碰撞。如果 MeshLibrary 具有碰撞 Shape3D,則 GridMap 會被偵測。
body 是其他 PhysicsBody3D 或 GridMap 的 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
在這種模式下,物體的阻尼值將替換掉區域中設定的任何值或預設值。
屬性說明
阻礙物體的旋轉。預設情況下,物體將使用專案設定 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) 🔗
該 RigidBody3D 的旋轉速度,單位為弧度每秒。
若爲 true,則形體未運動時進入睡眠模式。參看 sleeping。
Vector3 center_of_mass = Vector3(0, 0, 0) 🔗
當 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 🔗
void set_center_of_mass_mode(value: CenterOfMassMode)
CenterOfMassMode get_center_of_mass_mode()
定義設定物體質心的方式。
Vector3 constant_force = Vector3(0, 0, 0) 🔗
在每個物理更新期間施加到物體的總恒定位置的力。
見 add_constant_force() 和 add_constant_central_force() 。
Vector3 constant_torque = Vector3(0, 0, 0) 🔗
在每個物理更新期間施加的物體的總恒定旋轉力。
bool contact_monitor = false 🔗
如果為 true,則該 RigidBody3D 將在與其他物體碰撞時發出訊號。
注意:預設情況下,報告的最大接觸數被設定為 0,表示不會記錄任何內容,見 max_contacts_reported。
void set_use_continuous_collision_detection(value: bool)
bool is_using_continuous_collision_detection()
如果為 true,則使用連續碰撞偵測。
連續碰撞偵測嘗試預測一個移動的物體會在哪裡碰撞,而不是移動它並在它發生碰撞時糾正它的運動。連續碰撞偵測更精確,並且錯過了較小的、快速移動的物體的撞擊。不使用連續碰撞偵測的計算速度更快,但可能會錯過小的、快速移動的物體。
bool custom_integrator = false 🔗
如果為 true,則該物體的標準力積分(如重力或阻尼)將被停用。除了碰撞響應之外,如果覆蓋了 _integrate_forces() 方法,則物體將僅按照該方法確定的方式移動。
設定該屬性將在內部呼叫方法 PhysicsServer3D.body_set_omit_force_integration()。
如果為 true,則該物體被凍結。不再施加重力和力。
要設定凍結時物體的行為,見 freeze_mode。
注意:對於始終凍結的物體,請改用 StaticBody3D 或 AnimatableBody3D。
FreezeMode freeze_mode = 0 🔗
void set_freeze_mode(value: FreezeMode)
FreezeMode get_freeze_mode()
物體的凍結模式。freeze 為 true 時決定物體的行為。
注意:始終凍結的物體請改用 StaticBody3D 或 AnimatableBody3D。
與 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()
private RigidBody3D _ball;
public override void _Ready()
{
_ball = GetNode<RigidBody3D>("Ball");
}
private Vector3 GetBallInertia()
{
return PhysicsServer3D.BodyGetDirectState(_ball.GetRid()).InverseInertia.Inverse();
}
抑制物體的運動。預設情況下,物體將使用 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) 🔗
物體的線速度,單位為單位每秒。可以偶爾使用,但是不要每一影格都設定它,因為物理可能在另一個執行緒中運作,並且以不同的間隔。使用 _integrate_forces() 作為你的程序迴圈,以精確控制物體狀態。
如果為 true,則該物體不能旋轉。重力和力只施加線性運動。
此實體的質量。
int max_contacts_reported = 0 🔗
將記錄的最大接觸點數。需要一個大於 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()
覆寫形體的物理材質。
若爲此屬性指定了某種材質,則會使用該材質代替其他物理材質(比如繼承而來的材質)。
如果為 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) 🔗
設定軸速度。給定向量軸上的速度將被設定為給定向量長度。這對跳躍行為很有用。