@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
@@ -0,0 +1,428 @@
1
+ // PRD-668 Phase 1: the price of displaced, diced triangles, counted before a dice pass exists.
2
+ // Read-only. It walks what the scene already submits and counts the patches and micro-triangles
3
+ // Unreal's Nanite tessellation would dice them into. It draws nothing and decides no look.
4
+ //
5
+ // Clean-room port of the rules, not the code (UE 5.8.3):
6
+ // - dice rate 2 px: `Engine/Source/Runtime/Renderer/Private/Nanite/NaniteCullRaster.cpp:147-152`
7
+ // - edge factor = edge length / max(nearer depth, near) * view-to-pixels / dice rate, a quarter past
8
+ // the fade distance: `Engine/Shaders/Private/Nanite/NaniteTessellation.ush:62-101`, with
9
+ // LODScale * InvDiceRate = ViewToPixels / DicingRate (`NaniteShared.cpp:197-199`,
10
+ // `NaniteCullRaster.cpp:6993`), ViewToPixels = 0.5 * ViewToClip[1][1] * view height
11
+ // - fade distance: `NaniteTessellation.ush:49-59`; the fade-out size is min(start 4, end 1) px when
12
+ // the material enables the fade and 0 (no fade) when it does not
13
+ // (`Engine/Source/Runtime/Engine/Private/Rendering/NaniteResources.cpp:774-791`)
14
+ // - magnitude 4 cm about a 0.5 center, range (0 - c) * m to (1 - c) * m:
15
+ // `Engine/Source/Runtime/Engine/Classes/Engine/EngineTypes.h:3446-3458`, `NaniteResources.cpp:792-793`
16
+ // - table of factors 1 to 14 and a split past it at TF / 14, capped at 8, ceil and clamp, each child
17
+ // culled and priced from its own points:
18
+ // `Engine/Shaders/Shared/NaniteDefinitions.h:125-128`, `NaniteTessellation.ush:103-106,141-144`,
19
+ // `Engine/Shaders/Private/Nanite/NaniteSplit.usf:117-258`
20
+ // - a uniform pattern of factor n holds n * n triangles:
21
+ // `Engine/Source/Runtime/Renderer/Private/Nanite/TessellationTable.cpp:233-236`
22
+ import type { BufferAttribute, InstancedMesh, Mesh, Object3D, PerspectiveCamera } from "three";
23
+ import { Matrix4 } from "three";
24
+
25
+ /** `r.Nanite.DicingRate`: pixels per micro-triangle edge. */
26
+ export const DICE_RATE_PIXELS = 2;
27
+ /** `NANITE_TESSELLATION_TABLE_SIZE`: the largest edge factor one pattern holds. */
28
+ const TABLE_SIZE = 14;
29
+ /** The cap on one split level's factor (`min(GetSplitFactors(...), 8)`). */
30
+ const SPLIT_CAP = 8;
31
+ /** `NANITE_TESSELLATION_MAX_PATCH_SPLIT_LEVELS`. */
32
+ const MAX_SPLIT_LEVELS = 6;
33
+ /** The hard-coded edge-factor multiple past the fade distance. */
34
+ const LOW_TESS_MULTIPLE = 0.25;
35
+
36
+ export interface IDisplacementPriceOptions {
37
+ /** Pixels per micro-triangle edge. Default 2, Unreal's. */
38
+ readonly diceRate?: number;
39
+ /** Displacement magnitude in metres. Default 0.04, Unreal's 4 cm. */
40
+ readonly magnitude?: number;
41
+ /** The height that does not move the surface. Default 0.5, Unreal's. */
42
+ readonly center?: number;
43
+ /** Pixels the largest displacement spans where the fade ends. Default 0: fade off, Unreal's stock material. */
44
+ readonly fadeOutPixels?: number;
45
+ /** Culls each patch against this buffer, as Unreal's split pass tests its HZB. Default: none. */
46
+ readonly occlusion?: IOcclusionBuffer;
47
+ }
48
+
49
+ /**
50
+ * A conservative stand-in for Unreal's HZB: per texel, the far depth of the nearest triangle that
51
+ * covers its center. A patch is hidden only when every texel under it holds an occluder wholly in
52
+ * front of it, so no patch is ever hidden by itself.
53
+ */
54
+ export interface IOcclusionBuffer {
55
+ readonly width: number;
56
+ readonly height: number;
57
+ readonly depth: Float32Array;
58
+ }
59
+
60
+ export interface IDisplacementPrice {
61
+ /** Triangles the scene submits now: draw ranges times drawn copies. */
62
+ triangles: number;
63
+ /** Of those, the ones not wholly outside one frustum plane. */
64
+ visibleTriangles: number;
65
+ /** Visible triangles with an edge factor above 1, the ones a dice pass would split. */
66
+ dicedTriangles: number;
67
+ /** Leaf patches the diced triangles split into. */
68
+ patches: number;
69
+ /** Micro-triangles the diced triangles become. */
70
+ microTriangles: number;
71
+ /** `microTriangles - dicedTriangles`: what dicing adds to the submitted count. */
72
+ addedMicroTriangles: number;
73
+ /** Metres past which edge factors drop to a quarter, for unit scale; 0 when the fade is off. */
74
+ fadeDistance: number;
75
+ }
76
+
77
+ function clampFactor(factor: number): number {
78
+ return Math.min(TABLE_SIZE, Math.max(1, Math.ceil(factor)));
79
+ }
80
+
81
+ /**
82
+ * Micro-triangles in the pattern for three edge factors, after Unreal's ceil and 1-14 clamp.
83
+ *
84
+ * Exact for a uniform pattern (n * n). Unreal remeshes a non-uniform pattern; this estimates its
85
+ * interior vertices from the mean factor and closes with Euler's T = 2I + B - 2.
86
+ * ponytail: estimate for non-uniform patterns; read Unreal's baked table counts if a gate sits on the edge.
87
+ */
88
+ export function patternTriangles(a: number, b: number, c: number): number {
89
+ const boundary = clampFactor(a) + clampFactor(b) + clampFactor(c);
90
+ const mean = boundary / 3;
91
+ const interior = Math.max(0, Math.round(((mean - 1) * (mean - 2)) / 2));
92
+ return 2 * interior + boundary - 2;
93
+ }
94
+
95
+ /** One edge's tessellation factor, as `GetTessFactors` computes it for a perspective view. */
96
+ export function edgeFactor(
97
+ edgeLength: number,
98
+ nearerDepth: number,
99
+ viewToPixels: number,
100
+ diceRate: number,
101
+ fadeDistance: number,
102
+ near: number,
103
+ ): number {
104
+ const depth = Math.max(nearerDepth, near);
105
+ const distant = fadeDistance > 0 && depth > fadeDistance;
106
+ return ((edgeLength / depth) * viewToPixels * (distant ? LOW_TESS_MULTIPLE : 1)) / diceRate;
107
+ }
108
+
109
+ /** The view depth where the largest displacement spans `fadeOutPixels`; 0 when the fade is off. */
110
+ export function displacementFadeDistance(
111
+ magnitude: number,
112
+ center: number,
113
+ maxScale: number,
114
+ viewToPixels: number,
115
+ fadeOutPixels: number,
116
+ ): number {
117
+ if (fadeOutPixels <= 0) return 0;
118
+ const largest = Math.max(center, 1 - center) * magnitude;
119
+ return (largest * maxScale * viewToPixels) / fadeOutPixels;
120
+ }
121
+
122
+ /** Visits the n * n children of a uniform barycentric grid over a patch's three view-space points. */
123
+ function splitGrid(points: Float64Array, n: number, visit: (child: Float64Array) => void): void {
124
+ const at = (row: number, column: number, into: Float64Array, slot: number): void => {
125
+ const w0 = 1 - row / n;
126
+ const w1 = (row - column) / n;
127
+ const w2 = column / n;
128
+ for (let axis = 0; axis < 3; axis += 1)
129
+ into[slot * 3 + axis] =
130
+ w0 * (points[axis] as number) +
131
+ w1 * (points[3 + axis] as number) +
132
+ w2 * (points[6 + axis] as number);
133
+ };
134
+ for (let row = 0; row < n; row += 1)
135
+ for (let column = 0; column <= row; column += 1) {
136
+ const up = new Float64Array(9);
137
+ at(row, column, up, 0);
138
+ at(row + 1, column, up, 1);
139
+ at(row + 1, column + 1, up, 2);
140
+ visit(up);
141
+ if (column === row) continue;
142
+ const down = new Float64Array(9);
143
+ at(row, column, down, 0);
144
+ at(row + 1, column + 1, down, 1);
145
+ at(row, column + 1, down, 2);
146
+ visit(down);
147
+ }
148
+ }
149
+
150
+ const scratchInstance = new Matrix4();
151
+ const scratchView = new Matrix4();
152
+ const view = new Float64Array(9);
153
+
154
+ /** Writes vertex `vertex` of `position`, through `m`, into slot `k` of `view`. */
155
+ function toView(position: BufferAttribute, vertex: number, m: number[], k: number): void {
156
+ const x = position.getX(vertex);
157
+ const y = position.getY(vertex);
158
+ const z = position.getZ(vertex);
159
+ view[k * 3] =
160
+ (m[0] as number) * x + (m[4] as number) * y + (m[8] as number) * z + (m[12] as number);
161
+ view[k * 3 + 1] =
162
+ (m[1] as number) * x + (m[5] as number) * y + (m[9] as number) * z + (m[13] as number);
163
+ view[k * 3 + 2] =
164
+ (m[2] as number) * x + (m[6] as number) * y + (m[10] as number) * z + (m[14] as number);
165
+ }
166
+
167
+ /**
168
+ * Calls `visit` with each triangle `root` submits now, in `camera`'s view space: every visible mesh,
169
+ * its draw range only, once per drawn instance.
170
+ */
171
+ function forEachSubmittedTriangle(
172
+ root: Object3D,
173
+ camera: PerspectiveCamera,
174
+ visit: (points: Float64Array, modelView: Matrix4) => void,
175
+ ): void {
176
+ root.updateMatrixWorld(true);
177
+ camera.updateMatrixWorld();
178
+ const each = (mesh: Mesh, modelView: Matrix4): void => {
179
+ const geometry = mesh.geometry;
180
+ const position = geometry.getAttribute("position") as BufferAttribute;
181
+ const index = geometry.getIndex();
182
+ const total = index === null ? position.count : index.count;
183
+ const start = Math.max(0, geometry.drawRange.start);
184
+ const end = Math.min(total, start + geometry.drawRange.count);
185
+ const m = modelView.elements;
186
+ for (let corner = start; corner + 2 < end; corner += 3) {
187
+ for (let k = 0; k < 3; k += 1) toView(position, index?.getX(corner + k) ?? corner + k, m, k);
188
+ visit(view, modelView);
189
+ }
190
+ };
191
+ root.traverseVisible((object) => {
192
+ const mesh = object as Mesh;
193
+ if (mesh.isMesh !== true) return;
194
+ const instanced = object as InstancedMesh;
195
+ if (instanced.isInstancedMesh !== true) {
196
+ each(mesh, scratchView.multiplyMatrices(camera.matrixWorldInverse, mesh.matrixWorld));
197
+ return;
198
+ }
199
+ for (let copy = 0; copy < instanced.count; copy += 1) {
200
+ instanced.getMatrixAt(copy, scratchInstance);
201
+ scratchView
202
+ .multiplyMatrices(camera.matrixWorldInverse, mesh.matrixWorld)
203
+ .multiply(scratchInstance);
204
+ each(mesh, scratchView);
205
+ }
206
+ });
207
+ }
208
+
209
+ /** Writes point `k` of `points` into `into` as buffer texels; false in front of the near plane. */
210
+ function toTexel(
211
+ points: Float64Array,
212
+ k: number,
213
+ projection: number[],
214
+ near: number,
215
+ buffer: { readonly width: number; readonly height: number },
216
+ into: number[],
217
+ ): boolean {
218
+ const depth = -(points[k * 3 + 2] as number);
219
+ if (depth < near) return false;
220
+ const cx =
221
+ (projection[0] as number) * (points[k * 3] as number) - (projection[8] as number) * depth;
222
+ const cy =
223
+ (projection[5] as number) * (points[k * 3 + 1] as number) - (projection[9] as number) * depth;
224
+ into[k * 2] = (cx / depth + 1) * 0.5 * buffer.width;
225
+ into[k * 2 + 1] = (1 - cy / depth) * 0.5 * buffer.height;
226
+ return true;
227
+ }
228
+
229
+ /** The texel rectangle under three texel points, clamped to the buffer: left, right, top, bottom. */
230
+ function texelRect(
231
+ texel: number[],
232
+ width: number,
233
+ height: number,
234
+ ): [number, number, number, number] {
235
+ const xs = [texel[0] as number, texel[2] as number, texel[4] as number];
236
+ const ys = [texel[1] as number, texel[3] as number, texel[5] as number];
237
+ return [
238
+ Math.max(0, Math.floor(Math.min(...xs))),
239
+ Math.min(width - 1, Math.floor(Math.max(...xs))),
240
+ Math.max(0, Math.floor(Math.min(...ys))),
241
+ Math.min(height - 1, Math.floor(Math.max(...ys))),
242
+ ];
243
+ }
244
+
245
+ /** Keeps `far` at every texel center the triangle covers, where it is nearer than the buffer. */
246
+ function rasterize(buffer: IOcclusionBuffer, texel: number[], far: number): void {
247
+ const [x0, y0, x1, y1, x2, y2] = texel as [number, number, number, number, number, number];
248
+ const area = (x1 - x0) * (y2 - y0) - (x2 - x0) * (y1 - y0);
249
+ if (area === 0) return;
250
+ const [left, right, top, bottom] = texelRect(texel, buffer.width, buffer.height);
251
+ for (let y = top; y <= bottom; y += 1)
252
+ for (let x = left; x <= right; x += 1) {
253
+ const px = x + 0.5;
254
+ const py = y + 0.5;
255
+ // Signed by the area, so either winding covers the same texels.
256
+ const w0 = ((x2 - x1) * (py - y1) - (y2 - y1) * (px - x1)) * area;
257
+ const w1 = ((x0 - x2) * (py - y2) - (y0 - y2) * (px - x2)) * area;
258
+ const w2 = ((x1 - x0) * (py - y0) - (y1 - y0) * (px - x0)) * area;
259
+ const slot = y * buffer.width + x;
260
+ if (w0 >= 0 && w1 >= 0 && w2 >= 0 && far < (buffer.depth[slot] as number))
261
+ buffer.depth[slot] = far;
262
+ }
263
+ }
264
+
265
+ /**
266
+ * Rasterizes every triangle `root` submits into a `width` x `height` occlusion buffer.
267
+ *
268
+ * Each covered texel center keeps the smallest far depth over the triangles that cover it, so an
269
+ * occluder never claims to hide more than it does. Triangles that cross the near plane are skipped.
270
+ * ponytail: a CPU raster for a measurement; a real dice pass reads the GPU's own HZB.
271
+ */
272
+ export function occlusionBuffer(
273
+ root: Object3D,
274
+ camera: PerspectiveCamera,
275
+ width: number,
276
+ height: number,
277
+ ): IOcclusionBuffer {
278
+ const buffer: IOcclusionBuffer = {
279
+ depth: new Float32Array(width * height).fill(Number.POSITIVE_INFINITY),
280
+ height,
281
+ width,
282
+ };
283
+ const projection = camera.projectionMatrix.elements;
284
+ const texel = [0, 0, 0, 0, 0, 0];
285
+ forEachSubmittedTriangle(root, camera, (points) => {
286
+ for (let k = 0; k < 3; k += 1)
287
+ if (!toTexel(points, k, projection, camera.near, buffer, texel)) return;
288
+ rasterize(
289
+ buffer,
290
+ texel,
291
+ -Math.min(points[2] as number, points[5] as number, points[8] as number),
292
+ );
293
+ });
294
+ return buffer;
295
+ }
296
+
297
+ /** True when some texel under the patch holds no occluder wholly in front of `nearest`. */
298
+ function unoccluded(buffer: IOcclusionBuffer, texel: number[], nearest: number): boolean {
299
+ const [left, right, top, bottom] = texelRect(texel, buffer.width, buffer.height);
300
+ if (left > right || top > bottom) return true;
301
+ for (let y = top; y <= bottom; y += 1)
302
+ for (let x = left; x <= right; x += 1)
303
+ if ((buffer.depth[y * buffer.width + x] as number) >= nearest) return true;
304
+ return false;
305
+ }
306
+
307
+ /**
308
+ * Prices dicing every triangle `root` submits now, seen by `camera` at `viewportHeight` pixels.
309
+ *
310
+ * Frustum culling per patch, as Unreal's split pass does, and occlusion when `options.occlusion`
311
+ * is given (`NaniteSplit.usf:228`, `Cull.FrustumHZB`). Back faces are diced too: Unreal's patch
312
+ * back-face cull is compiled out (`NaniteSplit.usf:196-202`). Without an occlusion buffer the price
313
+ * is an upper bound.
314
+ */
315
+ export function priceDisplacedSurface(
316
+ root: Object3D,
317
+ camera: PerspectiveCamera,
318
+ viewportHeight: number,
319
+ options: IDisplacementPriceOptions = {},
320
+ ): IDisplacementPrice {
321
+ const diceRate = options.diceRate ?? DICE_RATE_PIXELS;
322
+ const magnitude = options.magnitude ?? 0.04;
323
+ const center = options.center ?? 0.5;
324
+ const fadeOutPixels = options.fadeOutPixels ?? 0;
325
+ const occlusion = options.occlusion;
326
+ if (!(diceRate > 0) || !(viewportHeight > 0))
327
+ throw new Error("TN_DISPLACED_SURFACE: dice rate and viewport height must be positive.");
328
+ const projection = camera.projectionMatrix.elements;
329
+ const viewToPixels = 0.5 * (projection[5] as number) * viewportHeight;
330
+ const { near, far } = camera;
331
+ const price: IDisplacementPrice = {
332
+ addedMicroTriangles: 0,
333
+ dicedTriangles: 0,
334
+ fadeDistance: displacementFadeDistance(magnitude, center, 1, viewToPixels, fadeOutPixels),
335
+ microTriangles: 0,
336
+ patches: 0,
337
+ triangles: 0,
338
+ visibleTriangles: 0,
339
+ };
340
+ /** Which frustum planes view-space point `k` of `points` lies outside, one bit each. */
341
+ const outcode = (points: Float64Array, k: number): number => {
342
+ const vx = points[k * 3] as number;
343
+ const vy = points[k * 3 + 1] as number;
344
+ const vz = points[k * 3 + 2] as number;
345
+ const cx = (projection[0] as number) * vx + (projection[8] as number) * vz;
346
+ const cy = (projection[5] as number) * vy + (projection[9] as number) * vz;
347
+ const depth = -vz;
348
+ return (
349
+ (cx < -depth ? 1 : 0) |
350
+ (cx > depth ? 2 : 0) |
351
+ (cy < -depth ? 4 : 0) |
352
+ (cy > depth ? 8 : 0) |
353
+ (depth < near ? 16 : 0) |
354
+ (depth > far ? 32 : 0)
355
+ );
356
+ };
357
+ /** True when all three points lie outside one frustum plane. */
358
+ const outside = (points: Float64Array): boolean =>
359
+ (outcode(points, 0) & outcode(points, 1) & outcode(points, 2)) !== 0;
360
+ const texel = [0, 0, 0, 0, 0, 0];
361
+ /** False when the occlusion buffer hides the patch, its nearest point pulled in by the displacement. */
362
+ const seen = (points: Float64Array, reach: number): boolean => {
363
+ if (occlusion === undefined) return true;
364
+ for (let k = 0; k < 3; k += 1)
365
+ if (!toTexel(points, k, projection, near, occlusion, texel)) return true;
366
+ const nearest =
367
+ -Math.max(points[2] as number, points[5] as number, points[8] as number) - reach;
368
+ return unoccluded(occlusion, texel, nearest);
369
+ };
370
+ const factorOf = (points: Float64Array, i: number, j: number, fade: number): number =>
371
+ edgeFactor(
372
+ Math.hypot(
373
+ (points[i * 3] as number) - (points[j * 3] as number),
374
+ (points[i * 3 + 1] as number) - (points[j * 3 + 1] as number),
375
+ (points[i * 3 + 2] as number) - (points[j * 3 + 2] as number),
376
+ ),
377
+ Math.min(-(points[i * 3 + 2] as number), -(points[j * 3 + 2] as number)),
378
+ viewToPixels,
379
+ diceRate,
380
+ fade,
381
+ near,
382
+ );
383
+
384
+ /**
385
+ * Dices one patch, given as nine view-space numbers, into `price`; false when it needs no dice.
386
+ *
387
+ * Past a factor of 14 it splits, as `NaniteSplit.usf:239-258` does, by TF / 14 capped at 8, and
388
+ * every child culls and prices itself from its own points (`NaniteSplit.usf:117-235`).
389
+ * ponytail: children are a uniform grid at the largest split factor where Unreal's split pattern
390
+ * follows each edge; the leaf count shifts, the micro-triangle density does not.
391
+ */
392
+ const dice = (
393
+ points: Float64Array,
394
+ fade: number,
395
+ reach: number,
396
+ level: number,
397
+ root: boolean,
398
+ ): boolean => {
399
+ if (!root && outside(points)) return true;
400
+ const a = factorOf(points, 0, 1, fade);
401
+ const b = factorOf(points, 1, 2, fade);
402
+ const c = factorOf(points, 2, 0, fade);
403
+ const largest = Math.max(a, b, c);
404
+ if (root && largest <= 1) return false;
405
+ // An occluded root is not diced at all; an occluded child is a culled part of a diced one.
406
+ if (!seen(points, reach)) return !root;
407
+ if (largest <= TABLE_SIZE || level >= MAX_SPLIT_LEVELS) {
408
+ price.patches += 1;
409
+ price.microTriangles += patternTriangles(a, b, c);
410
+ return true;
411
+ }
412
+ const n = clampFactor(Math.min(largest / TABLE_SIZE, SPLIT_CAP));
413
+ splitGrid(points, n, (child) => dice(child, fade, reach, level + 1, false));
414
+ return true;
415
+ };
416
+
417
+ forEachSubmittedTriangle(root, camera, (points, modelView) => {
418
+ price.triangles += 1;
419
+ if (outside(points)) return;
420
+ price.visibleTriangles += 1;
421
+ const scale = modelView.getMaxScaleOnAxis();
422
+ const fade = displacementFadeDistance(magnitude, center, scale, viewToPixels, fadeOutPixels);
423
+ const reach = Math.max(center, 1 - center) * magnitude * scale;
424
+ if (dice(points, fade, reach, 0, true)) price.dicedTriangles += 1;
425
+ });
426
+ price.addedMicroTriangles = price.microTriangles - price.dicedTriangles;
427
+ return price;
428
+ }
@@ -0,0 +1,37 @@
1
+ import type { Matrix4, Object3D } from "three";
2
+
3
+ /**
4
+ * The method the owned engine puts on every `Object3D` to copy its world matrix into a caller's
5
+ * `Matrix4`. Plain three.js has no such method and reads `matrixWorld` instead.
6
+ *
7
+ * The engine defines this name in `runtime-native/src/engine/abi/bindings_scene.cpp` and probes it in
8
+ * `adapters/v8/math/entry.js`. `__tests__/engine-hooks.spec.ts` holds those two copies to this one,
9
+ * so a rename on either side fails a spec instead of silently taking every caller down the slow path.
10
+ */
11
+ export const COPY_MATRIX_WORLD_HOOK = "__tnCopyMatrixWorld";
12
+
13
+ type CopyMatrixWorld = (target: Matrix4) => void;
14
+
15
+ /** An `Object3D` that may carry the engine's hook; the property is absent on plain three.js. */
16
+ type HookCarrier = Object3D & { readonly [COPY_MATRIX_WORLD_HOOK]?: unknown };
17
+
18
+ function hookOf(object: Object3D): CopyMatrixWorld | undefined {
19
+ const hook = (object as HookCarrier)[COPY_MATRIX_WORLD_HOOK];
20
+ return typeof hook === "function" ? (hook as CopyMatrixWorld) : undefined;
21
+ }
22
+
23
+ /** Whether `object` belongs to the owned engine, which copies world matrices out instead of aliasing them. */
24
+ export function hasCopyMatrixWorldHook(object: Object3D): boolean {
25
+ return hookOf(object) !== undefined;
26
+ }
27
+
28
+ /**
29
+ * Copy `object`'s current world matrix into `target` through the engine's hook.
30
+ * @returns false when the object has no hook, so the caller reads `object.matrixWorld` itself
31
+ */
32
+ export function copyMatrixWorld(object: Object3D, target: Matrix4): boolean {
33
+ const hook = hookOf(object);
34
+ if (hook === undefined) return false;
35
+ hook.call(object, target);
36
+ return true;
37
+ }
@@ -21,6 +21,7 @@
21
21
  * instead of skipping.
