@threenative/core 0.3.12 → 0.3.15

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 (165) hide show
  1. package/README.md +1 -1
  2. package/capabilities.json +1047 -44
  3. package/dist/{assets-YUbXa3-Y.d.ts → assets-CfMKnOsK.d.ts} +78 -1
  4. package/dist/{canvas-layer-CWuFRT7G.d.ts → canvas-layer-G7ttVy7y.d.ts} +1 -1
  5. package/dist/{chunk-7UUT3TY5.js → chunk-2GPHICV6.js} +1 -1
  6. package/dist/{chunk-GMHATRPW.js → chunk-GEMQJBY4.js} +1650 -383
  7. package/dist/{chunk-VAZM36TV.js → chunk-H4J6IAJE.js} +17 -10
  8. package/dist/{chunk-5O73CDMR.js → chunk-QAMSM3Z5.js} +415 -27
  9. package/dist/{chunk-2Z44XSI2.js → chunk-QAQHYOWY.js} +3 -7
  10. package/dist/{chunk-DBELTTTM.js → chunk-U4YHUKKL.js} +1 -1
  11. package/dist/{chunk-OKXUCASC.js → chunk-VBBYWGAT.js} +3 -4
  12. package/dist/chunk-VP43GIWW.js +18 -0
  13. package/dist/{chunk-N5LRP4BR.js → chunk-VQRPEOKY.js} +66 -3
  14. package/dist/{chunk-6KLNISRJ.js → chunk-XDTZ4QMO.js} +11 -4
  15. package/dist/default-tone-mapping-GgKPTiBP.d.ts +4 -0
  16. package/dist/{game-D7pAzZUY.d.ts → game-k8K3hZai.d.ts} +72 -8
  17. package/dist/hot.d.ts +5 -4
  18. package/dist/hot.js +5 -8
  19. package/dist/index.d.ts +871 -1018
  20. package/dist/index.js +4786 -1631
  21. package/dist/{model-lod-B6BMqS1r.d.ts → model-lod-DPTzeCcD.d.ts} +4 -2
  22. package/dist/playtest.d.ts +5 -4
  23. package/dist/playtest.js +6 -5
  24. package/dist/quality-BADStsTn.d.ts +868 -0
  25. package/dist/react.d.ts +3 -2
  26. package/dist/render-environment.d.ts +170 -0
  27. package/dist/render-environment.js +352 -0
  28. package/dist/{renderer-DvFVoAgj.d.ts → renderer-BtOSseYf.d.ts} +29 -31
  29. package/dist/spells/index.js +1 -1
  30. package/dist/ui-layer.js +3 -2
  31. package/dist/worker.js +12 -5
  32. package/dist/world.d.ts +280 -16
  33. package/dist/world.js +1529 -642
  34. package/mcp/animation-server.mjs +1 -1
  35. package/mcp/engine-server.mjs +135 -11
  36. package/mcp/servers.mjs +4 -4
  37. package/package.json +10 -6
  38. package/scripts/ensure-mcp.mjs +6 -1
  39. package/src/animation-batch.ts +193 -0
  40. package/src/animation-layers.ts +7 -3
  41. package/src/animation.ts +209 -29
  42. package/src/asset-cache.ts +3 -3
  43. package/src/asset-memo.ts +202 -0
  44. package/src/assets.ts +436 -131
  45. package/src/auto-batch.ts +190 -44
  46. package/src/clustered-batch.ts +146 -3
  47. package/src/clustered-mesh.ts +548 -20
  48. package/src/compute-driven.ts +1 -1
  49. package/src/config.ts +8 -0
  50. package/src/debug.ts +119 -22
  51. package/src/dev-global.ts +54 -0
  52. package/src/displaced-surface.ts +428 -0
  53. package/src/engine-hooks.ts +37 -0
  54. package/src/frame-budget.ts +35 -3
  55. package/src/game-boot-phase.ts +269 -0
  56. package/src/game-dev-tools.ts +7 -14
  57. package/src/game-frame-loop.ts +45 -82
  58. package/src/game-startup.ts +145 -70
  59. package/src/game-ui.ts +84 -0
  60. package/src/game.ts +168 -552
  61. package/src/gamepad-mappings.ts +269 -0
  62. package/src/generated/console-markers.ts +14 -0
  63. package/src/geometry-capture.ts +28 -4
  64. package/src/gpu-readings.ts +98 -0
  65. package/src/gpu-scene-bvh.ts +149 -36
  66. package/src/grass-field.ts +628 -0
  67. package/src/hot.ts +4 -7
  68. package/src/index.ts +227 -8
  69. package/src/input.ts +237 -25
  70. package/src/instanced-batch-lod.ts +3 -8
  71. package/src/interpolation.ts +171 -40
  72. package/src/look/ao-admission.ts +4 -3
  73. package/src/look/auto-exposure.ts +5 -16
  74. package/src/look/default-tone-mapping.ts +41 -5
  75. package/src/look/local-exposure.ts +2 -7
  76. package/src/look/quad-pass.ts +21 -0
  77. package/src/look/quality.ts +4 -0
  78. package/src/look/unreal-bloom.ts +4 -13
  79. package/src/look/world-environment.ts +58 -115
  80. package/src/merge-parts.ts +20 -24
  81. package/src/model-lod.ts +97 -14
  82. package/src/particle-significance.ts +12 -0
  83. package/src/particles.ts +19 -10
  84. package/src/platform.ts +23 -4
  85. package/src/profiling/FrameStages.ts +5 -6
  86. package/src/profiling/Spans.ts +3 -17
  87. package/src/profiling/debug-telemetry.ts +2 -6
  88. package/src/profiling/render-list-validate.ts +6 -15
  89. package/src/projection-marker.ts +2 -1
  90. package/src/quiet-markers.ts +3 -10
  91. package/src/render/cpu-bvh.ts +100 -0
  92. package/src/render/depth-pyramid.ts +6 -14
  93. package/src/render/environment/environmentContribution.ts +202 -0
  94. package/src/render/environment/environmentRadiance.ts +44 -0
  95. package/src/render/environment/environmentSampleCache.ts +56 -0
  96. package/src/render/environment/environmentSampling.ts +201 -0
  97. package/src/render/environment/environmentSnapshot.ts +71 -0
  98. package/src/render/environment/gate.ts +57 -0
  99. package/src/render/material-key.ts +21 -1
  100. package/src/render/mesh-pool.ts +3 -19
  101. package/src/render/probe-trace.ts +872 -0
  102. package/src/render/probe-volume.ts +780 -34
  103. package/src/render/radiance-cache.ts +17 -0
  104. package/src/render/screen-probe-gather.ts +303 -0
  105. package/src/render/short-range-ao.ts +274 -0
  106. package/src/render/virtual-shadow-partial.ts +13 -0
  107. package/src/render/virtual-shadow.ts +18 -16
  108. package/src/render/world-impostor-surface.ts +207 -9
  109. package/src/render/world-impostor.ts +5 -2
  110. package/src/render-camera-cull.ts +105 -4
  111. package/src/render-environment.ts +41 -0
  112. package/src/renderer-config.ts +36 -0
  113. package/src/renderer-facts.ts +37 -0
  114. package/src/renderer.ts +78 -32
  115. package/src/resolution-scaler.ts +3 -2
  116. package/src/scatter-field.ts +496 -0
  117. package/src/scene-entry-inspectors.ts +61 -0
  118. package/src/snow-field.ts +1 -0
  119. package/src/startup-offscreen-bytes.ts +84 -0
  120. package/src/state.ts +16 -3
  121. package/src/static-transform.ts +100 -25
  122. package/src/streamed-textures.ts +112 -0
  123. package/src/streaming.ts +68 -4
  124. package/src/texture-streaming.ts +331 -0
  125. package/src/tile-ring.ts +294 -0
  126. package/src/version.ts +1 -1
  127. package/src/warmup.ts +15 -2
  128. package/src/worker.ts +12 -2
  129. package/src/world-bundle-safety.ts +55 -10
  130. package/src/world-cell-batches.ts +166 -200
  131. package/src/world-cell-chunks.ts +3 -7
  132. package/src/world-cell-data.ts +7 -0
  133. package/src/world-cell-impostors.ts +20 -8
  134. package/src/world-cell-models.ts +36 -8
  135. package/src/world-cell-options.ts +2 -14
  136. package/src/world-cell-placements.ts +194 -90
  137. package/src/world-cell-prewarm.ts +39 -4
  138. package/src/world-cell-records.ts +401 -0
  139. package/src/world-cell-render-bundles.ts +2 -2
  140. package/src/world-cell-render-gpu-dress.ts +17 -19
  141. package/src/world-cell-render-main-cull.ts +73 -17
  142. package/src/world-cell-render-util.ts +18 -5
  143. package/src/world-cell-render.ts +13 -5
  144. package/src/world-cell-residency.ts +15 -6
  145. package/src/world-cell-stale.ts +238 -0
  146. package/src/world-cells.ts +23 -6
  147. package/src/world-gpu-flags.ts +18 -50
  148. package/src/world-gpu-reference.ts +22 -8
  149. package/src/world-gpu-scene.ts +44 -24
  150. package/src/world-gpu-shadow.ts +21 -8
  151. package/src/world-gpu-types.ts +41 -13
  152. package/src/world-load-limiter.ts +5 -0
  153. package/src/world-model-sections.ts +80 -0
  154. package/src/world-river-ribbon.ts +273 -0
  155. package/src/world-root-frame.ts +39 -0
  156. package/src/world-shore-field.ts +91 -0
  157. package/src/world-static-pose.ts +163 -0
  158. package/src/world-surface-sampler.ts +48 -0
  159. package/src/world-terrain-splat.ts +10 -18
  160. package/src/world-tile-budget.ts +4 -11
  161. package/src/world-tiles.ts +79 -12
  162. package/src/world-validate.ts +6 -14
  163. package/src/world-warm.ts +51 -0
  164. package/src/world-water-bodies.ts +113 -3
  165. package/src/world.ts +13 -0
