castle-web-cli 0.4.230 → 0.4.232

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 (92) hide show
  1. package/dist/castle-host/host.js +81 -0
  2. package/dist/devSaveStorage.d.ts +36 -0
  3. package/dist/devSaveStorage.js +469 -0
  4. package/dist/devSessionChild.js +22 -12
  5. package/dist/devSessionServer.js +8 -2
  6. package/dist/devSessionStorage.d.ts +9 -0
  7. package/dist/devSessionStorage.js +66 -1
  8. package/dist/init.js +1 -1
  9. package/dist/serve.js +5 -1
  10. package/dist/serverBundle.js +5 -3
  11. package/kits/base/castle.json +1 -1
  12. package/kits/base/sdk/README.md +148 -1
  13. package/kits/base/sdk/castle.d.ts +4 -0
  14. package/kits/base/sdk/castle.js +2 -0
  15. package/kits/base/sdk/commands.d.ts +15 -0
  16. package/kits/base/sdk/multiplayer.js +52 -4
  17. package/kits/base/sdk/save.d.ts +197 -0
  18. package/kits/base/sdk/save.js +525 -0
  19. package/kits/base/sdk/saveCoordinator.d.ts +39 -0
  20. package/kits/base/sdk/saveCoordinator.js +252 -0
  21. package/kits/base/sdk/server/storage.d.ts +3 -2
  22. package/kits/base/sdk/server/storage.js +25 -5
  23. package/kits/base/sdk/server/wrapper.d.ts +4 -0
  24. package/kits/base/sdk/server/wrapper.js +2 -0
  25. package/kits/base/sdk/store.d.ts +3 -2
  26. package/kits/base/sdk/store.js +5 -0
  27. package/kits/hub-game/CLAUDE.md +29 -4
  28. package/kits/hub-game/code/client/avatar.js +39 -0
  29. package/kits/hub-game/code/client/chat.js +12 -0
  30. package/kits/hub-game/code/client/chrome.js +237 -13
  31. package/kits/hub-game/code/client/grab.js +166 -7
  32. package/kits/hub-game/code/client/hats.js +26 -0
  33. package/kits/hub-game/code/client/hookLayer.js +36 -3
  34. package/kits/hub-game/code/client/hudClear.js +126 -0
  35. package/kits/hub-game/code/client/state.js +35 -1
  36. package/kits/hub-game/code/client/talk.js +10 -36
  37. package/kits/hub-game/code/client/tiers.js +505 -0
  38. package/kits/hub-game/code/client/together.js +144 -4
  39. package/kits/hub-game/code/client/wear.js +96 -14
  40. package/kits/hub-game/code/server/actors.js +5 -0
  41. package/kits/hub-game/code/server/grab.js +299 -13
  42. package/kits/hub-game/code/server/hub.js +162 -7
  43. package/kits/hub-game/code/server/manifest.js +80 -8
  44. package/kits/hub-game/code/server/npcs.js +21 -33
  45. package/kits/hub-game/code/server/party.js +75 -6
  46. package/kits/hub-game/code/server/say.js +8 -2
  47. package/kits/hub-game/code/server/wear.js +116 -11
  48. package/kits/hub-game/code/systems/hub.js +386 -21
  49. package/kits/hub-game/docs/contract.md +285 -19
  50. package/kits/hub-game/package.json +1 -1
  51. package/kits/hub-game/scripts/test-chat.mjs +32 -0
  52. package/kits/hub-game/scripts/test-grab-client.mjs +511 -0
  53. package/kits/hub-game/scripts/test-grab.mjs +857 -3
  54. package/kits/hub-game/scripts/test-hats.mjs +229 -0
  55. package/kits/hub-game/scripts/test-hub-trip.mjs +721 -0
  56. package/kits/hub-game/scripts/test-hud-clear.mjs +676 -0
  57. package/kits/hub-game/scripts/test-manifest.mjs +122 -1
  58. package/kits/hub-game/scripts/test-npcs.mjs +34 -24
  59. package/kits/hub-game/scripts/test-party.mjs +108 -4
  60. package/kits/hub-game/scripts/test-say.mjs +59 -2
  61. package/kits/hub-game/scripts/test-tiers.mjs +854 -0
  62. package/kits/hub-game/scripts/test-together.mjs +33 -1
  63. package/kits/hub-game/scripts/test-try-on.mjs +940 -0
  64. package/kits/physics-2d/CLAUDE.md +2 -0
  65. package/kits/physics-2d/castle.json +2 -2
  66. package/kits/physics-2d/engine/scene.js +127 -0
  67. package/kits/physics-2d/package.json +1 -1
  68. package/kits/physics-2d/scripts/test-skip-unchanged.mjs +298 -0
  69. package/kits/physics-3d/CLAUDE.md +531 -0
  70. package/kits/physics-3d/behaviors/Player.jsx +437 -3
  71. package/kits/physics-3d/castle.json +3 -3
  72. package/kits/physics-3d/docs/pxmodel-format.md +4 -0
  73. package/kits/physics-3d/engine3d/Scene3DPlayer.jsx +33 -1
  74. package/kits/physics-3d/engine3d/actornode.js +253 -0
  75. package/kits/physics-3d/engine3d/nearshadows.js +600 -0
  76. package/kits/physics-3d/engine3d/optimize.js +49 -0
  77. package/kits/physics-3d/engine3d/orbitinput.js +277 -0
  78. package/kits/physics-3d/engine3d/unchanged.js +153 -0
  79. package/kits/physics-3d/engine3d/world3d.js +525 -11
  80. package/kits/physics-3d/package.json +1 -1
  81. package/kits/physics-3d/scripts/Player.before-orbit.mjs +310 -0
  82. package/kits/physics-3d/scripts/Scene3DPlayer.before-orbit.jsx +337 -0
  83. package/kits/physics-3d/scripts/test-camera-follow.mjs +543 -0
  84. package/kits/physics-3d/scripts/test-camera-orbit.mjs +2105 -0
  85. package/kits/physics-3d/scripts/test-drop-empty-parts.mjs +787 -0
  86. package/kits/physics-3d/scripts/test-near-shadows.mjs +1073 -0
  87. package/kits/physics-3d/scripts/test-static-actors.mjs +667 -0
  88. package/kits/physics-3d/scripts/test-static-passes.mjs +459 -0
  89. package/kits/physics-3d/scripts/test-static-physics.mjs +128 -0
  90. package/kits/physics-3d/scripts/test-steady-hover.mjs +633 -0
  91. package/kits/physics-3d/systems/physics3d.js +273 -9
  92. package/package.json +1 -1
