@opengamehq/cli 0.0.0-stage → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. package/AGENTS.md +235 -0
  2. package/CHANGELOG.md +9 -0
  3. package/README.md +128 -2
  4. package/dist/cli.mjs +1415 -0
  5. package/dist/opengame-global.js +3 -0
  6. package/dist/opengame-global.js.LEGAL.txt +1 -0
  7. package/dist/preflight-worker.mjs +13 -0
  8. package/dist/runtime-builder.mjs +800 -0
  9. package/dist/runtime-catalog.json +1 -0
  10. package/dist/runtime-catalog.sha256 +1 -0
  11. package/dist/runtime-shells/runtime-shell.html +4 -0
  12. package/dist/runtime-shells/runtime-shell.js +91 -0
  13. package/dist/safe-fs.py +242 -0
  14. package/dist/skills/manifest.json +512 -0
  15. package/dist/skills/opengame-accessibility/SKILL.md +90 -0
  16. package/dist/skills/opengame-api/SKILL.md +85 -0
  17. package/dist/skills/opengame-assets/SKILL.md +124 -0
  18. package/dist/skills/opengame-assets/references/pipeline.md +97 -0
  19. package/dist/skills/opengame-audio/SKILL.md +154 -0
  20. package/dist/skills/opengame-audio/helpers/audio-chain.js +325 -0
  21. package/dist/skills/opengame-audio/references/mix-notes.md +82 -0
  22. package/dist/skills/opengame-capture/SKILL.md +108 -0
  23. package/dist/skills/opengame-capture/references/pipeline.md +82 -0
  24. package/dist/skills/opengame-capture/references/threejs.md +145 -0
  25. package/dist/skills/opengame-characters/SKILL.md +129 -0
  26. package/dist/skills/opengame-characters/references/integration.md +144 -0
  27. package/dist/skills/opengame-characters/references/player-og.md +160 -0
  28. package/dist/skills/opengame-cli/SKILL.md +118 -0
  29. package/dist/skills/opengame-deploy/SKILL.md +204 -0
  30. package/dist/skills/opengame-deploy/references/json-events.md +62 -0
  31. package/dist/skills/opengame-deploy/references/manifest.md +83 -0
  32. package/dist/skills/opengame-deploy/references/packaging.md +117 -0
  33. package/dist/skills/opengame-depth/SKILL.md +130 -0
  34. package/dist/skills/opengame-enemies/SKILL.md +103 -0
  35. package/dist/skills/opengame-enemies/references/threejs.md +134 -0
  36. package/dist/skills/opengame-front-end/SKILL.md +143 -0
  37. package/dist/skills/opengame-front-end/references/launch.md +50 -0
  38. package/dist/skills/opengame-front-end/references/menus.md +47 -0
  39. package/dist/skills/opengame-game-feel/SKILL.md +137 -0
  40. package/dist/skills/opengame-game-feel/helpers/spring.js +146 -0
  41. package/dist/skills/opengame-game-feel/references/feel-numbers.md +83 -0
  42. package/dist/skills/opengame-jam/SKILL.md +103 -0
  43. package/dist/skills/opengame-lighting/SKILL.md +94 -0
  44. package/dist/skills/opengame-lighting/helpers/light-pool.js +185 -0
  45. package/dist/skills/opengame-loading/SKILL.md +99 -0
  46. package/dist/skills/opengame-loading/references/threejs.md +116 -0
  47. package/dist/skills/opengame-look/SKILL.md +114 -0
  48. package/dist/skills/opengame-look/references/post-and-lens.md +66 -0
  49. package/dist/skills/opengame-mobile/SKILL.md +90 -0
  50. package/dist/skills/opengame-performance/SKILL.md +140 -0
  51. package/dist/skills/opengame-performance/references/measuring.md +72 -0
  52. package/dist/skills/opengame-production/SKILL.md +131 -0
  53. package/dist/skills/opengame-production/references/templates.md +63 -0
  54. package/dist/skills/opengame-quality-bar/SKILL.md +122 -0
  55. package/dist/skills/opengame-quality-bar/references/cheap-tells.md +36 -0
  56. package/dist/skills/opengame-quality-bar/references/review-prompt.md +27 -0
  57. package/dist/skills/opengame-router/SKILL.md +51 -0
  58. package/dist/skills/opengame-router/references/process.md +38 -0
  59. package/dist/skills/opengame-scene-audit/SKILL.md +123 -0
  60. package/dist/skills/opengame-scene-audit/helpers/scene-audit.js +599 -0
  61. package/dist/skills/opengame-sdk/SKILL.md +254 -0
  62. package/dist/skills/opengame-sdk/references/engines.md +93 -0
  63. package/dist/skills/opengame-sdk/references/frame.md +107 -0
  64. package/dist/skills/opengame-sdk/references/identity.md +112 -0
  65. package/dist/skills/opengame-sdk/references/leaderboards.md +83 -0
  66. package/dist/skills/opengame-stability/SKILL.md +84 -0
  67. package/dist/skills/opengame-verification/SKILL.md +136 -0
  68. package/dist/skills/opengame-verification/helpers/browser-evidence.mjs +74 -0
  69. package/dist/skills/opengame-weapons/SKILL.md +109 -0
  70. package/dist/skills/opengame-weapons/references/handling-numbers.md +72 -0
  71. package/dist/skills/opengame-weapons/references/threejs.md +169 -0
  72. package/dist/skills/opengame-world-physics/SKILL.md +114 -0
  73. package/dist/skills/opengame-world-physics/references/measured-failures.md +52 -0
  74. package/package.json +38 -4
