@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,165 @@
1
+ # Netcode notes from LC
2
+
3
+ LC's four-player private lobbies were built in a few days and measured on headless pages
4
+ on one machine. They were never deployed, never played by people and no voice went
5
+ through them, so read every number here as what the protocol did under test, not what
6
+ players felt.
7
+
8
+ ## Who owns what
9
+
10
+ | Thing | Owner | Why |
11
+ | --- | --- | --- |
12
+ | The map | Everyone, from one seed | Nothing to send, nothing to disagree about |
13
+ | A player's body, aim and own shots | That player's page | Their input never waits on the line |
14
+ | A hit on an enemy or another player | Claimed by the shooter, decided by the host | A claim 40 m off the round's line was refused on four pages |
15
+ | Enemies, waves, stations, doors, points, weather | The host page | One answer to every shared question |
16
+ | The room, seats, the host's checkpoint | The relay | It outlives any one page and never simulates |
17
+
18
+ ## One protocol file
19
+
20
+ The page and the relay import the same module, so a size or rate cannot differ between
21
+ them. LC's limits:
22
+
23
+ | Kind | Direction | Size | Rate |
24
+ | --- | --- | --- | --- |
25
+ | Body (pose, aim, stance) | each page to all | exactly 28 B | 30 a second |
26
+ | Events (shot, reload, use) | each page to all | 6 to 32 B | as they happen |
27
+ | Wish (a client asks the host) | client to host | up to 29 B | paid only on the answer |
28
+ | Host world update | host to all | up to 1200 B | up to 80 a second |
29
+ | Host checkpoint | host to room | up to 4096 B | about once a second, kept by the room |
30
+ | Chat | any | up to 200 characters | |
31
+
32
+ Eight fouls close a line, and so does a frame over 4200 B or more than 300 frames a
33
+ second. A capability integer in the welcome message lets mixed builds share a room. At a
34
+ cap of 32 a second the room "dropped what was over without a word" until the cap was
35
+ raised and every drop was counted.
36
+
37
+ Bandwidth with three players: a guest received about 5,100 B/s and the host sent about
38
+ 4,925. The relay's plan billed about 13,000 to 19,000 requests a room-hour; check how
39
+ your host bills WebSocket messages before you choose a send rate.
40
+
41
+ ## Join codes
42
+
43
+ Six characters from an alphabet without look-alikes (for example, leave out 0 and O, and
44
+ 1, I and L), and ten
45
+ wrong codes lock an address for a minute. A private room is reachable only by its code.
46
+
47
+ ## Liveness, migration and rejoin
48
+
49
+ - The socket lives in a Web Worker, so a long main-thread frame cannot starve it.
50
+ - The room declares a page silent after 2 s, and the page declares the room silent after
51
+ 3 s.
52
+ - Reconnect attempts at 0, 0.2, 0.4 and 0.8 s, then every second.
53
+ - A seat is held 2 minutes. 30 s was shorter than one page's own boot on a busy machine.
54
+ - The host passes on close code 1001 (going away), or on an `away` message the page sends
55
+ from `pagehide`, to the lowest seat still standing. Measured: the new host named 49 to
56
+ 91 ms after the close, enemies standing still at most 26 ms (they had stood 1.8 to
57
+ 2.0 s before the checkpoint was kept by the room).
58
+ - A rejoin token lives in `sessionStorage` and `localStorage` for 2.5 minutes, with a Web
59
+ Lock per seat so two tabs cannot take one seat. A reload rejoins before the title with
60
+ position, weapons and rounds kept.
61
+ - A loading player is not drawn and cannot be hit until their page says it is playing.
62
+
63
+ ## Drawing other players
64
+
65
+ ```js
66
+ // Per remote player, keep recent samples in send order: { sentAt, receivedAt, state }.
67
+ const BEHIND_MS = 100, OFFSET_WINDOW_MS = 2000, MAX_EXTRAPOLATE_MS = 150;
68
+
69
+ // The smallest arrival delay seen recently is the best estimate of the gap between the
70
+ // sender's clock and ours (it includes the fastest the line has been).
71
+ function clockOffset(samples, now) {
72
+ let best = Infinity;
73
+ for (const s of samples) if (now - s.receivedAt <= OFFSET_WINDOW_MS) best = Math.min(best, s.receivedAt - s.sentAt);
74
+ if (best === Infinity) { const s = samples[samples.length - 1]; best = s.receivedAt - s.sentAt; }
75
+ return best;
76
+ }
77
+
78
+ function drawnState(samples, now, lerpState) {
79
+ if (!samples.length) return null;
80
+ const t = now - clockOffset(samples, now) - BEHIND_MS; // the moment to draw, in the sender's clock
81
+ if (t <= samples[0].sentAt) return samples[0].state; // older than anything kept
82
+ for (let i = samples.length - 1; i > 0; i--) {
83
+ const a = samples[i - 1], b = samples[i];
84
+ if (a.sentAt <= t && t <= b.sentAt) {
85
+ return lerpState(a.state, b.state, b.sentAt > a.sentAt ? (t - a.sentAt) / (b.sentAt - a.sentAt) : 1);
86
+ }
87
+ }
88
+ const last = samples[samples.length - 1], prev = samples[samples.length - 2];
89
+ if (!prev || last.sentAt <= prev.sentAt) return last.state; // nothing to extrapolate from
90
+ const ahead = Math.min(t - last.sentAt, MAX_EXTRAPOLATE_MS); // never run far past the data
91
+ return lerpState(prev.state, last.state, 1 + ahead / (last.sentAt - prev.sentAt));
92
+ }
93
+ ```
94
+
95
+ LC measured a drawn-error median of 0.5 cm and a p95 of 18 to 22 cm, and 87 of 102 tail
96
+ samples came from the sender's own long frames, not the network. A simulation of a
97
+ smoothing change promised a p95 of 84 down to 27 cm; real pages showed 71.7 against
98
+ 71.8. Measure smoothing on pages.
99
+
100
+ ## The bad-network pipe
101
+
102
+ Browser network throttling does not hold WebSocket frames, so put a TCP relay between the
103
+ pages and the room server. Removing bytes from a TCP stream would corrupt it, so "loss"
104
+ here is what loss looks like to a WebSocket: a hold for a retransmission delay.
105
+
106
+ ```js
107
+ // pipe.mjs: node pipe.mjs LISTEN_PORT TARGET_HOST TARGET_PORT
108
+ import net from 'node:net';
109
+ const [listen, host, port] = process.argv.slice(2);
110
+ const ONE_WAY_MS = 100, JITTER_MS = 20, LOSS = 0.02, RETRANSMIT_MS = 200;
111
+
112
+ function delayed(src, dst) {
113
+ const queue = []; // { due, chunk } in arrival order; one timer drains it in order
114
+ let timer = null, ended = false;
115
+ const drain = () => {
116
+ timer = null;
117
+ const now = Date.now();
118
+ while (queue.length && queue[0].due <= now) dst.write(queue.shift().chunk);
119
+ if (queue.length) timer = setTimeout(drain, queue[0].due - now);
120
+ else if (ended) dst.end();
121
+ };
122
+ src.on('data', (chunk) => {
123
+ const hold = ONE_WAY_MS + (Math.random() * 2 - 1) * JITTER_MS + (Math.random() < LOSS ? RETRANSMIT_MS : 0);
124
+ const after = queue.length ? queue[queue.length - 1].due : 0; // never overtake, as TCP never does
125
+ queue.push({ due: Math.max(Date.now() + hold, after), chunk });
126
+ if (!timer) timer = setTimeout(drain, Math.max(0, queue[0].due - Date.now()));
127
+ });
128
+ src.on('end', () => { ended = true; if (!timer) drain(); });
129
+ src.on('error', () => dst.destroy());
130
+ }
131
+
132
+ net.createServer((client) => {
133
+ const server = net.connect(Number(port), host);
134
+ delayed(client, server);
135
+ delayed(server, client);
136
+ }).listen(Number(listen));
137
+ ```
138
+
139
+ Point each page's socket at the pipe's port. 100 ms each way is the 200 ms round trip LC
140
+ tested at.
141
+
142
+ ## The test rig
143
+
144
+ - **The room server alone.** Started by its own process, tested without a browser: joins,
145
+ codes, caps, fouls, migration and rejoin. LC had 114 such tests.
146
+ - **N pages, one job.** Several headless, muted browsers in one test, run as a single job
147
+ in your machine's job queue. Each page in its own guard, so one crash names itself.
148
+ - **One real-input player.** At least one page driven by real input events (key and
149
+ pointer events through the browser's input pipeline), never only by calls into the game.
150
+ - **A script-only cheat.** Test players survive through a cheat only a script can turn
151
+ on, and one stays vulnerable so damage, downs and revives are still tested.
152
+ - **Frames at the draw.** Count frames where the renderer submits, not at
153
+ `requestAnimationFrame`, which ran at 57 a second on pages drawing 18.
154
+ - **No read-back in a timed window.** A canvas read-back froze a timed revive for 3 s.
155
+ - **Every lobby control pressed once.** LC's panel answered no real press until somebody
156
+ pressed one.
157
+ - **Load.** Two rooms of two on one machine with one player reloading over a slow line.
158
+
159
+ ## Voice, as designed
160
+
161
+ A WebRTC mesh, Opus, STUN only. The mic opens on the player's press. Proximity gain 0.7 at
162
+ 40 m, then a raised cosine down to 0 at 90 m; through a wall x0.6 and a 900 Hz low-pass;
163
+ the game ducks 4 dB under any voice. No TURN server, so a player behind a strict NAT had
164
+ no path. A mesh also shares every player's IP address with every other player. Nobody
165
+ spoke or listened through any of it.
@@ -1,5 +1,13 @@
1
1
  # opengame-performance changelog
2
2
 
3
+ ## 1.1.1
4
+
5
+ `landing-pacer.mjs` lets a frame whose promise rejects leave the queue, so two failed submits no longer hold every later frame; `stats()` counts them as `failed`.
6
+
7
+ ## 1.1.0
8
+
9
+ New rules from LC, OS and OH for bare timing runs, pacing by what lands (with `landing-pacer.mjs`), draws counted per pass, uploads that never stall and whole-tab memory over long sessions. Frame budgets now count frames the engine ran because a page throttle never reaches a worker-thread engine (OS), resolution steps lower the world before the gameplay layer (OH, LC, OS), and a countdown may warm the first match once its map is shown (OS); a new reference covers three.js on WebGPU.
10
+
3
11
  ## 1.0.0
4
12
 
5
13
  First public release, in the opengamehq/opengame repository and the OpenGame CLI.
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  name: opengame-performance
3
- description: Keep a browser game smooth on an ordinary laptop, with three.js specifics. Covers frame-time variance and one-percent lows, per-system timing, writes only on change, menus and previews at high pixel ratio, quiet-machine A/B measurement, draw and memory budgets, shader prewarm, textures decoded once, dynamic resolution and no per-frame allocation. Use when the person says the game stutters, hitches, lags, drops frames, swings between frame rates, has a slow menu or freezes on the first explosion.
3
+ description: Keep a browser game smooth on an ordinary laptop and a shared GPU, with three.js and WebGPU specifics. Covers frame-time tails counted from frames the engine ran, bare timing runs, cost over frame rate, frame pacing by what lands, draw calls per pass, a fixed light set and warm-up, uploads that never stall, the world lowered before the gameplay layer, and whole-tab memory. Use when the game stutters, hitches, drops frames, swings between rates, has a slow menu or a mouse that feels slow.
4
4
  metadata:
5
- version: "1.0.0"
5
+ version: "1.1.1"
6
6
  ---
7
7
 
8
8
  # Performance
@@ -11,11 +11,16 @@ A game is smooth when its worst frames are fast, not when its average is. Player
11
11
  the 99th percentile: the hitch on the first explosion, the stall when a new material
12
12
  compiles, the sawtooth of the garbage collector. They feel the spread as well: OC's owner
13
13
  asked about 25 times for a stable frame rate and put it as "MINIMIZE VARIANCE (... not
14
- bouncing 60-120)". Measure the tails and the spread, on the real route, and fix what the
15
- measurement names.
14
+ bouncing 60-120)", and OS's owner asked for a "120 fps target with 0 variabliity".
15
+ Measure the tails and the spread, on the real route, and fix what the measurement names.
16
+ OS and LC found their own instruments wrong more often than their code: callbacks counted
17
+ as frames, a throttle that never reached the engine, a capture tool's read-back timed as
18
+ the game's. Prove the instrument first.
16
19
 
