# How to Build a Great Browser Minigame Version: 1.0 (2026-07-12) Canonical URL: https://fyrka.games/dev/minigame-guide.md Hard platform rules: https://fyrka.games/dev/fyrka-game-spec.md (read that one too — it is the contract, this file is the craft) This guide is for everyone who builds games for FYRKA — humans, AI agents, and human+AI teams ("vibecoding"). FYRKA does not care which tools you use. We care whether the game is fun in the first ten seconds and honest about what it is. ```bash # Give your AI agent the full FYRKA knowledge base: curl -fsSL https://fyrka.games/dev/llms.txt curl -fsSL https://fyrka.games/dev/fyrka-game-spec.md -o FYRKA.md curl -fsSL https://fyrka.games/dev/minigame-guide.md -o FYRKA-GUIDE.md ``` ## 1. One mechanic, done well The best browser minigames are one verb: jump, drift, aim, wash, stack, dodge. Pick one verb and make it feel great before you add anything else. - If you cannot describe your game in one sentence with one verb, cut. - Every extra system (inventory, crafting, dialogue) steals polish time from the verb that actually sells the game. - A good test: after 30 seconds of play, has the player done the core verb at least ten times? ## 2. The first ten seconds Browser players give you seconds, not minutes. The game must: 1. Load fast (under ~3 seconds on a mid phone — see the spec's size limits). 2. Show gameplay immediately — no splash screens, no settings walls. One "Play" button at most. 3. Teach by doing. One short hint line ("Arrow keys to drift") beats a tutorial. If the game needs a manual, the design needs work. 4. Let the player fail fast and restart instantly. Restart must never take longer than one second or one key press (R is the convention). ## 3. Game feel ("juice") is the difference Two games with identical rules can feel amateur or amazing. The difference is feedback: - **Every action reacts.** Hit = flash + particles + sound + tiny screen shake. Score = number pops up where it happened, not just in a corner. - **Animate transitions.** Nothing should teleport: scale buttons on press, ease the camera, tween score counters. - **Squash and stretch.** A jump that stretches on rise and squashes on landing reads as alive, even with cube graphics. - **Keep it cheap.** Juice is math, not assets: sine wobble, eased lerps, a dozen colored squares as particles. No texture packs needed. Budget rule of thumb: spend 50% of your time on the core loop, 30% on feedback/juice, 20% on everything else. ## 4. Controls: desktop AND phone More than half of browser play is on phones. A FYRKA game should support: - **Desktop:** keyboard (WASD/arrows + one action key) or mouse. Show the keys on screen until the player uses them. - **Touch:** a virtual joystick or direct touch/swipe, plus at most 1–2 buttons. Big hit areas (≥ 64px), placed in thumb reach, `touch-action: none` on the canvas so the page does not scroll. - Never require hover, right-click, or precise cursor work on touch. - Pause automatically when the tab loses focus. If your one verb cannot work on touch, be honest in the game description ("desktop only") — but expect fewer players. ## 5. Performance budget Target: steady 60 FPS on a three-year-old mid-range phone. - One canvas, one render loop via `requestAnimationFrame`. Stop the loop when the tab is hidden. - Reuse objects; avoid allocating in the frame loop (garbage collection spikes = stutter). - Keep draw calls and particle counts bounded. Cap delta time so a lag spike does not teleport the player. - Compress assets: total bundle well under the spec limit is not the goal — small enough to load in ~3 seconds on mobile data is. - Test with the browser's CPU throttling (6x) at least once. ## 6. Look and sound on a budget - **Palette first.** Pick 4–6 colors and stick to them. A consistent cheap look beats an inconsistent fancy one. Flat colors + one light direction is a complete art style (it is the FYRKA house look, too). - **Readable at a glance.** Player, threats, and pickups must be distinguishable by silhouette and color alone. - **Sound is optional but powerful.** A few short synthesized effects (jump, hit, score) add more than a music track. Autoplay is blocked by browsers: start audio only after the first user input, and never make sound required to play. ## 7. Score, restart, "one more run" Replayability comes from a clear score and a fast loop, not from content volume: - One number the player optimizes ("best height", "fastest lap", "days survived"). Show it during play and on the result screen. - Result screen = score, personal best, one big "Retry" button. - Difficulty should ramp inside a run (speed up, spawn more) so every run ends — a run that cannot be lost is a screensaver. - Deterministic daily seeds ("today's track is the same for everyone") are a cheap way to make players come back and compare scores. ## 8. Vibecoding: working with an AI agent FYRKA is explicitly friendly to AI-built games. What works in practice: - **Feed the contract first.** Give your agent `FYRKA.md` (the spec) and this guide before the first prompt. Hard rules up front prevent painful rewrites (external CDNs, forbidden APIs, wrong bundle layout). - **Iterate in the browser, not in the chat.** Short loop: prompt → open `index.html` → play 60 seconds → tell the agent the top ONE problem. Ten small rounds beat one giant prompt. - **Ask for feel, not features.** "Make the jump feel snappier: shorter rise, faster fall, squash on landing" gets better results than "improve the game". - **Watch for classic AI-game bugs:** buttons that do nothing, fake features in the description (multiplayer that does not exist, shops with nothing to buy), difficulty that never ramps, memory leaks in the frame loop, and touch controls that were never actually tested on a phone. - **Never claim what the game does not do.** The FYRKA review checks the store description against the actual game. Honest games get published; invented features get rejected. ## 9. Quality checklist (run before every upload) Gameplay - [ ] Core verb is fun within 30 seconds - [ ] A first-time player understands the goal without a manual - [ ] Every run can be lost; difficulty ramps - [ ] Restart in ≤ 1 second (button + R key) Technical - [ ] `index.html` in the bundle root; opens and plays from a plain static server - [ ] No external hosts (fonts, CDNs, analytics) — everything ships in the bundle - [ ] 60 FPS on a mid phone; loop pauses when the tab is hidden - [ ] No console errors during a full run - [ ] Works in Chrome, Firefox and Safari (WebKit has the strictest audio/fullscreen rules) Mobile - [ ] Playable with touch only (or clearly labeled desktop-only) - [ ] UI readable at 375px width, portrait or landscape handled - [ ] No accidental page scroll/zoom while playing Honesty & polish - [ ] Store description matches the actual game — no invented features - [ ] Score, best score and result screen work - [ ] Sound (if any) starts only after user input and has a mute toggle ## 10. Publishing on FYRKA 1. Zip your bundle (`index.html` at the zip root, everything self-contained). 2. Check the hard limits in the spec (size, file types, forbidden APIs). 3. Upload at https://fyrka.games/creator-upload.html — the automated scan answers immediately. 4. A human reviews every scanned game before it goes live. We review the game, not your toolchain: AI-built, hand-built or both — same bar for everyone. 5. Published games run in a sandboxed player with their own page (`/g/your-slug`), leaderboards via the platform bridge, and a report flow players can use. Questions or stuck at the scan? The upload page shows the exact rejection reason; fix it and upload again — there is no penalty for retries.