@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
package/dist/react-css.js CHANGED
@@ -1,221 +1,7 @@
1
+ import { connectUiBridge } from './chunk-CFGTPFUH.js';
1
2
  import ReactReconciler from 'react-reconciler';
2
3
  import { DiscreteEventPriority, NoEventPriority } from 'react-reconciler/constants.js';
3
4
 
4
- // src/react-css.ts
5
-
6
- // src/ui-bridge.ts
7
- var UI_BRIDGE_GLOBALS = {
8
- /** UI end, inbound: the host calls this with one JSON string. */
9
- uiReceive: "__tnUiReceive",
10
- /** UI end, outbound: an injected object with `postMessage(string)`. */
11
- uiHost: "tnHost",
12
- /** Game end, inbound: the runtime calls this with one JSON string. */
13
- gameReceive: "__tnUiGameReceive",
14
- /** Game end, outbound: the runtime installs this and forwards to the web view. */
15
- gamePost: "__tnUiPost"
16
- };
17
- var stateFrames = /* @__PURE__ */ new WeakMap();
18
- function assertSendable(message) {
19
- if (typeof message !== "object" || message === null || Array.isArray(message)) {
20
- throw new Error("TN_UI_BRIDGE_MESSAGE_INVALID: a bridge message must be a JSON object.");
21
- }
22
- if (typeof message.type !== "string" || message.type.length === 0) {
23
- throw new Error("TN_UI_BRIDGE_MESSAGE_INVALID: a bridge message must carry a string 'type'.");
24
- }
25
- let frame;
26
- try {
27
- frame = stateFrames.get(message) ?? JSON.stringify(message);
28
- } catch (error) {
29
- throw new Error(
30
- `TN_UI_BRIDGE_MESSAGE_INVALID: '${message.type}' is not JSON-serialisable: ${error instanceof Error ? error.message : String(error)}`
31
- );
32
- }
33
- if (frame === void 0) {
34
- throw new Error(`TN_UI_BRIDGE_MESSAGE_INVALID: '${message.type}' serialised to nothing.`);
35
- }
36
- return frame;
37
- }
38
- function parseFrame(frame) {
39
- const text = typeof frame === "string" ? frame : frame?.data;
40
- if (typeof text !== "string") {
41
- throw new Error("TN_UI_BRIDGE_FRAME_INVALID: expected a JSON string from the host.");
42
- }
43
- let parsed;
44
- try {
45
- parsed = JSON.parse(text);
46
- } catch (error) {
47
- throw new Error(
48
- `TN_UI_BRIDGE_FRAME_INVALID: not JSON: ${error instanceof Error ? error.message : String(error)}`
49
- );
50
- }
51
- if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
52
- throw new Error("TN_UI_BRIDGE_FRAME_INVALID: a bridge frame must be a JSON object.");
53
- }
54
- if (typeof parsed.type !== "string") {
55
- throw new Error("TN_UI_BRIDGE_FRAME_INVALID: a bridge frame must carry a string 'type'.");
56
- }
57
- return parsed;
58
- }
59
- function findOutbound(scope, end) {
60
- if (end === "game") {
61
- const post = scope[UI_BRIDGE_GLOBALS.gamePost];
62
- return typeof post === "function" ? (frame) => post(frame) : void 0;
63
- }
64
- const injected = scope[UI_BRIDGE_GLOBALS.uiHost];
65
- if (typeof injected?.postMessage === "function") {
66
- return (frame) => injected.postMessage(frame);
67
- }
68
- const webkit = scope.webkit;
69
- const handler = webkit?.messageHandlers?.[UI_BRIDGE_GLOBALS.uiHost];
70
- if (typeof handler?.postMessage === "function") {
71
- return (frame) => handler.postMessage(frame);
72
- }
73
- const ipc = scope.ipc;
74
- if (typeof ipc?.postMessage === "function") {
75
- return (frame) => ipc.postMessage(frame);
76
- }
77
- return void 0;
78
- }
79
- var BROKER_KEY = "__tnUiBridgeBroker";
80
- function broker(scope) {
81
- const existing = scope[BROKER_KEY];
82
- if (existing !== void 0) return existing;
83
- const created = { game: /* @__PURE__ */ new Set(), ui: /* @__PURE__ */ new Set(), inbound: /* @__PURE__ */ new Map() };
84
- scope[BROKER_KEY] = created;
85
- return created;
86
- }
87
- function installInbound(scope, key, deliver) {
88
- const bus = broker(scope);
89
- let slot = bus.inbound.get(key);
90
- if (slot === void 0) {
91
- const receivers = /* @__PURE__ */ new Set();
92
- slot = {
93
- receivers,
94
- dispatch: (frame) => {
95
- let firstError;
96
- let failed = false;
97
- for (const receiver of [...receivers]) {
98
- try {
99
- receiver(frame);
100
- } catch (error) {
101
- if (!failed) {
102
- failed = true;
103
- firstError = error;
104
- }
105
- }
106
- }
107
- if (failed) throw firstError;
108
- }
109
- };
110
- bus.inbound.set(key, slot);
111
- }
112
- slot.receivers.add(deliver);
113
- scope[key] = slot.dispatch;
114
- const installed = slot;
115
- return () => {
116
- installed.receivers.delete(deliver);
117
- if (installed.receivers.size === 0 && scope[key] === installed.dispatch) scope[key] = void 0;
118
- };
119
- }
120
- var LOOPBACK_KEY = "__tnUiLoopback";
121
- function installLoopback(scope) {
122
- const search = scope.location?.search;
123
- if (typeof search !== "string" || new URLSearchParams(search).get("tnUiLoopback") !== "1") return;
124
- if (scope[LOOPBACK_KEY] !== void 0) return;
125
- const { port1: gamePort, port2: uiPort } = new MessageChannel();
126
- const receive = (key) => (event) => scope[key]?.(event.data);
127
- gamePort.onmessage = receive(UI_BRIDGE_GLOBALS.gameReceive);
128
- uiPort.onmessage = receive(UI_BRIDGE_GLOBALS.uiReceive);
129
- scope[UI_BRIDGE_GLOBALS.gamePost] = (frame) => gamePort.postMessage(frame);
130
- scope[UI_BRIDGE_GLOBALS.uiHost] = { postMessage: (frame) => uiPort.postMessage(frame) };
131
- scope.__tnUiOverlayAttached = () => true;
132
- scope[LOOPBACK_KEY] = {
133
- close() {
134
- gamePort.close();
135
- uiPort.close();
136
- for (const key of [UI_BRIDGE_GLOBALS.gamePost, UI_BRIDGE_GLOBALS.uiHost, LOOPBACK_KEY])
137
- scope[key] = void 0;
138
- scope.__tnUiOverlayAttached = void 0;
139
- }
140
- };
141
- }
142
- function connectUiBridge(options) {
143
- const { end } = options;
144
- if (end !== "game" && end !== "ui") {
145
- throw new Error(`TN_UI_BRIDGE_END_INVALID: expected 'game' or 'ui', got '${String(end)}'.`);
146
- }
147
- const scope = options.scope ?? globalThis;
148
- installLoopback(scope);
149
- const listeners = /* @__PURE__ */ new Set();
150
- const deliver = (frame) => {
151
- const message = parseFrame(frame);
152
- for (const listener of [...listeners]) listener(message);
153
- };
154
- const outbound = findOutbound(scope, end);
155
- const inboundKey = end === "ui" ? UI_BRIDGE_GLOBALS.uiReceive : UI_BRIDGE_GLOBALS.gameReceive;
156
- let closed = false;
157
- if (outbound === void 0) {
158
- const bus = broker(scope);
159
- const peer = end === "ui" ? "game" : "ui";
160
- const own = (message) => {
161
- for (const listener of [...listeners]) listener(message);
162
- };
163
- bus[end].add(own);
164
- return {
165
- end,
166
- transport: "in-process",
167
- hasPeer: () => bus[peer].size > 0,
168
- post(message) {
169
- const frame = assertSendable(message);
170
- if (closed) throw new Error("TN_UI_BRIDGE_CLOSED: post on a closed bridge.");
171
- const copy = JSON.parse(frame);
172
- for (const listener of [...bus[peer]]) listener(copy);
173
- },
174
- onMessage(listener) {
175
- listeners.add(listener);
176
- return () => listeners.delete(listener);
177
- },
178
- close() {
179
- closed = true;
180
- listeners.clear();
181
- bus[end].delete(own);
182
- }
183
- };
184
- }
185
- const uninstall = installInbound(scope, inboundKey, deliver);
186
- const injected = scope[UI_BRIDGE_GLOBALS.uiHost];
187
- if (end === "ui" && injected !== void 0 && typeof injected === "object") {
188
- injected.onmessage = (event) => deliver(event);
189
- }
190
- return {
191
- end,
192
- transport: "host",
193
- hasPeer() {
194
- const attached = scope.__tnUiOverlayAttached;
195
- if (end === "ui") return true;
196
- return typeof attached === "function" ? attached() === true : false;
197
- },
198
- post(message) {
199
- const frame = assertSendable(message);
200
- if (closed) throw new Error("TN_UI_BRIDGE_CLOSED: post on a closed bridge.");
201
- outbound(frame);
202
- },
203
- onMessage(listener) {
204
- listeners.add(listener);
205
- return () => listeners.delete(listener);
206
- },
207
- close() {
208
- closed = true;
209
- listeners.clear();
210
- uninstall();
211
- if (end === "ui" && injected !== void 0 && typeof injected === "object") {
212
- injected.onmessage = void 0;
213
- }
214
- }
215
- };
216
- }
217
-
218
- // src/react-css.ts
219
5
  var CSS_UI_MESSAGE = "tn:css";
