@threenative/core 0.3.4 → 0.3.6

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 (176) hide show
  1. package/capabilities.json +1505 -79
  2. package/dist/{audio-7i3Xl0l3.d.ts → audio-DIJE5HTr.d.ts} +43 -3
  3. package/dist/{canvas-layer-DDmC_VVF.d.ts → canvas-layer-C1-5CviZ.d.ts} +5 -1
  4. package/dist/{game-CljaDv4D.d.ts → game-Jz4Fdoeb.d.ts} +114 -11
  5. package/dist/hot.d.ts +4 -4
  6. package/dist/index.d.ts +712 -118
  7. package/dist/index.js +12437 -4955
  8. package/dist/{gpu-readback-CqJEfWNQ.d.ts → model-lod-BDAUYgsS.d.ts} +80 -5
  9. package/dist/playtest.d.ts +6 -10
  10. package/dist/playtest.js +57 -24
  11. package/dist/react-css.d.ts +62 -0
  12. package/dist/react-css.js +591 -0
  13. package/dist/react.d.ts +2 -2
  14. package/dist/{renderer-CfsS2hxi.d.ts → renderer-9yEo9hPa.d.ts} +489 -22
  15. package/dist/terrain-jobs-worker.d.ts +2 -0
  16. package/dist/terrain-jobs-worker.js +130 -0
  17. package/dist/ui-layer.js +59 -8
  18. package/dist/world.d.ts +766 -73
  19. package/dist/world.js +9307 -3543
  20. package/gpl/recipes/export_world.py +18 -1
  21. package/mcp/blender-server.mjs +7 -4
  22. package/mcp/blender.mjs +3 -4
  23. package/mcp/engine-server.mjs +2 -2
  24. package/mcp/servers.mjs +4 -4
  25. package/package.json +15 -9
  26. package/patches/three@0.185.1-prd269-upgrade.patch +22418 -0
  27. package/patches/three@0.185.1.patch +6594 -700
  28. package/scripts/apply-three-patch.mjs +62 -4
  29. package/src/animation-blend.ts +264 -0
  30. package/src/animation-composition.ts +362 -0
  31. package/src/animation-layers.ts +260 -0
  32. package/src/animation-root-motion.ts +283 -0
  33. package/src/animation.ts +896 -0
  34. package/src/assets.ts +1303 -0
  35. package/src/atmosphere/index.ts +335 -0
  36. package/src/atmosphere/luts.ts +298 -0
  37. package/src/atmosphere/params.ts +323 -0
  38. package/src/audio.ts +912 -0
  39. package/src/billboard.ts +124 -0
  40. package/src/bone-lengths.ts +157 -0
  41. package/src/camera-shake.ts +116 -0
  42. package/src/canvas-layer.ts +47 -0
  43. package/src/clip-audit.ts +401 -0
  44. package/src/clustered-batch.ts +492 -0
  45. package/src/clustered-mesh.ts +638 -0
  46. package/src/compute-driven.ts +176 -0
  47. package/src/compute-timing.ts +318 -0
  48. package/src/config.ts +593 -0
  49. package/src/debug.ts +82 -0
  50. package/src/engine-render-hook.ts +25 -0
  51. package/src/entities.ts +79 -0
  52. package/src/entity-snapshot.ts +53 -0
  53. package/src/flight.ts +683 -0
  54. package/src/fluid-field.ts +748 -0
  55. package/src/fluid-particles.ts +1253 -0
  56. package/src/frame-budget.ts +1368 -0
  57. package/src/game.ts +2408 -0
  58. package/src/geometry-capture.ts +1098 -0
  59. package/src/gpu-class.ts +160 -0
  60. package/src/gpu-frame-observation.ts +424 -0
  61. package/src/gpu-readback.ts +143 -0
  62. package/src/gpu-scene-bvh.ts +464 -0
  63. package/src/grounding.ts +100 -0
  64. package/src/hot.ts +161 -0
  65. package/src/import-meta.d.ts +13 -0
  66. package/src/index.ts +1536 -0
  67. package/src/input.ts +690 -0
  68. package/src/instanced-batch-lod.ts +283 -0
  69. package/src/instanced-batch.ts +274 -0
  70. package/src/interpolation.ts +129 -0
  71. package/src/launch-diagnostics.ts +161 -0
  72. package/src/loop.ts +574 -0
  73. package/src/matrix-world.ts +245 -0
  74. package/src/merge-parts.ts +812 -0
  75. package/src/model-lod.ts +1315 -0
  76. package/src/net-protocol.ts +333 -0
  77. package/src/net-session.ts +477 -0
  78. package/src/net.ts +80 -0
  79. package/src/ocean/fft.ts +72 -0
  80. package/src/ocean/spectral.ts +728 -0
  81. package/src/particle-significance.ts +102 -0
  82. package/src/particles.ts +648 -0
  83. package/src/path-follow.ts +175 -0
  84. package/src/picking.ts +250 -0
  85. package/src/pipeline-census.ts +1566 -0
  86. package/src/platform.ts +210 -0
  87. package/src/playtest.ts +850 -0
  88. package/src/pointer-events.ts +411 -0
  89. package/src/pose-measure.ts +435 -0
  90. package/src/profiling/FrameCounters.ts +231 -0
  91. package/src/profiling/Spans.ts +548 -0
  92. package/src/profiling/opacity-convention.ts +21 -0
  93. package/src/profiling/render-list-validate.ts +175 -0
  94. package/src/profiling/render-trap-audit.ts +84 -0
  95. package/src/profiling/scene-warning.ts +190 -0
  96. package/src/profiling/span-probes.ts +191 -0
  97. package/src/profiling/unlit-foliage-warning.ts +149 -0
  98. package/src/projection-apply.ts +1529 -0
  99. package/src/projection-marker.ts +142 -0
  100. package/src/projection-plan.ts +1258 -0
  101. package/src/projection-skinned.ts +419 -0
  102. package/src/projection-stability.ts +409 -0
  103. package/src/projection-uniform.ts +328 -0
  104. package/src/random.ts +41 -0
  105. package/src/react-css.ts +604 -0
  106. package/src/react-glyphs.ts +114 -0
  107. package/src/react-host.ts +576 -0
  108. package/src/react-layout.ts +265 -0
  109. package/src/react.ts +60 -0
  110. package/src/render/alpha-antialiasing.ts +159 -0
  111. package/src/render/batched-velocity.ts +126 -0
  112. package/src/render/chain.ts +1021 -0
  113. package/src/render/daylight.ts +189 -0
  114. package/src/render/depth-pyramid.ts +596 -0
  115. package/src/render/foliage-alpha.ts +166 -0
  116. package/src/render/material-key.ts +60 -0
  117. package/src/render/mesh-pool.ts +144 -0
  118. package/src/render/probe-volume.ts +1668 -0
  119. package/src/render/resolution-subrect.ts +253 -0
  120. package/src/render/velocity.ts +442 -0
  121. package/src/render/virtual-shadow-pages.ts +827 -0
  122. package/src/render/virtual-shadow-partial.ts +174 -0
  123. package/src/render/virtual-shadow.ts +3330 -0
  124. package/src/render/world-impostor-surface.ts +722 -0
  125. package/src/render/world-impostor.ts +558 -0
  126. package/src/render-camera-cull.ts +441 -0
  127. package/src/render-pass-budget.ts +501 -0
  128. package/src/renderProjection.ts +758 -0
  129. package/src/renderer-config.ts +127 -0
  130. package/src/renderer.ts +1847 -0
  131. package/src/replay-protocol.ts +85 -0
  132. package/src/replay.ts +205 -0
  133. package/src/resolution-scaler.ts +819 -0
  134. package/src/rig-preparation.ts +271 -0
  135. package/src/ripple-field.ts +432 -0
  136. package/src/scale.ts +109 -0
  137. package/src/scene.ts +239 -0
  138. package/src/schedule.ts +155 -0
  139. package/src/skeletal-mesh.ts +61 -0
  140. package/src/skeleton.ts +100 -0
  141. package/src/snow-field.ts +744 -0
  142. package/src/softbody-topology.ts +269 -0
  143. package/src/softbody.ts +516 -0
  144. package/src/sprite-animator.ts +222 -0
  145. package/src/startup-readiness.ts +386 -0
  146. package/src/state.ts +66 -0
  147. package/src/static-transform.ts +274 -0
  148. package/src/storage-buffer.ts +253 -0
  149. package/src/streaming.ts +308 -0
  150. package/src/target-fps.ts +92 -0
  151. package/src/terrain-jobs-worker.ts +17 -0
  152. package/src/terrain-jobs.ts +353 -0
  153. package/src/textures.ts +39 -0
  154. package/src/tracers.ts +237 -0
  155. package/src/ui-bridge.ts +368 -0
  156. package/src/ui-hit-regions.ts +380 -0
  157. package/src/ui-layer.ts +83 -0
  158. package/src/ui-state.ts +220 -0
  159. package/src/version.ts +2 -0
  160. package/src/viewport.ts +253 -0
  161. package/src/warmup.ts +1357 -0
  162. package/src/water-surface.ts +384 -0
  163. package/src/wave-field.ts +524 -0
  164. package/src/world-capabilities.ts +131 -0
  165. package/src/world-cell-proxy.ts +392 -0
  166. package/src/world-cells.ts +10564 -0
  167. package/src/world-gpu-scene.ts +3354 -0
  168. package/src/world-heightmap.ts +82 -0
  169. package/src/world-package.ts +469 -0
  170. package/src/world-passes.ts +582 -0
  171. package/src/world-region.ts +17 -0
  172. package/src/world-terrain-splat.ts +564 -0
  173. package/src/world-tiles.ts +3826 -0
  174. package/src/world-topology.ts +370 -0
  175. package/src/world-validate.ts +48 -0
  176. package/src/world.ts +805 -0
