@vgai/engine 0.5.15 → 0.5.17

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 (220) hide show
  1. package/dist/adapter/adapter-module.d.ts +229 -33
  2. package/dist/adapter/adapter-module.d.ts.map +1 -1
  3. package/dist/adapter/adapter-module.js +222 -50
  4. package/dist/adapter/authoring-seam-contract.d.ts +530 -0
  5. package/dist/adapter/authoring-seam-contract.d.ts.map +1 -0
  6. package/dist/adapter/authoring-seam-contract.js +162 -0
  7. package/dist/adapter/authoring.d.ts +237 -50
  8. package/dist/adapter/authoring.d.ts.map +1 -1
  9. package/dist/adapter/authoring.js +2 -1
  10. package/dist/adapter/entrypoint-selection-source.d.ts +35 -0
  11. package/dist/adapter/entrypoint-selection-source.d.ts.map +1 -0
  12. package/dist/adapter/entrypoint-selection-source.js +151 -0
  13. package/dist/adapter/finders/scenes-from-entrypoint-selection.d.ts +7 -3
  14. package/dist/adapter/finders/scenes-from-entrypoint-selection.d.ts.map +1 -1
  15. package/dist/adapter/finders/scenes-from-entrypoint-selection.js +145 -27
  16. package/dist/adapter/first-party-systems.d.ts +13 -3
  17. package/dist/adapter/first-party-systems.d.ts.map +1 -1
  18. package/dist/adapter/first-party-systems.js +10 -3
  19. package/dist/adapter/index.d.ts +7 -2
  20. package/dist/adapter/index.d.ts.map +1 -1
  21. package/dist/adapter/index.js +4 -0
  22. package/dist/adapter/ingest/contract-system-adapters.d.ts +1 -1
  23. package/dist/adapter/ingest/contract-system-adapters.d.ts.map +1 -1
  24. package/dist/adapter/ingest/contract-system-adapters.js +13 -25
  25. package/dist/adapter/ingest/game-contract-seams.d.ts +214 -0
  26. package/dist/adapter/ingest/game-contract-seams.d.ts.map +1 -0
  27. package/dist/adapter/ingest/game-contract-seams.js +62 -0
  28. package/dist/adapter/ingest/game-contract.d.ts +5 -3
  29. package/dist/adapter/ingest/game-contract.d.ts.map +1 -1
  30. package/dist/adapter/ingest/game-contract.js +4 -1
  31. package/dist/adapter/ingest/merge-debug-adapters.d.ts +52 -0
  32. package/dist/adapter/ingest/merge-debug-adapters.d.ts.map +1 -0
  33. package/dist/adapter/ingest/merge-debug-adapters.js +141 -0
  34. package/dist/adapter/ingest/observation-debug-adapter.d.ts +56 -0
  35. package/dist/adapter/ingest/observation-debug-adapter.d.ts.map +1 -0
  36. package/dist/adapter/ingest/observation-debug-adapter.js +131 -0
  37. package/dist/adapter/ingest/scene-capture.d.ts +38 -13
  38. package/dist/adapter/ingest/scene-capture.d.ts.map +1 -1
  39. package/dist/adapter/ingest/scene-capture.js +101 -24
  40. package/dist/adapter/ingest/visible-capture-window.d.ts +22 -5
  41. package/dist/adapter/ingest/visible-capture-window.d.ts.map +1 -1
  42. package/dist/adapter/ingest/visible-capture-window.js +46 -7
  43. package/dist/adapter/native-debug-module.d.ts +43 -0
  44. package/dist/adapter/native-debug-module.d.ts.map +1 -0
  45. package/dist/adapter/native-debug-module.js +230 -0
  46. package/dist/adapter/object3d-authoring-subject.d.ts +32 -0
  47. package/dist/adapter/object3d-authoring-subject.d.ts.map +1 -0
  48. package/dist/adapter/object3d-authoring-subject.js +25 -0
  49. package/dist/adapter/root-adapter.d.ts +25 -56
  50. package/dist/adapter/root-adapter.d.ts.map +1 -1
  51. package/dist/adapter/root-adapter.js +4 -20
  52. package/dist/adapter/root-seam-contract.d.ts +129 -0
  53. package/dist/adapter/root-seam-contract.d.ts.map +1 -0
  54. package/dist/adapter/root-seam-contract.js +37 -0
  55. package/dist/adapter/seam-evidence.d.ts +118 -0
  56. package/dist/adapter/seam-evidence.d.ts.map +1 -0
  57. package/dist/adapter/seam-evidence.js +231 -0
  58. package/dist/adapter/setup-three-root-adapter.d.ts +2 -3
  59. package/dist/adapter/setup-three-root-adapter.d.ts.map +1 -1
  60. package/dist/adapter/setup-three-root-adapter.js +11 -12
  61. package/dist/adapter/system-adapter.d.ts +6 -1
  62. package/dist/adapter/system-adapter.d.ts.map +1 -1
  63. package/dist/adapter/system-seam-contract.d.ts +354 -0
  64. package/dist/adapter/system-seam-contract.d.ts.map +1 -0
  65. package/dist/adapter/system-seam-contract.js +95 -0
  66. package/dist/animation/xstate-animation-binding.d.ts +6 -0
  67. package/dist/animation/xstate-animation-binding.d.ts.map +1 -1
  68. package/dist/animation/xstate-animation-binding.js +142 -4
  69. package/dist/asset-formats/collider.d.ts +1 -1
  70. package/dist/asset-formats/mesh.d.ts +2 -2
  71. package/dist/asset-formats/particles.d.ts +1 -1
  72. package/dist/canvas-react/engine-bridge.d.ts +6 -6
  73. package/dist/canvas-react/engine-bridge.d.ts.map +1 -1
  74. package/dist/canvas-react/engine-bridge.js +2 -2
  75. package/dist/canvas-react/index.d.ts +2 -2
  76. package/dist/canvas-react/index.d.ts.map +1 -1
  77. package/dist/canvas-react/index.js +1 -1
  78. package/dist/canvas-react/pixi-react-adapter.d.ts +15 -9
  79. package/dist/canvas-react/pixi-react-adapter.d.ts.map +1 -1
  80. package/dist/canvas-react/pixi-react-adapter.js +129 -64
  81. package/dist/canvas-react/pixi-react-root-factory.d.ts.map +1 -1
  82. package/dist/canvas-react/pixi-react-root-factory.js +4 -0
  83. package/dist/canvas-react/world-context.d.ts +22 -12
  84. package/dist/canvas-react/world-context.d.ts.map +1 -1
  85. package/dist/canvas-react/world-context.js +12 -51
  86. package/dist/data/curve.d.ts +1 -1
  87. package/dist/data/curve.js +2 -2
  88. package/dist/dev/instruments.d.ts +4 -4
  89. package/dist/dev/instruments.js +4 -4
  90. package/dist/dev/register-render-vitals.d.ts +2 -2
  91. package/dist/dev/register-render-vitals.js +2 -2
  92. package/dist/dev/static-batch-advisor.d.ts +1 -1
  93. package/dist/dev/static-batch-advisor.js +2 -2
  94. package/dist/ecs/user-data.d.ts +5 -0
  95. package/dist/ecs/user-data.d.ts.map +1 -1
  96. package/dist/ecs/user-data.js +3 -0
  97. package/dist/input/input-manager.d.ts +64 -0
  98. package/dist/input/input-manager.d.ts.map +1 -1
  99. package/dist/input/input-manager.js +149 -0
  100. package/dist/manifest/load.d.ts +0 -3
  101. package/dist/manifest/load.d.ts.map +1 -1
  102. package/dist/manifest/load.js +0 -4
  103. package/dist/manifest/schema.d.ts +9 -11
  104. package/dist/manifest/schema.d.ts.map +1 -1
  105. package/dist/manifest/schema.js +2 -23
  106. package/dist/pixi/authoring.d.ts +33 -0
  107. package/dist/pixi/authoring.d.ts.map +1 -1
  108. package/dist/pixi/authoring.js +301 -2
  109. package/dist/pixi/ingest.d.ts +2 -1
  110. package/dist/pixi/ingest.d.ts.map +1 -1
  111. package/dist/pixi/ingest.js +4 -2
  112. package/dist/pixi/scene-capture.d.ts +9 -1
  113. package/dist/pixi/scene-capture.d.ts.map +1 -1
  114. package/dist/pixi/scene-capture.js +9 -6
  115. package/dist/react/world-state.d.ts +12 -0
  116. package/dist/react/world-state.d.ts.map +1 -1
  117. package/dist/react/world-state.js +14 -0
  118. package/dist/render/particles-factory.d.ts +13 -6
  119. package/dist/render/particles-factory.d.ts.map +1 -1
  120. package/dist/render/particles-factory.js +6 -3
  121. package/dist/render/soft-particle-depth.d.ts +3 -3
  122. package/dist/render/soft-particle-depth.d.ts.map +1 -1
  123. package/dist/render/soft-particle-depth.js +8 -13
  124. package/dist/runtime/create-runtime.d.ts +25 -62
  125. package/dist/runtime/create-runtime.d.ts.map +1 -1
  126. package/dist/runtime/create-runtime.js +58 -105
  127. package/dist/runtime/dev-build.d.ts +37 -0
  128. package/dist/runtime/dev-build.d.ts.map +1 -0
  129. package/dist/runtime/dev-build.js +49 -0
  130. package/dist/runtime/game.d.ts +38 -72
  131. package/dist/runtime/game.d.ts.map +1 -1
  132. package/dist/runtime/game.js +40 -55
  133. package/dist/runtime/mount-game.d.ts.map +1 -1
  134. package/dist/runtime/mount-game.js +12 -1
  135. package/dist/runtime/mount-manifest.d.ts +0 -13
  136. package/dist/runtime/mount-manifest.d.ts.map +1 -1
  137. package/dist/runtime/mount-manifest.js +5 -25
  138. package/dist/runtime/types.d.ts +18 -0
  139. package/dist/runtime/types.d.ts.map +1 -1
  140. package/dist/setup/setup-renderer.d.ts +3 -4
  141. package/dist/setup/setup-renderer.d.ts.map +1 -1
  142. package/dist/setup/setup-renderer.js +3 -4
  143. package/dist/world3d-react/engine-bridge.d.ts +1 -1
  144. package/dist/world3d-react/engine-bridge.d.ts.map +1 -1
  145. package/dist/world3d-react/engine-bridge.js +29 -4
  146. package/dist/world3d-react/index.d.ts +1 -1
  147. package/dist/world3d-react/index.js +1 -1
  148. package/dist/world3d-react/r3f-adapter.d.ts +7 -0
  149. package/dist/world3d-react/r3f-adapter.d.ts.map +1 -1
  150. package/dist/world3d-react/r3f-adapter.js +132 -28
  151. package/dist/world3d-react/r3f-root-factory.d.ts.map +1 -1
  152. package/dist/world3d-react/r3f-root-factory.js +14 -0
  153. package/dist/world3d-react/rapier-physics-bridge.d.ts +4 -4
  154. package/dist/world3d-react/rapier-physics-bridge.js +3 -3
  155. package/dist/world3d-react/world-context.d.ts +52 -3
  156. package/dist/world3d-react/world-context.d.ts.map +1 -1
  157. package/dist/world3d-react/world-context.js +94 -64
  158. package/dist-config/config.js.map +1 -1
  159. package/package.json +1 -1
  160. package/schemas/engine-capabilities.json +8 -8
  161. package/schemas/vgai-project.schema.json +1 -6
  162. package/src/adapter/adapter-module.ts +405 -72
  163. package/src/adapter/authoring-seam-contract.ts +211 -0
  164. package/src/adapter/authoring.ts +242 -50
  165. package/src/adapter/entrypoint-selection-source.ts +159 -0
  166. package/src/adapter/finders/scenes-from-entrypoint-selection.ts +162 -36
  167. package/src/adapter/first-party-systems.ts +17 -3
  168. package/src/adapter/index.ts +51 -1
  169. package/src/adapter/ingest/contract-system-adapters.ts +26 -30
  170. package/src/adapter/ingest/game-contract-seams.ts +85 -0
  171. package/src/adapter/ingest/game-contract.ts +9 -4
  172. package/src/adapter/ingest/merge-debug-adapters.ts +193 -0
  173. package/src/adapter/ingest/observation-debug-adapter.ts +158 -0
  174. package/src/adapter/ingest/scene-capture.ts +126 -23
  175. package/src/adapter/ingest/visible-capture-window.ts +63 -9
  176. package/src/adapter/native-debug-module.ts +307 -0
  177. package/src/adapter/object3d-authoring-subject.ts +50 -0
  178. package/src/adapter/root-adapter.ts +25 -56
  179. package/src/adapter/root-seam-contract.ts +57 -0
  180. package/src/adapter/seam-evidence.ts +336 -0
  181. package/src/adapter/setup-three-root-adapter.ts +13 -15
  182. package/src/adapter/system-adapter.ts +6 -1
  183. package/src/adapter/system-seam-contract.ts +121 -0
  184. package/src/animation/xstate-animation-binding.ts +151 -4
  185. package/src/canvas-react/engine-bridge.ts +6 -6
  186. package/src/canvas-react/index.ts +2 -1
  187. package/src/canvas-react/pixi-react-adapter.tsx +143 -77
  188. package/src/canvas-react/pixi-react-root-factory.tsx +4 -0
  189. package/src/canvas-react/world-context.ts +26 -101
  190. package/src/data/curve.ts +2 -2
  191. package/src/dev/instruments.ts +4 -4
  192. package/src/dev/register-render-vitals.ts +2 -2
  193. package/src/dev/static-batch-advisor.ts +2 -2
  194. package/src/ecs/user-data.ts +5 -0
  195. package/src/input/input-manager.ts +145 -0
  196. package/src/manifest/load.ts +0 -7
  197. package/src/manifest/schema.ts +2 -25
  198. package/src/pixi/authoring.ts +329 -2
  199. package/src/pixi/ingest.ts +9 -2
  200. package/src/pixi/scene-capture.ts +20 -5
  201. package/src/react/world-state.tsx +15 -0
  202. package/src/render/particles-factory.ts +16 -6
  203. package/src/render/soft-particle-depth.ts +8 -13
  204. package/src/runtime/create-runtime.ts +79 -158
  205. package/src/runtime/dev-build.ts +49 -0
  206. package/src/runtime/game.ts +72 -113
  207. package/src/runtime/mount-game.ts +19 -1
  208. package/src/runtime/mount-manifest.ts +5 -37
  209. package/src/runtime/types.ts +22 -0
  210. package/src/setup/setup-renderer.ts +3 -4
  211. package/src/world3d-react/engine-bridge.ts +29 -4
  212. package/src/world3d-react/index.ts +1 -1
  213. package/src/world3d-react/r3f-adapter.tsx +140 -31
  214. package/src/world3d-react/r3f-root-factory.tsx +14 -0
  215. package/src/world3d-react/rapier-physics-bridge.tsx +4 -4
  216. package/src/world3d-react/world-context.ts +111 -87
  217. package/dist/runtime/dev-layers.d.ts +0 -34
  218. package/dist/runtime/dev-layers.d.ts.map +0 -1
  219. package/dist/runtime/dev-layers.js +0 -46
  220. package/src/runtime/dev-layers.ts +0 -46
