Ansekai DocsAnsekai docs
All pages
Connections and security
Examples

SDK

Web SDK

@ansekai/web

Ansekai SDK for browser games and Node. It has no dependencies.

TypeScript
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 onHTTPTCPUDP
BrowserYesNoNo
NodeYesYesYes

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

CallDoes
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.expiresAtWhen the session ends, null if it never ends
auth.currentPlayerThe 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.

TypeScript
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);
CallDoes
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.

TypeScript
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 });
CallDoes
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:

TypeScript
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 });
CallDoes
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.stateA 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.pingThe 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

Web SDK · Ansekai Docs