Ansekai DocsAnsekai docs
All pages
Connections and security
Examples

SDK

Native SDK

The SDK for games in C and C++, and for any engine that can call C: Unity through P/Invoke, Unreal as a plugin, Godot as a GDExtension, or an engine of your own. It lives in SDKs/native and shows one header, include/ansekai/ansekai.h.

It runs on Windows, macOS, Linux, Android and iOS and reaches every connection a module can take: HTTP, WebSocket, WebTransport, TCP and UDP. TLS is built in with the Mozilla roots, so nothing has to be installed, and every TLS connection offers X25519MLKEM768 first, a key exchange a quantum computer can't break later. Turn on Native SDK on the SDK page of the game when it ships it.

Use

C
#include <ansekai/ansekai.h>

static void signed_in(void *user, const ansekai_result *result)
{
    if (result->error) {
        printf("login failed: %s\n", result->error); /* like "invalid_credentials" or "network_error" */
        return;
    }

    printf("signed in: %s\n", result->body);
}

ansekai_options options;
ansekai_options_init(&options);
options.url = "https://play.example.com";
options.game_key = "key from the SDK page of the panel";
options.storage_path = "<a folder of the game>/ansekai.json";

ansekai_client *client = ansekai_create(&options);

ansekai_login(client, "player@example.com", "a good password", signed_in, NULL);
ansekai_call(client, "data.set", "{\"key\":\"level\",\"value\":3}", NULL, NULL);

/* Every frame, on the main thread */
ansekai_poll(client);

/* When the game closes */
ansekai_destroy(client);

Calls never block. Each one returns a request id and the network work happens on threads of the SDK, threads of them, 3 by default. The callbacks run inside ansekai_poll, on the thread that calls it, so an engine calls it once a frame on its main thread and touches its scene from the callbacks safely. The strings of a result live until the callback returns, copy what you keep.

ansekai_call reaches every method of the protocol with its JSON parameters. Auth has its own functions too because the session belongs to the core: it is saved in storage_path and read back on the next run, the token goes with every call, and a session the server ended is gone from the device. Without storage_path the session lives in memory until the client is destroyed.

When the player changes

C
static void session_changed(void *user, const ansekai_session_change *change)
{
    if (change->reason == ANSEKAI_SESSION_ENDED) {
        /* change->error is "not_signed_in" or "token_expired", show the login screen */
    }
}

ansekai_on_session(client, session_changed, NULL);

The game hears a sign in, a logout, an upgrade of a guest and a session the server ended, through ansekai_poll like everything else. change->player is the player after the change, NULL when nobody is signed in.

Hearing changes

C
static void changed(void *user, const ansekai_change *change)
{
    printf("%s is now %s\n", change->path, change->deleted ? "gone" : change->value);
}

uint64_t rooms = ansekai_subscribe(client, "rooms", changed, NULL);
/* ... */
ansekai_unsubscribe(client, rooms);

What is at the path comes first, then every change at and under it. The client keeps a WebSocket open while anything is heard, opens it again after a drop, finds what it missed with a ping every 20 seconds and drops a change it already saw. Changes come through ansekai_poll like answers.

A module whose settings ask for a WebSocket moves there by itself: its first call goes over HTTP, the server names the socket and the next calls take it.

Rooms

C
static void in_room(void *user, const ansekai_room_event *event)
{
    if (event->type == ANSEKAI_ROOM_STATE) {
        /* event->data is what changed, ansekai_room_state gives everything */
    }
}

static void matched(void *user, const ansekai_result *result)
{
    /* result->body is the room, its "id" goes to ansekai_join */
    *(uint64_t *)user = ansekai_join(client, "<id of the room>", 1, in_room, NULL);
}

ansekai_match(client, "duel", NULL, matched, &room);

/* Every frame */
ansekai_room_input(client, room, "{\"move\":{\"$v\":[0,0,1]},\"at\":12.5}");
double now = ansekai_room_time(client, room);

ansekai_match waits in line until matching opens a room, a NULL region takes the closest one, ansekai_cancel_match stops waiting. A match holds one of the threads of the client while it waits. ansekai_join returns a handle at once, the room says ANSEKAI_ROOM_JOINED or ANSEKAI_ROOM_FAILED through ansekai_poll, then its messages, state changes and how it ended.

The binary format is smaller and carries vectors, the JSON one is easier to read. A vector is {"$v": [x, y, z]} in every JSON the SDK takes and gives. ansekai_room_time is the clock of the room, the same as ansekai.room.time() in its code, learned from its pings: draw others a little behind it and send that moment with a shot, the room rewinds to it. ansekai_room_ping is the round trip in seconds.

A room whose template asks for TCP, UDP or WebTransport is joined over it when the server is https, a network that blocks it falls back to the WebSocket every room has. WebTransport carries only the binary format, a room joined in JSON takes the WebSocket. ansekai_room_protocol says which one a room uses.

