@threenative/core 0.3.11 → 0.3.12

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 (157) hide show
  1. package/capabilities.json +1096 -26
  2. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  3. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-CWuFRT7G.d.ts} +1 -1
  4. package/dist/chunk-2Z44XSI2.js +35 -0
  5. package/dist/chunk-5O73CDMR.js +1849 -0
  6. package/dist/chunk-6KLNISRJ.js +153 -0
  7. package/dist/chunk-7UUT3TY5.js +133 -0
  8. package/dist/chunk-CFGTPFUH.js +231 -0
  9. package/dist/chunk-DBELTTTM.js +615 -0
  10. package/dist/chunk-GMHATRPW.js +7701 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-KIRUKTBQ.js +187 -0
  13. package/dist/chunk-N5LRP4BR.js +220 -0
  14. package/dist/chunk-OKXUCASC.js +2238 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-VAZM36TV.js +497 -0
  17. package/dist/{game-DzMcitDO.d.ts → game-D7pAzZUY.d.ts} +15 -3
  18. package/dist/hot.d.ts +3 -3
  19. package/dist/hot.js +2 -46
  20. package/dist/index.d.ts +329 -302
  21. package/dist/index.js +10566 -22552
  22. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-B6BMqS1r.d.ts} +33 -3
  23. package/dist/playtest.d.ts +3 -3
  24. package/dist/playtest.js +24 -75
  25. package/dist/react-css.js +1 -215
  26. package/dist/react.d.ts +2 -2
  27. package/dist/{renderer-rZm0hVqq.d.ts → renderer-DvFVoAgj.d.ts} +13 -4
  28. package/dist/spells/index.d.ts +643 -0
  29. package/dist/spells/index.js +1558 -0
  30. package/dist/spells/ultra/index.d.ts +1600 -0
  31. package/dist/spells/ultra/index.js +6804 -0
  32. package/dist/terrain-jobs-worker.js +1 -123
  33. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  34. package/dist/ui-layer.js +5 -384
  35. package/dist/worker.js +4 -41
  36. package/dist/world.d.ts +725 -259
  37. package/dist/world.js +16714 -18284
  38. package/mcp/animation-server.mjs +1 -1
  39. package/mcp/animation.mjs +2 -3
  40. package/mcp/engine-server.mjs +142 -47
  41. package/mcp/servers.mjs +9 -2
  42. package/mcp/terrain.mjs +8 -0
  43. package/package.json +14 -6
  44. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  45. package/patches/three@0.187.0.patch +2004 -407
  46. package/src/assets.ts +9 -2
  47. package/src/card-lod.ts +152 -0
  48. package/src/compressed-texture-preparation.ts +1008 -0
  49. package/src/frame-budget.ts +31 -20
  50. package/src/game-dev-tools.ts +93 -0
  51. package/src/game-frame-loop.ts +995 -0
  52. package/src/game-renderer-metrics.ts +77 -0
  53. package/src/game-startup.ts +1001 -0
  54. package/src/game-validate.ts +70 -0
  55. package/src/game.ts +253 -1935
  56. package/src/index.ts +27 -2
  57. package/src/launch-diagnostics.ts +22 -12
  58. package/src/look/ao-admission.ts +24 -0
  59. package/src/look/filmic-tone-mapping.ts +15 -13
  60. package/src/look/look-diagnostics.ts +3 -3
  61. package/src/look/quality.ts +10 -5
  62. package/src/look/world-environment.ts +76 -9
  63. package/src/loop.ts +29 -0
  64. package/src/model-lod.ts +42 -3
  65. package/src/particle-kinds.ts +515 -0
  66. package/src/picking.ts +17 -3
  67. package/src/playtest.ts +27 -1
  68. package/src/projection-apply.ts +4 -1
  69. package/src/projection-plan.ts +9 -6
  70. package/src/render/mesh-pool.ts +1 -1
  71. package/src/render/resolution-subrect.ts +2 -0
  72. package/src/render/rough-diffuse.ts +46 -12
  73. package/src/render/soft-shadow.ts +27 -12
  74. package/src/render/virtual-shadow-adaptive.ts +55 -0
  75. package/src/render/virtual-shadow-casters.ts +175 -0
  76. package/src/render/virtual-shadow-layers.ts +76 -0
  77. package/src/render/virtual-shadow-level.ts +224 -0
  78. package/src/render/virtual-shadow-markers.ts +193 -0
  79. package/src/render/virtual-shadow-options.ts +370 -0
  80. package/src/render/virtual-shadow-pages.ts +5 -0
  81. package/src/render/virtual-shadow.ts +213 -992
  82. package/src/render/world-impostor-surface.ts +293 -34
  83. package/src/render-pass-budget.ts +34 -7
  84. package/src/renderProjection.ts +22 -0
  85. package/src/renderer.ts +92 -37
  86. package/src/snow-field.ts +1 -1
  87. package/src/spells/cast-pool.ts +361 -0
  88. package/src/spells/index.ts +177 -0
  89. package/src/spells/mechanisms.ts +295 -0
  90. package/src/spells/reaction-field.ts +415 -0
  91. package/src/spells/spell-lights.ts +139 -0
  92. package/src/spells/spell-world.ts +187 -0
  93. package/src/spells/spell.ts +397 -0
  94. package/src/spells/spells.ts +283 -0
  95. package/src/spells/ultra/engine/camera.ts +184 -0
  96. package/src/spells/ultra/engine/quality.ts +96 -0
  97. package/src/spells/ultra/index.ts +52 -0
  98. package/src/spells/ultra/main.ts +305 -0
  99. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  100. package/src/spells/ultra/spells/cast.ts +233 -0
  101. package/src/spells/ultra/spells/fire.ts +1267 -0
  102. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  103. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  104. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  105. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  106. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  107. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  108. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  109. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  110. package/src/spells/ultra/vfx/common.ts +1195 -0
  111. package/src/spells/ultra/vfx/noise.ts +441 -0
  112. package/src/startup-readiness.ts +128 -34
  113. package/src/version.ts +1 -1
  114. package/src/warmup.ts +56 -8
  115. package/src/water-surface.ts +9 -3
  116. package/src/world-bundle-safety.ts +401 -0
  117. package/src/world-cell-batches.ts +1216 -0
  118. package/src/world-cell-chunks.ts +1132 -0
  119. package/src/world-cell-data.ts +995 -0
  120. package/src/world-cell-impostors.ts +1449 -0
  121. package/src/world-cell-lod-bias.ts +151 -0
  122. package/src/world-cell-models.ts +1074 -0
  123. package/src/world-cell-options.ts +189 -0
  124. package/src/world-cell-placements.ts +694 -0
  125. package/src/world-cell-prewarm.ts +557 -0
  126. package/src/world-cell-readiness.ts +357 -0
  127. package/src/world-cell-render-bundles.ts +459 -0
  128. package/src/world-cell-render-gpu-dress.ts +714 -0
  129. package/src/world-cell-render-main-cull.ts +484 -0
  130. package/src/world-cell-render-shadow-claims.ts +198 -0
  131. package/src/world-cell-render-util.ts +246 -0
  132. package/src/world-cell-render.ts +1493 -0
  133. package/src/world-cell-residency.ts +745 -0
  134. package/src/world-cells.ts +1318 -10418
  135. package/src/world-chunk-shadow.ts +308 -0
  136. package/src/world-collar.ts +315 -0
  137. package/src/world-gpu-flags.ts +163 -0
  138. package/src/world-gpu-readback.ts +881 -0
  139. package/src/world-gpu-reference.ts +510 -0
  140. package/src/world-gpu-scene.ts +214 -2264
  141. package/src/world-gpu-shadow.ts +190 -0
  142. package/src/world-gpu-types.ts +381 -0
  143. package/src/world-gpu-validation.ts +518 -0
  144. package/src/world-heightfield.ts +802 -0
  145. package/src/world-load-limiter.ts +106 -0
  146. package/src/world-noise.ts +241 -0
  147. package/src/world-package.ts +42 -0
  148. package/src/world-region.ts +1 -1
  149. package/src/world-terrain-splat.ts +365 -149
  150. package/src/world-tile-budget.ts +256 -0
  151. package/src/world-tile-geometry.ts +469 -0
  152. package/src/world-tile-lod.ts +408 -0
  153. package/src/world-tile-observation.ts +566 -0
  154. package/src/world-tile-stitch.ts +166 -0
  155. package/src/world-tiles.ts +170 -1745
  156. package/src/world-water-bodies.ts +359 -0
  157. package/src/world.ts +35 -741
