MeshyPhysics

Inherits RefCounted.

Class index

The live physics controls of one MeshyMeshInstance3D.

Access this object through the mesh’s MeshyMeshInstance3D.physics property. Changes affect that mesh’s runtime state and preserve its authored settings resource. Values unsupported by the current physics mode are rejected with a warning.

Retaining this object does not keep its mesh alive. After the mesh is freed, reads return default values and writes have no effect.

Properties

angular_damp

angular_damp: float

setter: set_angular_damp; getter: get_angular_damp.

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.

angular_damp_mode

angular_damp_mode: int

setter: set_angular_damp_mode; getter: get_angular_damp_mode.

Defines how angular_damp is applied.

angular_damp_space_override

angular_damp_space_override: int

setter: set_angular_damp_space_override; getter: get_angular_damp_space_override.

Override mode for angular damping calculations within this area.

angular_velocity

angular_velocity: Vector3

setter: set_angular_velocity; getter: get_angular_velocity.

The RigidBody3D’s rotational velocity in radians per second.

axis_lock_angular_x

axis_lock_angular_x: bool

setter: set_axis_lock_angular_x; getter: get_axis_lock_angular_x.

Lock the body’s rotation in the X axis.

axis_lock_angular_y

axis_lock_angular_y: bool

setter: set_axis_lock_angular_y; getter: get_axis_lock_angular_y.

Lock the body’s rotation in the Y axis.

axis_lock_angular_z

axis_lock_angular_z: bool

setter: set_axis_lock_angular_z; getter: get_axis_lock_angular_z.

Lock the body’s rotation in the Z axis.

axis_lock_linear_x

axis_lock_linear_x: bool

setter: set_axis_lock_linear_x; getter: get_axis_lock_linear_x.

Lock the body’s linear movement in the X axis.

axis_lock_linear_y

axis_lock_linear_y: bool

setter: set_axis_lock_linear_y; getter: get_axis_lock_linear_y.

Lock the body’s linear movement in the Y axis.

axis_lock_linear_z

axis_lock_linear_z: bool

setter: set_axis_lock_linear_z; getter: get_axis_lock_linear_z.

Lock the body’s linear movement in the Z axis.

can_sleep

can_sleep: bool

setter: set_can_sleep; getter: get_can_sleep.

If true, the body can enter sleep mode when there is no movement. See sleeping.

center_of_mass

center_of_mass: Vector3

setter: set_center_of_mass; getter: 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 RigidBody3D.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 RigidBody3D.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.

center_of_mass_mode

center_of_mass_mode: int

setter: set_center_of_mass_mode; getter: get_center_of_mass_mode.

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

collision_layer

collision_layer: int

setter: set_collision_layer; getter: get_collision_layer.

The physics layers this CollisionObject3D is in. Collision objects can exist in one or more of 32 different layers. See also collision_mask.

Note: Object A can detect a contact with object B only if object B is in any of the layers that object A scans. See Collision layers and masks in the documentation for more information.

collision_mask

collision_mask: int

setter: set_collision_mask; getter: get_collision_mask.

The physics layers this CollisionObject3D scans. Collision objects can scan one or more of 32 different layers. See also collision_layer.

Note: Object A can detect a contact with object B only if object B is in any of the layers that object A scans. See Collision layers and masks in the documentation for more information.

collision_priority

collision_priority: float

setter: set_collision_priority; getter: get_collision_priority.

The priority used to solve colliding when occurring penetration. The higher the priority is, the lower the penetration into the object will be. This can for example be used to prevent the player from breaking through the boundaries of a level.

constant_angular_velocity

constant_angular_velocity: Vector3

setter: set_constant_angular_velocity; getter: get_constant_angular_velocity.

The body’s constant angular velocity. This does not rotate the body, but affects touching bodies, as if it were rotating.

constant_force

constant_force: Vector3

setter: set_constant_force; getter: get_constant_force.