ansekai_destroy drops calls that are still waiting. A call already on the network finishes first, it waits at most timeout_ms.

Drawing others smoothly

C
ansekai_timeline *enemy = ansekai_timeline_create(4, 1.0); /* x, y, z and the turn */

/* In ANSEKAI_ROOM_STATE, with the "time" of the change */
double at[4] = {x, y, z, yaw};
ansekai_timeline_push(enemy, time, at);

/* Every frame */
double now[4];
double moment = ansekai_room_render_time(client, room, 0);

if (ansekai_timeline_sample(enemy, moment, 1u << 3, now)) {
    /* draw the enemy at now[0], now[1], now[2] turned by now[3], the bit says the fourth number is an angle */
}

/* A shot goes with the same moment, the room checks it against what the player saw */

ansekai_room_render_time is the clock of the room a tenth of a second back, or the delay it gets. A timeline keeps a second of snapshots of numbers and blends the two around a moment, an angle turns the short way around. It belongs to the thread that uses it.

Sent to a room

C
static void assigned(void *user, const char *room)
{
    /* room is the JSON of the room code sent this player to, join it with its "id" */
}

ansekai_on_assigned(client, assigned, NULL);

Code of the game can put a player in a room, like a plugin that calls ansekai.rooms.create with the player in it or matching that found a room. The client asks every 2 seconds through ansekai_poll while a listener is set.

Stopping a call

Every call returns an id, ansekai_cancel stops it and its callback runs with aborted. A call that still waits in line never goes out. One already on the network may have run on the server, only its answer is dropped. An upload, a download and a wait in line stop for real.

Files

C
static void uploaded(void *user, const ansekai_result *result)
{
    /* result->body is {"file":{"id":...}}, keep the id to reach the file again */
}

uint64_t upload = ansekai_upload_file(client, "saves/slot1.bin", "{\"folder\":\"saves\"}", uploaded, NULL);

/* Every frame while it runs */
uint64_t done, total;
if (ansekai_transfer_progress(client, upload, &done, &total)) {
    /* draw done of total */
}

ansekai_download_file(client, "<id of the file>", "saves/slot1.bin", downloaded, NULL);
ansekai_download(client, "<id of the file>", 0, 0, in_memory, NULL); /* result->body and result->body_size hold the bytes */

ansekai_upload_file and ansekai_download_file move a file a piece at a time, a file of any size never sits whole in memory. A download goes to path.part and takes its name only when every byte came. One the network broke or the game stopped keeps path.part with the etag of the file in path.part.etag, and the next download of that file to that path goes on where it stopped, a file that changed meanwhile starts again. ansekai_upload saves bytes of memory, ansekai_download reads a file or a part of it into memory with an offset and a length. Options of an upload are JSON: name, access (private, players or public), folder and contentType, or id to put new bytes under a file that keeps its id. ansekai_cancel stops one, it ends with aborted.

The bytes follow the connection of the storage module. On a WebSocket every file takes a WebSocket of its own, on WebTransport a stream of its own in the session, each with the flow control of TCP or QUIC, so a big file never holds the calls up. On HTTP the bytes go over HTTPS, and so does the first file before a call of storage named the road, its answer moves the next ones. The Files tab of the panel can send them on another road than the calls, WebTransport then takes a session of its own for files. Storage takes no TCP or UDP. A road that breaks hands the file to HTTPS from its first byte. HTTP stays open for the bytes under Only this connection: a download picks up in the middle, a CDN can keep it and a signed link works without headers. Every other call of storage, storage.list, storage.info, storage.update, storage.delete and storage.url, goes through ansekai_call on the connection of the module.

Where the session file goes

PlatformFolder
UnityApplication.persistentDataPath
UnrealFPaths::ProjectSavedDir()
GodotOS.get_user_data_dir()
AndroidContext.getFilesDir()
iOS and macOSApplication Support of the app
Windows%LOCALAPPDATA%\<game>
Linux$XDG_DATA_HOME/<game>

A server on your machine

A server with a certificate it made itself is trusted with ca_pem, the certificate in PEM. insecure_tls = 1 skips the check entirely, never ship a game with it.

Build

Shell
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

That gives a shared library: libansekai.so, libansekai.dylib or ansekai.dll. Only the ansekai_* functions leave it, the Mbed TLS inside never meets the one of an engine like Godot. -DANSEKAI_SHARED=OFF builds a static library.

PlatformConfigure
Windowscmake -S . -B build -G "Visual Studio 17 2022" -A x64
macOScmake -S . -B build -G Ninja -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
Androidcmake -S . -B build -G Ninja -DCMAKE_TOOLCHAIN_FILE=$ANDROID_NDK/build/cmake/android.toolchain.cmake -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=24
iOScmake -S . -B build -G Xcode -DCMAKE_SYSTEM_NAME=iOS -DANSEKAI_SHARED=OFF -DANSEKAI_EXAMPLES=OFF

Updated November 21, 2026

Native SDK · Ansekai Docs