@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,269 @@
1
+ import type { IInputGamepad } from "./input.js";
2
+
3
+ /**
4
+ * The web half of the one interface a game reads a controller through: the W3C "standard"
5
+ * mapping. A pad the browser already maps needs nothing; a pad it reports unmapped
6
+ * (`mapping: ""`, which is the browser saying "I do not know this device") is turned into the
7
+ * standard layout by one table row per measured device, never by a class per model.
8
+ *
9
+ * The rows are SDL_GameControllerDB entries, copied verbatim and stamped with the line they came
10
+ * from (`third_party/sdl3/SDL3-3.2.30/src/joystick/SDL_gamepad_db.h`). The database carries several
11
+ * GUID forms per device — a USB hidraw entry, a Bluetooth one, and one per host driver — and which
12
+ * of them a browser reports is the device read still open on this PRD. What the rows do here is name
13
+ * the slots, and for every form of these devices the sticks and the face/shoulder/start/back/stick
14
+ * buttons are the same; the triggers are axes in the forms below and buttons in the
15
+ * `SDL_JOYSTICK_DINPUT` (Windows) form at `:72`, which no browser reports.
16
+ *
17
+ * The d-pad is deliberately not mapped: every row expresses it as a hat (`h0.1`), which arrives in a
18
+ * browser as two extra axes in a device-specific order. No kit here binds the d-pad, so a row ships
19
+ * the sticks, the triggers and the face/shoulder/start/back/stick-click buttons only.
20
+ */
21
+
22
+ /** Which normalizer read a pad — the word a `TN_GAMEPAD` line reports. */
23
+ export type GamepadNormalizer = "standard" | "table" | "unmapped";
24
+
25
+ /** The W3C standard's 16 buttons; 6 and 7 are the analog triggers, read from axes. */
26
+ export const STANDARD_BUTTON_COUNT = 16;
27
+
28
+ /** The standard's 4 stick axes: left x/y, then right x/y. */
29
+ export const STANDARD_AXIS_COUNT = 4;
30
+
31
+ /**
32
+ * A mutable standard pad: the buffer a normalizer fills and `InputMap` publishes. One is allocated
33
+ * per pad the reader has to normalize, then mutated every tick — normalizing must not allocate in
34
+ * the frame loop.
35
+ */
36
+ export interface IStandardPad {
37
+ readonly axes: number[];
38
+ readonly buttons: { pressed: boolean }[];
39
+ }
40
+
41
+ export function createStandardPad(): IStandardPad {
42
+ const buttons: { pressed: boolean }[] = [];
43
+ for (let index = 0; index < STANDARD_BUTTON_COUNT; index += 1) buttons.push({ pressed: false });
44
+ return { axes: [0, 0, 0, 0], buttons };
45
+ }
46
+
47
+ /** One device the browser cannot map, keyed by the vendor:product its `id` carries. */
48
+ interface IPadRow {
49
+ /** The SDL_GameControllerDB mapping string, verbatim. */
50
+ readonly map: string;
51
+ readonly product: number;
52
+ readonly vendor: number;
53
+ }
54
+
55
+ const PAD_ROWS: readonly IPadRow[] = [
56
+ {
57
+ // 8BitDo Ultimate C 2.4G Wireless Controller, **measured on the owner's device** (2026-11-11):
58
+ // the kernel reports `2dc8:3016` and Chromium reports `mapping: ""` for it, so this row is the
59
+ // only thing that makes the pad work on the web. SDL 3.2.30 has no row for `3016` under any name
60
+ // (its 8BitDo entries are `301b`, `3013`, `3011`, `3012`), so nothing could be copied.
61
+ // Linux sorts an unmapped pad's buttons and axes by evdev code, and the measured device exposes
62
+ // KEY 304..318 and ABS 0,1,2,5,9,10,16,17 — so the raw indices are that order: b0..b14 are
63
+ // A, B, C, X, Y, Z, LB, RB, LT, RT, Select, Start, Home, L3, R3, and a0..a7 are ABS_X, ABS_Y,
64
+ // ABS_Z, ABS_RZ, ABS_GAS, ABS_BRAKE, HAT0X, HAT0Y. Hence X and Y sit on b3/b4 (not b2/b3), the
65
+ // right stick is a2/a3, and the triggers are a5 (left) and a4 (right), travelling -1..1.
66
+ // What was measured in Chromium, by pressing the pad: A, B, X, Y, LB, RB, Select and Start at raw
67
+ // 0, 1, 3, 4, 6, 7, 10, 11, the left stick on a0/a1 and the right stick on a2/a3. The trigger sides
68
+ // are derived from the kernel instead, which is the closest measurement available without a
69
+ // per-frame logger in the page: pressing LT swept `ABS_BRAKE` (10) 0..255 and pressing RT swept
70
+ // `ABS_GAS` (9) 0..255, and axes are reported in ascending ABS order — the rule the two sticks
71
+ // confirm, ABS_X/ABS_Y on a0/a1 and ABS_Z/ABS_RZ on a2/a3 — which puts the left trigger on a5 and
72
+ // the right on a4, as SDL's 8BitDo rows also have them.
73
+ // The stick clicks reach Chromium as raw buttons 13 and 14, which is the standard's 10 and 11 —
74
+ // observed when both sticks were clicked together, so the indices are measured while which side is
75
+ // which follows the kernel's order (`BTN_THUMBL` 317 before `BTN_THUMBR` 318), the same derivation
76
+ // the triggers use. One caveat: the extra C/Z buttons at b2/b5 have no standard slot, so they are
77
+ // left unbound.
78
+ product: 0x3016,
79
+ vendor: 0x2dc8,
80
+ map: "a:b0,b:b1,x:b3,y:b4,back:b10,start:b11,leftshoulder:b6,rightshoulder:b7,leftstick:b13,rightstick:b14,lefttrigger:a5,righttrigger:a4,leftx:a0,lefty:a1,rightx:a2,righty:a3,",
81
+ },
82
+ {
83
+ // 8BitDo Ultimate 2C Wireless, SDL_GameControllerDB:367 (`0300…1b30000001000000`), whose
84
+ // triggers are axes 5 and 4 — the form a browser reports, where the `SDL_JOYSTICK_DINPUT`
85
+ // entry (:72) has them as buttons 8 and 9 and nothing on the web would ever see those.
86
+ product: 0x301b,
87
+ vendor: 0x2dc8,
88
+ map: "a:b0,b:b1,back:b10,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,guide:b12,leftshoulder:b6,leftstick:b13,lefttrigger:a5,leftx:a0,lefty:a1,paddle1:b2,paddle2:b5,rightshoulder:b7,rightstick:b14,righttrigger:a4,rightx:a2,righty:a3,start:b11,x:b3,y:b4,",
89
+ },
90
+ {
91
+ // 8BitDo Ultimate Wireless Controller, SDL_GameControllerDB:369 (`0300…1330000000020000`).
92
+ product: 0x3013,
93
+ vendor: 0x2dc8,
94
+ map: "a:b0,b:b1,back:b10,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,guide:b12,leftshoulder:b6,leftstick:b13,lefttrigger:a5,leftx:a0,lefty:a1,misc1:b26,paddle1:b23,paddle2:b19,rightshoulder:b7,rightstick:b14,righttrigger:a4,rightx:a2,righty:a3,start:b11,x:b3,y:b4,",
95
+ },
96
+ {
97
+ // Steam Deck Controller, SDL_GameControllerDB:756 (`0300…0512000000016800`). Steam Input's virtual
98
+ // pad is a different SDL entry (:757) with the face buttons on b3..b6, and its d-pad as buttons;
99
+ // that one is not covered here.
100
+ product: 0x1205,
101
+ vendor: 0x28de,
102
+ map: "a:b0,b:b1,back:b4,dpdown:h0.4,dpleft:h0.8,dpright:h0.2,dpup:h0.1,guide:b5,leftshoulder:b9,leftstick:b7,lefttrigger:a4,leftx:a0,lefty:a1,misc1:b11,paddle1:b12,paddle2:b13,paddle3:b14,paddle4:b15,rightshoulder:b10,rightstick:b8,righttrigger:a5,rightx:a2,righty:a3,start:b6,x:b2,y:b3,",
103
+ },
104
+ ];
105
+
106
+ /** SDL's names for the standard slots, so a copied row needs no renumbering to be read. */
107
+ const BUTTON_NAMES: Readonly<Record<string, number>> = {
108
+ a: 0,
109
+ b: 1,
110
+ x: 2,
111
+ y: 3,
112
+ leftshoulder: 4,
113
+ rightshoulder: 5,
114
+ back: 8,
115
+ start: 9,
116
+ leftstick: 10,
117
+ rightstick: 11,
118
+ };
119
+
120
+ const AXIS_NAMES: Readonly<Record<string, number>> = {
121
+ leftx: 0,
122
+ lefty: 1,
123
+ rightx: 2,
124
+ righty: 3,
125
+ };
126
+
127
+ const TRIGGER_SLOTS: Readonly<Record<string, number>> = {
128
+ lefttrigger: 6,
129
+ righttrigger: 7,
130
+ };
131
+
132
+ /** Where one row sends a standard slot: an index into the pad's buttons or its axes. */
133
+ type PadSlot =
134
+ | { readonly index: number; readonly kind: "button" }
135
+ | { readonly index: number; readonly invert: boolean; readonly kind: "axis" };
136
+
137
+ interface IParsedRow {
138
+ /** Standard axis index -> where the pad keeps it. */
139
+ readonly axes: readonly (PadSlot | undefined)[];
140
+ /** Standard button index -> where the pad keeps it. */
141
+ readonly buttons: readonly (PadSlot | undefined)[];
142
+ }
143
+
144
+ function parseSlot(value: string): PadSlot | undefined {
145
+ const invert = value.startsWith("-");
146
+ const token = invert || value.startsWith("+") ? value.slice(1) : value;
147
+ const index = Number.parseInt(token.slice(1), 10);
148
+ if (!Number.isInteger(index) || index < 0) return undefined;
149
+ if (token.startsWith("b")) return { index, kind: "button" };
150
+ if (token.startsWith("a")) return { index, invert, kind: "axis" };
151
+ return undefined;
152
+ }
153
+
154
+ function parseRow(row: IPadRow): IParsedRow {
155
+ const axes: (PadSlot | undefined)[] = [];
156
+ const buttons: (PadSlot | undefined)[] = [];
157
+ for (const token of row.map.split(",")) {
158
+ const colon = token.indexOf(":");
159
+ if (colon < 1) continue;
160
+ const slot = parseSlot(token.slice(colon + 1));
161
+ if (slot === undefined) continue; // a hat, a paddle or the guide button: no standard slot
162
+ const name = token.slice(0, colon);
163
+ const axis = AXIS_NAMES[name];
164
+ if (axis !== undefined) axes[axis] = slot;
165
+ const button = BUTTON_NAMES[name] ?? TRIGGER_SLOTS[name];
166
+ if (button !== undefined) buttons[button] = slot;
167
+ }
168
+ return { axes, buttons };
169
+ }
170
+
171
+ /** Parsed once per row: parsing the same string every tick is work the frame loop must not do. */
172
+ const PARSED_ROWS = new Map<IPadRow, IParsedRow>(PAD_ROWS.map((row) => [row, parseRow(row)]));
173
+
174
+ /**
175
+ * Row per browser `id`. A pad keeps its id while it is connected, so this answer never changes for a
176
+ * connected device — and `RegExp.exec` allocates a match array, which the frame loop must not do.
177
+ */
178
+ const ROW_BY_ID = new Map<string, IPadRow | null>();
179
+
180
+ const CHROMIUM_VENDOR_PRODUCT = /vendor:\s*([0-9a-f]{1,4})\s+product:\s*([0-9a-f]{1,4})/i;
181
+ const FIREFOX_VENDOR_PRODUCT = /^([0-9a-f]{4})-([0-9a-f]{4})-/i;
182
+
183
+ /**
184
+ * The vendor:product a browser `id` carries. Chromium writes `… Vendor: 045e Product: 028e` inside
185
+ * the parentheses, Firefox writes `045e-028e-<name>`. Anything else answers `undefined`, which is
186
+ * what makes such a pad unmapped rather than guessed at.
187
+ */
188
+ export function padVendorProduct(
189
+ id: string | undefined,
190
+ ): { readonly product: number; readonly vendor: number } | undefined {
191
+ if (id === undefined) return undefined;
192
+ const match = CHROMIUM_VENDOR_PRODUCT.exec(id) ?? FIREFOX_VENDOR_PRODUCT.exec(id);
193
+ if (match === null) return undefined;
194
+ const vendor = Number.parseInt(match[1] as string, 16);
195
+ const product = Number.parseInt(match[2] as string, 16);
196
+ if (!Number.isInteger(vendor) || !Number.isInteger(product)) return undefined;
197
+ return { product, vendor };
198
+ }
199
+
200
+ function readSlot(pad: IInputGamepad, slot: PadSlot): number {
201
+ if (slot.kind === "button") return pad.buttons[slot.index]?.pressed === true ? 1 : 0;
202
+ const value = pad.axes[slot.index];
203
+ if (value === undefined || !Number.isFinite(value)) return 0;
204
+ return slot.invert ? -value : value;
205
+ }
206
+
207
+ /**
208
+ * Fills `out` with `pad` in the W3C standard layout and says which normalizer read it.
209
+ *
210
+ * A pad that reports `mapping: "standard"` — or no `mapping` field at all, which is what the owned
211
+ * native host and a test fixture report — passes through. A pad reporting the empty string is
212
+ * looked up by vendor:product; `unmapped` means the caller must ignore it, because reading raw
213
+ * indices fires whatever action the device happened to number 0.
214
+ */
215
+ export function toStandardPad(pad: IInputGamepad, out: IStandardPad): GamepadNormalizer {
216
+ const mapping = pad.mapping;
217
+ const parsed =
218
+ mapping === undefined || mapping === "standard"
219
+ ? undefined
220
+ : PARSED_ROWS.get(rowFor(pad.id) as IPadRow);
221
+ if (mapping === undefined || mapping === "standard") {
222
+ copyPad(pad, out);
223
+ return "standard";
224
+ }
225
+ if (parsed === undefined) {
226
+ clearPad(out);
227
+ return "unmapped";
228
+ }
229
+ for (let index = 0; index < STANDARD_AXIS_COUNT; index += 1) {
230
+ const slot = parsed.axes[index];
231
+ out.axes[index] = slot === undefined ? 0 : readSlot(pad, slot);
232
+ }
233
+ for (let index = 0; index < STANDARD_BUTTON_COUNT; index += 1) {
234
+ const slot = parsed.buttons[index];
235
+ // A trigger is an axis on these devices; the standard's button 6/7 is down past halfway.
236
+ const value = slot === undefined ? 0 : readSlot(pad, slot);
237
+ (out.buttons[index] as { pressed: boolean }).pressed = value > 0.5;
238
+ }
239
+ return "table";
240
+ }
241
+
242
+ function rowFor(id: string | undefined): IPadRow | undefined {
243
+ if (id === undefined) return undefined;
244
+ const cached = ROW_BY_ID.get(id);
245
+ if (cached !== undefined) return cached ?? undefined;
246
+ const key = padVendorProduct(id);
247
+ let found: IPadRow | undefined;
248
+ if (key !== undefined)
249
+ for (const row of PAD_ROWS)
250
+ if (row.vendor === key.vendor && row.product === key.product) found = row;
251
+ ROW_BY_ID.set(id, found ?? null);
252
+ return found;
253
+ }
254
+
255
+ function clearPad(out: IStandardPad): void {
256
+ for (let index = 0; index < STANDARD_AXIS_COUNT; index += 1) out.axes[index] = 0;
257
+ for (let index = 0; index < STANDARD_BUTTON_COUNT; index += 1)
258
+ (out.buttons[index] as { pressed: boolean }).pressed = false;
259
+ }
260
+
261
+ function copyPad(pad: IInputGamepad, out: IStandardPad): void {
262
+ const axes = pad.axes;
263
+ for (let index = 0; index < STANDARD_AXIS_COUNT; index += 1) {
264
+ const value = axes[index];
265
+ out.axes[index] = value !== undefined && Number.isFinite(value) ? value : 0;
266
+ }
267
+ for (let index = 0; index < STANDARD_BUTTON_COUNT; index += 1)
268
+ (out.buttons[index] as { pressed: boolean }).pressed = pad.buttons[index]?.pressed === true;
269
+ }
@@ -0,0 +1,14 @@
1
+ // Generated by @threenative/three-native from api/console-markers.json. Do not edit.
2
+ //
3
+ // The `TN_*` console markers the perf tooling parses. Add the colon where a line is matched.
4
+ export const CONSOLE_MARKER = {
5
+ bridgeCensus: "TN_BRIDGE_CENSUS",
6
+ firstFrame: "TN_FIRST_FRAME",
7
+ frameBudget: "TN_FRAME_BUDGET",
8
+ frameHitch: "TN_FRAME_HITCH",
9
+ hostGap: "TN_HOST_GAP",
10
+ playerFrame: "TN_PLAYER_FRAME",
11
+ presentsTick: "TN_PRESENTS_TICK",
12
+ projection: "TN_PROJECTION",
13
+ slowPhase: "TN_SLOW_PHASE",
14
+ } as const;
@@ -27,7 +27,13 @@
27
27
  import { Frustum, Matrix4, Sphere, Vector3 } from "three";
