@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,283 @@
1
+ > Carried from `opengame-sdk` 1.0.13. Read it when: Integrate a browser game with OpenGame through @opengamehq/sdk, the injected global or a native engine bridge. Covers start-up, the player and their OG at load, names, leaderboards, achievements, events, pause, mute, fullscreen, keys inside the frame and threaded builds. Use when the person says integrate with OpenGame, add the SDK, show the player's name or OG, add a leaderboard or achievement, track events, fix fullscreen or keys in the game frame, or asks how a game talks to OpenGame.
2
+
3
+
4
+ # Integrate a game with OpenGame
5
+
6
+ Inside an OpenGame page the SDK works as described here. Under `opengame dev` it runs a
7
+ local stand-in that keeps scores and events in the browser. Any signed-in account can deploy
8
+ now. Until 18 November, a CLI with no login hears
9
+ "OpenGame opens for creators on 18 November." Sign in with `opengame login` first.
10
+
11
+ The SDK is what ends up inside the game. It talks only to the OpenGame page around
12
+ the game and to `https://api.opengame.gg`.
13
+ The game never holds a key, never
14
+ sees an email and never talks to opengame.io. Four rules shape every call:
15
+
16
+ 1. **Nothing is required.** A game that calls nothing still runs. A game that calls
17
+ everything still runs outside OpenGame and when the platform is down.
18
+ 2. **The page brokers, the game asks.** Identity and sessions arrive
19
+ from the page over `postMessage`. The SDK accepts messages only from its exact
20
+ parent window on a trusted origin.
21
+ 3. **Every number a game reports is the game's claim.** Scores, achievements and
22
+ events are labelled as the game's and never decide anything that matters.
23
+ 4. **Check before offering a feature.** `og.capabilities` lists what this page offers
24
+ this game today.
25
+
26
+ ## Take API facts from the installed SDK
27
+
28
+ This skill holds the practices. The SDK package holds the API for its own version, so
29
+ read the copy the game will ship before writing a call:
30
+
31
+ - `node_modules/@opengamehq/sdk/README.md`: the full reference, including the bridge
32
+ operations and every result shape.
33
+ - `node_modules/@opengamehq/sdk/AGENTS.md`: the short rules and the error catalogue,
34
+ generated from the SDK's own error table.
35
+ - `node_modules/@opengamehq/sdk/dist/*.d.ts`: the exact signatures.
36
+ - With no package to hand, the SDK reference (`https://docs.opengame.io/reference/sdk`).
37
+
38
+ Never guess a name. A call that is not in that README does not exist in that version.
39
+ Where this skill and the installed README disagree, follow the README and tell the
40
+ OpenGame team which line here is wrong.
41
+
42
+ ## Choose how the SDK reaches the game
43
+
44
+ | The game | Load it | Then `og` is |
45
+ | --- | --- | --- |
46
+ | Bundled JavaScript | `import { og } from '@opengamehq/sdk'` | the import |
47
+ | No build step | copy `dist/opengame.js` beside the game, in a `<script>` before the game's own | `OpenGame.og` |
48
+ | Already ships `js/og-platform.js` (Studio template, our Originals) | replace that file with the SDK's `dist/og-platform.js` | its `og` export |
49
+ | A native engine (WebAssembly, Kaigen, Unity, Godot) | `OpenGame.bridge`, called from the main thread | the bridge's operations |
50
+
51
+ Ship the SDK with the game rather than loading it from a CDN, so an outage cannot take it
52
+ away.
53
+
54
+ ```bash
55
+ npm i @opengamehq/sdk
56
+ ```
57
+
58
+ Some runtime contracts add the full global at `/_og/sdk.js` to the
59
+ game's pages themselves. How each path works, and what happens when a game ships its
60
+ own copy as well: [references/engines.md](references/engines.md).
61
+
62
+ ## Start, and give the player their identity at load
63
+
64
+ ```js
65
+ import { og } from '@opengamehq/sdk'
66
+ import { watchAvatar } from '@opengamehq/sdk/avatar'
67
+
68
+ const started = og.init() // outside a frame at once; inside one within 4 seconds, longer while the page checks who is playing
69
+ watchAvatar(og, avatar => avatar ? buildYourOg(avatar) : useDefaultCharacter()) // start the build now
70
+ og.player.onChange(fillNames) // the handle, or the game's default: the name rule below
71
+ await loadEngineAndAssets() // the player usually arrives during this
72
+ await started
73
+ og.ready() // once, on the first frame the player can act in
74
+ ```
75
+
76
+ - Call `og.init()` first, before the engine or the heavy assets, and do not block
77
+ loading on it: it never rejects. Outside any frame it resolves straight away with
78
+ `og.env.connected === false`; inside a frame that is not OpenGame it waits the full
79
+ handshake first.
80
+ - The page answers the first message with the player, their OG and their outfit while
81
+ the game is still under its loading screen. Use them then. Start building "Your OG"
82
+ and fill the name at load, and wear the result when the menu opens.
83
+ - Call `og.ready()` on the **first playable frame**, not when the page loads and not
84
+ behind a click-to-start overlay that the player has not seen yet.
85
+ - `og.env` is `{ embedded, connected, preview, sdkVersion, capabilities }`.
86
+ `preview` is true on the owner's private preview.
87
+
88
+ Who the player is in each situation, the private rollout and the early handshake:
89
+ [references/identity.md](references/identity.md).
90
+
91
+ ## Rules, most damaging first
92
+
93
+ **CRITICAL: the player is applied at load, not after the menu.** Wrong: waiting for
94
+ the title screen to read `og.player` or start building the OG. Right: subscribe right
95
+ after `og.init()` and build in the background; only the swap into the scene waits for
96
+ a menu. OG Clash showed its default character on the first menu, and "Your OG" turned
97
+ up most of a minute later, until it started the build under the loading screen.
98
+
99
+ **CRITICAL: the game never waits on the platform.** Core, board and achievement calls
100
+ answer `{ ok: true, value }` or `{ ok: false, error }` (boards add a `reason`).
101
+ The game keeps playing on every one of them. Review runs offline and previews have no identity, so a menu that waits on a
102
+ board or a sign-in is a menu that never opens.
103
+
104
+ **CRITICAL: browser functions are called with their own receiver.** Wrong:
105
+ `this.transport = fetch` and later `this.transport(url)`. Chrome throws `Illegal
106
+ invocation` before any request leaves. Right: call `fetch(url)` directly, or store
107
+ `fetch.bind(globalThis)`. OpenGame's own score refresh did this, and every suite passed
108
+ because Node's `fetch` and every mock ignore their receiver. Prove a network path in a
109
+ real browser, not with a mocked `fetch`.
110
+
111
+ **HIGH: fullscreen belongs to the page.** The frame cannot take fullscreen itself, and
112
+ OpenGame's page has its own Fullscreen button. Remove the game's own fullscreen control
113
+ and any call to `requestFullscreen` when it runs inside OpenGame; if the game keeps a
114
+ button, have it call `og.fullscreen.request()` from the player's click. OG Clash, Super
115
+ Mario Zombies, Mario Colosseum and World at War each had a native one to take out.
116
+
117
+ **HIGH: keys stay in the frame.** Prevent Tab's default when the game uses it and the
118
+ focus is not on one of the game's own controls; otherwise focus walks out to the page's
119
+ buttons and the game never hears Tab released. Release every held key on `blur` and on
120
+ `visibilitychange` to hidden, because its keyup will be delivered somewhere else (OG
121
+ Clash's scoreboard stuck open over the pause menu). Cancel the default of every wheel
122
+ turn, arrow, Space and Page key the game consumes, so the page around it does not
123
+ scroll.
124
+
125
+ **HIGH: pause and mute are honoured.** `og.onPause` stops simulation, timers and audio (a game in a shared online match stops only its own input and sound, and `opengame-multiplayer` says how a host hands over);
126
+ `og.audio.onHostMute` silences the game. The frame boots under a poster before the
127
+ player presses Play, muted and paused from the first handshake, so keep loading through
128
+ the pause. Start audio only from an `onHostMute(false)` that arrives after
129
+ `await og.init()`: `og.audio.muted` reads false until the page first says otherwise.
130
+
131
+ **HIGH: every name field starts as the player's handle.** Any name the game asks this
132
+ player for or shows as theirs, such as a call sign, trainer name, player name, nickname,
133
+ or their own HUD label or nameplate, is filled from `og.player.handle` inside
134
+ `og.player.onChange`, so a signed-in player starts with the name they chose on OpenGame.
135
+ `handle` is null for a guest, an account without a handle and every private preview; then keep the game's own default. Stop filling once
136
+ the player edits the field, and when the game restores a name the player saved, show
137
+ that one instead. Allow 20 characters, `_` and `-` included, in
138
+ the field's `maxlength`, in the game's own name check and wherever the name is drawn.
139
+ Grep for name inputs and default names such as "Player" or "Rookie" to find every one
140
+ before you call this done.
141
+
142
+ ```js
143
+ let edited = savedName !== null // a name the player saved last time wins
144
+ if (edited) nameField.value = savedName
145
+ nameField.addEventListener('input', () => { edited = true })
146
+ og.player.onChange(player => {
147
+ if (!edited) nameField.value = player.handle ?? DEFAULT_NAME // null: the game's default
148
+ })
149
+ ```
150
+
151
+ **HIGH: a threaded build declares it and is checked isolated.** A build that needs
152
+ `SharedArrayBuffer` declares `"requires": { "threads": true }` and is checked in the
153
+ preview's game frame for `crossOriginIsolated`; load its runtime from the game's own
154
+ files. Call the SDK from the main thread only.
155
+ [references/engines.md](references/engines.md) has the check.
156
+
157
+ **MEDIUM: a guest has no id on OpenGame today.** While accounts are in private testing
158
+ every guest, and every account that is not a confirmed member, gets `og.player.id ===
159
+ null`. The local mock's guest has `dev-guest`, so this breaks only on the real page.
160
+ Check `typeof og.player.id === 'string'` before using it as a key.
161
+
162
+ ## Leaderboards and achievements
163
+
164
+ Declare each board and each achievement in `opengame.json` first, then:
165
+
166
+ ```js
167
+ const board = og.leaderboard('rounds')
168
+ const saved = await board.submit(14, { mode: 'coop' })
169
+ if (!saved.ok) console.warn(saved.reason ?? saved.error) // the player keeps playing
170
+ const top = await board.top({ limit: 10 })
171
+ const unlocked = await og.achievements.unlock('first_win')
172
+ ```
173
+
174
+ Metadata keys are limited to `label` (string), `mode` (string), `level` (string), `character` (string), `duration_ms` (number), `accuracy` (number), `combo` (number); `level` is a string
175
+ here even though events also accept it as a number. Achievements answer
176
+ `unavailable_in_preview` in a private preview and unlock once the game is published.
177
+ Full calls, bounds and codes: [references/leaderboards.md](references/leaderboards.md).
178
+
179
+ ## Events
180
+
181
+ ```js
182
+ og.track('wave_cleared', { level: 14, duration_ms: 81234 })
183
+ ```
184
+
185
+ Event names are lowercase with underscores, up to 48
186
+ characters. Properties are limited to `level`, `mode`, `difficulty`, `score`, `duration_ms`, `result`, `step`, `board`, `fps`, `heap_mb`, `sample_rate` and
187
+ 1,024 bytes per event, at most
188
+ 600 events a minute; anything else is dropped
189
+ rather than sent, and `og.track` returns `unavailable` before `og.init()`. Events are batched and
190
+ flushed every 10 seconds and on page exit. Plays, sessions and play
191
+ time are measured by the page; do not track them yourself.
192
+
193
+ ## The frame around the game
194
+
195
+ Focus, the poster, pause, mute, fullscreen, keys, scrolling and opening an outside link
196
+ with `og.openLink`: [references/frame.md](references/frame.md).
197
+
198
+ ## Invite links for a game's own lobbies
199
+
200
+ OpenGame runs no rooms; a multiplayer game brings its own (`opengame-multiplayer`). The
201
+ SDK gives it the link to share and the code a friend arrives with:
202
+
203
+ ```js
204
+ await og.init()
205
+ if (og.invite.code) joinLobby(og.invite.code) // opened from an invite: skip the menu
206
+ else showInvite(og.invite.link(lobbyCode) ?? lobbyCode) // hosting: share this; the code when null
207
+ ```
208
+
209
+ **HIGH: share `og.invite.link(code)`, never the game's own address.** The link is the game's
210
+ page on opengame.io with `?join=CODE`: whoever opens it gets the game on OpenGame, as
211
+ themselves, and lands in the lobby. A link to `<label>.opengame.gg` opens a warning page instead of the
212
+ game. A code is 4 to 12 capitals and digits, or exactly 22 of `A-Z a-z 0-9 _ -`; `link`
213
+ returns null for anything else, rather than a link whose code the page would change.
214
+ Under `opengame dev` the link is the local page, so two tabs can try it.
215
+
216
+ ## OG Radio
217
+
218
+ Players can pick OG Radio stations and songs in the game's menu and listen while they
219
+ play. The OpenGame page plays the music; the game only asks. `OpenGame.radio` in the
220
+ injected SDK, or `import { radio } from '@opengamehq/sdk/radio'`:
221
+
222
+ ```js
223
+ const picker = OpenGame.radio.mountPicker(menuElement, { theme: { accent: '#ff3b30' } })
224
+ ```
225
+
226
+ **HIGH: call `play`, `next`, `previous`, `setShuffle`, `setRepeat` and a louder
227
+ `setVolume` from the player's click or key press.** From a timer, a load handler or a game
228
+ event they return `gesture_required`, and while the player has the game muted they return
229
+ `muted`. Songs are always A to Z by title, and `q` searches within the scope it is given.
230
+ Calls, scopes, theming and codes: [references/radio.md](references/radio.md).
231
+
232
+ ## Offline and local development
233
+
234
+ Under `opengame dev`, which sets the flag the local stand-in needs, `og.init()` gives a
235
+ guest player (`dev-guest`), or a signed-in
236
+ one (`dev-account`, handle `dev`) with `og.init({ dev: { player: "signed-in" } })` or
237
+ `?og-dev-player=signed-in`, leaderboards stored in
238
+ `localStorage` per page folder.
239
+ The whole game can be built and tested offline except achievements, which
240
+ answer `unavailable` outside OpenGame and before `og.init()` has resolved. Hosted failures never
241
+ fall back to fake local data, so a broken hosted call shows up as an error, not as a
242
+ working board on one machine.
243
+
244
+ ## Common mistakes
245
+
246
+ | What you see | Why | Fix |
247
+ | --- | --- | --- |
248
+ | The default character on the first menu, "Your OG" much later | The OG is read or built only after the title | Build from `watchAvatar` at load; swap in at the menu |
249
+ | `TypeError: Illegal invocation` from a request | `fetch` stored as a field and called as a method | Call `fetch(...)` directly or bind it |
250
+ | The game's own fullscreen button does nothing in OpenGame | The frame has no fullscreen permission | Remove it; the page has Fullscreen |
251
+ | Tab leaves the game; a held-key screen stays up | Tab's default moved focus to the page | Prevent Tab on the game; release keys on blur |
252
+ | The page scrolls when the player scrolls a list or presses an arrow | The game consumed the input without cancelling it | `preventDefault` on inputs the game handles |
253
+ | A black frame or a stall in a threaded build | The frame is not cross-origin isolated | Load the runtime from the game's own files and check `crossOriginIsolated` in the preview; `requires.threads` turns the black frame into a sentence |
254
+ | `invalid_meta` on a score with a level | `level` sent as a number | Send `level` as a string in score metadata |
255
+ | `board_unavailable` | The board is not declared in `opengame.json` | Declare it, then deploy again |
256
+ | A board works locally and is empty on OpenGame | Local boards are this browser's `localStorage` | Check a published game, signed in |
257
+ | A signed-in player is asked to type a name, or is called "Player" | The field is filled from the game's default only | Fill it from `og.player.handle` in `onChange`, default when null |
258
+ | `Cannot read properties of null` from `og.player.id` on OpenGame only | Guests have no id there; the local guest does | Check the type before using it |
259
+ | Work gated on `onPause(false)` stalls under the poster | The page rests the game from its first handshake until Play | Pause the simulation, never loading or the OG build |
260
+
261
+ ## Verify before you call it integrated
262
+
263
+ Run each check and say which ones you could not run; an unrun check is unverified.
264
+
265
+ - Locally, as a guest and with `?og-dev-player=signed-in`: the name and the OG are
266
+ right on the first menu, and `og.player.requestSignIn()` mid-game updates both. Signed
267
+ in, every name field and name label reads `dev`; as a guest, the game's own default.
268
+ - On the published game, signed out: nothing assumes `og.player.id` is a string.
269
+ - `og.ready()` fires once, on the first frame the player can act in.
270
+ - Pause stops simulation, timers and audio; resume does not replay a backlog. Nothing
271
+ plays while muted under the poster.
272
+ - In the private preview, where there is no identity and achievements answer
273
+ `unavailable_in_preview`: nothing waits on them, and nothing breaks.
274
+ - Inside the game frame: Tab, arrows and the wheel do not move the page; alt-tab with
275
+ a key held, come back, and nothing is stuck; the page's Fullscreen works and the game
276
+ draws at the new size.
277
+ - A threaded build, in the preview's game frame, in each browser the creator supports:
278
+ the console check in [references/engines.md](references/engines.md) reads `true`.
279
+ - Every board and achievement used in code is declared in `opengame.json`, and
280
+ `opengame check . --json` passes.
281
+ - On the published game, signed in as a confirmed member (the only accounts given a
282
+ player during the private rollout) with a handle, then as a guest: the handle
283
+ shows only in the first case.
@@ -0,0 +1,93 @@
1
+ # How the SDK reaches the game
2
+
3
+ Pick one path, and read the matching section of the installed SDK's README before
4
+ writing the calls; the operations and their arguments are listed there for that
5
+ version.
6
+
7
+ ## Bundled JavaScript
8
+
9
+ `import { og } from '@opengamehq/sdk'`, with `@opengamehq/sdk/avatar` as a separate
10
+ entry so a game bundles only what it imports.
11
+ Importing starts nothing: no listener, no timer, no request until `og.init()`.
12
+
13
+ ## No build step
14
+
15
+ Copy `dist/opengame.js` into the game's own files and load it with a `<script>` before
16
+ the game's scripts; it defines the global `OpenGame.og`. `dist/avatar.js` imports
17
+ nothing and loads from a `<script type="module">`, given `OpenGame.og` as the client.
18
+
19
+ ## The injected global
20
+
21
+ Some runtime contracts have OpenGame add `/_og/sdk.js`, the complete SDK, to each game
22
+ page; today the cross-origin isolated ones do. It defines `OpenGame`, with
23
+ `OpenGame.og` and `OpenGame.bridge`.
24
+ Check for `window.OpenGame` in the preview's game frame before relying on it, and
25
+ otherwise ship a copy yourself.
26
+
27
+ The injected global starts the handshake as it loads, before the game's own scripts:
28
+ it listens to the page and requests the session. That is how a native engine whose
29
+ runtime takes a minute to boot still has its player on the first menu. It does no
30
+ more than that until `og.init()`: no input, error or frame-rate reporting, and
31
+ `og.track` returns `unavailable`. Call `og.init()` as usual; it adopts what has already arrived.
32
+
33
+ On those contracts the tag is always added; og-games decides from the contract alone
34
+ and never reads the manifest. `"sdk": { "inject": false }` in `opengame.json` is honoured
35
+ only by the older contract whose serving tree the pipeline rewrites, which no new release
36
+ gets. A game that also ships its own copy is fine: copies of one SDK major install one
37
+ core and share a single `og`, so there is still one handshake. The copy that loads
38
+ first is the one that runs, which on these contracts is the platform's, so code against
39
+ the version the platform serves, not a newer minor you bundled. A copy of a different
40
+ major gets a client of its own.
41
+
42
+ ## `js/og-platform.js`
43
+
44
+ Games built from the Studio template, and our Originals, call the helpers in
45
+ `js/og-platform.js` (`ogReady`, `ogEvent` and the rest). The SDK's
46
+ `dist/og-platform.js` is rebuilt on the SDK, so a game moves
47
+ onto one implementation by replacing that one file. It contains the core: use its `og`
48
+ export for new code rather than adding a second copy of the SDK, so the version you
49
+ tested is the only one that runs. Its `ogEvent`
50
+ becomes `og.track`, so events then reach the creator's stats through the events API.
51
+
52
+ ## Native engines
53
+
54
+ An engine that cannot call JavaScript objects directly uses `OpenGame.bridge` from the
55
+ injected or shipped global: `setHandler` receives results and events as JSON strings,
56
+ `request(op, args)` returns an id whose result arrives on the handler.
57
+ The adapter adds no handshake, credential
58
+ or mock of its own; the core does all of that. The list of operations is in
59
+ the README under "Injected global and native engines".
60
+
61
+ Call the bridge from the browser's main thread. `window.OpenGame` does not exist in a
62
+ Web Worker and shared memory does not change that; send the call to the main thread
63
+ with the engine's own mechanism.
64
+
65
+ ## Threaded and WebAssembly builds
66
+
67
+ A build that uses threads needs `SharedArrayBuffer`, which a frame has only when it is
68
+ cross-origin isolated. OpenGame's scan notices thread use and moves the release onto
69
+ an isolated contract before anybody plays it; the game page and its frame then get the
70
+ isolation headers. The game still has three things to do:
71
+
72
+ 1. Declare it, when the game cannot start without threads:
73
+
74
+ ```json
75
+ { "requires": { "threads": true } }
76
+ ```
77
+
78
+ A browser that cannot run it then gets a sentence instead of a black frame. Leave it
79
+ out of a single-thread export, or browsers that could play it are turned away.
80
+ 2. Load its runtime, workers and assets from its own files. Isolation blocks a
81
+ cross-origin script or image that does not send the matching headers.
82
+ 3. Check it in the private preview, in the game's frame (choose the `opengame.gg`
83
+ frame in the console's context menu first), in every browser the creator supports:
84
+
85
+ ```js
86
+ console.table({ secure: isSecureContext, isolated: crossOriginIsolated, sharedMemory: 'SharedArrayBuffer' in self })
87
+ ```
88
+
89
+ All three must read `true`. `opengame dev . --contract` with the isolated contract
90
+ serves the same headers locally, but only the preview is the real page and frame.
91
+
92
+ Memory diagnostics, WebGPU and each engine's export settings are in the docs at
93
+ `https://docs.opengame.io/engines/overview`.
@@ -0,0 +1,107 @@
1
+ # The frame around the game
2
+
3
+ A game on OpenGame runs in a sandboxed, cross-origin frame on its own `opengame.gg`
4
+ address, inside a page that owns the poster, the Play button, mute, fullscreen and the
5
+ account. The frame may run scripts, keep its own storage and lock the pointer. It may
6
+ not open popups, navigate the page, submit forms or take fullscreen. Everything below
7
+ follows from that.
8
+
9
+ ## Before Play
10
+
11
+ The page boots the game under its poster before the player presses Play, so a large
12
+ game can load while they read the page. Keep loading, build the player's OG, and play
13
+ no sound: from the first handshake with the page (as the injected global loads, or at
14
+ `og.init()`) until Play, the page reports muted and `og.onPause` reports paused. Pause
15
+ the simulation, never loading or the OG build, or they wait for a press that has not
16
+ happened.
17
+ Focus that lands on the frame before Play is handed back to the page, so the game
18
+ cannot assume it has the keyboard yet. Pressing Play gives the frame focus.
19
+
20
+ ## Pause and mute
21
+
22
+ ```js
23
+ og.onPause(paused => game.setPaused(paused)) // tab hidden, page overlay open
24
+ og.audio.onHostMute(muted => audio.setMuted(muted)) // the page's mute button
25
+ ```
26
+
27
+ Listeners receive the current state at once and return an unsubscribe function. A
28
+ pause stops the simulation, its timers and its audio, and resuming does not replay the
29
+ time it missed. A game that already pauses when pointer lock ends can call
30
+ `document.exitPointerLock()` in its `onPause(true)` handler, so both ways of pausing
31
+ reach the same menu.
32
+
33
+ ## Fullscreen
34
+
35
+ ```js
36
+ fullscreenButton.onclick = () => og.fullscreen.request() // from a player's click
37
+ og.fullscreen.onChange(active => layout(active))
38
+ ```
39
+
40
+ The page's Fullscreen button takes the stage, the game included, and the game only
41
+ sees its frame resize; `og.fullscreen.active` is true while it is fullscreen. A game's own fullscreen control is a second button for the same
42
+ thing, so take it out when running inside OpenGame, as OG Clash, Super Mario Zombies,
43
+ Mario Colosseum and World at War did. If the game keeps one, it calls
44
+ `og.fullscreen.request()`; `requestFullscreen` inside the frame fails. Safari and
45
+ Firefox spend Escape on leaving fullscreen, so the pause menu needs a second way in.
46
+
47
+ ## Keys and the wheel
48
+
49
+ - **Tab.** Its default moves focus to the next control, which inside OpenGame is one
50
+ of the page's buttons. If the game uses Tab, prevent its default unless the event
51
+ target is one of the game's own inputs, buttons or links. Do not count `tabindex` as a
52
+ control: Emscripten's and Unity's templates put it on the canvas itself.
53
+ - **Held keys.** When the frame loses focus, the keyup for a held key goes to the page
54
+ and the game never hears it. On `blur`, and on `visibilitychange` to hidden, release
55
+ every key still down: through the engine's own "release all input" call if it has
56
+ one, or with a synthetic keyup where the engine listens.
57
+ - **Scrolling.** The browser hands a wheel turn, an arrow, Space, Page Up or Down, Home
58
+ or End that the game did not cancel to the next box that can scroll, which is the
59
+ page. Cancel the default of each one the game consumes, on the element that reads it.
60
+ OpenGame is adding a guard for this at the game host; do not rely on it.
61
+ - **Text fields.** Keep normal key behaviour in the game's own inputs, so a name field
62
+ takes Space, arrows and Tab.
63
+
64
+ OG Clash, 28 Oct 2026: its scoreboard is held on Tab. Tab moved focus to the page, the
65
+ pointer lock went with it, the engine paused onto its menu, and Tab's keyup went to
66
+ the page, so the scoreboard stayed up over the pause menu. A guard adapted from its fix:
67
+
68
+ ```js
69
+ const held = new Map()
70
+ const control = t => t instanceof Element && !!t.closest('input, select, textarea, button, a[href]')
71
+ addEventListener('keydown', e => {
72
+ if (e.isTrusted) held.set(e.code, e)
73
+ if (e.key === 'Tab' && !control(e.target)) e.preventDefault()
74
+ }, true)
75
+ addEventListener('keyup', e => { if (e.isTrusted) held.delete(e.code) }, true)
76
+ const release = () => {
77
+ for (const down of held.values()) {
78
+ const target = down.target instanceof Node && down.target.isConnected ? down.target : document
79
+ // bubbles, so listeners on the canvas, the document and the window all hear it
80
+ target.dispatchEvent(new KeyboardEvent('keyup', { code: down.code, key: down.key, keyCode: down.keyCode, which: down.which, bubbles: true }))
81
+ }
82
+ held.clear()
83
+ }
84
+ addEventListener('blur', release)
85
+ document.addEventListener('visibilitychange', () => { if (document.hidden) release() })
86
+ ```
87
+
88
+ This keeps Tab, Shift+Tab included, inside the game, so give a keyboard-only player
89
+ another way back to the page: let Tab through while the pause menu is open. Check it
90
+ against the engine: press Tab, alt-tab with a key held, come back, and nothing is
91
+ stuck.
92
+
93
+ ## Leaving the game
94
+
95
+ A link out goes through the page, which shows the address and lets the player choose:
96
+
97
+ ```js
98
+ creditsButton.addEventListener('click', async () => {
99
+ if (!og.capabilities.includes('external-links')) return
100
+ const opened = await og.openLink('https://example.com/credits')
101
+ if (!opened.ok && opened.error !== 'cancelled') showMessage(opened.reason ?? opened.error)
102
+ })
103
+ ```
104
+
105
+ Call it directly from the click or key handler, or it answers `gesture_required`. A
106
+ host on OpenGame's list of refused services answers `invalid_request`, as a malformed
107
+ address does. `window.open` and links with a target do nothing in the frame.
@@ -0,0 +1,111 @@
1
+ # Who the player is
2
+
3
+ | Situation | `id` | `handle`, `ogNumber` | `avatar` | `signedIn` |
4
+ | --- | --- | --- | --- | --- |
5
+ | Signed in, with a handle | Stable for this player in this game, on every device | Their public handle and number | Their head, and their outfit if they have one | `true` |
6
+ | Signed in, no handle claimed yet | Stable as above | `null` | Their OG, if they have made one | `true` |
7
+ | Guest | `null` while accounts are in private testing; otherwise stable in this browser for this game | `null` | `null` | `false` |
8
+ | Private preview | `null`. Identity is not offered; scores stay separate from public ones | `null` | `null` | `false` |
9
+ | Outside OpenGame, by default | `dev-guest` | `null` | `null` | `false` |
10
+ | Outside OpenGame, as a signed-in player | `dev-account` | handle `dev`, number `1` | a sample head and outfit | `true` |
11
+
12
+ Read the fields where you use them, `og.player.id`, `og.player.handle`,
13
+ `og.player.ogNumber`, `og.player.signedIn` and `og.player.avatar`, rather than keeping a
14
+ copy: each one is the current player.
15
+
16
+ Pick the local player with `og.init({ dev: { player: "signed-in" } })` or
17
+ `?og-dev-player=signed-in` on the page address; `guest` and `no-handle` work too.
18
+
19
+ **The private rollout.** While OpenGame accounts are in private testing, a game gets a
20
+ signed-in player only for a member who has confirmed they are 18 or older. Everybody
21
+ else, signed in or not, plays as a guest with `id: null` and can still save scores
22
+ through the page's guest credential. So a game cannot assume a string `id`: key
23
+ per-player storage on `id` only when it is one, and keep a guest's progress in the
24
+ game's own storage. The local mock's guest has `dev-guest`, so this path runs only on
25
+ OpenGame: test the published game signed out.
26
+
27
+ ## When the player arrives
28
+
29
+ The page answers the SDK's first message with the player, while the game is still
30
+ loading. Under the injected global that first message goes out as the script loads,
31
+ before the game's own code runs, and a shipped `dist/opengame-global.js` does the same
32
+ on OpenGame. With the npm import or `dist/opengame.js` it goes out at `og.init()`.
33
+ Either way:
34
+
35
+ - Call `og.init()` before anything heavy, and subscribe at once: `og.player.onChange`
36
+ and `watchAvatar` call the listener with the current player straight away and again
37
+ on every change.
38
+ - Start the work the player needs, such as building "Your OG", as soon as it is known.
39
+ Show it at the first menu. Only the swap into a running scene needs to wait for a
40
+ menu.
41
+ - While the page is still confirming the account it sends a pending notice, and `og.init()` waits about
42
+ 10 seconds more for it. A guest stays a guest until then;
43
+ `onChange` fires if the account arrives.
44
+
45
+ OG Clash, 28 Oct 2026: it asked for nothing until its engine reached the title, then
46
+ built the OG on a cold worker, so the first menu showed the default character and the
47
+ player's own appeared most of a minute later. Starting the build when the player is
48
+ known, under the loading screen, fixed it.
49
+
50
+ ## What it is and is not
51
+
52
+ - The per-game `id` cannot be joined across games: the same person has a different id
53
+ in every game. That is the point of it; do not try to work around it.
54
+ - `handle` and `ogNumber` are public profile values, the same across games, sent for
55
+ every signed-in player who has claimed a handle; there is no setting to withhold
56
+ them. A game may show them, link them and recognise a returning handle; say so in
57
+ the game's own copy if it matters to players. Fall back to a guest name when they
58
+ are `null`. They are never a storage key, because they can be
59
+ null for a signed-in player and can change.
60
+ - The SDK never gives the game an email, the account's real id, a friends list or a
61
+ browser fingerprint, and a game should never ask for them.
62
+ - A guest's id lives in one browser. Clearing site data makes a new guest; only scores
63
+ carry over when a guest signs in.
64
+
65
+ ## Names
66
+
67
+ Every name the game asks this player for, or shows as theirs, starts as their handle.
68
+ That covers a call sign, a trainer name, a player name, a nickname, and their own HUD
69
+ label or nameplate. Fill each one from `og.player.handle` inside `og.player.onChange`,
70
+ and let the game's own default stand when it is null. The listener runs at once and
71
+ again when the page confirms the account late or the player signs in or out. Stop
72
+ filling a field once the player edits it, so a name they typed stays. When the game
73
+ restores a name the player saved in an earlier session, show that one and do not fill. A
74
+ handle is 3 to 20 characters of letters,
75
+ digits, `_` and `-`; allow the longest in the field, in the game's own name check and
76
+ wherever the name is drawn. Never write the handle into the game's own save as if it
77
+ were the player's identity.
78
+ Leaderboard entries carry their own `name`; show it as given, and expect `null` on a
79
+ few old rows.
80
+
81
+ ## Changes while playing
82
+
83
+ `og.player.onChange(listener)` fires with the current player at once and again when a
84
+ guest signs in, an account changes, or a refreshed session changes what the player
85
+ shares. During an account change the
86
+ old credentials are removed before the new ones are verified, so read `og.player` in
87
+ the callback instead of caching it.
88
+
89
+ ## Asking to sign in
90
+
91
+ `og.player.requestSignIn()` asks the page to open its own sign-in dialog. Offer it only
92
+ when `og.capabilities` includes `identity`, and only from a player's action ("Sign in to
93
+ save your score"). The game keeps running; `onChange` fires when they return signed in.
94
+
95
+ ## The player's OG
96
+
97
+ `og.player.avatar` is `{ seed, palette, look?, character? }`. `look` (the head) arrives
98
+ only when the player is signed in and has made one;
99
+ `character` (the body and outfit) arrives only beside a `look`. A guest, and every
100
+ player in a private preview, gets null, and then `og.capabilities` has no `avatar`.
101
+ With no `look`, draw the game's default.
102
+
103
+ ```js
104
+ import { watchAvatar } from '@opengamehq/sdk/avatar'
105
+ const stop = watchAvatar(og, avatar => avatar ? useYourOg(avatar) : useDefaultCharacter())
106
+ ```
107
+
108
+ `watchAvatar` calls at once and then only when the recipe changes, so a model is not
109
+ rebuilt on every session refresh. `readAvatar` names the parts of one recipe. Do not
110
+ store the recipe or send it anywhere; a player who changes or deletes their OG expects
111
+ the game to follow. Building and showing it is in `opengame-characters`.