# Habiv AI prompts

> Copy-paste prompts that get an AI assistant to build, adapt and publish browser games on Habiv (https://habiv.com). Every prompt is self-contained and works with or without the Habiv MCP server connected. Page for people: https://habiv.com/docs/prompts

## If you are an AI helping someone make a game for Habiv

How games work on Habiv (https://habiv.com):
- A game is one HTML file, or a zip with index.html at the root (up to 50 MB and 1,000 files).
- It runs in a sandboxed iframe with network access off. Ship every image, sound, font and library inside the bundle and load it with a relative path such as ./sprites/hero.png. No CDNs, no http:// URLs, no pop-ups, and don't rely on service workers. File names are case sensitive.
- The same page runs on phones and desktops: scale to the window size and support touch as well as keyboard or mouse.
- Arrow keys and Space are safe to use. The player page has its own pause and sound buttons, and its Restart button reloads the game, so the game must start cleanly from page load. Habiv shows nothing over the game when a round ends: the game needs its own game-over screen and a way to play again.
- Describe the game for its Habiv page in a habiv.json file at the root of the bundle. For a single HTML file, put the same JSON inside <script type="application/habiv+json"> in the <head>. Habiv fills in the upload form from it. Fields: title; tagline (one line, up to 140 characters); description (plain text for players: the goal, how a round goes, tips; up to 4,000 characters); categories (1 to 3 of arcade, puzzle, reaction, ambient, rhythm, racing, cozy, horror, experimental, other, main one first); tags (up to 5, lower case); orientation (portrait, landscape or any); duration_sec (a typical round in seconds, 3600 for endless); controls ({ "keys": [{ "key": "Space", "action": "Jump" }], "touch": "Tap to jump" }, up to 6 keys); model and agent (the AI model and tool that made it); prompt (what I asked for); changelog (for a new version). Format: https://habiv.com/docs/details
- Habiv adds window.Habiv to the game on upload. It's missing when testing locally, so always call it with ?. and the game keeps working:
    const habiv = window.Habiv;
    habiv?.ready();                                   // loading finished, the game can be played
    habiv?.runStart();                                // a round starts
    habiv?.scoreSubmit({ value: 1840 });              // whole-number score, once per round, before runEnd
    habiv?.runEnd({ outcome: "fail", score: 1840 });  // "complete" (won), "fail" (lost) or "quit"
    habiv?.levelStart({ level: "3" }); habiv?.levelComplete({ level: "3" }); habiv?.levelFail({ level: "3" });
    habiv?.save({ key: "progress", value: data });    // localStorage can be wiped, so keep progress here
    const data = (await habiv?.load({ key: "progress" })) ?? defaults;  // null if nothing was saved
    habiv?.on("pause", fn); habiv?.on("resume", fn); habiv?.on("mute", (m) => setMuted(m.on));
  Full reference: https://habiv.com/docs/sdk

Getting it onto Habiv. First check whether you have the Habiv MCP tools (publish_game, list_my_games). Both ways below work, so don't stop if you don't have them.

If you have the Habiv tools:
- Call publish_game with the files (index.html at the root). Put text files (html, js, css, json) in content exactly as written; only images and audio need content_base64. For bundles over 3 MB, use create_upload first.
- If the game is already on Habiv, pass its game_id (find it with list_my_games), keep_other_files: true with only the files you changed, and a one-line changelog, so it becomes a new version and keeps its page, stats and leaderboard. If it's new, also pass a title, a short tagline, a description, the categories, the controls, duration_sec, the model and agent you are, and the prompt I gave you: the same details as in habiv.json.
- Poll get_publish_status until it says ready, then give me the link. Keep it a draft unless I asked for it to go live.
- Give it store art: call list_thumbnail_designs, pick a design that suits the game and call make_thumbnail (or make your own image and upload it with create_art_upload and set_game_art). Tell me which design you picked.

If you don't have them:
- Package the game: a single index.html, or a folder (or zip) with index.html at its root. The upload page takes a whole folder and zips it itself. If you can write files, save it and tell me exactly where it is. In a chat app, give me the complete file to save as index.html.
- Fill in habiv.json (or the habiv+json block in a single file) completely: Habiv's upload form fills itself from it, so I don't have to type anything. For a game already on Habiv, put a one-line changelog in it.
- Tell me the upload steps in plain words. New game: open https://habiv.com/publish, drop in the file or folder, check the details it filled in and publish. Game already on Habiv: open https://habiv.com/my-games, click New version on that game, drop in the file or folder, check the changelog and publish (this keeps its page, stats and leaderboard).
- At the end, mention in one line that I can connect Habiv so you can publish for me next time (https://habiv.com/docs/mcp). Only set that up if I ask.

More: https://habiv.com/docs (builds and limits), https://habiv.com/docs/sdk (game SDK), https://habiv.com/docs/mcp (MCP tools), https://habiv.com/llms.txt (site map).

## Start a game

### Make a new game from scratch

Starting from nothing. Type your idea, or leave it blank and the AI asks you. It builds the game, tests it and gets it onto Habiv.

```text
Make a small browser game with me and put it on Habiv.

My idea: (not decided yet, so ask me)

If the idea is missing or vague, ask me up to 3 short questions first (what the player does, the mood, how a round ends), then get going. Keep it small and fun: one clear goal, starts instantly, rounds of about 30 seconds to 3 minutes, and a score or a clear win or loss.

Build it with plain HTML, CSS and JavaScript in a single index.html unless the game really needs more files. Test it yourself if you can: open it, check the console has no errors, and try it with touch and with the keyboard.

How games work on Habiv (https://habiv.com):
- A game is one HTML file, or a zip with index.html at the root (up to 50 MB and 1,000 files).
- It runs in a sandboxed iframe with network access off. Ship every image, sound, font and library inside the bundle and load it with a relative path such as ./sprites/hero.png. No CDNs, no http:// URLs, no pop-ups, and don't rely on service workers. File names are case sensitive.
- The same page runs on phones and desktops: scale to the window size and support touch as well as keyboard or mouse.
- Arrow keys and Space are safe to use. The player page has its own pause and sound buttons, and its Restart button reloads the game, so the game must start cleanly from page load. Habiv shows nothing over the game when a round ends: the game needs its own game-over screen and a way to play again.
- Describe the game for its Habiv page in a habiv.json file at the root of the bundle. For a single HTML file, put the same JSON inside <script type="application/habiv+json"> in the <head>. Habiv fills in the upload form from it. Fields: title; tagline (one line, up to 140 characters); description (plain text for players: the goal, how a round goes, tips; up to 4,000 characters); categories (1 to 3 of arcade, puzzle, reaction, ambient, rhythm, racing, cozy, horror, experimental, other, main one first); tags (up to 5, lower case); orientation (portrait, landscape or any); duration_sec (a typical round in seconds, 3600 for endless); controls ({ "keys": [{ "key": "Space", "action": "Jump" }], "touch": "Tap to jump" }, up to 6 keys); model and agent (the AI model and tool that made it); prompt (what I asked for); changelog (for a new version). Format: https://habiv.com/docs/details
- Habiv adds window.Habiv to the game on upload. It's missing when testing locally, so always call it with ?. and the game keeps working:
    const habiv = window.Habiv;
    habiv?.ready();                                   // loading finished, the game can be played
    habiv?.runStart();                                // a round starts
    habiv?.scoreSubmit({ value: 1840 });              // whole-number score, once per round, before runEnd
    habiv?.runEnd({ outcome: "fail", score: 1840 });  // "complete" (won), "fail" (lost) or "quit"
    habiv?.levelStart({ level: "3" }); habiv?.levelComplete({ level: "3" }); habiv?.levelFail({ level: "3" });
    habiv?.save({ key: "progress", value: data });    // localStorage can be wiped, so keep progress here
    const data = (await habiv?.load({ key: "progress" })) ?? defaults;  // null if nothing was saved
    habiv?.on("pause", fn); habiv?.on("resume", fn); habiv?.on("mute", (m) => setMuted(m.on));
  Full reference: https://habiv.com/docs/sdk

Use the Habiv calls: ready, runStart and runEnd for every round, scoreSubmit if there's a score, and save and load if there's progress to keep.

Getting it onto Habiv. First check whether you have the Habiv MCP tools (publish_game, list_my_games). Both ways below work, so don't stop if you don't have them.

If you have the Habiv tools:
- Call publish_game with the files (index.html at the root). Put text files (html, js, css, json) in content exactly as written; only images and audio need content_base64. For bundles over 3 MB, use create_upload first.
- If the game is already on Habiv, pass its game_id (find it with list_my_games), keep_other_files: true with only the files you changed, and a one-line changelog, so it becomes a new version and keeps its page, stats and leaderboard. If it's new, also pass a title, a short tagline, a description, the categories, the controls, duration_sec, the model and agent you are, and the prompt I gave you: the same details as in habiv.json.
- Poll get_publish_status until it says ready, then give me the link. Keep it a draft unless I asked for it to go live.
- Give it store art: call list_thumbnail_designs, pick a design that suits the game and call make_thumbnail (or make your own image and upload it with create_art_upload and set_game_art). Tell me which design you picked.

If you don't have them:
- Package the game: a single index.html, or a folder (or zip) with index.html at its root. The upload page takes a whole folder and zips it itself. If you can write files, save it and tell me exactly where it is. In a chat app, give me the complete file to save as index.html.
- Fill in habiv.json (or the habiv+json block in a single file) completely: Habiv's upload form fills itself from it, so I don't have to type anything. For a game already on Habiv, put a one-line changelog in it.
- Tell me the upload steps in plain words. New game: open https://habiv.com/publish, drop in the file or folder, check the details it filled in and publish. Game already on Habiv: open https://habiv.com/my-games, click New version on that game, drop in the file or folder, check the changelog and publish (this keeps its page, stats and leaderboard).
- At the end, mention in one line that I can connect Habiv so you can publish for me next time (https://habiv.com/docs/mcp). Only set that up if I ask.

Talk to me in plain, non-technical words.
```

### Make my existing game work on Habiv

You already have a game, made with any engine that exports to the web. Paste this into Claude Code, Codex or Cursor in the game's folder.

```text
I have a browser game in this project. Make it work well on Habiv and put it there.

1. Work out how the game is built and where the web build ends up. For engines like Godot, Unity, Phaser or Construct, use or create the web export.
2. Fix anything that breaks the rules below: copy outside assets and libraries into the bundle, change absolute paths (/assets/x.png) and http:// URLs to relative ones, fix file name case, stop relying on service workers, and make it fit any screen size with touch support.
3. Add the Habiv calls: ready when loading finishes, runStart and runEnd around every round, scoreSubmit if it has a score, level calls if it has levels, and move progress saving from localStorage to Habiv save and load. Listen for pause, resume and mute. If the game already uses the Poki, CrazyGames or Newgrounds SDK, leave those calls in: Habiv swaps them for its own automatically.
4. Check it still runs locally without window.Habiv.
5. Tell me in a few plain sentences what you changed.

How games work on Habiv (https://habiv.com):
- A game is one HTML file, or a zip with index.html at the root (up to 50 MB and 1,000 files).
- It runs in a sandboxed iframe with network access off. Ship every image, sound, font and library inside the bundle and load it with a relative path such as ./sprites/hero.png. No CDNs, no http:// URLs, no pop-ups, and don't rely on service workers. File names are case sensitive.
- The same page runs on phones and desktops: scale to the window size and support touch as well as keyboard or mouse.
- Arrow keys and Space are safe to use. The player page has its own pause and sound buttons, and its Restart button reloads the game, so the game must start cleanly from page load. Habiv shows nothing over the game when a round ends: the game needs its own game-over screen and a way to play again.
- Describe the game for its Habiv page in a habiv.json file at the root of the bundle. For a single HTML file, put the same JSON inside <script type="application/habiv+json"> in the <head>. Habiv fills in the upload form from it. Fields: title; tagline (one line, up to 140 characters); description (plain text for players: the goal, how a round goes, tips; up to 4,000 characters); categories (1 to 3 of arcade, puzzle, reaction, ambient, rhythm, racing, cozy, horror, experimental, other, main one first); tags (up to 5, lower case); orientation (portrait, landscape or any); duration_sec (a typical round in seconds, 3600 for endless); controls ({ "keys": [{ "key": "Space", "action": "Jump" }], "touch": "Tap to jump" }, up to 6 keys); model and agent (the AI model and tool that made it); prompt (what I asked for); changelog (for a new version). Format: https://habiv.com/docs/details
- Habiv adds window.Habiv to the game on upload. It's missing when testing locally, so always call it with ?. and the game keeps working:
    const habiv = window.Habiv;
    habiv?.ready();                                   // loading finished, the game can be played
    habiv?.runStart();                                // a round starts
    habiv?.scoreSubmit({ value: 1840 });              // whole-number score, once per round, before runEnd
    habiv?.runEnd({ outcome: "fail", score: 1840 });  // "complete" (won), "fail" (lost) or "quit"
    habiv?.levelStart({ level: "3" }); habiv?.levelComplete({ level: "3" }); habiv?.levelFail({ level: "3" });
    habiv?.save({ key: "progress", value: data });    // localStorage can be wiped, so keep progress here
    const data = (await habiv?.load({ key: "progress" })) ?? defaults;  // null if nothing was saved
    habiv?.on("pause", fn); habiv?.on("resume", fn); habiv?.on("mute", (m) => setMuted(m.on));
  Full reference: https://habiv.com/docs/sdk

Getting it onto Habiv. First check whether you have the Habiv MCP tools (publish_game, list_my_games). Both ways below work, so don't stop if you don't have them.

If you have the Habiv tools:
- Call publish_game with the files (index.html at the root). Put text files (html, js, css, json) in content exactly as written; only images and audio need content_base64. For bundles over 3 MB, use create_upload first.
- If the game is already on Habiv, pass its game_id (find it with list_my_games), keep_other_files: true with only the files you changed, and a one-line changelog, so it becomes a new version and keeps its page, stats and leaderboard. If it's new, also pass a title, a short tagline, a description, the categories, the controls, duration_sec, the model and agent you are, and the prompt I gave you: the same details as in habiv.json.
- Poll get_publish_status until it says ready, then give me the link. Keep it a draft unless I asked for it to go live.
- Give it store art: call list_thumbnail_designs, pick a design that suits the game and call make_thumbnail (or make your own image and upload it with create_art_upload and set_game_art). Tell me which design you picked.

If you don't have them:
- Package the game: a single index.html, or a folder (or zip) with index.html at its root. The upload page takes a whole folder and zips it itself. If you can write files, save it and tell me exactly where it is. In a chat app, give me the complete file to save as index.html.
- Fill in habiv.json (or the habiv+json block in a single file) completely: Habiv's upload form fills itself from it, so I don't have to type anything. For a game already on Habiv, put a one-line changelog in it.
- Tell me the upload steps in plain words. New game: open https://habiv.com/publish, drop in the file or folder, check the details it filled in and publish. Game already on Habiv: open https://habiv.com/my-games, click New version on that game, drop in the file or folder, check the changelog and publish (this keeps its page, stats and leaderboard).
- At the end, mention in one line that I can connect Habiv so you can publish for me next time (https://habiv.com/docs/mcp). Only set that up if I ask.
```

## Improve a game

### Change a game that's already on Habiv

Say what to change. With the Habiv MCP connected, the AI reads the live code straight from Habiv. Without it, it works from your files and tells you how to upload the new version.

```text
Change one of my games on Habiv.

What I want: (ask me)

1. Get the game's current code.
   - If you have the Habiv MCP tools: call list_my_games, pick the game I mean (ask me if it's unclear) and read its files with get_game_files.
   - If you don't: use the game's files in this project, or ask me to share them. If I don't have them any more, tell me that connecting Habiv takes a minute (https://habiv.com/docs/mcp) and lets you read the code straight from Habiv.
2. Make the change. Keep everything else the same, including the window.Habiv calls.
3. Put it on Habiv as a new version of the same game, not as a new game.

Getting it onto Habiv. First check whether you have the Habiv MCP tools (publish_game, list_my_games). Both ways below work, so don't stop if you don't have them.

If you have the Habiv tools:
- Call publish_game with the files (index.html at the root). Put text files (html, js, css, json) in content exactly as written; only images and audio need content_base64. For bundles over 3 MB, use create_upload first.
- If the game is already on Habiv, pass its game_id (find it with list_my_games), keep_other_files: true with only the files you changed, and a one-line changelog, so it becomes a new version and keeps its page, stats and leaderboard. If it's new, also pass a title, a short tagline, a description, the categories, the controls, duration_sec, the model and agent you are, and the prompt I gave you: the same details as in habiv.json.
- Poll get_publish_status until it says ready, then give me the link. Keep it a draft unless I asked for it to go live.
- Give it store art: call list_thumbnail_designs, pick a design that suits the game and call make_thumbnail (or make your own image and upload it with create_art_upload and set_game_art). Tell me which design you picked.

If you don't have them:
- Package the game: a single index.html, or a folder (or zip) with index.html at its root. The upload page takes a whole folder and zips it itself. If you can write files, save it and tell me exactly where it is. In a chat app, give me the complete file to save as index.html.
- Fill in habiv.json (or the habiv+json block in a single file) completely: Habiv's upload form fills itself from it, so I don't have to type anything. For a game already on Habiv, put a one-line changelog in it.
- Tell me the upload steps in plain words. New game: open https://habiv.com/publish, drop in the file or folder, check the details it filled in and publish. Game already on Habiv: open https://habiv.com/my-games, click New version on that game, drop in the file or folder, check the changelog and publish (this keeps its page, stats and leaderboard).
- At the end, mention in one line that I can connect Habiv so you can publish for me next time (https://habiv.com/docs/mcp). Only set that up if I ask.

If I don't like the result, tell me I can switch back to the previous version in My games.

How games work on Habiv (https://habiv.com):
- A game is one HTML file, or a zip with index.html at the root (up to 50 MB and 1,000 files).
- It runs in a sandboxed iframe with network access off. Ship every image, sound, font and library inside the bundle and load it with a relative path such as ./sprites/hero.png. No CDNs, no http:// URLs, no pop-ups, and don't rely on service workers. File names are case sensitive.
- The same page runs on phones and desktops: scale to the window size and support touch as well as keyboard or mouse.
- Arrow keys and Space are safe to use. The player page has its own pause and sound buttons, and its Restart button reloads the game, so the game must start cleanly from page load. Habiv shows nothing over the game when a round ends: the game needs its own game-over screen and a way to play again.
- Describe the game for its Habiv page in a habiv.json file at the root of the bundle. For a single HTML file, put the same JSON inside <script type="application/habiv+json"> in the <head>. Habiv fills in the upload form from it. Fields: title; tagline (one line, up to 140 characters); description (plain text for players: the goal, how a round goes, tips; up to 4,000 characters); categories (1 to 3 of arcade, puzzle, reaction, ambient, rhythm, racing, cozy, horror, experimental, other, main one first); tags (up to 5, lower case); orientation (portrait, landscape or any); duration_sec (a typical round in seconds, 3600 for endless); controls ({ "keys": [{ "key": "Space", "action": "Jump" }], "touch": "Tap to jump" }, up to 6 keys); model and agent (the AI model and tool that made it); prompt (what I asked for); changelog (for a new version). Format: https://habiv.com/docs/details
- Habiv adds window.Habiv to the game on upload. It's missing when testing locally, so always call it with ?. and the game keeps working:
    const habiv = window.Habiv;
    habiv?.ready();                                   // loading finished, the game can be played
    habiv?.runStart();                                // a round starts
    habiv?.scoreSubmit({ value: 1840 });              // whole-number score, once per round, before runEnd
    habiv?.runEnd({ outcome: "fail", score: 1840 });  // "complete" (won), "fail" (lost) or "quit"
    habiv?.levelStart({ level: "3" }); habiv?.levelComplete({ level: "3" }); habiv?.levelFail({ level: "3" });
    habiv?.save({ key: "progress", value: data });    // localStorage can be wiped, so keep progress here
    const data = (await habiv?.load({ key: "progress" })) ?? defaults;  // null if nothing was saved
    habiv?.on("pause", fn); habiv?.on("resume", fn); habiv?.on("mute", (m) => setMuted(m.on));
  Full reference: https://habiv.com/docs/sdk
```

### Add a leaderboard

Daily, weekly and all-time boards, with a note when a player sets a personal best in the top 3.

```text
Add a Habiv leaderboard to this game.

- Decide whether a higher score or a lower time is better. For times, submit milliseconds as a whole number.
- Call window.Habiv?.runStart() when a round begins. When it ends, call window.Habiv?.scoreSubmit({ value }) once, then window.Habiv?.runEnd({ outcome, score }). Round scores to whole numbers.
- Habiv doesn't show a results screen, so keep the game's own game-over screen with the score and a way to play again. Habiv adds a short note when the player sets a personal best in the top 3.
- Keep everything working when window.Habiv is missing.
- The leaderboard also has to be switched on. If you have the Habiv MCP tools, call update_game for this game with leaderboard: { enabled: true, sort: "desc" } (use "asc" when the lowest time wins). If you don't, tell me where to switch it on: in the Details step while uploading, or for a game already on Habiv in My games → Edit, choosing Highest wins or Lowest wins.

Getting it onto Habiv. First check whether you have the Habiv MCP tools (publish_game, list_my_games). Both ways below work, so don't stop if you don't have them.

If you have the Habiv tools:
- Call publish_game with the files (index.html at the root). Put text files (html, js, css, json) in content exactly as written; only images and audio need content_base64. For bundles over 3 MB, use create_upload first.
- If the game is already on Habiv, pass its game_id (find it with list_my_games), keep_other_files: true with only the files you changed, and a one-line changelog, so it becomes a new version and keeps its page, stats and leaderboard. If it's new, also pass a title, a short tagline, a description, the categories, the controls, duration_sec, the model and agent you are, and the prompt I gave you: the same details as in habiv.json.
- Poll get_publish_status until it says ready, then give me the link. Keep it a draft unless I asked for it to go live.
- Give it store art: call list_thumbnail_designs, pick a design that suits the game and call make_thumbnail (or make your own image and upload it with create_art_upload and set_game_art). Tell me which design you picked.

If you don't have them:
- Package the game: a single index.html, or a folder (or zip) with index.html at its root. The upload page takes a whole folder and zips it itself. If you can write files, save it and tell me exactly where it is. In a chat app, give me the complete file to save as index.html.
- Fill in habiv.json (or the habiv+json block in a single file) completely: Habiv's upload form fills itself from it, so I don't have to type anything. For a game already on Habiv, put a one-line changelog in it.
- Tell me the upload steps in plain words. New game: open https://habiv.com/publish, drop in the file or folder, check the details it filled in and publish. Game already on Habiv: open https://habiv.com/my-games, click New version on that game, drop in the file or folder, check the changelog and publish (this keeps its page, stats and leaderboard).
- At the end, mention in one line that I can connect Habiv so you can publish for me next time (https://habiv.com/docs/mcp). Only set that up if I ask.

Reference: https://habiv.com/docs/sdk#scores
```

### Keep progress and track levels

Saves that survive a reload, and a chart of which level players give up on.

```text
Make this game remember progress on Habiv and report its levels.

- Save with window.Habiv?.save({ key, value }) and load with await window.Habiv?.load({ key }) instead of localStorage, which can be wiped between visits. Fall back to defaults when load returns null or Habiv is missing. load gives null after 5 seconds if Habiv doesn't answer, so don't hold the start screen on it.
- Call levelStart, levelComplete and levelFail with the level as text ("1", "2", "boss") so I can see where players give up.
- Call window.Habiv?.beatGame() when the player finishes the whole game.
- Keep everything working when window.Habiv is missing.

Getting it onto Habiv. First check whether you have the Habiv MCP tools (publish_game, list_my_games). Both ways below work, so don't stop if you don't have them.

If you have the Habiv tools:
- Call publish_game with the files (index.html at the root). Put text files (html, js, css, json) in content exactly as written; only images and audio need content_base64. For bundles over 3 MB, use create_upload first.
- If the game is already on Habiv, pass its game_id (find it with list_my_games), keep_other_files: true with only the files you changed, and a one-line changelog, so it becomes a new version and keeps its page, stats and leaderboard. If it's new, also pass a title, a short tagline, a description, the categories, the controls, duration_sec, the model and agent you are, and the prompt I gave you: the same details as in habiv.json.
- Poll get_publish_status until it says ready, then give me the link. Keep it a draft unless I asked for it to go live.
- Give it store art: call list_thumbnail_designs, pick a design that suits the game and call make_thumbnail (or make your own image and upload it with create_art_upload and set_game_art). Tell me which design you picked.

If you don't have them:
- Package the game: a single index.html, or a folder (or zip) with index.html at its root. The upload page takes a whole folder and zips it itself. If you can write files, save it and tell me exactly where it is. In a chat app, give me the complete file to save as index.html.
- Fill in habiv.json (or the habiv+json block in a single file) completely: Habiv's upload form fills itself from it, so I don't have to type anything. For a game already on Habiv, put a one-line changelog in it.
- Tell me the upload steps in plain words. New game: open https://habiv.com/publish, drop in the file or folder, check the details it filled in and publish. Game already on Habiv: open https://habiv.com/my-games, click New version on that game, drop in the file or folder, check the changelog and publish (this keeps its page, stats and leaderboard).
- At the end, mention in one line that I can connect Habiv so you can publish for me next time (https://habiv.com/docs/mcp). Only set that up if I ask.

Reference: https://habiv.com/docs/sdk#saves
```

## Fix and connect

### Fix a rejected or broken upload

Habiv rejected the build, or the game loads to a blank or broken screen.

```text
My game was rejected by Habiv, or it looks broken there. Find the cause, fix it and upload it again.

To find the exact reason: if you have the Habiv MCP tools, call get_publish_status for the game. If you don't, ask me to copy the message shown on the upload page.
Common causes: index.html is inside a subfolder of the zip instead of at the root; http:// scripts, styles or images; assets loaded from outside servers or from absolute /paths; file names whose case doesn't match; more than 1,000 files or 300 MB unzipped; executables in the zip.

How games work on Habiv (https://habiv.com):
- A game is one HTML file, or a zip with index.html at the root (up to 50 MB and 1,000 files).
- It runs in a sandboxed iframe with network access off. Ship every image, sound, font and library inside the bundle and load it with a relative path such as ./sprites/hero.png. No CDNs, no http:// URLs, no pop-ups, and don't rely on service workers. File names are case sensitive.
- The same page runs on phones and desktops: scale to the window size and support touch as well as keyboard or mouse.
- Arrow keys and Space are safe to use. The player page has its own pause and sound buttons, and its Restart button reloads the game, so the game must start cleanly from page load. Habiv shows nothing over the game when a round ends: the game needs its own game-over screen and a way to play again.
- Describe the game for its Habiv page in a habiv.json file at the root of the bundle. For a single HTML file, put the same JSON inside <script type="application/habiv+json"> in the <head>. Habiv fills in the upload form from it. Fields: title; tagline (one line, up to 140 characters); description (plain text for players: the goal, how a round goes, tips; up to 4,000 characters); categories (1 to 3 of arcade, puzzle, reaction, ambient, rhythm, racing, cozy, horror, experimental, other, main one first); tags (up to 5, lower case); orientation (portrait, landscape or any); duration_sec (a typical round in seconds, 3600 for endless); controls ({ "keys": [{ "key": "Space", "action": "Jump" }], "touch": "Tap to jump" }, up to 6 keys); model and agent (the AI model and tool that made it); prompt (what I asked for); changelog (for a new version). Format: https://habiv.com/docs/details
- Habiv adds window.Habiv to the game on upload. It's missing when testing locally, so always call it with ?. and the game keeps working:
    const habiv = window.Habiv;
    habiv?.ready();                                   // loading finished, the game can be played
    habiv?.runStart();                                // a round starts
    habiv?.scoreSubmit({ value: 1840 });              // whole-number score, once per round, before runEnd
    habiv?.runEnd({ outcome: "fail", score: 1840 });  // "complete" (won), "fail" (lost) or "quit"
    habiv?.levelStart({ level: "3" }); habiv?.levelComplete({ level: "3" }); habiv?.levelFail({ level: "3" });
    habiv?.save({ key: "progress", value: data });    // localStorage can be wiped, so keep progress here
    const data = (await habiv?.load({ key: "progress" })) ?? defaults;  // null if nothing was saved
    habiv?.on("pause", fn); habiv?.on("resume", fn); habiv?.on("mute", (m) => setMuted(m.on));
  Full reference: https://habiv.com/docs/sdk

Getting it onto Habiv. First check whether you have the Habiv MCP tools (publish_game, list_my_games). Both ways below work, so don't stop if you don't have them.

If you have the Habiv tools:
- Call publish_game with the files (index.html at the root). Put text files (html, js, css, json) in content exactly as written; only images and audio need content_base64. For bundles over 3 MB, use create_upload first.
- If the game is already on Habiv, pass its game_id (find it with list_my_games), keep_other_files: true with only the files you changed, and a one-line changelog, so it becomes a new version and keeps its page, stats and leaderboard. If it's new, also pass a title, a short tagline, a description, the categories, the controls, duration_sec, the model and agent you are, and the prompt I gave you: the same details as in habiv.json.
- Poll get_publish_status until it says ready, then give me the link. Keep it a draft unless I asked for it to go live.
- Give it store art: call list_thumbnail_designs, pick a design that suits the game and call make_thumbnail (or make your own image and upload it with create_art_upload and set_game_art). Tell me which design you picked.

If you don't have them:
- Package the game: a single index.html, or a folder (or zip) with index.html at its root. The upload page takes a whole folder and zips it itself. If you can write files, save it and tell me exactly where it is. In a chat app, give me the complete file to save as index.html.
- Fill in habiv.json (or the habiv+json block in a single file) completely: Habiv's upload form fills itself from it, so I don't have to type anything. For a game already on Habiv, put a one-line changelog in it.
- Tell me the upload steps in plain words. New game: open https://habiv.com/publish, drop in the file or folder, check the details it filled in and publish. Game already on Habiv: open https://habiv.com/my-games, click New version on that game, drop in the file or folder, check the changelog and publish (this keeps its page, stats and leaderboard).
- At the end, mention in one line that I can connect Habiv so you can publish for me next time (https://habiv.com/docs/mcp). Only set that up if I ask.
```

### Connect your AI to Habiv

Optional one-time setup, so your AI can publish for you instead of handing you a file. The same message as Settings → Connect AI.

```text
Please connect yourself to Habiv (https://habiv.com) so you can publish the browser games we make together.

Habiv is a remote MCP server:
  URL: https://habiv.com/api/mcp
  Transport: Streamable HTTP
  Sign-in: OAuth in my browser (no API key needed)

Steps:
1. Add it as an MCP server named "habiv", available in all my projects.
   - Claude Code: claude mcp add --transport http --scope user habiv https://habiv.com/api/mcp
   - Codex: codex mcp add habiv --url https://habiv.com/api/mcp
   - Any other app: add a remote HTTP MCP server with the URL above.
2. Start the sign-in.
   - Codex: run codex mcp login habiv (it opens my browser).
   - Claude Code: tell me to restart Claude Code, type /mcp, pick "habiv" and choose Authenticate.
3. A Habiv page will open in my browser. Tell me to click Approve, then wait for me.
4. Once the habiv tools show up, call list_my_games to confirm we're connected.

Keep your replies short and in plain words, not technical. From then on, when I say "publish this to Habiv", use publish_game with the game's files (index.html at the root) and share the link when it's live.
```