@@ -113,7 +113,7 @@ export class ComputeDrivenRegistry {
113
113
  ): void {
114
114
  const simulatedSeconds =
115
115
  simulation === undefined ? undefined : simulation.tick() * simulation.step;
116
- if (camera !== undefined) {
116
+ if (camera !== undefined && !this.#significance.idle) {
117
117
  const candidates: IBudgetCandidate[] = [];
118
118
  for (const { object, driven } of this.#entries.values()) {
119
119
  if (
package/src/config.ts CHANGED
@@ -336,6 +336,14 @@ export interface IThreeNativeConfig {
336
336
  readonly orientation?: ThreeNativeOrientation;
337
337
  readonly fullscreen?: boolean;
338
338
  readonly keepScreenOn?: boolean;
339
+ /**
340
+ * CPU priority of a shipped native game (PRD-859). `"game"`, the default, raises the game, render
341
+ * and present threads above other programs and lowers the game's own background work (shader
342
+ * compiles, workers, the HUD processes), through the route each OS allows without admin rights.
343
+ * `"normal"` keeps the OS default. The player reports what the OS applied on its
344
+ * `TN_PROCESS_PRIORITY` line. The browser owns scheduling, so a web build ignores it.
345
+ */
346
+ readonly priority?: "game" | "normal";
339
347
  /**
340
348
  * Maximum native presentation rate in frames per second. Left out, it follows the display's own
341
349
  * refresh rate capped at 120 on desktop and web, and stays 60 on mobile where the ceiling is
package/src/debug.ts CHANGED
@@ -3,18 +3,112 @@
3
3
  *
4
4
  * Two questions an agent answers differently in every game, both of which cost a rewrite: how do I
5
5
  * turn this on for one run without changing the code, and how does a capture script reach the object
6
- * it wants to look at. The answers here are one function each, and neither decides how anything
7
- * looks.
6
+ * it wants to look at. The answers here are one function each, neither decides how anything looks.
8
7
  */
9
8
 
10
- /** The shared global the engine's dev surfaces and `exposeDebug` both publish under. */
11
- const HOST_KEY = "__THREENATIVE__";
9
+ import { devGlobal, publishDevGlobal } from "./dev-global.js";
12
10
 
13
11
  /** `freeCam` → `FREE_CAM`. A name a developer typed becomes a name a shell can set. */
14
12
  function envName(name: string): string {
15
13
  return `TN_DEBUG_${name.replace(/([a-z0-9])([A-Z])/gu, "$1_$2").toUpperCase()}`;
16
14
  }
17
15
 
16
+ /**
17
+ * The three seams a launch has, named once. A native host sets the environment variable, a browser
18
+ * page asks with the query parameter, and a test or capture harness sets the global before boot.
19
+ */
20
+ export interface ILaunchFlagSpec {
21
+ /** Environment variable a native host sets, e.g. `TN_TERRAIN_VALIDATE`. */
22
+ readonly environment: string;
23
+ /** Query parameter a browser asks with, e.g. `tnTerrainValidate`. */
24
+ readonly query: string;
25
+ /** Global a test or harness sets before the game boots, e.g. `__tnTerrainValidate`. */
26
+ readonly global?: string;
27
+ }
28
+
29
+ /**
30
+ * Every seam that named `flag`, in the order they are read: environment, query string, global.
31
+ *
32
+ * An empty environment variable is skipped — a shell that exports a name with no value did not ask
33
+ * for anything — while an empty value on any other seam means the seam named the flag and had no
34
+ * value to give, which is a URL's way of saying yes.
35
+ */
36
+ function readLaunchSeams(spec: ILaunchFlagSpec, search?: string): readonly string[] {
37
+ const values: string[] = [];
38
+ if (spec.environment.length > 0) {
39
+ const env = envValue(spec.environment);
40
+ if (env !== undefined && env !== "") values.push(env);
41
+ }
42
+ const query = search ?? globalThis.location?.search;
43
+ if (typeof query === "string") {
44
+ const fromQuery = new URLSearchParams(query).get(spec.query);
45
+ if (fromQuery !== null) values.push(fromQuery);
46
+ }
47
+ if (spec.global !== undefined) {
48
+ const fromGlobal: unknown = (globalThis as Record<string, unknown>)[spec.global];
49
+ if (typeof fromGlobal === "string") values.push(fromGlobal);
50
+ else if (typeof fromGlobal === "number") values.push(String(fromGlobal));
51
+ else if (typeof fromGlobal === "boolean") values.push(fromGlobal ? "true" : "false");
52
+ }
53
+ return values;
54
+ }
55
+
56
+ /** `0` and `false` are the only two spellings of off; a named-but-empty value is on. */
57
+ function isOff(value: string): boolean {
58
+ return value === "0" || value === "false";
59
+ }
60
+
61
+ /**
62
+ * Whether this launch asked for a flag, on one rule for every subsystem.
63
+ *
64
+ * `askedFor` says which answer the caller cares about: an opt-in switch (`"on"`, the default) is off
65
+ * when no seam asked for it, and an opt-out switch (`"off"`) is on unless some seam asked it off.
66
+ * Every seam that names the flag is heard, so a global a test sets is not lost behind an environment
67
+ * variable that happens to disagree; what changes from the sixteen hand-written readers this
68
+ * replaces is the vocabulary, not the seams: `0` and `false` are off and everything else is on.
69
+ *
70
+ * `search` is the query string to read, for a caller that already read the URL once at setup.
71
+ *
72
+ * @situation read one of the engine's launch switches the same way every subsystem does
73
+ * @example const validate = readLaunchFlag({ environment: "TN_TERRAIN_VALIDATE", query: "tnTerrainValidate" });
74
+ * @constraint `0` and `false` are off; a named-but-empty value is on; an empty variable is unset
75
+ */
76
+ export function readLaunchFlag(
77
+ spec: ILaunchFlagSpec,
78
+ askedFor: "on" | "off" = "on",
79
+ search?: string,
80
+ ): boolean {
81
+ const values = readLaunchSeams(spec, search);
82
+ return askedFor === "off"
83
+ ? values.some((value) => isOff(value))
84
+ : values.some((value) => !isOff(value));
85
+ }
86
+
87
+ /**
88
+ * The text this launch gave a flag, or `undefined` when no seam named it.
89
+ *
90
+ * For switches whose value is not a yes or no — an occlusion mode, a numeric override — the caller
91
+ * parses. An empty string means a seam named the flag with no value.
92
+ *
93
+ * @situation read a launch override whose value is not a boolean
94
+ * @example const mode = readLaunchValue({ environment: "TN_OCCLUSION", query: "tnOcclusion" });
95
+ */
96
+ export function readLaunchValue(spec: ILaunchFlagSpec): string | undefined {
97
+ return readLaunchSeams(spec)[0];
98
+ }
99
+
100
+ /**
101
+ * Every value this launch gave a flag, one per seam that named it, in the order they are read.
102
+ *
103
+ * For the switches whose answer is not a yes or a no — a tri-state, a table of spellings — the
104
+ * caller classifies the whole set rather than only the first seam's answer.
105
+ *
106
+ * @situation classify every value a launch gave one switch
107
+ */
108
+ export function readLaunchValues(spec: ILaunchFlagSpec): readonly string[] {
109
+ return readLaunchSeams(spec);
110
+ }
111
+
18
112
  /**
19
113
  * `process.env` on a host that installed one, narrowed rather than asserted exactly as
20
114
  * `isDevLaunch` does in `game.ts`: it exists on the native runtime and not in a browser bundle.
@@ -31,15 +125,10 @@ function envValue(name: string): string | undefined {
31
125
  return typeof value === "string" ? value : undefined;
32
126
  }
33
127
 
34
- /** Not one of the two spellings of off. */
35
- function isOn(value: string): boolean {
36
- return value !== "0" && value !== "false";
37
- }
38
-
39
128
  /**
40
129
  * A debug switch read from the URL, or from the environment on a native launch.
41
130
  *
42
- * @situation read a debug toggle from the URL or an environment variable
131
+ * @situation read a debug toggle from the URL, an environment variable or a harness global
43
132
  *
44
133
  * A browser asks with the query string — `?freeCam`, or `?freeCam=0` to force it off — and a native
45
134
  * launch asks with `TN_DEBUG_FREE_CAM`, because a query string is not something a developer sets on
@@ -47,14 +136,23 @@ function isOn(value: string): boolean {
47
136
  * "off" rather than quietly turning it back on.
48
137
  */
49
138
  export function debugFlag(name: string): boolean {
50
- // An exported-but-empty variable is off, as `DEV_MODE=` is to the engine's own reader; a bare
51
- // `?freeCam` is on, because the query string has no other way to say it.
52
- const env = envValue(envName(name));
53
- if (env !== undefined && env !== "" && isOn(env)) return true;
54
- const search: unknown = globalThis.location?.search;
55
- if (typeof search !== "string") return false;
56
- const value = new URLSearchParams(search).get(name);
57
- return value !== null && isOn(value);
139
+ return readLaunchFlag({ environment: envName(name), query: name });
140
+ }
141
+
142
+ /**
143
+ * The text this launch gave a debug switch, or `undefined` when no seam named it.
144
+ *
145
+ * `debugFlag`'s non-boolean sibling: the same naming rule — `?name` on the web, `TN_DEBUG_NAME` on
146
+ * a native launch — for a switch whose value is a word rather than a yes or no, such as a quality
147
+ * tier or a mode. An empty string means a seam named the switch and gave no value.
148
+ *
149
+ * @situation read a debug override whose value is not a boolean
150
+ * @situation override a quality tier or a mode for one run without changing the code
151
+ * @constraint a name in camelCase becomes UPPER_SNAKE: `debugValue("quality")` reads `?quality=` or `TN_DEBUG_QUALITY`
152
+ * @example const tier = debugValue("quality");
153
+ */
154
+ export function debugValue(name: string): string | undefined {
155
+ return readLaunchValue({ environment: envName(name), query: name });
58
156
  }
59
157
 
60
158
  /**
@@ -74,9 +172,8 @@ export function exposeDebug(name: string, value: unknown): void {
74
172
  const isDev =
75
173
  (import.meta as ImportMeta & { env?: Record<"DEV", boolean | undefined> }).env?.DEV === true;
76
174
  if (!isDev) return;
77
- const tools = (Reflect.get(globalThis, HOST_KEY) ?? {}) as { debug?: Record<string, unknown> };
78
- const debug = tools.debug ?? {};
175
+ const tools = devGlobal(globalThis) ?? {};
176
+ const debug = (tools.debug as Record<string, unknown> | undefined) ?? {};
79
177
  debug[name] = value;
80
- tools.debug = debug;
81
- Reflect.set(globalThis, HOST_KEY, tools);
178
+ publishDevGlobal("debug", debug, globalThis);
82
179
  }
@@ -0,0 +1,54 @@
1
+ /**
2
+ * The one owner of `__THREENATIVE__`, the object every dev surface publishes under.
3
+ *
4
+ * Five places used to spell the key itself — the debug flag, hot reload, the game's dev tools, the
5
+ * UI overlay and the engine's export — so the global's name and its shape were written twice at
6
+ * least. The worker keeps its own mirror list: that list is a typed tuple its mirror machinery is
7
+ * built from, and moving it here changed what the worker host forwarded.
8
+ *
9
+ * Nothing here decides how anything looks: it is the seam a capture script, the console and the dev
10
+ * overlay reach the running game through.
11
+ */
12
+
13
+ /** The property name a dev surface publishes under, on the window and on a worker's global. */
14
+ export const DEV_GLOBAL_KEY = "__THREENATIVE__";
15
+
16
+ /** What the game's own dev tools publish: a snapshot, and an armed geometry capture. */
17
+ export interface IDevTools {
18
+ snapshot(): import("./entities.js").EntitySnapshot;
19
+ /**
20
+ * Arms one per-object geometry capture for a development overlay. Absent until the game has a
21
+ * render loop; the overlay treats that as "not ready", never as an empty scene.
22
+ */
23
+ geometry?(
24
+ request?: import("./geometry-capture.js").IGeometryCaptureRequest,
25
+ ): Promise<import("./geometry-capture.js").IGeometryCaptureReport>;
26
+ }
27
+
28
+ /** What a dev surface may publish under {@link DEV_GLOBAL_KEY}. */
29
+ export type DevGlobal = Partial<IDevTools> & Record<string, unknown>;
30
+
31
+ /**
32
+ * The global a host installed, or `undefined` outside a dev launch.
33
+ *
34
+ * `scope` is required on purpose: a default of `globalThis` would make an explicit `undefined` read
35
+ * the page's global, which is exactly the worker case a caller is asking about.
36
+ */
37
+ export function devGlobal(scope: unknown): DevGlobal | undefined {
38
+ const value = (scope as Record<string, unknown> | undefined)?.[DEV_GLOBAL_KEY];
39
+ return typeof value === "object" && value !== null ? (value as DevGlobal) : undefined;
40
+ }
41
+
42
+ /** Adds one member to the global, keeping whatever another surface already published. */
43
+ export function publishDevGlobal(name: string, value: unknown, scope: unknown): void {
44
+ const host = scope as Record<string, unknown> | undefined;
45
+ if (host === undefined) return;
46
+ // In place: a surface that published earlier keeps its identity, which is what lets a disposer
47
+ // check `devGlobal(host) === mine` and leave another surface's members alone.
48
+ const current = devGlobal(scope);
49
+ if (current !== undefined) {
50
+ current[name] = value;
51
+ return;
52
+ }
53
+ host[DEV_GLOBAL_KEY] = { [name]: value };
54
+ }