@@ -0,0 +1,505 @@
1
+ // Device tiers: a cheaper picture of a hub place for a phone that cannot draw
2
+ // the full one. Only in a deck whose castle.json says `"hub": { "tiers": true }`
3
+ // (the hook layer reads it into `state.js` `deck.tiers`); without it the hub
4
+ // system never calls in here, so nothing below runs, reads storage or touches
5
+ // the renderer.
6
+ //
7
+ // A device is 'high' (the picture as authored) or 'low'. The low picture was
8
+ // chosen on real phones (a Galaxy Tab A7 Lite and a Redmi 9A, CPU-bound at 12
9
+ // fps in the town): no sun shadow, decorative actors not drawn, other scenery
10
+ // not drawn past 30 m and NPC bodies past 20 m. The render resolution is left
11
+ // alone: a render scale of 1 on a 2x screen bought 2-9% on those phones and
12
+ // made Low visibly jagged, while shadows off alone took a TECNO from 32-35 to
13
+ // 48.5 fps.
14
+ // "Not drawn" takes the actor's three.js node out of the scene graph, which
15
+ // saves the traversal and matrix work as well as the draw. Nothing here
16
+ // touches colliders, physics, the network, labels or anything another player
17
+ // sees: it is this client's picture only.
18
+ // A deck may mark an actor in its scene file `"tier": "keep"` (beside `id`,
19
+ // not a component): it is drawn on every tier, whatever it would be called
20
+ // here -- a place's ground is often plain Transform/Shape/Model, and a place
21
+ // drawn without it stands on nothing.
22
+ //
23
+ // Where a device starts: low if it was found slow here in the last week
24
+ // (remembered in localStorage), or its GPU or memory says it is a weak phone;
25
+ // otherwise high, and the frame times decide (`makeJudge`). A player may pick
26
+ // Low or High by hand (the Graphics row in the Character card), which wins
27
+ // over all of it.
28
+
29
+ import { Box3, Sphere } from 'three';
30
+
31
+ export const TIERS = ['low', 'high'];
32
+ export const MODES = ['auto', 'low', 'high'];
33
+ // localStorage: the tier found here (`{ tier: 'low', at }`), and the mode the
34
+ // player picked.
35
+ export const TIER_KEY = 'castle.hub.tier';
36
+ export const MODE_KEY = 'castle.hub.graphics';
37
+ // A device found slow stays low this long, then is tried from high again.
38
+ export const REMEMBER_MS = 7 * 24 * 60 * 60 * 1000;
39
+ // The judge: a window's median frame time over this is a slow device. The
40
+ // first window after the player is placed is short, so a slow phone is helped
41
+ // within seconds; every later one is longer, so a passing stall is not taken
42
+ // for one.
43
+ export const SLOW_FRAME_MS = 40;
44
+ export const FIRST_WINDOW_MS = 5000;
45
+ export const WINDOW_MS = 10000;
46
+ // A gap this long between two frames is the page having been hidden or
47
+ // stalled: the window it falls in says nothing about drawing.
48
+ export const GAP_MS = 1000;
49
+ // Low: how far away scenery and NPC bodies are still drawn, and how often
50
+ // what is near is looked at again (not every frame).
51
+ export const SCENERY_NEAR_M = 30;
52
+ export const NPC_NEAR_M = 20;
53
+ export const CHECK_EVERY_MS = 500;
54
+
55
+ // GPUs of the phones the low picture is for, by the WebGL renderer string
56
+ // (`WEBGL_debug_renderer_info`): PowerVR Rogue GE8xxx, Mali-G52 MC1/MC2,
57
+ // Mali-G51, Mali-T7xx/T8xx, Adreno 3xx/4xx/50x.
58
+ const WEAK_GPUS = [
59
+ /PowerVR Rogue GE8\d{2,3}/i,
60
+ /Mali-G52 MC[12]\b/i,
61
+ /Mali-G51\b/i,
62
+ /Mali-T[78]\d\d\b/i,
63
+ /Adreno\D*(?:[34]\d\d|50\d)\b/i,
64
+ ];
65
+
66
+ export function weakGpu(renderer) {
67
+ return typeof renderer === 'string' && WEAK_GPUS.some((re) => re.test(renderer));
68
+ }
69
+
70
+ // The tier the device's own hints give, before a frame is drawn.
71
+ export function hintedTier({ gpu = null, deviceMemory = null } = {}) {
72
+ if (weakGpu(gpu)) {
73
+ return { tier: 'low', reason: 'gpu' };
74
+ }
75
+ if (typeof deviceMemory === 'number' && deviceMemory > 0 && deviceMemory <= 2) {
76
+ return { tier: 'low', reason: 'memory' };
77
+ }
78
+ return { tier: 'high', reason: 'auto' };
79
+ }
80
+
81
+ // Storage that may be missing, or throw on every access (a private window, a
82
+ // sandboxed frame, blocked site data): every read and write is guarded, and a
83
+ // failure reads as nothing stored.
84
+ export function readJson(storage, key) {
85
+ try {
86
+ const text = storage?.getItem(key);
87
+ return typeof text === 'string' ? JSON.parse(text) : null;
88
+ } catch {
89
+ return null;
90
+ }
91
+ }
92
+
93
+ export function writeJson(storage, key, value) {
94
+ try {
95
+ storage?.setItem(key, JSON.stringify(value));
96
+ return true;
97
+ } catch {
98
+ return false;
99
+ }
100
+ }
101
+
102
+ export function readMode(storage) {
103
+ const mode = readJson(storage, MODE_KEY);
104
+ return MODES.includes(mode) ? mode : 'auto';
105
+ }
106
+
107
+ // Where a device starts: found slow here within the week, then its hints.
108
+ export function initialTier({ storage, now, gpu, deviceMemory }) {
109
+ const seen = readJson(storage, TIER_KEY);
110
+ if (seen?.tier === 'low' && typeof seen.at === 'number' && now - seen.at >= 0 && now - seen.at < REMEMBER_MS) {
111
+ return { tier: 'low', reason: 'remembered' };
112
+ }
113
+ return hintedTier({ gpu, deviceMemory });
114
+ }
115
+
116
+ export function median(values) {
117
+ if (!values.length) {
118
+ return 0;
119
+ }
120
+ const sorted = [...values].sort((a, b) => a - b);
121
+ const mid = sorted.length >> 1;
122
+ return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
123
+ }
124
+
125
+ // The frame-time judge. `feed(dtMs, nowMs, counts)` takes each frame; `counts`
126
+ // is false while the frame says nothing about how this device draws the place
127
+ // (the player not placed yet, a trip or scene swap under the cover, the page
128
+ // hidden), and the window then starts over. A window's median, not its mean,
129
+ // is judged, so the odd long frame (a mesh built, a collection) does not
130
+ // decide. Returns 'low' once, when a window is slow; the judge then stops: a
131
+ // visit never moves back up.
132
+ export function makeJudge() {
133
+ const judge = { done: false, first: true, start: null, frames: [] };
134
+ judge.reset = () => {
135
+ judge.start = null;
136
+ judge.frames = [];
137
+ };
138
+ judge.feed = (dt, now, counts) => {
139
+ if (judge.done) {
140
+ return null;
141
+ }
142
+ if (!counts || !(dt >= 0) || dt > GAP_MS) {
143
+ judge.reset();
144
+ return null;
145
+ }
146
+ if (judge.start === null) {
147
+ // The frame that opens a window may straddle whatever came before it.
148
+ judge.start = now;
149
+ return null;
150
+ }
151
+ judge.frames.push(dt);
152
+ if (now - judge.start < (judge.first ? FIRST_WINDOW_MS : WINDOW_MS)) {
153
+ return null;
154
+ }
155
+ const slow = median(judge.frames) > SLOW_FRAME_MS;
156
+ judge.first = false;
157
+ judge.reset();
158
+ if (slow) {
159
+ judge.done = true;
160
+ return 'low';
161
+ }
162
+ return null;
163
+ };
164
+ return judge;
165
+ }
166
+
167
+ // What an actor is to the low picture, by its components' names: 'npc' (an
168
+ // NPC body), 'decor' (nothing but Transform, Shape and Model), 'static'
169
+ // (scenery: those plus Solid or Lookable, or a Shape with `solid`) or 'game'
170
+ // (anything else, never
171
+ // touched: doors, pads, players, balls, the town's own pieces).
172
+ const GAMEPLAY = /^Hub|^Town|^Body$|^Ball$|^Player$/;
173
+ const DECOR = new Set(['Transform', 'Shape', 'Model']);
174
+ const SCENERY = new Set(['Transform', 'Shape', 'Model', 'Solid', 'Lookable']);
175
+
176
+ // The mark a scene file puts on an actor (`"tier": "keep"`, a field of the
177
+ // actor beside `id`) to have it drawn on every tier whatever `classify` says
178
+ // of it. Any other value is no mark.
179
+ export const KEEP = 'keep';
180
+
181
+ export function classify(components) {
182
+ const names = Object.keys(components ?? {});
183
+ // physics-3d makes an actor's collider block when it has `Solid` or its
184
+ // Shape says `solid` (physics3d.js `isSolid`); either way it is scenery that
185
+ // stops a player, never decor.
186
+ const solid = names.includes('Solid') || Boolean(components?.Shape?.solid);
187
+ if (names.includes('HubNpc')) {
188
+ return 'npc';
189
+ }
190
+ if (names.some((name) => GAMEPLAY.test(name))) {
191
+ return 'game';
192
+ }
193
+ if (!solid && names.every((name) => DECOR.has(name))) {
194
+ return 'decor';
195
+ }
196
+ return names.every((name) => SCENERY.has(name)) ? 'static' : 'game';
197
+ }
198
+
199
+ // A node's bounds once, as its middle's offset from the node's position and a
200
+ // radius: scenery does not change shape, and the offset follows a node the
201
+ // place moves (a hidden actor waits far below the ground).
202
+ function nodeBounds(node) {
203
+ const sphere = new Box3().setFromObject(node).getBoundingSphere(new Sphere());
204
+ if (!Number.isFinite(sphere.radius) || sphere.radius < 0) {
205
+ return { dx: 0, dy: 0, dz: 0, r: 0 };
206
+ }
207
+ const p = node.position;
208
+ return { dx: sphere.center.x - p.x, dy: sphere.center.y - p.y, dz: sphere.center.z - p.z, r: sphere.radius };
209
+ }
210
+
211
+ // The low picture's levers on a physics-3d world (`scene.three`: scene,
212
+ // camera, and `nodes`, actor id -> { node }; never the renderer or composer).
213
+ // `apply` puts the low picture on and keeps it on as the engine builds and
214
+ // replaces nodes (a scene load, a door trip and the way back, the town's nodes
215
+ // parked and put back: world3d.js `swapSceneNodes` adds a parked node back to
216
+ // the scene); `restore` puts back exactly what it changed.
217
+ export function makeLevers({ boundsOf = nodeBounds } = {}) {
218
+ const lv = {
219
+ world: null,
220
+ active: false,
221
+ // Lights whose shadow was turned off here.
222
+ lights: new Set(),
223
+ // node -> the parent it was taken out of.
224
+ removed: new WeakMap(),
225
+ hidden: 0,
226
+ bounds: new WeakMap(),
227
+ // The authored actors of the scene playing: only these are ever hidden
228
+ // (never a player's avatar, what they wear, or what the place spawned).
229
+ authored: null,
230
+ authoredFor: null,
231
+ // Of those, the ids the scene file marks `"tier": "keep"`: never hidden.
232
+ // null when the file marks none.
233
+ kept: null,
234
+ seen: { path: undefined, nodes: null, size: -1 },
235
+ // The entries taken out on the last look, [actor id, entry]: the engine
236
+ // replaces an entry in the same map when an actor's look changes
237
+ // (world3d.js `ensureActorNode`), and the new node is drawn, so these are
238
+ // checked every frame -- only the hidden ones, never every actor.
239
+ watch: [],
240
+ nextAt: 0,
241
+ };
242
+
243
+ const adopt = (world) => {
244
+ if (lv.world !== world) {
245
+ // A new world: nothing changed on the old one is put back there.
246
+ lv.world = world;
247
+ lv.lights = new Set();
248
+ lv.removed = new WeakMap();
249
+ lv.authored = null;
250
+ lv.authoredFor = null;
251
+ lv.kept = null;
252
+ lv.seen = { path: undefined, nodes: null, size: -1 };
253
+ lv.watch = [];
254
+ lv.nextAt = 0;
255
+ }
256
+ };
257
+
258
+ // Every light in the scene that casts a shadow stops: the sun (world3d.js)
259
+ // and any a deck added. With the sun casting none, nearshadows.js finds no
260
+ // sun and draws its frames plain, and three.js skips the shadow pass.
261
+ const lightsOff = (world) => {
262
+ for (const child of world.scene?.children ?? []) {
263
+ if (child.isLight && child.castShadow) {
264
+ child.castShadow = false;
265
+ lv.lights.add(child);
266
+ }
267
+ }
268
+ };
269
+
270
+ const authoredIds = (scene) => {
271
+ if (lv.authoredFor === scene.data && lv.authored) {
272
+ return lv.authored;
273
+ }
274
+ lv.authoredFor = scene.data;
275
+ const ids = new Set();
276
+ let kept = null;
277
+ try {
278
+ const file = scene.readFromFile(scene.scenePath);
279
+ for (const a of file?.actors ?? []) {
280
+ ids.add(a.id);
281
+ if (a.tier === KEEP) {
282
+ (kept ??= new Set()).add(a.id);
283
+ }
284
+ }
285
+ } catch {
286
+ // A scene that cannot be read has no authored actors: nothing is hidden.
287
+ ids.clear();
288
+ kept = null;
289
+ }
290
+ lv.authored = ids;
291
+ lv.kept = kept;
292
+ return lv.authored;
293
+ };
294
+
295
+ const hide = (node) => {
296
+ if (node.parent) {
297
+ lv.removed.set(node, node.parent);
298
+ node.parent.remove(node);
299
+ }
300
+ };
301
+
302
+ const unhide = (node) => {
303
+ const parent = lv.removed.get(node);
304
+ if (parent && !node.parent) {
305
+ parent.add(node);
306
+ }
307
+ lv.removed.delete(node);
308
+ };
309
+
310
+ const far = (node, near, cam, sized) => {
311
+ const p = node.position;
312
+ let b = { dx: 0, dy: 0, dz: 0, r: 0 };
313
+ if (sized) {
314
+ b = lv.bounds.get(node);
315
+ if (!b) {
316
+ b = boundsOf(node);
317
+ lv.bounds.set(node, b);
318
+ }
319
+ }
320
+ const d = Math.hypot(p.x + b.dx - cam.x, p.y + b.dy - cam.y, p.z + b.dz - cam.z) - b.r;
321
+ return d > near;
322
+ };
323
+
324
+ // One look at every node: what should not be drawn is taken out, what should
325
+ // be is put back.
326
+ const pass = (world, scene, actors) => {
327
+ lightsOff(world);
328
+ const authored = actors ? authoredIds(scene) : null;
329
+ const cam = world.camera?.position ?? { x: 0, y: 0, z: 0 };
330
+ const watch = [];
331
+ for (const [id, entry] of world.nodes) {
332
+ const node = entry?.node;
333
+ if (!node || entry.instancedRig) {
334
+ continue;
335
+ }
336
+ let want = false;
337
+ if (authored?.has(id) && !lv.kept?.has(id)) {
338
+ const kind = classify(scene.getActor?.(id)?.components);
339
+ want =
340
+ kind === 'decor' ||
341
+ (kind === 'static' && far(node, SCENERY_NEAR_M, cam, true)) ||
342
+ (kind === 'npc' && far(node, NPC_NEAR_M, cam, false));
343
+ }
344
+ if (want) {
345
+ hide(node);
346
+ if (!node.parent) {
347
+ watch.push([id, entry]);
348
+ }
349
+ } else if (lv.removed.has(node)) {
350
+ unhide(node);
351
+ }
352
+ }
353
+ lv.watch = watch;
354
+ lv.hidden = watch.length;
355
+ };
356
+
357
+ // Whether a node taken out was replaced (a rebuild) or put back since.
358
+ const watchBroken = (world) => {
359
+ for (const [id, entry] of lv.watch) {
360
+ if (world.nodes.get(id) !== entry || entry.node.parent) {
361
+ return true;
362
+ }
363
+ }
364
+ return false;
365
+ };
366
+
367
+ // Each frame while low. The nodes are looked at every CHECK_EVERY_MS, and at
368
+ // once when the engine swapped or rebuilt them (another scene, nodes parked
369
+ // or put back, actors come or gone, the scene loaded again: new scene data
370
+ // may carry other `tier` marks over the same nodes). `actors` false (a game reached through
371
+ // a door: another deck's content) puts every node back and keeps only the
372
+ // shadow lever.
373
+ lv.apply = (world, scene, now, { actors = true } = {}) => {
374
+ adopt(world);
375
+ lv.active = true;
376
+ const seen = lv.seen;
377
+ const changed = world.scenePath !== seen.path || world.nodes !== seen.nodes || world.nodes.size !== seen.size || scene.data !== seen.data || watchBroken(world);
378
+ if (!changed && now < lv.nextAt && actors === seen.actors) {
379
+ return;
380
+ }
381
+ lv.seen = { path: world.scenePath, nodes: world.nodes, size: world.nodes.size, data: scene.data, actors };
382
+ lv.nextAt = now + CHECK_EVERY_MS;
383
+ pass(world, scene, actors);
384
+ };
385
+
386
+ // Back to the picture as authored: every node taken out of the scene put
387
+ // back where it was (a node the engine has since released or parked is
388
+ // left to the engine), every shadow on again.
389
+ lv.restore = (world) => {
390
+ adopt(world);
391
+ for (const entry of world.nodes.values()) {
392
+ if (entry?.node && lv.removed.has(entry.node)) {
393
+ unhide(entry.node);
394
+ }
395
+ }
396
+ lv.removed = new WeakMap();
397
+ for (const light of lv.lights) {
398
+ light.castShadow = true;
399
+ }
400
+ lv.lights.clear();
401
+ lv.hidden = 0;
402
+ lv.watch = [];
403
+ lv.active = false;
404
+ lv.seen = { path: undefined, nodes: null, size: -1 };
405
+ };
406
+
407
+ return lv;
408
+ }
409
+
410
+ // The WebGL renderer string, for `weakGpu`.
411
+ export function gpuOf(renderer) {
412
+ try {
413
+ const gl = renderer?.getContext?.();
414
+ if (!gl) {
415
+ return null;
416
+ }
417
+ const info = gl.getExtension('WEBGL_debug_renderer_info');
418
+ const name = gl.getParameter(info ? info.UNMASKED_RENDERER_WEBGL : gl.RENDERER);
419
+ return typeof name === 'string' ? name : null;
420
+ } catch {
421
+ return null;
422
+ }
423
+ }
424
+
425
+ function pageStorage() {
426
+ try {
427
+ return globalThis.localStorage ?? null;
428
+ } catch {
429
+ return null;
430
+ }
431
+ }
432
+
433
+ // The hub system's tiers: `frame(scene, counts, now)` each frame. `counts` is
434
+ // whether this frame says how the device draws the place (see `makeJudge`).
435
+ export function makeTiers({ storage = pageStorage(), clock = () => Date.now(), deviceMemory = globalThis.navigator?.deviceMemory ?? null, levers = makeLevers() } = {}) {
436
+ const t = {
437
+ mode: readMode(storage),
438
+ auto: null,
439
+ judge: makeJudge(),
440
+ levers,
441
+ last: null,
442
+ };
443
+
444
+ t.current = () => (t.mode === 'auto' ? (t.auto?.tier ?? 'high') : t.mode);
445
+ t.reason = () => (t.mode === 'auto' ? (t.auto?.reason ?? 'auto') : 'manual');
446
+
447
+ t.set = (mode) => {
448
+ if (!MODES.includes(mode)) {
449
+ return false;
450
+ }
451
+ t.mode = mode;
452
+ writeJson(storage, MODE_KEY, mode);
453
+ // A window half gathered under another mode says nothing about this one.
454
+ t.judge.reset();
455
+ return true;
456
+ };
457
+
458
+ t.frame = (scene, counts, now) => {
459
+ const world = scene.three;
460
+ if (!world) {
461
+ return;
462
+ }
463
+ // Hints are read once, from the renderer the place is drawn with.
464
+ t.auto ??= initialTier({ storage, now: clock(), gpu: gpuOf(world.renderer), deviceMemory });
465
+ const dt = t.last === null ? 0 : now - t.last;
466
+ t.last = now;
467
+ if (t.mode === 'auto' && t.auto.tier === 'high') {
468
+ const hidden = globalThis.document?.hidden === true;
469
+ if (t.judge.feed(dt, now, counts && !hidden) === 'low') {
470
+ t.auto = { tier: 'low', reason: 'slow' };
471
+ writeJson(storage, TIER_KEY, { tier: 'low', at: clock() });
472
+ }
473
+ } else {
474
+ // Not judging (a pick by hand, or already low): no frames are kept
475
+ // for a later window.
476
+ t.judge.reset();
477
+ }
478
+ if (t.current() === 'low') {
479
+ levers.apply(world, scene, now, { actors: !scene.content });
480
+ } else if (levers.active) {
481
+ // Low to High costs a one-off stall (about 1 s on the phones measured)
482
+ // as three.js recompiles its shader programs for the shadows coming
483
+ // back. Acceptable: auto never moves up, only a player's pick does.
484
+ levers.restore(world);
485
+ }
486
+ };
487
+
488
+ // For test drivers and phone measurements (`globalThis.__hub.tier`).
489
+ t.handle = {
490
+ get current() {
491
+ return t.current();
492
+ },
493
+ get reason() {
494
+ return t.reason();
495
+ },
496
+ get mode() {
497
+ return t.mode;
498
+ },
499
+ get hidden() {
500
+ return levers.hidden;
501
+ },
502
+ set: (mode) => t.set(mode),
503
+ };
504
+ return t;
505
+ }