Creator guide

You are helping me publish this web game on Gamero (a weekly game-jam site). Set up the project so that `npm run build` produces a ready-to-upload `gamero.zip` in the project root. When I upload that ZIP, Gamero unpacks the game AND reads a `screens/` folder that fills in the WHOLE game page: title, tagline, genre, controls, cover, screenshots, description, how-to-play. Naming must follow the rules below exactly; anything unexpected makes the upload fail.

I'm entering the challenge "Best strategy game". It requires "category": "Strategy". Its requirements:
- Must be a strategy game – decisions and planning should matter more than reflexes
- Playable in the browser on both mobile (portrait) and desktop
- One full session should take 2–10 minutes
- Include a short "How to play" screen or tutorial
- Original work created or substantially updated during the challenge week
- No external logins, ads or in-app purchases
- Submit by 14.11, 00:00 – late entries won't be accepted
Use "challengeNotes" in game.json to explain how the game fits.

## 1. The build
- Keep the existing build (Vite, webpack, Phaser template, plain HTML…). Its output folder (e.g. `dist/`) must contain `index.html` at its root.
- All asset paths must be RELATIVE (for Vite set `base: "./"`). The game is served from a sub-path inside a sandboxed iframe: no cookies, no popups, no access to the parent page, no server-side code.
- Total size: ZIP max 100 MB, unpacked max 200 MB, max 3000 files. No .exe/.dll/.sh/.php/.py/.jar or other executable/server files.
- It must work on phones: touch input, resize-aware canvas, no hover-only controls.

## 2. The screens/ folder
Create a `screens/` folder in the PROJECT ROOT (not in public/ or the build output) and commit it. No subfolders. Images: PNG, JPG, WebP or GIF, max 5 MB each. Allowed files:

| File | Used for | Rules |
|---|---|---|
| `game.json` | All game details (see section 3) | Required for the first upload. |
| `cover.png` | Card image + page header | 16:9, at least 630×354 (ideally 1280×720). Center-cropped to 16:9. No important content near the edges. |
| `screenshot-1.png` … `screenshot-8.png` | Screenshot gallery | Ordered by the number. Longest side 320–1920 px. Optional caption after the number in lowercase-kebab-case: `screenshot-2-boss-fight.png` → caption "Boss fight". |
| `preview.mp4` or `preview.webm` | Optional hover clip on the game card | MP4 (H.264) or WebM, 16:9, max 8 MB; 5–10 seconds of real gameplay, no sound needed (it plays muted and loops). Not a QuickTime .mov. |
| `description.md` | "About" section | Markdown, max 10 000 characters. What the game is, what makes it fun. Don't repeat the title as a heading. |
| `description-1.png`, `description-2.png` … | Pictures inside the description | Max 10. Reference them as `![alt text](description-1.png)`; any picture you don't reference is appended at the end. |
| `how-to-play.md` | "How to play" section | Markdown, max 3 000 characters. Goal + controls for EVERY supported input (touch, keyboard, mouse, gamepad). |
| `how-to-play-1.png` … | Pictures inside the instructions | Max 10, e.g. a controls diagram. Reference as `![Controls](how-to-play-1.png)`. |

Markdown: no raw HTML, no external images (they are not shown; only screens/ pictures are), links are fine. Keep sentences short; players skim.

Images: use REAL gameplay captures, not mock-ups. If you can run the game, use Playwright (or a similar headless browser) against the built game to capture the cover and 3–5 screenshots of different, interesting moments at 1280×720 (plus a portrait 720×1280 shot if the game supports portrait). If you can't capture them, tell me exactly which shots to take; don't invent placeholder art.

