SDK
Web SDK
@ansekai/web
Ansekai SDK for browser games and Node. It has no dependencies.
import { createClient, AnsekaiError } from "@ansekai/web";
const ansekai = createClient({
url: "https://your-server",
gameKey: "key from the SDK page of the panel",
});
ansekai.auth.onChange((player) => {
console.log(player ? `Signed in as ${player.email}` : "Signed out");
});
try {
await ansekai.auth.register("player@example.com", "a good password");
} catch (error) {
if (error instanceof AnsekaiError && error.code === "email_taken") {
await ansekai.auth.login("player@example.com", "a good password");
}
}The Auth module of the game must have the email and password method on.
url is the address of your site. When the game lives on another server of the network, the client asks once where, remembers it on the device and talks to that server from then on.
Connections
Every module answers on every connection. A client starts on HTTP, and when the server says that a module wants WebSocket, TCP or UDP the next calls move there by themselves. ansekai.protocol is the connection in use, ansekai.preferredProtocol is the one the module asked for.
| Runs on | HTTP | TCP | UDP |
|---|---|---|---|
| Browser | Yes | No | No |
| Node | Yes | Yes | Yes |
A browser can't open TCP or UDP sockets, so it stays on HTTP or moves to WebSocket. realtime.subscribe always keeps a connection open, it uses the one the module wants and WebSocket if that one is HTTP or out of reach. It reconnects by itself and only asks for what it missed. Node needs an https url, keys only leave over TLS. A game with AES-GCM-SIV or ML-KEM stays on HTTP in Node too, for now. A failed move never breaks a call, the client keeps the connection it has. In Node, call ansekai.close() when you are done. A plugin with its own settings in the panel gets its own connection the same way, the first call of its function tells the client where it goes.
Auth
| Call | Does |
|---|---|
auth.register(email, password) | Creates a player and signs them in |
auth.login(email, password) | Signs a player in |
auth.guest() | Starts a player without an account, the game must have guests on in the panel. The player has guest: true and no email |
auth.upgrade(email, password) | Gives the guest of this device an email and a password, it keeps its id, its saves and its session. Needs email and password on too |
auth.logout() | Signs out, the device forgets the player even if the server can't be reached |
auth.me() | Asks the server who is signed in, it throws token_expired when the session is over |
auth.expiresAt | When the session ends, null if it never ends |
auth.currentPlayer | The player of this device, without asking the server |
auth.onChange(listener) | Calls the listener now and on every change, the result stops it |
data.get(key) | Reads a key, null if it isn't there. { playerId } reads a public key of another player |
data.list() | Reads every key of the player. { playerId } reads the public keys of another player |
data.set(key, value) | Saves any JSON value. { version } refuses the write if the key changed, version: 0 only creates |
data.delete(key) | Deletes a key, it takes { version } too |
data.increment(key, by) | Adds to a number in one step, two devices can't lose each other's change |
realtime.get(path) | Reads a value that the whole game shares, null if it isn't there |
realtime.list(path) | Reads the values at and under a path, { after, limit } gives the next page |
realtime.subscribe(path, listener) | Calls the listener with what is there now and with every change at and under the path, the result stops it |
realtime.set(path, value) | Saves a value on a shared path, it takes { version } like data.set |
realtime.delete(path) | Deletes a value on a shared path |
plugins.call(name, params) | Runs a function of a plugin on the server, ansekai.fail("code") arrives as an error with that code |
Storage
Every file gets an id when it is uploaded, and every other call reaches it by that id. The id never changes, replace puts new bytes under it and move puts the file in another folder. Folders only help people find files, a folder exists while a file is inside it. Keep it in Player Data or the Realtime Database to find the file again.
const file = await ansekai.storage.upload(blob, { name: "avatar.png", access: "public" });
await ansekai.data.set("avatar", file.id);
const bytes = await ansekai.storage.download(file.id);
image.src = ansekai.storage.publicUrl(file.id);| Call | Does |
|---|---|
storage.upload(body, { name, access, folder, contentType }) | Saves a Blob, ArrayBuffer, typed array or string as a new file of the player and gives it with its id, folder is a path like levels/forest |
storage.replace(id, body) | Puts new bytes under the same id, { name } renames it too |
storage.download(id) | Reads the bytes as a Uint8Array, { range: { offset, length } } reads a part |
storage.text(id) | Reads a file as text |
storage.info(id) | Reads the name, size, type and access of a file, null if it isn't there |
storage.list() | The files of the player from the newest in every folder. { folder } opens one folder and gives the folders right under it too, "" is the root. { playerId } shows what another player shares, { after, limit } gives the next page |
storage.update(id, { name, access, folder }) | Renames a file, changes who reads it or moves it |
storage.move(id, folder) | Moves a file to another folder, the id stays |
storage.delete(id) | Deletes a file |
storage.url(id, { expiresIn }) | A link that works without a key for expiresIn seconds, one hour by default and a week at most |
storage.publicUrl(id) | The link of a public file, it never expires |
Access is private for only its player, players for every signed in player and public for anyone with the game key. The bytes follow the connection of the storage module like its other calls: on a WebSocket every file takes a WebSocket of its own, on WebTransport a stream of its own in the session, so a big file never holds the calls up. On HTTP they go over HTTP, and so does the first file of a new client, its answer moves the next ones. The Files tab of the panel can send them on another road than the calls. Storage takes no TCP or UDP. A road that breaks hands the file to HTTP. Uploads and downloads have no timeout, pass { signal } to stop one.
Cache
Fast values that don't have to last, a restart of the server empties the cache. Every key picks a tier: memory, the default, is the fastest and small, disk keeps more and counts against the cloud saves.
await ansekai.cache.set("lobby", { players: 3 }, { ttl: 60 });
await ansekai.cache.set("level", bigLevel, { tier: "disk", ttl: 3600 });
const lobby = await ansekai.cache.get("lobby");
const leader = await ansekai.cache.get("leader", { shared: true });| Call | Does |
|---|---|
cache.get(key) | Reads a key of the player, null if it isn't there or ran out. { shared: true } reads a key of the whole game, only server code writes those |
cache.set(key, value, { tier, ttl }) | Keeps a value, ttl is in seconds, 30 days at most, without it the key stays until the cache needs the room |
cache.setIfAbsent(key, value, options) | Keeps a value only if the key isn't there, false when someone was first |
cache.delete(key) | Deletes a key, false if it wasn't there |
cache.increment(key, by, options) | Adds to a number in one step, a missing key starts from zero, the options only count for a new key |
A full cache throws cache_full. Plugins and loops reach it as ansekai.cache with the same calls, { player = id } in the options or a player id as the last argument of get and delete names a key of a player.
Rooms
A room runs the Luau of a template on the server for a match, a lobby or a world, players join it and talk to its code. Matching puts waiting players into rooms, server code opens rooms with ansekai.rooms.create and sends players to them:
const info = await ansekai.rooms.match("duel");
const room = await ansekai.rooms.join(info.id);
room.on("message", (message) => draw(message));
room.on("closed", ({ reason, result }) => showResult(reason, result));
await room.send({ kind: "move", x: 3, y: 4 });| Call | Does |
|---|---|
rooms.match(template, { region }) | Waits in line in the closest region of the game, or the one given, and gives the room matching opened |
rooms.cancel() | Leaves the line |
rooms.create(template, { region, data }) | Opens a room when the template lets players do so |
rooms.list({ template, region }) | Open rooms the player can join |
rooms.regions(), rooms.nearestRegion() | The regions rooms of the game open in, and the one whose server answers this device the fastest |
rooms.current() | The newest open room that code, matching or the player sent the player to, null if there is none |
rooms.onAssigned(listener) | Calls the listener when code sends the player to a room, the result stops it |
rooms.join(id, { format }) | Joins an open room and opens its connection, the room hears join. The format is binary unless json is given |
room.send(message) | Sends anything JSON can hold and a Vector3, the room hears it in ansekai.on("message") and the promise waits for the room to take it |
room.input(message) | The same without waiting, for the inputs of every frame |
room.state | A Map of what the code wrote with ansekai.room.state, it changes by itself |
room.on(name, listener) | message, state (what changed: set, removed, full and time), closed (with its reason and result), kicked and lost |
room.serverTime(), room.renderTime(), room.ping | The clock of the room, the moment others are drawn at, and the ping in seconds, see Lag compensation |
room.leave() | Leaves the room, the room hears leave |
A room can run on a server of another region than the game, rooms.join connects there by itself.
The template picks the connection like the settings of a module: WebSocket, WebTransport, TCP or UDP with its delivery, encryption and key exchange. Node takes TCP or UDP when the template asks for it. A browser takes WebTransport when the template asks for it and the WebSocket otherwise, or when UDP is blocked. room.protocol tells which one a room uses.
Errors
Everything throws AnsekaiError with code, status, retryAfter in seconds and a message for people.
Example
examples/basic-site is a small site with sign in, sign up and sign out, npm run example starts it.
Tests
npm test runs without a server. ANSEKAI_URL and ANSEKAI_KEY add a run against a real one. test/move.mjs follows the connection setting of a real game.
Updated November 21, 2026