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.
| Field | What it does |
|---|---|
| Type | Dynamic 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 Mass | Works the mass out from the colliders, each its volume times its Density, and shows it in Mass while the game plays. |
| Mass | The body's mass, in kilograms, whatever its colliders' sizes. |
| Gravity Scale | How much of gravity pulls it: 1 all of it, 0 none, −1 upward. |
| Linear Damping | How quickly its moving slows by itself, as in air. 0 at first. |
| Angular Damping | How quickly its turning slows by itself. 0.05 at first. |
| Freeze | Ticks 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. |
| Interpolate | None 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 Detection | Discrete 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 Velocity | How fast it moves, in meters a second. |
| Angular Velocity | How 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));| Method | What it does |
|---|---|
AddForce, AddForceAtPosition | Pushes for the next step, in newtons. Away from the center of mass, it turns the body as well. |
AddImpulse, AddImpulseAtPosition | Changes its speed at once, in newton-seconds: a jump, a hit. |
AddTorque, AddAngularImpulse | Turns it about each of the world's axes: a torque for the next step, in newton meters, or a turning impulse at once. |
MovePosition, MoveRotation | Moves 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:
| Field | What it does |
|---|---|
| Is Trigger | A trigger meets nothing: bodies pass through it, and your code is told what went in and out (see Triggers). |
| Material | The Physics Material 3D it is made of. None uses the Default Material of the Physics 3D settings. |
| Density | How 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.
| Field | What it does |
|---|---|
| Size | How wide, high and deep it is, in the entity's own units. 1 each way at first. |
| Offset | Where 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.
| Field | What it does |
|---|---|
| Radius | How far its surface is from its middle, in the entity's own units. 0.5 at first. |
| Offset | Where 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.
| Field | What it does |
|---|---|
| Radius | How far its surface is from the line down its middle. 0.5 at first. |
| Height | How long it is end to end, its round ends included. 2 at first. A capsule no longer than it is wide is a ball. |
| Direction | Which of the entity's own axes it lies along: X, Y (upright) or Z. |
| Offset | Where 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.
| Field | What it does |
|---|---|
| Convex | Makes it the mesh's hull, the smallest convex shape round it, rather than its triangles. |
| Is Trigger | As on any collider. |
| Material | As on any collider. |
| Density | How 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.
| Field | What it does |
|---|---|
| Friction | How much it holds against sliding: 0 slides as on ice. 0.4 at first. |
| Bounciness | How 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.
| Field | What it does |
|---|---|
| Gravity | The pull on every body, in meters a second squared. (0, −9.81, 0) at first, the Earth's. |
| Velocity Steps | How 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 Steps | How many times each step pushes apart what overlaps, from 1 to 16. 2 at first. |
| Allowed Penetration | How 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 Material | What a collider is made of when it names no material. None uses a Physics Material 3D's own values. |
| Queries Hit Triggers | Whether raycasts, shape casts and overlaps find triggers. On at first. |
| Queries Start In Colliders | Whether 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. |
| Collisions | A 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
- Rigidbody3D: a body physics moves, with BodyType3D and Freeze3D.
- BoxCollider3D, SphereCollider3D, CapsuleCollider3D and MeshCollider3D: the shapes a body meets things with.
- Physics3D: forces, impulses and moves asked of a body.
- MeshShape3D: a mesh collider's shape worked out on a thread of your own.
- PhysicsMaterial3D and Physics3DSettings: what colliders are made of, and the settings every body follows.