## 3. screens/game.json
A JSON object. Every property is optional except "title" and "tagline" on the first upload; a property you leave out keeps its current value on the site. Unknown properties are rejected (so don't put the description in here; it goes in description.md).

- "title": string, max 100.
- "tagline": string, max 120, one punchy line shown on the game card.
- "theme": one of "Abstract / Minimal", "Alien invasion", "Ancient Egypt", "Ancient Rome / Greece", "Animals", "Arabian Nights", "Arctic", "Autumn", "Aviation", "Aztec / Maya", "Biopunk", "Cars / Racing", "Castle", "Cave / Underground", "Christmas", "Circus / Carnival", "City / Urban", "Claymation", "Comic book", "Countryside", "Cute / Cozy", "Cyberpunk", "Desert", "Detective / Mystery", "Dieselpunk", "Dinosaurs", "Dragons", "Dreams / Surreal", "Dungeon", "Easter", "Factory / Automation", "Fairy tale", "Fantasy", "Farm", "Feudal Japan", "Food / Candy", "Forest", "Garden", "Ghosts / Haunted", "Halloween", "Hand-drawn", "Heist / Crime", "Horror", "Hospital", "Industrial", "Insects / Bugs", "Island / Tropical", "Jungle", "Kitchen / Cooking", "Low poly", "Magic / Wizards", "Medieval", "Microscopic / Cells", "Military / War", "Mining", "Monochrome", "Monsters", "Music / Concert", "Mythology", "Nature", "Neon / Synthwave", "Ninja / Samurai", "Noir", "Ocean / Sea life", "Office", "Paper / Cardboard", "Pirates", "Pixel art", "Post-apocalyptic", "Prehistoric", "Retro / 8-bit", "Robots", "School", "Sci-fi", "Sky / Clouds", "Solarpunk", "Space", "Sports", "Spring", "Spy / Espionage", "Steampunk", "Suburbia", "Summer", "Superheroes", "Time travel", "Toys", "Trains", "Underwater", "Valentine's", "Vampires", "Victorian", "Vikings", "Volcano", "Voxel", "Watercolor", "Weather / Storms", "Western", "Winter / Holidays", "Witches", "Zombies".
- "category" and "subCategory": pick the category, then optionally one of its sub-categories:
- "Action": "Platform", "Shooter", "First-person shooter", "Third-person shooter", "Shoot 'em up", "Light gun", "Hero shooter", "Arena shooter", "Fighting", "Beat 'em up", "Hack and slash", "Stealth", "Survival", "Rhythm", "Battle royale"
- "Action-adventure": "Survival horror", "Metroidvania", "Soulslike", "Immersive sim"
- "Adventure": "Text adventure", "Graphic adventure", "Point-and-click", "Visual novel", "Interactive movie", "Real-time 3D adventure", "Walking simulator"
- "Puzzle": "Logic", "Tile-matching", "Physics", "Programming", "Hidden object", "Escape room", "Breakout clone", "Trivia"
- "Role-playing": "Action RPG", "MMORPG", "Roguelike", "Roguelite", "Tactical RPG", "Sandbox RPG", "First-person party-based RPG", "Monster tamer", "Dungeon crawler"
- "Simulation": "Construction and management", "City-building", "Business / Tycoon", "Colony management", "Life simulation", "Social simulation", "Pet / Virtual pet", "Dating sim", "Vehicle simulation", "Flight simulator", "Space flight", "Farming"
- "Strategy": "4X", "Artillery", "Auto battler", "MOBA", "Real-time strategy", "Real-time tactics", "Tower defense", "Turn-based strategy", "Turn-based tactics", "Wargame", "Grand strategy", "Deck-building / Card"
- "Sports": "Racing", "Team sports", "Individual sports", "Competitive / Esports", "Sports-based fighting"
- "Massively multiplayer": "MMO", "MMORPG", "MMOFPS"
- "Other": "Casual", "Idle / Incremental", "Party", "Sandbox", "Survival", "Horror", "Educational", "Music", "Board game", "Card game", "Hyper-casual", "Endless runner", "Typing", "Exergame"
- "dimension": one of "2D", "2.5D", "3D".
- "tags": up to 10 short lowercase tags, e.g. ["pixel-art", "roguelike"].
- "inputMethods": the inputs the game ACTUALLY supports, any of "Touch", "Keyboard", "Mouse", "Gamepad".
- "orientation": "Any", "Portrait" or "Landscape".
- "contentWarnings": any that apply of "FlashingLights", "Violence", "Gore", "LoudAudio", "Horror"; [] if none.
- "engine": e.g. "Phaser 3", "Godot 4", "Three.js", "Plain JavaScript". Max 100.
- "videoUrl": optional YouTube link. "sourceCodeUrl": optional repo link. Both http(s) URLs.
- "challengeNotes": how the game fits the weekly challenge, markdown, max 3000.
- "credits": team, music, fonts, asset licenses, markdown, max 3000.
- "aiDisclosure": honestly state what AI was used for (code, art, audio, text), max 1000.
- "awards": optional achievements, the FULL list (awards left out are deleted). Each: "key" (lowercase letters, digits, - and _, max 32, unique), "title" (max 60), "description" (max 200), "icon" (one emoji), "secret" (true hides it until unlocked). Max 50.

Example:
{
  "title": "Neon Drift",
  "tagline": "Race through a city that rebuilds itself every lap",
  "theme": "Neon / Synthwave",
  "category": "Sports",
  "subCategory": "Racing",
  "dimension": "2D",
  "tags": ["racing", "arcade", "neon"],
  "inputMethods": ["Touch", "Keyboard", "Gamepad"],
  "orientation": "Landscape",
  "contentWarnings": ["FlashingLights"],
  "engine": "Phaser 3",
  "videoUrl": "https://youtu.be/xxxxxxxxxxx",
  "sourceCodeUrl": "https://github.com/me/neon-drift",
  "challengeNotes": "The track changes shape every lap, which fits this week's theme.",
  "credits": "Music: Jane Doe (CC-BY 4.0)",
  "aiDisclosure": "Code written with Claude Code; all art and music made by hand."
}

Awards example (inside the same object):
"awards": [
  { "key": "first-win", "title": "First win", "description": "Win a round", "icon": "🏆" },
  { "key": "no-hit", "title": "Untouchable", "description": "Clear a level without getting hit", "icon": "🛡️" },
  { "key": "hidden-room", "title": "Explorer", "description": "Find the hidden room", "icon": "🗝️", "secret": true }
]

## 3b. Leaderboards and awards (optional)
If the game has a score, a time or achievements, integrate the Gamero SDK:
- Add `<script src="https://gamero.gg/sdk/gamero.js"></script>` to index.html before the game code. It defines `window.Gamero`.
- Guard every call with `if (window.Gamero?.available)`: outside Gamero (local dev) it is false and calls reject.
- `Gamero.submitScore(value, { board = "main", order = "desc" })` when a run ends. Integers only; for times use milliseconds with order "asc". Only the player's best is kept. Resolves { best, improved, rank, players }.
- `Gamero.getLeaderboard(board, { limit })` resolves { entries: [{ rank, player, value, isMe }], me }.
- `Gamero.unlockAward(key)` for each award in game.json, whenever its condition is met (repeat calls are ignored).
- Calls reject with err.code "signin" for guests: keep the game fully playable, never block on these calls, and catch errors.
- Gamero shows its own leaderboard and award panels and an "Award unlocked" popup, so in-game UI is optional.

## 3c. Online multiplayer (Gamero rooms)
This is a multiplayer game. Gamero provides online rooms through the same SDK (`<script src="https://gamero.gg/sdk/gamero.js"></script>` in index.html). There is NO game server and you must not add one (no Node/socket.io/WebRTC/Firebase servers, the game can't open its own connections reliably from the sandbox): Gamero relays JSON messages between the players of a room, and the game decides who is authoritative.

API (`const mp = Gamero.multiplayer`):
- `await mp.join({ maxPlayers })` quick-matches into an open public room with the same maxPlayers (2–16, default 2), or creates one. `mp.join({ private: true, maxPlayers })` creates a room only reachable by its code. `mp.join({ code })` joins a friend's room. Resolves the room `{ code, me, host, maxPlayers, isPublic, locked, players: [{ id, name }] }`. Rejects with err.code "not-found", "full", "locked" (already started), "busy", "network" or "unavailable" (not on Gamero).
- `mp.room` is the current room (players and host kept up to date) or null. `mp.isHost()` is true for the host: the longest-connected player. When the host leaves, the next player becomes host.
- `mp.send(data)` sends JSON-serializable data to everyone else; `mp.send(data, playerId)` to one player. Fire-and-forget, ordered, reliable. Max 16 KB per message and 60 messages per second per player; the sender never receives its own message.
- `mp.lock()` (host only) stops new players from joining: call it when the match starts.
- `mp.leave()` leaves the room.
- Events, registered with `mp.on(event, fn)` BEFORE calling join: "message" (data, fromPlayer), "join" (player), "leave" (player), "host" (newHostPlayer), "close" (reason: the connection dropped, e.g. "disconnected", "slow", "rate"), "error" (err).
- Player names are Gamero display names; guests can play too and appear as "Guest 1234". Ids are small integers, unique within the room.

How to build it:
- Host-authoritative: the host runs the simulation (physics, collisions, scoring, spawning, randomness) and sends compact state snapshots 10–20 times per second. Other players send only their inputs to the host (`mp.send(input, mp.room.host)`) and render the snapshots with interpolation (render ~100 ms in the past) and local prediction for their own character so it feels responsive. Turn-based games: send each move, the host validates it and broadcasts the result.
- Tag every message with a type, e.g. `{ type: "input" | "state" | "start" | "end", ... }`. Keep snapshots small: round numbers, short keys, only what changed.
- Never send messages every animation frame; use a fixed send rate.
- Lobby screen with three touch-friendly buttons: "Quick match", "Create private room" (then show the room code big and a waiting list of players) and "Join with code" (a 5-character code input). Show who is in the room. The host has a Start button, enabled once enough players joined; Start calls `mp.lock()` and broadcasts a "start" message with any shared seed/settings.
- Handle players leaving mid-match (remove them, or end the round if too few remain) and host migration: on "host", if `mp.isHost()` is now true, continue the simulation from the last snapshot. On "close", show a message and go back to the lobby.
- A player who joins a room mid-lobby must receive the current lobby state: the host sends it to them on "join".
- Keep the game usable when `Gamero.available` is false (local dev): show the lobby with a "Multiplayer works on Gamero" note, and keep a local/solo or bot mode so the game can be tried alone. Structure the network code behind a small interface so a fake in-memory transport can drive two game instances locally for testing.
- Leaderboards/awards still work as in 3b; submit each player's own score from their own client.

## 4. npm run build → gamero.zip
- Add `archiver` as a devDependency and a script `scripts/gamero-zip.mjs` that zips the CONTENTS of the build folder at the ZIP root (index.html must be at the top level, not inside dist/) plus the `screens/` folder as `screens/`.
- Chain it in package.json: `"build": "<existing build command> && node scripts/gamero-zip.mjs"`.
- Add `gamero.zip` to .gitignore.
- The script must fail with a clear message if index.html is missing from the build output.

## 5. Check before you finish
- Run `npm run build` and list the ZIP contents. Confirm: `index.html` at the root, `screens/` next to it, only allowed file names in screens/, game.json is valid JSON with only the properties above, every `![…](file)` reference in the .md files points to an existing `description-N` / `how-to-play-N` picture.
- Serve the build output from a sub-folder (e.g. `npx serve` one level up) and confirm the game loads with no 404s.
- If you added the SDK: the script tag is in the built index.html, every Gamero call is guarded by `Gamero.available` and catches errors, the game is fully playable without it, and every `unlockAward` key exists in game.json "awards".
- Multiplayer: event handlers are registered before `join`, nothing is sent every frame, every message is under 16 KB, the lobby works on a phone, and leaving / host migration / "close" are handled. Tell me to test it with **Test play** in two browser windows (or two devices) side by side.
- Tell me the ZIP size and anything left for me to do. On Gamero I only have to upload the ZIP in step 1 of the submission page, check the preview, and press Publish.

{
  "title": "Neon Drift",
  "tagline": "Race through a city that rebuilds itself every lap",
  "theme": "Neon / Synthwave",
  "category": "Sports",
  "subCategory": "Racing",
  "dimension": "2D",
  "tags": ["racing", "arcade", "neon"],
  "inputMethods": ["Touch", "Keyboard", "Gamepad"],
  "orientation": "Landscape",
  "contentWarnings": ["FlashingLights"],
  "engine": "Phaser 3",
  "videoUrl": "https://youtu.be/xxxxxxxxxxx",
  "sourceCodeUrl": "https://github.com/me/neon-drift",
  "challengeNotes": "The track changes shape every lap, which fits this week's theme.",
  "credits": "Music: Jane Doe (CC-BY 4.0)",
  "aiDisclosure": "Code written with Claude Code; all art and music made by hand."
}

// scripts/gamero-zip.mjs: zips the web build + screens/ into gamero.zip
// npm i -D archiver
import { createWriteStream, existsSync } from "node:fs";
import archiver from "archiver";

const BUILD_DIR = "dist"; // folder that contains index.html after the build

if (!existsSync(`${BUILD_DIR}/index.html`)) {
  console.error(`${BUILD_DIR}/index.html not found, did the build run?`);
  process.exit(1);
}

const output = createWriteStream("gamero.zip");
const zip = archiver("zip", { zlib: { level: 9 } });
zip.pipe(output);
zip.directory(BUILD_DIR, false);                                // game files at the ZIP root
if (existsSync("screens")) zip.directory("screens", "screens"); // game page data
await zip.finalize();
await new Promise((resolve) => output.on("close", resolve));
console.log(`gamero.zip ready (${(zip.pointer() / 1024 / 1024).toFixed(1)} MB). Upload it in step 1 of your submission.`);

"scripts": {
  "build": "vite build && node scripts/gamero-zip.mjs"
}

<script src="https://gamero.gg/sdk/gamero.js"></script>

// After the run ends (integers only: points, or a time in ms)
if (window.Gamero?.available) {
  const { rank, improved } = await Gamero.submitScore(score);
  await Gamero.submitScore(timeMs, { board: "speedrun", order: "asc" }); // lower wins

  // Unlock awards whenever the condition is met; repeats are ignored
  Gamero.unlockAward("first-win").catch(() => {});

  // Show the top 10 in your own UI
  const { entries, me } = await Gamero.getLeaderboard("main", { limit: 10 });
}

"awards": [
  { "key": "first-win", "title": "First win", "description": "Win a round", "icon": "🏆" },
  { "key": "no-hit", "title": "Untouchable", "description": "Clear a level without getting hit", "icon": "🛡️" },
  { "key": "hidden-room", "title": "Explorer", "description": "Find the hidden room", "icon": "🗝️", "secret": true }
]

// On start: turn on what the player owns
if (window.Gamero?.available && await Gamero.hasItem("gold-skin")) useGoldSkin();

// From your shop button: Gamero shows the price and asks the player
try {
  await Gamero.buyItem("gold-skin");
  useGoldSkin();
} catch (e) {
  // e.code: "cancelled" (player said no), "coins" (not enough), "signin" (guest)
}

const mp = Gamero.multiplayer;

// Listen first, then join
mp.on("join", (player) => showLobby(mp.room.players));
mp.on("leave", (player) => removePlayer(player.id));
mp.on("host", (player) => { if (mp.isHost()) takeOverSimulation(); });
mp.on("message", (data, from) => {
  if (data.type === "input") applyInput(from.id, data);   // host: inputs from players
  if (data.type === "state") applySnapshot(data);         // everyone else: the host's world
});
mp.on("close", (reason) => backToMenu(reason));

// Lobby buttons
const room = await mp.join({ maxPlayers: 4 });            // Quick match
// await mp.join({ private: true, maxPlayers: 4 });      // Create a room, show room.code to friends
// await mp.join({ code: "K7QX2" });                     // Join a friend's room

// Host presses Start
if (mp.isHost()) { mp.lock(); mp.send({ type: "start", seed: 1234 }); }

// In the game loop, 15–20 times a second (not every frame)
if (mp.isHost()) mp.send({ type: "state", players: snapshot() });
else mp.send({ type: "input", left, right, jump }, mp.room.host);