28
28
  import type { Camera, Object3D } from "three";
29
29
  import { markEngineRenderHook } from "./engine-render-hook.js";
30
- import { baseGeometryOf, conservativeViewDepth, lodPixelScale, worldSphere } from "./model-lod.js";
30
+ import {
31
+ LOD_NEAR_PLANE,
32
+ baseGeometryOf,
33
+ lodPixelScale,
34
+ selectLodFor,
35
+ worldSphere,
36
+ } from "./model-lod.js";
31
37
  import type { FramePassKind, IRenderPassSample } from "./render-pass-budget.js";
32
38
 
33
39
  /** Rows returned when a request does not name a limit. */
@@ -420,14 +426,14 @@ function projectedSize(
420
426
  ): { readonly pixels: number; readonly distance: number } | undefined {
421
427
  if (!(viewportHeight > 0)) return undefined;
422
428
  const like = camera as ICameraLike;
423
- const near = like.near ?? 0.1;
429
+ const near = like.near ?? LOD_NEAR_PLANE;
424
430
  const distance = centreScratch
425
431
  .copy(sphere.center)
426
432
  .distanceTo(camera.getWorldPosition(new Vector3()));
427
433
  let depth: number;
428
434
  let degenerate: boolean;
429
435
  try {
430
- const view = conservativeViewDepth(camera, sphere.center, sphere.radius, near);
436
+ const view = selectLodFor(camera, sphere, near);
431
437
  depth = view.depth;
432
438
  degenerate = view.degenerate;
433
439
  } catch {
@@ -462,6 +468,7 @@ export function rendererBackendIdentity(raw: unknown): string | undefined {
462
468
  export class GeometryCapture {
463
469
  #pending: IPendingRequest | undefined;
464
470
  #armed: IArmedFrame | undefined;
471
+ #deferredPasses: readonly IRenderPassSample[] | undefined;
465
472
 
466
473
  /**
467
474
  * Arms one capture and answers its report. A malformed request throws rather than quietly
@@ -560,7 +567,17 @@ export class GeometryCapture {
560
567
  * Ends the frame: removes every hook, reconciles the rows against the measured pass totals and
561
568
  * answers the waiting request.
562
569
  */
563
- finishFrame(passes: readonly IRenderPassSample[]): void {
570
+ finishFrame(
571
+ passes: readonly IRenderPassSample[],
572
+ options?: { readonly drawsAfterFrame?: boolean },
573
+ ): void {
574
+ // A host whose render() only records the frame (the native V8 player) draws it after the frame
575
+ // callback, and its engine runs onBeforeRender then: the hooks stay until settleDeferred().
576
+ if (options?.drawsAfterFrame === true && this.#pending !== undefined) {
577
+ this.#deferredPasses = passes;
578
+ return;
579
+ }
580
+ this.#deferredPasses = undefined;
564
581
  const armed = this.#armed;
565
582
  const pending = this.#pending;
566
583
  this.#restore();
@@ -570,8 +587,15 @@ export class GeometryCapture {
570
587
  pending.settle(buildReport(armed, passes, pending));
571
588
  }
572
589
 
590
+ /** Answers a capture whose frame a host drew after the frame callback. A no-op otherwise. */
591
+ settleDeferred(): void {
592
+ const passes = this.#deferredPasses;
593
+ if (passes !== undefined) this.finishFrame(passes);
594
+ }
595
+
573
596
  /** Drops a pending capture and every hook. A scene exit is not a reason to report a stale frame. */
574
597
  cancel(reason: string): void {
598
+ this.#deferredPasses = undefined;
575
599
  const pending = this.#pending;
576
600
  this.#restore();
577
601
  this.#pending = undefined;
@@ -0,0 +1,98 @@
1
+ /**
2
+ * One owner for a GPU timing series: the sample, the frame it belongs to, how stale it is, and the
3
+ * smoothed value a decision may act on.
4
+ *
5
+ * The renderer, the resolution scaler and the frame budget each worked this out for themselves, with
6
+ * three different freshness rules — consecutive stale frames in the renderer, an absolute age in the
7
+ * scaler, "did the frame id repeat" in the budget — so the same reading could be current for one
8
+ * subsystem and stale for another with nothing failing. The numbers they disagree about now live
9
+ * here once, and each caller says which rule it wants.
10
+ *
11
+ * Nothing here decides how anything looks: it takes the milliseconds the engine resolved and answers
12
+ * whether they describe the frame under consideration.
13
+ */
14
+
15
+ /** Samples older than this many consecutive stale frames are dropped by the adaptive loop. */
16
+ export const GPU_STALE_FRAME_LIMIT = 8;
17
+
18
+ /**
19
+ * A resolved sample stays usable for a window decision this many frames after its own frame. The
20
+ * scaler reads this; its own age check stays inline because it rejects an unknown age where a series
21
+ * would treat one as fresh.
22
+ */
23
+ export const GPU_READING_MAX_AGE_FRAMES = 16;
24
+
25
+ /** Window GPU samples that make a window's own median fresh evidence when the latest is too old. */
26
+ export const GPU_WINDOW_MIN_SAMPLES = 4;
27
+
28
+ /** One resolved GPU time and the drawn frame it was submitted under. */
29
+ export interface IGpuReading {
30
+ /** Milliseconds, finite and non-negative as the engine reports them. */
31
+ readonly ms: number;
32
+ /** The drawn frame that submitted the sample, when the caller knows it. */
33
+ readonly frame?: number;
34
+ }
35
+
36
+ /** How a series smooths and when it gives up; the defaults are the engine's. */
37
+ export interface IGpuReadingsOptions {
38
+ /** Weight of a new sample: 0.5 is half/half, 1 keeps only the newest. */
39
+ readonly smoothing?: number;
40
+ /** Consecutive stale notes that drop the smoothed value. */
41
+ readonly staleLimit?: number;
42
+ }
43
+
44
+ /**
45
+ * A GPU series fed one resolved sample at a time.
46
+ *
47
+ * A repeated frame id is the previous resolve still in flight, not a new measurement, so it counts
48
+ * as stale — that rule is the one three callers each wrote for themselves.
49
+ */
50
+ export class GpuReadings {
51
+ readonly #smoothing: number;
52
+ readonly #staleLimit: number;
53
+ #ema: number | undefined;
54
+ #lastFrame: number | undefined;
55
+ #last: IGpuReading | undefined;
56
+ #stale = 0;
57
+
58
+ constructor(options: IGpuReadingsOptions = {}) {
59
+ this.#smoothing = options.smoothing ?? 0.5;
60
+ this.#staleLimit = options.staleLimit ?? GPU_STALE_FRAME_LIMIT;
61
+ }
62
+
63
+ /** The smoothed value a decision may act on, or `undefined` when the series went stale. */
64
+ get ema(): number | undefined {
65
+ return this.#ema;
66
+ }
67
+
68
+ /** The newest accepted reading, before smoothing. */
69
+ get last(): IGpuReading | undefined {
70
+ return this.#last;
71
+ }
72
+
73
+ /** Whether `frame` repeated the last accepted sample, which is a resolve still in flight. */
74
+ repeats(frame: number | undefined): boolean {
75
+ return frame !== undefined && frame === this.#lastFrame;
76
+ }
77
+
78
+ /** Records one resolved sample. `undefined`, a non-number or a negative value counts as stale. */
79
+ note(ms: number | undefined, frame?: number): void {
80
+ if (ms === undefined || !Number.isFinite(ms) || ms < 0) {
81
+ this.#markStale();
82
+ return;
83
+ }
84
+ if (this.repeats(frame)) {
85
+ this.#markStale();
86
+ return;
87
+ }
88
+ if (frame !== undefined) this.#lastFrame = frame;
89
+ this.#stale = 0;
90
+ this.#last = frame === undefined ? { ms } : { frame, ms };
91
+ this.#ema = this.#ema === undefined ? ms : this.#ema + (ms - this.#ema) * this.#smoothing;
92
+ }
93
+
94
+ #markStale(): void {
95
+ this.#stale += 1;
96
+ if (this.#stale >= this.#staleLimit) this.#ema = undefined;
97
+ }
98
+ }