@opengamehq/skills 1.3.0 → 1.5.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 (385) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/README.md +12 -4
  3. package/dist/.claude-plugin/marketplace.json +26 -0
  4. package/dist/skills/manifest.json +1409 -145
  5. package/dist/skills/opengame-accessibility/CHANGELOG.md +4 -0
  6. package/dist/skills/opengame-accessibility/SKILL.md +48 -32
  7. package/dist/skills/opengame-all-in-one/CHANGELOG.md +21 -0
  8. package/dist/skills/opengame-all-in-one/SKILL.md +195 -0
  9. package/dist/skills/opengame-all-in-one/references/opengame-accessibility/README.md +102 -0
  10. package/dist/skills/opengame-all-in-one/references/opengame-api/README.md +107 -0
  11. package/dist/skills/opengame-all-in-one/references/opengame-assets/README.md +168 -0
  12. package/dist/skills/opengame-all-in-one/references/opengame-assets/references/pipeline.md +164 -0
  13. package/dist/skills/opengame-all-in-one/references/opengame-audio/README.md +238 -0
  14. package/dist/skills/opengame-all-in-one/references/opengame-audio/helpers/audio-chain.js +325 -0
  15. package/dist/skills/opengame-all-in-one/references/opengame-audio/references/mix-notes.md +125 -0
  16. package/dist/skills/opengame-all-in-one/references/opengame-audio/references/qa-without-ears.md +177 -0
  17. package/dist/skills/opengame-all-in-one/references/opengame-capture/README.md +128 -0
  18. package/dist/skills/opengame-all-in-one/references/opengame-capture/references/pipeline.md +114 -0
  19. package/dist/skills/opengame-all-in-one/references/opengame-capture/references/threejs.md +161 -0
  20. package/dist/skills/opengame-all-in-one/references/opengame-characters/README.md +180 -0
  21. package/dist/skills/opengame-all-in-one/references/opengame-characters/references/first-person-body.md +108 -0
  22. package/dist/skills/opengame-all-in-one/references/opengame-characters/references/integration.md +144 -0
  23. package/dist/skills/opengame-all-in-one/references/opengame-characters/references/player-og.md +160 -0
  24. package/dist/skills/opengame-all-in-one/references/opengame-cli/README.md +189 -0
  25. package/dist/skills/opengame-all-in-one/references/opengame-deploy/README.md +223 -0
  26. package/dist/skills/opengame-all-in-one/references/opengame-deploy/references/json-events.md +63 -0
  27. package/dist/skills/opengame-all-in-one/references/opengame-deploy/references/manifest.md +89 -0
  28. package/dist/skills/opengame-all-in-one/references/opengame-deploy/references/packaging.md +119 -0
  29. package/dist/skills/opengame-all-in-one/references/opengame-depth/README.md +154 -0
  30. package/dist/skills/opengame-all-in-one/references/opengame-enemies/README.md +155 -0
  31. package/dist/skills/opengame-all-in-one/references/opengame-enemies/references/pacing-and-bots.md +108 -0
  32. package/dist/skills/opengame-all-in-one/references/opengame-enemies/references/threejs.md +193 -0
  33. package/dist/skills/opengame-all-in-one/references/opengame-front-end/README.md +185 -0
  34. package/dist/skills/opengame-all-in-one/references/opengame-front-end/references/launch.md +50 -0
  35. package/dist/skills/opengame-all-in-one/references/opengame-front-end/references/menus.md +81 -0
  36. package/dist/skills/opengame-all-in-one/references/opengame-game-feel/README.md +181 -0
  37. package/dist/skills/opengame-all-in-one/references/opengame-game-feel/helpers/spring.js +146 -0
  38. package/dist/skills/opengame-all-in-one/references/opengame-game-feel/references/feel-numbers.md +142 -0
  39. package/dist/skills/opengame-all-in-one/references/opengame-game-feel/references/killcam.md +88 -0
  40. package/dist/skills/opengame-all-in-one/references/opengame-jam/README.md +114 -0
  41. package/dist/skills/opengame-all-in-one/references/opengame-lighting/README.md +141 -0
  42. package/dist/skills/opengame-all-in-one/references/opengame-lighting/helpers/light-pool.js +185 -0
  43. package/dist/skills/opengame-all-in-one/references/opengame-loading/README.md +135 -0
  44. package/dist/skills/opengame-all-in-one/references/opengame-loading/helpers/loading-count.mjs +115 -0
  45. package/dist/skills/opengame-all-in-one/references/opengame-loading/references/threejs.md +141 -0
  46. package/dist/skills/opengame-all-in-one/references/opengame-look/README.md +181 -0
  47. package/dist/skills/opengame-all-in-one/references/opengame-look/references/matching-a-reference.md +73 -0
  48. package/dist/skills/opengame-all-in-one/references/opengame-look/references/painterly.md +69 -0
  49. package/dist/skills/opengame-all-in-one/references/opengame-look/references/post-and-lens.md +73 -0
  50. package/dist/skills/opengame-all-in-one/references/opengame-maps/README.md +74 -0
  51. package/dist/skills/opengame-all-in-one/references/opengame-maps/references/map-spec.md +77 -0
  52. package/dist/skills/opengame-all-in-one/references/opengame-mobile/README.md +86 -0
  53. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/README.md +183 -0
  54. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/briefs.md +293 -0
  55. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/day-one-questions.md +46 -0
  56. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/edge-cases.md +27 -0
  57. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/filmable.md +244 -0
  58. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/finishing.md +126 -0
  59. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/measure.md +282 -0
  60. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-capture.md +151 -0
  61. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-gates.md +84 -0
  62. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-genres.md +198 -0
  63. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-grammar.md +320 -0
  64. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/montage-ops.md +127 -0
  65. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/og-snipers-record.md +110 -0
  66. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/owner-eye.md +214 -0
  67. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/reference-study.md +293 -0
  68. package/dist/skills/opengame-all-in-one/references/opengame-montage-make/references/song.md +64 -0
  69. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/README.md +193 -0
  70. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/briefs.md +293 -0
  71. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/day-one-questions.md +46 -0
  72. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/filmable.md +244 -0
  73. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/measure.md +282 -0
  74. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-capture.md +151 -0
  75. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-gates.md +84 -0
  76. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-genres.md +198 -0
  77. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-grammar.md +320 -0
  78. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/montage-ops.md +127 -0
  79. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/og-snipers-record.md +110 -0
  80. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/owner-eye.md +214 -0
  81. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/reference-study.md +293 -0
  82. package/dist/skills/opengame-all-in-one/references/opengame-montage-plan/references/song.md +64 -0
  83. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/README.md +174 -0
  84. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/briefs.md +293 -0
  85. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/day-one-questions.md +46 -0
  86. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/filmable.md +244 -0
  87. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/finishing.md +126 -0
  88. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/measure.md +282 -0
  89. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-capture.md +151 -0
  90. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-gates.md +84 -0
  91. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-genres.md +198 -0
  92. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-grammar.md +320 -0
  93. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/montage-ops.md +127 -0
  94. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/og-snipers-record.md +110 -0
  95. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/owner-eye.md +214 -0
  96. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/reference-study.md +293 -0
  97. package/dist/skills/opengame-all-in-one/references/opengame-montage-review-and-improve/references/song.md +64 -0
  98. package/dist/skills/opengame-all-in-one/references/opengame-multiplayer/README.md +139 -0
  99. package/dist/skills/opengame-all-in-one/references/opengame-multiplayer/references/bot-lobbies.md +71 -0
  100. package/dist/skills/opengame-all-in-one/references/opengame-multiplayer/references/netcode.md +165 -0
  101. package/dist/skills/opengame-all-in-one/references/opengame-performance/README.md +177 -0
  102. package/dist/skills/opengame-all-in-one/references/opengame-performance/helpers/landing-pacer.mjs +86 -0
  103. package/dist/skills/opengame-all-in-one/references/opengame-performance/references/measuring.md +123 -0
  104. package/dist/skills/opengame-all-in-one/references/opengame-performance/references/webgpu.md +86 -0
  105. package/dist/skills/opengame-all-in-one/references/opengame-production/README.md +192 -0
  106. package/dist/skills/opengame-all-in-one/references/opengame-production/references/team.md +107 -0
  107. package/dist/skills/opengame-all-in-one/references/opengame-production/references/templates.md +153 -0
  108. package/dist/skills/opengame-all-in-one/references/opengame-quality-bar/README.md +170 -0
  109. package/dist/skills/opengame-all-in-one/references/opengame-quality-bar/references/cheap-tells.md +43 -0
  110. package/dist/skills/opengame-all-in-one/references/opengame-quality-bar/references/judges.md +95 -0
  111. package/dist/skills/opengame-all-in-one/references/opengame-quality-bar/references/review-prompt.md +32 -0
  112. package/dist/skills/opengame-all-in-one/references/opengame-rhythm/README.md +134 -0
  113. package/dist/skills/opengame-all-in-one/references/opengame-rhythm/references/charting.md +109 -0
  114. package/dist/skills/opengame-all-in-one/references/opengame-rhythm/references/timing.md +92 -0
  115. package/dist/skills/opengame-all-in-one/references/opengame-router/README.md +54 -0
  116. package/dist/skills/opengame-all-in-one/references/opengame-router/references/process.md +38 -0
  117. package/dist/skills/opengame-all-in-one/references/opengame-scene-audit/README.md +136 -0
  118. package/dist/skills/opengame-all-in-one/references/opengame-scene-audit/helpers/scene-audit.js +677 -0
  119. package/dist/skills/opengame-all-in-one/references/opengame-sdk/README.md +283 -0
  120. package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/engines.md +93 -0
  121. package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/frame.md +107 -0
  122. package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/identity.md +111 -0
  123. package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/leaderboards.md +115 -0
  124. package/dist/skills/opengame-all-in-one/references/opengame-sdk/references/radio.md +71 -0
  125. package/dist/skills/opengame-all-in-one/references/opengame-stability/README.md +112 -0
  126. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/README.md +160 -0
  127. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/archetypes.md +113 -0
  128. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/briefs.md +273 -0
  129. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/core.md +129 -0
  130. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/craft.md +299 -0
  131. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/edge-cases.md +27 -0
  132. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/filmable.md +244 -0
  133. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/finishing.md +126 -0
  134. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/gates.md +184 -0
  135. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/measure.md +282 -0
  136. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/music.md +148 -0
  137. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/og-clash-record.md +133 -0
  138. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/ops.md +154 -0
  139. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/owner-eye.md +214 -0
  140. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/review.md +141 -0
  141. package/dist/skills/opengame-all-in-one/references/opengame-trailer-make/references/title.md +92 -0
  142. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/README.md +172 -0
  143. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/archetypes.md +113 -0
  144. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/briefs.md +273 -0
  145. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/core.md +129 -0
  146. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/craft.md +299 -0
  147. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/edge-cases.md +27 -0
  148. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/filmable.md +244 -0
  149. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/finishing.md +126 -0
  150. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/gates.md +184 -0
  151. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/measure.md +282 -0
  152. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/music.md +148 -0
  153. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/og-clash-record.md +133 -0
  154. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/ops.md +154 -0
  155. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/owner-eye.md +214 -0
  156. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/reference-set.md +92 -0
  157. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/review.md +141 -0
  158. package/dist/skills/opengame-all-in-one/references/opengame-trailer-plan/references/title.md +92 -0
  159. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/README.md +141 -0
  160. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/archetypes.md +113 -0
  161. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/briefs.md +273 -0
  162. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/core.md +129 -0
  163. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/craft.md +299 -0
  164. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/edge-cases.md +27 -0
  165. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/filmable.md +244 -0
  166. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/finishing.md +126 -0
  167. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/gates.md +184 -0
  168. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/measure.md +282 -0
  169. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/music.md +148 -0
  170. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/og-clash-record.md +133 -0
  171. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/ops.md +154 -0
  172. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/owner-eye.md +214 -0
  173. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/review.md +141 -0
  174. package/dist/skills/opengame-all-in-one/references/opengame-trailer-review-and-improve/references/title.md +92 -0
  175. package/dist/skills/opengame-all-in-one/references/opengame-verification/README.md +197 -0
  176. package/dist/skills/opengame-all-in-one/references/opengame-verification/helpers/browser-evidence.mjs +74 -0
  177. package/dist/skills/opengame-all-in-one/references/opengame-weapons/README.md +179 -0
  178. package/dist/skills/opengame-all-in-one/references/opengame-weapons/references/handling-numbers.md +114 -0
  179. package/dist/skills/opengame-all-in-one/references/opengame-weapons/references/reloads-and-hands.md +96 -0
  180. package/dist/skills/opengame-all-in-one/references/opengame-weapons/references/sights-and-scopes.md +98 -0
  181. package/dist/skills/opengame-all-in-one/references/opengame-weapons/references/threejs.md +240 -0
  182. package/dist/skills/opengame-all-in-one/references/opengame-world-physics/README.md +141 -0
  183. package/dist/skills/opengame-all-in-one/references/opengame-world-physics/references/measured-failures.md +79 -0
  184. package/dist/skills/opengame-api/CHANGELOG.md +12 -0
  185. package/dist/skills/opengame-api/SKILL.md +39 -13
  186. package/dist/skills/opengame-assets/CHANGELOG.md +11 -0
  187. package/dist/skills/opengame-assets/SKILL.md +79 -31
  188. package/dist/skills/opengame-assets/references/pipeline.md +67 -0
  189. package/dist/skills/opengame-audio/CHANGELOG.md +11 -0
  190. package/dist/skills/opengame-audio/SKILL.md +129 -41
  191. package/dist/skills/opengame-audio/references/mix-notes.md +44 -1
  192. package/dist/skills/opengame-audio/references/qa-without-ears.md +177 -0
  193. package/dist/skills/opengame-capture/CHANGELOG.md +10 -0
  194. package/dist/skills/opengame-capture/SKILL.md +44 -20
  195. package/dist/skills/opengame-capture/references/pipeline.md +33 -1
  196. package/dist/skills/opengame-capture/references/threejs.md +17 -1
  197. package/dist/skills/opengame-characters/CHANGELOG.md +15 -0
  198. package/dist/skills/opengame-characters/SKILL.md +94 -39
  199. package/dist/skills/opengame-characters/references/first-person-body.md +108 -0
  200. package/dist/skills/opengame-characters/references/player-og.md +1 -1
  201. package/dist/skills/opengame-cli/CHANGELOG.md +20 -0
  202. package/dist/skills/opengame-cli/SKILL.md +12 -11
  203. package/dist/skills/opengame-deploy/CHANGELOG.md +30 -0
  204. package/dist/skills/opengame-deploy/SKILL.md +43 -23
  205. package/dist/skills/opengame-deploy/references/json-events.md +6 -5
  206. package/dist/skills/opengame-deploy/references/manifest.md +9 -3
  207. package/dist/skills/opengame-deploy/references/packaging.md +32 -30
  208. package/dist/skills/opengame-depth/CHANGELOG.md +8 -0
  209. package/dist/skills/opengame-depth/SKILL.md +61 -33
  210. package/dist/skills/opengame-enemies/CHANGELOG.md +10 -0
  211. package/dist/skills/opengame-enemies/SKILL.md +96 -40
  212. package/dist/skills/opengame-enemies/references/pacing-and-bots.md +108 -0
  213. package/dist/skills/opengame-enemies/references/threejs.md +59 -0
  214. package/dist/skills/opengame-front-end/CHANGELOG.md +4 -0
  215. package/dist/skills/opengame-front-end/SKILL.md +85 -39
  216. package/dist/skills/opengame-front-end/references/menus.md +42 -8
  217. package/dist/skills/opengame-game-feel/CHANGELOG.md +11 -0
  218. package/dist/skills/opengame-game-feel/SKILL.md +95 -47
  219. package/dist/skills/opengame-game-feel/references/feel-numbers.md +59 -0
  220. package/dist/skills/opengame-game-feel/references/killcam.md +88 -0
  221. package/dist/skills/opengame-jam/CHANGELOG.md +12 -0
  222. package/dist/skills/opengame-jam/SKILL.md +48 -33
  223. package/dist/skills/opengame-lighting/CHANGELOG.md +9 -0
  224. package/dist/skills/opengame-lighting/SKILL.md +85 -34
  225. package/dist/skills/opengame-loading/CHANGELOG.md +4 -0
  226. package/dist/skills/opengame-loading/SKILL.md +78 -38
  227. package/dist/skills/opengame-loading/helpers/loading-count.mjs +115 -0
  228. package/dist/skills/opengame-loading/references/threejs.md +32 -7
  229. package/dist/skills/opengame-look/CHANGELOG.md +9 -0
  230. package/dist/skills/opengame-look/SKILL.md +122 -51
  231. package/dist/skills/opengame-look/references/matching-a-reference.md +73 -0
  232. package/dist/skills/opengame-look/references/painterly.md +69 -0
  233. package/dist/skills/opengame-look/references/post-and-lens.md +10 -3
  234. package/dist/skills/opengame-maps/CHANGELOG.md +9 -0
  235. package/dist/skills/opengame-maps/SKILL.md +78 -0
  236. package/dist/skills/opengame-maps/references/map-spec.md +77 -0
  237. package/dist/skills/opengame-mobile/CHANGELOG.md +4 -0
  238. package/dist/skills/opengame-mobile/SKILL.md +18 -18
  239. package/dist/skills/opengame-montage-make/CHANGELOG.md +5 -0
  240. package/dist/skills/opengame-montage-make/SKILL.md +187 -0
  241. package/dist/skills/opengame-montage-make/references/briefs.md +293 -0
  242. package/dist/skills/opengame-montage-make/references/day-one-questions.md +46 -0
  243. package/dist/skills/opengame-montage-make/references/edge-cases.md +27 -0
  244. package/dist/skills/opengame-montage-make/references/filmable.md +244 -0
  245. package/dist/skills/opengame-montage-make/references/finishing.md +126 -0
  246. package/dist/skills/opengame-montage-make/references/measure.md +282 -0
  247. package/dist/skills/opengame-montage-make/references/montage-capture.md +151 -0
  248. package/dist/skills/opengame-montage-make/references/montage-gates.md +84 -0
  249. package/dist/skills/opengame-montage-make/references/montage-genres.md +198 -0
  250. package/dist/skills/opengame-montage-make/references/montage-grammar.md +320 -0
  251. package/dist/skills/opengame-montage-make/references/montage-ops.md +127 -0
  252. package/dist/skills/opengame-montage-make/references/og-snipers-record.md +110 -0
  253. package/dist/skills/opengame-montage-make/references/owner-eye.md +214 -0
  254. package/dist/skills/opengame-montage-make/references/reference-study.md +293 -0
  255. package/dist/skills/opengame-montage-make/references/song.md +64 -0
  256. package/dist/skills/opengame-montage-plan/CHANGELOG.md +5 -0
  257. package/dist/skills/opengame-montage-plan/SKILL.md +197 -0
  258. package/dist/skills/opengame-montage-plan/references/briefs.md +293 -0
  259. package/dist/skills/opengame-montage-plan/references/day-one-questions.md +46 -0
  260. package/dist/skills/opengame-montage-plan/references/filmable.md +244 -0
  261. package/dist/skills/opengame-montage-plan/references/measure.md +282 -0
  262. package/dist/skills/opengame-montage-plan/references/montage-capture.md +151 -0
  263. package/dist/skills/opengame-montage-plan/references/montage-gates.md +84 -0
  264. package/dist/skills/opengame-montage-plan/references/montage-genres.md +198 -0
  265. package/dist/skills/opengame-montage-plan/references/montage-grammar.md +320 -0
  266. package/dist/skills/opengame-montage-plan/references/montage-ops.md +127 -0
  267. package/dist/skills/opengame-montage-plan/references/og-snipers-record.md +110 -0
  268. package/dist/skills/opengame-montage-plan/references/owner-eye.md +214 -0
  269. package/dist/skills/opengame-montage-plan/references/reference-study.md +293 -0
  270. package/dist/skills/opengame-montage-plan/references/song.md +64 -0
  271. package/dist/skills/opengame-montage-review-and-improve/CHANGELOG.md +5 -0
  272. package/dist/skills/opengame-montage-review-and-improve/SKILL.md +178 -0
  273. package/dist/skills/opengame-montage-review-and-improve/references/briefs.md +293 -0
  274. package/dist/skills/opengame-montage-review-and-improve/references/day-one-questions.md +46 -0
  275. package/dist/skills/opengame-montage-review-and-improve/references/filmable.md +244 -0
  276. package/dist/skills/opengame-montage-review-and-improve/references/finishing.md +126 -0
  277. package/dist/skills/opengame-montage-review-and-improve/references/measure.md +282 -0
  278. package/dist/skills/opengame-montage-review-and-improve/references/montage-capture.md +151 -0
  279. package/dist/skills/opengame-montage-review-and-improve/references/montage-gates.md +84 -0
  280. package/dist/skills/opengame-montage-review-and-improve/references/montage-genres.md +198 -0
  281. package/dist/skills/opengame-montage-review-and-improve/references/montage-grammar.md +320 -0
  282. package/dist/skills/opengame-montage-review-and-improve/references/montage-ops.md +127 -0
  283. package/dist/skills/opengame-montage-review-and-improve/references/og-snipers-record.md +110 -0
  284. package/dist/skills/opengame-montage-review-and-improve/references/owner-eye.md +214 -0
  285. package/dist/skills/opengame-montage-review-and-improve/references/reference-study.md +293 -0
  286. package/dist/skills/opengame-montage-review-and-improve/references/song.md +64 -0
  287. package/dist/skills/opengame-multiplayer/CHANGELOG.md +15 -0
  288. package/dist/skills/opengame-multiplayer/SKILL.md +143 -0
  289. package/dist/skills/opengame-multiplayer/references/bot-lobbies.md +71 -0
  290. package/dist/skills/opengame-multiplayer/references/netcode.md +165 -0
  291. package/dist/skills/opengame-performance/CHANGELOG.md +8 -0
  292. package/dist/skills/opengame-performance/SKILL.md +106 -65
  293. package/dist/skills/opengame-performance/helpers/landing-pacer.mjs +86 -0
  294. package/dist/skills/opengame-performance/references/measuring.md +51 -0
  295. package/dist/skills/opengame-performance/references/webgpu.md +86 -0
  296. package/dist/skills/opengame-production/CHANGELOG.md +13 -0
  297. package/dist/skills/opengame-production/SKILL.md +119 -54
  298. package/dist/skills/opengame-production/references/team.md +107 -0
  299. package/dist/skills/opengame-production/references/templates.md +106 -16
  300. package/dist/skills/opengame-quality-bar/CHANGELOG.md +10 -0
  301. package/dist/skills/opengame-quality-bar/SKILL.md +94 -42
  302. package/dist/skills/opengame-quality-bar/references/cheap-tells.md +14 -7
  303. package/dist/skills/opengame-quality-bar/references/judges.md +95 -0
  304. package/dist/skills/opengame-quality-bar/references/review-prompt.md +10 -5
  305. package/dist/skills/opengame-rhythm/CHANGELOG.md +5 -0
  306. package/dist/skills/opengame-rhythm/SKILL.md +138 -0
  307. package/dist/skills/opengame-rhythm/references/charting.md +109 -0
  308. package/dist/skills/opengame-rhythm/references/timing.md +92 -0
  309. package/dist/skills/opengame-router/CHANGELOG.md +12 -0
  310. package/dist/skills/opengame-router/SKILL.md +14 -7
  311. package/dist/skills/opengame-scene-audit/CHANGELOG.md +15 -0
  312. package/dist/skills/opengame-scene-audit/SKILL.md +64 -47
  313. package/dist/skills/opengame-scene-audit/helpers/scene-audit.js +97 -19
  314. package/dist/skills/opengame-sdk/CHANGELOG.md +16 -0
  315. package/dist/skills/opengame-sdk/SKILL.md +27 -10
  316. package/dist/skills/opengame-sdk/references/engines.md +2 -2
  317. package/dist/skills/opengame-sdk/references/identity.md +10 -11
  318. package/dist/skills/opengame-sdk/references/leaderboards.md +11 -1
  319. package/dist/skills/opengame-sdk/references/radio.md +1 -1
  320. package/dist/skills/opengame-stability/CHANGELOG.md +4 -0
  321. package/dist/skills/opengame-stability/SKILL.md +59 -27
  322. package/dist/skills/opengame-trailer-make/CHANGELOG.md +5 -0
  323. package/dist/skills/opengame-trailer-make/SKILL.md +164 -0
  324. package/dist/skills/opengame-trailer-make/references/archetypes.md +113 -0
  325. package/dist/skills/opengame-trailer-make/references/briefs.md +273 -0
  326. package/dist/skills/opengame-trailer-make/references/core.md +129 -0
  327. package/dist/skills/opengame-trailer-make/references/craft.md +299 -0
  328. package/dist/skills/opengame-trailer-make/references/edge-cases.md +27 -0
  329. package/dist/skills/opengame-trailer-make/references/filmable.md +244 -0
  330. package/dist/skills/opengame-trailer-make/references/finishing.md +126 -0
  331. package/dist/skills/opengame-trailer-make/references/gates.md +184 -0
  332. package/dist/skills/opengame-trailer-make/references/measure.md +282 -0
  333. package/dist/skills/opengame-trailer-make/references/music.md +148 -0
  334. package/dist/skills/opengame-trailer-make/references/og-clash-record.md +133 -0
  335. package/dist/skills/opengame-trailer-make/references/ops.md +154 -0
  336. package/dist/skills/opengame-trailer-make/references/owner-eye.md +214 -0
  337. package/dist/skills/opengame-trailer-make/references/review.md +141 -0
  338. package/dist/skills/opengame-trailer-make/references/title.md +92 -0
  339. package/dist/skills/opengame-trailer-plan/CHANGELOG.md +5 -0
  340. package/dist/skills/opengame-trailer-plan/SKILL.md +176 -0
  341. package/dist/skills/opengame-trailer-plan/references/archetypes.md +113 -0
  342. package/dist/skills/opengame-trailer-plan/references/briefs.md +273 -0
  343. package/dist/skills/opengame-trailer-plan/references/core.md +129 -0
  344. package/dist/skills/opengame-trailer-plan/references/craft.md +299 -0
  345. package/dist/skills/opengame-trailer-plan/references/edge-cases.md +27 -0
  346. package/dist/skills/opengame-trailer-plan/references/filmable.md +244 -0
  347. package/dist/skills/opengame-trailer-plan/references/finishing.md +126 -0
  348. package/dist/skills/opengame-trailer-plan/references/gates.md +184 -0
  349. package/dist/skills/opengame-trailer-plan/references/measure.md +282 -0
  350. package/dist/skills/opengame-trailer-plan/references/music.md +148 -0
  351. package/dist/skills/opengame-trailer-plan/references/og-clash-record.md +133 -0
  352. package/dist/skills/opengame-trailer-plan/references/ops.md +154 -0
  353. package/dist/skills/opengame-trailer-plan/references/owner-eye.md +214 -0
  354. package/dist/skills/opengame-trailer-plan/references/reference-set.md +92 -0
  355. package/dist/skills/opengame-trailer-plan/references/review.md +141 -0
  356. package/dist/skills/opengame-trailer-plan/references/title.md +92 -0
  357. package/dist/skills/opengame-trailer-review-and-improve/CHANGELOG.md +5 -0
  358. package/dist/skills/opengame-trailer-review-and-improve/SKILL.md +145 -0
  359. package/dist/skills/opengame-trailer-review-and-improve/references/archetypes.md +113 -0
  360. package/dist/skills/opengame-trailer-review-and-improve/references/briefs.md +273 -0
  361. package/dist/skills/opengame-trailer-review-and-improve/references/core.md +129 -0
  362. package/dist/skills/opengame-trailer-review-and-improve/references/craft.md +299 -0
  363. package/dist/skills/opengame-trailer-review-and-improve/references/edge-cases.md +27 -0
  364. package/dist/skills/opengame-trailer-review-and-improve/references/filmable.md +244 -0
  365. package/dist/skills/opengame-trailer-review-and-improve/references/finishing.md +126 -0
  366. package/dist/skills/opengame-trailer-review-and-improve/references/gates.md +184 -0
  367. package/dist/skills/opengame-trailer-review-and-improve/references/measure.md +282 -0
  368. package/dist/skills/opengame-trailer-review-and-improve/references/music.md +148 -0
  369. package/dist/skills/opengame-trailer-review-and-improve/references/og-clash-record.md +133 -0
  370. package/dist/skills/opengame-trailer-review-and-improve/references/ops.md +154 -0
  371. package/dist/skills/opengame-trailer-review-and-improve/references/owner-eye.md +214 -0
  372. package/dist/skills/opengame-trailer-review-and-improve/references/review.md +141 -0
  373. package/dist/skills/opengame-trailer-review-and-improve/references/title.md +92 -0
  374. package/dist/skills/opengame-verification/CHANGELOG.md +11 -0
  375. package/dist/skills/opengame-verification/SKILL.md +113 -48
  376. package/dist/skills/opengame-weapons/CHANGELOG.md +11 -0
  377. package/dist/skills/opengame-weapons/SKILL.md +129 -55
  378. package/dist/skills/opengame-weapons/references/handling-numbers.md +42 -0
  379. package/dist/skills/opengame-weapons/references/reloads-and-hands.md +96 -0
  380. package/dist/skills/opengame-weapons/references/sights-and-scopes.md +98 -0
  381. package/dist/skills/opengame-weapons/references/threejs.md +71 -0
  382. package/dist/skills/opengame-world-physics/CHANGELOG.md +9 -0
  383. package/dist/skills/opengame-world-physics/SKILL.md +55 -24
  384. package/dist/skills/opengame-world-physics/references/measured-failures.md +28 -1
  385. package/package.json +1 -1
