@threenative/core 0.3.10 → 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 (158) 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 +10565 -22533
  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-camera-cull.ts +32 -1
  84. package/src/render-pass-budget.ts +34 -7
  85. package/src/renderProjection.ts +22 -0
  86. package/src/renderer.ts +92 -37
  87. package/src/snow-field.ts +1 -1
  88. package/src/spells/cast-pool.ts +361 -0
  89. package/src/spells/index.ts +177 -0
  90. package/src/spells/mechanisms.ts +295 -0
  91. package/src/spells/reaction-field.ts +415 -0
  92. package/src/spells/spell-lights.ts +139 -0
  93. package/src/spells/spell-world.ts +187 -0
  94. package/src/spells/spell.ts +397 -0
  95. package/src/spells/spells.ts +283 -0
  96. package/src/spells/ultra/engine/camera.ts +184 -0
  97. package/src/spells/ultra/engine/quality.ts +96 -0
  98. package/src/spells/ultra/index.ts +52 -0
  99. package/src/spells/ultra/main.ts +305 -0
  100. package/src/spells/ultra/scene/arenaMaterial.ts +325 -0
  101. package/src/spells/ultra/spells/cast.ts +233 -0
  102. package/src/spells/ultra/spells/fire.ts +1267 -0
  103. package/src/spells/ultra/vfx/FluidVolume.ts +816 -0
  104. package/src/spells/ultra/vfx/FluidVolume.tsl.ts +855 -0
  105. package/src/spells/ultra/vfx/FxTarget.ts +61 -0
  106. package/src/spells/ultra/vfx/GroundField.ts +1399 -0
  107. package/src/spells/ultra/vfx/Particles.ts +1475 -0
  108. package/src/spells/ultra/vfx/Ribbons.ts +645 -0
  109. package/src/spells/ultra/vfx/Shockwaves.ts +286 -0
  110. package/src/spells/ultra/vfx/Volumes.ts +489 -0
  111. package/src/spells/ultra/vfx/common.ts +1195 -0
  112. package/src/spells/ultra/vfx/noise.ts +441 -0
  113. package/src/startup-readiness.ts +128 -34
  114. package/src/version.ts +1 -1
  115. package/src/warmup.ts +56 -8
  116. package/src/water-surface.ts +9 -3
  117. package/src/world-bundle-safety.ts +401 -0
  118. package/src/world-cell-batches.ts +1216 -0
  119. package/src/world-cell-chunks.ts +1132 -0
  120. package/src/world-cell-data.ts +995 -0
  121. package/src/world-cell-impostors.ts +1449 -0
  122. package/src/world-cell-lod-bias.ts +151 -0
  123. package/src/world-cell-models.ts +1074 -0
  124. package/src/world-cell-options.ts +189 -0
  125. package/src/world-cell-placements.ts +694 -0
  126. package/src/world-cell-prewarm.ts +557 -0
  127. package/src/world-cell-readiness.ts +357 -0
  128. package/src/world-cell-render-bundles.ts +459 -0
  129. package/src/world-cell-render-gpu-dress.ts +714 -0
  130. package/src/world-cell-render-main-cull.ts +484 -0
  131. package/src/world-cell-render-shadow-claims.ts +198 -0
  132. package/src/world-cell-render-util.ts +246 -0
  133. package/src/world-cell-render.ts +1493 -0
  134. package/src/world-cell-residency.ts +745 -0
  135. package/src/world-cells.ts +1318 -10418
  136. package/src/world-chunk-shadow.ts +308 -0
  137. package/src/world-collar.ts +315 -0
  138. package/src/world-gpu-flags.ts +163 -0
  139. package/src/world-gpu-readback.ts +881 -0
  140. package/src/world-gpu-reference.ts +510 -0
  141. package/src/world-gpu-scene.ts +214 -2264
  142. package/src/world-gpu-shadow.ts +190 -0
  143. package/src/world-gpu-types.ts +381 -0
  144. package/src/world-gpu-validation.ts +518 -0
  145. package/src/world-heightfield.ts +802 -0
  146. package/src/world-load-limiter.ts +106 -0
  147. package/src/world-noise.ts +241 -0
  148. package/src/world-package.ts +42 -0
  149. package/src/world-region.ts +1 -1
  150. package/src/world-terrain-splat.ts +365 -149
  151. package/src/world-tile-budget.ts +256 -0
  152. package/src/world-tile-geometry.ts +469 -0
  153. package/src/world-tile-lod.ts +408 -0
  154. package/src/world-tile-observation.ts +566 -0
  155. package/src/world-tile-stitch.ts +166 -0
  156. package/src/world-tiles.ts +170 -1745
  157. package/src/world-water-bodies.ts +359 -0
  158. package/src/world.ts +35 -741
