Manual

Manual

Bodies and colliders

Physics 3D moves the bodies of a 3D game: what falls, rolls, bounces and is pushed. This page covers the Rigidbody 3D, each kind of collider and how to edit its size in the Scene view, the materials colliders are made of, which layers collide, and the Physics 3D settings.

Physics 3D

Physics 3D is the official package abyss.physics3d, built on Jolt Physics 5.6.0. Install it from Window ▸ Package Manager (see Using packages). As the game starts, the Logs panel says Physics 3D: Jolt 5.6.0.

Physics runs only while the game plays. In the editor, bodies stay where you placed them, and Stop puts them back.

The world's units are meters, and gravity pulls down along −Y. Physics steps at the game's fixed rate, a sixtieth of a second unless Project Settings ▸ Time says otherwise (see Systems at a fixed rate). Each step writes where every body went to its Transform.

Jolt is built cross-platform deterministic: the same bodies, made in the same order and stepped as often, end exactly where they ended before, on any platform.

Bodies and ground

A collider is the shape an entity meets things with. What it belongs to decides how it moves:

  • A collider with no Rigidbody 3D on its entity or above it is ground. It never moves by itself. It stays where its entity's place in the world puts it, and moves only when you move the entity.
  • A Rigidbody 3D makes its entity a body, which physics moves. The body is made of the colliders on its own entity and of those on the entities under it, down to any child that has a Rigidbody 3D of its own.
  • A child with its own Rigidbody 3D is a separate body. To hold two bodies together, use a joint.

So a cart of a bed and four wheels, each a child entity with a collider, is one body when the Rigidbody 3D is on the cart. Each collider sits where its own Transform, and those between it and the body, put it, and each is on its own entity's layer.

An entity needs no Rigidbody 3D to be solid. Floors, walls and terrain are colliders alone.

Rigidbody 3D

A Rigidbody 3D makes its entity a body that physics moves. Add one from Add Component in the Inspector, beside one or more colliders.

FieldWhat it does
TypeDynamic is moved by gravity, by what it meets and by forces. Kinematic is moved by its velocity alone, as your code sets it: it pushes dynamic bodies and is never pushed. Static never moves by physics: ground and walls that belong together as one body.
Use Auto MassWorks the mass out from the colliders, each its volume times its Density, and shows it in Mass while the game plays.
MassThe body's mass, in kilograms, whatever its colliders' sizes.
Gravity ScaleHow much of gravity pulls it: 1 all of it, 0 none, −1 upward.
Linear DampingHow quickly its moving slows by itself, as in air. 0 at first.
Angular DampingHow quickly its turning slows by itself. 0.05 at first.
FreezeTicks for each way it never moves or turns, along and about the world's axes: Position X, Y and Z, and Rotation X, Y and Z.
InterpolateNone draws it where the last step put it. Interpolate draws it between where the last two steps put it: smooth at any frame rate, a step behind.
Collision DetectionDiscrete checks where it is at each step, which is cheap, though a small fast body can pass through a thin one. Continuous also checks along its way between steps, for bullets and other fast, small bodies.
Linear VelocityHow fast it moves, in meters a second.
Angular VelocityHow fast it turns about each of the world's axes, in degrees a second.

Freeze keeps a body to the ways it may move. A character standing upright never turns about X or Z; a game played on a plane never moves along Z. A dynamic body frozen every way is moved as a kinematic one is, by your code alone.

While the game plays, Linear Velocity and Angular Velocity show what the last step left. They are also how your code moves a body: set them, and the next step starts from them.

Move a body from code

Your code reaches Physics 3D through the world's services: context.Services.Get<Physics3D>() in a system, or world.Services.Get<Physics3D>() elsewhere. A force, an impulse or a move asked of it is applied at the next fixed step.

using System.Numerics;using Abyss.Physics3D;
Physics3D physics = context.Services.Get<Physics3D>();
physics.AddImpulse(ball, new Vector3(0f, 5f, 2f));       // a kick, at oncephysics.AddForce(balloon, new Vector3(0f, 12f, 0f));     // a push for the next step, through its middlephysics.AddForceAtPosition(boat, thrust, stern);         // a push off its middle turns it toophysics.AddTorque(wheel, new Vector3(0f, 0f, 40f));      // a turn
physics.MovePosition(door, open);                        // a kinematic body, there after one stepphysics.MoveRotation(door, Quaternion.CreateFromAxisAngle(Vector3.UnitY, 1.2f));
MethodWhat it does
AddForce, AddForceAtPositionPushes for the next step, in newtons. Away from the center of mass, it turns the body as well.
AddImpulse, AddImpulseAtPositionChanges its speed at once, in newton-seconds: a jump, a hit.
AddTorque, AddAngularImpulseTurns it about each of the world's axes: a torque for the next step, in newton meters, or a turning impulse at once.
MovePosition, MoveRotationMoves or turns a body to a place over the next step, pushing what is in its way. This is how a kinematic platform, door or lift is moved. Asked every step, it keeps going.

