Physics Components

Last verified: 2026-06-03

Physics uses Rapier in runtime. Collider, RigidBody, movement input, and queries have separate roles.

RigidBodyComponent

Use Rigid Body to make an entity static, dynamic, or kinematic in physics. Fields control body type, mass, damping, gravity scale, translation locks, rotation locks, CCD, and sleeping state.

Dynamic bodies are moved by the physics step and write back Transform and Velocity. Kinematic bodies follow authored/runtime movement intent. Static bodies do not move but can be contacted and queried.

Gotcha: a RigidBody without a Collider can move, but it has no authored contact shape.

ColliderComponent

Use Collider to define a passive contact, trigger, or query shape. Fields control shape, size, solidity, trigger behavior, layers, friction, and restitution.

With RigidBody, Collider attaches to the authored body. Without RigidBody, Collider binds as a fixed standalone collider, which is the right model for floors, walls, trigger volumes, and physics query targets.

Gotcha: Collider is passive by default. Static Collider plus static Collider does not emit normal collision events. Trigger enter/exit requires an active participant such as a Rigidbody body or a server movement-controlled entity.

VelocityComponent

Use Velocity to expose the current movement velocity vector. It is runtime-owned: physics and the kinematic controller patch it each tick, and you author it only as a reset default.

Gotcha: Velocity requires Transform so movement has a world-space target, but Velocity alone does not mean physics simulation, wall blocking, or collision event participation.

CharacterMovementComponent

Use CharacterMovementComponent for the authored movement config of the shared kinematic character controller: maxSpeed (horizontal cap) plus the deterministic vertical motor gravity, jumpSpeed, and groundY. Set enableKcc to opt the entity into predicted kinematic movement (walk + jump); leave it unset to infer from gravity. (ecs-v1 F4e split this config out of VelocityComponent so the live velocity vector and the authored config stop sharing a component.)

Gotcha: CharacterMovementComponent requires Transform. The velocity vector still lives on VelocityComponent; this component holds only the config the controller reads.

NetworkProfileComponent

Use NetworkProfileComponent to pick how remote clients present this entity's replicated motion: responsive hugs the newest server sample and never bridges gaps (teleporting projectiles, snappy pickups), smooth doubles the interpolation buffer for perfectly fluid slow movers (platforms, doors), and the unset/default value is the tick-derived baseline. It carries only the selection; the interpolation timing numbers stay server-derived in the runtime netcode contract.

Gotcha: NetworkProfileComponent has no hard dependency and only shapes remote (interpolated) presentation. The entity you own is predicted, so the profile changes how OTHER clients see this entity, not how it feels for its owner.

ForceComponent

Force is an internal runtime component used as the physics command queue. It stores pending forces, impulses, torque, torque impulses, teleports, resets, and optional application points until the physics system consumes them.

Gotcha: creators do not add or edit Force directly. Scripts use ctx.physics.command(entityId, bodyCommand).

NavAgentComponent

Use Nav Agent to mark an entity as server-owned path-following agent intent. Fields control enabled state, destination, optional target entity key, speed, arrival radius, agent profile, and repath behavior.

Gotcha: Nav Agent is navigation intent, not a second transform owner or a navmesh component. Runtime movement still resolves through the existing mover/Transform authority, and path previews/debug overlays should read navigation/runtime state instead of treating the component as scene geometry.

Common Patterns

Use a dynamic RigidBody plus box/sphere/capsule Collider for moving physical objects. Use a standalone Collider for a static floor, wall, trigger, or query target. Use movement input/action declarations for player/NPC controller movement; those movers can sweep, slide, block, and enter triggers against standalone solid colliders without adding RigidBody. Use Nav Agent for server-owned NPC path-following over the world navmesh. Use a kinematic RigidBody when physics contact/query behavior should be owned by Rapier.

Queries are separate from collision response and events. Raycast, overlap, and shapecast may hit passive colliders even when the same passive pair would not emit enter/exit events.

Verified Behavior

The component integrity cycle verifies dynamic falling bodies, collision response, collision events, sensors/triggers, shapecast/overlap/occupancy queries, Physics.command body mutations, NavAgentComponent materialization/mutation/replication, kinematic transform sync, standalone fixed colliders, cleanup on removal, and replication policy.