The body’s total constant positional forces applied during each physics update.

See RigidBody3D.add_constant_force and RigidBody3D.add_constant_central_force.

constant_linear_velocity

constant_linear_velocity: Vector3

setter: set_constant_linear_velocity; getter: get_constant_linear_velocity.

The body’s constant linear velocity. This does not move the body, but affects touching bodies, as if it were moving.

constant_torque

constant_torque: Vector3

setter: set_constant_torque; getter: get_constant_torque.

The body’s total constant rotational forces applied during each physics update.

See RigidBody3D.add_constant_torque.

contact_monitor

contact_monitor: bool

setter: set_contact_monitor; getter: get_contact_monitor.

If true, the RigidBody3D will emit signals when it collides with another body.

Note: By default the maximum contacts reported is set to 0, meaning nothing will be recorded, see max_contacts_reported.

continuous_cd

continuous_cd: bool

setter: set_continuous_cd; getter: get_continuous_cd.

If true, continuous collision detection is used.

Continuous collision detection tries to predict where a moving body will collide, instead of moving it and correcting its movement if it collided. Continuous collision detection is more precise, and misses fewer impacts by small, fast-moving objects. Not using continuous collision detection is faster to compute, but can miss small, fast-moving objects.

custom_integrator

custom_integrator: bool

setter: set_custom_integrator; getter: get_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 RigidBody3D._integrate_forces method, if that virtual method is overridden.

Setting this property will call the method PhysicsServer3D.body_set_omit_force_integration internally.

debug_color

debug_color: Color

setter: set_debug_color; getter: get_debug_color.

The collision shape color that is displayed in the editor, or in the running project if Debug > Visible Collision Shapes is checked at the top of the editor.

Note: The default value is ProjectSettings.debug/shapes/collision/shape_color. The Color(0, 0, 0, 0) value documented here is a placeholder, and not the actual default debug color.

debug_fill

debug_fill: bool

setter: set_debug_fill; getter: get_debug_fill.

If true, when the shape is displayed, it will show a solid fill color in addition to its wireframe.

freeze

freeze: bool

setter: set_freeze; getter: get_freeze.

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.

freeze_mode

freeze_mode: int

setter: set_freeze_mode; getter: 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.

gravity

gravity: float

setter: set_gravity; getter: get_gravity.

The area’s gravity intensity (in meters per second squared). This value multiplies the gravity direction. This is useful to alter the force of gravity without altering its direction.

gravity_direction

gravity_direction: Vector3

setter: set_gravity_direction; getter: get_gravity_direction.

The area’s gravity vector (not normalized).

gravity_point

gravity_point: bool

setter: set_gravity_point; getter: get_gravity_point.

If true, gravity is calculated from a point (set via gravity_point_center). See also gravity_space_override.

gravity_point_center

gravity_point_center: Vector3

setter: set_gravity_point_center; getter: get_gravity_point_center.

If gravity is a point (see gravity_point), this will be the point of attraction.

gravity_point_unit_distance

gravity_point_unit_distance: float

setter: set_gravity_point_unit_distance; getter: get_gravity_point_unit_distance.

The distance at which the gravity strength is equal to gravity. For example, on a planet 100 meters in radius with a surface gravity of 4.0 m/s², set the gravity to 4.0 and the unit distance to 100.0. The gravity will have falloff according to the inverse square law, so in the example, at 200 meters from the center the gravity will be 1.0 m/s² (twice the distance, 1/4th the gravity), at 50 meters it will be 16.0 m/s² (half the distance, 4x the gravity), and so on.

The above is true only when the unit distance is a positive number. When this is set to 0.0, the gravity will be constant regardless of distance.

gravity_scale

gravity_scale: float

setter: set_gravity_scale; getter: get_gravity_scale.

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.

gravity_space_override

gravity_space_override: int

setter: set_gravity_space_override; getter: get_gravity_space_override.