Forces and impulses move only dynamic bodies. Asked of a static body, or of an entity with no Rigidbody 3D, they do nothing. Physics3D is safe to call from any system, parallel ones included.

Setting a body's Transform from code puts it there at once, as a teleport, passing through whatever is between. To move a body without that jump, set its velocity or use MovePosition.

Run a system that pushes on bodies at the fixed rate ([AbyssSystem(Fixed = true)]), so it acts once for each step. The physics step runs before your game's fixed systems, so they see where it left everything.

Colliders

Every collider is in its entity's own units, and scales and turns with the entity. A box, a sphere and a capsule have an Offset, where their middle is from the entity's; a mesh collider is where its mesh is. Every collider can be a trigger, and has a material and a density:

FieldWhat it does
Is TriggerA trigger meets nothing: bodies pass through it, and your code is told what went in and out (see Triggers).
MaterialThe Physics Material 3D it is made of. None uses the Default Material of the Physics 3D settings.
DensityHow heavy it is for its size, in kilograms a cubic meter. A body with Use Auto Mass gets its mass from it.

When you add a collider in the editor, it fits what its entity draws, a mesh or a sprite: a box takes the size of the mesh's box, a sphere goes round it, and a capsule lies along its longest side. An entity that draws nothing keeps the collider's defaults.

In the Scene view, the colliders of what is picked are drawn as green wireframes, while you edit and while the game plays.

Box Collider 3D

A box, as wide, high and deep as Size.

FieldWhat it does
SizeHow wide, high and deep it is, in the entity's own units. 1 each way at first.
OffsetWhere its middle is, from the entity's.

A box with no depth, such as one round a plane, is made a centimeter thick, so what lands on it still stops.

Sphere Collider 3D

A ball, scaled by the largest of the entity's scales.

FieldWhat it does
RadiusHow far its surface is from its middle, in the entity's own units. 0.5 at first.
OffsetWhere its middle is, from the entity's.

Capsule Collider 3D

A cylinder with a half ball at each end: the usual shape of a character. Its radius scales by the larger of the entity's scales across it, and its height by the scale along it.

FieldWhat it does
RadiusHow far its surface is from the line down its middle. 0.5 at first.
HeightHow long it is end to end, its round ends included. 2 at first. A capsule no longer than it is wide is a ball.
DirectionWhich of the entity's own axes it lies along: X, Y (upright) or Z.
OffsetWhere its middle is, from the entity's.

Mesh Collider 3D

A Mesh Collider 3D is the entity's own mesh, scaled, turned and mirrored with it: a level's floors, walls and ramps meet things as they are drawn, so a ball rolls into a trench and up a ramp as they look. An entity with no mesh meets nothing, and the Inspector says so under the collider.

FieldWhat it does
ConvexMakes it the mesh's hull, the smallest convex shape round it, rather than its triangles.
Is TriggerAs on any collider.
MaterialAs on any collider.
DensityHow heavy its hull is for its size. Triangles weigh nothing.

A mesh collider is its triangles where it is ground, or on a Static or Kinematic body. Triangles have no inside, so on a Dynamic body and as a trigger it is always the hull, which weighs its volume times its Density. The Inspector says so under a collider this changes, and the Scene view draws what physics meets: the triangles' edges, or the hull's.

Two things to know about triangles and hulls:

  • A triangle is met from its front only, the side its corners go round counter-clockwise from. Something that jumps up into a floor from below passes through it.
  • A hull has at most 256 corners. A mesh of more is held by those furthest out.

Every Mesh Collider 3D of the same mesh shares one shape, made the first time the game asks for it.

Meshes baked as a model is imported

A model's meshes can be worked out for physics as the editor imports the model, so a game reads the shapes rather than working them out as it starts. In the model's import settings, the Baking section has a Physics 3D switch. Adding a Mesh Collider 3D to an entity whose mesh is part of a model turns it on for that model. See Models for the rest of a model's import settings.

