Physics
NEO's rigid-body physics (neo_physics): bodies, colliders, settings and commands, and how the motion-matched character walks, lands, climbs and pushes in the physics world.
On this page
neo_physics is NEO's rigid-body physics: dynamic, kinematic and static bodies, colliders from shapes, scene primitives and meshes, joints, and ray and shape casts. It steps on the fixed timestep and gives the same results on native and web builds. With it, the gameplay kit's motion-matched character moves in the same world as everything else.
This page is for creators who write Rust game code. For the character itself, see Gameplay kit.
Turning it on#
A game gets the neo_physics plugin by linking the crate. It's on by default; [plugins] neo_physics = false turns it off. Its settings live in [plugin.neo_physics] in neo.toml:
[plugin.neo_physics]
gravity = 9.81 # m/s², along -Y
substeps = 6 # solver substeps per fixed step
paused = false
debug_draw = false # colliders, contacts and joints drawn as gizmos
interpolate = true # rendered transforms interpolate between fixed steps
character_push_force = 400.0 # N: the most a character pushes the bodies it walks into| Setting | Default | What it does |
|---|---|---|
gravity | 9.81 | Gravity in m/s², pointing down (-Y). |
substeps | 6 | Solver substeps per fixed step, 1 to 64. |
paused | false | Stops the simulation. |
debug_draw | false | Draws colliders, contacts and joints. |
interpolate | true | Smooths rendered motion between fixed steps. The simulation itself is unchanged. |
character_push_force | 400.0 | The most force, in newtons, a character puts on the bodies it walks into. 0 to 100,000. |
You can change every setting while the game runs, in the Plugins panel or with plugins.settings.set neo_physics. See Plugins and neo.toml.
Bodies and colliders#
Bodies are components from neo_physics::prelude:
use neo::prelude::*;
use neo_physics::prelude::*;
fn setup(mut commands: Commands) {
// a floor, a crate and a ball on a rope
commands.spawn((RigidBody::Static, Collider::cuboid(20.0, 1.0, 20.0), Transform::from_xyz(0.0, -0.5, 0.0)));
let a = commands.spawn((RigidBody::Dynamic, Collider::cuboid(1.0, 1.0, 1.0), Transform::from_xyz(0.0, 4.0, 0.0))).id();
let b = commands.spawn((RigidBody::Dynamic, Collider::sphere(0.3), Transform::from_xyz(1.5, 4.0, 0.0))).id();
commands.spawn(DistanceJoint::new(a, b).with_limits(1.0, 1.5));
}| Need | How |
|---|---|
| Body kinds | RigidBody::Dynamic, RigidBody::Kinematic (moved by its velocity, pushes dynamic bodies, nothing pushes it), RigidBody::Static. |
| Colliders | Collider::cuboid, sphere, capsule, cylinder, compound. Meshes: Collider::trimesh_from_mesh, convex_hull_from_mesh, or ColliderConstructor::TrimeshFromMesh on an entity with a Mesh3d. Terrain: Collider::heightfield. |
| Scene primitives | A scene object (cube, sphere, plane, cylinder, from the Studio's + Add or a saved scene) given a RigidBody gets a matching collider, scaled by its transform. |
| Joints | FixedJoint, RevoluteJoint (hinges, doors), SphericalJoint (chains), PrismaticJoint (sliders), DistanceJoint (ropes, springs), with limits and motors. |
| Queries | The SpatialQuery system parameter in systems; neo_physics::query::{raycast, shapecast} from a &mut World. |
| Materials | Friction, Restitution, ColliderDensity, Mass. |
| Stats | The PhysicsStats resource: bodies by kind, sleeping bodies, colliders, joints, contacts, steps and step time. |
Physics steps in FixedUpdate (64 Hz by default). PhysicsSystems::Prepare runs before the step and PhysicsSystems::Writeback after it. See Fixed timestep.
Commands#
The Studio and its MCP tools use these commands.
| Command | What it does |
|---|---|
physics.stats | Stats, settings and the state hash. |
physics.bodies | Every body: entity, name, kind, position, rotation, velocities, mass, and whether it's asleep. Takes kind and limit. |
physics.raycast | The first hit of a ray (origin, direction, max_distance). |
physics.shapecast | The first hit of a swept sphere, cuboid, capsule or cylinder. |
physics.impulse | Applies an impulse to a dynamic body. |
physics.spawn | Spawns a cube, sphere, cylinder or capsule body. |
physics.hash | The state hash. |
physics.character | The characters in the physics world: whether they use it, its colliders and level boxes, the push force, and for each character its capsule in the world and last frame's pushes (body, impulse, point). |
The character in the physics world#
With the gameplay_kit feature of neo_physics, the gameplay kit's characters (the player, NPCs and other players) move in the physics world. Starter's physics feature turns it on.
What the character collides with#
Every frame, before the character simulation steps, the physics colliders become the character's collision world. The character walks, steps up, lands, places its feet and traverses on all of them:
- triangle meshes, including meshes from the Studio;
- heightfield terrain;
- primitives (boxes, spheres, capsules, cylinders);
- simulated bodies, dynamic and kinematic;
- the level's own boxes, which become static colliders.
Sensors are ignored.
Vault, hurdle and mantle find ledges on any shape, not only boxes. On a mesh block or a terrain cliff, the front ledge is the edge above the wall the character faces (at least 60 cm wide), and the back ledge is where the top ends (up to 4 m across).
Pushing bodies#
A simulated body blocks the character like a wall, and so does an edge higher than a step, such as the top of a crate. The bodies a character presses get impulses, at the contact and at the body's centre height, toward the speed it wants to walk at, with at most character_push_force newtons per character (400 N by default). Set it in [plugin.neo_physics] or change it while the game runs.
| Body | What happens |
|---|---|
| A light crate | Slides or tips ahead. The character keeps pace with a body moving away from it, no faster. |
| A heavy block whose friction holds more than the push | Doesn't move, and stops the character. |
Bodies don't pass through characters#
Every character has a kinematic capsule in the physics world, 3 cm smaller than its own (CharacterProxy). Bodies falling or rolling into a character hit it instead of passing through. The capsule follows the character every fixed step, and crouching resizes it. The character's own queries ignore these capsules.
What colliders mean to the character#
Add a CharacterSurface component to a collider to set its footstep material and whether traversals may climb it:
use neo::prelude::*;
use neo_character::level::Surface;
use neo_physics::kit::CharacterSurface;
use neo_physics::prelude::*;
fn spawn_ramp(mut commands: Commands) {
commands.spawn((
RigidBody::Static,
Collider::cuboid(4.0, 0.5, 2.0),
Transform::from_xyz(3.0, 0.25, 0.0),
// ramp footsteps, and no vaulting or mantling onto it
CharacterSurface { surface: Surface::Ramp, traversable: false },
));
}| Field | What it does |
|---|---|
surface | The footstep material: Floor, Block, Accent, Ramp or Stairs. |
traversable | Whether vault, hurdle and mantle may use its ledges. |
Without a CharacterSurface, a static or kinematic collider is a Block the character may climb, and a dynamic one is a Block it doesn't climb.
Startup and the clock#
Physics waits for the character simulation at startup: nothing steps until the simulation exists and its level's colliders are in the world. Otherwise bodies spawned at startup could fall through a floor that isn't there yet. Until the physics world holds the current level (the first fixed step, or the rebuild after a level edit), the character uses its own boxes, which are the same geometry. Physics also pauses whenever the character simulation pauses.
A game without physics is unchanged: the character collides with its own level boxes, exactly as before.
Checking it#
The engine's character_world example plays the character on a test course with a curb, a mesh hill, terrain bumps, crates, a heavy block and a mesh block to mantle. It renders in a hidden window and writes every frame's facing vectors and shots to a folder:
cargo run -p neo_physics --features gameplay_kit --example character_world -- --course <dir>
cargo run -p neo_physics --features gameplay_kit --example character_world -- --character-audit <dir> --character-audit-frames 90--character-audit runs the gameplay kit's facing audit (8 directions, walk, run and sprint, 4 camera angles, two orbits) with the character in the physics world.
A hidden run still renders. neo_gameplay_kit::offscreen sends every camera that would draw to the window into an offscreen image instead, and screenshots read that image. Use it for your own audits and verification runs:
| Item | What it does |
|---|---|
Offscreen::new(w, h) | The resource that turns it on, with the capture size in pixels (scale factor 1.0). |
OffscreenPlugin | Redirects the cameras while Offscreen is present. |
hidden_window(title, w, h) | A window of the capture size that's never shown or focused, without vsync. |
screenshot(offscreen) | A screenshot of what the player sees: the offscreen image in a hidden run, else the window. |
Limits today#
- Characters standing on bodies don't weigh on them.
- Moving kinematic platforms don't carry characters: the character doesn't take a platform's velocity.
- Other players' capsules block bodies but don't push them. Each player pushes only on its own machine.
- Ragdolls have no capsule in the physics world, so ragdolls and bodies don't touch yet.
- The character tests every collider's bounds on each query. That's fine for hundreds of colliders, not for thousands.
- The character course's determinism check matches on Apple silicon and the web; it hasn't run on x86_64 yet.