@@ -0,0 +1,245 @@
1
+ import { Object3D } from "three";
2
+ import { SPANS, beginSpan, endSpan } from "./profiling/Spans.js";
3
+ import { isStatic } from "./static-transform.js";
4
+
5
+ /**
6
+ * The per-frame world-matrix walk, with a hidden subtree left where it stands.
7
+ *
8
+ * `three`'s `Object3D.updateMatrixWorld` recurses into every child of every node whatever its
9
+ * `visible` flag, multiplying a world matrix for each. That is the correct default for a library
10
+ * that cannot know what a game is doing, and it is the wrong one for a renderer that is about to
11
+ * skip exactly those subtrees: a full-detail body while its merged stand-in draws, a hidden LOD
12
+ * level, a parked or hangared model each pay the walk and none of them can draw.
13
+ *
14
+ * Native flight in `sandbox/midway-open-pacific` profiled `updateMatrixWorld` plus
15
+ * `multiplyMatrices` at **29 % of all JavaScript ticks**, and the same scene's hand-rolled
16
+ * visible-only pass walked **779 nodes per frame instead of 9,903**, 3.1 ms down to 0.3 ms. That
17
+ * pass was the game's; this is the engine's, so the next game does not write it again.
18
+ *
19
+ * The pass mirrors three exactly for a visible node: `matrixAutoUpdate` -> `updateMatrix()`, then
20
+ * the `matrixWorldNeedsUpdate || force` recompute honouring `matrixWorldAutoUpdate` and a null
21
+ * parent, then force the children. A node with `visible === false` defers its own compose and its
22
+ * subtree's walk. Every skipped root is remembered, so the first frame it is visible again both
23
+ * its own world matrix and its descendants are recomputed with `force = true`.
24
+ *
25
+ * Two things are never dropped by the pruning, because both are read while nothing above them is
26
+ * visible:
27
+ *
28
+ * - a class that overrides `updateMatrixWorld` runs its own — never a `Scene`, which three does not
29
+ * override and whose method only differs when something patched the prototype. `SkinnedMesh`
30
+ * refreshes `bindMatrixInverse`, `Camera` its `matrixWorldInverse`; re-implementing only the base
31
+ * walk left every deck-crew sailor that had moved since load drawing with a stale bind matrix and
32
+ * vanishing from the frame. Their subtrees are small, so walking them whole costs nothing;
33
+ * - a hidden node that holds a `Bone` is walked, because a visible `SkinnedMesh` draws with its
34
+ * skeleton's matrices wherever the armature happens to sit. Whether bones sit below a node is
35
+ * decided once and remembered — a rig is built whole and does not grow.
36
+ *
37
+ * A third thing is dropped, and it is the walk's largest single share on a streamed world: a subtree
38
+ * frozen with `markStatic`. `markStatic` composes the subtree once and turns off the two flags that
39
+ * would recompose it, which until now still left three's unconditional recursion visiting every node
40
+ * under it every frame. A frozen root that carries no dirty flag is a leaf here, and it is one
41
+ * whether the walk was forced or not: `refreshStaticTransforms` re-arms a root whose own transform
42
+ * moved, `invalidateStatic` re-arms one something wrote inside, and both compose the subtree once at
43
+ * that moment. `isStatic` is what separates the engine's freeze from a game that turned the flags off
44
+ * for its own reasons. See `static-transform.ts`.
45
+ *
46
+ * Where the root is a native-engine object it has its own walk, `__tnUpdateMatrixWorld(force, prune)`: this
47
+ * pass run natively in one call, answering the nodes it visited. The pass calls that and nothing else, since the
48
+ * walk above costs a bridge call per node read and written (about 16 to 25 thousand a frame at 4,096 cubes).
49
+ * With `prune` (the `"visible"` mode) the native walk leaves a hidden subtree where it stands by the same rules,
50
+ * bones included; `"all"` visits every node. A JS subclass of `Object3D` that overrides `updateMatrixWorld` is not
51
+ * called from inside it; the engine's own `SkinnedMesh` and `Camera` keep their derived matrices. The web and the
52
+ * legacy host have no such method and walk as above.
53
+ *
54
+ * A game that reads a **hidden** object's `matrixWorld` directly must not rely on this pass
55
+ * having reached it: use `getWorldPosition`/`getWorldQuaternion`/`getWorldScale` (which update the
56
+ * chain they need) or call `object.updateWorldMatrix(true, false)` first. The convention's named
57
+ * override is `renderer.matrixWorld: "all"`, which visits every node exactly as three's own walk
58
+ * does; `"visible"` is the default.
59
+ */
60
+
61
+ /** How much of the scene graph the engine walks for world matrices each frame. */
62
+ export type MatrixWorldMode = "visible" | "all";
63
+
64
+ /** The shipping default: a hidden subtree is not walked. */
65
+ export const DEFAULT_MATRIX_WORLD_MODE: MatrixWorldMode = "visible";
66
+
67
+ /** What the pass did on the last frame, for the frame telemetry a window reports. */
68
+ export interface IMatrixWorldReport {
69
+ readonly schemaVersion: 1;
70
+ readonly mode: MatrixWorldMode;
71
+ /**
72
+ * Nodes the engine walked this frame, summed over every application (authored scene and a
73
+ * projection mirror when one is in use). One number both ways, so `"all"` can be read as the
74
+ * cost of the walk the convention just removed.
75
+ */
76
+ readonly visited: number;
77
+ }
78
+
79
+ export interface IMatrixWorldOptions {
80
+ /** `"visible"` (default) skips a hidden subtree; `"all"` reproduces three's own walk. */
81
+ readonly mode?: MatrixWorldMode;
82
+ }
83
+
84
+ /** What a native-engine root offers: the whole walk in one call, answering the nodes it covered. */
85
+ type NativeWalk = (this: Object3D, force: boolean, prune: boolean) => number;
86
+
87
+ /** The base walk, to tell a class that overrides `updateMatrixWorld` (SkinnedMesh, Camera) apart. */
88
+ const BASE_UPDATE_MATRIX_WORLD = Object3D.prototype.updateMatrixWorld;
89
+
90
+ /**
91
+ * Whether this node's own `updateMatrixWorld` must run instead of this walk.
92
+ *
93
+ * A `Scene` never does: three does not override the walk on `Scene`, so a scene whose method is not
94
+ * the base one has had its prototype patched — the frame spans time the render phase's walk by
95
+ * wrapping `Scene.prototype.updateMatrixWorld` — or a game has subclassed `Scene`. Reading that as
96
+ * "a class that owns its walk" handed the whole scene to three's own recursion, and three's
97
+ * recursion prunes nothing: the visible-only pass and every frozen subtree stopped mattering for as
98
+ * long as the frame spans were on, which is how they are measured. The trade is a game that
99
+ * subclasses `Scene` *and* overrides the walk, which no template does; it is walked by this pass
100
+ * instead, which is the same walk minus the pruning.
101
+ */
102
+ function ownsItsWalk(root: Object3D): boolean {
103
+ if ((root as Object3D & { isScene?: boolean }).isScene === true) return false;
104
+ return root.updateMatrixWorld !== BASE_UPDATE_MATRIX_WORLD;
105
+ }
106
+
107
+ /**
108
+ * `three`'s own world-matrix compose, verbatim: recompute when the node is dirty or the walk is
109
+ * forced, honour `matrixWorldAutoUpdate` and a null parent, then clear the dirty flag.
110
+ *
111
+ * Answers whether the node's world matrix was recomposed, which is what makes its subtree dirty.
112
+ */
113
+ function composeWorld(root: Object3D, force: boolean): boolean {
114
+ if (!(root.matrixWorldNeedsUpdate || force)) return false;
115
+ if (root.matrixWorldAutoUpdate === true) {
116
+ if (root.parent === null) root.matrixWorld.copy(root.matrix);
117
+ else root.matrixWorld.multiplyMatrices(root.parent.matrixWorld, root.matrix);
118
+ }
119
+ root.matrixWorldNeedsUpdate = false;
120
+ return true;
121
+ }
122
+
123
+ /**
124
+ * Whether the walk can stop here, because the subtree's world matrices were composed when the engine
125
+ * placed it and only a write inside could change them.
126
+ *
127
+ * `isStatic` is what separates the engine's freeze from a game that turned the flags off itself, and
128
+ * a dirty flag means someone has written to this node since. A forced walk does not change the
129
+ * answer: `composeWorld` has already run, and a frozen root silences its own world compose, so three
130
+ * would carry the force down the subtree and recompute nothing at the end of it.
131
+ */
132
+ function frozenLeaf(root: Object3D): boolean {
133
+ return root.matrixWorldNeedsUpdate === false && isStatic(root);
134
+ }
135
+
136
+ function resolveMode(mode: MatrixWorldMode | undefined): MatrixWorldMode {
137
+ if (mode === undefined) return DEFAULT_MATRIX_WORLD_MODE;
138
+ if (mode !== "visible" && mode !== "all")
139
+ throw new Error(
140
+ `renderer.matrixWorld must be "visible" or "all", received ${JSON.stringify(mode)}.`,
141
+ );
142
+ return mode;
143
+ }
144
+
145
+ /**
146
+ * One game's world-matrix walk, holding the state the pruning needs between frames.
147
+ *
148
+ * The stale set and the bone cache live on the instance rather than in module scope: two games,
149
+ * two playtest scenarios or two roots in one process must not share "this subtree was skipped
150
+ * while hidden", or one game's hidden node would be force-refreshed by the other's frame.
151
+ */
152
+ export class MatrixWorldPass {
153
+ readonly #mode: MatrixWorldMode;
154
+ /** Hidden nodes whose own matrix was forced, waiting for the frame they show again. */
155
+ readonly #stale = new WeakSet<Object3D>();
156
+ /** Whether a `Bone` sits anywhere under a node, decided once and remembered. */
157
+ readonly #bones = new WeakMap<Object3D, boolean>();
158
+ #visited = 0;
159
+
160
+ constructor(options: IMatrixWorldOptions = {}) {
161
+ this.#mode = resolveMode(options.mode);
162
+ }
163
+
164
+ get mode(): MatrixWorldMode {
165
+ return this.#mode;
166
+ }
167
+
168
+ /** What the current frame has walked so far, across every {@link apply} call. */
169
+ get report(): IMatrixWorldReport {
170
+ return { schemaVersion: 1, mode: this.#mode, visited: this.#visited };
171
+ }
172
+
173
+ /** Starts a frame's count. The pass's state (stale set, bone cache) is untouched. */
174
+ beginFrame(): void {
175
+ this.#visited = 0;
176
+ }
177
+
178
+ /**
179
+ * Walks `root`, mirroring three for every node the mode visits.
180
+ *
181
+ * Returns the nodes this call visited, so a caller can report one application's cost without
182
+ * also reporting the frame's total.
183
+ */
184
+ apply(root: Object3D, force = false): number {
185
+ const before = this.#visited;
186
+ beginSpan(SPANS.sceneUpdate);
187
+ try {
188
+ const native = (root as Object3D & { __tnUpdateMatrixWorld?: NativeWalk })
189
+ .__tnUpdateMatrixWorld;
190
+ if (typeof native === "function")
191
+ this.#visited += native.call(root, force, this.#mode === "visible");
192
+ else this.#step(root, force, this.#mode === "visible");
193
+ } finally {
194
+ endSpan(SPANS.sceneUpdate);
195
+ }
196
+ return this.#visited - before;
197
+ }
198
+
199
+ /** Forgets what was skipped. A whole-scene swap has no hidden ancestors left to refresh. */
200
+ dispose(): void {
201
+ this.#visited = 0;
202
+ }
203
+
204
+ #step(root: Object3D, force: boolean, prune: boolean): void {
205
+ this.#visited += 1;
206
+ // A class that extends the walk runs its own, so `SkinnedMesh.bindMatrixInverse` and
207
+ // `Camera.matrixWorldInverse` stay as fresh as the world matrix they derive from.
208
+ if (ownsItsWalk(root)) {
209
+ const stale = this.#stale.delete(root);
210
+ root.updateMatrixWorld(force || stale);
211
+ return;
212
+ }
213
+ // Nothing here can draw. Remember even a clean root: local or ancestor transforms can change
214
+ // while it is hidden without leaving a world-matrix dirty flag on this node.
215
+ if (prune && root.visible === false && !this.#holdsBones(root)) {
216
+ this.#stale.add(root);
217
+ return;
218
+ }
219
+ const stale = this.#stale.delete(root);
220
+ if (root.matrixAutoUpdate) root.updateMatrix();
221
+ const childForce = composeWorld(root, force || stale) || force || stale;
222
+ // The frozen subtree's world matrices were composed when the engine placed it, and only a write
223
+ // to something in it can change them: `refreshStaticTransforms` re-arms a frozen root whose own
224
+ // transform moved, and `invalidateStatic` re-arms one something wrote inside. Both compose the
225
+ // subtree once, at that moment, so the frames in between have nothing to recompute — which is
226
+ // what makes the recursion here worth stopping.
227
+ if (frozenLeaf(root)) return;
228
+ const children = root.children;
229
+ for (let index = 0, length = children.length; index < length; index += 1) {
230
+ this.#step(children[index] as Object3D, childForce, prune);
231
+ }
232
+ }
233
+
234
+ #holdsBones(node: Object3D): boolean {
235
+ let known = this.#bones.get(node);
236
+ if (known === undefined) {
237
+ known = false;
238
+ node.traverse((object) => {
239
+ if ((object as Object3D & { isBone?: boolean }).isBone === true) known = true;
240
+ });
241
+ this.#bones.set(node, known);
242
+ }
243
+ return known;
244
+ }
245
+ }