Server code
Rooms
A room is a running copy of the Luau of a room template: a match, a lobby or a world that players join. A room isn't tied to a server in the panel, it has an id, a template, a region and its players. Every room of the game shows on the Rooms page with its region, its server, its players and the time it has left.
Templates
A template holds:
| Setting | Means |
|---|---|
| Code | Luau with join, leave and message handlers, and start, tick and stop like a loop |
| Tick rate | 1, 2, 4, 8, 16, 32, 64 or 128 ticks a second. Solo goes up to 8, Studio to 32, Live to 128. A room of 128 gets a thread of its own, so other rooms can't push its ticks late |
| Players at most | 1 to 1000 |
| Lifetime | 10 seconds to a day, an hour when nothing is said. A room can be opened with another one |
| Close when empty | Off, or the seconds a room may stay without players |
| Connection | WebSocket, WebTransport, TCP or UDP, with delivery, encryption and key exchange like the settings of a module |
| Matching | How many players a match puts together, and how long the first of them waits at most |
| Players can open rooms | Lets rooms.create of the SDK open rooms of this template |
Publishing keeps a version, new rooms take the live version and open rooms finish with the code they started with.
Code of a room
local scores = {}
ansekai.on("join", function(ctx, player)
scores[player] = 0
ansekai.room.broadcast({ joined = player, map = ansekai.room.data.map })
end)
ansekai.on("message", function(ctx, player, message)
if message.kind == "score" then
scores[player] += 1
ansekai.room.send(player, { score = scores[player] })
end
if scores[player] >= 10 then
ansekai.room.close({ winner = player })
end
end)
ansekai.tick(function(ctx, seconds)
end)| Call | Does |
|---|---|
ansekai.room.id, ansekai.room.data | The id of the room and what it was opened with |
ansekai.room.players() | The players in the room now |
ansekai.room.send(player, message) | Sends a table to one player |
ansekai.room.broadcast(message) | Sends a table to every player |
ansekai.room.kick(player) | Sends a player out, it can join again |
ansekai.room.close(result) | Ends the room after this step, stop runs and the result is kept |
ansekai.room.time() | The clock of the room in seconds since 1970, the SDK knows the same clock |
ansekai.room.ping(player) | Seconds a message takes to the player and back, nil before the first ping came back |
ansekai.history | The last second of hit shapes, see Lag compensation |
ansekai.room.state.set(key, value) | Writes a value of the state that every player sees, nil removes it |
ansekai.room.state.get(key), .delete(key), .keys(prefix) | Reads, removes and lists the keys of the state |
State of the room
The state is a map of keys to values that the code writes and every player of the room sees. After each step the room sends every player only what changed since the state it has: a player that joins gets the whole state, after that only the keys that changed.
ansekai.on("join", function(ctx, player)
ansekai.room.state.set("players/" .. player, { hp = 100, at = vector.create(0, 0, 0) })
end)
ansekai.tick(function(ctx, seconds)
for id, body in bodies do
ansekai.room.state.set("players/" .. id, { hp = body.hp, at = body.position })
end
end)A value is nil, a boolean, a number, text, a vector or a table of them. Writing the same value again sends nothing. A key is 200 characters at most, a value 16 KB, and the state holds 10000 keys and 2 MB.
The binary format
The SDK talks to rooms in a binary format unless JSON is asked for. It is smaller than JSON: whole numbers are varints, a vector is twelve bytes, and a key of the state travels as text only the first time, after that as a small number. Messages can carry vectors in it, the code gets them as tables with x, y and z. Players of JSON and of the binary format can be in the same room.
WebTransport
WebTransport is UDP for browsers: HTTP/3 over QUIC with the certificate of the HTTPS port. A template with WebTransport lets a browser talk to its room like a game in Node does with UDP. What must arrive, like the replies and the messages of the code, goes on a stream. The state and the pings go as datagrams: a lost one is never sent again as it was, the next change carries everything the player is missing, so a late packet never holds back a newer one. room.input goes as a datagram too and may get lost, an input of every frame is sent again with the next frame anyway.
Where UDP is blocked, the SDK joins with the WebSocket after a few seconds. Node has no WebTransport and takes the WebSocket too.
ctx.room is the id of the room, ctx.tick and ctx.rate are like in a loop. A room reaches Player Data, the Realtime Database, the Cache and Storage like any other code.
Opening rooms
Plugins, loops and rooms open rooms and send players to them:
ansekai.rpc("play", function(ctx)
local room = ansekai.rooms.create("arena", { players = { ctx.player }, lifetime = 600, data = { map = "docks" } })
return { room = room }
end)| Call | Does |
|---|---|
ansekai.rooms.create(template, options) | Opens a room and gives its id. Options: players (only they can join), lifetime in seconds, data, region (one the game picked, the first one without it) |
ansekai.rooms.add(room, player) | Sends one more player to an open room |
ansekai.rooms.close(room, result) | Ends an open room |
ansekai.rooms.list() | The open rooms of the game |
A room opened without players lets every player of the game in. The panel opens rooms from a template too and closes them by hand. A template with "Players can open rooms" lets the SDK open them with rooms.create(template, { region }), others find them with rooms.list.
Regions
The Settings page of a game picks the regions its rooms open in. Solo picks 1, Studio 3, Live 10. Without a pick rooms stay in the region of the game. A room in a region that isn't picked is refused, from the panel, from Luau, by matching and by players alike.
A room in another region runs on a server of that region, the one with the fewest rooms of the game. The game and its record stay on its home:
- The code of the room reaches Player Data, the Realtime Database, the Cache and Storage of the game through the home. Each of these calls commits on its own there, a step of a room on another server is not one transaction.
- The server of the room tells the home every second about its players, its use and its logs, the bill counts it on the home.
- A room whose server stays quiet for 30 seconds is closed on the home.
- Members sign these calls with the key of the network.
Matching
const info = await ansekai.rooms.match("duel"); // Waits in the closest region of the game
const room = await ansekai.rooms.join(info.id);Players wait in a line for each template and region on the home of the game. A room opens for them when the line has as many players as the template says, or with whoever waits when the first of them waited long enough. The SDK times a ping to a server of each region of the game and waits in the fastest, { region } picks one. A game that wants its own matching still writes it in Luau with ansekai.rooms.create and ansekai.rooms.add.
Ending
A room ends when its code calls ansekai.room.close, when it stayed empty for the seconds of its template, when its lifetime is up, from the panel, or with ansekai.rooms.close. Its players hear room.closed with the reason and the result, the record keeps both.
Clients
A player joins with a ticket that rooms.join gives, it lives a minute and works once. A room on another server gives the ticket there, the answer has its address in url. With a WebSocket the ticket goes to /api/socket?ticket=. For TCP and UDP the client gets a session key for the ticket over TLS from /api/rooms/link, then talks the Self protocol like the modules do. Messages are hello first, then message with data, and leave.
Billing
A room is paid like a loop: the memory it holds by the minute, the CPU time of its code and its ticks. Events of players cost CPU time and are not counted as ticks.
Updated November 21, 2026