Ansekai DocsAnsekai docs
All pages
Connections and security
Examples

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.

Luau
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

CallDoes
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

CallDoes
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:

Luau
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)
3D2D
addBox({ size }) with three sidesaddBox({ 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 anglesangle and body:angle() as one angle in radians, body:setAngle(angle)
body:spin() is a vectorbody: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

Physics · Ansekai Docs