22
22
  */
23
23
 
24
+ import { CONSOLE_MARKER } from "./generated/console-markers.js";
24
25
  import type { IFrameCounters } from "./profiling/FrameCounters.js";
25
26
  import { type IFrameStageSample, RENDER_STAGES, STAGE_PARTS } from "./profiling/FrameStages.js";
26
27
  import {
@@ -62,9 +63,11 @@ function requireTarget(target: ITargetFps): ITargetFps {
62
63
  }
63
64
 
64
65
  /** Marker printed once per report window. */
65
- export const FRAME_BUDGET_MARKER = "TN_FRAME_BUDGET";
66
+ export const FRAME_BUDGET_MARKER = CONSOLE_MARKER.frameBudget;
67
+ /** Marker printed once, at the end of the first frame: the game drew, and with which threads. */
68
+ export const FIRST_FRAME_MARKER = CONSOLE_MARKER.firstFrame;
66
69
  /** Marker printed the moment a gap between presented frames exceeds `hitchMs`. */
67
- export const FRAME_HITCH_MARKER = "TN_FRAME_HITCH";
70
+ export const FRAME_HITCH_MARKER = CONSOLE_MARKER.frameHitch;
68
71
 
69
72
  /**
70
73
  * The named parts of one presented frame. They partition the frame: `hostGap` is the time before
@@ -768,6 +771,8 @@ export class FrameBudget {
768
771
  /** The last drawn frame's timestamp; a declined frame leaves it, so the next drawn interval spans it. */
769
772
  #lastDrawnTimestamp: number | undefined;
770
773
  #lastFrameEnd: number | undefined;
774
+ #covered = false;
775
+ #windowCovered = false;
771
776
  #framesInWindow = 0;
772
777
  #hitchesInWindow = 0;
773
778
  /** The target frame this window counts against, and its two counts; see `overTarget`. */
@@ -779,6 +784,7 @@ export class FrameBudget {
779
784
  #lastPresentCount: number | undefined;
780
785
  #presentsInWindow = 0;
781
786
  #firstFrameStart: number | undefined;
787
+ #firstFrameReported = false;
782
788
  #firstTaskFrameStart: number | undefined;
783
789
 
784
790
  constructor(options: IFrameBudgetOptions = {}) {
@@ -880,10 +886,22 @@ export class FrameBudget {
880
886
  this.#taskObserver = undefined;
881
887
  }
882
888
 
889
+ /** Marks the following frames as behind the presentation cover: no hot-call line for them. */
890
+ markCovered(): void {
891
+ this.#covered = true;
892
+ this.#windowCovered = true;
893
+ }
894
+
895
+ /** Marks the cover lifted: the next window that begins reports hot calls again. */
896
+ markRevealed(): void {
897
+ this.#covered = false;
898
+ }
899
+
883
900
  beginFrame(timestampMs: number, nowMs: number): void {
884
901
  if (this.#open)
885
902
  throw new Error("FrameBudget.beginFrame called before the previous frame ended.");
886
903
  this.#open = true;
904
+ if (this.#framesInWindow === 0) this.#windowCovered = this.#covered;
887
905
  this.#windowStartTick ??= this.#simulation?.tick();
888
906
  this.#frameStart = nowMs;
889
907
  if (this.#firstFrameStart === undefined) this.#firstFrameStart = nowMs;
@@ -997,6 +1015,7 @@ export class FrameBudget {
997
1015
  `Frame budget gpu frame must be a non-negative integer, received ${String(frame)}.`,
998
1016
  );
999
1017
  }
1018
+ // A repeated frame id is the previous resolve still in flight, not a new measurement.
1000
1019
  if (frame === this.#lastGpuFrame) {
1001
1020
  this.#gpuStaleThisFrame = true;
1002
1021
  return;
@@ -1131,6 +1150,19 @@ export class FrameBudget {
1131
1150
  const simulationEnd = this.#simulationEnd ?? this.#frameStart;
1132
1151
  const frameMs = Math.max(0, nowMs - this.#frameStart);
1133
1152
  this.#lastFrameEnd = nowMs;
1153
+ // The first drawn frame after the startup cover lifts: the world the player sees. A software
1154
+ // adapter needs minutes to fill a window, and the thread verdict is known now. A boot line like
1155
+ // TN_QUALITY_TIER, so it goes to the console and the window sink stays per window.
1156
+ if (!this.#firstFrameReported && !this.#covered && !this.#renderSkippedThisFrame) {
1157
+ this.#firstFrameReported = true;
1158
+ const threads = (globalThis as { __tnWebThreads?: unknown }).__tnWebThreads;
1159
+ console.info(
1160
+ `${FIRST_FRAME_MARKER}:${JSON.stringify({
1161
+ frameMs: round(frameMs),
1162
+ ...(typeof threads === "string" ? { threads } : {}),
1163
+ })}`,
1164
+ );
1165
+ }
1134
1166
 
1135
1167
  this.#countPresents();
1136
1168
 
@@ -1593,7 +1625,7 @@ export class FrameBudget {
1593
1625
  this.#report(`${FRAME_BUDGET_MARKER}:${JSON.stringify(completed)}`);
1594
1626
  if (this.#debug) {
1595
1627
  this.#report(formatDebugReport(completed));
1596
- const hotCalls = debugHotCalls(completed);
1628
+ const hotCalls = this.#windowCovered ? undefined : debugHotCalls(completed);
1597
1629
  if (hotCalls !== undefined) this.#report(hotCalls);
1598
1630
  }
1599
1631
  this.#windowIndex += 1;