How a build appears
Approved contributors only. Games are added by people the arcade has approved. To become one, or to suggest a game, message us at play@smashi.app.
A build is one game made by one model from one prompt. It is a folder of static files on the site, plus one entry in the games list. Builds with the same title are one game. The site reads the list and shows the build in five places:
- Library card: the cover, the title, the prompt (first five lines),
model / harnessand a Play button. - Select your build: every build with the same title, side by side, so models can be compared on the same game.
- Build details: the summary, model, harness, reasoning effort, time to build, genre, build date and the full prompt.
- Game page: every build of the game side by side at
/games/<game>/, with the prompt they were given.<game>is the title in lowercase with hyphens:Cadillacs and Dinosaursis at/games/cadillacs-and-dinosaurs/. The first build of a new title starts its game page. - Build page: the same details as Build details on a page of its own, under its game, at
/games/<game>/<id>/, with a share image made from the cover. Publish writes the pages and the images; you do not.
Play opens the build at /arcade/<id>/ in its own browser window, and the site's own music stops until the visitor comes back, so the game has the speakers to itself. The link to share is the build page, https://smashi.app/games/<game>/<id>/: chat apps and social sites show its share image, with the game's title, the model, the harness and the build time. The game page has a share image too, with the number of builds and who built them. https://smashi.app/#play/<id> goes straight to the game.
Quick start
Only approved contributors can add a game: you need shell access to the server, which comes with approval. Ask at play@smashi.app. The site lives in one home directory; run every command from there.
- Build the game as a folder of static files with
index.htmlat its root. It has to meet the game rules. - Pick an id and add the cover:
assets/cover.webp, 1280 × 720. - Copy the folder to
public/arcade/<id>/. - Add your entry as the first item in
public/arcade/games.js. - Run
node tools/arcade.mjs check <id>and fix every error. - Run
node tools/arcade.mjs publish. - Open
https://smashi.app/games/<game>/<id>/, press Play and finish one round.
public/- The source. Work here.
arcade/games.js- The games list.
arcade/<id>/- One folder per build.
games/<game>/- The game's page and share image, with a folder per build inside:
<id>/, the build's page and share image. Publish writes them all. public_html/- The live site. Never edit it: publish writes it.
tools/arcade.mjs- Check, build and publish.
tools/page.htmlis the frame of the build pages. The other tools are the site's own: see The site itself. .deployments/- A snapshot of every publish, and the publish lock.
Game rules
Every build has to meet the rules marked Must. The ones marked Should are expected unless there is a reason not to.
MustStatic files only
HTML, CSS, JavaScript and media. No server code, no database, nothing to install or build on the server. If you used a bundler, publish its output.
Mustindex.html at the folder root
Opening
/arcade/<id>/starts the game. The page has<!doctype html>, alangon<html>,<meta charset="utf-8">, a viewport meta tag and a<title>with the game's name.MustRelative paths
Load every file by a relative path such as
assets/hero.pngor./game.js, never one that starts with/. A plain link back to the arcade,<a href="/">, is fine.MustNothing from other sites
No CDN scripts, hosted fonts, analytics, ads, remote APIs or web sockets. Put fonts and libraries in the folder, with their license text in
assets/licenses/.MustFits its window
Play opens the game in its own window, or a new tab on phones. The game fills that window at any size from 320 × 480 up, in portrait and landscape, and the page never scrolls in either direction. Scale the play area to the window instead of assuming a size.
MustKeyboard and touch
Playable from start to finish with a keyboard alone, and with touch alone on a phone, using on-screen buttons or gestures. Show the controls before play starts.
MustStart, end, restart
A start screen, a clear win or lose state, and a way to play again without reloading the page.
MustQuiet until asked
No sound before the player's first key press or tap.
MustOwn storage keys only
All builds share one origin, so they share
localStorage. Start every key with your id, for example<id>:best. Never calllocalStorage.clear()orsessionStorage.clear(), and never touch keys that start witharcade-: those are the site's.MustNo service workers, cookies or permission prompts
That includes camera, microphone, location and notification requests.
MustSize
The whole folder is 5 MB or less, and no single file is over 2 MB.
MustYour own material
Use only art, sound, fonts and code that were made for the build or that you may redistribute. Do not copy sprites, music or logos from existing games.
MustLeave everything else alone
A build never loads or changes files outside its folder: not another build, not the site's styles or scripts.
ShouldRun everywhere
Current Chrome, Firefox and Safari, on desktop and on phones.
ShouldStay smooth
Hold 60 frames per second on a mid-range phone, and stop the game loop while the tab is hidden.
ShouldGive the player control
A pause key, a mute control when there is sound, and no screen shake or flashing when the system asks for reduced motion.
ShouldDescribe itself
A one-sentence
<meta name="description">inindex.html.
Folder and id
The id names the folder, the URL and the entry. It is 3 to 40 characters: lowercase letters, digits and single hyphens, starting with a letter. It has to be unique and it never changes after publishing. The usual shape is the build's own name plus the model: fossil-fury-opus, saltline-brawl-fable.
index.html- Required. The game.
assets/cover.webp- Required. The cover image.
assets/...- Everything else the game loads.
assets/licenses/- License texts for third-party fonts, code or art.
Scripts and styles may sit next to index.html or in subfolders. Leave out source maps, editor files, node_modules and anything else the game does not load.
Cover image
- File:
assets/cover.webp, in WebP format. - Size: exactly 1280 × 720 pixels (16:9), 200 KB or less.
- Content: a screenshot or title art of this build. It shows what the player will actually get.
- Safe area: cards crop the cover to 2:1 and the build details to 5:2, both centred, so up to 15% can be cut from the top and from the bottom. Keep the subject and any title in the middle 70% of the height.
- Share image: publish makes it from the cover, 1200 × 630, and writes the game's title, the model, the harness and the build time over the lower half. Whatever sits in the upper half of the cover is what shows.
- No borders, letterboxing, small text or watermarks.
cwebp -q 80 -resize 1280 720 screenshot.png -o assets/cover.webp
Games list entry
The games list is public/arcade/games.js, an ES module that exports an array named games. Add your entry as the first item of the array: the list order is the library order, newest first. Do not reorder or reformat the other entries.
{
"id": "your-build-id",
"title": "Game Title",
"genre": "Platformer",
"summary": "One sentence about what the player does in this build.",
"prompt": "The prompt, word for word.",
"model": "Model Name 1.0",
"reasoningEffort": "High",
"sourceUrl": "https://github.com/you/your-build",
"harness": "Harness Name",
"buildSeconds": 754,
"builtAt": "2026-11-20T14:05:00Z",
"entry": "/arcade/your-build-id/",
"image": "/arcade/your-build-id/assets/cover.webp"
},
Fields
idRequiredString
The folder name, as described under Folder and id. Unique, and never changed after publishing.
titleRequiredString
The name of the game the prompt asked for. Every build of the same game uses exactly the same title, because builds are grouped by it and the game page's address is made from it. A name the build gave itself belongs in summary.
genreOptionalString, 24 characters at most
In sentence case, like Racing or Beat ’em up. Reuse a genre that is already in the list when it fits.
summaryRequiredString, 160 characters at most
One sentence on what the player does in this build. If the build has its own name, start with it: Fossil Fury: fight poachers and raptors down the Overgrown Highway.
promptRequiredString
The message that asked for this build, word for word, typos included. Do not shorten, translate or improve it. Write a line break as \n.
modelRequiredString
The model's public name and version, as the harness shows it: Claude Opus 5.5, GPT-6.2 Astra. If the model is already in the list, copy its spelling exactly. Builds are grouped by the exact text, and the check rejects a second spelling.
reasoningEffortOptionalString
Only when the harness has a reasoning or effort setting: its value, capitalised, like Low, Medium or High. Otherwise leave the field out.
sourceUrlOptionalString, an https:// address
Where the build's code is public, such as its GitHub repository: https://github.com/you/your-build. The build page and Build details then show a Source code button. Builds are meant to be open source, but the link can be added later: leave the field out until the code is public.
harnessRequiredString
The tool the model ran in. Use the product name without a version: Claude Code, Codex. Copy the spelling of an existing entry when there is one.
buildSecondsRequiredWhole number above 0
The time to build, in seconds. Recording the build says what counts.
builtAtRequiredString, ISO 8601 in UTC
When the build finished: 2026-11-20T14:05:00Z. It cannot be in the future.
entryRequiredString
Always /arcade/<id>/.
imageRequiredString
Always /arcade/<id>/assets/cover.webp.
There are no other fields: the check warns about unknown ones and the site ignores them. A new entry cannot use null.
Older entries look different. Builds published before 20 November 2026 predate these rules, so some have null for the harness or build time. Do not copy their shape.
Recording the build
The library exists to compare models, so an entry has to describe the run that actually produced the files.
- Prompt: copy it from the conversation, exactly as it was sent.
- Model and reasoning effort: the ones that were selected in the harness for this run.
- Harness: the tool the model ran in, not the company that makes the model.
- Time to build: start the clock when the prompt is sent and stop it when the model says the game is finished. Everything in between counts: planning, writing, running, testing and fixing. Making the cover, writing the entry and publishing do not count. If the harness reports how long the run took, use that number. Give it in whole seconds: 12 min 34 s is
754. - Build date: the moment the clock stopped, in UTC.
Check and publish
One tool checks a build against this page and puts it live. It needs Node 18 or newer and no packages. If node is not on your path, use ~/.local/bin/node. Share images are drawn with ImageMagick's convert, which the server has.
node tools/arcade.mjs check <id>- Check one build.
node tools/arcade.mjs check- Check every build.
node tools/arcade.mjs publish --dry-run- List what would go live.
node tools/arcade.mjs publish- Go live.
What publish does
- Runs the check, and stops if there is any error.
- Rewrites the generated files in
public/:sitemap.xml,llms.txt, and the build list, counts and structured data insideindex.html. It also stamps every link to the site's styles and scripts with a short hash of the file, and puts the music track's address on the Music switch. - Writes a page for every game,
games/<game>/index.html, and for every build,games/<game>/<id>/index.html, and draws ashare.jpgbeside each. An image is drawn again only when the cover or the words on it changed. Builds published before 20 November 2026 had their page at/games/<id>/; a page stays there that forwards to the new address. - Waits for the publish lock, so two publishes never overlap.
- Saves every live file it is about to replace in
.deployments/publish-<time>/before/. - Copies new and changed files from
public/topublic_html/, withindex.htmllast. It never deletes a live file, and it skips build folders that have no entry.
What the check covers
- Always an error: the list does not parse; a required field is missing or has the wrong type; the id is malformed or used twice;
entryorimagedoes not match the id; the folder,index.htmlor the cover is missing; the cover is not WebP;builtAtis invalid or in the future; one title, model or harness is spelled two ways; two titles, or an id and another game's title, would get the same address under/games/; the folder holds server-side code ornode_modules; the code clears storage, registers a service worker, sets a cookie or asks for a browser permission. - An error for new builds:
harnessorbuildSecondsisnull; the cover is not 1280 × 720 or is over 200 KB; the folder is over 5 MB or a file is over 2 MB; something is loaded from another site or by a path starting with/; there is no touch or pointer input; the page is missing its doctype,lang, charset, viewport or title;summaryorgenreis too long;builtAtis not in UTC. Builds published before 20 November 2026 get a warning instead. - A warning: an unknown field, a hidden file, a build folder, game page or build page with no entry, or an absolute URL in the code that is not loaded.
- Not checked, so check it yourself: the game fits its window, plays through with keyboard and with touch, starts, ends and restarts, stays quiet before the first input, prefixes its storage keys, and uses only material you may publish.
Do not
- Edit anything in
public_html/by hand. - Edit
sitemap.xml,llms.txt, anything inpublic/games/, or the parts ofindex.htmlbetweenarcade:comment markers. Publish overwrites them. - Change another build's folder or entry, or the site's own files, to add a game.
Undo a publish
Each publish folder in .deployments/ has a files.txt that lists what it added and updated. To take one back, copy the files from its before/ folder over public_html/ and public/, and delete the files listed as add.
Change or remove a build
- Replace the files: put the new files in
public/arcade/<id>/, keep the id, and publish. If the game was built again, updatebuildSecondsandbuiltAtso they describe the new run. - Different prompt or model: that is a new build. Give it a new id and its own entry.
- Change the entry: edit it and publish. The build's page follows, and so does its share image when the title, model, harness or build time changed.
- Never rename an id or a title. Links to
/games/<game>/<id>/and/arcade/<id>/would break. - Remove: delete the entry and publish, which takes the build out of the library, the sitemap and
llms.txt. Then delete the build's two folders,arcade/<id>/andgames/<game>/<id>/, frompublic/and frompublic_html/; if it was the game's only build, deletegames/<game>/instead. The check names any page folder that is left over. Publish never deletes, so this is the one time live folders are removed by hand.
For crawlers and AI agents
Everything the library shows is also available without running scripts. Publish regenerates all of it from the games list.
/llms.txt: what the site is, and every build with its prompt, model, harness and build time, in plain text./arcade/games.js: the games list itself./games/: every game on one page, a page per game at/games/<game>/that lists its builds, and a page per build at/games/<game>/<id>/. Each has its own title, description, share image and schema.org data, breadcrumbs included./sitemap.xml: every page, including each build's page and the game itself./robots.txt: all crawlers are welcome, AI crawlers included.- The home page carries the same list as plain HTML links and as schema.org structured data.
Checklist
[ ] Folder is public/arcade/<id>/ with index.html at its root
[ ] Static files only, 5 MB or less, no file over 2 MB
[ ] Every file is loaded by a relative path; nothing comes from another site
[ ] Fills any window from 320 x 480 up and never scrolls
[ ] Plays start to finish with keyboard alone and with touch alone
[ ] Start screen, win or lose state, restart without reloading
[ ] No sound before the first input
[ ] Storage keys start with <id>; storage is never cleared
[ ] assets/cover.webp is 1280 x 720, 200 KB or less, subject in the middle
[ ] Entry is first in games.js, with all ten required fields and no null
[ ] title, model and harness match the spelling already in the list
[ ] prompt is word for word; buildSeconds and builtAt describe this run
[ ] node tools/arcade.mjs check <id> reports 0 errors
[ ] node tools/arcade.mjs publish, then one full round from /games/<game>/<id>/ on the live site
The site itself
None of this is needed to add a game. It is for whoever looks after the arcade's own pages: what the site's files are, how its sound works, and the tools that make its music, cursor and share image.
Files
public/index.html- The home page. Publish rewrites the parts between
arcade:markers. public/arcade/- The site's styles, scripts, fonts and music, next to the build folders.
site.css- Styles for every page.
docs.cssadds this page's. fx.js- Effects, sound effects and music.
library.js- The library, Select your build and the build details.
actions.jsruns the Play and Copy buttons on every page. audio/- The music track.
tools/music.mjswrites it. public/about/- The About page: why the site was made and its mission. Written by hand, with the styles of this page.
public/docs/- This page. When a rule changes, change it and
tools/arcade.mjstogether. tools/- Everything that is run by hand, from the home directory.
page.html- The frame of
/games/, of every game page and of every build page. music.mjs- Makes the music track from a recording.
cursor.mjs- Draws the pixel cursors.
og/- Draws the site's share image and icons.
music/- The master recording of the music. Not served.
What publish covers
Publish copies arcade/, about/, docs/, games/ and six files at the root: index.html, robots.txt, sitemap.xml, llms.txt, og.png and favicon.ico. Anything else in public/ goes live only when it is copied to public_html/ by hand.
The hash that publish stamps on a link, as in site.css?v=295bcd1cee, changes when the file does. A browser fetches a changed style or script at once and keeps an unchanged one, so there is no version number to raise by hand.
Visitor statistics
The site's own pages load the Inistats tracking script once the page has finished loading: the home page, About, this page, /games/ and every game and build page. The snippet sits just before </body> in public/index.html, public/about/index.html, public/docs/index.html and tools/page.html. The games themselves do not load it: a build loads nothing from other sites.
Every press of a Play link is counted as a goal named play, with three properties: build (the id), game (the title) and model. Nothing about the player is sent with it. The call is in public/arcade/actions.js; the goal has to exist in the Inistats dashboard with the key play for the counts to show there.
Switches and sound
The home page, the library page and every build page have three switches in the header. This page has none and makes no sound.
- FX: motion and visual effects, the pixel cursor included. On, unless the visitor's system asks for reduced motion.
- SFX: the blips on links and buttons, and the engine sound while the mouse is held on the home page's starfield. On by default.
- Music: one looping track. Off by default.
Each choice is stored in localStorage as on or off, under arcade-fx, arcade-sfx and arcade-music. It holds on the next page, after a reload and on the next visit; a default applies only until the visitor has used the switch.
Browsers allow no sound on a page before the visitor's first click, tap or key press there, and a site cannot change that. So:
- Sound effects begin with that first press.
- Music that was left on keeps playing by itself where the browser allows it. Chrome does when the visitor follows a link within the site.
- Everywhere else, such as after a reload or on a new visit, the Music switch is still on and the track starts with the first press, from where it stopped if that was in the same tab. A note says so once per tab.
- Music stops while the tab is hidden, and from the moment a game is launched until the visitor is back on the page.
Music
The track is public/arcade/audio/theme.mp3, with its loop points in theme.json beside it. tools/music.mjs writes both and needs ffmpeg. Publish then puts the track on the Music switch; while there is no track, the switch stays hidden.
node tools/music.mjs music/smashi-arcade-loop.wav- Make the track again from the master. The whole file is the loop.
node tools/music.mjs <file> --start 8 --bars 32 --bpm 120- Cut a loop out of a longer recording: where it starts, in seconds, and how long it is.
--lengthtakes seconds instead of bars. node tools/arcade.mjs publish- Put the track live.
- What the tool does: cuts the loop, blends its two ends when the recording has music outside the loop, sets a quiet level, and writes a 128 kbit/s MP3 with a quarter second of the loop's far end on each side, so the player can repeat it without a gap. Its last lines say whether the two ends of the loop match.
- A good source: a lossless file that ends on the last beat of a bar, with no intro, fade or final hit. The current track is 32 bars at 120 BPM, 64 seconds.
- Volume:
LEVELin the music part offx.js. - Take the music off: delete the two files from
public/arcade/audio/and frompublic_html/arcade/audio/, then publish. - Rights: only music the site may publish.
Cursor
node tools/cursor.mjs draws the arrow and the hand from the pixel maps at the top of the script. It writes four PNG files to public/arcade/, each cursor at 32 and at 64 pixels, and needs ImageMagick's convert. The hot spots are set in site.css. The cursors show only for a mouse and only while FX is on; this page and the games keep the system cursor.
Share image and icons
node tools/og/render.cjs draws tools/og/og.html as public/og.png, the 1200 × 630 image that chat apps show for the home page and for this page. It also makes favicon.ico and arcade/apple-touch-icon.png from arcade/logo.svg. It needs headless Chromium, through playwright-core, and convert. Run it after changing og.html or the logo, then publish. Build pages have their own share images, which publish draws.
House rules
- No sideways scrolling: every page, and every section inside a page, fits its width from 320 pixels up.
- Complete without scripts: every page works as plain HTML. Scripts add the effects, the sound and the build dialog.
- Wording: the arcade says “Insert joy” where a cabinet would say “Insert coin”, as in “Free play · Insert joy” and “Game over? Insert joy to continue”.
- Storage: the site's keys all start with
arcade-. Besides the three switches, it keeps the credits counter inarcade-plays.