17
20
  Rules carry five tags; `opengame-quality-bar` explains them and the game codes. Loading
18
21
  and download size have their own skill, `opengame-loading`; phones have `opengame-mobile`.
22
+ three.js WebGPU details (graph sharing, uniform groups, what `compileAsync` misses, the
23
+ upload ring) are in [references/webgpu.md](references/webgpu.md).
19
24
 
20
25
  ## Measure the running game
21
26
 
@@ -30,111 +35,147 @@ leak; frame-time samples do not measure retained memory.
30
35
 
31
36
  ### Low variance beats a high average
32
37
  - **Invariant:** After warm-up the frame time stays close to its median: the one-percent low holds the floor, no frame runs far past the usual, and every average is reported with the spread beside it.
33
- - **Technique:** Record every frame's duration on the real route after a warm-up, and report the median, p99, the one-percent low (the frame rate of the slowest hundredth of frames), the worst frame as a multiple of the median, and the count of frames over twice the median. Show an FPS counter that is green at the floor and yellow below it. When a game cannot hold its top rate, cap it at a rate it holds rather than letting it swing. Three.js: time frames in the `setAnimationLoop` callback with `performance.now()`, use stats.js for the on-screen counter, and fix the pixel ratio while measuring.
34
- - **Reference configuration:** OC's targets: desktop floor 60 fps, aim 120 (phone targets are in `opengame-mobile`); one-percent low at least 60 at 1280 x 720; p99 at most 1.5x the median; no frame over 2x the usual once warm; counter green at 60 and up and yellow below, with no red. Averages hid the problem: OC measured combat at 74 fps average with a 35 fps one-percent low, one build at 64 and 13, another at 31 and 8.6.
38
+ - **Technique:** Record every frame's duration on the real route after a warm-up, and report the median, p99, the one-percent low (the frame rate of the slowest hundredth of frames), the worst frame as a multiple of the median, the share of frames over the display's period, and the count of frames over twice the median. Show an FPS counter that is green at the floor and yellow below it. When a game cannot hold its top rate, cap it at a rate it holds rather than letting it swing. Three.js: time frames in the `setAnimationLoop` callback with `performance.now()`, use stats.js for the on-screen counter, and fix the pixel ratio while measuring.
39
+ - **Reference configuration:** OC's targets: desktop floor 60 fps, aim 120 (phone targets are in `opengame-mobile`); one-percent low at least 60 at 1280 x 720; p99 at most 1.5x the median; no frame over 2x the usual once warm; counter green at 60 and up and yellow below, with no red. Averages hid the problem: OC measured combat at 74 fps average with a 35 fps one-percent low, one build at 64 and 13, another at 31 and 8.6. OS's bar was a one-percent low of at least 50 fps with under 5% of frames over 16.7 ms; a quiet run averaged 75-93 fps with 10-24% of frames over 16.7 ms, which was the owner's "lagging and not smooth". No OS map reached 120. LC, measured alone, held 60 fps in 49 of 49 ten-second rows over 523 s; what degraded was long frames, not the steady rate.
35
40
  - **Applies when:** Every real-time game. Turn-based and puzzle games still need it in menus and transitions.
36
41
  - **Verify:** The measurement script prints the one-percent low and the count of frames over twice the median for the busiest route; a run whose average clears the floor while its one-percent low does not is reported as a failure.
37
42
 