@@ -0,0 +1,108 @@
1
+ # Pacing, attacks and bots
2
+
3
+ Reference configurations for "Pace in enemies met per minute", "Each enemy attacks on its
4
+ own clock" and "Bots read as players" in `SKILL.md`. LC is a wave-survival body-camera
5
+ shooter against the dead; OS a snipers-only free-for-all where every rival is a bot
6
+ presented as a person. Use the numbers as a start for a game of the same kind, then tune
7
+ on real runs.
8
+
9
+ ## LC's tide
10
+
11
+ The director that decides who comes, when and from where.
12
+
13
+ - A level every 100 s. The live cap is 9 at the start, plus 0.6 a level, up to 32.
14
+ - Health 80 at level 1 and 100 at level 2, then +25 a level, then x1.06 a level. A head
15
+ round from the starting pistol does 132, so early heads die to one shot.
16
+ - The first figure stands up at 2.5 s and then one every 4 s; first contact in 10 to
17
+ 15 s, in front of the player and out of the torch's light.
18
+ - No surge for the first 75 to 90 s, or until the first generator; a surge spreads over
19
+ 9 s; the ebb after it runs at two thirds of the rate.
20
+ - Runners from minute 2, a third of arrivals by 3:00, half by 5:00; a first sprinter
21
+ alone at 3:30.
22
+ - Arrivals 16 to 36 m away by walking distance, out of sight, flanks and ahead weighted
23
+ 3:1 over behind, the empty side weighted 4x. At level 1 nobody strikes unseen from
24
+ behind.
25
+ - Lull floor: nobody within 25 m for 8 s brings two up 12 to 34 m off.
26
+ - Stragglers: a figure 45 m behind for 4 s, or stuck for 3 s, is replaced and stops
27
+ counting toward the cap.
28
+ - A hemmed-in ceiling: at most 3 attackers within 10 m.
29
+ - Spawn coverage: from every standpoint, spawns on at least three sides at a useful range
30
+ in every door state (short of three sides: 9.7% of standpoints to 0.8%).
31
+
32
+ Targets measured on real runs: at least 8 met in minute one, 14 more in minute two, 20
33
+ more in minute three, no gap over 8 s. "Met" means first within 25 m and in view.
34
+
35
+ ### Fear before speed
36
+
37
+ "Fear comes from the dark, the numbers closing and the cost of a mistake, not from being
38
+ struck all the time." LC's six seeded scares, none of which the player can bait:
39
+
40
+ 1. A hush of 8 to 12 s, then six runners from two sides.
41
+ 2. A surge on an empty reload.
42
+ 3. The first sprinter, alone.
43
+ 4. A dive out of the dark.
44
+ 5. Lightning showing the tree line full.
45
+ 6. A silent one behind the player while both hands are busy on a machine.
46
+
47
+ ## LC's attacks
48
+
49
+ - Each figure in reach swings on its own clock: a 0.42 s wind-up, hit or miss decided by
50
+ distance at the end of it, a 0.55 s recovery, about 1.1 s between one figure's swings.
51
+ No shared gap, no turn-taking. A figure held back by the crowd within 1.75 m strikes
52
+ from where it stands.
53
+ - 34 damage of 100 a blow, so three blows down (five with the armour perk); a dive does
54
+ 45. Health regenerates after 4 s unhurt and is whole in 1.2 s.
55
+ - The leap: a 0.62 s gather from 2.5 to 4.4 m away, a 0.44 to 0.75 s flight that tracks
56
+ the first 34% toward where the player will be, never before 1:35 or within 38 s of the
57
+ last, never two in the air. A landing radius of 0.9 m, smaller than a sidestep's travel
58
+ in the flight time. A miss lands face down and is helpless for 1.5 s.
59
+ - The player's sprint (6.3 m/s) beats the fastest zombie (capped at 4.8) by a clear
60
+ margin; a walk outruns only shamblers.
61
+
62
+ ## Calibrate the test player first
63
+
64
+ LC's scripted players backed away at 2.3 m/s where a person aiming backs off at 1.33,
65
+ killed 25 to 30 a minute against a person's 13, and spaced blows 2.2 s against 2.62.
66
+ Numbers tuned on them made the game harmless for a person. Before tuning difficulty on
67
+ bots, replay a real run headless on its seed and require the bench to land within a
68
+ fifth of it, and test a player who just stands (`opengame-depth`).
69
+
70
+ ## OS's bot motor model
71
+
72
+ What made rivals read as people in killcams and in the open.
73
+
74
+ - Reaction time from an ex-Gaussian distribution with a floor of 150 ms.
75
+ - Flicks that follow a minimum-jerk path timed by Fitts' law, undershoot, then correct.
76
+ - Aim error that drifts smoothly instead of being resampled each frame.
77
+ - Scoped shots 0.22 to 0.28 s after full zoom, with settle error after a fast scope-in
78
+ (without it, rival quickscopes caused 26 of 37 of the owner's deaths). Modelled on the
79
+ owner's own play: 41% of those shots came within 0.25 s of scoping; a hip flick, a
80
+ 0.42 s pause, then a 1 degree correction.
81
+ - Strafe only under 28 m, in committed legs; reload and work the bolt in cover; ignore
82
+ distant shots briefly after a look (head whips 51 to 18); hunt high campers.
83
+ - Drawn facing trails the aim through a critically damped spring of 0.06 s, capped at
84
+ 0.6 rad; hits stay on the simulation.
85
+ - Scope choice by distance band: quickscope near, drag-scope middle, hardscope far.
86
+ - No one-frame head lock: in a killcam it "tells the player it was a bot".
87
+
88
+ ### The behaviour count
89
+
90
+ Log per match, per bot slot: share of time creeping, one-frame yaw snaps, peeks, seconds
91
+ standing in the open during a fight, seconds to engage a camper, stuck and pacing spells.
92
+ Fix the worst three, and judge every change with a same-frame A/B split by slot in one
93
+ build: alternating 40 s windows on a loaded machine read -13% CPU where the truth was
94
+ +46% and 4.5x the stuck bots, against a noise floor of 20%.
95
+
96
+ ### A lobby that feels online (OS)
97
+
98
+ Bots presented as people need a lobby that behaves like one.
99
+
100
+ - Arrivals on a lognormal spread; a lobby fills to exactly its cap only 70% of the time
101
+ ("always exactly 32 looks scripted").
102
+ - 5 to 20% of bots leave during a match, with killfeed lines; about 80% stay for the next.
103
+ - Names from a generator in the style of real console handles, mostly lowercase, with
104
+ digits or underscores in 10 to 15% of them, as the owner asked.
105
+ - An empty mic slot rather than fake talking.
106
+ - The match keeps running under the pause menu; a paused player can be killed.
107
+ - Bot powers rate-capped, for example a counter-radar at most once every 5 minutes for
108
+ at most 30 s.
@@ -0,0 +1,193 @@
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
+ ## A gait inside its rate band
128
+
129
+ Pick the clip whose stride fits the ground actually covered, and refuse to stretch it.
130
+ LC's band was 0.9 to 1.15x the capture rate; below a shamble's band the figure stands.
131
+
132
+ ```js
133
+ // gaits: [{ action, stride, captureSpeed }] sorted slow to fast; dt > 0
134
+ const speed = groundCovered / dt // after collision, not the requested speed
135
+ const held = smoothSpeed(speed, dt) // hold a change about a third of a second
136
+ let pick = null
137
+ for (const g of gaits) {
138
+ const rate = held / g.captureSpeed
139
+ if (rate >= 0.9 && rate <= 1.15) { pick = g; break }
140
+ }
141
+ if (!pick && held < gaits[0].captureSpeed * 0.67) standAndReach() // too slow for any gait
142
+ else {
143
+ pick ??= nearestGait(held) // between bands: the nearest, clamped
144
+ setGait(pick, Math.min(1.15, Math.max(0.9, held / pick.captureSpeed))) // fade in a quarter second
145
+ }
146
+ ```
147
+
148
+ Log figure-seconds whose rate would have left the band; a wall-treading fix that let
149
+ clips slow to 0.1x produced "slow mo" runners.
150
+
151
+ ## Pose sentinels in the build
152
+
153
+ Console errors in the shipped build catch the broken poses the owner otherwise finds.
154
+ LC fires on a figure in its rest pose, on both arms held level at the sides for 0.2 s,
155
+ and on a killed figure that has not started to fall within 0.25 s.
156
+
157
+ ```js
158
+ function checkPose(fig, now) {
159
+ if (fig.isRestPose()) console.error('rest pose', fig.id, fig.clipName)
160
+ const armsOut = Math.abs(fig.armElevation('left')) < 0.15 && Math.abs(fig.armElevation('right')) < 0.15
161
+ fig.armsOutSince = armsOut ? (fig.armsOutSince ?? now) : null
162
+ if (fig.armsOutSince !== null && now - fig.armsOutSince > 0.2) console.error('arms out', fig.id)
163
+ if (fig.diedAt && now - fig.diedAt > 0.25 && fig.hipDrop() < 0.05) console.error('no fall', fig.id)
164
+ }
165
+ ```
166
+
167
+ `armElevation` and `hipDrop` are the game's own measures from the rig (radians from
168
+ horizontal, metres below the standing hip); fill them in for your skeleton.
169
+
170
+ ## Crowds without a SkinnedMesh per figure
171
+
172
+ LC drew 32 zombies in 0.50 ms with 162 draws and 1.43 M triangles (9 standing: 0.21 ms):
173
+
174
+ - one float texture of every slot's bone matrices (46 KB for 22 bones a figure), uploaded
175
+ only when it changes, read in the vertex shader;
176
+ - one instanced draw per kind per detail level, at most 27 draws for the horde;
177
+ - full meshes only for the nearest 5 within 8 m; the far field one figure per family,
178
+ with no shadow;
179
+ - figures more than 78 degrees off the view culled (186 draws to 111 to 129);
180
+ - one node material per family, with per-figure values read through
181
+ `reference('material.userData.x')` rather than a material each.
182
+
183
+ Pose every near figure every frame: skipping poses for detail levels had left 144 to 297
184
+ of 720 frames unposed, which the owner saw as walking "very jaggedly".
185
+
186
+ ## Other engines
187
+
188
+ - Godot: `NavigationRegion3D`, `NavigationAgent3D` and `NavigationLink3D` for jumps;
189
+ `NavigationMesh.agent_max_climb` is the step; bake on a thread with
190
+ `bake_navigation_mesh(true)`.
191
+ - Unity: the AI Navigation package's `NavMeshSurface`, `NavMeshLink` for jumps and
192
+ `NavMeshObstacle` with carving for doors; the agent type's Step Height is the step;
193
+ `NavMeshSurface.UpdateNavMesh` rebuilds asynchronously.
@@ -0,0 +1,185 @@
1
+ > Carried from `opengame-front-end` 1.1.0. Read it when: Build a browser game's title, menus, first run, loading, settings, results and HUD. Covers menus on the game's world that never cost a frame, menu effects that never move the interface, console-grade pad and keyboard input, interface time on the wall clock, the press that starts play, settings from one schema, an honest loading bar, text that never clips and a HUD from one unit. Use when the menu looks cheap or lags, clicks do nothing, settings reset, or for a title, menu, HUD or share image.
2
+
3
+
4
+ # The front end and the HUD
5
+
6
+ The first thing a stranger sees is the title and the menu, and a button on black
7
+ answers them before the game can. The front end is part of the game, in the same world,
8
+ type and light, and it must never be the thing that hangs, lags or moves under the
9
+ pointer.
10
+
11
+ Rules carry five tags; `opengame-quality-bar` explains them and the game codes. OC's
12
+ owner asked for a console-grade menu 4 or more times and for an honest loading bar 3
13
+ times, LC's owner raised the menu effects 7 times, and OS's owner asked about 9 times for
14
+ screens with no overlap and 6 times for a match that never stops for the menu. Those
15
+ rules come first.
16
+
17
+ ## Rules
18
+
19
+ ### Every menu shows the world, with its own sound, and costs no frames
20
+ - **Invariant:** Every menu and the loading screen show the game's world with that scene's sound under it, answer focus with sound, never look like a web page or show a pixelated first frame, and hold the frame-rate floor of play: the world behind the menu is a sharp still, a film proven smooth on this device, or a live scene measured at the play floor.
21
+ - **Technique:** A looping film per screen or a rendered clip of real play, or a full-resolution still of the place in a page layer under a transparent canvas, with the engine drawing only the interface. Draw a live 3D scene behind a menu only once its frame time at native pixel ratio meets the play floor (see `opengame-performance`). Never fake motion by panning or zooming a still. Route the scene's ambience 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 still until the first frame is at full resolution.
22
+ - **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). OS's owner first asked for motion ("nothing shoudl just be fucking raw static images"), called a faked pan worse ("the still images were actually better here than this shit"), and then: "so many of the pre gameplay screens are SOOO laggy... if we cant show videos in background or anywhere thats fine just show high quality images of each map ... we cannot have anything be laggy or cause freezes etc." OS's live title world cost 174-283 ms of CPU a frame; it now stands on a 4K still with the world off ("A moving clip in the wrong weather is worse than a still in the right one"), and its bar for every menu is 60 fps with no frame over 50 ms. LC's title is a live place (a breathing camera and slow sway) under a 26 KB still that covers it until the live scene's mean level matches, and LC's menus held 60 fps. This rule replaces "every menu is a live scene": OS showed that a still beats a live world that costs frames. Motion durations 120, 160, 220 and 280 ms.
23
+ - **Applies when:** Every game with menus.
24
+ - **Verify:** Load cold in a real browser at native resolution: the first frame is sharp, the background moves only if it is a film or a measured live scene, its sound plays after the first press, and every focus change makes a sound. Record each menu's frame times at native pixel ratio: it holds the play floor. Capture the page layer and the canvas apart: with a still background, the canvas alone shows no world.
25
+
26
+ ### Menu effects texture a still picture and never move the interface
27
+ - **Invariant:** A tape, CRT, grain or scanline effect on a non-play screen is a texture over a still picture: text and buttons never shake, jitter, lean, roll, tear or warp in a way the eye or the pointer notices, every element is hit where it is drawn, the effect never shows in play, and when the owner names a real object as the target (a VHS tape, a CRT television) the build reproduces that object's measured cues before anything is made stronger.
28
+ - **Technique:** Open the named reference, write its numbers per layer into the design doc and film it beside the build at real speed. Read an adjective ("a bit trippy") as a description of the reference, never as a control to turn up; a stronger version needs the owner's word after they have seen the matched one. After one literal reading is rejected, list the real object's cues (curved glass, bezel, scanlines, a still interface) and show stills beside a reference before making it the default. Use compositor-only layers (opacity and transform). Draw static glass once, in a worker canvas, and bend each small element with CSS transforms recomputed only on open, focus, scroll or resize, so hit areas follow what is drawn. Keep SVG filters, `backdrop-filter` and `clip-path` off layers over a WebGPU canvas, skip a GPU effect pass rather than run it at zero, and let reduced motion remove moving layers rather than freeze them.
29
+ - **Reference configuration:** LC's owner asked for a tape look that was "a bit trppy and distorted"; the lead agent read that as a call for more three times and shipped a second band, hum bars, a sine lean and roll-outs that passed the team's own 10 checks. The owner: "dont shake/jitter the screen... this is way too aggressive we nee da subtle vhs effect". Matched to the reference, LC's tape is grain 0.05 stepping 4 times per 0.5 s, scan lines 1 px in 3 at alpha 0.035, a hum rising 0 to 0.05 then 0.03 over 9 s, one 14vh band with a 0.14 core drifting up over 11 s, and corner falloff 0.26 from 88%, with a pause frame diff of 0.01/255, and drew no later complaint, which is weak evidence of acceptance. LC's CRT took four builds in about 30 h ("the buttons shouldnt literlaly be moving"; "the whol menu anda ll screens should read and look like a retro crt tv... thats the bar") and held as a still curved television: curve 0.028 by 0.036, scanlines on a 3 px period at 0.34 darkness, under 1 px of element error, at most 12 recomputes a second. Measured costs over the canvas: an SVG displacement filter 1.2-2.4 fps, `backdrop-filter` 16-29 fps against 60, `clip-path` 36 fps. LC's menus held 60 fps with under 0.1 ms of interface script a frame.
30
+ - **Applies when:** Title, pause, settings, loading and results screens with a stylised effect, and any effect the owner names by a real object.
31
+ - **Verify:** Sample every element's rectangle 10 times a second for 6 s: none moves. A frame-pair diff of the text layer with the effect on and off is 0. A 5-point hit test on every row lands on that row. A table of values for each layer matches the reference's.
32
+
33
+ ### Poster first, and a film only once it plays smoothly
34
+ - **Invariant:** The menu is usable the moment it appears, a background film appears only once it is proven to play smoothly on this device, a film never blocks a control, and motion respects the player's preference.
35
+ - **Technique:** Show the still at once. Once the menu is up, fetch each clip whole into `MediaSource` before playing it, so a slow network cannot stall it mid-loop; never fetch one large clip as a blob at boot, where a failed fetch can break the boot. Pick the clip's tier with `navigator.mediaCapabilities.decodingInfo`, playing only a tier reported smooth and power-efficient, and fade it in only after `requestVideoFrameCallback` shows its first second playing without dropped frames. Start it 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 still with no autoplay; a failed or slow film stays on the still. On phones the still replaces the loading film. Test the codec in a real browser, because automated browsers often cannot decode it.
36
+ - **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. OC's 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; Playwright's Chromium could not decode H.264, so the film never played in OC's own captures. OS's software AV1 decode dropped 257 of 459 frames, and a 46.6 MB clip fetched at boot aborted and failed the release tour; after the fix the tour had 0 failed of 2,968 requests.
37
+ - **Applies when:** Games with a menu film or animated background.
38
+ - **Verify:** Load with reduced motion on: no video plays. Block the video file, or make `decodingInfo` report it as not smooth: the menu works on the still. Hide the tab: the film pauses. Count dropped frames in the first second after the fade: none.
39
+
40
+ ### The title is a scene
41
+ - **Invariant:** The title screen shows the game's world, with the game's name as crisp live text and a clear way in.
42
+ - **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.
43
+ - **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. LC self-hosts its open-licence faces with `font-display: block` and inlines the font so the first paint needs no fetch.
44
+ - **Applies when:** Every game.
45
+ - **Verify:** Capture the title cold at laptop and 1080p sizes; inspect the computed font family; Tab reaches Play first and Enter starts the game.
46
+
47
+ ### Console-grade input: one press, taught keys, the right pad, one focused row
48
+ - **Invariant:** An interaction fires on one press (a timed action starts on the press and shows its progress), a moved or new binding is taught until the player uses it, prompts show the buttons of the device in hand, every menu step has exactly one focused row, and a player on a laptop with no mouse can play.
49
+ - **Technique:** One action map for keyboard and mouse, pad and touch, switching prompts the frame another device is used, and deciding the device by recent motion past the dead zone, so a resting stick never takes over from the mouse. Identify a pad by vendor and product id before its name (test the specific maker before a generic "Wireless Controller"), and take every button word from one name table. Keep exactly one enabled row focused; wrap; when a row greys out, move focus to the nearest enabled row; remember focus per screen and tab; let hover move focus without scrolling the list. Make destructive actions holds, or a click that arms and a second click that confirms. A press still held from the action that opened a screen does nothing there until it is released; a fresh press acts. Unplugging a pad pauses with one line of text. Offer a keyboard-only layout for laptops (arrows to look, a key to aim, a key to use). Never move a default binding without the owner's decision, a changelog line and a save migration. Remapping, sensitivity and dead zones are in `opengame-accessibility`.
50
+ - **Reference configuration:** LC's owner: "f should be interactions not e" and "e should also be how u ads (for people without a mosue on laptop btw)"; LC's arrow look reaches 140°/s in 0.22 s. Both owners wanted interactions that answer a press: LC's "interactions should not be holding f to buy a gun it should just be pressing f or holding f but just say press f on the ui", and OS's pickup should "just be pressing f not holding", after 7 asks. LC guards a new screen against a carried-over press for 0.15 s, teaches a moved key every run until it is used, and gives the device to a mouse that moved in the last 3 s, after a resting stick had flipped the device every frame and slowed the mouse through aim help. LC walked 196 scripted menu steps under DualSense and Xbox ids after a regex had named an Xbox pad a PlayStation one; no real pad was ever held, which is the gap. OS's owner: "it says x to pick up but im using a ps5 controller". An OS agent moved E to zoom cycling while serving another ask: "also remember u need ot be able to eds with E as well! why did we remove that?"
51
+ - **Applies when:** Every desktop game with menus, and every game that claims controller support.
52
+ - **Verify:** Walk every screen by keys, by pad under each maker's ids and by mouse, at three aspect ratios, with rows found by name: each step shows exactly one focused row and no keyboard glyph while a pad is in use. Play the first objective on the laptop layout with no mouse. Hold a real pad of each maker before claiming parity.
53
+
54
+ ### Interface time is wall time, and the first press on a visible screen acts
55
+ - **Invariant:** Menu animations, input gates, video clocks, countdowns, bars, heartbeats and logged durations run on real elapsed time while the simulation keeps its clamped step; a press on any visible screen acts at once, even during an entrance or a load; a press made just before a screen appears is kept, neither lost nor taken blind; and no prompt offers an action that cannot act yet.
56
+ - **Technique:** Read the wall clock, with a capped step, for curtains, wipes, pointer arming, video, countdowns, heartbeats and every logged duration, and keep the clamped delta for the simulation. Latch input from the first frame, and never gate it on a backdrop or an entrance animation. Release held input on blur and time out wait-for-release latches. Keep a press made in the moments before a menu shows, light its row, and act on it shortly after on a timer that reads the real clock; carry held movement keys across a screen change and drop one-off presses until they are released. Hide a Skip or Continue prompt until its action can act. Game timers that should slow with the game are in `opengame-game-feel`.
57
+ - **Reference configuration:** Six OS bugs came from a 50 ms delta clamp: a 180 ms wipe took about 2 s, clicks stayed unarmed for 1.7 s at 3 fps, the title ignored presses for about 7 s, a countdown on clamped time ran about twice as long on slow machines, and a heartbeat summing clamped deltas reloaded a live game at about 3 fps. A press at about 5 s waited until 10.3 s; fixed, the menu opened 0.6 s after the press. OS's boot bar held 13% for 27.4 s; fixed, its longest hold was 0.88 s. The owner: "i hit d one and i start to hear footsteps but it doesnt do anything and im stuck on this gunsmith screen?... wtf?". LC keeps a press from the 5 s before the menu shows and acts on it about a third of a second after lighting the row: 10 of 10 kept, where 2 of 2 had been dropped. LC's owner: "whyd eos this say skip if its loading".
58
+ - **Applies when:** Every game with a capped simulation step, a loading phase or animated screens.
59
+ - **Verify:** Under a 4x CPU throttle, wipes, countdowns and logged durations match a stopwatch. A press 100 ms after the title draws acts. Press Enter in the moment between ready and the menu appearing: the press is kept and acted on.
60
+
61
+ ### The press that starts play starts it, and the match never waits for a menu
62
+ - **Invariant:** The press that starts a run hides the menu in its own frame, starts play with no second wait or "click to take control", and takes mouse look in the same press; in a game presented as online, opening the menu, changing settings, idling or switching tabs never stops the match, and world audio carries on under the menu, ducked.
63
+ - **Technique:** Request pointer lock inside the handler of the press that starts play (with `unadjustedMovement` where the browser supports it), and outside OpenGame request fullscreen only after `pointerlockchange`, because fullscreen spends the user activation; inside OpenGame's frame the page owns fullscreen, so call `og.fullscreen.request()` from a click and never `requestFullscreen` (`opengame-sdk`). Give one owner the lock state and have it confirm a held lock rather than request it again; browsers refuse a lock requested from an Escape keydown. In an online-styled game the simulation clock never reads interface state and the menu only captures input; a solo game pauses as [references/menus.md](references/menus.md) describes. Scripted calls into the page are granted user activation, so test the lock and its refusal with a real click.
64
+ - **Reference configuration:** LC's owner: "we jshould just have the lading screen before the main menu... and then main menua nd hitting new run automatically starts game.. no more loading". LC's New run reaches the first frame of play in 12-23 ms and holds the lock 6-12 ms after the press, where it had taken 280-324 ms and flashed a prompt. OS's owner asked six times, for example "everyone needs to keep playing -> pause is just u opening menu not pausing the game!" and "u should hear the gameplay in background (muted a bit) but not just the voices", and: "and again i said get rid of this weird spawn in shit wher eu dont spawn in and it says click to take control!". In OS, fullscreen spent the activation, so runs fell to the click prompt ("lock+fullscreen both hold in that order, every other order loses the lock"), and a second lock request dropped the lock in 1 of 7 tours.
65
+ - **Applies when:** Every game that takes the pointer; keeping the match running applies to bot-filled and online-styled games.
66
+ - **Verify:** A real-pointer tour logs `document.pointerLockElement` at drop-in, at respawn and after alt-tab. Time the press to the first frame of play. In an online-styled game, film 10 s with the menu open mid-fight: bots move, timers run, and ambience is heard.
67
+
68
+ ### A short first run from the title to play
69
+ - **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.
70
+ - **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.
71
+ - **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. OS's loadout took 8 or more asks (Enter confirms, Confirm at bottom right) and passed only under a real interaction test.
72
+ - **Applies when:** Every game with menus before play.
73
+ - **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.
74
+
75
+ ### Saves survive a reload, and the player is told when they cannot
76
+ - **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.
77
+ - **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 change to the tier the player chose steps at most once, never in menus, never below the floor the owner set, and says so on screen; a resolution scaler inside a tier is in `opengame-performance`.
78
+ - **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." OH renamed its game twice and kept the old save-key prefix so nobody lost their bests.
79
+ - **Applies when:** Every game with settings or a profile.
80
+ - **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.
81
+
82
+ ### Settings come from one schema, and rebinding swaps
83
+ - **Invariant:** One typed schema defines every setting, and the settings screen, the store, the defaults, the migration and any import all read it, so a saved or pasted value can only be an allowed value and no two actions ever share a key.
84
+ - **Technique:** Typed fields with ranges, read through a sanitiser on every load and import. Build the settings screen from the schema rather than by hand. Offer copy and paste of settings as text, through the same sanitiser. Put whole looks or presets first, and let the player try one on live after a short pause on it. When a player binds a key another action holds, give that action the old key (a swap), never two actions on one key or one action on none. A reset asks twice.
85
+ - **Reference configuration:** OH keeps 128 settings in one schema with a sanitiser, six whole looks tried on live after 260 ms, settings copied and pasted as text, and resets asked twice; launch QA had found two lanes sharing one key. LC stores its four pad layouts as bindings in the same table. OC's store had saved only 3 of 21 settings (see the rule above).
86
+ - **Applies when:** Every game with more than a handful of settings, deep customisation or remapping.
87
+ - **Verify:** Paste junk settings text: every field lands on an allowed value. Rebind one action to another's key and play both actions. Diff the settings screen's fields against the schema: nothing missing, nothing extra.
88
+
89
+ ### The loading bar is honest and always moving
90
+ - **Invariant:** The loading bar follows real work to the moment play can start, rises in small steps, never goes backwards, keeps moving while shaders compile, never holds still long enough to look frozen, and reads full only when the next screen responds.
91
+ - **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. Draw the count with compositor-only CSS transforms (a strip of digits, a scaled bar), so it keeps stepping while compiles block the page. Show a time-left estimate only if it held close through a whole boot. Test on a throttled connection; a fast local boot hides every stall. What the count weighs, and what "playable" means, is in `opengame-loading`.
92
+ - **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. LC's first count read 91% at 0.8 s with play 17-21 s away; fixed, it reached 100% at 22.1 s with play ready at 21.8 s, rising at most 30 points a second and holding an eighth of a second after 100. LC's time-left estimate was 2.8-10.3 s off and was hidden. OS hung at 22% on a hard-coded 0.22, first "fixed" with a fake moving band; the owner: "it should just be loading and 0->100% and then the 5->1 countdown and not hanging".
93
+ - **Applies when:** Every game with a loading screen.
94
+ - **Verify:** Film the bar on a throttled connection and read each shown value from the pixels with its time: no backward step, no hold past the limit, and play responds when the bar reads full.
95
+
96
+ ### A boot veil with a deadline
97
+ - **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.
98
+ - **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.
99
+ - **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.
100
+ - **Applies when:** Every game with loading.
101
+ - **Verify:** Throttle the network and block one required asset: the veil lifts at the deadline and the screen offers a retry.
102
+
103
+ ### Loading that cannot hang, failures you can act on
104
+ - **Invariant:** Every wait has a deadline and a fallback, and a failure says what happened and offers a way forward.
105
+ - **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.
106
+ - **Reference configuration:** ST's rule: loading is complete only when the next advertised action responds. LC opens a pressed menu page's frame at once, reading "OPENING" in 26 ms, while its late script arrives.
107
+ - **Applies when:** Every game.
108
+ - **Verify:** Kill the network mid-load and press every button on the screen that appears.
109
+
110
+ ### Every click lands, wherever the button is released
111
+ - **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.
112
+ - **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.
113
+ - **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. OS's careless-player fuzzer found Enter ignored after a key was held over a tab switch.
114
+ - **Applies when:** Every browser game with DOM over the canvas or menus drawn in the canvas.
115
+ - **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.
116
+
117
+ ### No text is cut, overlapped or off screen at any size
118
+ - **Invariant:** On every screen and in every state, no text is cut, ellipsised, off screen, overlapping another element or below a readable size, at any window size the game supports, and a rule that shortens text to fit drops decoration before meaning.
119
+ - **Technique:** Have the game report its own layout: dump every box and text extent from the DOM (or every draw command of a canvas-drawn interface) for each screen and state, at many window sizes and at the HUD-scale and safe-area settings, set through the real settings screen. Intersect each text range with its clipping ancestors, scope each check under its screen, crop each finding, and exit non-zero on any finding outside an allowlist whose entries carry a reason. Reserve whole rectangles for slots whose content changes, not one item's width. Keep characters inside the frame, fading before any image edge. Run it after every interface pass and in every release.
120
+ - **Reference configuration:** OH audits every screen at eight sizes from 1100x900 to 2560x1440 with a root size of `clamp(10px, 0.78vw + 0.55vh, 24px)`, three type sizes a screen and nothing under 13 px; its rule for shortening text to fit had dropped the genre first, an owner-found bug ("how come so many songs are missing their genre and subgenre on the tracklist?"). OS's owner said "We can't have overlaps or overflows anywhere." about 9 times; OS's layout dump over about 70 screens at six resolutions went from 320 findings to 0 with an empty allowlist and found everything past x=1728 off screen at 16:10, but checked nothing for half a day because a backdrop at z-index -1 read as a modal. OS on framing: "no cut outs ... even fi they move".
121
+ - **Applies when:** Every game with a DOM or canvas-drawn interface.
122
+ - **Verify:** The audit is empty apart from named exceptions. Plant an overlap and a cut label: it fails on each. Capture every list row at five sizes.
123
+
124
+ ### Say where, not what the folder is called
125
+ - **Invariant:** Every out-of-match surface names a place the way a player is sent there, and names it the same way everywhere.
126
+ - **Technique:** One table of places with their names and when they are, read by the menu, the loading screen and the results.
127
+ - **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.
128
+ - **Applies when:** Games with levels, maps or places.
129
+ - **Verify:** Grep the front end for internal ids reaching visible text.
130
+
131
+ ### Pause, settings, results and retry belong to the game
132
+ - **Invariant:** Every screen outside play shares the game's visual language, settings apply live, and retry resets the game without reloading the page.
133
+ - **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.
134
+ - **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.
135
+ - **Applies when:** Every game.
136
+ - **Verify:** Walk that whole loop by keyboard alone, twice, and check that nothing duplicated (loops, listeners, decoders) on the second pass.
137
+
138
+ ### A HUD scaled from one unit, and sized once against a reference
139
+ - **Invariant:** The HUD keeps its proportions at every screen size, numbers do not jitter as they change, the centre of the screen stays clear, and its size is set against a reference frame or the owner's word and then offered as a setting, never moved back and forth by critic notes.
140
+ - **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 or a thin stroke rather than panels; icons drawn per element at one stroke weight; text written only when it changes. Measure each cluster's share of the frame against the reference frame once, record it, and offer a HUD-scale setting rather than resizing after each critique. The zero-HUD setting is in `opengame-accessibility`.
141
+ - **Reference configuration:** AW: `--u: min(0.0926vh, 0.0521vw)`, one 1080p pixel. LC sizes its console interface from `min(1vh, 0.5625vw)` and draws HUD text with a black stroke plus a shadow. 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; sized to its reference frame, OC's clusters take 13-15% of the width (see `opengame-quality-bar`). OS's HUD went from "way too big" to "so small" in one day, as one judge's "30-40% too big" was answered and the next said it had shrunk too far. LC writes HUD text only on change and holds a task-line change that only names a new place for 6 s: a 42-minute run's events had made 74 text changes for 21 steps, and now make 20.
142
+ - **Applies when:** Every game with a HUD.
143
+ - **Verify:** Capture the HUD at every desktop viewport: the layout is the same picture at each size, a counting number does not shift its neighbours, and each cluster's share matches the recorded one.
144
+
145
+ ### A hitmarker grammar
146
+ - **Invariant:** The player can tell a hit, a critical hit, a kill and incoming damage apart at a glance, and their direction.
147
+ - **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.
148
+ - **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. OS fires a hitmarker only on damage the resolver scored, after "im also getting too many hitmarkers... when i shoudlnt be".
149
+ - **Applies when:** Combat games.
150
+ - **Verify:** Frame-step a recording of a hit, a headshot and a kill; each mark is distinguishable on a single frame.
151
+
152
+ ### Flashes are limited at the source
153
+ - **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.
154
+ - **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.
155
+ - **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. LC's hurt rim keeps at least three quarters of the frame clear.
156
+ - **Applies when:** Every game with flashes, damage overlays or explosions.
157
+ - **Verify:** Record the worst flash in the game and measure per-frame mean luminance; no step exceeds the limit. See `opengame-accessibility`.
158
+
159
+ ### The FPS counter informs and never alarms
160
+ - **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.
161
+ - **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.
162
+ - **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.
163
+ - **Applies when:** Games that show a frame-rate counter.
164
+ - **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.
165
+
166
+ ### New interface is built from the game's own kit
167
+ - **Invariant:** Every dialog, badge, toast and card added later looks and sounds like the game's own menus, from its first frame.
168
+ - **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. Check an entrance animation frame by frame, because a timing contract can pass while the frames stay faded.
169
+ - **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. OS's perk medals took 6 asks ("we need it to look like the second frame asap"): a 220 ms entrance contract passed while the medal stayed faded.
170
+ - **Applies when:** Every game that adds web UI around or over the canvas.
171
+ - **Verify:** Capture the new dialog beside a menu in one frame: same type, colours and corners. Hover and click it with sound on. Step its first 300 ms frame by frame: it is whole by the frame the design says.
172
+
173
+ ### The share card is a frame of the real game
174
+ - **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.
175
+ - **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.
176
+ - **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.
177
+ - **Applies when:** Every game with a public URL.
178
+ - **Verify:** Paste the live URL into a link-preview checker and a chat app: the card is a sharp real frame with no counter.
179
+
180
+ ## Further reading
181
+
182
+ Interface sound, controls legends, pause in solo and online-styled games, pointer lock
183
+ traps and the menu audio path: [references/menus.md](references/menus.md). First-run
184
+ details, the share card and analytics for a game served from its own domain:
185
+ [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.