Set your project up once and every npm run build gives you a gamero.zip with everything the game page needs: the game, its details, cover, screenshots and texts. Upload it, check the preview, publish.
Want a scoreboard or achievements? Add one script tag and your game gets leaderboards and awards, shown right next to it on the game page.
Challenge
Pick the challenge you're entering, or none for a standalone game. The prompt and rules below follow it.
Players
Pick every mode your game offers.
The prompt now also explains Gamero party mode: one screen shows the game, players use their phones, and Gamero keeps the party scoreboard.
Using Claude Code, Cursor, Copilot or a chat assistant? Paste this prompt into it, inside your game project. It describes everything below: the build, screens/, game.json with every allowed value and the rules of “Best racing game”, the ZIP script, and how to add leaderboards and awards if your game has a score or achievements, plus how to build a party game with a screen and phone controllers.
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 racing game". It requires "category": "Sports", "subCategory": "Racing". Its requirements:
Build a car or racing game in one week.
- Must be about cars, driving or racing (circuit, drift, arcade, endless runner, time trial – your call)
- Must be playable with keyboard or mouse; bonus points for touch controls
- Works on mobile portrait
- A clear goal: lap times, score, checkpoints or beating rivals
- Max 20 MB
- Original work: only assets you made or have the right to use
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, except `content/` for content packs (section 3d). Max 40 files in screens/ in total. 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 ``; 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 ``. |
| `content/{key}.{lang}.json` | Optional content packs the game loads | See section 3d. |
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.
- "party": party mode settings, see section 3c.
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. Party mode (one screen + phones)
This is a party game for Gamero party mode: one **screen** (a TV or laptop everyone looks at) shows the game, and every player uses their **phone** as the controller. Gamero runs the party around the game: joining with a QR code or code (guests included), seats, phones reconnecting, choosing the next game, and a party scoreboard that carries across games. The game only plays one round and reports who placed where. There is NO game server and you must not add one (no Node/socket.io/WebRTC/Firebase): Gamero relays JSON messages between the screen and the phones.
Setup:
- `<script src="https://gamero.gg/sdk/gamero.js"></script>` in every HTML page the game loads, before the game code.
- In screens/game.json add `"party": { "minPlayers": 2, "maxPlayers": 8, "screenPlays": false, "controller": "controller.html" }`. minPlayers/maxPlayers: 1–16, counting phones only (plus the screen when screenPlays is true). "screenPlays": true if the screen device is also a player. Parties are started either with a TV/laptop or with **just phones**; in a just-phones party the host's phone is the screen: the host always plays. With screenPlays they play through the screen view; without it Gamero loads the screen view (top) and the controller (bottom) together on the host's phone, so a screenPlays: false game must still work when its screen view is a small landscape strip. Set it to true whenever the screen view itself can work on a phone with the host's controls in it; false for games that need a big shared screen (e.g. hidden information on the phones that the screen must not show to its own player). "controller": optional page the phones load, relative to the build root; leave it out to load index.html on both. A separate small controller page is recommended: phones load faster and the code stays simple.
- The game is loaded with `?gameroParty=screen` or `?gameroParty=controller` in its URL; the SDK reads it. Don't strip or rewrite the query string.
API (`const party = Gamero.party`):
- `party.active` is true only when a Gamero party loaded the game; `party.role` is "screen" or "controller" (null otherwise). Both are available synchronously at startup.
- `await party.join()` once at startup, after registering handlers; events start after it. Resolves `{ code, round, role, lang, content, me, screenPlays, screenConnected, players: [{ seat, name, connected }], scoreboard: [{ seat, name, points, wins, rounds }] }`. `lang` is the party's language (e.g. "pl"), chosen by the host in the lobby; `content` is the content pack key the host picked (section 3d), or null. `me` is this phone's seat number (null on the screen unless screenPlays). Seats are small integers, stable for the whole party (a phone that reconnects keeps its seat). `party.info` is the same object, kept up to date.
- `party.send(data)` to every other device; `party.send(data, seat)` to one phone; `party.sendToScreen(data)` from a phone to the screen. JSON only, max 16 KB per message, 60 messages per second per device, ordered and reliable; the sender never receives its own message.
- Events with `party.on(event, fn)`: "message" (data, from, at): from is `{ seat, name }` or the string "screen", at is the server time in ms when it arrived (use the arrival order to decide who answered or buzzed first, never the phones' clocks); "players" (players): someone joined, left or reconnected (check `connected`); "screen" (connected): the screen dropped out or came back.
- `await party.endRound(ranking)` (screen only, once, when the game is over): the placements, best first. Each entry is a seat or an array of tied seats, e.g. `[3, [1, 5], 2]`. Seats left out get no points. Gamero adds party points by place (1st 10, 2nd 7, 3rd 5, 4th 3, 5th 2, below that 1), shows the results and takes everyone back to the party lobby, which unloads the game. Resolves `{ number, game, results: [{ seat, name, place, points }] }`.
- `party.getScoreboard()` is the party scoreboard at the start of this game (e.g. to show "Ana leads the party").
How to build it:
- The screen is the authority: it holds the game state, timers, rules and randomness, and decides the ranking. Phones send only inputs (`{ type: "answer", ... }`, `{ type: "buzz" }`, `{ type: "move", ... }`) and show what the screen tells them. Tag every message with a type.
- Screen UI: readable from across a room (big text, high contrast, landscape 16:9), shows who has answered or is ready, and works with no input on the screen at all (it may be a TV): the game starts by itself after a short countdown and moves on with timers.
- With screenPlays true the screen may be the host's phone instead (just-phones party, `party.info.me` is its seat): the screen view must also fit a portrait phone (responsive layout, nothing tiny) and include the host's own controls in it (same inputs as a controller, handled locally rather than sent), and treat the host's seat like any other player in the rules and the ranking. Don't reveal anything on the screen that the host's player shouldn't see.
- Every phone must show everything its player needs to play: never rely on players looking at the screen. In a just-phones party there is no TV, only the host's phone, so the other players can't see it. With each step the screen sends the controllers the full prompt (the question text, the word or picture prompt, the options, the timer's end time) and each controller shows it above its inputs. Images: send a short id or a URL in the game's build, not image data. After each step send the result too (correct answer, who won the point), so every phone shows it.
- Controller UI: portrait phone, big touch targets, no hover, no keyboard except for text answers, no scrolling; show the player's name, the current question or prompt, what to do now, and feedback after each input. Long question text must wrap and fit without scrolling (smaller font if needed). Keep it light (no big assets).
- Phones sleep and reload: when a controller starts it sends `{ type: "hello" }` to the screen, and the screen answers that seat with the current state (the current question with its options, whether they already answered, their score). The screen must never wait forever for a player who is offline (`connected: false`): use timeouts.
- Late joiners appear in "players" during the game; let them in at the next step or have them watch.
- If the screen reloads, the round starts over on it; phones go back to their waiting view when the screen sends a new start.
- Outside a party (`party.active` false, e.g. local dev or the normal game page), show a short "Start this game from a Gamero party (gamero.gg/party)" message, and if practical a local test mode that simulates the screen and two phones in one page so the game can be tried alone. Keep the network code behind a small interface so that fake transport can drive it.
- Leaderboards and awards (3b) still work per device; they are optional in a party game.
- Quiz, trivia, drawing or word games: put the questions/words in content packs (section 3d). The host then picks a pack and the language in the party lobby, and the screen loads it with `Gamero.content.get()`.
## 3d. Content packs (optional: questions, words, prompts, levels)
If the game plays from a list of data (quiz questions, survey answers, words to draw, songs, puzzles, levels), ship that data as **content packs** instead of only hard-coding it. Gamero stores the packs, lets the party host pick one, and serves each in the player's language.
- Files: `screens/content/{key}.{lang}.json`, e.g. `screens/content/general.en.json` and `screens/content/general.pl.json` (the same pack translated). `key`: lowercase letters, digits, - and _, max 32. `lang`: one of "en", "pl", "de", "es", "fr", "it", "pt", "pt-br", "nl", "cs", "uk", "tr", "sv", "ja", "ko", "zh". Max 30 files, 256 KB each.
- Each file is ONE JSON object in the game's own format, e.g. `{ "title": "General knowledge", "questions": [...] }`. The optional "title" (max 100) names the pack in the party lobby; without it the key is shown. Comments and trailing commas are allowed. Use the same structure in every pack.
- The packs in the ZIP are the FULL list: a pack missing from a new upload is deleted. A ZIP with no `screens/content/` folder keeps the current packs.
- Split by what players would choose between (categories, difficulty, themes), not into tiny files. A pack can be in some languages only: Gamero picks the closest one (pt-br → pt → en → any other).
- If the data already lives in the project (a JSON/CSV/JS file), GENERATE the pack files from it in `npm run build` instead of keeping two copies by hand.
- Load it with `await Gamero.content.get(key?, { lang? })`, resolving `{ key, lang, title, data }`. With no key: in a party, the pack the host picked, else the game's first pack. The language defaults to the party's language, else the player's browser language. `await Gamero.content.list({ lang? })` resolves `[{ key, title, lang, langs }]`, e.g. for an in-game category menu. Both reject with err.code "not-found" (no such pack) or "unavailable" (not on Gamero).
- Check `pack.lang`: if the game's own UI text or answer matching depends on the language, follow the pack's language, not the browser's.
- Keep a built-in copy of the default pack in the game, used when `Gamero.available` is false or loading fails, so local dev and offline play keep working.
- In a party only the SCREEN loads the pack and sends phones what they need for each step (the question and its options), never the whole pack or the answer before it's revealed.
## 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 `` 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".
- If you added content packs: every file is `screens/content/{key}.{lang}.json` with a supported language, is a JSON object under 256 KB, the packs share one structure, the build regenerates them from the source data, and the game falls back to its built-in copy without Gamero.
- Party: game.json has "party" with sensible minPlayers/maxPlayers, the "controller" page (if any) exists at that path in the build and loads the SDK, handlers are registered before `party.join()`, the screen calls `endRound` exactly once with every ranked seat, nothing is sent every frame, every message is under 16 KB, the screen never waits forever on an offline phone, a reloaded controller recovers via "hello", and with screenPlays the screen view is playable on a portrait phone with the host ranked like everyone else. Tell me to test it by uploading the ZIP as a draft, opening gamero.gg/party on my computer, joining with my phone (or a second browser window) and picking the game: my drafts are listed for me.
- 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.gamero.zip
├── index.html ← your game (must be at the root; add the SDK script here for leaderboards/awards)
├── assets/ … ← anything your game loads, relative paths
└── screens/ ← game page data, NOT served with the game
├── game.json ← title, tagline, theme, genre, controls, credits, awards…
├── cover.png ← card + page header, 16:9, at least 630×354
├── screenshot-1.png ← gallery, in number order (max 8)
├── screenshot-2-boss-fight.png ← text after the number = caption "Boss fight"
├── preview.mp4 ← optional: few-second muted loop played when hovering the card
├── description.md ← "About" text (markdown, max 10 000 chars)
├── description-1.png ← pictures for the description
├── how-to-play.md ← "How to play" text (markdown, max 3 000 chars)
├── how-to-play-1.png ← pictures for the instructions (controls diagram…)
└── content/ ← optional: data your game loads (questions, words, levels)
├── general.en.json ← pack "general" in English
└── general.pl.json ← the same pack in Polishindex.html can also sit inside one top-level folder (e.g. dist/index.html). Then screens/ can be next to that folder or inside it.game.json with at least a title and tagline. Without it, fill in the game details by hand first.awards list in game.json replaces all awards, and a content/ folder replaces all content packs.game.json property stops the upload with an error, and nothing changes.screens/ folder is never served with your game, so name your game's own folders differently.Every field from the submission form. Values must match the site's lists (the AI prompt includes them all), and “Best racing game” fixes some of them.
{
"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."
}inputMethods: any of Touch, Keyboard, Mouse, Gamepad. orientation: Any, Portrait or Landscape.contentWarnings: any of FlashingLights, Violence, Gore, LoudAudio, Horror.dimension: 2D, 2.5D or 3D. Up to 10 tags.awards: optional list of achievements your game unlocks, see Awards. Leave it out to manage awards on the submission page instead..md files so they can include pictures.| File | Becomes | Rules |
|---|---|---|
cover.png | Cover (card + page header) | 16:9, min 630×354, ideally 1280×720. Center-cropped. |
screenshot-1.png … -8.png | Screenshot gallery | Number order. Longest side 320–1920 px. screenshot-3-night-level.png → caption “Night level”. |
preview.mp4 / .webm | Hover clip on the card (optional) | MP4 (H.264) or WebM, 16:9, max 8 MB. 5–10 s of gameplay; plays muted and looping. |
description.md | About | Markdown, max 10 000 characters. |
description-N.png | Pictures in About | Up to 10. Use . Unreferenced ones go at the end. |
how-to-play.md | How to play | Markdown, max 3 000 characters. Goal + controls per input. |
how-to-play-N.png | Pictures in How to play | Up to 10, e.g. a controls diagram. |
Images can be PNG, JPG, WebP or GIF up to 5 MB each. We convert them to WebP, so they show as still images. Markdown can't contain HTML, and only pictures from screens/ are displayed.
Example description.md
Race through a city that rebuilds itself every lap.  - 12 hand-made tracks - Ghost replays of your best lap
Doing it by hand? Add this script, then chain it after your build in package.json:
// 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"
}With Vite, set base: "./" so assets load from relative paths. Add gamero.zip to .gitignore.
Optional. With the Gamero SDK your game can post scores and unlock awards for the signed-in player. Gamero shows the leaderboard and awards next to the game, plus an “Award unlocked” popup over it, so you don't have to build any UI for them.
Add this to your index.html, before your game's own scripts. It defines window.Gamero.
<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 });
}Your game runs in a sandboxed iframe and never sees the player's login. The SDK passes each call to the Gamero page, which saves it for the signed-in player. Every method returns a Promise.
| Call | What it does | Resolves |
|---|---|---|
Gamero.available | true when running on Gamero | A boolean, not a Promise. False on your local dev server. |
submitScore(value, { board, order }) | Report a finished run | { best, improved, rank, players }. board defaults to "main". |
getLeaderboard(board, { limit }) | Top scores (default 10, max 100) | { key, order, players, entries: [{ rank, player, value, isMe }], me } |
unlockAward(key) | Unlock an award for the player | { unlocked, award }. unlocked is true only the first time. |
getAwards() | All awards and the player's progress | [{ key, title, description, icon, isSecret, unlockedBy, unlockedAt }] |
getItems() | Items your game sells for gamecoins | [{ key, title, description, icon, price, owned }] |
hasItem(key) | Whether the player owns an item | true or false (always false for guests). |
buyItem(key) | Ask the player to buy an item | { bought, item }. bought is false if they already owned it. |
content.get(key?, { lang }) | Load a content pack | { key, lang, title, data }, in the closest language. See Content packs. |
content.list({ lang }) | All content packs | [{ key, title, lang, langs }] |
getPlayer() | Who is playing | { displayName }, or null for guests. |
Failed calls reject with an Error whose code is "signin" (a guest tried to save progress), "unavailable" (not running on Gamero), "cancelled" (the player declined a purchase), "coins" (not enough gamecoins), "not-found" (no such content pack), "timeout" or "error" (the message says why, e.g. an unknown award key).
improved: false and changes nothing."main", "level-3"). A board is created by its first score, and that score's order is fixed from then on: "desc" (higher wins, the default) or "asc" (lower wins, for times).Define them in step 4 of your submission (Awards), or in screens/game.json. Each award has a key your game uses, a title, an optional description and emoji icon, and can be secret: hidden from players until they unlock it.
"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 }
]- and _, max 32 characters, unique within your game. Up to 50 awards.game.json list is the full list: every upload replaces the awards on the site. Awards are matched by key, so players keep the ones they unlocked. Removing an award also removes it from players.unlockAward every time the condition is met. Repeat calls are ignored, so you don't need to remember what the player already has.Your game can sell extras for gamecoins, Gamero's currency: a skin, a bonus level, a power-up. Define them in step 5 of your submission (Shop items) with a key, title, emoji and a price from 10 to 500 coins.
// 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)
}buyItem never spends coins on its own. Gamero shows the item, the price and the player's balance over your game and the player confirms or cancels. Don't pause the game while waiting for that answer.Does your game play from a list of data, like quiz questions, words to draw or levels? Put it in screens/content/ as packs. Gamero stores them, serves each one in the player's language, and in a party lets the host pick the pack and the language in the lobby.
// screens/content/general.en.json: any JSON object, in your own format
{
"title": "General knowledge", // optional: the pack's name in the party lobby
"questions": [
{ "q": "Which planet is the Red Planet?", "options": ["Venus", "Mars", "Jupiter", "Mercury"], "correct": 1 }
]
}let questions = BUILT_IN_QUESTIONS; // keep a copy in the game for local dev
if (window.Gamero?.available) {
try {
const pack = await Gamero.content.get(); // in a party: the pack the host picked, in the party's language
questions = pack.data.questions; // pack.lang says which language you got
} catch (e) { /* e.code "not-found": no packs, keep the built-in ones */ }
}{key}.{lang}.json. The same key in several languages is one pack, translated: general.en.json, general.pl.json. Languages: en, pl, de, es, fr, it, pt, pt-br, nl, cs, uk, tr, sv, ja, ko, zh.pt-br, then pt, then English, then any other. Check pack.lang if your interface or answer checking depends on it."title" for the lobby. Up to 30 files.content/ folder replaces all packs. Leave the folder out to keep the current ones.code: "signin", and Gamero asks them to sign in. Never block or pause the game waiting on these calls, and always catch their errors.Gamero.available is false, so check it before calling. Test the real thing with Test play on the submission page. Scores and awards you earn on your draft are saved as yours.JavaScriptBridge.eval("Gamero.submitScore(1234)"). Unity: call the same functions from a .jslib plugin.Optional. Gamero runs the online part for you: players join a room (2–16 players) and every message one of them sends is passed to the others. There is no server code to write or host. One player, the host, runs the game's rules and the others follow. Choose Online multiplayer at the top of this page and the AI prompt explains all of it.
It uses the same SDK script as leaderboards. Register your handlers, then join:
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);| Call | What it does | Notes |
|---|---|---|
join({ maxPlayers }) | Quick match | Joins an open public room of the same size (2–16, default 2), or opens one. Resolves the room. |
join({ private: true }) | Create a private room | Only reachable with its 5-character room.code. Show it so friends can join. |
join({ code }) | Join a friend's room | Rejects with code "not-found", "full" or "locked". |
room | The current room, or null | { code, me, host, maxPlayers, isPublic, locked, players: [{ id, name }] }, kept up to date. |
send(data, to?) | Message the room | JSON data to everyone else, or only to player to. Max 16 KB and 60 per second. |
isHost() | Whether you're the host | The longest-connected player. If they leave, the next one takes over. |
lock() | Close the room (host) | Call it when the match starts, so nobody joins mid-game. |
leave() | Leave the room | Back to the lobby. |
on(event, fn) / off | Listen to the room | message (data, player), join, leave, host (player), close (reason), error. |
send(input, mp.room.host). Don't send every frame.host, the new host carries on from the last snapshot. On close, the connection is gone, so go back to the lobby.join rejects with "unavailable", so keep a solo or bot mode for local development. To test the real thing, open Test play in two browser windows.Optional. In a Gamero party one screen (a TV or laptop) shows your game and everyone plays on their phone. Gamero handles joining (QR code, guests), reconnecting phones, and a party scoreboard that carries across games. Your game only does the playing.
Turn it on in the editor (Party mode) or in screens/game.json:
"party": {
"minPlayers": 2,
"maxPlayers": 10,
"screenPlays": false, // true: the screen has a seat too, so the game also works with just phones
"controller": "controller.html" // optional: the page phones load; default index.html for both
}The game loads once on the screen with party.role "screen" and once on each phone as "controller":
const party = Gamero.party;
if (party.active) { // loaded by a Gamero party
const info = await party.join(); // { role, me, players: [{ seat, name, connected }], ... }
party.on("message", (data, from, at) => { ... }); // from: { seat, name } or "screen"
party.on("players", (players) => { ... }); // someone joined, left or reconnected
if (party.role === "screen") { // the TV: show the game, run the rules
party.send({ type: "question", options }); // to every phone (or send(data, seat) for one)
// ...when the game is over, the placements, best first; [1, 5] is a tie:
await party.endRound([3, [1, 5], 2]);
} else { // a phone: buttons, text input
party.sendToScreen({ type: "answer", choice: 2 });
}
}endRound once. Gamero turns places into party points: 1st 10, 2nd 7, 3rd 5, 4th 3, 5th 2, everyone else ranked 1. Seats you leave out get 0.at on each message is the server time it arrived: use the arrival order for “who buzzed first”, not the phones' clocks."screenPlays": true through your screen view; in the others Gamero shows your screen view on top of the host's phone and your controller below it. If your screen view works well on a phone (with the host's own controls in it), turn it on for the best fit.Gamero.content.get() on the screen loads that pack. party.join() also tells you the lang and content key.gamero.zip in step 1. It creates your draft and fills in every step below it. Not entering a challenge? Upload it as a standalone game instead: no deadline or theme, and you can publish as many as you like.npm run build again and upload the new ZIP.The game runs in a sandboxed iframe on a separate domain: no cookies, popups or parent-page access. Any HTML5 engine works (plain JS, Phaser, PixiJS, Godot single-threaded web export, Unity WebGL…). Test it on a phone too.