38
- ### Budgets are tails, measured on the real route
39
- - **Invariant:** The game has written budgets for frame-time tails and for what each frame draws, and every number reported against them came out of one measurement script on the real path: menu, Play, live play.
40
- - **Technique:** Drive the production path with input, record frame times, and report p50, p95, p99 and long tasks, plus draw calls, triangles, texture and geometry memory, and JS allocation rate. Print the machine's load and the throttle actually achieved beside every result, because milliseconds move with load and counts do not.
41
- - **Reference configuration:** AW, at 1920 x 1080 on its high tier with 12 combatants under a 4x CPU throttle: p50 16.7 ms, p95 25.0 ms, p99 33.3 ms, long tasks 300 ms per 20 s, 700 draw calls, 900,000 triangles, 320 MB of textures, 160 MB of geometry, 200 MB of decoded audio, 4 MB/s of allocation. AW estimates 2x throttle is about an M1 Air's CPU and 4x pessimistic by design; the throttle does nothing to the GPU.
42
- - **Applies when:** Every 3D game. Smaller games set smaller budgets, but the shape (tails, counts, one script) stays.
43
- - **Verify:** The script prints all of the above for the busiest route, and fails when a map did not actually load (AW measured a grey stand-in arena under a map's name, and it looked faster than the truth).
43
+ ### Budgets are tails, counted from frames the engine ran on the player's path
44
+ - **Invariant:** The game has written budgets for frame-time tails and for what each frame draws, and every number reported against them counts frames the engine actually presented, on the production path (menu, Play, live play), with the tier, renderer, pacing and machine state confirmed by the game's own log.
45
+ - **Technique:** Drive the production path with input, and count the frames the engine admitted and presented, not animation-frame callbacks, which keep firing when the engine or GPU skips. Report p50, p95, p99 and long tasks, plus draw calls, triangles, texture and geometry memory, and JS allocation rate. Log the median frame beside the engine's CPU and GPU time: a gap above both is waiting, not work. Test any frame pacer on an exact refresh grid. To stand in for a weak machine, limit the machine where the engine runs: a page-level CPU throttle or a shimmed `navigator` value never reaches worker threads, so pin the browser to fewer cores at the operating system and force the tier with the game's own switch, then check the profile line the game logs. Print the machine's load and the throttle achieved beside every result, because milliseconds move with load and counts do not.
46
+ - **Reference configuration:** AW, at 1920 x 1080 on its high tier with 12 combatants under a 4x CPU throttle: p50 16.7 ms, p95 25.0 ms, p99 33.3 ms, long tasks 300 ms per 20 s, 700 draw calls, 900,000 triangles, 320 MB of textures, 160 MB of geometry, 200 MB of decoded audio, 4 MB/s of allocation. AW estimates 2x throttle is about an M1 Air's CPU and 4x pessimistic by design; the throttle does nothing to the GPU. OS runs its engine on worker threads, where the throttle never arrives: one capture held "10,297 polls/5,053 admissions/5,244 GPU skips", which withdrew every earlier median and p99. A 9.95 ms median against 6.44 ms of engine CPU and 6.67 ms of GPU was "roughly 3–5 ms waiting, not working". An OS pacer dropped to every third or fourth refresh "and holds there 8–120 s", and the owner felt it within hours. OS's weak-tier runs logged the full renderer and 32 GB of memory for days; a real weak boot froze for 13-16 s. LC counted four multiplayer pages at 56.9-57.3 fps by callbacks; they drew 17.4-18.5.
47
+ - **Applies when:** Every 3D game. Smaller games set smaller budgets, but the shape (tails, counts, one script, frames the engine ran) stays.
48
+ - **Verify:** On one capture, print callbacks against presented frames. Every receipt quotes the game's profile line (tier, renderer, pacing). The script fails when a map did not actually load (AW measured a grey stand-in arena under a map's name, and it looked faster than the truth).
44
49
 
45
50
  ### Every slow frame has an owner
46
51
  - **Invariant:** Frame time is split by system and by render pass, so every frame over budget names the system that made it slow, and only a small share of an ordinary frame is unattributed.
47
- - **Technique:** Wrap each system's update and each pass in a timer that writes into a rolling per-system histogram. On any frame over twice the median, log the top systems for that frame. Spread one-off heavy jobs (path searches, camera searches, spawning a set piece) over several frames instead of running them in one. Keep logging off the hot path, since writing log lines is a cost too. Three.js: `performance.now()` around each system, `renderer.info.render` per pass, and GPU timestamp queries (`EXT_disjoint_timer_query_webgl2` on WebGL 2, the `timestamp-query` feature on WebGPU) for passes.
48
- - **Reference configuration:** OC began with about 40% of the frame not broken out, and found spikes by parsing logs (1,096 frames over 25 ms in one session, the worst 159 ms) until its agents wrote a per-system profiler. Once timed, all game systems together cost 0.4-2.5 ms and the large items were the engine's update, render sync and audio mix (3.8-7 ms for 30-46 voices). Named fixes followed: ally pathing went from 18 calls to 1, a held-gun shader at 1.6-1.8 ms (28% of a combat frame) got a 0.4 ms target, and 13 log lines on one frame turned out to cause a hitch.
52
+ - **Technique:** Wrap each system's update and each pass in a timer that writes into a rolling per-system histogram. On any frame over twice the median, log the top systems for that frame. Spread one-off heavy jobs (path searches, camera searches, spawning a set piece, long rays) over several frames instead of running them in one. Keep logging off the hot path, since writing log lines is a cost too. Three.js: `performance.now()` around each system, `renderer.info.render` per pass, and GPU timestamp queries (`EXT_disjoint_timer_query_webgl2` on WebGL 2, the `timestamp-query` feature on WebGPU) for passes.
53
+ - **Reference configuration:** OC began with about 40% of the frame not broken out, and found spikes by parsing logs (1,096 frames over 25 ms in one session, the worst 159 ms) until its agents wrote a per-system profiler. Once timed, all game systems together cost 0.4-2.5 ms and the large items were the engine's update, render sync and audio mix (3.8-7 ms for 30-46 voices). Named fixes followed: ally pathing went from 18 calls to 1, a held-gun shader at 1.6-1.8 ms (28% of a combat frame) got a 0.4 ms target, and 13 log lines on one frame turned out to cause a hitch. OS's bot thinking was only 0.33 ms while fitting rifles against walls took 35% of CPU (then 12%); collision split by place went from 31.0 to 16.9 ms, and a body pinned on a dense rock from 178.5 to 3.9 ms. OS's 1.2 km rangefinder ray, cast in spans only while zoomed, went from a 123 ms peak to under 0.14 ms.
49
54
  - **Applies when:** Every game with more than a handful of systems, and always before anyone guesses at a cause.
50
55
  - **Verify:** Plant a busy-wait of known length in one system: the next slow-frame log names that system and the planted time. The per-system table for an ordinary frame sums to within a few percent of the measured frame.
51
56
 