@@ -0,0 +1,94 @@
1
+ // src/gpu-readback.ts
2
+ var GPUReadback = class {
3
+ everyFrames;
4
+ #attribute;
5
+ /** Frames observed through `request()`. The clock every other number here is measured against. */
6
+ #frame = 0;
7
+ /** The frame whose GPU state the landed bytes hold, or `-1` when nothing has landed. */
8
+ #sampleFrame = -1;
9
+ /** The frame the in-flight request was issued on, or `-1` when none is in flight. */
10
+ #requestedFrame = -1;
11
+ #pending = false;
12
+ #data;
13
+ #requests = 0;
14
+ #lands = 0;
15
+ #failures = 0;
16
+ #released = false;
17
+ constructor(options) {
18
+ if (options.attribute === void 0 || options.attribute === null)
19
+ throw new Error("GPUReadback.attribute is required.");
20
+ if (!Number.isInteger(options.everyFrames) || options.everyFrames <= 0)
21
+ throw new Error("GPUReadback.everyFrames must be a positive integer.");
22
+ this.#attribute = options.attribute;
23
+ this.everyFrames = options.everyFrames;
24
+ }
25
+ get released() {
26
+ return this.#released;
27
+ }
28
+ /** True while a copy is in flight. A game that wants to pace its own work can read it. */
29
+ get pending() {
30
+ return this.#pending;
31
+ }
32
+ /** The newest landed bytes, or `undefined` before the first copy lands. */
33
+ get data() {
34
+ return this.#data;
35
+ }
36
+ /**
37
+ * How many frames old the landed bytes are.
38
+ *
39
+ * Before anything has landed this is the number of frames since construction, which grows
40
+ * without bound on purpose: "no data yet" and "data from frame zero" must not read the same.
41
+ */
42
+ get staleFrames() {
43
+ if (this.#sampleFrame < 0) return this.#frame;
44
+ return this.#frame - this.#sampleFrame;
45
+ }
46
+ /** The newest bytes with their age attached, or `undefined` before the first copy lands. */
47
+ get sample() {
48
+ if (this.#data === void 0) return void 0;
49
+ return { data: this.#data, staleFrames: this.staleFrames };
50
+ }
51
+ /** Requests, landings and failures, for a report that has to say why a sample is old. */
52
+ get stats() {
53
+ return { requests: this.#requests, lands: this.#lands, failures: this.#failures };
54
+ }
55
+ /**
56
+ * Advances the frame clock and starts a copy when the throttle allows one.
57
+ *
58
+ * Safe to call every frame. It returns before the GPU has answered — awaiting it is the one
59
+ * thing that would turn this class into the stall it exists to avoid.
60
+ */
61
+ request(renderer) {
62
+ if (this.#released) throw new Error("GPUReadback cannot request after release.");
63
+ this.#frame += 1;
64
+ if (this.#pending) return;
65
+ if (this.#requestedFrame >= 0 && this.#frame - this.#requestedFrame < this.everyFrames) return;
66
+ const issuedFrame = this.#frame;
67
+ this.#requestedFrame = issuedFrame;
68
+ this.#pending = true;
69
+ this.#requests += 1;
70
+ renderer.readback(this.#attribute).then((bytes) => this.#land(bytes, issuedFrame)).catch(() => this.#fail());
71
+ }
72
+ #land(bytes, issuedFrame) {
73
+ this.#pending = false;
74
+ if (this.#released) return;
75
+ this.#data = new Float32Array(bytes);
76
+ this.#sampleFrame = issuedFrame;
77
+ this.#lands += 1;
78
+ }
79
+ #fail() {
80
+ this.#pending = false;
81
+ if (this.#released) return;
82
+ this.#failures += 1;
83
+ }
84
+ /** Drops the attribute reference and the landed bytes. Further requests throw. */
85
+ dispose() {
86
+ if (this.#released) return;
87
+ this.#released = true;
88
+ this.#pending = false;
89
+ this.#attribute = void 0;
90
+ this.#data = void 0;
91
+ }
92
+ };
93
+
94
+ export { GPUReadback };
@@ -0,0 +1,497 @@
1
+ import { GPUReadback } from './chunk-QWJEMUUT.js';
2
+ import { Box3, Matrix4, Frustum, Sphere, Vector3, Sprite } from 'three';
3
+ import { instancedArray, deltaTime, time, Fn, vec3, Loop, instanceIndex, min, max, vec4, uniform, If, uint } from 'three/tsl';
4
+
5
+ var CameraShake = class {
6
+ amplitude;
7
+ rotationAmplitude;
8
+ frequency;
9
+ decay;
10
+ curve;
11
+ offset = {
12
+ position: new Vector3(),
13
+ rotation: new Vector3()
14
+ };
15
+ #active = false;
16
+ #elapsed = 0;
17
+ constructor(options) {
18
+ if (options === void 0 || options === null || options.amplitude === void 0)
19
+ throw new Error("CameraShake.amplitude is required.");
20
+ if (options.rotationAmplitude === void 0)
21
+ throw new Error("CameraShake.rotationAmplitude is required.");
22
+ validateVector(options.amplitude, "CameraShake.amplitude");
23
+ validateVector(options.rotationAmplitude, "CameraShake.rotationAmplitude");
24
+ if (!Number.isFinite(options.frequency) || options.frequency <= 0)
25
+ throw new Error("CameraShake.frequency must be positive and finite.");
26
+ if (!Number.isFinite(options.decay) || options.decay <= 0)
27
+ throw new Error("CameraShake.decay must be positive and finite.");
28
+ if (typeof options.curve !== "function") throw new Error("CameraShake.curve is required.");
29
+ this.amplitude = options.amplitude.clone();
30
+ this.rotationAmplitude = options.rotationAmplitude.clone();
31
+ this.frequency = options.frequency;
32
+ this.decay = options.decay;
33
+ this.curve = options.curve;
34
+ }
35
+ get active() {
36
+ return this.#active;
37
+ }
38
+ get elapsed() {
39
+ return this.#elapsed;
40
+ }
41
+ /** Start or restart the authored shake waveform. */
42
+ trigger() {
43
+ this.#elapsed = 0;
44
+ this.#active = true;
45
+ this.#clearOffset();
46
+ return this;
47
+ }
48
+ /** Stop the effect and clear the offset. */
49
+ stop() {
50
+ this.#active = false;
51
+ this.#elapsed = 0;
52
+ this.#clearOffset();
53
+ return this;
54
+ }
55
+ /** Evaluate the current offset and advance by one caller-supplied fixed-step delta. */
56
+ update(dt) {
57
+ if (!Number.isFinite(dt) || dt < 0)
58
+ throw new Error("CameraShake.update delta must be finite and non-negative.");
59
+ if (!this.#active) {
60
+ this.#clearOffset();
61
+ return this.offset;
62
+ }
63
+ const envelope = Math.exp(-this.decay * this.#elapsed);
64
+ const phase = this.#elapsed * this.frequency * Math.PI * 2;
65
+ const sample = this.curve(phase);
66
+ if (!Number.isFinite(sample)) throw new Error("CameraShake.curve must return a finite number.");
67
+ this.offset.position.copy(this.amplitude).multiplyScalar(sample * envelope);
68
+ this.offset.rotation.copy(this.rotationAmplitude).multiplyScalar(sample * envelope);
69
+ this.#elapsed += dt;
70
+ if (!Number.isFinite(this.#elapsed)) throw new Error("CameraShake elapsed time overflowed.");
71
+ if (Math.exp(-this.decay * this.#elapsed) <= Number.EPSILON) this.#active = false;
72
+ return this.offset;
73
+ }
74
+ #clearOffset() {
75
+ this.offset.position.set(0, 0, 0);
76
+ this.offset.rotation.set(0, 0, 0);
77
+ }
78
+ };
79
+ function validateVector(value, name) {
80
+ if (value === void 0 || value === null || ![value.x, value.y, value.z].every(Number.isFinite))
81
+ throw new Error(`${name} must contain finite components.`);
82
+ }
83
+ var DEAD_BIRTH = -1e6;
84
+ var LANES = 256;
85
+ var worldBox = new Box3();
86
+ var viewProjection = new Matrix4();
87
+ var frustum = new Frustum();
88
+ var sphere = new Sphere();
89
+ var cameraPosition = new Vector3();
90
+ function foldBounds(data) {
91
+ if (data.length === 0 || data.length % 8 !== 0 || !data.every(Number.isFinite)) return void 0;
92
+ const lanes = data.length / 8;
93
+ const box = new Box3();
94
+ for (let lane = 0; lane < lanes; lane += 1) {
95
+ const lo = lane * 4;
96
+ const hi = (lane + lanes) * 4;
97
+ const lowX = data[lo];
98
+ const highX = data[hi];
99
+ if (lowX === void 0 || highX === void 0) return void 0;
100
+ if (lowX > highX) continue;
101
+ for (let axis = 0; axis < 3; axis += 1) {
102
+ const low = data[lo + axis];
103
+ const high = data[hi + axis];
104
+ if (low === void 0 || high === void 0) return void 0;
105
+ box.min.setComponent(axis, Math.min(box.min.getComponent(axis), low));
106
+ box.max.setComponent(axis, Math.max(box.max.getComponent(axis), high));
107
+ }
108
+ }
109
+ return box.isEmpty() ? void 0 : box;
110
+ }
111
+ function computeNode(name, value) {
112
+ if (value === null || typeof value !== "object" || value.isComputeNode !== true) {
113
+ throw new Error(`GPUParticles3D.${name} must return a TSL compute node.`);
114
+ }
115
+ return value;
116
+ }
117
+ function finite(name, value) {
118
+ if (!Number.isFinite(value)) throw new Error(`GPUParticles3D.${name} must be a finite number.`);
119
+ return value;
120
+ }
121
+ function setVector(uniformNode, name, v) {
122
+ const target = uniformNode.value;
123
+ if (v === void 0) return void target.set(0, 0, 0);
124
+ target.set(finite(`${name}.x`, v.x), finite(`${name}.y`, v.y), finite(`${name}.z`, v.z));
125
+ }
126
+ var GPUParticles3D = class extends Sprite {
127
+ amount;
128
+ buffers;
129
+ processCadence = "render";
130
+ warmupNodes;
131
+ localCoords;
132
+ emitting = true;
133
+ #start;
134
+ #process;
135
+ #spawn;
136
+ #renderer;
137
+ #released = false;
138
+ #lifetime;
139
+ #maxPerFrame;
140
+ #cursor = 0;
141
+ #spawnedThisFrame = 0;
142
+ #seed = 0;
143
+ #clamped = 0;
144
+ #spawned = 0;
145
+ #recycledLive = 0;
146
+ #warned = false;
147
+ /** Recent requests: wall-clock second, first ring sequence number, count. Pruned past `lifetime`. */
148
+ #log = [];
149
+ #boundsOverride;
150
+ #measuredBounds;
151
+ #padding;
152
+ #onCull;
153
+ #graceSeconds = 1;
154
+ #boundsEveryFrames;
155
+ #partials;
156
+ #reduce;
157
+ #readback;
158
+ #frame = 0;
159
+ #lastMeasure = 0;
160
+ #lands = 0;
161
+ #dispatches = 0;
162
+ #outsideSince;
163
+ #authoredVisible = true;
164
+ #hiddenByCull = false;
165
+ #yielded = false;
166
+ #state = "running";
167
+ #reason;
168
+ #transitions = 0;
169
+ /** Cooperate with measured frame-budget shedding without changing particle storage. */
170
+ budget = {
171
+ significance: (camera) => {
172
+ if (this.#released || !this.emitting || !this.#authoredVisible || this.castShadow || this.#reason === "outside-view")
173
+ return void 0;
174
+ this.updateWorldMatrix(true, false);
175
+ if (camera.matrixWorldAutoUpdate) camera.updateMatrixWorld();
176
+ if (this.measuredBounds === void 0) {
177
+ sphere.center.setFromMatrixPosition(this.matrixWorld);
178
+ sphere.radius = 0;
179
+ } else {
180
+ this.measuredBounds.getBoundingSphere(sphere).applyMatrix4(this.matrixWorld);
181
+ }
182
+ cameraPosition.setFromMatrixPosition(camera.matrixWorld);
183
+ return (sphere.radius + this.#worldPadding) / Math.max(sphere.center.distanceTo(cameraPosition), 1e-3);
184
+ },
185
+ yield: (yielded) => {
186
+ this.#yielded = yielded;
187
+ }
188
+ };
189
+ constructor(options) {
190
+ if (!Number.isInteger(options.amount) || options.amount <= 0)
191
+ throw new Error("GPUParticles3D.amount must be a positive integer.");
192
+ if (options.material === void 0) throw new Error("GPUParticles3D.material is required.");
193
+ if (options.spawn !== void 0 && typeof options.spawn !== "function")
194
+ throw new Error("GPUParticles3D.spawn must be a function.");
195
+ if (options.start !== void 0 || options.spawn === void 0) {
196
+ if (typeof options.start !== "function")
197
+ throw new Error("GPUParticles3D.start must be a function.");
198
+ }
199
+ if (typeof options.process !== "function")
200
+ throw new Error("GPUParticles3D.process must be a function.");
201
+ if (options.lifetime !== void 0 && !(options.lifetime > 0))
202
+ throw new Error("GPUParticles3D.lifetime must be a positive number.");
203
+ const maxPerFrame = options.maxSpawnPerFrame ?? options.amount;
204
+ if (!Number.isInteger(maxPerFrame) || maxPerFrame <= 0)
205
+ throw new Error("GPUParticles3D.maxSpawnPerFrame must be a positive integer.");
206
+ const boundsEveryFrames = options.boundsEveryFrames ?? 8;
207
+ if (!Number.isInteger(boundsEveryFrames) || boundsEveryFrames <= 0)
208
+ throw new Error("GPUParticles3D.boundsEveryFrames must be a positive integer.");
209
+ if (options.padding !== void 0 && (!Number.isFinite(options.padding) || options.padding < 0))
210
+ throw new Error("GPUParticles3D.padding must be finite and non-negative.");
211
+ if (options.onCull !== void 0 && options.onCull !== "pause" && options.onCull !== "clear")
212
+ throw new Error("GPUParticles3D.onCull must be pause or clear.");
213
+ if (options.bounds !== void 0 && (options.bounds.isBox3 !== true || options.bounds.isEmpty() || ![...options.bounds.min.toArray(), ...options.bounds.max.toArray()].every(Number.isFinite)))
214
+ throw new Error("GPUParticles3D.bounds must be a finite, non-empty Box3.");
215
+ super(options.material);
216
+ Object.defineProperty(this, "visible", {
217
+ configurable: true,
218
+ enumerable: true,
219
+ get: () => this.#authoredVisible && !this.#hiddenByCull,
220
+ set: (visible) => {
221
+ this.#authoredVisible = visible;
222
+ }
223
+ });
224
+ this.#boundsOverride = options.bounds;
225
+ this.#padding = options.padding;
226
+ this.#onCull = options.onCull ?? "pause";
227
+ this.graceSeconds = options.graceSeconds ?? 1;
228
+ this.#boundsEveryFrames = boundsEveryFrames;
229
+ this.amount = options.amount;
230
+ this.#lifetime = options.lifetime;
231
+ this.#maxPerFrame = maxPerFrame;
232
+ const positions = instancedArray(options.amount, "vec3");
233
+ const velocities = instancedArray(options.amount, "vec3");
234
+ const births = options.spawn === void 0 ? void 0 : instancedArray(options.amount, "float");
235
+ this.buffers = births === void 0 ? { positions, velocities } : { positions, velocities, births };
236
+ options.material.positionNode = this.buffers.positions.toAttribute();
237
+ this.count = options.amount;
238
+ this.frustumCulled = false;
239
+ this.localCoords = options.localCoords ?? options.spawn === void 0;
240
+ if (!this.localCoords) {
241
+ this.matrixAutoUpdate = false;
242
+ this.matrixWorldAutoUpdate = false;
243
+ this.matrixWorld.identity();
244
+ }
245
+ this.#start = options.start === void 0 ? void 0 : computeNode(
246
+ "start",
247
+ options.start(this.buffers)
248
+ );
249
+ this.#process = computeNode(
250
+ "process",
251
+ options.process(
252
+ this.buffers,
253
+ { time, delta: deltaTime }
254
+ )
255
+ );
256
+ if (options.spawn !== void 0 && births !== void 0)
257
+ this.#spawn = this.#buildSpawn(options.spawn, births);
258
+ if (options.bounds === void 0) {
259
+ const partials = instancedArray(2 * LANES, "vec4");
260
+ const positions2 = this.buffers.positions;
261
+ const amount = this.amount;
262
+ this.#partials = partials;
263
+ this.#reduce = Fn(() => {
264
+ const lo = vec3(1e30).toVar();
265
+ const hi = vec3(-1e30).toVar();
266
+ Loop({ start: instanceIndex, end: amount, type: "uint", update: LANES }, ({ i }) => {
267
+ const position = positions2.element(i);
268
+ lo.assign(min(lo, position));
269
+ hi.assign(max(hi, position));
270
+ });
271
+ partials.element(instanceIndex).assign(vec4(lo, 0));
272
+ partials.element(instanceIndex.add(LANES)).assign(vec4(hi, 0));
273
+ })().compute(LANES);
274
+ this.#readback = new GPUReadback({ attribute: partials.value, everyFrames: 1 });
275
+ }
276
+ this.warmupNodes = [
277
+ ...this.#start === void 0 ? [] : [this.#start],
278
+ ...this.#spawn === void 0 ? [] : [this.#spawn.reset, this.#spawn.stamp, this.#spawn.spawn],
279
+ this.#process,
280
+ ...this.#reduce === void 0 ? [] : [this.#reduce]
281
+ ];
282
+ this.addEventListener("removed", this.#onRemoved);
283
+ }
284
+ #buildSpawn(spawn, births) {
285
+ const amount = this.amount;
286
+ const request = {
287
+ first: uniform(0, "uint"),
288
+ count: uniform(0, "uint"),
289
+ origin: uniform(new Vector3()),
290
+ direction: uniform(new Vector3()),
291
+ seed: uniform(0),
292
+ time
293
+ };
294
+ const stamp = Fn(() => {
295
+ If(instanceIndex.lessThan(request.count), () => {
296
+ births.element(request.first.add(instanceIndex).mod(uint(amount))).assign(time);
297
+ });
298
+ })().compute(amount);
299
+ const reset = Fn(() => {
300
+ births.element(instanceIndex).assign(DEAD_BIRTH);
301
+ })().compute(amount);
302
+ return {
303
+ births,
304
+ request,
305
+ reset,
306
+ spawn: computeNode("spawn", spawn({ ...this.buffers, births }, request)),
307
+ stamp
308
+ };
309
+ }
310
+ get released() {
311
+ return this.#released;
312
+ }
313
+ get stats() {
314
+ return {
315
+ clamped: this.#clamped,
316
+ recycledLive: this.#lifetime === void 0 ? void 0 : this.#recycledLive,
317
+ spawned: this.#spawned
318
+ };
319
+ }
320
+ /** Seconds outside view before culling; Infinity disables it at runtime. */
321
+ get graceSeconds() {
322
+ return this.#graceSeconds;
323
+ }
324
+ set graceSeconds(value) {
325
+ if (!Number.isFinite(value) && value !== Number.POSITIVE_INFINITY || value < 0)
326
+ throw new Error("GPUParticles3D.graceSeconds must be non-negative.");
327
+ this.#graceSeconds = value;
328
+ }
329
+ attachRenderer(renderer) {
330
+ if (this.#released) throw new Error("GPUParticles3D cannot be attached after release.");
331
+ if (this.#renderer === renderer) return;
332
+ this.#renderer = renderer;
333
+ this.#runStart(renderer);
334
+ }
335
+ /** The override or newest landed local bounds; absent until a valid sample lands. */
336
+ get measuredBounds() {
337
+ return this.#boundsOverride ?? this.#measuredBounds;
338
+ }
339
+ /** Simulation compute calls, excluding starts and bounds reduction. */
340
+ get dispatches() {
341
+ return this.#dispatches;
342
+ }
343
+ /** Current cull state and the number of state changes. */
344
+ get cull() {
345
+ return { state: this.#state, reason: this.#reason, transitions: this.#transitions };
346
+ }
347
+ get #worldPadding() {
348
+ return this.#padding ?? 0.5 * this.matrixWorld.getMaxScaleOnAxis();
349
+ }
350
+ process(renderer = this.#renderer, camera, _covered, _view, simulatedSeconds) {
351
+ if (this.#released || !this.emitting) return;
352
+ if (renderer === void 0) throw new Error("GPUParticles3D is not attached to a renderer.");
353
+ let readback = this.#readback;
354
+ if (readback !== void 0 && readback.stats.lands !== this.#lands) {
355
+ this.#lands = readback.stats.lands;
356
+ this.#measuredBounds = readback.data === void 0 ? void 0 : foldBounds(readback.data);
357
+ }
358
+ let reason;
359
+ if (camera !== void 0 && !this.castShadow && this.#authoredVisible) {
360
+ const bounds = this.measuredBounds;
361
+ if (bounds !== void 0 && this.#graceSeconds !== Number.POSITIVE_INFINITY) {
362
+ if (camera.matrixWorldAutoUpdate) camera.updateMatrixWorld();
363
+ this.updateWorldMatrix(true, false);
364
+ viewProjection.multiplyMatrices(camera.projectionMatrix, camera.matrixWorldInverse);
365
+ frustum.setFromProjectionMatrix(
366
+ viewProjection,
367
+ camera.coordinateSystem,
368
+ camera.reversedDepth
369
+ );
370
+ worldBox.copy(bounds).applyMatrix4(this.matrixWorld).expandByScalar(this.#worldPadding);
371
+ if (frustum.intersectsBox(worldBox)) this.#outsideSince = void 0;
372
+ else {
373
+ const now = simulatedSeconds ?? performance.now() / 1e3;
374
+ this.#outsideSince ??= now;
375
+ if (now - this.#outsideSince >= this.#graceSeconds) reason = "outside-view";
376
+ }
377
+ } else this.#outsideSince = void 0;
378
+ reason ??= this.#yielded ? "over-budget" : void 0;
379
+ } else this.#outsideSince = void 0;
380
+ const state = reason === void 0 ? "running" : this.#onCull === "clear" ? "cleared" : "paused";
381
+ if (state !== this.#state) {
382
+ this.#transitions += 1;
383
+ if (state === "running" && this.#onCull === "clear") this.restart();
384
+ this.#state = state;
385
+ readback = this.#readback;
386
+ }
387
+ this.#reason = reason;
388
+ if (reason !== void 0) {
389
+ this.#hiddenByCull = true;
390
+ return;
391
+ }
392
+ this.#hiddenByCull = false;
393
+ renderer.compute(this.#process);
394
+ this.#spawnedThisFrame = 0;
395
+ this.#dispatches += 1;
396
+ this.#frame += 1;
397
+ if (readback !== void 0 && this.#reduce !== void 0 && typeof renderer.readback === "function" && !readback.pending && !(readback.stats.failures > 0 && readback.stats.lands === 0) && this.#frame - this.#lastMeasure >= this.#boundsEveryFrames) {
398
+ this.#lastMeasure = this.#frame;
399
+ renderer.compute(this.#reduce);
400
+ readback.request(renderer);
401
+ }
402
+ }
403
+ /**
404
+ * Spawns `count` particles at `origin` (world space unless `localCoords`). Every call gets its own ring
405
+ * slots, so a second burst never touches the first one's live particles. No readback.
406
+ */
407
+ emitParticle(request = {}) {
408
+ if (this.#released) throw new Error("GPUParticles3D cannot emit after release.");
409
+ if (this.#spawn === void 0)
410
+ throw new Error("GPUParticles3D.emitParticle requires a spawn kernel.");
411
+ if (this.#renderer === void 0)
412
+ throw new Error("GPUParticles3D is not attached to a renderer.");
413
+ const asked = request.count ?? 1;
414
+ if (!Number.isInteger(asked) || asked < 0)
415
+ throw new Error("GPUParticles3D.emitParticle count must be a non-negative integer.");
416
+ const { request: uniforms } = this.#spawn;
417
+ setVector(uniforms.origin, "origin", request.origin);
418
+ setVector(uniforms.direction, "direction", request.direction);
419
+ uniforms.seed.value = finite("seed", request.seed ?? this.#seed++);
420
+ const count = Math.min(asked, this.amount, this.#maxPerFrame - this.#spawnedThisFrame);
421
+ if (count < asked) {
422
+ this.#clamped += asked - count;
423
+ if (!this.#warned) {
424
+ this.#warned = true;
425
+ console.warn(
426
+ `GPUParticles3D: spawn request of ${asked} clamped to ${count} (amount ${this.amount}, maxSpawnPerFrame ${this.#maxPerFrame}).`
427
+ );
428
+ }
429
+ }
430
+ if (count === 0) return;
431
+ this.#countRecycled(count);
432
+ uniforms.first.value = this.#cursor % this.amount;
433
+ uniforms.count.value = count;
434
+ this.#cursor += count;
435
+ this.#spawnedThisFrame += count;
436
+ this.#spawned += count;
437
+ this.#renderer.compute(this.#spawn.stamp);
438
+ this.#renderer.compute(this.#spawn.spawn);
439
+ }
440
+ /** Reruns `start`. A spawn-driven emitter instead kills every particle and rewinds the ring. */
441
+ restart() {
442
+ if (this.#released) throw new Error("GPUParticles3D cannot restart after release.");
443
+ if (this.#renderer === void 0)
444
+ throw new Error("GPUParticles3D is not attached to a renderer.");
445
+ this.#runStart(this.#renderer);
446
+ this.#readback?.dispose();
447
+ this.#readback = this.#partials === void 0 ? void 0 : new GPUReadback({ attribute: this.#partials.value, everyFrames: 1 });
448
+ this.#measuredBounds = void 0;
449
+ this.#lands = 0;
450
+ this.#outsideSince = void 0;
451
+ this.#lastMeasure = this.#frame - this.#boundsEveryFrames;
452
+ }
453
+ detach() {
454
+ if (this.#released) return;
455
+ this.#renderer = void 0;
456
+ this.#start?.dispose();
457
+ this.#process.dispose();
458
+ if (this.#spawn !== void 0) {
459
+ this.#spawn.spawn.dispose();
460
+ this.#spawn.stamp.dispose();
461
+ this.#spawn.reset.dispose();
462
+ this.#spawn.births.value.dispose();
463
+ }
464
+ this.#reduce?.dispose();
465
+ this.#readback?.dispose();
466
+ this.#partials?.value.dispose();
467
+ this.buffers.positions.value.dispose();
468
+ this.buffers.velocities.value.dispose();
469
+ this.#released = true;
470
+ }
471
+ #runStart(renderer) {
472
+ if (this.#start !== void 0) renderer.compute(this.#start);
473
+ if (this.#spawn === void 0) return;
474
+ renderer.compute(this.#spawn.reset);
475
+ this.#cursor = 0;
476
+ this.#spawnedThisFrame = 0;
477
+ this.#log = [];
478
+ }
479
+ /** Counts the slots this request overwrites that a recent request filled less than `lifetime` ago. */
480
+ #countRecycled(count) {
481
+ const lifetime = this.#lifetime;
482
+ if (lifetime === void 0) return;
483
+ const now = performance.now() / 1e3;
484
+ const first = this.#cursor;
485
+ const overwritten = first - this.amount;
486
+ this.#log = this.#log.filter((entry) => now - entry.at < lifetime);
487
+ for (const entry of this.#log) {
488
+ const lo = Math.max(entry.first, overwritten);
489
+ const hi = Math.min(entry.first + entry.count, overwritten + count);
490
+ if (hi > lo) this.#recycledLive += hi - lo;
491
+ }
492
+ this.#log.push({ at: now, count, first });
493
+ }
494
+ #onRemoved = () => this.detach();
495
+ };
496
+
497
+ export { CameraShake, GPUParticles3D };
@@ -1,7 +1,7 @@
1
1
  import { I as IAssetLoader, a as IAssetLoaderOptions } from './assets-YUbXa3-Y.js';
2
- import { F as FramePassKind, c as IRenderPassSample, d as IFramePhaseSample, e as IPipelineCensus, I as IRendererLike, f as IRendererOptions, a as IFrameBudgetWindow, g as IFrameBudgetOptions } from './renderer-rZm0hVqq.js';
2
+ import { F as FramePassKind, c as IRenderPassSample, d as IFramePhaseSample, e as IPipelineCensus, I as IRendererLike, f as IRendererOptions, a as IFrameBudgetWindow, g as IFrameBudgetOptions } from './renderer-DvFVoAgj.js';
3
3
  import { Vector2, Vector3, Object3D, Camera, Intersection, Scene as Scene$1 } from 'three';
4
- import { V as Viewport, C as CanvasLayer, I as IViewportOptions } from './canvas-layer-vCtanIeB.js';
4
+ import { V as Viewport, C as CanvasLayer, I as IViewportOptions } from './canvas-layer-CWuFRT7G.js';
5
5
  import { StoreApi } from 'zustand/vanilla';
6
6
 
7
7
  type EntitySnapshot = Record<string, Record<string, unknown> & {
@@ -1598,8 +1598,20 @@ interface IGamePluginRuntime {
1598
1598
  * A run that counts fixed-step ticks must not also accumulate real seconds into the same
1599
1599
  * simulation, and the frames before its first `advance()` are exactly where a boot's seconds
1600
1600
  * used to land. Optional: a runtime without a clock just never freezes one.
1601
+ *
1602
+ * `settleSteps` is the settling pass the world is owed: a zero freeze lets `settleClock` spend it
1603
+ * instead, once the world's scene is live.
1604
+ */
1605
+ readonly freezeClock?: (settleSteps?: number) => void;
1606
+ /**
1607
+ * Spend the settling pass now, from a caller that knows the world's scene is live.
1608
+ *
1609
+ * Present only when the runtime can spend it later than the freeze: a game that boots through a
1610
+ * loading scene otherwise settles the loading scene, and the world's own clock misses those fixed
1611
+ * steps — a playtest pose then depends on how fast the machine booted. Optional, and paired with
1612
+ * `freezeClock(0)`: a runtime without it settles on its first live frame, as before.
1601
1613
  */
1602
- readonly freezeClock?: () => void;
1614
+ readonly settleClock?: (steps?: number) => void;
1603
1615
  /**
1604
1616
  * Draw the current world once without advancing it, for a screenshot taken while the loop is
1605
1617
  * driven by `fixedStep` and presents nothing between ticks. Optional: a runtime without a frozen
package/dist/hot.d.ts CHANGED
@@ -1,10 +1,10 @@
1
1
  import { a as audioRuntimeSnapshot } from './audio-DIJE5HTr.js';
2
- import { I as IGame } from './game-DzMcitDO.js';
2
+ import { I as IGame } from './game-D7pAzZUY.js';
3
3
  import 'three';
4
4
  import './assets-YUbXa3-Y.js';
5
- import './renderer-rZm0hVqq.js';
5
+ import './renderer-DvFVoAgj.js';
6
6
  import 'three/webgpu';
7
- import './canvas-layer-vCtanIeB.js';
7
+ import './canvas-layer-CWuFRT7G.js';
8
8
  import 'zustand/vanilla';
9
9
 
10
10
  interface IHotDiagnostics {
package/dist/hot.js CHANGED
@@ -1,49 +1,5 @@
1
- import 'three';
2
-
3
- // src/audio.ts
4
-
5
- // src/platform.ts
6
- function hostWindow() {
7
- return typeof window === "undefined" ? void 0 : window;
8
- }
9
- function hostDocument() {
10
- return typeof document === "undefined" ? void 0 : document;
11
- }
12
-
13
- // src/audio.ts
14
- var AUDIO_STATE = /* @__PURE__ */ Symbol.for("threenative.audio.runtime");
15
- function audioState() {
16
- const host = globalThis;
17
- const existing = host[AUDIO_STATE];
18
- if (existing !== void 0) return existing;
19
- const created = { buses: /* @__PURE__ */ new Set(), cueCounts: /* @__PURE__ */ new Map(), cueLog: [] };
20
- host[AUDIO_STATE] = created;
21
- return created;
22
- }
23
- function audioRuntimeSnapshot() {
24
- let queued = 0;
25
- let voices = 0;
26
- let pooled = 0;
27
- let paused = 0;
28
- const unsupported = /* @__PURE__ */ new Set();
29
- const state = audioState();
30
- for (const bus of state.buses) {
31
- queued += bus.queued;
32
- voices += bus.voices;
33
- pooled += bus.pooled;
34
- paused += bus.pausedVoices;
35
- for (const option of bus.unsupported) unsupported.add(option);
36
- }
37
- return {
38
- cues: Object.fromEntries(state.cueCounts),
39
- paused,
40
- pooled,
41
- queued,
42
- recentCues: state.cueLog.map((entry) => ({ ...entry })),
43
- unsupported: [...unsupported].sort(),
44
- voices
45
- };
46
- }
1
+ import { audioRuntimeSnapshot } from './chunk-DBELTTTM.js';
2
+ import { hostWindow, hostDocument } from './chunk-6KLNISRJ.js';
47
3
 
48
4
  // src/hot.ts
49
5
  var isDev = import.meta.env?.DEV === true;