@@ -486,10 +486,12 @@ export interface IFrameBudgetWindow {
486
486
  export interface IFrameBudgetSimulation {
487
487
  readonly tick: () => number;
488
488
  readonly step: number;
489
+ /** False counts presented frames while the simulation has not advanced in the window. */
490
+ readonly clockFrozen?: boolean;
489
491
  }
490
492
 
491
493
  export interface IFrameBudgetOptions {
492
- /** Simulation ticks per report window when a clock is supplied, otherwise presented frames. Default 300. */
494
+ /** Simulation ticks per window; presented frames without a clock or while a live one is held. Default 300. */
493
495
  readonly reportEvery?: number;
494
496
  /** Minimum measured rendered frames per report window. Default 1. */
495
497
  readonly minFrames?: number;
@@ -1111,8 +1113,9 @@ export class FrameBudget {
1111
1113
  }
1112
1114
 
1113
1115
  /**
1114
- * Closes the frame and returns its phase split, or `undefined` when the frame was a hitch and
1115
- * therefore excluded — a 27-second startup stall is not a frame time and must not enter a
1116
+ * Closes the frame and returns its phase split, or `undefined` when `wantSample` is false. A hitch
1117
+ * still returns its split — `loop.ts` feeds it to the per-frame diagnostics — and the window meters
1118
+ * below are what exclude it: a 27-second startup stall is not a frame time and must not enter a
1116
1119
  * percentile anybody is asked to act on.
1117
1120
  *
1118
1121
  * `wantSample` is false when the caller is going to discard the split, which is the default
@@ -1138,6 +1141,20 @@ export class FrameBudget {
1138
1141
  : 0;
1139
1142
  if (drawn) this.#lastDrawnTimestamp = this.#frameTimestamp;
1140
1143
 
1144
+ const update = Math.max(0, simulationEnd - this.#frameStart);
1145
+ const tail = Math.max(0, nowMs - simulationEnd);
1146
+ const residual = Math.max(0, tail - this.#renderMs - this.#overlayMs - this.#uiMs);
1147
+ const sample: IFramePhaseSample | undefined = wantSample
1148
+ ? {
1149
+ hostGap: round(this.#hostGap),
1150
+ overlay: round(this.#overlayMs),
1151
+ render: round(this.#renderMs),
1152
+ residual: round(residual),
1153
+ ui: round(this.#uiMs),
1154
+ update: round(update),
1155
+ }
1156
+ : undefined;
1157
+
1141
1158
  const isHitch = this.#presentedDelta >= this.hitchMs;
1142
1159
  if (isHitch) {
1143
1160
  // The gap is excluded, so the next drawn interval must not start before it.
@@ -1153,22 +1170,10 @@ export class FrameBudget {
1153
1170
  })}`,
1154
1171
  );
1155
1172
  this.#maybeReport();
1156
- return undefined;
1173
+ // Exclude the present gap from windows; diagnostics still need the measured callback phases.
1174
+ return sample;
1157
1175
  }
1158
1176
 
1159
- const update = Math.max(0, simulationEnd - this.#frameStart);
1160
- const tail = Math.max(0, nowMs - simulationEnd);
1161
- const residual = Math.max(0, tail - this.#renderMs - this.#overlayMs - this.#uiMs);
1162
- const sample: IFramePhaseSample | undefined = wantSample
1163
- ? {
1164
- hostGap: round(this.#hostGap),
1165
- overlay: round(this.#overlayMs),
1166
- render: round(this.#renderMs),
1167
- residual: round(residual),
1168
- ui: round(this.#uiMs),
1169
- update: round(update),
1170
- }
1171
- : undefined;
1172
1177
  this.#frame.push(frameMs);
1173
1178
  this.#substeps.push(this.#substepCount);
1174
1179
  // The first frame has no predecessor, so it has neither an interval nor a host gap; pushing a
@@ -1572,11 +1577,17 @@ export class FrameBudget {
1572
1577
  }
1573
1578
 
1574
1579
  #maybeReport(): void {
1575
- // Callers without a loop clock retain presented-frame window boundaries.
1576
- const elapsed =
1580
+ // A window counts simulation ticks, so the first one spans startup plus `reportEvery` ticks of
1581
+ // play. A live clock whose simulation has not advanced in this window counts presented frames,
1582
+ // so a held game still reports.
1583
+ const ticks =
1577
1584
  this.#simulation === undefined
1578
- ? this.#framesInWindow
1585
+ ? 0
1579
1586
  : this.#simulation.tick() - (this.#windowStartTick ?? this.#simulation.tick());
1587
+ const elapsed =
1588
+ this.#simulation === undefined || (this.#simulation.clockFrozen === false && ticks === 0)
1589
+ ? this.#framesInWindow
1590
+ : ticks;
1580
1591
  if (elapsed < this.reportEvery || this.#framesInWindow < this.minFrames) return;
1581
1592
  const completed = this.window();
1582
1593
  this.#report(`${FRAME_BUDGET_MARKER}:${JSON.stringify(completed)}`);
@@ -0,0 +1,93 @@
1
+ /// <reference path="./import-meta.d.ts" />
2
+
3
+ import type { EntitySnapshot, Registry } from "./entities.js";
4
+ import type {
5
+ GeometryCapture,
6
+ IGeometryCaptureReport,
7
+ IGeometryCaptureRequest,
8
+ } from "./geometry-capture.js";
9
+
10
+ interface IDevTools {
11
+ snapshot(): EntitySnapshot;
12
+ /**
13
+ * Arms one per-object geometry capture for a development overlay. Absent until the game has a
14
+ * render loop; the overlay treats that as "not ready", never as an empty scene.
15
+ */
16
+ geometry?(request?: IGeometryCaptureRequest): Promise<IGeometryCaptureReport>;
17
+ }
18
+
19
+ export type DevToolsHost = Record<string, unknown> &
20
+ Partial<Record<"__THREENATIVE__", Partial<IDevTools>>>;
21
+
22
+ /**
23
+ * The bundler's dev flag.
24
+ *
25
+ * The `import.meta.env` access must stay written out exactly here. Vite replaces that member
26
+ * expression at build time; any indirection — a variable holding `import.meta`, or a helper that
27
+ * takes it as an argument — survives into the bundle, where the game is compiled as a script and
28
+ * not a module, and the whole bundle then fails to parse with "Cannot use 'import.meta' outside a
29
+ * module". That is a game that never starts, so the literal access is load-bearing, not style.
30
+ */
31
+ function bundlerDevFlag(): boolean {
32
+ return (import.meta as IImportMeta).env?.DEV === true;
33
+ }
34
+
35
+ /**
36
+ * Whether this launch is a development one.
37
+ *
38
+ * A web build answers through Vite's own flag. A native build has no bundler flag at launch, so the
39
+ * host publishes `DEV_MODE` on `process.env` — the one place a game can read how it was started —
40
+ * and this reads it. Both routes answer the same question: should the dev surfaces exist.
41
+ */
42
+ export function isDevLaunch(): boolean {
43
+ // `process.env` exists only where a host installed one: the native runtime does, a browser
44
+ // bundle does not. Narrowed rather than asserted, so a host that installs something else
45
+ // answers "not dev" instead of reading a field that is not there.
46
+ const scope: unknown = globalThis;
47
+ if (typeof scope === "object" && scope !== null && "process" in scope) {
48
+ const hostProcess: unknown = scope.process;
49
+ if (typeof hostProcess === "object" && hostProcess !== null && "env" in hostProcess) {
50
+ const env: unknown = hostProcess.env;
51
+ if (typeof env === "object" && env !== null && "DEV_MODE" in env) {
52
+ const flag: unknown = env.DEV_MODE;
53
+ if (typeof flag === "string" && flag !== "" && flag !== "0" && flag !== "false")
54
+ return true;
55
+ }
56
+ }
57
+ }
58
+ return bundlerDevFlag();
59
+ }
60
+
61
+ export function installDevTools(
62
+ entities: Registry,
63
+ host: DevToolsHost | undefined,
64
+ // Late-bound: the capture is constructed with the render loop, after this install runs.
65
+ geometry: () => GeometryCapture | undefined,
66
+ ): () => void {
67
+ // Written out here, not through `isDevLaunch()`: the bundler must see the literal flag to strip
68
+ // this whole install from a production build, and a runtime `DEV_MODE` check cannot be stripped.
69
+ const isDev = (import.meta as IImportMeta).env?.DEV === true;
70
+ if (!isDev || host === undefined) return () => undefined;
71
+ const devTools: IDevTools = {
72
+ ...host.__THREENATIVE__,
73
+ geometry: async (request) => {
74
+ const capture = geometry();
75
+ if (capture === undefined) {
76
+ return {
77
+ reason: "TN_GEOMETRY_CAPTURE_NO_LOOP: the game has no running render loop to capture.",
78
+ status: "unavailable",
79
+ };
80
+ }
81
+ return capture.request(request);
82
+ },
83
+ snapshot: () => entities.snapshot(),
84
+ };
85
+ host.__THREENATIVE__ = devTools;
86
+ return () => {
87
+ if (host.__THREENATIVE__ !== devTools) return;
88
+ const remaining = Object.fromEntries(
89
+ Object.entries(devTools).filter(([key]) => key !== "snapshot" && key !== "geometry"),
90
+ );
91
+ host.__THREENATIVE__ = Object.keys(remaining).length === 0 ? undefined : remaining;
92
+ };
93
+ }