Developer docs

Installing

Script tag — no bundler needed. The platform (and neko dev) serves the SDK at /__neko/sdk.js, the one absolute path that works in a game:

<script src="/__neko/sdk.js"></script>
<script>
  const { sdk, NekoSdkError } = window.Nekoland;
</script>

npm — with a bundler:

npm i @launchercapital/nekoland-sdk

import { NekoSDK, NekoSdkError } from "@launchercapital/nekoland-sdk";

const sdk = new NekoSDK();

Unity and Godot have their own wrappers — see Unity & Godot.

Init & lifecycle

// Await init before payments, storage or player (otherwise NOT_INITIALIZED).
// on() and track() are fine earlier. init also closes the platform loading screen.
const player = await sdk.init({ gameId: "gem-rush" }); // the gameId in nekogame.json

sdk.on("pause", () => { /* stop the loop and mute */ });
sdk.on("resume", () => { /* restore sound */ });
sdk.on("player.changed", () => { /* signed in or switched account → reload the save */ });

• init(options) resolves with the player. Options: gameId (required), manualReady, mode ("auto" | "platform" | "local"), local (see Local testing), timeoutMs (default 10,000) and extraHostOrigins (local development only).
• pause fires when the tab is hidden, the app goes to the background or a purchase dialog opens — stop the loop and mute. resume fires when it's back.
• player.changed fires when a guest signs in or the account changes. Reload the save; playerId may be different.
• on() returns an unsubscribe function and is safe to call before init.

Long loads

By default the platform loading screen closes as soon as init finishes. For big games (Unity etc.) keep it up and drive its progress bar:

await sdk.init({ gameId: "gem-rush", manualReady: true });

for (let i = 0; i < assets.length; i++) {
  await load(assets[i]);
  sdk.loadingProgress((i + 1) / assets.length); // 0..1
}
await sdk.gameReady(); // first screen is up → the loading screen closes

The platform closes the loading screen after 60 seconds regardless.

Play time

sdk.gameplayStart(); // leaving the menu, unpausing
sdk.gameplayStop();  // menu, pause, game over

Optional, for accurate play-time metrics. If you never call them, all time the game is visible counts as play. Both are safe before init.

Platform menu and screen edges

// Keep the HUD out of the platform menu button (top-left)
layoutHud(sdk.insets.menu); // { x, y, width, height } or null
sdk.on("insets.changed", (i) => layoutHud(i.menu));

// Esc / the menu button pauses the game (pause + menu.open)
sdk.on("menu.open", () => showPausedOverlay());
sdk.on("menu.close", () => hidePausedOverlay());

// Need Esc yourself? Turn it off and open the menu from your pause screen
await sdk.init({ gameId: "my-game", escapeMenu: false });
pauseScreen.onMenuClick = () => sdk.openMenu();

• The platform menu button (exit, friends, report, help) sits at the top-left of the game. Its area is sdk.insets.menu ({ x, y, width, height } in CSS px); insets.changed fires when the screen rotates. Keep HUD buttons out of it.
• The phone's safe area (notch, home indicator) is sdk.insets.safeArea ({ top, right, bottom, left }, CSS px from each edge). CSS env(safe-area-inset-*) is 0 inside the game iframe, so use this. Keep HUD and text inside it; the background may extend to the edges.
• Esc opens the menu: the game gets menu.open and pause, then menu.close and resume when it closes. If your game needs Esc, pass init({ gameId, escapeMenu: false }) and call sdk.openMenu() from your own pause screen.

Player & login

const { playerId, displayName, avatarUrl, isGuest, locale } = sdk.player;

if (sdk.player.isGuest) {
  try {
    await sdk.login(); // platform login / sign-up dialog
  } catch {
    // the player stayed a guest
  }
}