220
6
  var CSS_UI_TAGS = [
221
7
  "div",
package/dist/react.d.ts CHANGED
@@ -1,8 +1,9 @@
1
1
  import { ReactNode } from 'react';
2
- import { C as CanvasLayer } from './canvas-layer-vCtanIeB.js';
2
+ import { C as CanvasLayer } from './canvas-layer-G7ttVy7y.js';
3
3
  import 'three';
4
- import './renderer-rZm0hVqq.js';
4
+ import './renderer-BtOSseYf.js';
5
5
  import 'three/webgpu';
6
+ import './default-tone-mapping-GgKPTiBP.js';
6
7
 
7
8
  /**
8
9
  * Every character this glyph set can draw, for error messages and for the templates' AGENTS.md.
@@ -0,0 +1,170 @@
1
+ import { Scene, Color, Texture } from 'three';
2
+ import { Q as QualityTier } from './quality-BYqKGAwo.js';
3
+ import 'three/tsl';
4
+ import 'three/webgpu';
5
+ import './default-tone-mapping-GgKPTiBP.js';
6
+
7
+ interface IEnvironmentMeasurement {
8
+ readonly status: "measured" | "unknown";
9
+ readonly meanRadiance: number | null;
10
+ readonly meanRGB: readonly [number, number, number] | null;
11
+ readonly reason: string;
12
+ }
13
+ /**
14
+ * CPU-readable equirectangular source radiance only; no DOM/canvas or invented JPEG mean.
15
+ * Rows are weighted by their exact spherical solid angle, rather than overweighting the poles.
16
+ * Arbitrary GPU/compressed/HTML/cube sources remain explicitly unknown until separately proven.
17
+ * @example const m = measureEnvironment(scene, 2048);
18
+ */
19
+ declare function measureEnvironment(scene: Scene, maxSourceTexels: number): IEnvironmentMeasurement;
20
+ /**
21
+ * What a contribution report reads: the backlight's gains and the source-texel limit.
22
+ *
23
+ * Exported because `reportEnvironmentContribution` takes it — a public function with a private
24
+ * parameter type cannot be called from a game, which is how its example failed to compile.
25
+ */
26
+ interface IContributionControls {
27
+ readonly darkThreshold: number;
28
+ readonly rimGain: number;
29
+ readonly fillGain: number;
30
+ readonly fillAdmitted: boolean;
31
+ readonly fillColor: Color;
32
+ readonly maxSourceTexels: number;
33
+ }
34
+ /**
35
+ * Overrides change the look, never whether its source contribution is measured/reported.
36
+ * @example
37
+ * reportEnvironmentContribution(scene, {
38
+ * darkThreshold: 0.02, fillAdmitted: true, fillColor: new Color(1, 1, 1), fillGain: 0.4,
39
+ * maxSourceTexels: 2048, rimGain: 0.6,
40
+ * });
41
+ */
42
+ declare function reportEnvironmentContribution(scene: Scene, options: IContributionControls, measurement?: IEnvironmentMeasurement): {
43
+ scope: string;
44
+ environmentState: string;
45
+ ibl: string;
46
+ analyticFill: {
47
+ requestedGain: number;
48
+ admitted: boolean;
49
+ effectiveGain: number;
50
+ color: number[];
51
+ blackColorOverride: boolean;
52
+ reason: string;
53
+ };
54
+ rimGain: number;
55
+ fillGain: number;
56
+ darkThreshold: number;
57
+ status: "measured" | "unknown";
58
+ meanRadiance: number | null;
59
+ meanRGB: readonly [number, number, number] | null;
60
+ reason: string;
61
+ };
62
+
63
+ /**
64
+ * The mean radiance and colour of a bounded linear sample, or `unknown` with the reason.
65
+ *
66
+ * @situation turn an environment readback into the radiance a material's fill light needs
67
+ * @situation know why an environment sample could not be measured
68
+ * @constraint the sample must be the qualified 64x32 float RGBA readback; anything else is refused by name
69
+ * @example const m = sampledRadiance(readback, 1);
70
+ */
71
+ declare function sampledRadiance(samples: unknown, intensity: number): IEnvironmentMeasurement;
72
+
73
+ /** Provenance stays outside the printable measurement; source/image references are borrowed. */
74
+ interface IEnvironmentSourceSnapshot {
75
+ readonly source: Texture | null;
76
+ readonly intensity: number;
77
+ readonly textureVersion: number | null;
78
+ readonly sourceVersion: number | null;
79
+ readonly colorSpace: string | null;
80
+ readonly mapping: number | null;
81
+ readonly image: unknown;
82
+ }
83
+ /**
84
+ * The provenance of a scene's environment: which texture, at which intensity, in which colour space.
85
+ *
86
+ * @situation reject an environment readback that belongs to a different sky
87
+ * @example const snapshot = captureEnvironmentSnapshot(scene);
88
+ */
89
+ declare function captureEnvironmentSnapshot(scene: Scene): IEnvironmentSourceSnapshot;
90
+ /**
91
+ * Whether the scene's environment still matches the snapshot a sample was taken from.
92
+ *
93
+ * @situation hold a material's fill light to the sky that is on screen now
94
+ * @example if (environmentSnapshotCurrent(scene, snapshot)) draw(snapshot);
95
+ */
96
+ declare function environmentSnapshotCurrent(scene: Scene, snapshot: IEnvironmentSourceSnapshot): boolean;
97
+ /**
98
+ * Whether an environment texture's mapping and colour space are qualified for the bounded GPU sample.
99
+ *
100
+ * @situation know why an environment was not sampled on the GPU
101
+ * @example if (samplingSourceSupported(source)) sample(source);
102
+ */
103
+ declare function samplingSourceSupported(source: NonNullable<Scene["environment"]>): boolean;
104
+
105
+ /**
106
+ * Which renderers may run the material-lighting lane, and whether a renderer is running three's
107
+ * WebGL backend behind a WebGPU wrapper.
108
+ *
109
+ * Both questions are asked by the environment sampling mechanism beside this file, and both were
110
+ * answered in each template's `quality.ts` — twelve copies of the same predicate, so a fix to one
111
+ * left eleven kits admitting a renderer the fix refused. The tier they compare is the caller's, so
112
+ * a game that wants a different admission rule passes its own tier; nothing here decides how
113
+ * anything looks.
114
+ */
115
+
116
+ /** First admitted material lane: high desktop hardware WebGPU in the browser only. */
117
+ interface IMaterialLightingEnvironment {
118
+ readonly web: boolean;
119
+ readonly rendererKind: string;
120
+ readonly mobile?: boolean;
121
+ readonly software?: boolean;
122
+ readonly webglFallback?: boolean;
123
+ }
124
+ /**
125
+ * Whether `tier` may run the material-lighting lane in `environment`.
126
+ *
127
+ * @situation decide whether this renderer is the admitted material lane
128
+ * @constraint high tier, browser, hardware WebGPU, not mobile, not software, not a WebGL fallback
129
+ * @example if (materialLightingEnabled("high", env)) lightMaterials();
130
+ */
131
+ declare function materialLightingEnabled(tier: QualityTier, environment: IMaterialLightingEnvironment): boolean;
132
+ /**
133
+ * Whether a `WebGPURenderer` wrapper is running three's WebGL backend behind it.
134
+ *
135
+ * @situation refuse a GPU-only lane on a WebGL fallback instead of drawing something wrong
136
+ * @example if (isWebGLFallbackRenderer(renderer)) skipMaterialLane();
137
+ */
138
+ declare function isWebGLFallbackRenderer(renderer: unknown): boolean;
139
+
140
+ interface IEnvironmentSample extends IEnvironmentSourceSnapshot {
141
+ readonly measurement: IEnvironmentMeasurement;
142
+ }
143
+ /**
144
+ * Measures and samples the scene's real environment on the GPU, bounded by a readback deadline.
145
+ *
146
+ * @situation measure what a scene's environment actually contributes without stalling the frame
147
+ * @situation give a material's fill light the environment's own radiance
148
+ * @constraint off unless the renderer is the admitted high-tier WebGPU lane; every refusal is reported by name
149
+ * @constraint the readback is abandoned after the deadline and the frame keeps the previous answer
150
+ * @example const sample = await sampleEnvironment(renderer, scene, env);
151
+ */
152
+ declare function sampleEnvironment(renderer: unknown, scene: Scene, environment: IMaterialLightingEnvironment): Promise<IEnvironmentSample>;
153
+
154
+ /**
155
+ * The sample this renderer took of `scene`'s environment, if it is still current.
156
+ *
157
+ * @situation skip a second environment readback in the same frame
158
+ * @constraint a sample whose source texture or intensity moved is dropped, so a stale one never reaches a material
159
+ * @example const hit = cachedEnvironmentSample(renderer, scene);
160
+ */
161
+ declare function cachedEnvironmentSample(renderer: object, scene: Scene): IEnvironmentSample | undefined;
162
+ /**
163
+ * Remembers `sample` as this renderer's reading of `scene`'s environment.
164
+ *
165
+ * @situation reuse one environment readback across the materials of a scene
166
+ * @example cacheEnvironmentSample(renderer, scene, sample);
167
+ */
168
+ declare function cacheEnvironmentSample(renderer: object, scene: Scene, sample: IEnvironmentSample): void;
169
+
170
+ export { type IEnvironmentMeasurement, type IEnvironmentSample, type IEnvironmentSourceSnapshot, type IMaterialLightingEnvironment, cacheEnvironmentSample, cachedEnvironmentSample, captureEnvironmentSnapshot, environmentSnapshotCurrent, isWebGLFallbackRenderer, materialLightingEnabled, measureEnvironment, reportEnvironmentContribution, sampleEnvironment, sampledRadiance, samplingSourceSupported };