# Building a game for Ikirmikir

One file for anyone, person or AI agent, making a browser game for [Ikirmikir](https://ikirmikir.com): the rules a game must follow, the paper and pencil look, every SDK feature (rooms, the player, saves, scores, rank, badges), what players get from a game (points and challenges) and how a game gets published. A ready prompt for an AI agent is at the end.

SDK version: **1.3.1** (`@ikirmikir/game-sdk`, MIT). Updated 2026-11-12. The full API reference is at https://ikirmikir.com/developers/sdk/reference/.

**Read online:** this file is published at https://ikirmikir.com/developers/game-guide.md, with a short index for AI tools at https://ikirmikir.com/llms.txt. An agent can fetch either; both always match the live SDK.

**Two open examples to copy** (MIT, plain HTML, CSS and JavaScript, no build step):

| Game | Shows | Code |
|---|---|---|
| Mosha Mara | One player, a timed round, saves, a leaderboard with the place after each round, a score card to share, a canvas drawn in pencil | https://github.com/ikirmikir/sdk-example (`public/game.js`) |
| Kata-kuti | Two players in a room (invite link or code, names, away and back, roles by message), one-device play, a match clock for short rounds, a badge counted in saves | https://github.com/ikirmikir/kata-kuti (`public/game.js`) |

Search either `game.js` for `SDK:` to see every call.

---

## 1. What Ikirmikir is

A Bangladesh-born place to play the games we grew up with, together: Kata-kuti, ludo, carrom, kite fights, lattu, and new games from Bangladeshi streets (Runbro). Players come mostly on phones. They play as guests with no sign-up, or sign in with Google to keep progress on every phone, appear on leaderboards and collect badges. Friends play together in rooms by sending a link or a 5-letter code.

A game is a static web page (any engine that runs in a browser) that Ikirmikir shows inside its player. The SDK is optional, but without it a game gets no saves, scores, badges or rooms.

## 2. Rules every game follows

1. **Its own repo, its own host.** The game lives in its own GitHub repo and is hosted on its own Cloudflare Pages project. Its source never goes into the Ikirmikir platform repo.
2. **Allow Ikirmikir to show it.** Put a `_headers` file at the root of the build output:
   ```
   /*
     Content-Security-Policy: frame-ancestors https://ikirmikir.com https://ikirmikir.pages.dev https://*.ikirmikir.pages.dev http://localhost:3000 http://127.0.0.1:3000
     X-Content-Type-Options: nosniff
     Referrer-Policy: strict-origin-when-cross-origin
   ```
3. **The player is a sandbox.** The game runs in an iframe with `allow-scripts allow-same-origin allow-pointer-lock allow-orientation-lock`, and `fullscreen; gamepad; autoplay`. So: **no `<form>` submit** (use buttons and the Enter key), **no popups or new windows**, no `alert`/`prompt` dialogs. Ikirmikir has its own full screen button.
4. **Everything from its own address.** Fonts, images, sounds and scripts ship with the game. Nothing loads from other hosts while playing (what Maruf reviews must stay what players get). Copy the SDK file next to the game.
5. **Phone first.** Most players are on phones: touch controls first, big tap targets (at least 44 px), no sideways scrolling, works upright unless the game truly needs landscape. Keyboard too on computers.
6. **Never breaks.** Every SDK call can fail softly (no room, no signal, the free daily limit). The game keeps working on its own: local play when there is no room, no score shown when rank answers null.
7. **Kind and fair.** Plain English, nothing rude, no ads or in-game purchases of your own, no tracking. Children play here.
8. **Licenses.** Only your own art and sound, or assets with a license that allows it (record each in the game repo's README with its license).
9. **A round starts only from a button.** Start and Play again are real buttons; a tap on the game itself never starts a round, and Play again waits a moment after a round ends, so taps still landing don't start the next one by accident (Maruf, 2026-11-12).
10. **Each version is a fixed link.** Every release is a Cloudflare Pages deployment with its own address (`https://<8-character id>.<project>.pages.dev/`) that never changes. Maruf approves a version by its link.

## 3. The look: paper and pencil

Ikirmikir looks like a white page drawn on with a pencil, a little ink, and yellow and blue coloured pencils. Games should feel at home next to it. Kata-kuti (https://github.com/ikirmikir/kata-kuti, `public/style.css`) is the reference: copy from it.

### Colours

| Token | Hex | Use |
|---|---|---|
| `--paper` | `#FCFBF6` | The page |
| `--ink` | `#1E1E24` | Lines and text |
| `--graphite`, `--muted`, `--pencil` | `#4B4B55`, `#6E6E7A`, `#8d8d96` | Softer text, faint pencil lines |
| `--yellow` | `#FFD60A` | What you press, whose turn it is |
| `--hl` | `rgb(255 214 10 / 55%)` | Highlighter under words that matter |
| `--blue` | `#2F6BFF` | Pencil drawings, focus ring (not text) |
| `--red` | `#b42318` | Pencil drawings, errors |

### Type

- **Kalam** (400, 700) for headings, names and words that matter: hand-written.
- **Outfit** (variable) for everything else.
- **Galada** for Bangla words, **Hind Siliguri** 600 as its fallback.
- All SIL Open Font License; ship the `.woff2` files with the game (Kata-kuti has Kalam and Outfit in `public/fonts/` with their licenses).

### Hand-drawn shapes

```css
:root {
  --sk: 18px 7px 16px 9px / 9px 16px 7px 18px;   /* uneven corners for boxes */
  --sk-b: 9px 18px 8px 16px / 16px 8px 18px 9px;
  --sk-s: 12px 5px 11px 6px / 6px 11px 5px 12px; /* small: chips, tags */
}
.btn { height: 52px; padding: 0 20px; border: 2px solid var(--ink); border-radius: 16px 6px 14px 8px / 8px 14px 6px 16px;
  background: var(--paper); color: var(--ink); box-shadow: 3px 3px 0 var(--ink); font: 600 17px/1 Outfit, system-ui, sans-serif }
.btn:hover { transform: translate(-1px, -1px); box-shadow: 4px 4px 0 var(--ink) }
.btn:active { transform: translate(2px, 2px); box-shadow: 1px 1px 0 var(--ink) }
.btn.primary { background: var(--yellow) }   /* the one button to press */
.box { border: 2px solid var(--ink); border-radius: var(--sk); background: var(--paper); box-shadow: 3px 3px 0 var(--ink) }
.mark { background: linear-gradient(transparent 55%, var(--hl) 55%, var(--hl) 92%, transparent 92%) } /* highlighter */
```

- One yellow button per screen: the thing to press next. Others are paper.
- Links are ink and underlined, with a yellow highlight on hover. Not blue.
- Drawings are pencil strokes: lines drawn twice with a tiny wobble, coloured-pencil hatching inside shapes, never flat vector fills. Kata-kuti's `game.js` draws its board and marks this way.
- Motion is gentle: screens rise and fade in, marks draw themselves. With `prefers-reduced-motion`, hold still.
- Sound: soft and short, made with Web Audio (no files needed). Use `ik.sound.play("click")` for menu buttons so they sound like the site. Stay silent while `ik.muted` is true.
- Words: plain, short, friendly English. "Your move", "You win", "Play again". Bangla names welcome (কাটাকুটি).

## 4. The SDK

### Getting it

Copy the script file next to `index.html` (recommended: the version is then fixed with your game):

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

Download: https://ikirmikir.com/sdk/1.3.1/ikirmikir.js (the same file as https://cdn.jsdelivr.net/npm/@ikirmikir/game-sdk@1.3.1/dist/ikirmikir.js). With a bundler: `npm install @ikirmikir/game-sdk` and `import { Ikirmikir } from "@ikirmikir/game-sdk"` (TypeScript types included).

### Start, loading, play

```js
const ik = await Ikirmikir.init({ gameId: "your-game" }); // once, early. Never rejects.
// Inside Ikirmikir ik.env is "ikirmikir"; anywhere else, after about 1.5 s, "local".

ik.game.loadingProgress(40);  // 0 to 100 while assets load: Ikirmikir shows a real loading bar
ik.game.loadingDone();        // ready: Ikirmikir hides its loader

ik.game.gameplayStart();      // a round really starts (not menus)
ik.game.gameplayStop();       // round over, menu, between rounds, game over

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", m => { audio.muted = m });
menuButton.onclick = () => ik.sound.play("click"); // Ikirmikir's own click

await ik.share();              // { shared }: share the game's link
await ik.share({ score: { board: "best", value: score } }); // 1.3.1: a score card picture with the game's link
ik.has("multiplayer");         // check a feature before using it:
// "loading", "gameplay", "pause", "mute", "context", "share", "multiplayer", "sound", "player", "data", "scores", "badges"
ik.context;                    // { language: "en", device: "mobile" | "desktop", touch: true }
```

**Call `gameplayStart` and `gameplayStop` honestly.** Ikirmikir measures play time between them, and a score bigger than the time played allows is refused (section 4.5). Each stretch between them is a round for the player's points and the bat's challenges, and it counts only when it lasts **20 seconds or more**. If your rounds are shorter (a game of noughts and crosses), keep play running for the whole match: start at the first round, stop when the player leaves the match, the game is hidden, or a minute passes without a new round (Kata-kuti does this). A round still running when the player leaves the game page counts too.

### 4.1 Rooms: play with friends (inside Ikirmikir only)

```js
const r = ik.multiplayer.invite                       // the player came through an invite link
  ? await ik.multiplayer.join(ik.multiplayer.invite)
  : await ik.multiplayer.create({ maxPlayers: 2, name: nameInput.value }); // name optional
if (r.error) return showMessage(r.error);  // "not-found", "full", "unavailable", "not-available-here", "bad-request"
const room = r.room;
room.code; room.link;                      // "KX7Q2", and the invite link
room.you; room.players; room.max;          // Player = { id, name, connected }
inviteButton.onclick = () => room.invite(); // share sheet with the invite link
room.on("join", p => {}); room.on("leave", p => {});
room.on("away", p => {}); room.on("back", p => {});   // dropped connection: 30 s to come back
room.on("message", (data, from) => applyMove(data));
room.on("status", s => {});                // your own connection: "reconnecting", "connected", "closed"
room.send({ cell: 4 });                    // any JSON up to 4 KB, at most 20 a second
room.leave();
```

- Friends only: invite link or code. 2 to 8 players. A room closes 10 minutes after it empties.
- **Relay only.** The room passes messages on without reading them; every player's game runs the same rules on its own phone. Design moves so both sides can check them.
- Don't decide roles by the order of `room.players` (when the maker leaves and returns, both would pick the same). Let the player already in the room hand the newcomer their role in a message (Kata-kuti's `start` message).
- Messages sent while someone is `away` are not delivered to them: when they are `back`, send them what they missed.
- Names: 1 to 16 letters in any script, numbers, spaces, `_` or `-`; without one a player gets an id like `usr_k3x9q2a`.
- Outside Ikirmikir `ik.has("multiplayer")` is false: offer play on one device instead.
- Turn-based games suit the free plan best (a few messages a minute). Fast action games send many messages; check with Maruf first.

### 4.2 The player

```js
const me = await ik.player.get(); // { id, name, avatar, signedIn }
ik.on("player", p => {});         // signed in or out while the game is open
```

On Ikirmikir, `name` is the signed-in profile name, or the last guest room name remembered on this browser after a successful room join/create. A remembered guest still has `signedIn: false`: offer that name as an editable default. Signed-in players can use their profile name directly without another name form. Outside Ikirmikir there may be no name.

`id` is different for each game (games can't match players) and the same on every phone for a signed-in player. `name` and `avatar` are null for a guest. Games cannot open sign-in; only the site offers it.

### 4.3 Saves

```js
const save = await ik.data.get("progress");              // a value, or null
await ik.data.set("progress", { level: 3, coins: 40 });  // { ok, error? }
await ik.data.remove("progress");
await ik.data.keys();
```

- Keys: 1 to 64 letters, numbers, `_ . -`. Values: anything JSON can hold. At most **64 KB and 32 keys** per game.
- Inside Ikirmikir the site keeps the saves, so they **survive every new version of the game**. A signed-in player's saves follow them to every phone; a guest's stay on their phone. Outside Ikirmikir they live in the game's own storage.
- Save at checkpoints (end of a level, a setting changed), not every frame. More than 30 calls a second answer `slow-down`.
- Errors: `too-big`, `too-many-keys`, `bad-request`, `slow-down`, `unavailable`.
- Don't use the game's own `localStorage` for progress: each new version is a new address, so it starts empty.

### 4.4 Badges

```js
const r = await ik.badges.award("hundred"); // { ok, new, error? }; new is true the first time
const mine = await ik.badges.list();        // this game's badges the player has
```

- A game's badges are **listed for it on Ikirmikir** by Maruf: up to 8, each with an id (lowercase letters, numbers, `-`), a name, a symbol (one character, like ♛) and how to earn it. Unknown ids answer `unknown-badge`.
- Badges show on the player's profile next to Ikirmikir's own. Show your own small "Badge earned" moment when `new` is true.
- Count progress toward a badge in `ik.data` (for example wins), and award it when reached.

### 4.5 Scores, leaderboards and rank

```js
ik.game.gameplayStop();
const { ok, best, error } = await ik.scores.submit("best", score); // a board listed for the game
const r = await ik.scores.rank("best", score);
if (r?.week) show(`${r.week.place} this week` + (r.week.beat !== null ? `, better than ${r.week.beat}%` : ""));
const top = await ik.scores.top("best");   // { entries: [{ name, avatar, value, you }], best }
```

- A game's boards are **listed for it on Ikirmikir** by Maruf, each with: an id, a name, whether **higher or lower** wins, the **highest score** allowed, and the **most a player can score in one second of play**. Scores above the highest, or more than (seconds of play × that rate) allow, are refused with `too-high`. Ask for limits a little above a really good honest player.
- Boards keep each player's best **this week** (from Sunday 00:00 Bangladesh time) and **all time**. Only signed-in players are listed; a guest's best stays on their phone, but `rank` still tells a guest where their score would place.
- **Ties** (1.3.1): a board can have a second number that breaks ties, for example Runbro's "Thieves caught", then less chase time. Send both by name: `ik.scores.submit("caught", { caught: 24, time: 312 })`. The first number decides; when it is equal, the second does (lower or higher wins, as listed for the board). Boards without a tie-breaker take a plain number.
- After a round, show the place yourself (Ikirmikir shows no message over your game). A **Share** button at the end of a round can call `ik.share({ score: { board, value } })`: Ikirmikir draws a score card picture (the game's drawing, the player, the score and its place) and shares it with the game's link, or saves it and copies the link where the phone can't share pictures.
- `rank(board, value?)` answers `{ week, all }`, each `{ place, ahead, of, beat }` or null. `beat` (1.3.1) is the share of other players on the board this score beats, 0 to 100, or null when no one else is there. Without a value it places the player's best. It is null outside Ikirmikir or when the board can't be reached: then show nothing.
- Scores are not checked (the game reports them), so boards are for fun. Don't promise prizes.
- Ikirmikir's **Top players** list gives points for finishing in a game's top 10 on its first board (25 for 1st down to 1 for 10th), added up over every game.

### 4.6 Outside Ikirmikir (local mode)

The same build works on its own address: `ik.env === "local"`, saves and badges in the game's own storage, scores keep a local best, `rank` and `top` give nothing, no rooms. Test both.

### 4.7 What players get from your game on Ikirmikir

Signed-in players earn from every game, worked out by Ikirmikir from your SDK calls. Your game does nothing extra, but it must make the right calls:

- **Points and levels** for each finished round: 5, plus 2 a minute (up to 30 minutes), half again in a room with others. A round is the time between `gameplayStart` and `gameplayStop`, and it counts only when it lasts **20 seconds or more**. Short rounds: keep play running for the whole match (section 4). A round still running when the player leaves the page counts too.
- **New personal best** on a board: more points.
- **The bat's challenges** (the round button in Ikirmikir's menu): a rhyme picks a game and writes a task, like "Play 4 rounds of Runbro", "Play Kata-kuti for 8 minutes", "Play one round lasting 2 minutes", "Play 3 rounds in a row", "Play in a room with a friend", "Score 45 or more in one round" or "Beat your own best". Finishing one in time gives marbles. Rounds and minutes come from `gameplayStart` and `gameplayStop`; room tasks need rooms; score tasks need `ik.scores.submit` after every round. So: call them honestly, and send every round's score, not only bests.
- **Top players** points for a top 10 place on your first board (section 4.5).

Your own badges (section 4.4) show on the player's profile next to these.

## 5. Make it, test it, publish it

1. **Repo:** your own GitHub repo; static files in `public/` (or your engine's build output) with `index.html`, the game, `ikirmikir.js`, fonts and `_headers`.
2. **Run locally:** any static server, for example `npx serve public`.
3. **Test inside Ikirmikir:** deploy to Cloudflare Pages (a preview is fine), then open https://ikirmikir.com/developers/test/ and paste the `https://` link (an `http://` link is blocked inside the `https` site). The tool shows every SDK message. It keeps saves for that tab only and accepts any board or badge id, so scores and badges can be tried before they are listed.
4. **Check on a phone and a computer:** touch, keyboard, sound switch, pause when switching apps, upright and sideways, two phones in a room.
5. **Send Maruf, for each version:**
   - the deployment link (`https://<id>.<project>.pages.dev/`),
   - title, one-line tagline, two short paragraphs about the game, how to play in three steps, controls (touch and keyboard), players (for example "2 players"), orientation (any, portrait or landscape),
   - **boards**: id, name, higher or lower wins, highest score, most per second of play, and why those numbers,
   - **badges**: id, name, symbol, how to earn (up to 8),
   - the SDK version it uses.
6. Maruf reviews it in the player, adds it to the registry (`games.ts`, `boards.ts`) and makes it live. Every step of that, for Ikirmikir's own team and agents, is in the platform repo's `docs/platform/PUBLISH_A_GAME.md`.

## 6. Checklist before sending

- [ ] `_headers` with `frame-ancestors https://ikirmikir.com …`
- [ ] No `<form>` submit, no popups, nothing loaded from other hosts
- [ ] `init` once; `loadingProgress` and `loadingDone`; `gameplayStart` and `gameplayStop` around real play (rounds under 20 seconds: one match clock)
- [ ] Start and Play again are buttons; a tap on the game never starts a round
- [ ] Pauses on `pause`, silent while `ik.muted`, menu buttons use `ik.sound.play("click")`
- [ ] Progress saved with `ik.data`, not the game's own storage
- [ ] Scores sent with `ik.scores.submit` after a round; rank shown when it answers
- [ ] Badges awarded once their goal is reached; ids match the list sent to Maruf
- [ ] Rooms: invite link and code, names, away and back handled, roles handed over by message, one-device play when there is no room
- [ ] Every call's failure handled softly; the game works with `ik.env === "local"`
- [ ] Paper and pencil look, Kalam and Outfit shipped with the game, one yellow button per screen
- [ ] Phone first: big tap targets, no sideways scrolling, tested on a real phone
- [ ] Every outside asset's license recorded in the README

---

## 7. A prompt for an AI agent

Copy this, fill in the brackets, and give it to the agent. It tells the agent to fetch this file itself.

```text
You are building a browser game for Ikirmikir (https://ikirmikir.com), a Bangladesh-born site where people play the
games they grew up with, together, mostly on phones. First fetch and read https://ikirmikir.com/developers/game-guide.md
and follow it exactly: its rules, the paper and pencil look, and the Ikirmikir game SDK 1.3.1. Then read the code of the
example closest to this game: https://github.com/ikirmikir/sdk-example (one player, scores) or
https://github.com/ikirmikir/kata-kuti (rooms with friends).

The game: [name, and the Bangla name if any]
What it is: [two or three sentences: the game, its feel, who plays]
Players: [1 player | 2 to N players in a room with friends | both]
How a round works: [rules, how it ends, what the score is]
Saves: [what to keep between visits, for example level, coins, settings]
Leaderboard: [board id, name, higher or lower wins, or "none"]
Badges: [up to 8: id, name, symbol, how to earn, or "none"]
Engine: [plain HTML, CSS and JavaScript with no build step | Phaser | Three.js | other]
Orientation: [any | portrait | landscape]

Build it in its own repo, as static files in public/ with ikirmikir.js (download
https://ikirmikir.com/sdk/1.3.1/ikirmikir.js) and _headers next to index.html. Use Kata-kuti
(https://github.com/ikirmikir/kata-kuti) and Mosha Mara (https://github.com/ikirmikir/sdk-example) as the reference for
structure, look and SDK use. Put an AGENTS.md in the repo (what the game is, how to run and test it, the SDK rules
it follows) so the next agent can carry on.

Must:
- Work inside the Ikirmikir player (sandboxed iframe: no form submit, no popups, nothing from other hosts) and on its
  own (ik.env === "local").
- Phone first: touch controls, tap targets of at least 44 px, no sideways scrolling; keyboard on computers.
- Call ik.game.loadingProgress, loadingDone, gameplayStart and gameplayStop honestly; pause on "pause"; stay silent
  while ik.muted; menu buttons call ik.sound.play("click"). Rounds count for players only from 20 seconds: if a
  round is shorter, keep play running for the whole match.
- Start a round only from a Start or Play again button, never from a tap on the game; Play again waits a moment.
- Save progress with ik.data, never the game's own localStorage.
- After every round (not only bests): ik.scores.submit, then ik.scores.rank, and show the place this week (and
  "better than N% of players" when beat is not null) when it answers. Offer Share with ik.share({ score }).
- Award badges with ik.badges.award when their goal is reached; count progress in ik.data.
- For rooms: create or join (invite link or code, optional typed name), invite, send moves as small JSON, handle join,
  leave, away and back, hand roles over by message, and offer one-device play when ik.has("multiplayer") is false.
- Handle every failure softly; never show a broken game.
- Look like ikirmikir.com: paper #FCFBF6, ink #1E1E24, yellow #FFD60A for the one button to press, pencil drawings in
  blue #2F6BFF and red #b42318, hand-drawn boxes with uneven corners and a 3 px ink shadow, Kalam for headings and
  names, Outfit for the rest (ship both fonts, SIL OFL). Gentle motion; hold still with prefers-reduced-motion.
- Plain, short, friendly English. No ads, purchases or tracking. Only your own assets or properly licensed ones,
  each recorded in the README.

When done, give me: the repo layout, how to run it locally, how you tested it (phone size, local mode, a two-player
room through https://ikirmikir.com/developers/test/), and the list Maruf needs: title, tagline, description, how to
play, controls, players, orientation, boards (id, name, order, highest score, most per second and why) and badges.
```

### Ludo capture cosmetics

The platform shop offers three optional, cosmetic-only Ludo captures. Volley Kick is the free fallback. `ik.player.get()` and the `player` event may include `capture` for Ludo (`ludo` / the existing `ludo-para` listing): `ludo-lob`, `ludo-bank`, `ludo-hatch`, or null. No ownership list, balance or account ID is sent to the game.

For rooms, use the capturing seat's entry in `room.players`, not the local viewer's profile. Its optional `capture` field is populated by the API after validating the session and purchase. Client room messages, query parameters and headers cannot select paid effects. The selection is fixed when joining a table, including reconnects; equip a different effect before joining a new table. Missing or unknown values mean Volley Kick. Animations must not change outcomes, dice, movement, rewards or legal actions, and must support reduced motion and cancellation. This is an additive field compatible with existing SDK 1.3.1 consumers; never edit a game's copied SDK.