• sdk.player: playerId (stable per game, different in every game), displayName, avatarUrl (absolute profile photo URL, missing if none — CORS-enabled so you can draw it on a canvas), isGuest, locale (e.g. en-US).
• sdk.login() asks a guest to log in or sign up and resolves with the member (immediately if already a member); it rejects if they decline. Guests keep their cloud save when they sign up.
• sdk.platform: "web" (browser), "ios" or "android" (the Nekoland app). sdk.device: "mobile" (phone or tablet, touch) or "desktop" (computer). Use it for touch buttons and UI size; accept touch, mouse and keyboard either way.
• Languages: pick strings by the language of sdk.player.locale (e.g. en-US → en) and fall back to the default language when it isn't supported. List supported languages in languages in nekogame.json.
• sdk.sandbox is true in a pre-approval preview and in local mode (purchases are test purchases). sdk.isLocal is true in local test mode. Behave the same either way.

Payments

Declare every product in nekogame.json first — neko dev and the platform only sell products listed there. Then follow this grant → save → consume pattern so a purchase is never lost or granted twice:

const CONSUMABLES = new Set(["gems_500"]); // purchases don't carry the type
const owned = new Set();                   // permanent products

async function grant(p) {
  if (!CONSUMABLES.has(p.productId)) { owned.add(p.productId); return; } // permanent: unlock, never consume
  if (p.state !== "completed") return;                                   // already consumed
  if (!save.grantedIds.includes(p.purchaseId)) {
    save.gems += 500;
    save.grantedIds = [...save.grantedIds, p.purchaseId].slice(-50);
    await sdk.storage.set({ save: JSON.stringify(save) });               // ① save the grant
  }
  await sdk.payments.consume(p.purchaseId);                              // ② then consume
}

// On every start: anything paid for but not granted yet
for (const p of await sdk.payments.getPurchases()) await grant(p);

// Buy button
try {
  await grant(await sdk.payments.purchase({ productId: "gems_500" }));
} catch (e) {
  if (e instanceof NekoSdkError && e.code === "USER_CANCELLED") return;
  // NOT_LOGGED_IN · INSUFFICIENT_COINS · ALREADY_OWNED · PURCHASE_PENDING · PRICE_CHANGED · INVALID_PRICE · PRODUCT_NOT_FOUND · TIMEOUT
}

• purchase({ productId, developerPayload? }) shows the platform's confirm, top-up and sign-in dialogs outside the iframe. Never draw your own confirm dialog; guests are asked to sign in automatically. developerPayload comes back unchanged on the purchase and receipt.
• getPurchases() returns consumables not yet consumed and every permanent product the player owns. Call it on every start to restore ownership.
• consume(purchaseId) marks a consumable as granted. Until you call it, it keeps showing up in getPurchases(). Don't consume non-consumables.
• A purchase is { purchaseId, productId, state, purchasedAt, developerPayload?, signedReceipt }; state is completed, consumed or refunded.
• An item used at once (e.g. "Revive"): grant it as above (count +1, save, consume), then spend it from your own count (−1, save).

For your shop UI, read titles and prices from the platform:

const products = await sdk.payments.getProducts(); // or getProducts(["gems_500"])
// [{ productId, type, title, description, priceCoins, variablePrice?, iconUrl? }]

Cloud saves

// Values are strings, so store JSON
const raw = (await sdk.storage.get(["save"])).save; // missing keys → null
const save = raw ? JSON.parse(raw) : { gems: 0, grantedIds: [] };

save.gems += 10;
await sdk.storage.set({ save: JSON.stringify(save) }); // merged with existing keys

• Values are strings — store JSON. get(keys) returns null for missing keys; set(entries) merges with existing keys.
• 1MB per game and player. Going over rejects with INVALID_ARGUMENT.
• Use sdk.storage, not localStorage — it follows the player across devices, and guests keep it when they sign up. Previews keep their storage separate from the live game.

Friends & invites

Friends live on the player's Nekoland account. Friend requests, 1:1 chat and online status are handled by the platform, outside your game. The game only sees friends as playerIds of this game (new in SDK 0.6.0).

// [{ playerId, displayName, avatarUrl?, online, inGame, hasPlayed }] — empty for guests
const friends = await sdk.friends.list();
const playingNow = friends.filter((f) => f.inGame);

