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 implements full 3D 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 3D transform or linear_velocity of a RigidBody3D very often may lead to some unpredictable behaviors. This also happens when a RigidBody3D is the descendant of a constantly moving node, like another RigidBody3D, as that will cause its global transform to be set whenever its ancestor moves.
教學
屬性
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
方法
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 |
|
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
在這種模式下，物體的阻尼值將替換掉區域中設定的任何值或預設值。
屬性說明
Damps the body's rotation. By default, the body will use the ProjectSettings.physics/3d/default_angular_damp project setting or any value override set by an Area3D 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/3d/default_angular_damp for more details about damping.
DampMode angular_damp_mode = 0 🔗
Defines how angular_damp is applied.
Vector3 angular_velocity = Vector3(0, 0, 0) 🔗
該 RigidBody3D 的旋轉速度，單位為弧度每秒。
如果為 true，則物體未運動時可以進入睡眠模式。見 sleeping 。
Vector3 center_of_mass = Vector3(0, 0, 0) 🔗
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.
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 🔗
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 PhysicsServer3D.body_set_omit_force_integration() internally.
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 StaticBody3D or AnimatableBody3D 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 StaticBody3D or AnimatableBody3D instead.
This is multiplied by ProjectSettings.physics/3d/default_gravity to produce this body's gravity. For example, a value of 1.0 will apply normal gravity, 2.0 will apply double the gravity, and 0.5 will apply half the gravity to this body.
Vector3 inertia = Vector3(0, 0, 0) 🔗
The body's moment of inertia. This is like mass, but for rotation: it determines how much torque it takes to rotate the body on each axis. The moment of inertia is usually computed automatically from the mass and the shapes, but this property allows you to set a custom value.
If set to Vector3.ZERO, inertia is automatically computed (default value).
Note: This value does not change when inertia is automatically computed. Use PhysicsServer3D to get the computed inertia.
@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();
}
Damps the body's movement. By default, the body will use the ProjectSettings.physics/3d/default_linear_damp project setting or any value override set by an Area3D 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/3d/default_linear_damp for more details about damping.
DampMode linear_damp_mode = 0 🔗
Defines how linear_damp is applied.
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 🔗
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: 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 上的扭矩產生的角加速度。
void set_axis_velocity(axis_velocity: Vector3) 🔗
設定軸速度。給定向量軸上的速度將被設定為給定向量長度。這對跳躍行為很有用。