@@ -23,7 +23,7 @@ import { documentVisibilityClock, startVisibleCaptureWindow, } from '../adapter/
23
23
  * host's `pixi.js` namespace so a shared-instance game is trapped. Install once per
24
24
  * ingest session; `uninstall()` on teardown.
25
25
  */
26
- export function installSceneCapture2D(pixiNamespace) {
26
+ export function installSceneCapture2D(pixiNamespace, options = {}) {
27
27
  const PIXI = pixiNamespace;
28
28
  const proto = PIXI.Application.prototype;
29
29
  let captured = null;
@@ -38,9 +38,12 @@ export function installSceneCapture2D(pixiNamespace) {
38
38
  drawCount++;
39
39
  const stage = this['stage'];
40
40
  if (!captured && stage) {
41
- captured = { stage, renderer: this['renderer'], app: this };
42
- for (const resolve of waiters.splice(0))
43
- resolve(captured);
41
+ const candidate = { stage, renderer: this['renderer'], app: this };
42
+ if (options.accept?.(candidate) ?? true) {
43
+ captured = candidate;
44
+ for (const resolve of waiters.splice(0))
45
+ resolve(captured);
46
+ }
44
47
  }
45
48
  return realRender?.apply(this, args);
46
49
  },
@@ -76,8 +79,8 @@ export function installSceneCapture2D(pixiNamespace) {
76
79
  waiters.splice(i, 1);
77
80
  opts.onWait?.(null);
78
81
  reject(new Error(`pixi scene capture timed out after ${timeoutMs}ms of VISIBLE time ` +
79
- `(${Math.round(captureWindow.elapsedHiddenMs())}ms hidden, which is not counted — ` +
80
- 'a hidden tab cannot render) — the game never rendered, or it bundles its own ' +
82
+ `(${Math.round(captureWindow.elapsedHiddenMs())}ms browser-suspended, which is ` +
83
+ 'not counted because no frame can be presented) — the game never rendered, or it bundles its own ' +
81
84
  '(un-shared) copy of pixi.js.'));
82
85
  },
83
86
  });
