Server code
Physics
Loops and plugins have Jolt Physics as ansekai.physics. A loop keeps a world at its top and steps it in the tick, so the world lives as long as the loop. A plugin can simulate a few seconds inside one run and answer with the result.
local world = ansekai.physics.world({ maxBodies = 256 })
local ground = world:addBox({ size = vector.create(50, 1, 50), position = vector.create(0, -0.5, 0), motion = "static" })
local ball = world:addSphere({ radius = 0.5, position = vector.create(0, 5, 0), restitution = 0.4 })
local goal = world:addBox({ size = vector.create(4, 2, 1), position = vector.create(0, 1, 20), motion = "static", sensor = true })
ansekai.tick(function(ctx, seconds)
world:step(seconds)
for _, pair in world:contacts() do
if pair.a == goal or pair.b == goal then
ansekai.realtime.set("match/goal", true)
end
end
ansekai.realtime.set("match/ball", { x = ball:position().x, y = ball:position().y, z = ball:position().z })
end)Vectors are the vectors of Luau (vector.create(x, y, z)). A table with x, y and z, or with three numbers, works too. Answers are always vectors. Rotations are angles in radians around x, y and z.
World
| Call | Does |
|---|---|
ansekai.physics.world({ gravity, maxBodies }) | A new world, gravity is (0, -9.81, 0) and room is for 1024 bodies by default, 4096 at most |
world:addBox({ size, ... }) | A box, size is the whole box, 1 meter on every side by default |
world:addSphere({ radius, ... }) | A sphere, half a meter by default |
world:addCapsule({ radius, height, ... }) | A capsule standing up, height is its straight part |
world:step(seconds) | Moves time on, a long step is cut into collision steps of 1/60 second, 4 at most, and to 0.25 seconds |
world:raycast(from, to) | The first body on the line: { body, point, normal, fraction }, nil when nothing is there |
world:contacts() | The pairs { a, b } that started touching in the last step, a sensor too |
world:body(id) | The body with this id, nil when it was removed |
world:bodyCount() | How many bodies the world has |
Every shape takes these options too: position, rotation, motion ("dynamic" falls and gets pushed, "static" never moves, "kinematic" only moves where the code sends it), mass in kilograms, friction (0.2), restitution (0 to 1, how much it bounces), sensor (it notices contacts and stops nothing) and velocity.
Body
| Call | Does |
|---|---|
body:id() | A number that finds the body again with world:body(id), keep it in your own tables |
body:position(), body:rotation() | Where it is and how it is turned |
body:velocity(), body:spin() | How fast it moves and turns |
body:active() | False while it sleeps, a body that stops moving sleeps until something touches it |
body:setPosition(v), body:setRotation(v) | Puts it somewhere at once |
body:setVelocity(v), body:setSpin(v) | Sets how fast it moves or turns |
body:addForce(v) | Pushes it during the next step |
body:addImpulse(v) | Kicks it at once |
body:moveTo(position, seconds) | A kinematic body gets there in the next step and pushes what is in the way |
body:remove() | Takes it out of the world, its id stops working |
body:valid() | False once it was removed |
Two handles of the same body are equal with ==, even when they came from different calls.
2D
Box2D 3.1 is there as ansekai.physics2d for platformers, top down games and anything flat. It works like the 3D world, with these differences:
local world = ansekai.physics2d.world({ gravity = vector.create(0, -9.81, 0) })
world:addBox({ size = { 40, 1 }, position = { 0, -0.5 }, motion = "static" })
local hero = world:addCapsule({ radius = 0.4, length = 1, position = { 0, 3 }, fixedRotation = true })
ansekai.tick(function(ctx, seconds)
world:step(seconds)
end)| 3D | 2D |
|---|---|
addBox({ size }) with three sides | addBox({ size }) with a width and a height |
addSphere({ radius }) | addCircle({ radius }) |
addCapsule({ radius, height }) | addCapsule({ radius, length }), standing up |
rotation and body:rotation() as three angles | angle and body:angle() as one angle in radians, body:setAngle(angle) |
body:spin() is a vector | body:spin() is a number, radians in a second |
Vectors are the same vectors of Luau with z left out, or tables with x and y or two numbers. Bodies take fixedRotation, so a character never falls over, and bullet for fast things that must not pass through thin walls. Everything else is the same: motion, mass, friction (0.6 here), restitution, sensor, velocity, step, raycast, contacts, body(id), bodyCount, moveTo, remove. A step runs 4 sub-steps.
Limits
- A machine has 4 worlds at most, 2D and 3D together. A world has room for 4096 bodies at most.
- Box2D keeps the 2D worlds of the whole server in one table of 1024, a server that is full says
this server has no room for another 2D world now. - The memory of Jolt counts against the memory of the loop (16 MB) or the plugin (8 MB), together with the memory of Luau. A world that would pass it stops with
physics ran out of memory. The usage page shows it as the memory of loops, it is billed like the rest of it. - The time of a step counts as code time, against the tick budget and the loop budget of the plan, like any other code.
- Sizes and places are between -10000 and 10000 meters.
- Mistakes are errors the code can catch with
pcall: an unknown motion, a size of zero, a full world, a removed body.
How it runs
Jolt 5.3 and Box2D 3.1 are built into the server, both hand their memory to the same counter. Every world runs on the thread of its loop with a job system of one thread, so a step never takes cores from other games. Jolt asks the server for memory through a hook that remembers which loop asked, so the memory of a world is counted for its loop and freed with it.
It is built with SSE4.2 and nothing newer, so the server runs on any x86-64 machine of the last decade, and in cross platform deterministic mode: the same steps give the same result on every server.
Bodies sink up to two centimeters into each other, that is how Jolt keeps stacks steady. A ball of radius 0.5 rests at about 0.48.
Updated November 21, 2026