@threenative/core 0.3.11 → 0.3.13

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 (236) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1988 -204
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/camera-shake-CZKOfGn4.d.ts +46 -0
  5. package/dist/{canvas-layer-vCtanIeB.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  6. package/dist/chunk-4SRAQFTU.js +133 -0
  7. package/dist/chunk-CFGTPFUH.js +231 -0
  8. package/dist/chunk-DIPIJICH.js +8916 -0
  9. package/dist/chunk-EEABDLUC.js +2237 -0
  10. package/dist/chunk-EFWZWLPY.js +1895 -0
  11. package/dist/chunk-GXY7B3JG.js +46 -0
  12. package/dist/chunk-GYUZJQ7U.js +280 -0
  13. package/dist/chunk-H4J6IAJE.js +504 -0
  14. package/dist/chunk-KIRUKTBQ.js +187 -0
  15. package/dist/chunk-QWJEMUUT.js +94 -0
  16. package/dist/chunk-SV4QVUTQ.js +31 -0
  17. package/dist/chunk-U4YHUKKL.js +615 -0
  18. package/dist/chunk-VP43GIWW.js +18 -0
  19. package/dist/chunk-XDTZ4QMO.js +160 -0
  20. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  21. package/dist/{game-DzMcitDO.d.ts → game-k8K3hZai.d.ts} +85 -9
  22. package/dist/hot.d.ts +5 -4
  23. package/dist/hot.js +5 -52
  24. package/dist/index.d.ts +633 -1351
  25. package/dist/index.js +12873 -23068
  26. package/dist/{model-lod-CTpZ6imz.d.ts → model-lod-DPTzeCcD.d.ts} +35 -3
  27. package/dist/playtest.d.ts +5 -4
  28. package/dist/playtest.js +25 -75
  29. package/dist/quality-BYqKGAwo.d.ts +868 -0
  30. package/dist/react-css.js +1 -215
  31. package/dist/react.d.ts +3 -2
  32. package/dist/render-environment.d.ts +170 -0
  33. package/dist/render-environment.js +352 -0
  34. package/dist/{renderer-rZm0hVqq.d.ts → renderer-BtOSseYf.d.ts} +42 -35
  35. package/dist/spells/index.d.ts +643 -0
  36. package/dist/spells/index.js +1558 -0
  37. package/dist/spells/ultra/index.d.ts +1600 -0
  38. package/dist/spells/ultra/index.js +6804 -0
  39. package/dist/terrain-jobs-worker.js +1 -123
  40. package/dist/two-sided-foliage-W523J3UM.js +1 -0
  41. package/dist/ui-layer.js +6 -384
  42. package/dist/worker.js +13 -43
  43. package/dist/world.d.ts +988 -268
  44. package/dist/world.js +17464 -18290
  45. package/mcp/animation-server.mjs +1 -1
  46. package/mcp/animation.mjs +2 -3
  47. package/mcp/engine-server.mjs +245 -52
  48. package/mcp/servers.mjs +10 -3
  49. package/mcp/terrain.mjs +8 -0
  50. package/package.json +19 -7
  51. package/patches/three@0.187.0-prd269-upgrade.patch +2102 -0
  52. package/patches/three@0.187.0.patch +2004 -407
  53. package/src/animation-batch.ts +193 -0
  54. package/src/animation-layers.ts +7 -3
  55. package/src/animation.ts +209 -29
  56. package/src/asset-cache.ts +3 -3
  57. package/src/asset-memo.ts +202 -0
  58. package/src/assets.ts +437 -125
  59. package/src/auto-batch.ts +190 -44
  60. package/src/card-lod.ts +152 -0
  61. package/src/compressed-texture-preparation.ts +1008 -0
  62. package/src/compute-driven.ts +1 -1
  63. package/src/config.ts +8 -0
  64. package/src/debug.ts +103 -22
  65. package/src/dev-global.ts +54 -0
  66. package/src/engine-hooks.ts +37 -0
  67. package/src/frame-budget.ts +50 -23
  68. package/src/game-boot-phase.ts +269 -0
  69. package/src/game-dev-tools.ts +86 -0
  70. package/src/game-frame-loop.ts +958 -0
  71. package/src/game-renderer-metrics.ts +77 -0
  72. package/src/game-startup.ts +1076 -0
  73. package/src/game-ui.ts +84 -0
  74. package/src/game-validate.ts +70 -0
  75. package/src/game.ts +198 -2264
  76. package/src/gamepad-mappings.ts +269 -0
  77. package/src/generated/console-markers.ts +13 -0
  78. package/src/geometry-capture.ts +28 -4
  79. package/src/gpu-readings.ts +98 -0
  80. package/src/gpu-scene-bvh.ts +149 -36
  81. package/src/hot.ts +4 -7
  82. package/src/index.ts +141 -9
  83. package/src/input.ts +237 -25
  84. package/src/instanced-batch-lod.ts +3 -8
  85. package/src/interpolation.ts +171 -40
  86. package/src/launch-diagnostics.ts +22 -12
  87. package/src/look/ao-admission.ts +25 -0
  88. package/src/look/auto-exposure.ts +5 -16
  89. package/src/look/default-tone-mapping.ts +41 -5
  90. package/src/look/filmic-tone-mapping.ts +15 -13
  91. package/src/look/local-exposure.ts +2 -7
  92. package/src/look/look-diagnostics.ts +3 -3
  93. package/src/look/quad-pass.ts +21 -0
  94. package/src/look/quality.ts +14 -5
  95. package/src/look/unreal-bloom.ts +4 -13
  96. package/src/look/world-environment.ts +113 -103
  97. package/src/loop.ts +29 -0
  98. package/src/merge-parts.ts +20 -24
  99. package/src/model-lod.ts +139 -17
  100. package/src/particle-kinds.ts +515 -0
  101. package/src/particle-significance.ts +12 -0
  102. package/src/particles.ts +19 -10
  103. package/src/picking.ts +17 -3
  104. package/src/platform.ts +23 -4
  105. package/src/playtest.ts +27 -1
  106. package/src/profiling/FrameStages.ts +5 -6
  107. package/src/profiling/Spans.ts +3 -17
  108. package/src/profiling/debug-telemetry.ts +2 -6
  109. package/src/profiling/render-list-validate.ts +6 -15
  110. package/src/projection-apply.ts +4 -1
  111. package/src/projection-marker.ts +2 -1
  112. package/src/projection-plan.ts +9 -6
  113. package/src/quiet-markers.ts +3 -10
  114. package/src/render/cpu-bvh.ts +100 -0
  115. package/src/render/depth-pyramid.ts +6 -14
  116. package/src/render/environment/environmentContribution.ts +202 -0
  117. package/src/render/environment/environmentRadiance.ts +44 -0
  118. package/src/render/environment/environmentSampleCache.ts +56 -0
  119. package/src/render/environment/environmentSampling.ts +201 -0
  120. package/src/render/environment/environmentSnapshot.ts +71 -0
  121. package/src/render/environment/gate.ts +57 -0
  122. package/src/render/mesh-pool.ts +4 -20
  123. package/src/render/probe-trace.ts +872 -0
  124. package/src/render/probe-volume.ts +780 -34
  125. package/src/render/radiance-cache.ts +17 -0
  126. package/src/render/resolution-subrect.ts +2 -0
  127. package/src/render/rough-diffuse.ts +46 -12
  128. package/src/render/soft-shadow.ts +27 -12
  129. package/src/render/virtual-shadow-adaptive.ts +55 -0
  130. package/src/render/virtual-shadow-casters.ts +175 -0
  131. package/src/render/virtual-shadow-layers.ts +76 -0
  132. package/src/render/virtual-shadow-level.ts +224 -0
  133. package/src/render/virtual-shadow-markers.ts +193 -0
  134. package/src/render/virtual-shadow-options.ts +370 -0
  135. package/src/render/virtual-shadow-pages.ts +5 -0
  136. package/src/render/virtual-shadow-partial.ts +13 -0
  137. package/src/render/virtual-shadow.ts +231 -1008
  138. package/src/render/world-impostor-surface.ts +402 -40
  139. package/src/render/world-impostor.ts +5 -2
  140. package/src/render-camera-cull.ts +98 -3
  141. package/src/render-environment.ts +41 -0
  142. package/src/render-pass-budget.ts +34 -7
  143. package/src/renderProjection.ts +22 -0
  144. package/src/renderer-config.ts +36 -0
  145. package/src/renderer-facts.ts +37 -0
  146. package/src/renderer.ts +144 -65
  147. package/src/resolution-scaler.ts +3 -2
  148. package/src/scene-entry-inspectors.ts +61 -0
  149. package/src/snow-field.ts +2 -1
  150. package/src/spells/cast-pool.ts +361 -0
  151. package/src/spells/index.ts +177 -0
  152. package/src/spells/mechanisms.ts +295 -0
  153. package/src/spells/reaction-field.ts +415 -0
  154. package/src/spells/spell-lights.ts +139 -0
  155. package/src/spells/spell-world.ts +187 -0
  156. package/src/spells/spell.ts +397 -0
  157. package/src/spells/spells.ts +283 -0
  158. package/src/spells/ultra/engine/camera.ts +184 -0
  159. package/src/spells/ultra/engine/quality.ts +96 -0
  160. package/src/spells/ultra/index.ts +52 -0
  161. package/src/spells/ultra/main.ts +305 -0
  162. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  163. package/src/spells/ultra/spells/cast.ts +233 -0
  164. package/src/spells/ultra/spells/fire.ts +1267 -0
  165. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  166. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  167. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  168. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  169. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  170. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  171. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  172. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  173. package/src/spells/ultra/vfx/common.ts +1195 -0
  174. package/src/spells/ultra/vfx/noise.ts +441 -0
  175. package/src/startup-offscreen-bytes.ts +78 -0
  176. package/src/startup-readiness.ts +128 -34
  177. package/src/static-transform.ts +25 -19
  178. package/src/streamed-textures.ts +112 -0
  179. package/src/streaming.ts +68 -4
  180. package/src/texture-streaming.ts +331 -0
  181. package/src/version.ts +1 -1
  182. package/src/warmup.ts +56 -8
  183. package/src/water-surface.ts +9 -3
  184. package/src/worker.ts +12 -2
  185. package/src/world-bundle-safety.ts +446 -0
  186. package/src/world-cell-batches.ts +1178 -0
  187. package/src/world-cell-chunks.ts +1128 -0
  188. package/src/world-cell-data.ts +995 -0
  189. package/src/world-cell-impostors.ts +1461 -0
  190. package/src/world-cell-lod-bias.ts +151 -0
  191. package/src/world-cell-models.ts +1074 -0
  192. package/src/world-cell-options.ts +177 -0
  193. package/src/world-cell-placements.ts +798 -0
  194. package/src/world-cell-prewarm.ts +592 -0
  195. package/src/world-cell-readiness.ts +357 -0
  196. package/src/world-cell-records.ts +401 -0
  197. package/src/world-cell-render-bundles.ts +459 -0
  198. package/src/world-cell-render-gpu-dress.ts +710 -0
  199. package/src/world-cell-render-main-cull.ts +540 -0
  200. package/src/world-cell-render-shadow-claims.ts +198 -0
  201. package/src/world-cell-render-util.ts +259 -0
  202. package/src/world-cell-render.ts +1501 -0
  203. package/src/world-cell-residency.ts +754 -0
  204. package/src/world-cell-stale.ts +238 -0
  205. package/src/world-cells.ts +1335 -10418
  206. package/src/world-chunk-shadow.ts +308 -0
  207. package/src/world-collar.ts +315 -0
  208. package/src/world-gpu-flags.ts +131 -0
  209. package/src/world-gpu-readback.ts +881 -0
  210. package/src/world-gpu-reference.ts +524 -0
  211. package/src/world-gpu-scene.ts +256 -2286
  212. package/src/world-gpu-shadow.ts +203 -0
  213. package/src/world-gpu-types.ts +409 -0
  214. package/src/world-gpu-validation.ts +518 -0
  215. package/src/world-heightfield.ts +802 -0
  216. package/src/world-load-limiter.ts +111 -0
  217. package/src/world-model-sections.ts +80 -0
  218. package/src/world-noise.ts +241 -0
  219. package/src/world-package.ts +42 -0
  220. package/src/world-region.ts +1 -1
  221. package/src/world-river-ribbon.ts +282 -0
  222. package/src/world-root-frame.ts +39 -0
  223. package/src/world-shore-field.ts +91 -0
  224. package/src/world-static-pose.ts +163 -0
  225. package/src/world-surface-sampler.ts +48 -0
  226. package/src/world-terrain-splat.ts +361 -153
  227. package/src/world-tile-budget.ts +249 -0
  228. package/src/world-tile-geometry.ts +469 -0
  229. package/src/world-tile-lod.ts +408 -0
  230. package/src/world-tile-observation.ts +566 -0
  231. package/src/world-tile-stitch.ts +166 -0
  232. package/src/world-tiles.ts +247 -1755
  233. package/src/world-validate.ts +6 -14
  234. package/src/world-warm.ts +51 -0
  235. package/src/world-water-bodies.ts +359 -0
  236. package/src/world.ts +48 -741
@@ -0,0 +1,202 @@
1
+ import { type CacheLike, cacheStorage, manifestFingerprint } from "./asset-cache.js";
2
+ import { isNative } from "./platform.js";
3
+
4
+ /**
5
+ * Generated content kept between runs (PRD-860): `ctx.assets.memo(key, build)` returns what `build`
6
+ * returned the last time this exact build of the game ran, read back from disk, and calls `build`
7
+ * only when nothing is stored. A seeded world, a painted sky or a baked placement list is the same
8
+ * every run of one build, so a repeat visit stops paying for it.
9
+ *
10
+ * The value is named typed arrays, the shape a generator hands to geometry, instancing and
11
+ * textures. The build identity is the hashed entry script the web build writes into the page
12
+ * (`__TN_BUILD_ID__`), so any code change regenerates and the old build's entries are deleted. With
13
+ * no build identity (the dev server) or no Cache API (a native host), `build` runs every time and
14
+ * `TN_ASSET_MEMO` says why.
15
+ */
16
+ export type MemoArray =
17
+ | Float32Array
18
+ | Float64Array
19
+ | Int8Array
20
+ | Int16Array
21
+ | Int32Array
22
+ | Uint8Array
23
+ | Uint8ClampedArray
24
+ | Uint16Array
25
+ | Uint32Array;
26
+
27
+ export type MemoArrays = Readonly<Record<string, MemoArray>>;
28
+ /** Every field a typed array: a record or an interface, which has no index signature. */
29
+ export type MemoShape<T> = { readonly [K in keyof T]: MemoArray };
30
+
31
+ export type AssetMemo = <T extends MemoShape<T>>(
32
+ key: string,
33
+ build: () => T | Promise<T>,
34
+ ) => Promise<T>;
35
+
36
+ const KINDS = {
37
+ Float32Array,
38
+ Float64Array,
39
+ Int16Array,
40
+ Int32Array,
41
+ Int8Array,
42
+ Uint16Array,
43
+ Uint32Array,
44
+ Uint8Array,
45
+ Uint8ClampedArray,
46
+ } as const;
47
+ type Kind = keyof typeof KINDS;
48
+
49
+ const BUILD_ID_GLOBAL = "__TN_BUILD_ID__";
50
+ const MEMO_CACHE = "threenative-memo";
51
+ /** A host no request ever reaches: the Cache API only needs an absolute url to key on. */
52
+ const MEMO_ORIGIN = "https://memo.threenative.invalid/";
53
+ const MAGIC = 0x4f4d4e54; // "TNMO"
54
+
55
+ function invalid(detail: string): Error {
56
+ return new Error(`TN_ASSET_MEMO_INVALID: ${detail}`);
57
+ }
58
+
59
+ function kindOf(value: unknown): Kind | undefined {
60
+ for (const kind of Object.keys(KINDS) as Kind[]) if (value instanceof KINDS[kind]) return kind;
61
+ return undefined;
62
+ }
63
+
64
+ /** Header (magic, JSON length, JSON) then each array's bytes at an 8-byte boundary. */
65
+ export function encodeMemo(value: MemoArrays): ArrayBuffer {
66
+ const entries = Object.entries(value).map(([name, array]) => {
67
+ const kind = kindOf(array);
68
+ if (kind === undefined) throw invalid(`"${name}" is not a typed array.`);
69
+ return { array, kind, name };
70
+ });
71
+ const align = (n: number): number => Math.ceil(n / 8) * 8;
72
+ const header = new TextEncoder().encode(
73
+ JSON.stringify(entries.map(({ array, kind, name }) => ({ kind, length: array.length, name }))),
74
+ );
75
+ let offset = align(8 + header.byteLength);
76
+ const placed = entries.map((entry) => {
77
+ const at = offset;
78
+ offset = align(at + entry.array.byteLength);
79
+ return { ...entry, at };
80
+ });
81
+ const buffer = new ArrayBuffer(offset);
82
+ const view = new DataView(buffer);
83
+ view.setUint32(0, MAGIC, true);
84
+ view.setUint32(4, header.byteLength, true);
85
+ new Uint8Array(buffer, 8, header.byteLength).set(header);
86
+ for (const { array, at } of placed)
87
+ new Uint8Array(buffer, at, array.byteLength).set(
88
+ new Uint8Array(array.buffer, array.byteOffset, array.byteLength),
89
+ );
90
+ return buffer;
91
+ }
92
+
93
+ /** The inverse of `encodeMemo`; throws on anything it did not write. */
94
+ export function decodeMemo(buffer: ArrayBuffer): Record<string, MemoArray> {
95
+ const view = new DataView(buffer);
96
+ if (buffer.byteLength < 8 || view.getUint32(0, true) !== MAGIC)
97
+ throw invalid("stored entry is not a memo.");
98
+ const headerBytes = view.getUint32(4, true);
99
+ if (8 + headerBytes > buffer.byteLength) throw invalid("stored entry is truncated.");
100
+ const header: unknown = JSON.parse(
101
+ new TextDecoder().decode(new Uint8Array(buffer, 8, headerBytes)),
102
+ );
103
+ if (!Array.isArray(header)) throw invalid("stored entry has no array list.");
104
+ const result: Record<string, MemoArray> = {};
105
+ let offset = Math.ceil((8 + headerBytes) / 8) * 8;
106
+ for (const entry of header as Array<{ kind?: unknown; length?: unknown; name?: unknown }>) {
107
+ const kind = entry.kind as Kind;
108
+ const Ctor = KINDS[kind];
109
+ if (Ctor === undefined || typeof entry.name !== "string" || !Number.isInteger(entry.length))
110
+ throw invalid("stored entry has a malformed array.");
111
+ const length = entry.length as number;
112
+ const bytes = length * Ctor.BYTES_PER_ELEMENT;
113
+ if (offset + bytes > buffer.byteLength) throw invalid("stored entry is truncated.");
114
+ result[entry.name] = new Ctor(buffer, offset, length);
115
+ offset = Math.ceil((offset + bytes) / 8) * 8;
116
+ }
117
+ return result;
118
+ }
119
+
120
+ function report(fields: Record<string, unknown>): void {
121
+ console.info(`TN_ASSET_MEMO:${JSON.stringify(fields)}`);
122
+ }
123
+
124
+ function now(): number {
125
+ return globalThis.performance?.now() ?? Date.now();
126
+ }
127
+
128
+ export function createAssetMemo(namespace: string): AssetMemo {
129
+ const storage = cacheStorage();
130
+ const id = (globalThis as Record<string, unknown>)[BUILD_ID_GLOBAL];
131
+ const buildId = typeof id === "string" && id !== "" ? id : undefined;
132
+ const reason =
133
+ storage === undefined
134
+ ? isNative()
135
+ ? "native host has no Cache API: generated content rebuilds each run"
136
+ : "cache API unavailable: generated content rebuilds each run"
137
+ : buildId === undefined
138
+ ? "no build id (dev server or a page the web build did not write): generated content rebuilds each run"
139
+ : undefined;
140
+ const prefix = buildId === undefined ? "" : `${MEMO_ORIGIN}${encodeURIComponent(buildId)}/`;
141
+ const name = `${MEMO_CACHE}-${manifestFingerprint([{ url: namespace }]).slice(0, 8)}`;
142
+ let opened: Promise<CacheLike | undefined> | undefined;
143
+ /** Opens once, deleting what another build stored, so a cache holds one build's content. */
144
+ const open = (): Promise<CacheLike | undefined> => {
145
+ opened ??= (async () => {
146
+ const cache = await storage?.open(name);
147
+ if (cache === undefined) return undefined;
148
+ for (const request of await cache.keys())
149
+ if (!request.url.startsWith(prefix)) await cache.delete(request.url);
150
+ return cache;
151
+ })().catch(() => undefined);
152
+ return opened;
153
+ };
154
+ const checked = <T extends MemoShape<T>>(key: string, value: T): T => {
155
+ if (typeof value !== "object" || value === null)
156
+ throw invalid(`build for "${key}" returned no object.`);
157
+ for (const [field, array] of Object.entries(value))
158
+ if (kindOf(array) === undefined)
159
+ throw invalid(`build for "${key}" returned "${field}", not a typed array.`);
160
+ return value;
161
+ };
162
+
163
+ return async <T extends MemoShape<T>>(key: string, build: () => T | Promise<T>): Promise<T> => {
164
+ if (typeof key !== "string" || key === "") throw invalid("key must be a non-empty string.");
165
+ const started = now();
166
+ if (reason !== undefined) {
167
+ const value = checked(key, await build());
168
+ report({ key, hit: false, ms: Math.round(now() - started), reason });
169
+ return value;
170
+ }
171
+ const url = `${prefix}${encodeURIComponent(key)}`;
172
+ const cache = await open();
173
+ if (cache !== undefined) {
174
+ try {
175
+ const stored = await cache.match(url);
176
+ if (stored !== undefined) {
177
+ const buffer = await stored.arrayBuffer();
178
+ const value = decodeMemo(buffer) as T;
179
+ report({ bytes: buffer.byteLength, hit: true, key, ms: Math.round(now() - started) });
180
+ return value;
181
+ }
182
+ } catch {
183
+ // A damaged entry is a miss: delete it and build, never fail the load over a cache.
184
+ await cache.delete(url).catch(() => undefined);
185
+ }
186
+ }
187
+ const value = checked(key, await build());
188
+ const encoded = encodeMemo(value as MemoArrays);
189
+ const builtMs = Math.round(now() - started);
190
+ if (cache === undefined) {
191
+ report({ hit: false, key, ms: builtMs, reason: "cache storage refused to open" });
192
+ return value;
193
+ }
194
+ void cache
195
+ .put(url, new Response(encoded))
196
+ .then(() => report({ bytes: encoded.byteLength, hit: false, key, ms: builtMs, stored: true }))
197
+ .catch((error: unknown) =>
198
+ report({ hit: false, key, ms: builtMs, stored: false, reason: String(error) }),
199
+ );
200
+ return value;
201
+ };
202
+ }