Developers / SDK

SDK API reference

Version 1.3.1. With the script file, Ikirmikir is window.Ikirmikir; with npm, import { Ikirmikir } from "@ikirmikir/game-sdk". Below, ik is what init resolves to.

Ikirmikir.init({ gameId })

Returns Promise<Sdk>

Start the SDK. Call once, early in loading. Never rejects; calling again returns the same instance. Inside Ikirmikir it connects within a moment; elsewhere it waits about 1.5 seconds, then runs in local mode.

Ikirmikir.VERSION

Returns string

The SDK version, for example "1.3.1".

ik.env

Returns "ikirmikir" | "local"

Whether the game runs inside the Ikirmikir player.

ik.context

Returns { language, device, touch }

The player's language code (for example "en"), "mobile" or "desktop", and whether the screen is touch.

ik.muted

Returns boolean

True when the player turned Ikirmikir's sound off. Keep your game silent while it is true.

ik.has(feature)

Returns boolean

Whether a feature works here: "loading", "gameplay", "pause", "mute", "context", "share", "multiplayer", "sound", "player", "data", "scores", "badges".

ik.game.loadingProgress(percent)

Returns void

Loading progress from 0 to 100. Ikirmikir shows it as its loading bar.

ik.game.loadingDone()

Returns void

Your game is ready. Ikirmikir hides its loader and shows the game.

ik.game.gameplayStart()

Returns void

Someone is actually playing (not in a menu).

ik.game.gameplayStop()

Returns void

Play stopped: menu, game over, between rounds.

ik.on("pause", fn)

Returns () => void

The player switched tab or app: pause your game. Returns a function that stops listening.

ik.on("resume", fn)

Returns () => void

The player is back. Resume if you paused.

ik.on("mute", fn)

Returns () => void

Ikirmikir's sound switch changed; fn receives true for muted.

ik.share()

Returns Promise<{ shared }>

Ask Ikirmikir to share your game's link (share sheet, or copy the link). shared is false if nothing was shared.

ik.share({ score: { board, value } })

Returns Promise<{ shared }>

Share a score as a picture (1.3.1): Ikirmikir draws a score card with your game's drawing, the player, the score and its place this week, and shares it with your game's link. Where the phone can't share pictures, it saves the picture and copies the link. Call it from a Share button at the end of a round.

ik.sound.play(name)

Returns void

Play one of Ikirmikir's own interface sounds, so your menus sound like the rest of the site: "click" for a button press (1.2.1). Ikirmikir plays it and follows its sound switch, so you don't need your own click sound or a mute check. Inside Ikirmikir only (has("sound")); silent anywhere else.

ik.player.get()

Returns Promise<{ id, name, avatar, signedIn }>

Who is playing (1.3). id is different for each game, so games can't match players; it stays the same for a signed-in player on every phone. name and avatar are the player's Ikirmikir name and picture when signed in, null for a guest. Outside Ikirmikir: a guest with an id kept in your game's own storage.

ik.on("player", fn)

Returns () => void

The player signed in or out while your game was open; fn receives the new player (1.3).

ik.data.get(key)

Returns Promise<value | null>

A value your game saved, or null (1.3). Inside Ikirmikir your saves are kept by Ikirmikir, so they survive new versions of your game; a signed-in player's follow them to every phone. Outside Ikirmikir they live in your game's own storage.

ik.data.set(key, value)

Returns Promise<{ ok, error? }>

Save anything JSON can hold under a key of 1 to 64 letters, numbers, _ . or - (1.3). Up to 64 KB and 32 keys per game. Errors: "too-big", "too-many-keys", "bad-request", "slow-down" (more than 30 calls a second), "unavailable". Save at checkpoints, not every frame.

ik.data.remove(key)

Returns Promise<{ ok, error? }>

Remove a saved key (1.3).

ik.data.keys()

Returns Promise<string[]>

Every key your game has saved (1.3).

ik.scores.submit(board, value)

Returns Promise<{ ok, best, error? }>

Send a score to one of your game's boards (1.3); best is the player's best there. Boards are listed for your game on Ikirmikir (ask us): a name, whether higher or lower wins, the highest score and the most a player can score in a second of play. A signed-in player's scores go on the board; a guest's best is kept on their phone only. A board can also break ties with a second number (1.3.1): send both by name, for example submit("caught", { caught: 24, time: 312 }); the first decides, the second breaks a tie. Errors: "unknown-board", "too-high". Scores are not checked, so boards are for fun.

ik.scores.top(board)

Returns Promise<{ entries, best }>

The board's top 10 all time, each { name, avatar, value, you }, and the player's best (1.3). Empty outside Ikirmikir.

ik.scores.rank(board, value?)

Returns Promise<{ week, all } | null>

Where a score places, this week and all time, each { place, ahead, of, beat } (1.3). beat (1.3.1) is the share of other players this score beats, 0 to 100, or null when no one else is on the board. Call it after a round to show "4th this week, better than 82%". Without a value it places the player's best. Guests get where their score would place. Null outside Ikirmikir or when the board can't be reached; a period is null when there is no score to place.

ik.badges.award(id)

Returns Promise<{ ok, new, error? }>

Award one of your game's badges (1.3); new is true the first time. Badges are listed for your game on Ikirmikir (ask us: a name, a symbol and how to earn it, at most 8). They show on the player's profile. Error: "unknown-badge".

ik.badges.list()

Returns Promise<string[]>

Your game's badges this player has (1.3).

ik.multiplayer.create({ maxPlayers, name })

Returns Promise<{ room } | { error }>

Make a room for 2 to 8 players (default 8) and join it. name (optional): 1 to 16 letters in any script, numbers, spaces, _ or -; anything else is ignored and the player gets an id like "usr_k3x9q2a". Only inside Ikirmikir; elsewhere it resolves { error: "not-available-here" }. Other errors: "unavailable" (rooms can't be reached, for example after the free daily limit, until 6 AM Bangladesh time) and "bad-request".

ik.multiplayer.join(code, { name })

Returns Promise<{ room } | { error }>

Join a friend's room by its 5-character code (not case sensitive), with an optional name as for create. Errors: "not-found", "full", "unavailable", "not-available-here".

ik.multiplayer.invite

Returns string | null

The room code when the player arrived through an invite link. Join it straight away with join(invite).

room.you, room.players, room.max

Returns Player, Player[], number

You, everyone in the room (you included, in the order they came in) and the most players allowed. A Player is { id, name, connected }; name is what they typed, or an id like "usr_k3x9q2a".

room.send(data)

Returns boolean

Send anything JSON can hold, up to 4 KB, to every other player. Up to 20 messages a second. False when it can't be sent.

room.invite()

Returns Promise<{ shared }>

Open the share sheet with this room's invite link (Ikirmikir copies the link when there is no share sheet).

room.leave()

Returns void

Leave the room for good.

room.on("join" | "leave", fn)

Returns () => void

Someone came in, or left for good; fn receives the Player.

room.on("away" | "back", fn)

Returns () => void

Someone's connection dropped (they have 30 seconds to come back), or they came back. Messages sent while they were away are not delivered to them, so send them what they missed when they are back.

room.on("message", fn)

Returns () => void

A message from another player; fn receives (data, fromPlayer).

room.on("status", fn)

Returns () => void

Your own connection: "reconnecting", "connected" again, or "closed" (could not get back within 30 seconds).