Override mode for gravity calculations within this area.

inertia

inertia: Vector3

setter: set_inertia; getter: get_inertia.

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

linear_damp

linear_damp: float

setter: set_linear_damp; getter: get_linear_damp.

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.

linear_damp_mode

linear_damp_mode: int

setter: set_linear_damp_mode; getter: get_linear_damp_mode.

Defines how linear_damp is applied.

linear_damp_space_override

linear_damp_space_override: int

setter: set_linear_damp_space_override; getter: get_linear_damp_space_override.

Override mode for linear damping calculations within this area.

linear_velocity

linear_velocity: Vector3

setter: set_linear_velocity; getter: get_linear_velocity.

The body’s linear velocity in units per second. Can be used sporadically, but don’t set this every frame, because physics may run in another thread and runs at a different granularity. Use RigidBody3D._integrate_forces as your process loop for precise control of the body state.

lock_rotation

lock_rotation: bool

setter: set_lock_rotation; getter: get_lock_rotation.

If true, the body cannot rotate. Gravity and forces only apply linear movement.

mass

mass: float

setter: set_mass; getter: get_mass.

The body’s mass.

max_contacts_reported

max_contacts_reported: int

setter: set_max_contacts_reported; getter: get_max_contacts_reported.

The maximum number of contacts that will be recorded. Requires a value greater than 0 and contact_monitor to be set to true to start to register contacts. Use RigidBody3D.get_contact_count to retrieve the count or RigidBody3D.get_colliding_bodies to retrieve bodies that have been collided with.

Note: The number of contacts is different from the number of collisions. Collisions between parallel edges will result in two contacts (one at each end), and collisions between parallel faces will result in four contacts (one at each corner).

monitorable

monitorable: bool

setter: set_monitorable; getter: get_monitorable.

If true, other monitoring areas can detect this area.

monitoring

monitoring: bool

setter: set_monitoring; getter: get_monitoring.

If true, the area detects bodies or areas entering and exiting it.

physics_material_override

physics_material_override: PhysicsMaterial

setter: set_physics_material_override; getter: get_physics_material_override.

The physics material override for the body.

If a material is assigned to this property, it will be used instead of any other physics material, such as an inherited one.

priority

priority: int

setter: set_priority; getter: get_priority.

The area’s priority. Higher priority areas are processed first. The World3D’s physics is always processed last, after all areas.

sleeping

sleeping: bool

setter: set_sleeping; getter: get_sleeping.

If true, the body will not move and will not calculate forces until woken up by another body through, for example, a collision, or by using the RigidBody3D.apply_impulse or RigidBody3D.apply_force methods.

sync_to_physics

sync_to_physics: bool

setter: set_sync_to_physics; getter: get_sync_to_physics.

If true, the body’s movement will be synchronized to the physics frame. This is useful when animating movement via AnimationPlayer, for example on moving platforms. Do not use together with PhysicsBody3D.move_and_collide.

wind_attenuation_factor

wind_attenuation_factor: float

setter: set_wind_attenuation_factor; getter: get_wind_attenuation_factor.

The exponential rate at which wind force decreases with distance from its origin.

Note: This wind force only applies to SoftBody3D nodes. Other physics bodies are currently not affected by wind.

wind_force_magnitude

wind_force_magnitude: float

setter: set_wind_force_magnitude; getter: get_wind_force_magnitude.

The magnitude of area-specific wind force.

Note: This wind force only applies to SoftBody3D nodes. Other physics bodies are currently not affected by wind.

wind_source_path

wind_source_path: NodePath

setter: set_wind_source_path; getter: get_wind_source_path.

The Node3D which is used to specify the direction and origin of an area-specific wind force. The direction is opposite to the z-axis of the Node3D’s local transform, and its origin is the origin of the Node3D’s local transform.

Note: This wind force only applies to SoftBody3D nodes. Other physics bodies are currently not affected by wind.