The baked shapes are packed with the model. A mesh made by code, a primitive, or a bake made by another version of Jolt is worked out as the game plays instead.

Meshes made by code

A mesh your code makes or replaces gets its collider's shape in the first physics step that asks for it, on the engine thread: about a millisecond for a chunk of a block world. A game that builds meshes on threads of its own can work the shape out there too, and hand it over with the mesh in one call, so the step makes nothing:

// On the generation thread: the chunk's mesh data, and its collider's shape.MeshShape3D shape = MeshShape3D.Prepare(data);
// Then, with the data and the shape worked out of it:MeshId chunk = physics.CreateMesh(data, shape);physics.UpdateMesh(chunk, changed, MeshShape3D.Prepare(changed));

Prepare always works out the triangles, which ground and Static or Kinematic bodies meet. Pass hull: true to work out the hull too, for a collider that is Convex, a trigger or on a Dynamic body. CreateMesh and UpdateMesh set the mesh and its shape together, so a step never sees one without the other. A shape is handed over once and belongs to Physics 3D after; one you never hand over is let go of by Dispose.

Edit Collider

The Edit Collider button in a box's, a sphere's or a capsule's section puts dots on the collider in the Scene view:

  • a box gets one in the middle of each face;
  • a sphere gets one at each end of its three axes, for its radius;
  • a capsule gets four round its middle, for its radius, and one at each end, for its height.

A dot slides along its own line only, out of its face or the way its radius goes, wherever the pointer goes. Drag it to move that side while the far side stays. Hold Alt to keep the middle where it is, and Shift to grow the other sizes as much. Hold Ctrl, or turn on the Scene row's magnet, to snap it to the Move tool's step. A mesh collider is its mesh, and has no dots.

Physics Material 3D

A Physics Material 3D says how a collider slides along what it touches and how it bounces off it. Make one from the Project panel with Create ▸ Physics 3D ▸ Physics Material 3D, and drop it on a collider's Material slot.

FieldWhat it does
FrictionHow much it holds against sliding: 0 slides as on ice. 0.4 at first.
BouncinessHow much it bounces back: 0 stops dead, 1 bounces as high as it fell. 0 at first.

Each collider has its own material, so one body can be rubber underneath and ice on top. Where two colliders touch, they hold as the square root of their frictions multiplied, and bounce as the bouncier of the two.

Layers and what collides

Each collider is on its entity's layer, which you set with the Layer row under the entity's name in the Inspector (see Layers). The Collisions grid of the Physics 3D settings has a tick for each pair of layers: bodies on two layers whose tick is off pass through each other. A body whose colliders are on several layers is checked collider by collider.

To keep two particular entities from meeting, such as a thrown sword and its thrower, use IgnoreCollision; see Pairs that do not meet.

Physics 3D settings

Edit ▸ Project Settings ▸ Physics 3D holds the settings every body follows. They are saved in settings/physics-3d.json, which the built game carries.

FieldWhat it does
GravityThe pull on every body, in meters a second squared. (0, −9.81, 0) at first, the Earth's.
Velocity StepsHow many times each step's velocities are worked out, from 2 to 32. 10 at first: more holds stacks and joints steadier, and is slower.
Position StepsHow many times each step pushes apart what overlaps, from 1 to 16. 2 at first.
Allowed PenetrationHow far bodies may sink into each other before they are pushed apart, in meters. Half a centimeter at first: what rests on the ground is that far into it. Less looks truer, and settles a stack less readily.
Default MaterialWhat a collider is made of when it names no material. None uses a Physics Material 3D's own values.
Queries Hit TriggersWhether raycasts, shape casts and overlaps find triggers. On at first.
Queries Start In CollidersWhether a raycast or a shape cast that starts inside a collider hits it there. On at first. Off, it passes over it, so a ray down from a body's middle finds what is under it.
CollisionsA triangle of ticks, by the layers' names: which layers' bodies meet which.

A system reads these as Res<Physics3DSettings>. A game may change them while it plays, such as gravity for a low-gravity zone, with ResMut<Physics3DSettings>; the change lasts for that run only, and Stop puts the values back.

Particles meet colliders

A Particle Emitter drawn in 3D whose Collision module is in World mode has its particles meet these colliders, on the layers it collides with. It does so in the Scene panel while you edit, too. See Particle Emitter.

In the Scripting API