@@ -46,6 +46,18 @@ export declare function WorldProvider({ game, children }: PropsWithChildren<{
46
46
  * descriptively when called outside one — matching the repo's loud-failure
47
47
  * habit rather than silently returning `null`. */
48
48
  export declare function useGame(): Game;
49
+ /**
50
+ * {@link useGame}'s non-throwing sibling: the `Game` when one hosts this tree,
51
+ * `null` otherwise.
52
+ *
53
+ * For components that legitimately mount BOTH under a running game and under a
54
+ * host that has none — the editor design-mounts a world to author it, and a
55
+ * story renders a component with no game at all. Those components must degrade
56
+ * (a dev/QA surface that simply has nothing to drive) rather than throw during
57
+ * render, which would take the whole world down with it. Everything else uses
58
+ * `useGame`, whose throw is the honest report of a wiring bug.
59
+ */
60
+ export declare function useOptionalGame(): Game | null;
49
61
  /**
50
62
  * Subscribe to a selected slice of game state. Re-renders only when the
51
63
  * selected value changes: the selector re-runs at most once per completed
@@ -1 +1 @@
1
- {"version":3,"file":"world-state.d.ts","sourceRoot":"","sources":["../../src/react/world-state.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EAMvB,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAA4B,KAAK,MAAM,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AACjG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;6EAC6E;AAC7E,OAAO,EAAE,OAAO,EAAE,CAAC;AAInB;;;;;;;;;;;;;;oFAcoF;AACpF,wBAAgB,aAAa,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,iBAAiB,CAAC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,+BAElF;AAED;;mDAEmD;AACnD,wBAAgB,OAAO,IAAI,IAAI,CAQ9B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAAG,CAAC,CAW9F;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAiBlF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,CAAC,EAClC,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAC5B,CAAC,CAoBH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,EACjB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;CAAE,GAC1C,IAAI,CAaN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,QAAQ,GAAG,SAAS,GAAG,SAAS,EAC1E,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAAE,EACrE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAC/D,IAAI,CAeN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CASxE"}
1
+ {"version":3,"file":"world-state.d.ts","sourceRoot":"","sources":["../../src/react/world-state.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEL,KAAK,iBAAiB,EAMvB,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EAA4B,KAAK,MAAM,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AACjG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD;6EAC6E;AAC7E,OAAO,EAAE,OAAO,EAAE,CAAC;AAInB;;;;;;;;;;;;;;oFAcoF;AACpF,wBAAgB,aAAa,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,iBAAiB,CAAC;IAAE,IAAI,EAAE,IAAI,CAAA;CAAE,CAAC,+BAElF;AAED;;mDAEmD;AACnD,wBAAgB,OAAO,IAAI,IAAI,CAQ9B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,IAAI,IAAI,GAAG,IAAI,CAE7C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,EAAE,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAAG,CAAC,CAW9F;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAiBlF;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,CAAC,EAClC,MAAM,GAAE,MAAM,CAAC,CAAC,CAAa,GAC5B,CAAC,CAoBH;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,EACjB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAA;CAAE,GAC1C,IAAI,CAaN;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,CAAC,SAAS,CAAC,CAAC,QAAQ,GAAG,SAAS,GAAG,SAAS,EAC1E,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAAE,EACrE,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAC/D,IAAI,CAeN;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,KAAK,IAAI,CASxE"}
@@ -51,6 +51,20 @@ export function useGame() {
51
51
  }
52
52
  return game;
53
53
  }
54
+ /**
55
+ * {@link useGame}'s non-throwing sibling: the `Game` when one hosts this tree,
56
+ * `null` otherwise.
57
+ *
58
+ * For components that legitimately mount BOTH under a running game and under a
59
+ * host that has none — the editor design-mounts a world to author it, and a
60
+ * story renders a component with no game at all. Those components must degrade
61
+ * (a dev/QA surface that simply has nothing to drive) rather than throw during
62
+ * render, which would take the whole world down with it. Everything else uses
63
+ * `useGame`, whose throw is the honest report of a wiring bug.
64
+ */
65
+ export function useOptionalGame() {
66
+ return useContext(GameContext);
67
+ }
54
68
  /**
55
69
  * Subscribe to a selected slice of game state. Re-renders only when the
56
70
  * selected value changes: the selector re-runs at most once per completed
@@ -7,7 +7,7 @@
7
7
  * The schema mirrors quarks' native JSON format, so most fields pass through
8
8
  * directly to quarks' fromJSON or constructor methods.
9
9
  */
10
- import { type EmitterShape } from 'quarks.core';
10
+ import { type ColorGenerator, type EmitterShape, type FunctionColorGenerator } from 'quarks.core';
11
11
  import * as THREE from 'three';
12
12
  import { type BatchedRenderer, ParticleSystem } from 'three.quarks';
13
13
  import type { ParticlesDescriptor } from '../asset-formats/particles';
@@ -26,9 +26,9 @@ export interface ParticleSystemResult {
26
26
  * This is how a caller with fidelity a plain descriptor cannot express reaches
27
27
  * the SAME factory instead of hand-building its own `new ParticleSystem(...)`:
28
28
  * a foreign-engine carry (e.g. Godot CPUParticles) supplies its own
29
- * `EmitterShape` and an instancing geometry here, and expresses everything
30
- * else — lifecycle, start values, emission, behaviors, material — as descriptor
31
- * JSON.
29
+ * `EmitterShape`, start-colour generator, and instancing geometry here, and
30
+ * expresses everything else — lifecycle, scalar start values, emission,
31
+ * behaviors, material — as descriptor JSON.
32
32
  */
33
33
  export interface ParticleSystemObjects {
34
34
  /**
@@ -37,6 +37,12 @@ export interface ParticleSystemObjects {
37
37
  * present it REPLACES `data.shape`.
38
38
  */
39
39
  shape?: EmitterShape;
40
+ /**
41
+ * A pre-built start-colour generator for a per-particle draw the descriptor's
42
+ * JSON generator vocabulary cannot express. When present it REPLACES
43
+ * `data.startColor`.
44
+ */
45
+ startColor?: ColorGenerator | FunctionColorGenerator;
40
46
  /**
41
47
  * The geometry instanced per particle in `RenderMode.Mesh`. A
42
48
  * `BufferGeometry` is not JSON-serializable, so `renderMode: 'mesh'` requires
@@ -57,8 +63,9 @@ export interface ParticleSystemObjects {
57
63
  * Create a three.quarks ParticleSystem from ParticlesDescriptor JSON data.
58
64
  *
59
65
  * `objects` carries the pieces a JSON descriptor cannot: a plugin emitter
60
- * shape, a mesh-mode instancing geometry, and the default-sprite toggle. It is
61
- * optional and additive — a call with only `data` behaves exactly as before.
66
+ * shape, a start-colour generator, a mesh-mode instancing geometry, and the
67
+ * default-sprite toggle. It is optional and additive — a call with only `data`
68
+ * behaves exactly as before.
62
69
  */
63
70
  export declare function createParticleSystemFromData(data: ParticlesDescriptor, objects?: ParticleSystemObjects): ParticleSystemResult;
64
71
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"particles-factory.d.ts","sourceRoot":"","sources":["../../src/render/particles-factory.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAEH,OAAO,EAQL,KAAK,YAAY,EAmBlB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,KAAK,eAAe,EAAE,cAAc,EAAc,MAAM,cAAc,CAAC;AAChF,OAAO,KAAK,EAIV,mBAAmB,EAEpB,MAAM,4BAA4B,CAAC;AA4RpC,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC;IACxB,kEAAkE;IAClE,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC;IAC1C;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;GAMG;AAEH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,mBAAmB,EACzB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,oBAAoB,CA6DtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAsB9F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,SAAS,GAAG,IAAI,CAU/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,mBAAmB,CA6B1D"}
1
+ {"version":3,"file":"particles-factory.d.ts","sourceRoot":"","sources":["../../src/render/particles-factory.ts"],"names":[],"mappings":"AACA;;;;;;;;GAQG;AAEH,OAAO,EAIL,KAAK,cAAc,EAKnB,KAAK,YAAY,EAGjB,KAAK,sBAAsB,EAiB5B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAAE,KAAK,eAAe,EAAE,cAAc,EAAc,MAAM,cAAc,CAAC;AAChF,OAAO,KAAK,EAIV,mBAAmB,EAEpB,MAAM,4BAA4B,CAAC;AA4RpC,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC;IACxB,kEAAkE;IAClE,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;OAIG;IACH,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,GAAG,sBAAsB,CAAC;IACrD;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,KAAK,CAAC,cAAc,CAAC;IAC1C;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;GAOG;AAEH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,mBAAmB,EACzB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,oBAAoB,CA8DtB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,mBAAmB,GAAG,IAAI,CAsB9F;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,SAAS,GAAG,IAAI,CAU/F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CACtC,eAAe,EAAE,eAAe,EAChC,MAAM,EAAE,cAAc,GACrB,IAAI,CAGN;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,mBAAmB,CA6B1D"}
@@ -232,8 +232,9 @@ function getDefaultSpriteTex() {
232
232
  * Create a three.quarks ParticleSystem from ParticlesDescriptor JSON data.
233
233
  *
234
234
  * `objects` carries the pieces a JSON descriptor cannot: a plugin emitter
235
- * shape, a mesh-mode instancing geometry, and the default-sprite toggle. It is
236
- * optional and additive — a call with only `data` behaves exactly as before.
235
+ * shape, a start-colour generator, a mesh-mode instancing geometry, and the
236
+ * default-sprite toggle. It is optional and additive — a call with only `data`
237
+ * behaves exactly as before.
237
238
  */
238
239
  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: straightforward field-by-field mapping
239
240
  export function createParticleSystemFromData(data, objects) {
@@ -269,7 +270,9 @@ export function createParticleSystemFromData(data, objects) {
269
270
  params['startSize'] = valueGen(data.startSize);
270
271
  if (data.startRotation)
271
272
  params['startRotation'] = valueGen(data.startRotation);
272
- if (data.startColor)
273
+ if (objects?.startColor)
274
+ params['startColor'] = objects.startColor;
275
+ else if (data.startColor)
273
276
  params['startColor'] = colorGen(data.startColor);
274
277
  if (data.startTileIndex)
275
278
  params['startTileIndex'] = valueGen(data.startTileIndex);
@@ -91,9 +91,9 @@
91
91
  * callers are `registerParticleSystem` / `unregisterParticleSystem`.
92
92
  * - The render target and override material belong to the
93
93
  * {@link SoftParticleDepthPass} instance and die with its `dispose()`. The
94
- * pass itself is owned by whichever adapter mount created it (the R3F adapter
95
- * and `setup-three-root-adapter`), and that mount's teardown is the one path
96
- * allowed to end it.
94
+ * pass is owned by the renderer loop that calls it: an adapter mount for a
95
+ * runtime renderer, or the editor Scene viewport for its renderer. That
96
+ * owner's teardown is the one path allowed to end it.
97
97
  */
98
98
  import * as THREE from 'three';
99
99
  import type { BatchedRenderer } from 'three.quarks';
@@ -1 +1 @@
1
- {"version":3,"file":"soft-particle-depth.d.ts","sourceRoot":"","sources":["../../src/render/soft-particle-depth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAepD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,KAAK,CAAC,WAAW,CAOnD;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAQvE;AAED,uFAAuF;AACvF,wBAAgB,8BAA8B,IAAI,MAAM,CAEvD;AAED,0FAA0F;AAC1F,MAAM,WAAW,yBAAyB;IACxC,oBAAoB,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC3D,eAAe,IAAI,KAAK,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAClD,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9D,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC1D,kGAAkG;IAClG,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,UAAU,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;CACpE;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,yBAAyB,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC5F,OAAO,IAAI,IAAI,CAAC;CACjB;AA+CD,wBAAgB,2BAA2B,IAAI,qBAAqB,CA0GnE"}
1
+ {"version":3,"file":"soft-particle-depth.d.ts","sourceRoot":"","sources":["../../src/render/soft-particle-depth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAepD;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,KAAK,CAAC,WAAW,CAOnD;AAED,8FAA8F;AAC9F,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAQvE;AAED,uFAAuF;AACvF,wBAAgB,8BAA8B,IAAI,MAAM,CAEvD;AAED,0FAA0F;AAC1F,MAAM,WAAW,yBAAyB;IACxC,oBAAoB,CAAC,MAAM,EAAE,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IAC3D,eAAe,IAAI,KAAK,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAClD,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,iBAAiB,GAAG,IAAI,GAAG,IAAI,CAAC;IAC9D,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC1D,kGAAkG;IAClG,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,UAAU,EAAE,OAAO,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;CACpE;AAED,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,MAAM,CAAC,QAAQ,EAAE,yBAAyB,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC;IAC5F,OAAO,IAAI,IAAI,CAAC;CACjB;AA0CD,wBAAgB,2BAA2B,IAAI,qBAAqB,CA0GnE"}
@@ -91,9 +91,9 @@
91
91
  * callers are `registerParticleSystem` / `unregisterParticleSystem`.
92
92
  * - The render target and override material belong to the
93
93
  * {@link SoftParticleDepthPass} instance and die with its `dispose()`. The
94
- * pass itself is owned by whichever adapter mount created it (the R3F adapter
95
- * and `setup-three-root-adapter`), and that mount's teardown is the one path
96
- * allowed to end it.
94
+ * pass is owned by the renderer loop that calls it: an adapter mount for a
95
+ * runtime renderer, or the editor Scene viewport for its renderer. That
96
+ * owner's teardown is the one path allowed to end it.
97
97
  */
98
98
  import * as THREE from 'three';
99
99
  /**
@@ -173,16 +173,11 @@ function drawsIntoDepth(object) {
173
173
  * The three renderer members this prepass CANNOT do without — the render-target
174
174
  * swap it draws through, and the buffer size it sizes that target from.
175
175
  *
176
- * A real `WebGLRenderer` has all of them. A DESIGN-TIME settle does not: a
177
- * stand-in that only has to answer `render` mounts a world so the editor can
178
- * read it, and reaching for `getDrawingBufferSize` on one threw
179
- * `renderer.getDrawingBufferSize is not a function` out of the first driven
180
- * frame so a world whose particles merely *declare* a proximity fade could
181
- * not be settled at all. A prepass is an EFFECT: with no renderer to run it on,
182
- * the right answer is the inert far-depth default every batch is already bound
183
- * to (see {@link farDepthTexture}), which is pixel-identical to a batch that
184
- * never asked for soft particles. So this degrades, loudly and once, instead of
185
- * taking the frame down with it.
176
+ * A real `WebGLRenderer` has all of them. A design-time stand-in that only has
177
+ * to answer `render` may mount a world so another host can read it, but cannot
178
+ * run this effect. The editor does not pass that stand-in here: its real
179
+ * viewport renderer owns its own pass. Other incomplete hosts still degrade
180
+ * loudly and once instead of taking the frame down.
186
181
  */
187
182
  const REQUIRED_RENDERER_MEMBERS = [
188
183
  'getDrawingBufferSize',
@@ -1,14 +1,11 @@
1
- import * as THREE from 'three';
2
1
  import type { DomHostContext } from '../adapter/host-context';
3
- import type { MountedPixiRoot, MountedReactRoot, MountedRoot, MountedThreeRoot, RootAdapter } from '../adapter/root-adapter';
2
+ import type { MountedPixiRoot, MountedReactRoot, MountedThreeRoot, RootAdapter } from '../adapter/root-adapter';
4
3
  import { type Game, type GameInternal, type RootInstance } from './game';
5
4
  import type { PlaytestContext } from './types';
6
5
  /**
7
6
  * Register a three world onto the Game shell. `opts.id` defaults to
8
- * `'main'` — the single-world callers (`createGameRuntime`, slice-1/2 tests)
9
- * are unaffected; a second/third world (T7.1 slice 3's two-world proof, and
10
- * real multi-world manifests later) pass an explicit id. This is the ONE
11
- * registration code path for a three world, whatever its id.
7
+ * `'main'`; multi-root callers pass an explicit id. This is the one
8
+ * registration path for a three world, whatever its id.
12
9
  */
13
10
  export declare function registerThreeRoot(game: GameInternal, adapter: RootAdapter, mounted: MountedThreeRoot, opts?: {
14
11
  id?: string | undefined;
@@ -26,13 +23,13 @@ export declare function registerPixiRoot(game: GameInternal, adapter: RootAdapte
26
23
  pausable?: boolean | undefined;
27
24
  }): RootInstance;
28
25
  /**
29
- * Register a react world onto the Game shell (T6.2 slice 1) — the react
26
+ * Register a React world onto the Game shell — the DOM
30
27
  * analog of {@link registerThreeRoot}/{@link registerPixiRoot}. A react
31
28
  * world has no `frame` hooks (react's own
32
29
  * `createRoot` schedules its commits; `GameInternal.runFrame` correctly
33
30
  * leaves a world with no `frame` untouched by its opaque-`update` fallback
34
31
  * too, since `MountedReactGame` declares no `update`). `adapter` is typed
35
- * as the real {@link ReactRootAdapter} shape (T7.5, same reasoning as
32
+ * as the real {@link ReactRootAdapter} shape (same reasoning as
36
33
  * `registerPixiRoot`'s doc comment above) — `RootInstance.adapter` only
37
34
  * needs `.id`, so this passes through with zero cast.
38
35
  */
@@ -41,12 +38,12 @@ export declare function registerReactRoot(game: GameInternal, adapter: RootAdapt
41
38
  pausable?: boolean | undefined;
42
39
  }): RootInstance;
43
40
  /**
44
- * One world to mount in the {@link RootsRuntimeConfig} roots path (T6.1
45
- * slice 1) — the host-facing mirror of `manifest/load.ts`'s
46
- * `ResolvedAdapterRoot` (same `id`/`zOrder`/`pausable`/`loop` fields; the
41
+ * One world to mount in the universal host the host-facing mirror of
42
+ * `manifest/load.ts`'s `ResolvedAdapterRoot` (same identity and presentation
43
+ * fields; the
47
44
  * manifest-to-host translation itself is the editor's job, not this file's).
48
45
  *
49
- * `react` (T6.2 slice 1) mounts as a DOM-root layer `<div>` in the SAME
46
+ * A `dom` root mounts as a DOM layer `<div>` in the same
50
47
  * stack instead of a canvas — see {@link ReactRootMountSpec}/{@link
51
48
  * ReactRootAdapter} below.
52
49
  */
@@ -59,28 +56,6 @@ export interface RootMountSpecBase {
59
56
  readonly zOrder?: number | undefined;
60
57
  /** Whether play-mode pause/step applies to this world (D10). Defaults to `true`. */
61
58
  readonly pausable?: boolean | undefined;
62
- /**
63
- * `vgai.project.json`'s `dev: true` — this root is a DEV LAYER (the game's
64
- * own dev GUI), not shipped game content. Two things happen here: the
65
- * surface is stacked ABOVE every non-dev root (a dev layer sits topmost),
66
- * and it is marked `data-vgai-dev-layer="true"` so the play compositor can
67
- * leave it out of a capture (`composite-screenshot.ts`). Whether a dev root
68
- * reaches this function at all is the CALLER's gate —
69
- * `mountManifestRoots` asks `devLayersEnabled()` before building the spec.
70
- *
71
- * It steals no input from the game while closed for a reason that predates
72
- * this flag and needs no new mechanism: a dev layer is a `dom` root, DOM
73
- * layers are `pointer-events:none` (see `mountOneReactRoot`) with the
74
- * mounted tree opting individual elements back in, and the input router
75
- * never sees DOM roots at all.
76
- */
77
- readonly dev?: boolean | undefined;
78
- /** `'gated'` (host-driven, default) or `'self-driven'` (this world drives
79
- * its own loop — D5's "composited, unsynchronized" tier). Carried through
80
- * for parity with `ResolvedAdapterRoot`; T6.1 slice 1 does not yet
81
- * validate it against the mounted adapter's actual `drivesOwnLoop` (that
82
- * cross-check, if ever needed, is T7.6's loop-gate surface). */
83
- readonly loop?: 'gated' | 'self-driven' | undefined;
84
59
  /**
85
60
  * Optional claim predicate for the delegating input router (D5 §2a), over
86
61
  * a point RELATIVE TO THE CONTAINER. Absent means: this world claims only
@@ -103,8 +78,8 @@ export interface PixiRootMountSpec extends RootMountSpecBase {
103
78
  readonly adapter: RootAdapter<'canvas'>;
104
79
  }
105
80
  /**
106
- * A live, mounted react world (T6.2 slice 1) — the react analog of a mounted
107
- * canvas world. React roots render from game state via the T7.4 bridge
81
+ * A live, mounted React world — the DOM analog of a mounted canvas world.
82
+ * React roots render from game state
108
83
  * instead of a per-frame `update`, so this shape carries no `update`/`fixedUpdate`/
109
84
  * `ctx`/`frame` — `drivesOwnLoop` is always `false` (react's `createRoot`
110
85
  * schedules its OWN commits; the host's fixed-step loop never drives it,
@@ -121,10 +96,10 @@ export interface PixiRootMountSpec extends RootMountSpecBase {
121
96
  * `kind: 'dom'` (§7.1-15): a react world has no `observe` BY DESIGN — that
122
97
  * hook is scoped to `useRootObservation` (the ingested/foreign-world case),
123
98
  * not `useWorldState` (`ui/game-state.tsx`), which a react world's own
124
- * mounted tree uses instead — it reads `Game.state` directly (T7.4's actual
125
- * bridge for first-party-observable state), never a per-world `observe`.
99
+ * mounted tree uses instead — it reads `Game.state` directly, never a
100
+ * per-world `observe`.
126
101
  *
127
- * `kind`/`container` (T7.5) satisfy `MountedReactRoot` (`adapter/
102
+ * `kind`/`container` satisfy `MountedReactRoot` (`adapter/
128
103
  * root-adapter.ts`) — `container` is the SAME `DomHostContext.container` the
129
104
  * adapter's `mount` was handed (identity matters, mirroring `threeScene()`/
130
105
  * `pixiStage()`'s "same instance the adapter mounted" contract); every
@@ -139,7 +114,7 @@ export interface MountedReactGame extends MountedReactRoot {
139
114
  * A react-shaped adapter — the structural contract `RootMountSpec`'s
140
115
  * `react` variant requires. Deliberately
141
116
  * NOT tied to a concrete implementer here so an editor-resolved adapter (the
142
- * `default-react` resolver branch, T6.2's editor-side follow-up) can satisfy
117
+ * `default-react` resolver branch) can satisfy
143
118
  * this shape without this file importing react-dom or any editor code.
144
119
  *
145
120
  * A genuine `RootAdapter<'dom'>` refinement (`HostContextFor<'dom'>` =
@@ -227,37 +202,25 @@ export interface RootsRuntimeConfig {
227
202
  *
228
203
  * This is the GENERIC host handle — it has no first-party concepts (no
229
204
  * `GameContext`, no `GameSetupFn`). First-party features (the live `GameContext`,
230
- * warm-restart hot reload) are reached by casting `mounted` to `MountedSetupThreeRoot`
205
+ * warm-restart hot reload) are reached through `game.defaultRoot.mounted`
206
+ * and narrowed to `MountedSetupThreeRoot`
231
207
  * (the editor does this for HMR/physics-sync — those are inherently first-party).
232
208
  *
233
- * `scene`/`camera`/`mounted` alias the Game's `defaultRoot`: it is the first
234
- * three root (else the first
235
- * world) by DECLARATION order, per `Game.defaultRoot`'s existing rule —
236
- * independent of `zOrder`/canvas stacking, which is a rendering-only concern.
209
+ * Root access is explicit through `game.roots`, `game.world(id)`, and
210
+ * `game.defaultRoot`; the session does not project a surface-specific alias.
237
211
  */
238
212
  export interface GameSession {
239
213
  stop(): void;
214
+ /** Resolves after every root has finished the cleanup initiated by stop(). */
215
+ readonly stopComplete: Promise<void>;
240
216
  pause(): void;
241
217
  resume(): void;
242
218
  step(): void;
243
- /** Resize every world's render buffer. `pixelRatio` (W2c device preview)
244
- * optionally re-pins the three renderers' DPR in the same pass; omitted,
245
- * the mount-time ratio is left untouched (legacy behavior). */
219
+ /** Resize every world's render buffer. `pixelRatio` optionally re-pins the
220
+ * three renderers' DPR in the same pass. */
246
221
  resize(width: number, height: number, pixelRatio?: number): void;
247
- readonly scene: THREE.Scene;
248
- readonly camera: THREE.PerspectiveCamera;
249
- /** The default world's mounted root, as the honest `MountedRoot` union —
250
- * narrow on `.kind` before reaching for a surface's own members (the same
251
- * discriminant `scene`/`camera` above use). This deliberately does NOT
252
- * claim `MountedThreeRoot`: a roots-path session whose default world is
253
- * canvas or dom returns that world's mount, and the old
254
- * `as MountedThreeRoot` cast made every such value a type-level lie. For a
255
- * first-party three mount, narrow to `'three'` and cast to
256
- * `MountedSetupThreeRoot` for the first-party extras. */
257
- readonly mounted: MountedRoot;
258
- /** The Game root (T6.1 slice 1) — the multi-world entry point
259
- * (`game.roots`/`game.world(id)`/`game.queryByComponent`) for callers
260
- * that need more than the default-world aliases above. */
222
+ /** The multi-root entry point. Root access stays explicit through
223
+ * `game.roots`, `game.world(id)`, and `game.defaultRoot`. */
261
224
  readonly game: Game;
262
225
  }
263
226
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"create-runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/create-runtime.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"create-runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/create-runtime.ts"],"names":[],"mappings":"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"}