@@ -0,0 +1,130 @@
1
+ ---
2
+ name: opengame-depth
3
+ description: Give a browser game depth instead of a single verb. Covers proving a natural win exists, boss health sized from real damage, a first goal reachable at spawn, a spawn controller with wave sizes and a cap, rounds that never stall, short defence objectives, a boss goal the player can read, dev staging to any moment of a run, tuned odds, and systems that interact. Use when the person says the game is boring, too hard, rounds drag, it is unclear what to do, or it feels like a tech demo.
4
+ metadata:
5
+ version: "1.0.0"
6
+ ---
7
+
8
+ # Depth
9
+
10
+ A game is deep when its systems create decisions together: what you carry changes how
11
+ you fight, the ground changes your route, what you prepare changes the next encounter.
12
+ A decorative counter, a menu for an unfinished system or a bigger map is not depth. The
13
+ fastest way to look shallow is a minigame: one verb, no consequence, nothing to learn.
14
+
15
+ Rules carry five tags; `opengame-quality-bar` explains them and the game codes. OC's run is a wave
16
+ shooter with rounds of zombies, three generators to defend and then a boss.
17
+
18
+ ## Rules
19
+
20
+ ### Prove a natural win exists
21
+ - **Invariant:** Before any tuning for feel, unstaged runs by bots at several skill levels show that a player can reach and finish every stage of the run with the gear the game gives them.
22
+ - **Technique:** Write the target in rounds or minutes for a strong, an average and a new player. Run bots through the real game with no cheats and log where each run ends and why. Compare enemy health, player damage and boss health against what a full loadout can deal. Change one variable at a time between runs.
23
+ - **Reference configuration:** OC's first gameplay audit lost 7 of 7 natural bot runs: round 1 zombies had round 10 health, and each boss lock-core had 35,000 HP, more than a full loadout could deal. OC's targets: the boss wakes by round 8 to 10 for a great player, 10 to 12 for a decent one and 12 to 15 for a beginner. Difficulty later swung from "literally not even killing me" to a death in 0.37 s before settling at 3 hits to down.
24
+ - **Applies when:** Every game with a win condition, runs, waves or a boss.
25
+ - **Verify:** A bot run with no cheats reaches each stage within its target band; the report lists the round and cause of every loss.
26
+
27
+ ### Boss health comes from the damage a player can deal
28
+ - **Invariant:** The boss's health and each vulnerable window are sized from the damage the expected loadout deals in that window, and one document holds the number.
29
+ - **Technique:** Compute damage per second for the loadout a player has at that stage, multiply by the length of each vulnerable window and the number of windows the fight should take, and set health from that. Keep the value in one spec file that code reads.
30
+ - **Reference configuration:** OC's spec said 400,000 HP while the code held 60,000, and the spec had 4 phases against the code's 3. The rebalance moved to the reference game's solo formula with the titan at 120,000.
31
+ - **Applies when:** Games with bosses, shields or damage gates.
32
+ - **Verify:** A bot with a middle loadout breaks one weak point inside one window, and a full fight lands inside the target length.
33
+
34
+ ### The first goal is reachable at spawn
35
+ - **Invariant:** A new player can afford and see the first goal from where they start, and the objective panel, banners, voice and tips all state the same goal in the same words.
36
+ - **Technique:** Price the first purchase or gate at or below the starting money. Write each objective once, in one table, and drive the panel, banner, voice line and loading tip from it. Prompts name the action and the cost.
37
+ - **Reference configuration:** OC started the player with 500 points against a 750 gate, a design bug; the fix was a 500 gate and a "First: Quick Revive (500)" tip. OC once shipped three boss instructions at once, and its HUD still said "lock-cores 0/4" after the mechanic changed. Its prompt form: "Hold F to open the East Gate [750]".
38
+ - **Applies when:** Every game with an economy or an objective chain.
39
+ - **Verify:** A stranger reaches the first goal without help, and a search of the strings finds each objective worded once.
40
+
41
+ ### A spawn controller owns wave size, the cap and placement
42
+ - **Invariant:** One controller sets how many enemies each wave has, how many may be alive at once and where they appear, and early waves are small and close to the player.
43
+ - **Technique:** A table of wave sizes and health per round, a hard cap on live enemies, spawns spread across several approaches near the player, and no spawns during breaks. Every other system asks the controller for spawns instead of creating enemies itself.
44
+ - **Reference configuration:** OC used the reference game's solo counts (6, 8, 13, 18, 24) and at most 24 alive (R110). Before the controller, early rounds flooded with spawns. Spawn accounting and the remaining-enemies counter are in `opengame-enemies`.
45
+ - **Applies when:** Wave, horde and arena games.
46
+ - **Verify:** Log spawns per second and live count across rounds 1 to 5: each wave matches the table and the live count stays at or under the cap.
47
+
48
+ ### Rounds never stall
49
+ - **Invariant:** Every round ends a short time after the player kills what they can reach, and the last enemies are easy to find.
50
+ - **Technique:** Keep early breaks short, recover stragglers that stop making progress, respawn an enemy that has been out of sight and stuck for too long, and point at the last few enemies with a marker that shows above or below. Run full games with real input to find the stalls.
51
+ - **Reference configuration:** OC's breaks are 5 s in rounds 1 to 3 and 10 to 12 s after; stragglers are recovered after 12 s; markers appear once fewer than 5 remain (the last 1 to 4 at the radar edge). One OC round took 313 s. The owner asked for faster early rounds about 9 times. Stuck-enemy recovery steps are in `opengame-enemies`.
52
+ - **Applies when:** Wave and round-based games, and any objective that waits for "kill all".
53
+ - **Verify:** Over 20 automated rounds, log time from the last reachable kill to the round end: none exceeds the straggler limit.
54
+
55
+ ### Defence objectives are short and bounded
56
+ - **Invariant:** A defend-this objective has a fixed length, a limit on attackers and a readable health for the thing defended, and each one has its own sound, effects and voice.
57
+ - **Technique:** Set the duration, the number of attackers allowed at once, the spacing between their spawns and the damage each hit does to the objective. Show the objective's health while it is attacked. Give each objective its own music, effect and start, middle and end lines.
58
+ - **Reference configuration:** OC's sleeping titan wakes after three generators are defended (R89, which replaced three seals). The owner's game "crashed again while defending a generator", so each objective also needs its own soak test.
59
+ - **Applies when:** Escort, hold, capture and defend objectives.
60
+ - **Verify:** Play each objective with no damage dealt: it fails at the expected time. Play it well: it succeeds within its duration, and its health bar matches the logged hits.
61
+
62
+ ### The player always knows how to hurt the boss
63
+ - **Invariant:** At every moment of a boss fight the player can tell the one current goal, where to shoot, and whether the shot did anything.
64
+ - **Technique:** One goal per phase, worded the same in the HUD, banner and voice. Weak points that are large enough on screen at any range, saturated and pulsing, in a colour that means "shoot here" everywhere in the game and does not also mean danger. Damage numbers on a hit and an "immune" cue on a blocked one. A visible break when a weak point falls. The boss's own animation and telegraphs are in `opengame-enemies`.
65
+ - **Reference configuration:** OC's owner: "its completely unclear how to take down the titan or where u hvae to aim for / shoot at", raised 4 or more times; "i couldnt tell fi ti does anything". OC's fixes: weak points at 28 to 32 px or more at any range (1.5 to 2% of frame width), pulsing; crack beats at 66% and 33% health; a 2.5 s stagger on a break; orange means immune, cyan or violet means shoot here. A test bot hit weak points for only 8 of 489 s. One redesign left the boss asleep forever in normal runs.
66
+ - **Applies when:** Any boss or multi-stage enemy.
67
+ - **Verify:** A stranger plays the fight with no briefing and says, at three random pauses, what the goal is and where to shoot. Capture the weak points at the nearest and farthest fighting range.
68
+
69
+ ### Stage any moment of a run in seconds
70
+ - **Invariant:** Developers and test agents can jump to any round, phase or objective with any loadout, and none of that reaches production.
71
+ - **Technique:** Dev switches for god mode, no enemies, extra money, any weapon, every gate open, each objective complete and a jump to any round or straight to the boss. Use them to reach and test late content; judge feel and difficulty only on unstaged runs. Strip the switches from the production build or lock them behind a key the server checks.
72
+ - **Reference configuration:** OC's set: god mode, ghost town, +50,000 points and a jump to any round, after the owner told agents to "give urself god mode / infinite health". OC's production build stores the dev key only as a hash. Dev flags still leaked fake points into captures.
73
+ - **Applies when:** Every game longer than a few minutes.
74
+ - **Verify:** Reach the boss from a cold start in under a minute in a dev build; in the production build every dev switch does nothing.
75
+
76
+ ### Random rewards have tuned odds and a pity timer
77
+ - **Invariant:** Random rewards follow odds set against the genre reference, a long dry streak ends, and every path that can grant a rare item goes through the same odds.
78
+ - **Technique:** Write the odds per rarity, add a pity counter, show rarity with spectacle (colour, beam, sound), and list every code path that writes to an inventory slot so a rare item cannot arrive by another route. Audit each weapon's time to kill at several stages of the run.
79
+ - **Reference configuration:** OC's wonder weapon came at 1 in 56, then about 1 in 102, against 1 in 20 to 25 in the reference game; pity after 16 to 20 pulls. Wonder weapons are crate-only, which meant auditing 11 slot-write paths. Time to kill is audited at rounds 1, 10, 20 and 30.
80
+ - **Applies when:** Games with loot boxes, drops, crates or random rewards.
81
+ - **Verify:** Simulate 10,000 pulls and compare the rates with the table; trace each slot-write path to the odds function.
82
+
83
+ ### Systems are defined before code
84
+ - **Invariant:** Each system in the game exists because it changes a decision the player makes, and that change is written down before the system is built.
85
+ - **Technique:** For each system, one line each: the decision it creates, what it interacts with, and how the player learns it. Cut any system with no answer. Build the interactions, not only the systems.
86
+ - **Reference configuration:** ST's craft defaults: different weapons change tactics, terrain changes routes, preparation changes the next encounter, and a decorative counter is not evidence of depth.
87
+ - **Applies when:** Every game with more than one mechanic.
88
+ - **Verify:** Play two runs with different choices; the runs play differently in a way you can describe.
89
+
90
+ ### The whole archetype, not a minigame
91
+ - **Invariant:** The game delivers the archetype it belongs to (its loop, progression, failure and reason to return), not only the first ten seconds of it.
92
+ - **Technique:** Name the genre's archetype and list what a player of it expects from a full session. Build the loop end to end (start, escalate, fail or win, retry with something learned) before widening any one part.
93
+ - **Reference configuration:** Our originals' rule after a laser-and-prism board with one verb was filed as the thing not to make again: every game is a deep game, with systems that interact, a run that teaches, and a reason to come back tomorrow.
94
+ - **Applies when:** Every game, at every scope. A small game can be deep; a big one can be a minigame.
95
+ - **Verify:** A person who did not build it plays three sessions and can say what they would do differently next time.
96
+
97
+ ### One dense hero location first
98
+ - **Invariant:** One place in the game is finished to the bar before more places are added.
99
+ - **Technique:** Pick the location the first minute happens in and finish it: layout that creates routes and choices, a focal landmark, foreground, midground and distance, grounded props, the overhead layer, light and sound. Copy its standards outward, not its props.
100
+ - **Reference configuration:** MC's Rust map: about 2,900 primitives, 423 decals in one draw, 109 contact-shadow quads and 1,500 dust motes in 44 by 44 m. SR's island: 2,609 props, 6,512 grass clumps and 913 flowers.
101
+ - **Applies when:** Every game with a world to move through.
102
+ - **Verify:** Captures of the hero location from the player's camera pass the cheap-tells review in `opengame-quality-bar`.
103
+
104
+ ### Dressing is placed by rules
105
+ - **Invariant:** Set dressing looks authored: it sits where such things would be, never blocks paths or interactions, and comes out the same every session.
106
+ - **Technique:** Scatter from a seeded generator and reject candidates by surface, slope, footprint flatness, clearance from paths, stairs, doors and interactables, and a noise mask. Place props against real walls, not in the open; dress the overhead layer with pipes, ducts, beams and cables; rotate things a few degrees off square; keep litter low enough never to block movement.
107
+ - **Reference configuration:** DK tries 8 positions per prop, each clear of walkways and against a wall, with per-room counts (a factory: 8 crates, 7 drums, 4 rubble piles, 3 machines). The ST bar's scatter rules keep half a path's width plus 1.2 m clear of paths and 5 m clear of stairs, reject footprints less flat than 0.45 m, and vary scale 0.7 to 1.5 with tint. Litter stays under 0.3 m.
108
+ - **Applies when:** Any game with dressed spaces.
109
+ - **Verify:** The scene audit passes (`opengame-scene-audit`), and the walk bot reaches every interaction point.
110
+
111
+ ### Opponents telegraph
112
+ - **Invariant:** Every threat shows what it is about to do in time for the player to answer, and the answer is a skill the player can improve.
113
+ - **Technique:** Anticipation before every attack (pose, sound, light), a readable recovery after it, and attack patterns that combine the same few tells in new ways as the game escalates.
114
+ - **Reference configuration:** ST's craft defaults tie anticipation, contact, recovery, sound and visual cues to every real action, and its sound plan gives every enemy anticipation, action and reaction cues. OC's boss wind-ups run at least 900 ms, and 2,500 ms for attacks that down the player (`opengame-enemies`).
115
+ - **Applies when:** Games with opponents, hazards or bosses.
116
+ - **Verify:** Mute the game and play: every attack can still be read from the picture. Then play with the screen dimmed: the important ones can be read from sound.
117
+
118
+ ### Mashing does not win
119
+ - **Invariant:** Pressing buttons at random loses to playing well, at every difficulty past the first.
120
+ - **Technique:** Commitment on actions (wind-up, recovery, resource cost), punishable whiffs, and defence that rewards timing. Test it directly with a random-input bot.
121
+ - **Reference configuration:** A rule from the plan for OpenGame's craft skills (ST). None of our four games measured it, so there is no number to copy: the random-input bot is the measurement.
122
+ - **Applies when:** Action, fighting and arcade games.
123
+ - **Verify:** A bot that presses random inputs for a full match scores clearly worse than a person who plays with intent.
124
+
125
+ ### Teach in the scene
126
+ - **Invariant:** The player learns each action at the moment they need it, from the game itself, and the hints match the real keys.
127
+ - **Technique:** A short hint in the world, shown when the action first becomes useful, generated from the same action table input uses. No wall of controls before play.
128
+ - **Reference configuration:** Our originals' best opening is one line beside a live match with both control legends on screen: the menu states the verb.
129
+ - **Applies when:** Every game.
130
+ - **Verify:** A stranger completes the first objective without opening a help screen.
@@ -0,0 +1,103 @@
1
+ ---
2
+ name: opengame-enemies
3
+ description: Make enemies, hordes, teammates and bosses in a 3D browser game move and fight as designed. Covers a pursuit test that measures reach, jump links for player-built geometry, stuck recovery, no unreachable perches, navigation work budgeted per frame, a counter that matches the screen, teammate metrics, deaths per weapon, and a boss that lives and telegraphs. Use when the person says zombies get stuck, enemies stand around, allies are dumb, the counter is wrong, or the boss feels dead.
4
+ metadata:
5
+ version: "1.0.0"
6
+ ---
7
+
8
+ # Enemies, hordes and bosses
9
+
10
+ An enemy that stops moving breaks a game faster than anything else it can do. A zombie
11
+ pressed against a railing, a teammate frozen in the air or a horde counter that says 1
12
+ while a hundred spawn reads as broken within seconds. Most of these have three
13
+ causes. The navigation was built for a different body than the one walking it, the team
14
+ does not measure whether enemies arrive, and recovery is a guess.
15
+
16
+ Rules carry five tags; `opengame-quality-bar` explains them and the game codes. OC is
17
+ OG Clash, a first-person wave shooter with a boss. Its owner's longest-running complaint
18
+ was stuck zombies and teammates: about 35 messages between 16 and 21 Oct ("NO ONE should
19
+ ever gut stuck"), open across 40 or more builds, and about 5 days to close.
20
+
21
+ Navigation settings that must match the body (step height, radius, slope) are in
22
+ `opengame-world-physics`. Wave sizes, round pacing and the boss goal are in
23
+ `opengame-depth`. Three.js libraries and calls for everything here are in
24
+ [references/threejs.md](references/threejs.md).
25
+
26
+ ## Rules
27
+
28
+ ### Measure reach, not motion
29
+ - **Invariant:** Every enemy type reaches the player from every place the player can stand, and the team has measured the reach rate in a test.
30
+ - **Technique:** Build a pursuit test. Place the player at a grid of spots that covers floors, roofs, ramps, player-built structures and water exits; spawn several enemies at the real spawn points; log for each one whether it arrives and how long it takes. Count an enemy as stalled when its distance to the player stops falling while it is still far away, so circling in place counts as a failure. Run it on every build that touches navigation, and run real rounds as well, because the test only covers the spots you give it.
31
+ - **Reference configuration:** OC's pursuit test used 34 spots and 4 zombies per spot; stalled meant under 0.25 m/s of progress for 3 s while more than 3 m away. Reach within 40 s rose from 55% to 84%, and stalls fell from 0.76 to 0.11 per enemy-minute (R157). Real rounds still had 30% of zombies not arriving within 30 s, and roofs at 14 and 17 m stayed 0 of 8.
32
+ - **Applies when:** Any game whose enemies or allies chase the player through 3D space.
33
+ - **Verify:** The pursuit report lists reach rate, median time and stalls per spot, and the worst spots are captured on video.
34
+
35
+ ### Links for every move the agent can make
36
+ - **Invariant:** Every jump, drop, climb and gap an enemy's body can cross is in the navigation as a link the planner can use, including on geometry the player builds during play.
37
+ - **Technique:** Generate links from the agent's capability (jump height, jump distance, safe drop height) by scanning ledges and gaps in the collision geometry, then publish them into the navigation. Rebuild them when the player places, raises or destroys a structure. Each link stores its action (walk to takeoff, jump, land) so the agent plays the right motion. A body able to jump still needs the planner to route it to the takeoff point.
38
+ - **Reference configuration:** OC's agents wrote their own gap-link publisher, ballistic jump planner and stale-takeoff checks over about 18 builds (R116 to R134). In one live test "the player reached the roof, but the NPC jump link was never created". Zombies were found stuck behind a railing in a player-built tower. Dynamic jump links landed in R119.
39
+ - **Applies when:** Games with vertical levels, gaps, ledges or player-built geometry.
40
+ - **Verify:** Draw every link in a debug view. Build each player structure, stand on top, and run the pursuit test from there.
41
+
42
+ ### Stuck enemies recover in escalating steps
43
+ - **Invariant:** An enemy that stops making progress always recovers, by steps that start small and end with a respawn the player cannot see.
44
+ - **Technique:** Watch progress toward the target, not movement. When it stalls, repath or climb first, then side-step, then respawn out of the player's sight, and as a last resort sink a body the player is watching. Recycle stranded enemies that have gained little ground over a long window, as long as they are out of view and not close to the player. Limit how often one enemy may repath.
45
+ - **Reference configuration:** OC's steps: repath or climb at 1.75 s, side-step at 3.25 s, respawn unseen at 5 s, sink if watched at 8 s (R183). Stranded recycle: under 1.5 m of gain in 35 s, out of view. Repath floor 0.5 s.
46
+ - **Applies when:** Every game with chasing AI.
47
+ - **Verify:** Trap enemies on purpose (behind a railing, in a corner, on a ledge) and log each recovery step firing at its time.
48
+
49
+ ### No perch the enemies cannot reach
50
+ - **Invariant:** Every place the player can stand, enemies can reach or attack, unless the design marks it unreachable on purpose and moves the player off it.
51
+ - **Technique:** Find the islands in the navigation the player can reach and the enemies cannot. Either link them, spawn attackers at their foot, or make the spot slippery with a short hint so the player slides off. A slide must not damage or teleport the player.
52
+ - **Reference configuration:** OC's navigation had 129 islands, and glide-only roofs at 14 and 17 m were safe camping spots. Its fixes: a no-perch slide after about 2 s with a hint and no damage or teleport (R164), siege spawns at the foot when the player is 3 m or more up for 0.5 s, and a target of a hit within 8 s on any build.
53
+ - **Applies when:** Games with climbable geometry, player building or roofs.
54
+ - **Verify:** Stand on each high spot for 15 s with god mode on: the player is attacked or slides off on every one.
55
+
56
+ ### Navigation work fits the frame
57
+ - **Invariant:** Navigation rebuilds and path requests never hitch the game, however much geometry changes or however many agents ask for paths.
58
+ - **Technique:** Rebuild navigation tiles across several frames with a per-frame budget and keep tiles small enough that one tile fits it. Model doors, gates and barricades as area costs or obstacles so opening one needs no rebuild. Do not rebuild for transient effects such as boss attacks. Spread path requests across frames with a queue, share results between agents headed to the same place, and use a spatial grid for separation instead of checking every pair.
59
+ - **Reference configuration:** OC's 4-piece player build dirtied about 111 tiles, caused 39 to 43 ms spikes and left new builds without a path for about 7 s. Throttling from 64 to 16 tiles a frame could not fix it alone, since one tile took about 40 ms. Another single collider change dirtied 104 tiles and gave 7 to 14 frames of 60 to 100 ms, and OC stopped rebuilding for smash attacks. OC's gates became infinite-cost areas with no rebuild. Ally pathing went from 18 calls to 1 (R140).
60
+ - **Applies when:** Games with dynamic geometry or more than a handful of agents.
61
+ - **Verify:** Place and destroy structures and trigger every boss attack in a horde round while logging frame time and navigation time per frame: no frame passes the budget.
62
+
63
+ ### The counter matches the screen
64
+ - **Invariant:** The enemies-remaining number equals the enemies alive plus those still queued to spawn, every drawn enemy can be hit, and every hittable enemy is drawn.
65
+ - **Technique:** Keep one ledger that every spawn, death, despawn and respawn goes through, and drive the HUD from it. Keep each enemy's hit volume on its drawn body during leaps, climbs and recovery steps. Count a respawn as the same enemy.
66
+ - **Reference configuration:** Before OC's spawn accounting (R109) the owner saw "it says 1 remaining and ij ust had like a hundred spawn" and "says like 3 remaining but there are so many". "Ghost" zombies stayed visible and could not be shot. OC caps live zombies at 24 (`opengame-depth`).
67
+ - **Applies when:** Every game with a remaining-enemies count or a round end that waits for kills.
68
+ - **Verify:** Log the ledger and a count of drawn enemies every second through 10 rounds: they agree, and frames where a drawn body is far from its hit volume number zero.
69
+
70
+ ### Teammates are measured like players
71
+ - **Invariant:** AI teammates follow, fight, revive and keep up with the player, and their success is measured on the routes they walked, with teleports counted separately.
72
+ - **Technique:** Track rejoin rate, time stuck, time frozen in the air, far revives and shots on the boss. Log every regroup teleport and report navigation-only success on its own. Give teammates formation slots beside or behind the player, keep them out of the player's view cone, cap their damage so enemies stay a threat, and credit each kill to one squad member.
73
+ - **Reference configuration:** OC measured 14.7% of teammate-seconds frozen in the air and 7 boss shots out of 322, and found that regroup teleports had inflated its teammate metrics. Earlier allies killing at 180 DPS within 6 m made zombies harmless; they now rescue only within 2.6 m. Teammates do rare flips every 30 to 60 s.
74
+ - **Applies when:** Games with AI squadmates, companions or bots in the player's team.
75
+ - **Verify:** A 10-minute run reports each metric with teleports excluded, against the previous build.
76
+
77
+ ### The boss telegraphs every attack
78
+ - **Invariant:** Every boss attack is announced in time to answer it, and its warning travels at the speed of the real damage.
79
+ - **Technique:** A wind-up long enough to react, longer for attacks that down the player. Mark danger areas by their edge, a band and a progress wipe instead of a filled area that floods the view. Move a shockwave's visual and its damage front together. A dodge prompt names the verb. Weak points and the boss's goal are in `opengame-depth`. No boss action may hitch: prebuild its effects, death and results screens.
80
+ - **Reference configuration:** OC's wind-ups are at least 900 ms, and 2,500 ms for downing attacks. Dodge windows are 2.2 to 2.8 s. The shockwave travels at 20 m/s, matching its damage. A filled 10 m orange circle turned the whole view orange, so OC draws the rim, a glyph band and a wipe. The titan's death frame fell from 509 to 117 ms (R184).
81
+ - **Applies when:** Any boss or large enemy with readable attacks.
82
+ - **Verify:** Play each attack at 0.25 times speed beside its damage log: the warning and the damage line up.
83
+
84
+ ### The boss is alive and moves with weight
85
+ - **Invariant:** The boss breathes, shifts and reacts on every screen it appears on, its feet stay planted, and its clips never slide it across the floor.
86
+ - **Technique:** Layer idle life (breathing, weight shifts, a roar or gesture) over every state, sleeping included. Add hysteresis to walk and turn decisions. Strip root motion from library clips and drive movement from the game. Fit menu and cinematic cameras from its live joints.
87
+ - **Reference configuration:** OC's titan breathes every 3 to 5.6 s, shifts weight about every 9 s and roars every 27 s. A hit-react clip with root motion slid it 27 m. The owner called it "jagged" and asked that it "move and live and breath and act like a real fucking titan", 3 or more times.
88
+ - **Applies when:** Bosses and large hero enemies.
89
+ - **Verify:** Watch 60 s of the boss on the title, in play and asleep: it moves the whole time, and its foot positions stay fixed while planted.
90
+
91
+ ### Deaths match the weapon
92
+ - **Invariant:** Kill reactions follow the weapon fantasy: energy weapons drop bodies where they stand, shotguns and explosives throw them, and every death has weight.
93
+ - **Technique:** Pick a directional death clip from the hit, then hand over to physics with an impulse set per weapon class. Corpse settling, caps and deadlines are in `opengame-world-physics`.
94
+ - **Reference configuration:** OC's energy kills rise under 0.15 m and travel under 0.6 m; a point-blank shotgun throws 5 to 6 m/s with a sideways part; a pistol 1.7 m/s; explosives 4 to 5 m/s out and 3.5 to 4.5 up; directional death clips of 0.16 to 0.42 s come first. The owner: "ray guns hsouldnt make zombies fly", after agents had logged a "Ray Gun backflip" as a win.
95
+ - **Applies when:** Shooters and action games with physics deaths.
96
+ - **Verify:** Kill a row of enemies with each weapon class and measure rise and travel per body against the table.
97
+
98
+ ### A horde reads as many individuals and keeps off the lens
99
+ - **Invariant:** A crowd of one enemy type looks like individuals, every type reads at fighting range, and no enemy fills the first-person view.
100
+ - **Technique:** Offset animation phase, playback rate, scale and heading per enemy. Keep enemy flesh lighter than the floor. Stop enemies short of the camera and push them back when they crowd it, fade anything that comes very close to the lens, and hide eye glows up close. Update far animations less often.
101
+ - **Reference configuration:** OC: phase offsets 0 to 1.6 s, rate within 15%, scale 0.92 to 1.08; each type readable at 15 m; 25 to 35 enemies in frame for a horde to read; full animation under 25 m, every second frame under 45 m. Enemies stop at 1.05 m and are pushed back to 0.6 m; anything within 0.65 m of the lens dithers to 30%; eye glows hide within 3 m; a 4 m keep-out ring surrounds machines. The owner said they looked "lifeless, like robots" before.
102
+ - **Applies when:** Games with crowds of enemies and a first-person or close camera.
103
+ - **Verify:** Let 24 enemies surround a still player and capture the frame: no two neighbours share a pose, and no enemy covers more than the agreed share of the view.
@@ -0,0 +1,134 @@
1
+ # Enemies in three.js
2
+
3
+ three.js has no navigation of its own. The usual choice is recast-navigation-js, a
4
+ WebAssembly build of Recast and Detour, the navigation library that Unreal and Godot
5
+ build on. Its packages are `recast-navigation` (core, generators) and
6
+ `@recast-navigation/three` (helpers that read three.js meshes and draw debug views).
7
+ Check the names below against the version you install; the API has moved between
8
+ releases.
9
+
10
+ ## Building the navmesh
11
+
12
+ ```js
13
+ import { init, NavMeshQuery, Crowd } from 'recast-navigation'
14
+ import { threeToSoloNavMesh, threeToTileCache, NavMeshHelper } from '@recast-navigation/three'
15
+
16
+ await init()
17
+ const { success, navMesh } = threeToSoloNavMesh(walkableMeshes, {
18
+ cs: 0.2, ch: 0.2, // cell size and cell height in metres
19
+ walkableRadius: 2, // in cells: 2 x cs = 0.4 m
20
+ walkableHeight: 9, // in cells of ch: 1.8 m
21
+ walkableClimb: 2, // in cells of ch: 0.4 m, the body's step
22
+ walkableSlopeAngle: 40,
23
+ })
24
+ scene.add(new NavMeshHelper(navMesh))
25
+ ```
26
+
27
+ - Build from the collision meshes, not the render meshes. Decorative clutter with a
28
+ dense mesh blocks small steps; give it a simple proxy or leave it out.
29
+ - Recast counts radius, height and climb in cells. Convert from the world spec's metres
30
+ so `walkableClimb * ch` equals the controller's step height
31
+ (`opengame-world-physics`). The values in the block above are an example, not OC's.
32
+ - For a level that changes during play, use `threeToTileCache` (or `generateTileCache`)
33
+ with a small `tileSize`, so one tile rebuilds quickly.
34
+
35
+ ## Off-mesh connections: jumps, drops and climbs
36
+
37
+ Pass links as `offMeshConnections` when generating a solo or tiled navmesh:
38
+
39
+ ```js
40
+ offMeshConnections: [
41
+ { startPosition: takeoff, endPosition: landing, radius: 0.5,
42
+ bidirectional: false, area: JUMP_AREA, flags: 1, userId: linkId },
43
+ ]
44
+ ```
45
+
46
+ With a tile cache, the same objects go through `navMeshCreateParams.setOffMeshConnections`
47
+ in the tile cache's mesh process. Generate the list yourself from the agent's jump
48
+ height, jump distance and safe drop height:
49
+
50
+ 1. Find ledge edges in the collision geometry (a walkable polygon edge with a drop or a
51
+ gap beyond it).
52
+ 2. For each edge sample, cast down and across within the agent's reach to find a
53
+ landing that has room for the body.
54
+ 3. Check the arc with a capsule sweep against the colliders.
55
+ 4. Publish one connection per accepted pair, with an area id that tells the agent which
56
+ motion to play. Use `bidirectional: true` only when the climb back is also possible.
57
+ 5. Regenerate the links that touch a player-built piece when it is placed, raised or
58
+ destroyed.
59
+
60
+ When an agent reaches a connection, Detour hands it the start and end; play the jump or
61
+ drop motion on your own controller, then let the crowd resume.
62
+
63
+ ## Crowds
64
+
65
+ ```js
66
+ const crowd = new Crowd(navMesh, { maxAgents: 64, maxAgentRadius: 0.6 })
67
+ const agent = crowd.addAgent(spawn, { radius: 0.4, height: 1.8, maxSpeed: 3.4,
68
+ maxAcceleration: 20 })
69
+ agent.requestMoveTarget(playerPosition)
70
+ crowd.update(dt) // once per fixed step
71
+ mesh.position.copy(agent.position())
72
+ ```
73
+
74
+ - The crowd does local avoidance and path following for every agent at once, which is
75
+ far cheaper than one path query per enemy per frame.
76
+ - Request a new move target only when the player has moved a meaningful distance, and at
77
+ most a few agents per frame; the rest keep their last target.
78
+ - `agent.teleport(position)` is the out-of-sight respawn step. Count every call in your
79
+ teammate metrics so teleports cannot pass as navigation.
80
+
81
+ ## Path requests across frames
82
+
83
+ For agents outside the crowd (a boss, a scripted ally), queue `NavMeshQuery.computePath`
84
+ calls and run a fixed number per frame:
85
+
86
+ ```js
87
+ const query = new NavMeshQuery(navMesh)
88
+ const queue = []
89
+ function requestPath(agentId, from, to) { queue.push({ agentId, from, to }) }
90
+ function pumpPaths(maxPerFrame) {
91
+ for (let i = 0; i < maxPerFrame && queue.length; i++) {
92
+ const { agentId, from, to } = queue.shift()
93
+ const { success, path } = query.computePath(from, to)
94
+ deliverPath(agentId, success ? path : null)
95
+ }
96
+ }
97
+ ```
98
+
99
+ Agents heading to the same place (the player) can share one path to a nearby point and
100
+ let the crowd spread them. Back off after a failed request instead of asking again next
101
+ frame.
102
+
103
+ ## Obstacles and rebuilds within a frame budget
104
+
105
+ ```js
106
+ const { tileCache } = threeToTileCache(walkableMeshes, { tileSize: 16 /* , ... */ })
107
+ const { obstacle } = tileCache.addBoxObstacle(center, halfExtents, angle)
108
+ // every frame:
109
+ const { upToDate } = tileCache.update(navMesh)
110
+ ```
111
+
112
+ - `tileCache.update` works through queued obstacle changes over successive calls and
113
+ reports `upToDate` when it has finished. Call it once per frame and time it; if one
114
+ tile takes longer than the frame budget, make the tiles smaller.
115
+ - Doors, gates and barricades are obstacles or area flags that the query filter
116
+ excludes, so opening one does not regenerate geometry.
117
+ - Do not add obstacles for short boss effects; treat them as damage areas the agents
118
+ avoid by steering.
119
+
120
+ ## Debug views
121
+
122
+ `NavMeshHelper`, `OffMeshConnectionsHelper`, `TileCacheHelper` and `CrowdHelper` from
123
+ `@recast-navigation/three` draw the navmesh, links, tile cache obstacles and agents. For
124
+ a capture, draw links as arcs (`Line2`) coloured by area id, so a missing link on a
125
+ player build is visible.
126
+
127
+ ## Other engines
128
+
129
+ - Godot: `NavigationRegion3D`, `NavigationAgent3D` and `NavigationLink3D` for jumps;
130
+ `NavigationMesh.agent_max_climb` is the step; bake on a thread with
131
+ `bake_navigation_mesh(true)`.
132
+ - Unity: the AI Navigation package's `NavMeshSurface`, `NavMeshLink` for jumps and
133
+ `NavMeshObstacle` with carving for doors; the agent type's Step Height is the step;
134
+ `NavMeshSurface.UpdateNavMesh` rebuilds asynchronously.
@@ -0,0 +1,143 @@
1
+ ---
2
+ name: opengame-front-end
3
+ description: Build a browser game's title, menus, first run, loading, settings, results and HUD. Covers menus that are live scenes with sound, a short first run, saves that survive, an honest loading bar, clicks that always land, a HUD from one unit, an FPS counter, dialogs from the game's own kit and a share card from a real frame. Use when the person says the menu looks cheap, the loading bar freezes, clicks do nothing, settings reset, or asks for a title, menu, HUD or share image.
4
+ metadata:
5
+ version: "1.0.1"
6
+ ---
7
+
8
+ # The front end and the HUD
9
+
10
+ The first thing a stranger sees is the title and the menu, and a button on black
11
+ answers them before the game can. The front end is part of the game, in the same world,
12
+ type and light, and it must never be the thing that hangs.
13
+
14
+ Rules carry five tags; `opengame-quality-bar` explains them and the game codes. OC's
15
+ owner asked for a console-grade menu 4 or more times and for an honest loading bar 3
16
+ times; those rules come first.
17
+
18
+ ## Rules
19
+
20
+ ### Every menu is a live scene with its own sound
21
+ - **Invariant:** Every menu and the loading screen show the game's world in motion with that scene's sound under it, answer focus with sound, and never look like a web page or show a pixelated first frame.
22
+ - **Technique:** A looping in-engine film per screen, or a rendered clip of real play, with its ambience routed through the menu mix. Hover, focus and click sounds come from one kit. Screens change by cut, push or mask instead of opacity crossfades. Hold the poster until the first frame is at full resolution. On phones the poster replaces the loading film. Test the film's codec in a real browser, because automated browsers often cannot decode it.
23
+ - **Reference configuration:** OC's owner: "It should not look like a browser menu screen ... background cinematics, the sound of the cinematics in the background, hover effects". OC's menu film is 5 shots on a 36 s loop (zombies climbing, the squad on patrol, lightning on the beat). The loading film was 22.6 s of 1080p30 H.264 at 10.2 MB, later 19 s at 8.7 MB, muted with a poster, and skipped on phones. Motion durations 120, 160, 220 and 280 ms. Playwright's Chromium could not decode H.264, so the loading film never played in OC's own captures.
24
+ - **Applies when:** Every game with menus.
25
+ - **Verify:** Load cold in a real browser at native resolution: the first frame is sharp, the film moves, its sound plays after the first press, and every focus change makes a sound.
26
+
27
+ ### The title is a scene
28
+ - **Invariant:** The title screen shows the game's world, with the game's name as crisp live text and a clear way in.
29
+ - **Technique:** Key art or a looping clip of the world under live DOM type, a scrim only where text needs it, and a semantic Play control focused on load. Keep the promotional wordmark separate from the accessible title. Never bake controls or labels into footage.
30
+ - **Reference configuration:** AW fades its key art in over 620 ms with an 8 s scale from 1.045 to 1. Our originals' rule: no system display face (source a face that matches the world, or draw the title from the game's own bitmap font), no eyebrow above a heading, no gradient text, no emoji as icons.
31
+ - **Applies when:** Every game.
32
+ - **Verify:** Capture the title cold at laptop and 1080p sizes; inspect the computed font family; Tab reaches Play first and Enter starts the game.
33
+
34
+ ### Poster first, then film
35
+ - **Invariant:** The menu is usable the moment it appears, a background film never blocks a control, and motion respects the player's preference.
36
+ - **Technique:** Show the still poster immediately; start the film muted so autoplay is allowed, unmute through the menu mix after a real gesture, crossfade its loop, pause it when the tab is hidden or the menu closes, and keep one shared background element across menus. Reduced motion shows the poster with no autoplay. A failed film falls back to the poster.
37
+ - **Reference configuration:** AW gates its menu films on reduced motion and plays their sound at 0.07. ST starts menu audio at a 30% menu mix and never above it. Our originals cap menu film audio at 30% of media gain.
38
+ - **Applies when:** Games with a menu film or animated background.
39
+ - **Verify:** Load with reduced motion on: no video plays. Block the video file: the menu still works. Hide the tab: the film pauses.
40
+
41
+ ### A short first run from the title to play
42
+ - **Invariant:** A first-time player reaches play through a short fixed flow with one obvious way forward on each screen, is never stopped by a form, and cannot lose progress by accident.
43
+ - **Technique:** A few fixed screens from the title to play, each with one prominent forward button. Selecting an item previews it and only the button advances; Enter acts on release, so one press never skips a screen. A default name instead of a name prompt: on OpenGame, the signed-in player's handle, filled as `opengame-sdk` shows, and the game's own default name otherwise. Quit, Restart and Reset ask for a second press. A first-spawn hint with the goal and the controls for the device in use, shown once per profile and closing itself. Labels a player understands.
44
+ - **Reference configuration:** OC's flow is title, character, loadout and deploy. Its default name is "Player"; the first-spawn hint closes after 12 s, with keyboard and touch variants; "Early Access", not "Early build 0.1". The owner: "I'm trying to hit Enter to apply and it keeps moving stuff forward"; the character to loadout flow was fixed at R86.
45
+ - **Applies when:** Every game with menus before play.
46
+ - **Verify:** In a fresh profile, a stranger reaches play with one Enter or one click per screen. Press Quit once and see a confirm. Die and restart: the hint does not show again.
47
+
48
+ ### Saves survive a reload, and the player is told when they cannot
49
+ - **Invariant:** Every setting and profile value the player changes survives a reload, an explicit choice is never changed without telling the player, and the player is told when the browser blocks storage.
50
+ - **Technique:** One settings store written on every change, zero and false included, and read once at boot. A version field with a migration when a default changes, treating old saves as explicit choices. Test storage at boot and show a notice when it throws or is missing. An automatic quality change steps at most once, never in menus, never below the floor the owner set, and says so on screen.
51
+ - **Reference configuration:** OC saved only 3 of 21 settings until R104-R107, and profile persistence failed at r79 and r83 before passing at r84. OC's quality rule: one step from Ultra to High after 8 s at a GPU median over 17.5 ms, with a banner, never below High and never in menus. The owner: "Let's make Ultra the base... fall back to High, but not below."
52
+ - **Applies when:** Every game with settings or a profile.
53
+ - **Verify:** Set every option to a non-default value, including off and zero, reload, and compare. Block site storage in the browser and load: the notice shows.
54
+
55
+ ### The loading bar is honest and always moving
56
+ - **Invariant:** The loading bar follows real work, rises in small steps, never goes backwards, never holds still long enough to look frozen, and reads full only when the next screen responds.
57
+ - **Technique:** Weight progress by bytes, not file counts. Give each blocking stage (shader and pipeline compiles, environment maps, decoding) its own weight, and split it into pieces that each report. Show the bar only after a short delay, so a fast load shows none. The displayed value steps toward the real value one step at a time. Test on a throttled connection; a fast local boot hides every stall. In three.js, `LoadingManager.onProgress` counts items, which is the same trap; add byte weights and manual weights for `compileAsync` and PMREM. Load budgets are in `opengame-loading`.
58
+ - **Reference configuration:** OC's bar went to 60%, froze, then jumped to 100% ("can we have it be progressive by 1%"); later it stuck at 97% for 20 s and reloaded (R93), and real iPhones stalled at 97% for 1-3 min until R185. The fix climbs 1% at a time, never holds a number for more than about 0.75 s (0.68-0.73 s measured), has no stall over 300 ms in the timing strip, and appears only after 0.6 s. A shader warm-up curtain had added 2.5 s of blank screen. Test profiles: an 8 s load and a 25 Mbps connection.
59
+ - **Applies when:** Every game with a loading screen.
60
+ - **Verify:** Record the bar on a throttled connection and log each displayed value with its time: no backward step, no hold past the limit, and the title responds when the bar reads full.
61
+
62
+ ### A boot veil with a deadline
63
+ - **Invariant:** The loading cover lifts when the game is ready, and lifts anyway at a deadline with the reason recorded, so it can never hang.
64
+ - **Technique:** Lift on named readiness conditions plus a short measured quiet (no long tasks), bounded by a hard deadline that logs what was still outstanding. Show real progress for required assets, never an invented percentage.
65
+ - **Reference configuration:** AW's boot veil waits for its readiness steps plus 500 ms of measured quiet, and lifts at a 9 s deadline regardless, logging what it was waiting on. The OpenGame landing page once shipped a gate that waited for ever on a GPU that never answered.
66
+ - **Applies when:** Every game with loading.
67
+ - **Verify:** Throttle the network and block one required asset: the veil lifts at the deadline and the screen offers a retry.
68
+
69
+ ### Loading that cannot hang, failures you can act on
70
+ - **Invariant:** Every wait has a deadline and a fallback, and a failure says what happened and offers a way forward.
71
+ - **Technique:** Every fetch, decode and scene preparation has a timeout. Fence stale async loads so a rapid menu change cannot land an old scene. Play starts when the scene and controls are ready, not when a decorative clip ends.
72
+ - **Reference configuration:** ST's rule: loading is complete only when the next advertised action responds.
73
+ - **Applies when:** Every game.
74
+ - **Verify:** Kill the network mid-load and press every button on the screen that appears.
75
+
76
+ ### Every click lands, wherever the button is released
77
+ - **Invariant:** Every press and release reaches the game, whether the pointer is released over the canvas, over a page overlay or outside the window, so no button stays held and no menu click is lost.
78
+ - **Technique:** Listen for release on the window, not the canvas, or capture the pointer on press with `setPointerCapture`. Clear held buttons on `pointercancel`, `touchcancel`, blur and visibility change, and set `touch-action: none` on the game surface. Prove it with clicks the running game receives, not with a stand-in page.
79
+ - **Reference configuration:** OC's owner: "sometimes on the menu screens / pause I can hover over buttons but clicking them does nothing, randomly". The web runtime heard mouseup only on the canvas, so a press released over a page overlay left the button held, and the menu's wait-for-release guard then ignored every later click: 60 of 60 clicks after an overlay release were missed. Forwarding the release took 12 lines and brought it to 0 of 60 (R167). That proof came from a stand-in test page with no in-game clicks, which is the gap to close.
80
+ - **Applies when:** Every browser game with DOM over the canvas or menus drawn in the canvas.
81
+ - **Verify:** In the running game, press on the canvas, drag onto an overlay or out of the window, release, then click a menu button. It responds on 20 of 20 tries.
82
+
83
+ ### Say where, not what the folder is called
84
+ - **Invariant:** Every out-of-match surface names a place the way a player is sent there, and names it the same way everywhere.
85
+ - **Technique:** One table of places with their names and when they are, read by the menu, the loading screen and the results.
86
+ - **Reference configuration:** AW's menu module: a map id is a folder name, "BERLIN, APRIL 1945" is where a player is being sent. The module imports nothing, so the menu dresses itself before the engine loads.
87
+ - **Applies when:** Games with levels, maps or places.
88
+ - **Verify:** Grep the front end for internal ids reaching visible text.
89
+
90
+ ### Pause, settings, results and retry belong to the game
91
+ - **Invariant:** Every screen outside play shares the game's visual language, settings apply live, and retry resets the game without reloading the page.
92
+ - **Technique:** One set of styles and one set of transition durations for every screen; settings write through to the running game; retry resets actors, input, score, camera, effects and audio. Modal screens contain focus, make the background `inert`, and restore focus on close.
93
+ - **Reference configuration:** DK's motion durations are 110, 190, 320, 520 and 780 ms on `cubic-bezier(.16, 1, .3, 1)`, buttons translating in 120 ms. ST walks title, Play, game over, retry, pause, settings, resume and menu on every checkpoint.
94
+ - **Applies when:** Every game.
95
+ - **Verify:** Walk that whole loop by keyboard alone, twice, and check that nothing duplicated (loops, listeners, decoders) on the second pass.
96
+
97
+ ### A HUD scaled from one unit
98
+ - **Invariant:** The HUD keeps its proportions at every screen size, numbers do not jitter as they change, and the centre of the screen stays clear.
99
+ - **Technique:** Size every HUD element from one CSS unit derived from the viewport; tabular numerals on everything that counts; information on a safe inset at the edges; readability from shadow rather than panels; icons drawn per element at one stroke weight.
100
+ - **Reference configuration:** AW: `--u: min(0.0926vh, 0.0521vw)`, one 1080p pixel. SR: an edge inset of `clamp(14px, 2.4vw, 34px)`. Readability from a hard 1u shadow plus a soft 7u one, and bone (#ece7d8) instead of pure white. OC's sweep: 1280x720, 1920x1080, 2560x1440, 1024x768, 16:10, iPad and 844x390, where fixed-width panels clipped at 16:10.
101
+ - **Applies when:** Every game with a HUD.
102
+ - **Verify:** Capture the HUD at every desktop viewport; the layout is the same picture at each size, and a counting number does not shift its neighbours.
103
+
104
+ ### A hitmarker grammar
105
+ - **Invariant:** The player can tell a hit, a critical hit, a kill and incoming damage apart at a glance, and their direction.
106
+ - **Technique:** Distinct marks with distinct timing for hit, critical and kill, merged damage numbers per target, and a directional arc toward an attacker that decays.
107
+ - **Reference configuration:** MC and AW: four ticks; a hit 130 to 180 ms scaling 1.34 to 1; a headshot gold, 165 ms; a kill red and thicker, 240 to 340 ms. Hits on one target within 180 ms merge into one number rising 34 px over 900 ms. Incoming damage: a conic arc, attack 80 ms, hold 180 ms, decay 1350 ms.
108
+ - **Applies when:** Combat games.
109
+ - **Verify:** Frame-step a recording of a hit, a headshot and a kill; each mark is distinguishable on a single frame.
110
+
111
+ ### Flashes are limited at the source
112
+ - **Invariant:** No effect, in the canvas or in the DOM over it, changes the screen's brightness fast enough to be a photosensitive flash, rising or falling.
113
+ - **Technique:** Limit the frame-to-frame change in composited luminance for full-screen effects, in both directions, by measuring every large overlay rather than a list of known ones. Injury overlays keep the centre clear.
114
+ - **Reference configuration:** AW limits each overlay's frame-to-frame luminance step to 0.045, under half of WCAG 2.3.1's 0.10 flash pair, after two players reported flashing violent enough to fear a seizure.
115
+ - **Applies when:** Every game with flashes, damage overlays or explosions.
116
+ - **Verify:** Record the worst flash in the game and measure per-frame mean luminance; no step exceeds the limit. See `opengame-accessibility`.
117
+
118
+ ### The FPS counter informs and never alarms
119
+ - **Invariant:** If the game shows a frame-rate counter, it is a persisted setting, it shows in play and not in menus, it never covers health or ammo, and its colours report without alarming.
120
+ - **Technique:** A settings toggle that persists. Green at or above the target, a soft yellow below it, and no red. Track frame-time spikes and the slowest frames beside the average, since an average hides stutter. Place it clear of the HUD's information and paint it out of marketing captures. Ask the owner for the default once and write it down.
121
+ - **Reference configuration:** OC: green at 60 FPS and above, soft yellow below, never red (R160, an owner ask). Its floor is 60 and its aim 120, with no frame over twice the usual time after warm-up and 1% lows at or above 60 at 1280 x 720. The default changed 3 times, from on, to gameplay only, to off (R174, R178, R179), and on phones the counter moved off the health display.
122
+ - **Applies when:** Games that show a frame-rate counter.
123
+ - **Verify:** Switch it on, reload: it is still on, and only in play. Load the machine until the rate drops below target: the counter turns yellow, not red.
124
+
125
+ ### New interface is built from the game's own kit
126
+ - **Invariant:** Every dialog, badge, toast and card added later looks and sounds like the game's own menus.
127
+ - **Technique:** Build new UI from the menus' components, type, colours, hover and click sounds; flat, with no gradients, tints or shimmer; the same focus loop as other dialogs (Escape, outside tap, Tab, Enter); a form that closes confirms with the game's own toast.
128
+ - **Reference configuration:** OC's owner on a brand badge: "i hate the gradient... no orange tint. and make it look as sick as our menu components... same hover sfx and click sfx". The badge, the feedback dialog and its toast were rebuilt from the menu kit.
129
+ - **Applies when:** Every game that adds web UI around or over the canvas.
130
+ - **Verify:** Capture the new dialog beside a menu in one frame: same type, colours and corners. Hover and click it with sound on.
131
+
132
+ ### The share card is a frame of the real game
133
+ - **Invariant:** The link preview, share card and icons come from the game as it plays, carry the game's mark and address, and show no counters, debug text or placeholders.
134
+ - **Technique:** Capture a hero frame in game through the capture path in `opengame-capture`, add the logo, a call to action and the address, and paint out counters and dev overlays. Ship a wide card, a square card and icons drawn at their real sizes, then check the tags on the live URL.
135
+ - **Reference configuration:** OC: 1200x630 under 1 MB from an in-game shot with logo, call to action and URL, the FPS counter painted out; a 1200x1200 square; a favicon hand-pixelled at 16 px, an apple-touch icon and a theme colour. A later OC note set the card as a JPEG under 300 KB.
136
+ - **Applies when:** Every game with a public URL.
137
+ - **Verify:** Paste the live URL into a link-preview checker and a chat app: the card is a sharp real frame with no counter.
138
+
139
+ ## Further reading
140
+
141
+ Interface sound, controls legends and the menu audio path:
142
+ [references/menus.md](references/menus.md). First-run details, the share card and
143
+ analytics for a game served from its own domain: [references/launch.md](references/launch.md).
@@ -0,0 +1,50 @@
1
+ # First run, share card and analytics
2
+
3
+ ## The first run, screen by screen
4
+
5
+ OC's first run after the launch fixes, as a checklist to walk in a fresh profile:
6
+
7
+ - Title over key art, with a press-to-start that also unlocks audio (see `opengame-audio`).
8
+ - Character, with one forward button. The default name is "Player", so no name screen stands
9
+ between a new player and the match.
10
+ - Loadout, where picking a gun equips it and Deploy starts the match.
11
+ - The arena, with a first-spawn hint naming the goal and the controls for the device in
12
+ use (keyboard or touch), shown once per profile and closing after 12 s.
13
+ - Quit, Restart and Reset ask for a second press.
14
+ - Saves survive a reload, and a notice appears when site storage is blocked.
15
+ - Developer URL switches are off in production. OC kept a dev key only as a SHA-256 hash.
16
+ - The build label says "Early Access", not "Early build 0.1".
17
+
18
+ Check it with real key presses from the title, then reload and check the profile, because
19
+ OC's test shortcuts hid real save and dev-gate bugs.
20
+
21
+ ## The share card
22
+
23
+ - Wide 1200x630 and square 1200x1200, both from a real in-game frame captured at final
24
+ quality, with the logo, a call to action and the URL. OC kept the wide card under 1 MB,
25
+ and a later note asked for a JPEG under 300 KB.
26
+ - Paint out the FPS counter and any dev overlay.
27
+ - Favicon hand-pixelled at 16 px, an apple-touch icon and a theme colour.
28
+ - Full Open Graph and Twitter card tags, checked on the live URL after deploy.
29
+
30
+ ## Analytics
31
+
32
+ On OpenGame, send gameplay events with `og.track` from `opengame-sdk`. The page already
33
+ batches them, caps their size and rate, limits property keys, and measures plays and
34
+ sessions itself.
35
+
36
+ A game served from its own domain that runs its own analytics follows OC's pattern:
37
+
38
+ - Events go to a same-origin proxy (OC's was `/api/analytics`) that holds the analytics
39
+ token on the server. The browser never sees it.
40
+ - An allowlist of event names and fields, an origin check, a size cap and a rate limit on
41
+ the proxy. OC sent 19 events: the funnel, a run summary, settings changes and client
42
+ errors.
43
+ - Do Not Track and Global Privacy Control are honoured before anything is sent.
44
+ - No IP addresses and no person profiles are stored.
45
+ - The run-end event answers design questions: outcome (a crash is reported with `navigator.sendBeacon`
46
+ on `pagehide`), active time excluding pause, kills, headshots, score, phase at the end, device
47
+ class, quality tier, FPS and build. Test it against mocks: one of OC's cleared-round
48
+ counts fell from 2 to 0 with no error.
49
+ - A public leaderboard validates scores on the server, with run ids the server issues and
50
+ plausibility checks, and never ranks dev runs.