Physics API

Change a running instance

Each node exposes its own MeshyPhysics object through read-only physics. Read or assign typed properties to inspect or change that instance:

$Prop.apply_central_impulse(Vector3(0, 4, 0))
$Prop.physics.freeze = true
var velocity: Vector3 = $Prop.physics.linear_velocity
$Zone.physics.monitoring = false
$Zone.body_entered.connect(func(body: Node3D): print(body.name))

physics_settings supplies saved defaults. Live changes leave it unchanged. Scene saves exclude overrides and simulation state. Instances that share a preset keep velocities, forces, contacts, callbacks, server IDs, and overrides separate.

Live properties	Required mode
Mass, dynamic velocities, sleep, freeze	Rigid
Monitoring, environment overrides	Trigger
Constant velocities	Static or Animatable
`sync_to_physics`	Animatable

Invalid values or unavailable properties warn without changing state. Reads return effective defaults or overrides. Rigid linear_velocity and angular_velocity reads use the latest cached simulation state from physics callbacks.

Node methods

API	Purpose
`get_physics_rid()`	Server object ID. Invalid outside a physics world or without usable collision.
`set_physics_mode(mode)`, `get_physics_mode()`	Change or inspect the live mode
`set_collision_layer/mask(value)` and bit helpers	Change collision filtering
`apply_central_impulse`, `apply_impulse`, `apply_torque_impulse`	Instant Rigid changes
`apply_central_force`, `apply_force`, `apply_torque`	Forces during physics ticks
`get_overlapping_bodies/areas`, `overlaps_body/area`	Trigger overlap queries
`get_contact_count`, `get_contact(index)`	Configured Rigid contacts
`precise_contact_query(state, index)`	Resolve a contact to an authored source face
`precise_ray_query(from, to)`	Intersect saved authored triangles and identify the source face

Change modes

Live mode changes preserve the saved resource and collision. Compatible modes reuse saved convex shapes. Concave shapes support Static and Animatable only. An incompatible mode disables collision and warns. A compatible mode restores the shapes.

Mode changes reset overrides to new mode defaults without compiling geometry.

Contacts and overlap events

Rigid contacts require contact_monitor and a positive max_contacts_reported. Sleeping/state changes and integration signals expose Rigid simulation changes.

Trigger body/area and shape enter/exit signals track shape pairs. Object entry emits once. Object exit follows the last pair. Disabling monitoring, removal, and object recreation clear overlaps.

Changes inside overlap handlers apply after the current event batch. This includes live controls and settings, source geometry, or collision artifact replacements. Disabling collision from an entry handler completes shape entry before shape/object exit.

get_contact() returns world-space collider_position and, for Meshy colliders, source-face metadata in collider_surface. During integration, call precise_contact_query(state, index) on the collider for the same metadata. Positions and normals use world space. Unmatched contacts return an empty dictionary.

Precise ray results

Native PhysicsServer ray queries identify the Meshy node as collider. Source-face identity differs from render surface and convex-piece indices. One render surface can contain many authored faces.

precise_ray_query reports original triangle provenance and excludes synthetic decomposition caps. Pieces contain only their clipped authored triangles. The returned shape identifies a piece covering the hit. Rays through openings miss, even when coarse piece indices cannot identify authored faces.