// Platform friend picker → invite card in each chosen friend's Nekoland chat
try {
  const { sent } = await sdk.friends.invite({ data: roomCode }); // data: up to 500 characters
} catch (e) {
  // USER_CANCELLED: picker closed · NOT_LOGGED_IN: a guest declined to log in
}

// Friend request to a player you just played with (platform asks to confirm)
const { status } = await sdk.friends.add(otherPlayerId); // "sent" (waiting for them) or "friends"

// Opened from a friend's invite?
if (sdk.invite) {
  const { fromPlayerId, fromName, data } = sdk.invite; // data is null when none was sent
  joinRoom(data);
}

• friends.list() → [{ playerId, displayName, avatarUrl?, online, inGame, hasPlayed }]. online: on Nekoland right now (false when the friend hides their status — status is shown by default); inGame: playing this game now; hasPlayed: has opened this game before. Empty for guests.
• friends.invite({ data? }) opens the platform's friend picker. Each chosen friend gets an invite card in their Nekoland chat that opens your game. Resolves with { sent }. Guests are asked to log in first (NOT_LOGGED_IN if they decline); USER_CANCELLED if the picker is closed.
• friends.add(playerId) sends a friend request to another player of this game. The platform shows its own confirm dialog first; if that player had already sent a request, confirming makes you friends right away. Resolves { status: "sent" | "friends" } ("sent" = waiting for them to accept on Nekoland). INVALID_ARGUMENT for the player's own playerId or a player who can't receive requests, USER_CANCELLED if the dialog is closed.
• sdk.invite is { fromPlayerId, fromName, fromAvatarUrl?, data } when this session was opened from an invite, otherwise null.
• data (up to 500 characters) reaches the friend's game as-is. Use it for a room code — never for anything your server must trust.

Analytics

sdk.track("level_complete", { level: 3, stars: 2 });
sdk.track("tutorial_complete");

• Name: up to 40 lowercase letters, digits and _, starting with a letter. neko_ is reserved for the platform.
• Props: a flat object, up to 20 keys (same naming rule); strings up to 100 characters, finite numbers, booleans; 2KB total.
• Safe before init (up to 100 events are queued) and never throws — invalid events are dropped with a console warning in local mode.
• Suggested: level_start / level_complete / level_fail, tutorial_complete, item_earn / item_spend. Don't send purchases (the platform already knows) or personal data.
• Watch them with neko events (-f to follow) or in the developer console. Load time, errors and drop-off are collected automatically.

Player tokens

To prove who the player is to your own server, send a player token and verify it there:

// In the game
const { token, expiresAt } = await sdk.getPlayerToken(); // valid for 1 hour
await fetch("https://api.example.com/session", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ token }),
});

The token is an ES256 JWT valid for 1 hour (guests get one too). Request a new one when it expires, and after player.changed. Tokens from neko dev are unsigned and fail verification — test server integration on the preview.

Verifying players

import { NekoServer, NekoServerError } from "@launchercapital/nekoland-server";

const neko = new NekoServer({
  gameId: "gem-rush",                             // gameId from nekogame.json
  apiKey: process.env.NEKO_GAME_API_KEY,          // Developer Console → Server integration (server only!)
  webhookSecret: process.env.NEKO_WEBHOOK_SECRET, // shown once by `neko webhook set`
});

// Token the game got from sdk.getPlayerToken()
const player = await neko.verifyPlayerToken(token);
// { playerId, displayName, isGuest, sandbox, expiresAt }

• verifyPlayerToken checks the signature, issuer, game, kind and expiry. Use playerId as the account key on your server.
• Tokens last 1 hour. For long sessions, verify once and use your own session, or have the game send a fresh token.
• Preview tokens and purchases have sandbox: true. Keep them apart from real records.
• Keep the game API key and webhook secret in server environment variables only — never in game code.

Purchases on your server

Grant from a verified webhook or a receipt the client sent (purchase.signedReceipt), save the grant, then consume:

await neko.verifyReceipt(signedReceipt);              // receipt the client sent
await neko.getPurchase(purchaseId);
await neko.listPlayerPurchases(player.playerId);      // catch up on missed purchases
await neko.refund(purchaseId, "Accidental purchase"); // developer-initiated refund

consume is safe to call more than once. refund returns the cubes to the buyer, deducts them from your revenue and sends a purchase.refunded webhook. listPlayerPurchases(playerId, { all?, sandbox? }) lists ungranted consumables and owned non-consumables by default.

Webhooks

neko webhook set https://api.example.com/nekoland  # prints whsec_… the first time
neko webhook test             # sends a ping
neko webhook                  # URL and recent deliveries
neko webhook secret --rotate  # regenerate the secret

// Pass the raw body string, before parsing
const ev = await neko.verifyWebhook(rawBody, req.headers.get("nekoland-signature"));
switch (ev.type) {
  case "purchase.completed":
    // save the grant (dedupe by ev.data.purchaseId), then consume
    await neko.consume(ev.data.purchaseId);
    break;
  case "purchase.refunded":  /* take back what you granted */ break;
  case "player.suspended":   /* disconnect if online */ break;
  case "player.updated":     /* display name / guest status changed */ break;
}

• Types: purchase.completed, purchase.refunded (with reason), player.updated, player.suspended, player.unsuspended, ping. Player events arrive only for players who have opened this game.
• Answer 2xx within 10 seconds. Otherwise the delivery is retried after 1 min, 5 min, 30 min, 2 h and 6 h — dedupe by ev.id (and purchaseId).
• Without the package: the header is Nekoland-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>; the /v1 API takes Authorization: Bearer <game API key>; tokens and receipts are ES256 JWTs (keys at https://nekoland.net/.well-known/jwks.json, iss = nekoland, aud = gameId, sub = playerId).

Friends on the server

const player = await neko.verifyPlayerToken(token);
const friends = await neko.getFriends(player.playerId);
// [{ playerId, hasPlayed }] — playerIds in your game

getFriends(playerId) returns the player's Nekoland friends as playerIds of your game, with hasPlayed. Verify the player token first and pass its playerId. Use it for friend leaderboards or "join a friend's room".

Server errors

Unity

Unity 2021.3 or later. The package lands in Packages/com.nekoland.sdk. Then use Nekoland ▸ Setup WebGL Project: it installs the Nekoland WebGL template (includes /__neko/sdk.js) and sets Brotli compression with decompression fallback off. In the Editor the SDK runs against a mock platform, so Play just works.

using Nekoland;

async void Start()
{
    var player = await NekoSDK.InitAsync();             // always first
    NekoSDK.OnPause  += () => Time.timeScale = 0;
    NekoSDK.OnResume += () => Time.timeScale = 1;
    NekoSDK.OnPlayerChanged += async p => await LoadSave();

    await LoadSave();
    foreach (var p in await NekoSDK.Payments.GetPurchasesAsync()) await Grant(p);
    await NekoSDK.GameReadyAsync();                     // dismisses the platform loading screen
    NekoSDK.GameplayStart();
}

The template inits with manualReady, so the loading screen stays until GameReadyAsync(). Set "build": "Build/web" (your WebGL output folder) in nekogame.json. Add a CJK font for Korean, Japanese or Chinese text.

Godot 4

The addon lands in addons/nekoland. Enable Nekoland SDK in Project Settings ▸ Plugins (registers the NekoSDK autoload) and add <script src="/__neko/sdk.js"></script> to the Web export preset's Head Include. Every async method returns { ok, data } or { ok: false, code, message }.

func _ready():
	var res := await NekoSDK.init()                 # always first
	if not res.ok: return
	NekoSDK.paused.connect(func(): get_tree().paused = true)
	NekoSDK.resumed.connect(func(): get_tree().paused = false)
	NekoSDK.player_changed.connect(func(p): load_save())

	await load_save()
	for p in (await NekoSDK.payments_get_purchases()).data: await grant(p)
	NekoSDK.gameplay_start()

Thread Support can stay off; multithreaded exports also work (they're served cross-origin isolated) but older browsers can't run them.