@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,189 @@
1
+ import { INSTANCED_LOD_MAX_PIXEL_ERROR } from "./instanced-batch-lod.js";
2
+ import type { IWorldCellsLoadOptions } from "./world-cell-data.js";
3
+ import type { IWorldCell, IWorldPackage } from "./world-package.js";
4
+
5
+ /**
6
+ * `world-cells.ts`'s load options: the defaults a package does not name, the three places a launch
7
+ * states a switch, and the validation that turns a malformed option into a throw before a frame.
8
+ *
9
+ * The defaults live here rather than beside the class so the numbers a game can override are one
10
+ * file: a change to a default is a change to this module, and the class only reads what it exports.
11
+ * The launch readers are the option layer's own — `world-gpu-scene.ts` keeps the subsystem switches
12
+ * (`gpuScene`, `bundles`, `gpuSceneValidate`, `shadowGpuKeys`), and this file keeps the ones the
13
+ * world owns as a whole (impostors, the adaptive bias and its share of the frame).
14
+ */
15
+
16
+ export const DEFAULT_TILE_RESOLUTION = 129;
17
+
18
+ /**
19
+ * One tile vertex per heightmap sample, rounded up so every default lod factor (1, 2, 4) divides it
20
+ * and capped at the old fixed 129. A finer tile only interpolates the same samples: 129 over a 2 m
21
+ * heightmap drew 3.01M terrain triangles, 25 ms on an Iris Xe (PRD-762).
22
+ */
23
+ export function tileResolutionFor(tileSize: number, spacing: number): number {
24
+ const cells = Math.ceil(tileSize / spacing / 4) * 4;
25
+ return Math.min(DEFAULT_TILE_RESOLUTION, Math.max(9, cells + 1));
26
+ }
27
+
28
+ export const DEFAULT_ADMISSION_BUDGET_MS = 2;
29
+ /**
30
+ * How much more one `update` may admit while the startup cover hides the world: 8x takes the 2 ms
31
+ * default to one 60 Hz frame. Nobody sees frame pacing behind an opaque loading screen, and at 2 ms
32
+ * a 10-17 fps test lane spent 16 s (web) and about 47 s (native) admitting a spawn backlog of about
33
+ * 1,200 builds. The loader still presents every frame. Scaling keeps a game's own split between
34
+ * several worlds; `coveredAdmissionBudgetMs` and `coveredFreshMeshesPerUpdate` name the covered
35
+ * values outright.
36
+ */
37
+ export const COVERED_BUDGET_SCALE = 8;
38
+ /**
39
+ * How far the follow point has to move before a residency pass is worth repeating. Below it the
40
+ * ring, the refilter brackets and every tile's LOD level are the same numbers, so the pass would
41
+ * re-derive the set it already holds. Half a metre is under one 2 m heightmap cell and far under a
42
+ * 128 m cell, so nothing that could change an answer is skipped.
43
+ */
44
+ export const SETTLED_FOLLOW_METRES = 0.5;
45
+ /**
46
+ * How far the follow point has to move before the `maxDistance`/`lods` refilter pass runs again.
47
+ * That pass walks every resident cell's batches, derives both distance brackets and sorts what it
48
+ * found, and on a 2 km walk at 0.3 m a frame it ran every second frame for the same brackets — a
49
+ * third of the world's `update`. Two metres is the same order as the per-asset hysteresis the pass
50
+ * already applies (`threshold / 8`, 3.75 m for a 30 m gate), so a level switch or a cull lands
51
+ * within about two metres of the distance that asked for it, on a level the player is still walking
52
+ * toward. Raise it when a game's gates are far apart, lower it when placements sit inside one.
53
+ */
54
+ export const LEVEL_REFILTER_STEP_METRES = 2;
55
+ /**
56
+ * The projection a baked chain's levels are switched at when the world names none: 60° of vertical
57
+ * field of view over 1080 raster rows, which is the desktop view a switch distance is a function of.
58
+ * See `autoLod`.
59
+ */
60
+ const DEFAULT_AUTO_LOD_FOV_Y = 60;
61
+ const DEFAULT_AUTO_LOD_VIEWPORT_HEIGHT = 1080;
62
+ /**
63
+ * The screen-space error budget a baked chain's levels are switched at, in pixels, when the world
64
+ * names none. See `IWorldCellsLoadOptions.autoLod`.
65
+ */
66
+ export const DEFAULT_AUTO_LOD_MAX_PIXEL_ERROR = INSTANCED_LOD_MAX_PIXEL_ERROR;
67
+ /** An asset shorter than this casts into the finest level only; see the layer above. */
68
+ export const SMALL_CASTER_METRES = 1.5;
69
+ /**
70
+ * Placements filtered per unit of admission work.
71
+ *
72
+ * One unit is what a frame can overshoot its budget by, so it is sized to stay small rather than to
73
+ * divide the work evenly: a slice is a few hundred placements' worth of matrix maths, tens of
74
+ * microseconds, whatever the cell holds. ponytail: a count, not a time — the budget is the clock,
75
+ * and this only decides how often it is read.
76
+ */
77
+ export const ADMISSION_SLICE_PLACEMENTS = 256;
78
+
79
+ export interface IWorldCellsInit extends IWorldCellsLoadOptions {
80
+ readonly reachRanges: Map<
81
+ IWorldCell,
82
+ Map<string, { min: number; max: number; minY: number; maxY: number }>
83
+ >;
84
+ readonly manifest: IWorldPackage;
85
+ readonly placements: ArrayBuffer;
86
+ readonly heightmap: Uint16Array;
87
+ readonly baseUrl: string;
88
+ /** `baseUrl` as the loader keys it: no leading slash, which is what a manifest lists. */
89
+ readonly logicalBase: string;
90
+ /**
91
+ * Asset ids the package named twice for one model, each pointing at the id that is kept. Built
92
+ * once in `load`, where the loader can be asked what each path really fetches; empty when nothing
93
+ * is a duplicate. See {@link assetAliases}.
94
+ */
95
+ readonly aliases: ReadonlyMap<string, string>;
96
+ /**
97
+ * Whether `load` fabricated the loader it hands in as `assets` instead of the game supplying one.
98
+ * `load` always passes a loader to the constructor, so `assets === undefined` cannot tell an owned
99
+ * loader from a caller's; this is the bit that can. Left out, ownership is `assets === undefined`.
100
+ */
101
+ readonly ownsAssets?: boolean;
102
+ }
103
+
104
+ /**
105
+ * Pixels one world unit covers at unit depth, from the vertical field of view and the raster height.
106
+ * The scale `ModelLod` divides an error by; see `IWorldCellsLoadOptions.autoLod`.
107
+ */
108
+ export function autoLodScale(autoLod: IWorldCellsLoadOptions["autoLod"]): number {
109
+ const fovY = autoLod?.fovY ?? DEFAULT_AUTO_LOD_FOV_Y;
110
+ const viewportHeight = autoLod?.viewportHeight ?? DEFAULT_AUTO_LOD_VIEWPORT_HEIGHT;
111
+ if (!Number.isFinite(fovY) || fovY <= 0 || fovY >= 180)
112
+ throw new Error("WorldCells autoLod.fovY must be a finite angle in (0, 180) degrees.");
113
+ if (!Number.isFinite(viewportHeight) || !(viewportHeight > 0))
114
+ throw new Error(
115
+ "WorldCells autoLod.viewportHeight must be a positive number of raster pixels.",
116
+ );
117
+ return viewportHeight / (2 * Math.tan((fovY * Math.PI) / 360));
118
+ }
119
+
120
+ /** The screen-space error budget a synthesized level is switched at, in pixels. */
121
+ export function autoLodPixelError(autoLod: IWorldCellsLoadOptions["autoLod"]): number {
122
+ const maxPixelError = autoLod?.maxPixelError ?? DEFAULT_AUTO_LOD_MAX_PIXEL_ERROR;
123
+ if (!Number.isFinite(maxPixelError) || maxPixelError <= 0)
124
+ throw new Error("WorldCells autoLod.maxPixelError must be a positive number of pixels.");
125
+ return maxPixelError;
126
+ }
127
+
128
+ /** Default fraction of a 60 fps frame the main pass may take before the bias rises. */
129
+ export const DEFAULT_MAIN_GPU_SHARE = 0.5;
130
+
131
+ /**
132
+ * One launch override, read once: the environment, then the query string, then the global a test
133
+ * sets. The same three ways a debug flag is asked, but the answer is kept as text so a number can
134
+ * be parsed by the caller rather than rounded here.
135
+ */
136
+ function launchValue(parameter: string, flag: string, globalName: string): string | undefined {
137
+ const host = globalThis as { process?: { env?: Record<string, unknown> } } & Record<
138
+ string,
139
+ unknown
140
+ >;
141
+ const env = host.process?.env?.[flag];
142
+ if (typeof env === "string" && env !== "") return env;
143
+ const query = globalThis.location?.search;
144
+ if (typeof query === "string") {
145
+ const value = new URLSearchParams(query).get(parameter);
146
+ if (value !== null) return value;
147
+ }
148
+ const global = host[globalName];
149
+ if (typeof global === "number") return String(global);
150
+ return typeof global === "string" ? global : undefined;
151
+ }
152
+
153
+ /**
154
+ * Whether a launch opts into the whole-asset impostors: off unless `?tnImpostors=1`, `TN_IMPOSTORS=1`
155
+ * or `__tnImpostors = 1` says so. Opt-in because the judged Machinefall capture of the default
156
+ * (PRD-473 AC-3, 2026-10-14) read REGRESSION — ground shadows and canopy density differ — and its
157
+ * pinned frame windows showed no frame-time gain, so a game gets the source levels it had until the
158
+ * proof passes. `impostors: true` still asks explicitly.
159
+ */
160
+ export function impostorsRequested(): boolean {
161
+ const raw = launchValue("tnImpostors", "TN_IMPOSTORS", "__tnImpostors");
162
+ return raw === "1" || raw === "true";
163
+ }
164
+
165
+ /** Whether the adaptive LOD bias runs: on unless a launch pins it off. */
166
+ export function adaptiveLodRequested(): boolean {
167
+ const raw = launchValue("tnAdaptiveLod", "TN_ADAPTIVE_LOD", "__tnAdaptiveLod");
168
+ return raw === undefined ? true : raw !== "0" && raw !== "false";
169
+ }
170
+
171
+ /** The main-pass GPU share: the option, then the launch override, then 0.5. */
172
+ export function mainGpuShare(option: number | undefined): number {
173
+ const raw = launchValue("tnMainGpuShare", "TN_MAIN_GPU_SHARE", "__tnMainGpuShare");
174
+ const launched = raw === undefined ? undefined : Number(raw);
175
+ const share = option ?? launched ?? DEFAULT_MAIN_GPU_SHARE;
176
+ if (!Number.isFinite(share) || share <= 0 || share > 1)
177
+ throw new Error("WorldCells mainGpuShare must be a number in (0, 1].");
178
+ return share;
179
+ }
180
+
181
+ /**
182
+ * Whether an asset whose cull ends inside the near ring keeps a far aggregate: `"ring"` unless the
183
+ * caller names the `"always"` override. A misspelled value throws rather than silently picking one.
184
+ */
185
+ export function impostorFarOption(value: "ring" | "always" | undefined): "ring" | "always" {
186
+ if (value === undefined) return "ring";
187
+ if (value === "ring" || value === "always") return value;
188
+ throw new Error('WorldCells impostorFar must be "ring" or "always".');
189
+ }