Developers

SDK quick start

Version 1.3.1. Optional, for any web game. If your game runs outside Ikirmikir, the SDK notices and quietly does nothing, so one build works everywhere. No call ever throws.

1. Add it

With a bundler (Vite, webpack, and so on)

npm install @ikirmikir/game-sdk
# or: pnpm add @ikirmikir/game-sdk
import { Ikirmikir } from "@ikirmikir/game-sdk";

Without a bundler (plain HTML, Unity, Godot, Construct)

Download ikirmikir.js and put it next to your index.html. Recommended: your game then carries its own exact SDK.

<script src="ikirmikir.js"></script>  <!-- gives you window.Ikirmikir -->

Or load it from a public CDN:

<script src="https://cdn.jsdelivr.net/npm/@ikirmikir/[email protected]/dist/ikirmikir.js"></script>

2. Call it

const ik = await Ikirmikir.init({ gameId: "your-game" });

ik.game.loadingProgress(50);     // while your assets load, 0 to 100
ik.game.loadingDone();           // ready: Ikirmikir hides its loader

startButton.onclick = () => ik.game.gameplayStart();
function gameOver() { ik.game.gameplayStop(); }

ik.on("pause", () => game.pause());   // the player switched tab or app
ik.on("resume", () => game.resume());
audio.muted = ik.muted;               // Ikirmikir's sound switch wins
ik.on("mute", muted => { audio.muted = muted; });

Call init once, early in loading. Inside Ikirmikir it connects within a moment; anywhere else it waits about 1.5 seconds, then runs in local mode.

Play with friends (1.1)

const r = ik.multiplayer.invite
  ? await ik.multiplayer.join(ik.multiplayer.invite)   // came through an invite link
  : await ik.multiplayer.create({ maxPlayers: 2, name: nameInput.value }); // name is optional
if (r.error) return showMessage(r.error);
const room = r.room;
inviteButton.onclick = () => room.invite();          // share sheet with the invite link
room.on("join", player => startGame());
room.on("message", (move, from) => applyMove(move));
room.send({ cell: 4 });

Rooms are for friends: they join with the invite link or the 5-character code. Players can give a name (optional); without one they get an id like usr_k3x9q2a. The room passes your messages on without reading them, so every phone runs the same rules. Multiplayer works only inside Ikirmikir; check ik.has("multiplayer") and offer something else, such as playing on one device, when it is false. A full example: Kata-kuti (code).

Saves, scores and badges (1.3)

const me = await ik.player.get();          // { id, name, avatar, signedIn }
const saved = await ik.data.get("progress"); // null the first time
await ik.data.set("progress", { level: 3, coins: 40 });

async function roundOver(score) {
  ik.game.gameplayStop();
  const { best } = await ik.scores.submit("best", score);  // a board listed for your game
  const r = await ik.scores.rank("best", score);
  if (r?.week) show(`Place ${r.week.place} this week. ${r.week.ahead} ahead of you`);
  if (score >= 100) ik.badges.award("hundred");          // a badge listed for your game
}

Inside Ikirmikir your saves are kept by Ikirmikir, one place per game, so they survive every new version of your game. Signed-in players' saves, scores and badges follow them to every phone; guests keep theirs on their phone. Boards and badges are listed for your game on Ikirmikir: tell us their names when you send your game. Scores are not checked, so leaderboards are for fun. Outside Ikirmikir every call still works, from your game's own storage, and there are no boards to place on.

Good to know

  • Your game runs in a sandboxed frame that may not submit forms or open popups. Use buttons and key handlers instead of <form> submit.
  • Each version of your game is its own address, so anything it keeps in its own storage starts fresh with every new version. Save with ik.data instead.

3. Test it

Open your game in the test tool to see each message arrive, the loading bar, pause and the sound switch.

What's coming

1.0
Loading, gameplay start and stop, pause and resume, sound, player context, share
1.1
Multiplayer: rooms with friends, invite links and codes, send and receive, reconnecting
1.2
Players can give a name in rooms
1.2.1
Ikirmikir's own click for your menus: ik.sound.play("click")
1.3, now
The player, saves that survive new versions, leaderboards and where a score places, badges
1.4
Friends: who is online, invite a friend into your game
1.5
Ads: ad breaks and rewarded ads

Check ik.has("feature") before using a feature; new ones switch on without breaking older games.