Physics core

Back to Zarith

Everything on this page lives in core (packages com.raiiiden.zarith.core.jolt and com.raiiiden.zarith.core.physics). None of it imports Minecraft, so it is identical on every version. Most mods never use it directly; block groups and vehicles drive it for you. Use it when you need a body that is not made of blocks, or when you write your own entity around a body.

ZarithJolt

com.raiiiden.zarith.core.jolt.ZarithJolt loads Jolt once per JVM.

load() fails, with a reason, in these cases: no native for this OS and architecture, the native could not be extracted or loaded, or the jolt-jni classes came from a different class loader than Zarith (another mod bundles jolt-jni).

If the native file from an earlier launch is already in .zarith/natives/6.0.0/ and has the same size as the bundled one, it is reused. On Windows a DLL that another game instance has loaded cannot be replaced; Zarith treats the file already there as correct in that case.

PhysicsSpace

One Jolt world. LevelPhysics makes one per server level; you can also make your own.

PhysicsSpace space = new PhysicsSpace("my-test-space", terrain); // terrain may be null

The constructor throws IllegalStateException if Jolt is not loaded. A space with null terrain has no world blocks in it, only the bodies you add.

Constants and budgets

Collision layers

Each body sits on one of four object layers.

So a body that passes soft terrain falls through leaves, while everything else lands on them. Felled uses this for falling trees.

Methods

BodyShape

A body’s shape is a list of axis aligned boxes in the body’s local frame. The body’s position is this frame’s origin.

BodyShape crate = BodyShape.box(0.5f, 0.5f, 0.5f);        // a cube centred on the origin
BodyShape cube = BodyShape.cube();                         // the same

BodyShape table = new BodyShape()
        .add(0, 0.8, 0, 2, 1, 1)                           // top, settings density
        .add(0, 0, 0, 0.1, 0.8, 0.1)                       // one leg
        .add(1.9, 0, 0, 2, 0.8, 0.1)
        .add(0, 0, 0.9, 0.1, 0.8, 1)
        .add(1.9, 0, 0.9, 2, 0.8, 1)
        .add(0, 0, 0, 2, 0.3, 1, 2000f, false);            // heavy, mass only: lowers the centre of mass

add(minX, minY, minZ, maxX, maxY, maxZ) adds a solid box that weighs the body’s settings density. The long form adds two arguments:

• density: kg per cubic metre for this box, or Float.NaN for the settings density.
• collides: false for a mass only box. It adds weight and changes how the body turns, but never touches anything. Vehicles use this for ballast.

Boxes thinner than 0.06 m on any axis are padded to that, since Jolt rejects flat boxes. That is why carpets and pressure plates still work as bodies.

How the shape becomes a Jolt shape:

• If every box uses the settings density and collides, Jolt works out mass and inertia from the density. One box becomes a BoxShape; several are first merged (below) and become a static compound.
• If any box has its own density or is mass only, Zarith works out the total mass, centre of mass and full inertia tensor itself from every box, builds the shape from the colliding boxes only, shifts its centre of mass to match, and sets the mass properties on the body.
• Boxes that share a whole face are merged into one, along X, then Z, then Y, for up to four rounds. Seams between the boxes of a compound catch on anything sliding across them; a single box has none.
• Convex radius is Jolt’s default or half the smallest half extent, whichever is smaller.

Other methods: isEmpty(), boxCount(), boxes() (each as {centreX, centreY, centreZ, halfX, halfY, halfZ, density, collides}), volume(), mass(defaultDensity).

BodySettings

Everything needed to add a body. The defaults suit one block.

PhysicsBody

Every method is a no-op once the body is destroyed, and reads return zero or the input unchanged. Holders never need to guard against a body that vanished because its level unloaded.

Pose and frames

Motion

State

Sleeping

Jolt puts bodies to sleep when they stop moving, and a sleeping body costs almost nothing. Three things follow from that and catch people out:

1. A sleeping body feels no gravity. A body that falls asleep in mid-air stays there. Zarith uses this on purpose for parked hover ships.
2. addForceAndTorque does nothing on a sleeping body. Wake it with activate() first, or use a method that wakes it (setLinearVelocity, addImpulse and the like).
3. Something has to wake it. Terrain changes near a body wake it, a joint being made or removed wakes both ends, and the controllers wake their body whenever the pilot asks for anything.

Block groups add a rule of their own on top of Jolt’s: a group older than 40 ticks that has crept slower than 0.12 m/s and 0.06 rad/s for 30 ticks in a row is put to sleep, unless it is held, carrying a passenger, bobbing on the swell, or freshly broken off. Without it, a body balanced on an edge can creep for a long time and keep paying for a full step each tick.

Terrain

A space does not copy the world into Jolt. It mirrors only the blocks around its bodies, and keeps them up to date by polling.

How a body’s region is chosen

Each step, every body gets a box of blocks: its bounds plus one block on every side, stretched ahead in the direction it is moving by one step’s travel (at most 12 blocks per axis). If that box would be more than 96 blocks on any axis, it is clamped to 96 around the body’s centre, so a body flung at speed does not mirror a huge slab of terrain. Only the cells entering and leaving the box are touched when it moves, so a big body moving costs only its edges.

Chunks that are not loaded are left out. Zarith never loads a chunk.

How blocks become colliders

• Each block becomes a cell holding its collision boxes, its friction and whether it is soft.
• A full cube with a full cube on all six sides can never be touched, so it gets no boxes. This keeps flat ground and piles cheap. Soft blocks never count as full cubes here, so a block buried only in leaves keeps its collider for bodies falling through them.
• Cells are grouped into 16 by 16 by 16 sections. Each section becomes one static body per surface (a distinct friction and soft pair). Full cubes in a section are greedily merged into big boxes. Per block bodies would leave seams that sliding bodies catch on.
• Terrain boxes have zero convex radius. A rounded edge dips below the face beside it and makes a notch a sliding body can catch on.
• Identical box sizes share one Jolt shape.

How changes are noticed

Every body re-checks the cells in its region by comparing each block’s state with the one it was built from. Awake bodies check every 2 ticks with a budget of 8,192 cells a tick; sleeping bodies every 20 ticks with 2,048. A region bigger than the budget is checked in slices of columns over several ticks. A changed block rebuilds its own cell and its six neighbours (a neighbour may stop being buried), marks its section for a rebuild, and wakes sleeping bodies within 1.5 blocks.

This is why Zarith needs no block change events: breaking the floor under a body, or blowing it up, is noticed within a tick or two by every body standing near it.

Eviction

Cells are reference counted by the bodies whose regions hold them. A cell no body holds is kept for 100 ticks in case a body comes back, then removed. Eviction runs every 20 ticks and only looks at the oldest released cells, so a fast vehicle’s trail costs only what drops off the end.

TerrainSource

TerrainSource is the interface a space reads blocks through. Implement it to run a space against something other than a Minecraft level.

All calls happen on the server thread. LevelTerrain, the Minecraft implementation, caches the last chunk it looked up for the rest of the tick, because the checks walk columns block by block.

Blocks as bodies

com.raiiiden.zarith.physics.BlockBodies (in common) decides how a block state becomes body material.

Terrain uses the same friction rule, so a block slides on ice in the world as well.

Using a space directly

A minimal custom body on the level’s space, driven by your own code. You are responsible for destroying it.

PhysicsSpace space = LevelPhysics.get(level);
if (space == null) return;   // no Jolt on this machine

BodySettings settings = new BodySettings().at(x, y, z);
settings.density = 800f;
PhysicsBody ball = space.createBody(BodyShape.box(0.25f, 0.25f, 0.25f), settings);
ball.setOwner(myEntity);

// each server tick, before LevelPhysics steps the space:
ball.readPose(position, rotation);
ball.activate();
ball.addForceAndTorque(0, liftNewtons, 0, 0, 0, 0);

// when the entity goes:
ball.destroy();

If your object should also be walked on, shot and sheltered under, implement ZarithSolid on its entity. See Solids API.