52
- ### A verdict needs a quiet machine and an interleaved A/B
53
- - **Invariant:** A change is called faster or slower only from paired runs of both builds, alternated in one session on a machine with nothing else competing for it, with the competing load logged for every run.
54
- - **Technique:** Alternate A, B, A, B on the same scene, route, settings and pixel ratio. Warm up, then sample. Log other processes' CPU for each run by their full command line, and throw out runs where other work used a large share of the cores. Keep the browser at foreground priority. Drop frames that overlap a screenshot or a recording. When the measuring machine also builds and renders, book a quiet window for measurement and run nothing heavy in it.
55
- - **Reference configuration:** OC held R143 as a regression for a round: other Chrome processes were using 131%, 107% and 55% CPU. A background-priority daemon cut headless Chrome from 105 to 5.6 fps for about 4.5 h. OC's protocol: 30 s warm-up, 120 s sample, reject runs above about 50% of cores in competing use, and exclude frames that overlap a screenshot. Paired runs caught the R143 contention, and R159 was reverted after losing 6 of 9 pairs. See [references/measuring.md](references/measuring.md).
57
+ ### Timings come from a bare run: no read-back, and no hook that changes the game
58
+ - **Invariant:** Every millisecond reported (frame times, long tasks, press to play) comes from a run in which nothing reads the picture back and no test hook changes what the game does, with the machine's load written beside it.
59
+ - **Technique:** Split each sitting into a picture run (counts and frames only) and a bare run (the page's own timing rows, long tasks and landing times). Name the tool's own cost before blaming the game: a long task inside `toBlob`, `readPixels` or a screenshot is the tool's. The game never reads whether a capture or debug hook is attached, except hooks that declare themselves (a film, a stepped clock), and those change only what they declare. A profiled boot says which code is slow, not how long a boot takes. Measure presentation where the player's browser presents, on the hardware you promise and a real display: a virtual display can cost more than the game, and a software renderer (SwiftShader, llvmpipe) proves function only, never cost.
60
+ - **Reference configuration:** LC filed a BLOCKER that New run stood 1.3-3.2 s; it was the capture kit's read-back ("Of a press that stood 2,263 ms, 2,249 were the playtest kit's own frame reader"), and bare, the press took 232-354 ms. Another "game" long task was 5,031 of 5,048 ms inside `toBlob`. LC's engine skipped its frame-pacing rule whenever a capture hook was set, so four sittings saw 56-60 fps while the shipped default drew 4 fps (35 frames in 8 s) for the first 8 s of every run on a shared GPU. On OS's test machine, headed virtual-display presentation took about 46 ms a frame against about 4 ms of game GPU work, and running headless moved one map's p50 from 96 to 39 ms. An OS profiler read menu audio at a third of a core where the system's own process counters said 3.5%. OH's "60-120 fps on any computer" was never shown, because every measurement ran headless on a shared card; its SwiftShader runs at 20-23 fps proved function only.
61
+ - **Applies when:** Any game measured through captures, scripts or profilers, above all WebGPU on a shared GPU.
62
+ - **Verify:** Re-run a timed claim with the read-back off: if the number moves by more than its spread, the earlier number is void. Boot the same build with and without the test tool and diff the game's own per-frame decisions (pacing on, tier, clock source): identical.
63
+
64
+ ### A verdict needs a quiet machine and an interleaved A/B, and a shared GPU is measured by cost
65
+ - **Invariant:** A change is called faster or slower only from paired runs of both builds, alternated in one session on a machine with nothing else competing for it, with the competing load logged for every run; on a GPU shared with other work the verdict comes from measured cost, not frame rate, and an A/B whose content changed is void.
66
+ - **Technique:** Alternate A, B, A, B on the same scene, route, settings and pixel ratio, or toggle the change inside one page every half second, and where you can, split one frame's work between the two (half the bots each way) and time each half. Warm up, then sample. Log other processes' CPU for each run by their full command line, and throw out runs where other work used a large share of the cores. Keep the browser at foreground priority. Drop frames that overlap a screenshot or a recording. On a shared GPU, report per-pass GPU time from timestamp queries and per-section script time, and take the least frame as the cost; where timestamps are missing, a 1-pixel `readPixels` after a pass forces the GPU to finish and brackets that pass in a probe run, never in a run whose frame times are reported. Confirm with a draw and triangle count that both arms drew the same content. When the measuring machine also builds and renders, book a quiet window for measurement.
67
+ - **Reference configuration:** OC held R143 as a regression for a round: other Chrome processes were using 131%, 107% and 55% CPU. A background-priority daemon cut headless Chrome from 105 to 5.6 fps for about 4.5 h. OC's protocol: 30 s warm-up, 120 s sample, reject runs above about 50% of cores in competing use, and exclude frames that overlap a screenshot. Paired runs caught the R143 contention, and R159 was reverted after losing 6 of 9 pairs. LC's "427 to 71 draws" bundle was recorded while frustum-culled (triangles 2.05 to 0.45 M) and, done right, doubled GPU time; busy-machine "wins" of 26.2 against 32.5 ms read 18.4 against 18.2 on a quiet card ("The boots swing more than the ways differ"), and LC refuses readings at a load average over about 6. OH's same build read 2 ms and 21 ms minutes apart on a shared card. OS's windowed A/B read 13% less bot CPU and shipped for three releases; a same-frame split by bot slot showed 46% more, against a 20% noise floor. See [references/measuring.md](references/measuring.md).
56
68
  - **Applies when:** Every performance claim, most of all on a machine shared with builds, captures or other agents.
57
- - **Verify:** Run A against A first: the difference stays within noise. Then plant a known slowdown in B: the A/B flags it. Every run in the report lists its competing-CPU figure.
69
+ - **Verify:** Run A against A first: the difference stays within noise. Then plant a known slowdown in B: the A/B flags it. Every run in the report lists its competing-CPU figure and its draw count.
70
+
71
+ ### Measure the age of what the player sees, and pace frames by what lands
72
+ - **Invariant:** Frame-time and input claims are made from landed frames (the age of the picture on screen and of the input it carries, at the 95th percentile, measured beside a competing GPU load), and no frame is begun while two are unfinished and the oldest is already old.
73
+ - **Technique:** Learn when each frame's GPU work finishes (`device.queue.onSubmittedWorkDone()` on WebGPU, a `fenceSync` on WebGL 2). Hold the next frame, and carry its delta, while two frames are out and the oldest is past the limit. Run pacing and input-age checks beside a second uncapped page rendering on the same GPU on purpose, standing in for the screen recorder or stream a player runs; run cost A/Bs on a quiet machine. [helpers/landing-pacer.mjs](helpers/landing-pacer.mjs) holds frames and reports picture age. Camera input applied in the frame it is read is in `opengame-game-feel`.
74
+ - **Reference configuration:** LC beside a second browser: three.js's own pacing landed 40 fps, but each frame was 3.5-4.6 s old (p95 6.7-8.1 s) and growing; with the rule (two in flight, the oldest 50 ms), 20-28 fps at 38-45 ms old. On a quiet card the rule changed frame counts by under 2%; three or four in flight, a fixed divisor, or one in flight were all worse. LC's owner: "i was playing while recording with cap and it was very laggy but also liek my mouse sensitivity felt really slow"; the slow mouse was the old frame. A mouse-to-photon p95 under 100 ms needs about 40 landed fps with none over 60 ms; on a quiet card LC's frames are 11-12 ms old and the mouse 27-29 ms.
75
+ - **Applies when:** Every WebGPU game, and any game whose players record or stream while playing.
76
+ - **Verify:** Report p50 and p95 picture age and mouse-to-photon beside a second GPU load, A/B by turns in one page. The helper's test plants an unpaced loop and shows its age growing.
58
77
 
59
78
  ### Every number names the quality it ran at
60
- - **Invariant:** Adaptive quality never changes anything unseen: every frame-time number records the tier and render scale it ran at, benchmarks run with adaptation pinned, and a player's explicit choice is lowered only with a notice and never below an agreed floor.
61
- - **Technique:** Log each change of tier or render scale with its time and reason. Give benchmarks a flag that pins tier and scale. Show the effective tier in settings. Step down at most once, with a banner, outside menus and loading, and stop at the floor the owner agreed.
62
- - **Reference configuration:** OC's adaptive mode dropped render scale to 58% while its numbers were compared with fixed runs: one adaptive run read 119.4 fps average and 70.5 one-percent low beside a fixed combat run at 74 and 35. Its "Dynamic" mode lowered Ultra to Low or Medium while settings still said Ultra, and captures came out with 8 of 224 lights. The owner hit it 3 or more times ("Let's make Ultra the base... fall back to High, but not below"). The policy that held: one step from Ultra to High after 8 s at a GPU median above 17.5 ms, with a banner, never below High and never in menus.
79
+ - **Invariant:** Adaptive quality never changes anything unseen: every frame-time number records the tier, renderer and render scale it ran at, benchmarks run with adaptation pinned, and a player's explicit choice is lowered only with a notice and never below an agreed floor.
80
+ - **Technique:** The game logs the mode it actually took (tier, renderer, pacing, pixel ratio) at boot and on each change of tier or render scale, with its time and reason, and every receipt copies that line. Give benchmarks a flag that pins tier and scale. Show the effective tier in settings. Lower the tier the player chose at most once, with a banner, outside menus and loading, and stop at the floor the owner agreed; a resolution scaler inside the tier may step repeatedly, logging every step.
81
+ - **Reference configuration:** OC's adaptive mode dropped render scale to 58% while its numbers were compared with fixed runs: one adaptive run read 119.4 fps average and 70.5 one-percent low beside a fixed combat run at 74 and 35. Its "Dynamic" mode lowered Ultra to Low or Medium while settings still said Ultra, and captures came out with 8 of 224 lights. The owner hit it 3 or more times ("Let's make Ultra the base... fall back to High, but not below"). The policy that held: one step from Ultra to High after 8 s at a GPU median above 17.5 ms, with a banner, never below High and never in menus. OS's weak-tier runs used the full renderer for about two days, and five sets of "weak" numbers were relabelled.
63
82
  - **Applies when:** Every game with dynamic resolution or automatic tiers.
64
83
  - **Verify:** A benchmark report shows the tier and scale track for its whole run. A long session started on the top tier ends on it, or shows the banner and the logged reason.
65
84
 
66
85
  ### State is written only when it changes
67
86
  - **Invariant:** An update that leaves a value as it was does not write it, so nothing downstream re-uploads, re-syncs, re-sorts or re-lays out.
68
87
  - **Technique:** Compare before writing anything that marks state dirty, such as visibility, transforms, material parameters, uniforms, instance buffers and HUD text. Watch for APIs where asking for write access counts as a change even when no value moves. Three.js: set `visible`, `material.needsUpdate`, `texture.needsUpdate` and `instanceMatrix.needsUpdate` only on a real change; set `matrixAutoUpdate = false` on static objects and call `updateMatrix()` when they move; set DOM `textContent` only when the string differs.
69
- - **Reference configuration:** In OC, taking write access to a value marked it changed whether or not anything was written. A force field's per-frame write was behind the R159 hitches, and audits found about 20 such call sites. Comparing before writing cut main-thread CPU by 30% and frame spikes from 225 to 102 a minute.
88
+ - **Reference configuration:** In OC, taking write access to a value marked it changed whether or not anything was written. A force field's per-frame write was behind the R159 hitches, and audits found about 20 such call sites. Comparing before writing cut main-thread CPU by 30% and frame spikes from 225 to 102 a minute. LC put shared per-frame uniforms in one render group, taking GPU buffer writes from 1,211-1,240 (248 KB) a frame to 115-138 (55 KB).
70
89
  - **Applies when:** Every game, most of all one with many hidden or idle objects.
71
90
  - **Verify:** Count dirty marks and uploads per frame with the game idle in a menu: the count is zero. In combat, the count tracks what moved.
72
91
 
73
92
  ### Menus and previews draw only what changed
74
93
  - **Invariant:** A menu, pause screen or 3D preview costs what its motion needs: a still preview does not rewrite its scene every frame, and a menu holds the same floor as play.
75
- - **Technique:** Give menu scenes the same per-system timing as play. Rebuild a preview's scene only when its subject or camera changes, and write its visibility and materials on change. Draw the 3D preview at its own capped resolution, and stop rendering scenes that are fully covered. Measure menus in a headed browser at the display's native pixel ratio, since a headless run at pixel ratio 1 hides the cost. Three.js: render a preview into a small `WebGLRenderTarget`, call `renderer.render` for it only when a dirty flag is set, and `setAnimationLoop(null)` for scenes off screen.
76
- - **Reference configuration:** OC's owner measured a menu at 24 fps (p99 90 ms) and the main menu at 20 fps (p99 136 ms) on a Retina laptop while headless runs read 110-120. The owner had asked for menus at the play floor 3 or more times.
94
+ - **Technique:** Give menu scenes the same per-system timing as play. Rebuild a preview's scene only when its subject or camera changes, and write its visibility and materials on change. Draw the 3D preview at its own capped resolution, and stop rendering scenes that are fully covered. Behind a menu, turn off weather and haze and skip the expensive post passes. Measure menus in a headed browser at the display's native pixel ratio, since a headless run at pixel ratio 1 hides the cost. Three.js: render a preview into a small `WebGLRenderTarget`, call `renderer.render` for it only when a dirty flag is set, and `setAnimationLoop(null)` for scenes off screen.
95
+ - **Reference configuration:** OC's owner measured a menu at 24 fps (p99 90 ms) and the main menu at 20 fps (p99 136 ms) on a Retina laptop while headless runs read 110-120. The owner had asked for menus at the play floor 3 or more times. OS's live title world cost 174-283 ms of CPU a frame, so its menus now stand on a still (see `opengame-front-end`); behind a menu OS zeroes haze and rain and skips occlusion, reflections and bloom, taking GPU time from 2.49 to 1.55 ms.
77
96
  - **Applies when:** Every game with a 3D menu, loadout preview or character screen.
78
97
  - **Verify:** With the menu idle at native pixel ratio, the per-system table shows no scene rebuilds, and the one-percent low meets the play floor.
79
98
 
80
99
  ### Pixel ratio is capped by a pixel budget
81
100
  - **Invariant:** The number of pixels drawn is chosen from a budget in device pixels, so a high-density display does not multiply the GPU cost of the frame.
82
- - **Technique:** Choose the pixel ratio from a target pixel count in device pixels rather than CSS size, and run full-screen post at the internal resolution. Apply the cap before the first frame. Three.js: `renderer.setPixelRatio(Math.min(devicePixelRatio, cap))`, and check the result against `renderer.domElement.width * height` (or `drawingBufferWidth` on the context).
83
- - **Reference configuration:** At pixel ratio 2, OC's menu GPU time was 22.6 ms, of which the 3D was about 2 ms; the rest was full-resolution post. A cap written in CSS pixels never applied (17.6 fps) and shipped for 14 h before the fix. Ultra drew 2x the pixels on Retina, and the phone menu drew 3.4x the pixels of the run.
101
+ - **Technique:** Choose the pixel ratio from a target pixel count in device pixels rather than CSS size, and run full-screen post at the internal resolution. Apply the cap before the first frame. On a 4K display, draw the scene at a lower internal size under native-resolution interface. Three.js: `renderer.setPixelRatio(Math.min(devicePixelRatio, cap))`, and check the result against `renderer.domElement.width * height` (or `drawingBufferWidth` on the context).
102
+ - **Reference configuration:** At pixel ratio 2, OC's menu GPU time was 22.6 ms, of which the 3D was about 2 ms; the rest was full-resolution post. A cap written in CSS pixels never applied (17.6 fps) and shipped for 14 h before the fix. Ultra drew 2x the pixels on Retina, and the phone menu drew 3.4x the pixels of the run. LC's scene pass costs 4.65 ms at 1080p High, about 9 ms as a 1440p scene under 4K output and about 18 ms at native 4K, so its Ultra draws a 1440p scene and native 4K is opt-in. OS's 0.85 scale on a 1.25 pixel-ratio cap stretched the frame 1.6x, so OS starts at native pixel ratio.
84
103
  - **Applies when:** Every game that runs on Retina laptops, 4K monitors or phones.
85
104
  - **Verify:** Log the drawing-buffer size on a high-density display at every screen: it stays at or under the budget, and the frame time matches the same size at pixel ratio 1.
86
105
 
87
- ### Nothing compiles during play
88
- - **Invariant:** No shader program links after the loading cover lifts.
89
- - **Technique:** Prewarm every material through the same render target, colour space and cameras the frame really uses, under an opaque fade, and keep the light count fixed (see `opengame-lighting`). A prewarm through the canvas compiles the wrong variant when the world draws into a linear target. Prewarm first-use effects and sounds the round before they appear, not on the frame they first play.
90
- - **Reference configuration:** AW's prewarm ran with no target bound and compiled the sRGB variant of every material while every real frame drew into a linear target; nothing it compiled was used. Fixed, the countdown went from 16 long tasks totalling 3,607 ms to none, and programs linking after the veil from 10 to 0. OC: a quality switch that recompiled pipelines hitched for about 10 s (worst frame 48.7 ms), so it prewarms boss effects and sounds the round before and builds the death and results screens ahead of time.
91
- - **Applies when:** Every three.js game with more than a handful of materials.
92
- - **Verify:** Count `renderer.info.programs.length` when the loading cover lifts and again after the first fight; it does not change.
93
-
94
- ### Statics merged, repeats instanced
95
- - **Invariant:** Draw calls scale with the number of materials, not the number of objects.
96
- - **Technique:** Merge static geometry per material, instance repeated props in spatial chunks with level of detail and hysteresis, and check that skinned and instanced bounds are right so culling does not remove visible things.
97
- - **Reference configuration:** DK draws its props in about 9 calls; MC's Rust map in 24. AW gives one map's own geometry a budget of 44 draws inside the 700. OC's arena drew about 6,190 separate objects with none grouped, and cutting resolution by 60% saved only 16% of the frame.
98
- - **Applies when:** Every scene with many static objects.
99
- - **Verify:** Read `renderer.info.render.calls` with the busiest view on screen.
106
+ ### Nothing compiles during play: a fixed light set, and every pass warmed
107
+ - **Invariant:** No shader or pipeline is built on a frame the player sees, through any render pass, and the count of pipelines first built after the first shown frame is zero.
108
+ - **Technique:** Create every light at boot (at zero intensity until it is needed) and never add or remove lights, or toggle a light's `visible` or `castShadow`, in play, because the light set is part of the shader key. Put every mesh and material variant play can draw into the scene by ready, hidden if need be, and give late joiners pre-built material slots. Warm by drawing each new thing once off screen with culling off and every light state lit, through the same render target, colour space and camera the real frame uses, and through every pass (shadows, post, a scope), since a canvas-only compile misses the rest. Warm one unbuilt material per slice, keep warm frames out of auto exposure, and give every system a prewarm hook for its play-time materials. Materials that differ only in values share one compiled graph ([references/webgpu.md](references/webgpu.md)). Prewarm first-use effects and sounds the round before they appear, and keep the light count fixed (see `opengame-lighting`).
109
+ - **Reference configuration:** AW's prewarm ran with no target bound and compiled the sRGB variant of every material while every real frame drew into a linear target; nothing it compiled was used. Fixed, the countdown went from 16 long tasks totalling 3,607 ms to none, and programs linking after the veil from 10 to 0. OC: a quality switch that recompiled pipelines hitched for about 10 s (worst frame 48.7 ms), so it prewarms boss effects and sounds the round before and builds the death and results screens ahead of time. LC creates a hemisphere, a fill, lightning, a spot, 2 flashes and 3 lamps at boot, loads hero weapons into 8 pre-built slots plus 4 for racks, and in its first phase read 0 late pipelines in 37 captures; `compileAsync` covered only its canvas pass, and warm frames fed the exposure meter and blacked the title. One LC graph costs 20-700 ms of main thread wherever it is built; a first-use upgrade material was a 120-180 ms frame, and 33 ms once warmed; a warm slice of 48 things stood 1.2-2.1 s. By the end of its second phase LC built 9 pipelines after the first shown frame, against a target of 0.
110
+ - **Applies when:** Every three.js game with more than a handful of materials, and any engine whose shader key includes lights.
111
+ - **Verify:** Count programs (`renderer.info.programs.length` on WebGL, a counter on pipeline creation on WebGPU) when the loading cover lifts and again after a minute that includes the first reload, enemy, effect and upgrade: it does not change.
112
+
113
+ ### Count draws per pass at fixed bookmarks, because draws usually bound a three.js WebGPU frame
114
+ - **Invariant:** Every capture counts draws per pass, triangles and shadow casters by owner at fixed bookmarks, and no commit raises them past their budget.
115
+ - **Technique:** In three.js on WebGPU, main-thread draw submission usually limits the frame before triangles or pixels do, but full-resolution post or a native 4K scene can make pixels the limit (the pixel budget rule), so confirm which by cutting draws and watching the frame move. Count draws in game, by system, at fixed camera bookmarks on every tour, printed with an OVER BUDGET flag. One material per surface family, with variation in vertex attributes or texture arrays; one mesh per material per district; lamps as unlit meshes where they need not light; small things cast no shadow; shadow proxies for heavy casters; far ground as one mesh. Count a batching plan offline before building it, and count both the scene and shadow passes, because a merge that saves scene draws can add shadow draws.
116
+ - **Reference configuration:** LC: each draw costs 15-40 µs of main thread per pass (25-31 µs measured first), so about 150 draws in view at 120 fps: "THE CARD IS NOT THE LIMIT; THE MAIN THREAD IS". Turning shadows or rain off bought nothing, and halving pixels took a pass only from 35.6 to 32.5 ms. LC's budgets: 150 draws (world 60, enemies 24, view model 12, movers 30, engine 8), 60 shadow draws, 2.5 M triangles, 700 MB of textures and 3 ms of script; the frame went from 277 to 73-82 draws and the scene pass from 11.7 to 4.4 ms, and the world held at 39-62 draws and 0.84-1.40 M triangles over 24 bookmarks. OS: each shadow caster costs about 5x through four cascades.
117
+ - **Applies when:** Every 3D browser game; most of all three.js on WebGPU, where per-draw CPU cost dominates.
118
+ - **Verify:** Print the counts at each bookmark per build and fail on a rise. Cut 25 draws at a heavy bookmark: the frame time moves.
119
+
120
+ ### Statics merged, repeats instanced, crowds on the GPU
121
+ - **Invariant:** Draw calls scale with the number of materials, not the number of objects, and scattered props and crowds draw in a handful of instanced draws whose per-copy data lives on the GPU.
122
+ - **Technique:** Merge static geometry per material, instance repeated props in spatial chunks with level of detail and hysteresis, and check that skinned and instanced bounds are right so culling does not remove visible things. For clutter, keep copy matrices in a texture and draw a list of copies in the view cone plus everything near, refilled after a set walk or turn. For crowds, one bone texture for all slots, uploaded on change and read in the vertex stage so shadows carry the pose, one instanced draw per kind per level of detail, full meshes only for the nearest few, and characters' levels of detail chosen by their height on screen.
123
+ - **Reference configuration:** DK draws its props in about 9 calls; MC's Rust map in 24. AW gives one map's own geometry a budget of 44 draws inside the 700. OC's arena drew about 6,190 separate objects with none grouped, and cutting resolution by 60% saved only 16% of the frame. LC's litter: 9,018 things from 346 baked squares and 122 MB of buffers to 2.6 MB in at most 10 draws, listing copies within 80 degrees plus all within 7 m, refilled every 2 m or 12 degrees. LC's zombies: a 46 KB bone texture, at most 27 draws, the nearest 5 within 8 m drawn full; 32 of them cost 0.50 ms. OS: "Thinning instances buys nothing", since a draw is a species by level-of-detail bucket; avatar levels at 0.30, 0.10 and 0.035 of screen height took a full lobby from 3.06 M to 1.26 M triangles.
124
+ - **Applies when:** Every scene with many static objects, hundreds of props or tens of skinned characters.
125
+ - **Verify:** Read `renderer.info.render.calls` with the busiest view on screen, and ms, draws and triangles at 9, 23 and 32 characters.
100
126
 
101
127
  ### Textures by measurement, one decode per image
102
- - **Invariant:** Every image is fetched, decoded and uploaded once however many materials use it, and its GPU format was chosen by measuring size and quality.
103
- - **Technique:** Cache textures by URL and hand out clones that share the source; register only the original for disposal. Encode KTX2 per texture class after measuring bytes on the wire, GPU residency and quality on the real surface, with a fallback to the original image when the transcoder or device cannot do it.
104
- - **Reference configuration:** AW: sharing sources took GPU residency from 492.1 MB to 440.3 MB; 65% of its texture memory was loaded images, the only part KTX2 can reach. AW measured ETC1S with its normal-map mode at no extra cost for normals where UASTC cost about six times the bytes, and chose ETC1S throughout; SR encodes character textures as full-resolution UASTC.
128
+ - **Invariant:** Every image is fetched, decoded and uploaded once however many materials use it, and its GPU format was chosen by measuring size and quality for its role.
129
+ - **Technique:** Cache textures by URL and hand out clones that share the source; register only the original for disposal. Encode KTX2 per texture role after measuring bytes on the wire, GPU residency and quality on the real surface, with a fallback to the original image when the transcoder or device cannot do it. Decoding off the main thread is in `opengame-loading`.
130
+ - **Reference configuration:** AW: sharing sources took GPU residency from 492.1 MB to 440.3 MB; 65% of its texture memory was loaded images, the only part KTX2 can reach. AW measured ETC1S with its normal-map mode at no extra cost for normals where UASTC cost about six times the bytes, and chose ETC1S throughout; SR encodes character textures as full-resolution UASTC. LC chose ETC1S for colour and UASTC for normals and data, taking world textures on the card from 800.7 MB to 172 MB; its WebP sheets were "56 MB decoded for 2 MB on the wire", and each 4096 x 2048 finish texture took 33.6 MB on the card.
105
131
  - **Applies when:** Every textured game. Measure by `Texture.source`, not by texture objects, or a working cache looks like a failed fix.
106
132
  - **Verify:** Count distinct sources and sum their bytes at runtime; KTX2 statistics report how many loaded compressed and how many fell back.
107
133
 
108
- ### Resolution scales before content does
109
- - **Invariant:** When the GPU cannot keep up, the game lowers render resolution smoothly and raises it again only when it is clearly safe, without oscillating.
110
- - **Technique:** Measure missed presentations against the display's real period, require several agreeing checks to change, a longer dwell before raising after a drop, and a cooldown after any change. Lowering resolution cannot fix a CPU stall, so do not use it to hide one. Log every change (see the rule on naming the quality a number ran at).
111
- - **Reference configuration:** AW checks every 2 s, waits 8 s after any change and 20 s after a drop before raising, drops on 2 agreeing votes and raises on 4, drops by 0.15 and raises by 0.1, treating more than 5% missed frames as stutter and under 1% as clean.
112
- - **Applies when:** 3D games that must run across very different GPUs.
113
- - **Verify:** Log the scale over a long busy session on a slow machine: it settles rather than bouncing.
114
-
115
- ### Quality tiers that keep the look
116
- - **Invariant:** The lowest tier still reads as the same game, and every tier stays inside its budget.
117
- - **Technique:** Tiers drop expensive passes in order (occlusion, then volumetrics, then bloom and multisampling), cap device pixel ratio and shadow resolution, and shrink the light pool. Never change collision, input or what the player can see of a threat.
118
- - **Reference configuration:** DK's low tier drops occlusion, volumetrics, motion blur, depth of field and reflections and keeps bloom and FXAA. The ST starter drops occlusion, then bloom and multisampling.
134
+ ### Large uploads go through mapped buffers in small pieces, never in a press or a turn
135
+ - **Invariant:** No large texture or buffer write runs while the GPU process is behind, in the task of a key press, in a run's first frame or while the mouse is turning, and no single write is larger than the browser's staging can take without holding on to it.
136
+ - **Technique:** Send compressed texture levels through a buffer mapped at creation plus `copyBufferToTexture`, and images with `copyExternalImageToTexture`, rather than `writeTexture` and `writeBuffer`. Send one texture a frame, and split any upload into writes of a few megabytes. Pause late uploads in any frame where the mouse moved just before, with a cap so nothing starves. For data textures, send only the changed box. [references/webgpu.md](references/webgpu.md) says why.
137
+ - **Reference configuration:** Chromium puts `writeTexture` and `writeBuffer` bytes in one per-page transfer ring, and a call that needs more room than is free blocks the main thread until the GPU process drains. With the GPU process over 300 ms behind (another program on the GPU), LC's 1 MB `writeTexture` stood over 8 ms in 9 of 32 calls (worst 1,626 ms), mapped buffers 1 of 30 (56 ms), `copyExternalImageToTexture` 0 of 31; LC's sends over 50 ms went from 316 of 1,666 to 2 of 2,589, proved lossless by copying 1,904 levels back. A quarter-megabyte write had frozen the page 474 ms: "the cost is the call waiting on the busy card, not the size". LC pauses late work for 0.2 s after the mouse moves. OS found Chrome keeping a staging block sized to any write over 4 MB for the page's life; 4 MB chunks took shared memory from 871 to 187 MB and 45-minute renderer growth from 1,055 to 433 MB.
138
+ - **Applies when:** WebGPU games that stream textures or geometry after load, and any game whose players run a recorder or a second GPU program.
139
+ - **Verify:** Wrap the upload calls and log any that stand 8 ms or more, beside a second GPU-heavy page. Track the renderer and GPU processes' memory through a long session (the memory rule).
140
+
141
+ ### Quality steps down the world first, never the gameplay layer, and each step must pay
142
+ - **Invariant:** When the frame cannot keep up, the game lowers cost in a fixed order, world effects and world resolution before the layer the player acts on (the board, the reticle, the held weapon, the HUD); each step is kept only if it bought time, the game climbs back slowly without oscillating, and no step causes a hitch the player sees.
143
+ - **Technique:** Detect the display's refresh. Judge in short windows against the display's real period, require several agreeing windows to drop, undo a step that did not buy enough, and climb only after a long dwell with time to spare. Ignore loading and stalls. Never trade pixels while GPU time is well under budget, since the CPU or another program is then the limit, and lowering resolution cannot fix a CPU stall. Where reallocating render targets hitches, step only at a cut (a death, a killcam, a round end), as a few fixed steps rather than a continuously varying scale. Log every change (see the rule on naming the quality a number ran at).
144
+ - **Reference configuration:** AW checks every 2 s, waits 8 s after any change and 20 s after a drop before raising, drops on 2 agreeing votes and raises on 4, drops by 0.15 and raises by 0.1, treating more than 5% missed frames as stutter and under 1% as clean. OH lowers world scale (floor 0.5), multisampling, post taps and stroke density (floor 0.45), and the canvas ratio last (floor 0.6), so its board keeps full resolution until that last step; it drops after 3 windows of 0.5 s under 0.86x of target, undoes a step that gained under 8% and bars it for 90 s, and climbs after 8 windows and 20 s. LC lowers its effects tier first, then pixels in steps of 1/16 to a floor of 0.75, gives back a step that bought under a tenth (tier) or a quarter (pixels), and had walked to 0.75 under other programs' load for nothing before it stopped trading pixels while GPU time was under half the budget. OS measured each render-target reallocation as a 75-150 ms hitch (a scale change at scope-in re-created 46-70 textures and 250-450 bind groups), so it dropped continuous scaling in a match for one announced Ultra-to-High step at a killcam after the Ultra GPU median exceeded 9.2 ms for 8 s. This narrows AW's smooth scaler to engines where a resize is cheap. LC's owner saw the scaler stuck at 640x360: "why is the resolution so low btw?"; OS's owner felt the reallocation: "frame would halt for a few frames righ tbefore zoom in".
145
+ - **Applies when:** 3D games that must run across very different GPUs, and any frame-rate target promised on any machine.
146
+ - **Verify:** Force each step in a recording: no blank or hitched frame at the change, and the gameplay layer stays sharp until the last step. Log the scale over a long busy session on a slow machine: it settles rather than bouncing.
147
+
148
+ ### Quality tiers that keep the look, and keep the game fair
149
+ - **Invariant:** The lowest tier still reads as the same game, every tier stays inside its budget, and no tier changes what cover hides or what a player can see of a threat.
150
+ - **Technique:** Tiers drop expensive passes in order (occlusion, then volumetrics, then bloom and multisampling), cap device pixel ratio and shadow resolution, and shrink the light pool. Never change collision, input or what the player can see of a threat. Tiers move level-of-detail switch distances, never cull ranges, and keep foliage that hides players at its full distance on every tier.
151
+ - **Reference configuration:** DK's low tier drops occlusion, volumetrics, motion blur, depth of field and reflections and keeps bloom and FXAA. The ST starter drops occlusion, then bloom and multisampling. LC's tiers: Low 720p with FXAA and a 1024 shadow map every third frame; Medium 1080p with 4x MSAA and 1024 every second frame; High 1440p, 4x, 2048 every second frame; Ultra 1440p with shadows every frame. An OS low tier that thinned tree crowns let "a weak-machine player see through cover that hides players on normal machines", so its trees stay at Ultra distances on every tier.
119
152
  - **Applies when:** Every game with post or many lights.
120
- - **Verify:** Capture the same view at every tier and measure each against the budget.
153
+ - **Verify:** Capture the same view at every tier and measure each against the budget. In a shooter, A/B cover, sightlines and doors between the lowest and highest tier: identical.
121
154
 
122
155
  ### Nothing allocates per frame
123
156
  - **Invariant:** An ordinary frame of play allocates nothing, so the garbage collector does not cut a sawtooth through the frame times.
124
- - **Technique:** Reuse scratch vectors and matrices, fixed particle pools and ring buffers for decals, tracers and casings; update the HUD on change, not every frame; avoid layout reads in the hot path.
125
- - **Reference configuration:** DK's pools: 900 smoke and 900 spark particles. AW budgets 4 MB/s of allocation during play; above it the collector runs every second.
157
+ - **Technique:** Reuse scratch vectors and matrices, fixed particle pools and ring buffers for decals, tracers and casings; update the HUD on change, not every frame; avoid layout reads in the hot path. When the allocation rate is higher than the code suggests, trace it with the engine's own flags, since the JIT can box numbers the source never allocates.
158
+ - **Reference configuration:** DK's pools: 900 smoke and 900 spark particles. AW budgets 4 MB/s of allocation during play; above it the collector runs every second. An LC fight made 6.2-6.9 MB/s of garbage (596 MB in 50 s), and V8's optimiser was boxing 91 KB a frame where 6.9 KB was expected.
126
159
  - **Applies when:** Every game.
127
160
  - **Verify:** An allocation profile of a busy minute shows a flat heap and names no per-frame allocation site in game code.
128
161
 
129
- ### Loading pays only for what is needed
130
- - **Invariant:** The menu appears quickly, a returning player downloads almost nothing, and nothing cosmetic downloads during a countdown or the first seconds of play.
131
- - **Technique:** Bundle the boot tier, preload only what the first actionable scene needs, stage the rest after play starts, and serve with validators so unchanged files are not re-sent. The full set of loading rules is in `opengame-loading`.
132
- - **Reference configuration:** AW: time to menu 1,500 ms and under 4 MB fetched before the menu; a repeat visit dropped from 34.36 MB to 0.39 MB once its server sent `no-cache` with an ETag instead of `no-store`. Moving a 2.70 MB model prewarm out of the countdown took countdown downloads from 3.02 MB to 0.32 MB.
162
+ ### Memory stays flat over a long session, counted for the whole tab at its peak
163
+ - **Invariant:** Over hours of play with map or level switches, the renderer, GPU-process and browser memory stay near flat, the peak meets the budget, and frame time per minute does not drift.
164
+ - **Technique:** Sample each browser process (renderer, GPU process, browser) at a steady interval beside the game's own allocator counts, and budget the whole tab at its peak, since WebAssembly memory never shrinks. Split uploads into small writes (the upload rule). Release the old map before the next streams in. Free CPU copies only where nothing re-reads them (see `opengame-mobile`). Size engine pools for a full match, not a short test. Cap Cache Storage, since a private window keeps it in memory.
165
+ - **Reference configuration:** OS's owner: "like 300-400mB max ... play this game for hours / nonstop without it ever crashing" and "it starts high fps but as i play more fps just drops". OS's wasm heap stayed flat while the renderer process grew 1,444 MB in 9.5 min; split uploads took 45-minute renderer growth from 1,055 to 433 MB against a 300 MB bar, freeing texture copies crashed decals "after about a minute", and the best OS reached was a flat 959 MB over six loads, against a tab of 1.6-2.9 GB. Five OS sessions of up to 46 min showed no frame-time drift, on a test machine that ran about 13x fewer frames than the owner's, so the owner's drift stayed unexplained. LC's heap rose about 18 MB a minute in every run, with 780 MB on the card against a 700 MB budget. OH grows about 8.7 MB of heap a song, still open at launch. OS caps Cache Storage at 512 MB.
166
+ - **Applies when:** Browser and wasm games with long sessions.
167
+ - **Verify:** A 45-60 min session in one page, switching maps every 5 min, with per-minute counters per process: growth from the first sample stays under the bar, and the last block's frame time matches the first.
168
+
169
+ ### Play downloads nothing, and a countdown warms only what the first match draws
170
+ - **Invariant:** The menu appears quickly, a returning player downloads almost nothing, the first seconds of play download nothing, and a countdown fetches only what the first match will draw, once the map is fully shown.
171
+ - **Technique:** Bundle the boot tier, preload only what the first actionable scene needs, stage the rest behind the menu and the lobby, and serve with validators so unchanged files are not re-sent. In a countdown, warm the first match's sets only after the map passes its shown gate, and move everything else out. The full set of loading rules, including the shown gate, is in `opengame-loading`.
172
+ - **Reference configuration:** AW: time to menu 1,500 ms and under 4 MB fetched before the menu; a repeat visit dropped from 34.36 MB to 0.39 MB once its server sent `no-cache` with an ETag instead of `no-store`. Moving a 2.70 MB model prewarm out of the countdown took countdown downloads from 3.02 MB to 0.32 MB. OS warms its first match's 19.6 MB of streak art in the countdown after the map is shown, and its first minute of play went from 41.5 MB to 0.0-0.2 MB; warming before the map was shown had doubled the hold. This narrows AW's version, which kept the countdown nearly empty: both keep play free of downloads, and a countdown may warm once its map is done.
133
173
  - **Applies when:** Every game, most of all large 3D ones.
134
- - **Verify:** A network waterfall bucketed by phase: boot, menu, countdown, first seconds of play.
174
+ - **Verify:** A network waterfall bucketed by phase (boot, menu, lobby and countdown, first minute of play): play is empty, and countdown requests start after the shown gate and belong to the first match.
135
175
 
136
176
  ## Further reading
137
177
 
138
- What AW's measurement script got wrong before it was trusted, and how contention on a
139
- shared machine made OC chase a regression that did not exist:
140
- [references/measuring.md](references/measuring.md).
178
+ What AW's measurement script got wrong before it was trusted, how contention on a shared
179
+ machine made OC chase a regression that did not exist, and how OS and LC counted frames
180
+ that never reached the screen: [references/measuring.md](references/measuring.md).
181
+ three.js WebGPU specifics: [references/webgpu.md](references/webgpu.md).
@@ -0,0 +1,86 @@
1
+ /**
2
+ * Pace frames by when they land on the GPU, not by when they were begun. Copy this file
3
+ * into the game; it imports nothing. On a GPU shared with another program (a screen
4
+ * recorder, a second browser), the browser keeps handing out animation frames while the
5
+ * GPU falls behind, so frames begun are not frames seen and each picture reaches the
6
+ * screen older than the last. This holds the next frame while too much is in flight, and
7
+ * records the age of every frame that lands, which is the number a player feels.
8
+ *
9
+ * import { createLandingPacer } from "./landing-pacer.mjs";
10
+ *
11
+ * const pacer = createLandingPacer(); // two in flight, 50 ms oldest
12
+ * renderer.setAnimationLoop((t) => {
13
+ * if (!pacer.canBegin()) return; // skip; carry the time to the next frame
14
+ * const dt = pacer.begin(); // seconds since the last begun frame
15
+ * update(dt);
16
+ * renderer.render(scene, camera);
17
+ * pacer.submitted(renderer.backend.device.queue.onSubmittedWorkDone());
18
+ * });
19
+ * pacer.stats(); // { landed, p50, p95 } picture age in ms
20
+ *
21
+ * Measured on Last Contact beside a second uncapped browser on the same GPU: unpaced, 40
22
+ * frames a second landed, each 3.5-4.6 s old; paced, 20-28 a second, 38-45 ms old. On a
23
+ * quiet GPU the pacer changed frame counts by under 2%.
24
+ */
25
+
26
+ export function createLandingPacer({
27
+ maxInFlight = 2,
28
+ maxAgeMs = 50,
29
+ keep = 600,
30
+ now = () => (typeof performance !== "undefined" ? performance.now() : Date.now()),
31
+ } = {}) {
32
+ const inFlight = []; // begin times of frames submitted and not yet landed, oldest first
33
+ const ages = [];
34
+ let lastBegin = null;
35
+ let pending = null; // begin time of a frame begun but not yet submitted
36
+ let held = 0;
37
+ let failed = 0;
38
+
39
+ /** False while maxInFlight frames are out and the oldest is at least maxAgeMs old. */
40
+ function canBegin() {
41
+ if (inFlight.length < maxInFlight) return true;
42
+ const ok = now() - inFlight[0] < maxAgeMs;
43
+ if (!ok) held++;
44
+ return ok;
45
+ }
46
+
47
+ /** Mark a frame as begun; returns seconds since the last begun frame, so held time is carried. */
48
+ function begin() {
49
+ const t = now();
50
+ const dt = lastBegin === null ? 0 : (t - lastBegin) / 1000;
51
+ lastBegin = t;
52
+ pending = t;
53
+ return dt;
54
+ }
55
+
56
+ /** Pass the promise that resolves when this frame's GPU work is done. */
57
+ function submitted(landed) {
58
+ const started = pending ?? now();
59
+ pending = null;
60
+ inFlight.push(started);
61
+ const settle = () => {
62
+ const index = inFlight.indexOf(started);
63
+ if (index >= 0) inFlight.splice(index, 1);
64
+ };
65
+ // A frame whose promise rejects (a lost device, a failed submit) still leaves the
66
+ // queue, or two failures would hold every later frame. It records no age, because
67
+ // nothing landed, and is counted apart.
68
+ Promise.resolve(landed).then(() => {
69
+ settle();
70
+ ages.push(now() - started);
71
+ if (ages.length > keep) ages.shift();
72
+ }, () => { settle(); failed++; });
73
+ }
74
+
75
+ function percentile(sorted, p) {
76
+ if (!sorted.length) return null;
77
+ return sorted[Math.min(sorted.length - 1, Math.floor(p * sorted.length))];
78
+ }
79
+
80
+ function stats() {
81
+ const sorted = [...ages].sort((a, b) => a - b);
82
+ return { landed: ages.length, inFlight: inFlight.length, held, failed, p50: percentile(sorted, 0.5), p95: percentile(sorted, 0.95) };
83
+ }
84
+
85
+ return { canBegin, begin, submitted, stats };
86
+ }