@wildshard/engine 0.1.19 → 0.1.20

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 (79) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/lint/engine-sides.json +4 -0
  3. package/package.json +4 -2
  4. package/scripts/app-build/gen.ts +11 -0
  5. package/scripts/cell-mem-bench.mjs +2 -0
  6. package/scripts/check-devserver.mjs +1 -1
  7. package/scripts/grid-crossing-tour.mjs +11 -4
  8. package/scripts/grid-crossing-walk-proof.mjs +4 -2
  9. package/scripts/land.mjs +2 -1
  10. package/scripts/loading-flow/benchmax.mjs +34 -11
  11. package/scripts/loading-flow/deskbench.mjs +276 -0
  12. package/scripts/loading-flow/stalls.d.mts +17 -3
  13. package/scripts/loading-flow/stalls.mjs +82 -3
  14. package/scripts/nightly-model.ts +9 -6
  15. package/scripts/offline-proof.mjs +7 -1
  16. package/scripts/parity/boot-smoke.mjs +13 -2
  17. package/scripts/pin-format.ts +5 -2
  18. package/scripts/pins-reuse.d.mts +1 -0
  19. package/scripts/pins-reuse.mjs +22 -0
  20. package/scripts/scratch-dir.mjs +95 -0
  21. package/scripts/scratch-sweep.mjs +182 -0
  22. package/scripts/tsconfig.json +2 -12
  23. package/scripts/vps/harden-prometheus.sh +3 -0
  24. package/scripts/worktree-reap.mjs +54 -8
  25. package/scripts/worktree.mjs +19 -5
  26. package/src/client/engine/anim/rigParser.ts +2 -2
  27. package/src/client/engine/core/Game.ts +63 -19
  28. package/src/client/engine/core/gpuOnly.ts +10 -0
  29. package/src/client/engine/core/renderBudget.ts +134 -0
  30. package/src/client/engine/net/redial.ts +40 -5
  31. package/src/client/engine/render/dataLook.ts +70 -7
  32. package/src/client/engine/render/families/pbr.ts +2 -0
  33. package/src/client/engine/render/families/registry.ts +11 -2
  34. package/src/client/engine/render/families/sceneSurface.ts +116 -0
  35. package/src/client/engine/render/look.ts +7 -1
  36. package/src/client/engine/render/precompile.ts +4 -2
  37. package/src/client/engine/render/tiers.ts +4 -1
  38. package/src/client/engine/world/declaredProps.ts +5 -1
  39. package/src/client/engine/world/skyRig.ts +4 -1
  40. package/src/client/engine/world/terrainTileView.ts +64 -23
  41. package/src/client/game/devScene/hook.ts +149 -12
  42. package/src/client/game/devScene/liveLook.ts +21 -0
  43. package/src/client/game/grid/live.ts +45 -8
  44. package/src/client/game/grid/liveSession.ts +23 -4
  45. package/src/client/game/grid/pageEntry.ts +12 -1
  46. package/src/client/game/grid/productInputs.ts +22 -11
  47. package/src/client/game/grid/session.ts +13 -4
  48. package/src/client/game/session/finish.ts +4 -1
  49. package/src/client/game/shardfile/client.ts +24 -7
  50. package/src/client/game/shardfile/clientPropMaterials.ts +4 -1
  51. package/src/client/game/shardfile/clientViews.ts +36 -8
  52. package/src/client/game/shardfile/constructionCheckpoint.ts +2 -2
  53. package/src/client/game/shardfile/groundMerge.ts +57 -5
  54. package/src/client/game/shardfile/hybrid.ts +2 -0
  55. package/src/client/game/shardfile/look.ts +1 -1
  56. package/src/client/game/shardfile/slabLibrary.ts +115 -49
  57. package/src/client/game/shardfile/tileContent.ts +1 -1
  58. package/src/client/game/shardfile/tileDriver.ts +38 -11
  59. package/src/client/game/shardfile/wirePage.ts +7 -3
  60. package/src/client/game/shardfile/worldScenes.ts +17 -10
  61. package/src/client/host/online/doctor.ts +20 -7
  62. package/src/client/host/online/doctorView.ts +2 -0
  63. package/src/client/host/online/linkScreens.ts +83 -5
  64. package/src/client/host/online/shell.ts +13 -4
  65. package/src/client/host/standalone/shell.ts +37 -1
  66. package/src/server/game/quest/eliteDrops.ts +7 -3
  67. package/src/server/game/riding/nativeTaming.ts +13 -2
  68. package/src/server/host/dedicated/cellHost.ts +14 -2
  69. package/src/server/host/dedicated/cellProtocol.ts +2 -0
  70. package/src/server/host/dedicated/dedicatedRoom.ts +24 -7
  71. package/src/server/host/dedicated/serverMetrics.ts +9 -0
  72. package/src/server/host/dedicated/workerTable.ts +31 -24
  73. package/src/server/host/standalone/serverHost.ts +56 -10
  74. package/src/server/host/standalone/serverProduct.ts +9 -7
  75. package/src/server/host/standalone/serverRuntime.ts +1 -1
  76. package/src/shared/engine/core/framePacing.ts +12 -1
  77. package/src/shared/engine/physics/terrainTiles.ts +20 -4
  78. package/src/shared/game/devColliders.ts +60 -0
  79. package/src/shared/game/devGameplay.ts +41 -0
@@ -90,7 +90,7 @@ export interface LiveGridPorts {
90
90
  export interface LiveGridState {
91
91
  current: string | null; worldFeet: GridPoint; crossings: number;
92
92
  /** GC5: the world built ahead of the traveller (on the road or pre-warmed inside the source), and how many pre-warms began */
93
- ahead?: { readonly instance: string | null; readonly warms: number; readonly refused?: string | null };
93
+ ahead?: { readonly instance: string | null; readonly warms: number; readonly refused?: string | null; readonly deferred?: readonly string[]; readonly demanded?: string | null; readonly released?: number };
94
94
  /** Last complete world remains fully charged and pressure-evictable on the road. */
95
95
  retainedCell?: { readonly instance: string; readonly remainingMs: number; readonly playingBytes: number; readonly capBytes: number } | null;
96
96
  transitions: readonly { from: string | null; to: string | null }[];
@@ -176,6 +176,9 @@ export class LiveGridHost {
176
176
  private readonly productRequests = new Map<string, { work: Promise<LiveGridAdmission>; required: boolean;
177
177
  trigger: 'entry' | 'explicit' | 'radial' | 'boulevard' }>();
178
178
  private readonly deferredProducts = new Map<string, number>();
179
+ /** GC6: a demand read (the neighbour ahead) the budget refused, by allocator revision: kept apart from the radial reads'
180
+ * deferrals, since a radial read deferred for want of headroom must not stop the demand read that may make room */
181
+ private readonly deferredDemand = new Map<string, number>();
179
182
  private readonly issues = new Map<string, string>();
180
183
  private readonly refusals = new Map<string, unknown>();
181
184
  /** One failed cold unload per excursion; quota failures retain their full claim until retry or re-approach. */
@@ -191,6 +194,9 @@ export class LiveGridHost {
191
194
  private turnedSince: { instance: string; at: number } | null = null;
192
195
  /** GC5: why the last pre-warm the heading asked for did not start (its product still reading, an exclusive runtime, or the budget) */
193
196
  private warmRefusal: string | null = null;
197
+ /** GC6: the neighbour whose product is read as demand (the nearest edge's, or the heading's) and not yet admitted: radial
198
+ * reads of other cells wait while it is missing, so they don't take back the headroom its read needs. */
199
+ private demanded: string | null = null;
194
200
  private previousFeet: GridPoint | undefined;
195
201
  /** fixed steps since `previousFeet` moved, for the traveller's speed (GC5) */
196
202
  private stepsSincePrevious = 0;
@@ -289,12 +295,16 @@ export class LiveGridHost {
289
295
  if ((bundle.hybridWireBytes > 0 || admission.exclusiveRuntime === true) && admission.prepareRuntime === undefined) throw new Error('Hybrid runtime admission is missing');
290
296
  await (timing === undefined ? admission.prepareRuntime?.() : timing.run('runtime', async () => { await admitted.prepareRuntime?.(); }));
291
297
  this.assertAlive();
292
- this.deferredProducts.delete(instance); this.products.set(instance, admission); return admission;
298
+ this.deferredProducts.delete(instance); this.deferredDemand.delete(instance); this.products.set(instance, admission); return admission;
293
299
  } catch (error) {
294
300
  this.tileMetadata.delete(instance);
295
301
  if (this.tileApproach?.instance === instance) { this.tileApproach.controller.abort(); this.tileApproach = null; }
296
302
  const refused = error instanceof ApproachInputsDeferredError || (error instanceof Error && error.message.includes(PRODUCT_DEFERRED));
297
- if ((!required || speculative) && refused) this.deferredProducts.set(instance, this.ports.allocator.revision);
303
+ // GC6 (QA 11-14 row 6): inside Driftwood the page held 3 to 5 neighbours' radial products (1199 of 1200 MB), pinned
304
+ // while held, so Nalati's demand read was refused the whole approach and its world was built only on the road. A
305
+ // refused demand read lets the speculative products of other cells go, farthest first, and is read again.
306
+ if (required && speculative && refused) { if (this.releaseSpeculative(instance) > 0) this.deferredDemand.delete(instance); else { this.deferredDemand.set(instance, this.ports.allocator.revision); if (this.demanded === instance) this.demanded = null; } }
307
+ else if (!required && refused) this.deferredProducts.set(instance, this.ports.allocator.revision);
298
308
  else { this.issues.set(instance, error instanceof Error ? error.message : String(error)); this.refusals.set(instance, error); }
299
309
  try { admission?.cancel?.(); }
300
310
  catch (cleanup) { throw new AggregateError([error, cleanup], 'Live product admission and cancellation failed', { cause: cleanup }); }
@@ -303,6 +313,23 @@ export class LiveGridHost {
303
313
  })();
304
314
  this.productRequests.set(instance, { work: request, required, trigger }); return request;
305
315
  }
316
+ /** GC6: let every admitted product nobody builds, enters or reads ahead go except `kept`'s, farthest first (each releases
317
+ * its claim, so the allocator's revision moves and a deferred demand read is tried again). Returns how many went. */
318
+ private releaseSpeculative(kept: string): number {
319
+ const feet = this.worldFeet(), keep = (id: string): boolean => id === kept || id === this.active || id === this.ahead
320
+ || this.constructing.has(id) || this.requests.has(id) || this.residents.has(id)
321
+ || id === this.tileApproach?.instance || id === this.transportApproach?.instance;
322
+ const idle = [...this.products.keys()].filter(id => !keep(id))
323
+ .sort((a, b) => this.distance(this.assembly.cell(b), feet) - this.distance(this.assembly.cell(a), feet));
324
+ for (const id of idle) {
325
+ const admission = this.products.get(id); this.products.delete(id); this.tileMetadata.delete(id);
326
+ try { admission?.cancel?.(); } catch (error) { console.warn(`[grid] ${id}: releasing a speculative product`, error); }
327
+ }
328
+ this.released += idle.length;
329
+ return idle.length;
330
+ }
331
+ /** GC6: how many speculative products a demand read let go (`releaseSpeculative`), for the tour */
332
+ private released = 0;
306
333
  /** GC5 / GC36: the cell whose world the road is building or built ahead of its line (`buildAhead`), kept until the
307
334
  * traveller enters a cell or heads into another's mouth. */
308
335
  private ahead: string | null = null;
@@ -507,10 +534,13 @@ export class LiveGridHost {
507
534
  }
508
535
  return released;
509
536
  }
537
+ /** GC6: whether a world is being built (pre-warmed inside the source, built ahead on the road, or entered): every world build
538
+ * is for a cell the traveller heads into, so its slices are urgent (`setBuildUrgent`). */
539
+ building(): boolean { return this.requests.size > 0; }
510
540
  /** Retry after a durability/budget change, instead of fetching the same failed request every tick. */
511
541
  retry(instance: string): void {
512
542
  if (this.requests.has(instance) || this.productRequests.has(instance)) throw new Error('Live admission is still pending');
513
- this.coldUnloadRefused.delete(instance); this.deferredProducts.delete(instance);
543
+ this.coldUnloadRefused.delete(instance); this.deferredProducts.delete(instance); this.deferredDemand.delete(instance);
514
544
  // A quota-refused unload kept a complete native region: retry must not invalidate its valid readiness ticket.
515
545
  if (this.residents.has(instance)) return;
516
546
  this.issues.delete(instance); this.refusals.delete(instance); this.readiness.invalidate(instance);
@@ -552,8 +582,13 @@ export class LiveGridHost {
552
582
  if (this.active !== null && this.ahead !== null && (this.ahead === this.active
553
583
  || this.distance(this.assembly.cell(this.ahead), feet) > WARM_KEEP_METRES)) this.ahead = null;
554
584
  this.retireInactiveRegions();
585
+ // GC6: the demanded neighbour stays demanded until its product is in, it is entered, or the traveller is far from it
586
+ const demanded = this.demanded;
587
+ if (demanded !== null && (this.products.has(demanded) || this.residents.has(demanded) || demanded === this.active || this.issues.has(demanded)
588
+ || this.distance(this.assembly.cell(demanded), feet) > DEMAND_METRES + WARM_LEAD_METRES * 4)) this.demanded = null;
555
589
  for (const cell of nearby) {
556
590
  const estimate = readinessModel(this.ports.readiness.bundle(cell), this.ports.readiness.link), distance = this.distance(cell, feet);
591
+ if (this.demanded !== null && this.demanded !== cell.instance) continue;
557
592
  if (this.assembly.approaching(distance, estimate.distance) && !this.issues.has(cell.instance) && this.ports.backgroundReady?.() !== false) void background(cell.instance, this.prefetch([cell.instance], 'radial'), () => !this.disposed);
558
593
  }
559
594
  // GC5: the neighbour across the source's nearest edge, within DEMAND_METRES, has its product read as demand, standing or
@@ -566,8 +601,9 @@ export class LiveGridHost {
566
601
  const pending = near === undefined ? undefined : this.productRequests.get(near.instance);
567
602
  if (near !== undefined && this.distance(near, feet) <= DEMAND_METRES && !this.products.has(near.instance) && !this.residents.has(near.instance)
568
603
  && (pending === undefined || !pending.required && this.raised !== pending.work) && !this.issues.has(near.instance) && !this.constructing.has(near.instance)
569
- && this.deferredProducts.get(near.instance) !== this.ports.allocator.revision && this.ports.backgroundReady?.() !== false) {
604
+ && this.deferredDemand.get(near.instance) !== this.ports.allocator.revision && this.ports.backgroundReady?.() !== false) {
570
605
  if (pending !== undefined) this.raised = pending.work;
606
+ this.demanded = near.instance;
571
607
  void background(near.instance, this.prefetchProduct(near.instance, true, 'explicit', true), () => !this.disposed);
572
608
  }
573
609
  }
@@ -669,7 +705,8 @@ export class LiveGridHost {
669
705
  // guess, which the shared budget declines while the page's other neighbours compete for the same headroom.
670
706
  if (product === undefined) {
671
707
  this.warmRefusal = 'product';
672
- if (!this.productRequests.has(moving.instance) && this.deferredProducts.get(moving.instance) !== this.ports.allocator.revision)
708
+ this.demanded = moving.instance;
709
+ if (!this.productRequests.has(moving.instance) && this.deferredDemand.get(moving.instance) !== this.ports.allocator.revision)
673
710
  void background(moving.instance, this.prefetchProduct(moving.instance, true, 'explicit', true), () => !this.disposed);
674
711
  }
675
712
  else if (product.isolatedPreparation !== true) this.warmRefusal = 'exclusive';
@@ -863,7 +900,7 @@ export class LiveGridHost {
863
900
  playingBytes: this.ports.allocator.ownerCost(last.instance).playing, capBytes: Math.min(CONTENT_CAPS.playing, policy.playingBytes) };
864
901
  }
865
902
  /** Read-only crossing evidence and failures for the real grid physics harness. */
866
- state(): LiveGridState { return { current: this.active, worldFeet: this.worldFeet(), crossings: this.crossings, ahead: { instance: this.ahead, warms: this.warms, refused: this.warmRefusal }, transitions: this.transitions.map((row) => ({ ...row })), residents: [...this.residents.keys()].sort(), pending: [...new Set([...this.requests.keys(), ...this.productRequests.keys()])].sort(), pendingWork: [
903
+ state(): LiveGridState { return { current: this.active, worldFeet: this.worldFeet(), crossings: this.crossings, ahead: { instance: this.ahead, warms: this.warms, refused: this.warmRefusal, deferred: [...new Set([...this.deferredProducts.keys(), ...this.deferredDemand.keys()])], demanded: this.demanded, released: this.released }, transitions: this.transitions.map((row) => ({ ...row })), residents: [...this.residents.keys()].sort(), pending: [...new Set([...this.requests.keys(), ...this.productRequests.keys()])].sort(), pendingWork: [
867
904
  ...[...this.requests.keys()].sort().map(instance => ({ instance, kind: 'world' as const, trigger: 'entry' as const })),
868
905
  ...[...this.productRequests].sort(([a], [b]) => a.localeCompare(b)).map(([instance, request]) => ({ instance, kind: request.required ? 'required-metadata' as const : 'optional-metadata' as const, trigger: request.trigger })),
869
906
  ], issues: Object.fromEntries(this.issues), gameplayReady: this.active === null || this.ports.gameplayReady(this.active), ...(this.ports.lastCell === undefined ? {} : { retainedCell: this.retainedState() }), retirements: this.retirements.map(row => ({ ...row })), retiring: [...this.retiring.keys()], ghosts: { count: this.ghosts.count(), regions: this.ghosts.regions() } }; }
@@ -903,7 +940,7 @@ export class LiveGridHost {
903
940
  try { this.highway.dispose(); this.highwayDisposed = true; this.highwayLease.release(); }
904
941
  catch (error) { failures.push(error); }
905
942
  }
906
- this.deferredProducts.clear();
943
+ this.deferredProducts.clear(); this.deferredDemand.clear();
907
944
  if (failures.length > 0) throw new AggregateError(failures, 'Live grid disposal failed');
908
945
  }
909
946
  }
@@ -398,7 +398,7 @@ export class LiveGridSession {
398
398
 
399
399
  private installCrossing(): GridCrossingSession {
400
400
  return installGridCrossing({ current: () => this.live.current(), prepare: (from, to) => this.prepareCrossing(from, to),
401
- ready: (instance) => this.live.ready(instance), checkpoint: (instance) => {
401
+ ready: (instance) => this.live.ready(instance) && (instance === null || !this.entryPending(instance)), checkpoint: (instance) => {
402
402
  if (this.wire !== null) return true; // the server's saves are the session's
403
403
  const readiness = this.page.crossingSaveReady?.(instance) ?? true;
404
404
  return readiness === true ? this.live.checkpoint(instance) : readiness;
@@ -870,8 +870,16 @@ export class LiveGridSession {
870
870
  const current = this.live.current();
871
871
  return current !== null && this.runtimeRegions.has(current) ? current : null;
872
872
  }
873
+ /** GC6 (QA 11-14 row 6): a world built ahead whose entry still prepares (deferred inside the source, or running on the
874
+ * road). Inside the cell its gameplay gate (`frameReady`) stops the page's frames, and that preparation's warm-up waits on
875
+ * drawn frames: the traveller stood in the cell with no control for good. Its crossing holds on the road instead. */
876
+ entryPending(instance: string): boolean { return this.deferredEntries.has(instance) || this.queuedEntries.has(instance) || this.hybrid.preparing().includes(instance); }
877
+ /** GC6: whether any world built ahead still prepares its entry (the road then builds with the urgent budget) */
878
+ entriesPending(): boolean { return this.deferredEntries.size > 0 || this.queuedEntries.size > 0 || this.hybrid.preparing().length > 0; }
879
+ /** GC6: entries taken from `deferredEntries` and waiting their turn behind another's preparation (`prepareInTurn`) */
880
+ private readonly queuedEntries = new Set<string>();
873
881
  /** GC9: once the source is left (the hybrid session is neutral), each world pre-warmed inside it prepares its entry, so the
874
- * crossing finds it ready; an entry that arrives first waits for that preparation (`HybridRuntimeSession.enter`). */
882
+ * crossing finds it ready; a crossing that arrives first holds on the road until it is (`entryPending`, GC6). */
875
883
  private prepareDeferredEntries(): void {
876
884
  // one at a time, nearest first: an entry preparation binds the page's one construction environment
877
885
  const feet = this.live.worldFeet(), gap = (instance: string): number => {
@@ -879,6 +887,7 @@ export class LiveGridSession {
879
887
  };
880
888
  const rows = [...this.deferredEntries].sort(([a], [b]) => gap(a) - gap(b));
881
889
  this.deferredEntries.clear();
890
+ for (const [instance] of rows) this.queuedEntries.add(instance);
882
891
  this.deferredPreparation = this.prepareInTurn(this.deferredPreparation, rows);
883
892
  }
884
893
  private async prepareInTurn(previous: Promise<void>, rows: readonly (readonly [string, { readonly prepared: PreparedRegionalRuntime; readonly signal: AbortSignal | undefined }])[]): Promise<void> {
@@ -888,15 +897,25 @@ export class LiveGridSession {
888
897
  private deferredPreparation: Promise<void> = Promise.resolve();
889
898
  private async prepareEntryOnRoad(instance: string, row: { readonly prepared: PreparedRegionalRuntime; readonly signal: AbortSignal | undefined }): Promise<void> {
890
899
  const live = (): boolean => this.runtimeRegions.get(instance) === row.prepared && row.signal?.aborted !== true;
891
- if (!live() || this.hybrid.state().instance !== null) { if (live()) this.deferredEntries.set(instance, row); return; }
900
+ // prepareEntry registers its installation synchronously, so the entry stays pending across this hand-over
901
+ this.queuedEntries.delete(instance);
902
+ const entered = (): boolean => this.hybrid.state().instance === instance;
903
+ if (!live() || this.hybrid.state().instance !== null) { if (live() && !entered()) this.deferredEntries.set(instance, row); return; }
892
904
  let prepared = false;
893
905
  try { prepared = await this.hybrid.prepareEntry(instance, row.signal); }
894
906
  catch (error) { console.warn(`[grid] ${instance}: entry preparation on the road`, error); }
895
907
  // a turn back into the source meanwhile (its entry made the session active) waits for the next leave
896
- if (!prepared && live() && this.hybrid.state().instance !== null) this.deferredEntries.set(instance, row);
908
+ if (!prepared && live() && this.hybrid.state().instance !== null && !entered()) this.deferredEntries.set(instance, row);
897
909
  }
898
910
  /** G555: the entered runtime hooks' timings (the one running and those finished), for the cell loading screen. */
899
911
  hookTimings(): ReturnType<HybridRuntimeSession['timings']> { return this.hybrid.timings(); }
912
+ /** GC6: the entered runtime, whether its hooks finished, the hook running, the last finished, and the entries preparing */
913
+ hybridState(): { readonly instance: string | null; readonly ready: boolean; readonly hook: string | null; readonly last: string | null; readonly preparing: readonly string[]; readonly deferred: readonly string[]; readonly warm: readonly string[] } {
914
+ const state = this.hybrid.state(), timings = this.hybrid.timings(), last = timings.completed.at(-1);
915
+ return { ...state, hook: timings.current === null ? null : `${timings.current.instance}:${timings.current.hook}`,
916
+ last: last === undefined ? null : `${last.instance}:${last.hook}:${last.outcome}`, preparing: this.hybrid.preparing(), deferred: [...this.deferredEntries.keys()],
917
+ warm: this.hybrid.preparing().map(id => { const w = this.warmPreparation(id); return w === null ? `${id}:-` : `${id}:${w.phase}:${w.completed ? 'done' : w.progress?.detail ?? ''}`; }) };
918
+ }
900
919
  /** GC2: the server still has this client in `instance` (an online cell is still walled, C5). */
901
920
  serverHolds(instance: string): boolean { return this.wire !== null && this.wire.site() === instance; }
902
921
 
@@ -140,6 +140,17 @@ export function enterGrid(): void {
140
140
 
141
141
 
142
142
 
143
+ /** The grid page's address: its path, and only the harness flags skipintro, mute and nolock, none of which selects a level, and `skipintro` dropped here sent a
144
+ * `?chunk=<slug>&skipintro` link on a world build back under the title (OFFLINE OF18: every Open Plot in the offline proof). */
145
+ export function gridPageUrl(href: string): URL {
146
+ const from = new URL(href).searchParams, to = new URL(new URL(href).pathname, new URL(href).origin);
147
+ const skipintro = from.get('skipintro'), mute = from.get('mute'), nolock = from.get('nolock');
148
+ if (skipintro !== null) to.searchParams.set('skipintro', skipintro);
149
+ if (mute !== null) to.searchParams.set('mute', mute);
150
+ if (nolock !== null) to.searchParams.set('nolock', nolock);
151
+ return to;
152
+ }
153
+
143
154
  /** The boot's one read of the tap intent (used or not), overridden by validated recovery before ordinary admission.
144
155
  * In grid mode the address becomes the bare title URL, preventing an unrecorded automatic restart. */
145
156
  export function bootPageMode(slug: string): PageMode {
@@ -172,7 +183,7 @@ export function bootPageMode(slug: string): PageMode {
172
183
  registerBeforeReload(pageScope, reason => gridRecovery(saves).write(assembly, home, road, reason === 'settings' ? 'reload' : reason)); // SR12: a Settings reload continues play
173
184
  }
174
185
  if (mode === 'grid' && typeof history !== 'undefined') {
175
- try { history.replaceState(history.state, '', new URL(location.pathname, location.origin)); } catch { /* a sandboxed frame: the URL stays */ }
186
+ try { history.replaceState(history.state, '', gridPageUrl(location.href)); } catch { /* a sandboxed frame: the URL stays */ }
176
187
  }
177
188
  return mode;
178
189
  }
@@ -10,6 +10,22 @@ export class ApproachInputsDeferredError extends Error {
10
10
  constructor() { super('Product input residency admission deferred'); this.name = 'ApproachInputsDeferredError'; }
11
11
  }
12
12
 
13
+ /** GC6: reads in flight for a world's input read-back, and for a cancellable approach's. */
14
+ export const INPUT_READS = 16, APPROACH_INPUT_READS = 12;
15
+ /** Run `read` over `refs` with at most `width` in flight; the first failure stops new reads, waits for those in flight and
16
+ * throws. `active` is checked before each new read (it throws on cancellation). */
17
+ export async function readWindow(refs: readonly string[], width: number, active: () => void, read: (ref: string) => Promise<void>): Promise<void> {
18
+ let next = 0, failure: { readonly error: unknown } | undefined;
19
+ const lane = async (): Promise<void> => {
20
+ while (failure === undefined && next < refs.length) {
21
+ const ref = refs[next++]; if (ref === undefined) return;
22
+ try { active(); await read(ref); } catch (error) { failure ??= { error }; }
23
+ }
24
+ };
25
+ await Promise.all(Array.from({ length: Math.min(width, refs.length) }, lane));
26
+ if (failure !== undefined) throw failure.error;
27
+ }
28
+
13
29
  /** One admitted grid product's transient inputs, shared by overlapping preparations, never by finished promises. */
14
30
  export class ProductInputs {
15
31
  readonly reader: ClientAssets;
@@ -73,17 +89,12 @@ export class ProductInputs {
73
89
  const lease = this.reserve(bytes, signal !== undefined), loaded = new Map<string, Uint8Array>();
74
90
  try {
75
91
  // GC9: a cell's world reads its inputs back from the cache before it builds (Pine: about 1,500 files); one at a time
76
- // that read was most of the build behind a moving player's loading wall. Eight in flight; a cancellable approach four.
77
- const width = signal === undefined ? 8 : 4;
78
- for (let i = 0; i < missing.length; i += width) {
79
- active(); const batch = missing.slice(i, i + width);
80
- const results = await Promise.allSettled(batch.map(ref => this.reader.read(ref)));
81
- for (const [index, result] of results.entries()) {
82
- if (result.status === 'rejected') throw result.reason;
83
- const ref = batch[index]; if (ref === undefined) throw new Error('Missing approach transport identity');
84
- loaded.set(ref, result.value);
85
- }
86
- }
92
+ // that read was most of the build behind a moving player's loading wall.
93
+ // GC6 (QA 11-14 row 6): each read is a cache round trip that waits on drawn frames, so it is latency-bound, not
94
+ // byte-bound: Nalati's ~860 inputs in lockstep batches of four took 20 s of its world's 30 s at Jake's 2992x1434@2.
95
+ // A sliding window keeps INPUT_READS (a cancellable approach APPROACH_INPUT_READS) in flight; the bytes held are
96
+ // the same (all of them are kept, and the lease above already charges them).
97
+ await readWindow(missing, signal === undefined ? INPUT_READS : APPROACH_INPUT_READS, active, async ref => { loaded.set(ref, await this.reader.read(ref)); });
87
98
  active();
88
99
  for (const [ref, value] of loaded) this.assets.set(ref, value);
89
100
  this.claims.push({ refs: new Set(missing), bytes, lease });
@@ -98,6 +98,7 @@ import { clientTileViews, type ClientTileViews } from '../shardfile/clientViews'
98
98
  import type { ClientSkin } from '../shardfile/clientSkins';
99
99
  import { setParkedMatricesFrozen, setWarmUpHeld } from '@wildshard/engine/render/precompile';
100
100
  import { setBuildHeldTimed } from '@wildshard/engine/core/heldTiming';
101
+ import { setBuildUrgent } from '@wildshard/engine/core/framePacing';
101
102
  import { NeighbourLife, type NeighbourLifeCell } from './neighbourLife';
102
103
  import { NeighbourPanels } from './neighbourPanels';
103
104
  import { copyMarks } from './copyIdentity';
@@ -214,8 +215,12 @@ export interface GridSessionState {
214
215
  readonly cellStage: string | null;
215
216
  /** GC8: the `cell` path step that screen shows now and its detail, so a harness times each step. */
216
217
  readonly cellStep: { readonly step: string; readonly detail: string } | null;
218
+ /** GC6: the hybrid runtime session's entry state (liveSession `hybridState`) */
219
+ readonly hybrid?: ReturnType<LiveGridSession['hybridState']> | null;
217
220
  /** the allocator's grid content (MB) and the §3.2 playing total with the engine base (MB, the 1.0 GB envelope, G65) */
218
221
  readonly residentMB: number; readonly playingMB: number;
222
+ /** GC6: the playing envelope the allocator admits against (MB) */
223
+ readonly envelopeMB?: number;
219
224
  /** Exact category sum before engine base, overlap allowance or calibration factor; used by the soak harness. */
220
225
  readonly accountedBytes: number;
221
226
  readonly rings: { readonly frame?: number; readonly far: number; readonly l1: number; readonly l0: number; readonly refused: number; readonly inFlight: number; readonly queued: number;
@@ -688,7 +693,7 @@ export class GridSession {
688
693
  // QA 2026-11-13: a waiting cell's loading steps on SHARD SELECT's loading card, inset over the live world
689
694
  this.cellLoading = new CellLoading(new CellLoadingCard(), (waiting) => this.neighbours.some(row => row.instance === waiting));
690
695
  setParkedMatricesFrozen(true); // G580 T2: a hidden parked world skips matrix updates during its warm-up
691
- host.scope.onDispose(() => { this.cellLoading.close(); if (host.heldFrame !== undefined) host.heldFrame.enabled = false; setWarmUpHeld(false); setParkedMatricesFrozen(false); setBuildHeldTimed(false); });
696
+ host.scope.onDispose(() => { this.cellLoading.close(); if (host.heldFrame !== undefined) host.heldFrame.enabled = false; setWarmUpHeld(false); setParkedMatricesFrozen(false); setBuildHeldTimed(false); setBuildUrgent(false); });
692
697
  // G78: a shimmer line at every shard border on its real ground; G119: SAVING… / SAVE FAILED, RETRY while a crossing waits
693
698
  const rows = new Map((edges ?? []).map((cell) => [cell.instance, cell.edges]));
694
699
  let status: CrossingSaveStatus = null, polled = 0;
@@ -972,7 +977,8 @@ export class GridSession {
972
977
  */
973
978
  private cellLoadingInput(): CellLoadingInput | null {
974
979
  const live = this.live; if (live === null) return null;
975
- const current = live.live.current(), ready = (id: string): boolean => live.live.ready(id) && (current !== id || live.gameplayReady());
980
+ // GC6: a world built ahead whose entry still prepares holds its crossing on the road: the screen shows it
981
+ const current = live.live.current(), ready = (id: string): boolean => live.live.ready(id) && !live.entryPending(id) && (current !== id || live.gameplayReady());
976
982
  let target: GridCell | undefined = current !== null && !ready(current) ? this.assembly.cell(current) : undefined;
977
983
  if (target === undefined) {
978
984
  const at = this.world();
@@ -1011,6 +1017,9 @@ export class GridSession {
1011
1017
  // G580 T2 / T5: a held traveller's warm-up issues more programs a frame and its builds run a bigger budget
1012
1018
  setWarmUpHeld(this.cellLoading.open !== null);
1013
1019
  setBuildHeldTimed(this.cellLoading.open !== null);
1020
+ // GC6: a world the traveller heads into, or the road (where its entry prepares), builds with the urgent budget
1021
+ const live = this.live;
1022
+ setBuildUrgent(live !== null && (live.live.building() || live.entriesPending()));
1014
1023
  }
1015
1024
  private refusal(instance: string): ShardRefusal | null {
1016
1025
  const live = this.live?.refusal(instance);
@@ -1247,8 +1256,8 @@ export class GridSession {
1247
1256
  pitch: this.assembly.pitch,
1248
1257
  home: this.home.instance, inside: gridCells.cell?.instance ?? null, feet: { x: Math.round(at.x * 100) / 100, z: Math.round(at.z * 100) / 100 },
1249
1258
  cells: this.assembly.cells.map((cell) => { const d = drawn(cell.instance); return { instance: cell.instance, slug: cell.slug, cell: cell.cell, shows: shows(cell.instance, d), drawn: d }; }),
1250
- strips: this.strips.length, road: this.road, seams: this.seams, softWalls: this.softWalls.state(), shimmer: this.shimmer.state(), cellLoading: this.cellLoading.open, cellStage: this.cellLoading.stage, cellStep: this.cellLoading.now, ringsReady: this.rings.ready(), ringsWait: { cells: this.rings.waiting(), far: this.rings.farPlan(), preparation: this.farPreparation(), waits: { count: pending.length, oldest: pending.map(({ label, kind, ageMs }) => ({ label, kind, ageMs })).sort((a, b) => b.ageMs - a.ageMs).slice(0, 16) } },
1251
- residentMB: Math.round(cost.accounted / 1e4) / 100, playingMB: Math.round(cost.playing / 1e4) / 100,
1259
+ strips: this.strips.length, road: this.road, seams: this.seams, softWalls: this.softWalls.state(), shimmer: this.shimmer.state(), cellLoading: this.cellLoading.open, cellStage: this.cellLoading.stage, cellStep: this.cellLoading.now, hybrid: this.live?.hybridState() ?? null, ringsReady: this.rings.ready(), ringsWait: { cells: this.rings.waiting(), far: this.rings.farPlan(), preparation: this.farPreparation(), waits: { count: pending.length, oldest: pending.map(({ label, kind, ageMs }) => ({ label, kind, ageMs })).sort((a, b) => b.ageMs - a.ageMs).slice(0, 16) } },
1260
+ residentMB: Math.round(cost.accounted / 1e4) / 100, playingMB: Math.round(cost.playing / 1e4) / 100, envelopeMB: Math.round(this.allocator.envelope() / 1e4) / 100,
1252
1261
  accountedBytes: cost.accounted,
1253
1262
  rings: { frame: stats.frame, far: stats.resident.far, l1: stats.resident.l1, l0: stats.resident.l0, refused: stats.refused, inFlight: stats.inFlight, queued: stats.queued,
1254
1263
  ghosts: { count: this.tileGhosts.count(), tiles: this.tileGhosts.regions() } },
@@ -1,6 +1,7 @@
1
1
  import type { BuiltWorld } from './context';
2
2
  import { bootMark, bootTask } from '@wildshard/engine/boot/timing';
3
3
  import { diagnosticNow } from '@wildshard/engine/core/clock';
4
+ import { captureHeightfield } from '@wildshard/engine/world/Heightfield';
4
5
  import { sustainedFrames } from '@wildshard/engine/core/sustainedFrames';
5
6
  import { Rng } from '@wildshard/engine/core/rng';
6
7
  import { gridCells } from '../plugin/context';
@@ -401,7 +402,9 @@ export async function finishStage(ctx: Awaited<ReturnType<typeof playStage>>): P
401
402
  // build's define makes this `false` in this module, so the import and its chunk go (scripts/check-devserver.mjs checks;
402
403
  // DEVSERVER imported from grid/menu did not fold across modules and kept the chunk).
403
404
  if (typeof __DEVSERVER__ === 'boolean' && __DEVSERVER__) void import('../devScene/hook').then(dev => dev.installDevHook({ scope: game.levelScope, scene: game.rootScene, physics: () => world.physics,
404
- look: () => game.look, server: () => window.__workerClientDevColliders ?? null, watchFrames: fn => game.watchFrames(fn) }))
405
+ look: () => game.look, server: () => window.__workerClientDevColliders ?? null, serverGround: () => window.__workerClientDevGround ?? null,
406
+ restart: () => window.__workerClientDevRestart ?? null, quests: () => window.__shardfileDevQuests ?? null,
407
+ player: () => world.player, terrainField: captureHeightfield, watchFrames: fn => game.watchFrames(fn) }))
405
408
  .catch((cause: unknown) => { console.error('[devScene]', cause); });
406
409
  ctx.startExplore?.();
407
410
  document.dispatchEvent(new Event('ws:ready')); // booted to the title
@@ -2,6 +2,7 @@ import {readModuleGroups} from '@wildshard/engine/boot/download';
2
2
  import { whenControl } from '@wildshard/engine/boot/prefetch';
3
3
  import type * as ScriptPresentation from '../plugin/ui';
4
4
  import type { Scope } from '@wildshard/engine/app/scope';
5
+ import type { SystemSpec } from '@wildshard/engine/app/systems';
5
6
  import type * as LootPresentation from '../loot/runtime';
6
7
  import type * as CompendiumPresentation from '../compendium/install';
7
8
 
@@ -610,13 +611,29 @@ export class ShardfileClient {
610
611
  player: () => world.player.position });
611
612
  ctx.debug.expose('shardfileTalks', { talks: () => talks.map(talk => ({ id: talk.id, node: talk.node() ?? null, open: box?.isOpen ?? false })) });
612
613
  }
613
- for (const declaration of source.quests.quests) {
614
- const quest = new QuestState(declaration, flags, ctx.app.events, ctx.scope);
615
- const options = declaration.track === false ? { chip: () => ({ label: '', count: '' }) } : {};
616
- // a retained (grid) runtime's chip, pins and card are its entered cell's only
617
- if (presentation === null) throw new Error('Missing quest presentation module');
618
- if (retainsRuntimeServices(ctx)) presentation.installEnteredQuestPresentation(ctx, quest, options); else presentation.installQuestPresentation(ctx, quest, options);
619
- }
614
+ const installQuests = (quests: Shardfile['quests'], at: ShardContext, ui: typeof presentation): void => {
615
+ for (const declaration of quests.quests) {
616
+ const quest = new QuestState(declaration, flags, ctx.app.events, at.scope);
617
+ const options = declaration.track === false ? { chip: () => ({ label: '', count: '' }) } : {};
618
+ // a retained (grid) runtime's chip, pins and card are its entered cell's only
619
+ if (ui === null) throw new Error('Missing quest presentation module');
620
+ if (retainsRuntimeServices(ctx)) ui.installEnteredQuestPresentation(at, quest, options); else ui.installQuestPresentation(at, quest, options);
621
+ }
622
+ };
623
+ // SHARD-SOURCE AP19 (DEVSERVER): `wildshard watch`'s soft restart rebuilds the quest views from a new quest section, so on a
624
+ // watched (one-shard) page they live in one child scope it replaces; elsewhere they are the context's, as they always were.
625
+ if (typeof __DEVSERVER__ === 'boolean' && __DEVSERVER__ && !retainsRuntimeServices(ctx) && typeof window !== 'undefined') {
626
+ const views = (scope: Scope): ShardContext => Object.create(ctx, { scope: { value: scope }, system: { value: (spec: SystemSpec) => { ctx.app.addSystem(spec, scope); } } }) as ShardContext;
627
+ let held = ctx.scope.child('shardfile.quests');
628
+ installQuests(source.quests, views(held), presentation);
629
+ ctx.scope.expose(window, '__shardfileDevQuests', async (quests: Shardfile['quests']): Promise<boolean> => {
630
+ const ui = presentation ?? await import('../plugin/ui');
631
+ if (ctx.scope.disposed) return false;
632
+ // the old views go first: a quest's system keeps its id across the swap
633
+ held.dispose(); held = ctx.scope.child('shardfile.quests');
634
+ try { installQuests(quests, views(held), ui); return true; } catch (cause) { console.error('[devScene] quest views', cause); return false; }
635
+ });
636
+ } else installQuests(source.quests, ctx, presentation);
620
637
  if (ctx.product.has('ui/completion') && ctx.product.section('ui/completion').trigger === 'quest') installCompletion(ctx, flags, play.progress);
621
638
  runtime.hooks.questFlags = () => flags.all; runtime.hooks.adventureFlags = () => flags.all;
622
639
  // An admitted scene installs its own declared profiles once in the play phase.
@@ -23,6 +23,7 @@ import { materialGraphIr } from '@wildshard/format/materials';
23
23
  import { FAMILY_IDS } from '@wildshard/format/materialFamilies';
24
24
  import { propMaterialSlots, propSlotUse, type PropMaterials, type PropTextureSlot } from '@wildshard/format/propMaterials';
25
25
  import type { Shardfile } from '@wildshard/format/shardSchema';
26
+ import { sceneSurfaceChannels } from '@wildshard/engine/render/families/sceneSurface';
26
27
 
27
28
  const WRAPS: Readonly<Record<number, Wrapping>> = { 33071: ClampToEdgeWrapping, 33648: MirroredRepeatWrapping, 10497: RepeatWrapping };
28
29
  const MAG: Readonly<Record<number, MagnificationTextureFilter>> = { 9728: NearestFilter, 9729: LinearFilter };
@@ -90,7 +91,9 @@ export async function propSurfaces(materials: PropMaterials, ports: {
90
91
  for (const [slot, value] of slots) { const param = params[slot]; if (param?.type !== 'texture' && slot === 'colour' && graphUsesMeshMap(graph)) continue; if (param?.type !== 'texture') throw new Error(`props material "${name}": graph ${row.id} has no texture param ${slot}`); params[slot] = { ...param, value: value.file }; }
91
92
  material = ownedGraph(ports.compile({ family: 'graph', graph: { ...graph, params } }), `${row.id}:${name}`);
92
93
  } else material = base(row.id);
93
- resolved.set(name, { material, maps });
94
+ // SHARD-SOURCE AP11, AP12: a card reads its corners and a swaying surface its sway from their GLB channels
95
+ const channels = sceneSurfaceChannels(entry);
96
+ resolved.set(name, { material, maps, ...(channels === null ? {} : { channels }) });
94
97
  }
95
98
  return (name) => {
96
99
  const binding = resolved.get(name);
@@ -6,15 +6,15 @@
6
6
  * the optional `outline` hook (`clientMaterials().outline`): a graph that declares `stages.outline` draws its hull as each
7
7
  * mesh's second draw (terrain tiles, fine prop tiles, library panels and models; the coarse L1 proxy keeps one draw).
8
8
  */
9
- import { AdditiveBlending, Box3, BufferAttribute, BufferGeometry, Material, Mesh, StaticDrawUsage, type Object3D, type Texture } from 'three';
9
+ import { AdditiveBlending, Box3, BufferAttribute, BufferGeometry, Material, Mesh, ShaderMaterial, StaticDrawUsage, type Object3D, type Texture } from 'three';
10
10
  import type { Scope } from '@wildshard/engine/app/scope';
11
- import type { TerrainTileData } from '@wildshard/format/terrainTileBytes';
12
- import { installTerrainTile, maskTerrainTile } from '@wildshard/engine/world/terrainTileView';
11
+ import { installTerrainTile, isCoarse, maskTerrainTile } from '@wildshard/engine/world/terrainTileView';
12
+ import { decodeTerrainTile, type TerrainTileData } from '@wildshard/format/terrainTileBytes';
13
13
  import { coarseTileMask } from '@wildshard/engine/world/coarseTileMask';
14
14
  import { installDeclaredProps, type PropSurfaceBinding } from '@wildshard/engine/world/declaredProps';
15
15
  import type { ClientWorldViews, ResidentTile } from './tileContent';
16
16
  import type { GraphOutlineHook } from './clientGraphs';
17
- import { groundMerge } from './groundMerge';
17
+ import { groundMerge, mergeView } from './groundMerge';
18
18
  import type { Shardfile } from '@wildshard/format/shardSchema';
19
19
  import { geometryBoundsSteps } from '@wildshard/engine/world/geometryBounds';
20
20
  import { workSlice } from '@wildshard/engine/core/workSlice';
@@ -28,6 +28,21 @@ const FLAT = 0.01, FLOOR = 0.1;
28
28
  const isGlow = (material: Material): boolean => material.userData['graphRawOutput'] === true && material.userData['graphMeshMap'] !== true;
29
29
 
30
30
  function isMesh(object: Object3D): object is Mesh { return object instanceof Mesh; }
31
+ /**
32
+ * SHARD-SOURCE AP8: a fine tile mesh that may draw in its material's cross-tile merge: a plain drawn mesh (not instanced or
33
+ * skinned, no morphs, no groups, no hull under it) on one opaque built-in family material. Left out: see-through surfaces
34
+ * and cards (they sort or face the camera one by one), swaying ones (a phase per prop), graph shaders (they may read
35
+ * the mesh's own space) and mirrored meshes.
36
+ */
37
+ function mergeable(mesh: Mesh): mesh is Mesh<BufferGeometry, Material> {
38
+ const material: unknown = mesh.material, geometry: unknown = mesh.geometry;
39
+ if (Object.getPrototypeOf(mesh) !== Mesh.prototype || !mesh.visible || mesh.children.length > 0 || !isMaterial(material) || !isGeometry(geometry)) return false;
40
+ if (material instanceof ShaderMaterial || material.transparent || material.userData['sceneAlpha'] === true || material.userData['sceneCard'] === true) return false;
41
+ if (geometry.groups.length > 0 || Object.keys(geometry.morphAttributes).length > 0 || !geometry.hasAttribute('position')) return false;
42
+ // a mirrored mesh (negative scale) would keep its triangles' order in the merge and turn inside out: three flips winding per object
43
+ mesh.updateWorldMatrix(true, false); if (mesh.matrixWorld.determinant() < 0) return false;
44
+ return Object.keys(geometry.attributes).every((name) => !name.startsWith('_') && !name.startsWith('ws'));
45
+ }
31
46
  /** a fine tile has nothing under it to hide */
32
47
  function noMask(excluded: ReadonlySet<number>): void { if (excluded.size > 0) throw new Error('shardfile views: only a coarse tile masks quadrants'); }
33
48
 
@@ -37,7 +52,8 @@ function noMask(excluded: ReadonlySet<number>): void { if (excluded.size > 0) th
37
52
  * only attaches it. Terrain takes wire bytes or `TerrainTileData` already decoded off the main thread.
38
53
  */
39
54
  export interface ClientTileViews {
40
- terrain: (input: Uint8Array | TerrainTileData, root: Object3D, scope: Scope, shadow: boolean) => ResidentTile;
55
+ /** `ground`: where fine tiles merge (AP8; absent: `root`); a ring passes its shared root, as for props */
56
+ terrain: (input: Uint8Array | TerrainTileData, root: Object3D, scope: Scope, shadow: boolean, ground?: Object3D) => ResidentTile;
41
57
  /** `ground`: where a drawn splat ground's tiles merge (absent: `root`); a ring passes its shared root, as each tile's
42
58
  * `root` is its own group */
43
59
  props: (props: NonNullable<Shardfile['props']>, key: string, bytes: Uint8Array, root: Object3D, scope: Scope, additional?: ReadonlyMap<string, Uint8Array>, ground?: Object3D) => Promise<ResidentTile | null>;
@@ -60,7 +76,9 @@ interface ViewPorts { terrain: string | NonNullable<Shardfile['terrain']> | null
60
76
  /** The terrain's shadow flags (`terrain.shadow`): a tile casts only when `cast` (and the shadow disc says so), receives only when `receive` (absent: both). */
61
77
  terrainShadow?: NonNullable<Shardfile['terrain']>['shadow'] | undefined;
62
78
  /** The tiles' draw order among the opaque surfaces (`terrain.order`, three's renderOrder; absent: TERRAIN_ORDER). */
63
- terrainOrder?: number | undefined }
79
+ terrainOrder?: number | undefined;
80
+ /** SHARD-SOURCE AP8: a fine tile's static props draw merged per material across tiles (`propMerge`; absent: true) */
81
+ mergeProps?: boolean }
64
82
 
65
83
  /** G784: absent `terrain.order`, the ground draws before the opaque surfaces laid on it (a road, a yard, a path), so a
66
84
  * surface at the ground's depth always wins its tie. At renderOrder 0 three broke those ties by material id: a world's
@@ -88,12 +106,16 @@ export function clientTileViews(ports: ViewPorts): ClientTileViews {
88
106
  if (material === undefined) throw new Error('shardfile views: the terrain family has no resolved material');
89
107
  const cast = ports.terrainShadow?.cast ?? true, receive = ports.terrainShadow?.receive ?? true;
90
108
  return {
91
- terrain: (input, root, scope, shadow) => {
109
+ terrain: (input, root, scope, shadow, groundRoot) => {
92
110
  if (material === null) throw new Error('shardfile views: a terrain tile in a shard without terrain');
93
- const mesh = installTerrainTile(input, { root, scope, material, shadow: cast && shadow, ...(ports.lattice === undefined ? {} : { lattice: ports.lattice }) });
111
+ const data = input instanceof Uint8Array ? decodeTerrainTile(input) : input;
112
+ const mesh = installTerrainTile(data, { root, scope, material, shadow: cast && shadow, ...(ports.lattice === undefined ? {} : { lattice: ports.lattice }) });
94
113
  if (!receive) mesh.receiveShadow = false;
95
114
  mesh.renderOrder = ports.terrainOrder ?? TERRAIN_ORDER;
96
115
  const hulls = ports.outline?.(mesh, material, scope) ?? [];
116
+ // AP8: a fine tile with no hull draws in the terrain's merge, one view draw a 250 m block; it still casts itself
117
+ // (the shadow pass only) while its shadow disc says so. A coarse tile keeps its own mesh for its quadrant mask.
118
+ if ((ports.mergeProps ?? true) && hulls.length === 0 && !isCoarse(data)) mergeView(groundRoot ?? root, mesh, material, scope);
97
119
  // a coarse tile's mask moves its draw range; its hull (a shallow geometry copy) follows
98
120
  const mask = (excluded: ReadonlySet<number>): void => { maskTerrainTile(mesh, excluded); for (const hull of hulls) hull.geometry.setDrawRange(mesh.geometry.drawRange.start, mesh.geometry.drawRange.count); };
99
121
  return { mask, shadow: cast ? (enabled) => { mesh.castShadow = enabled; } : () => undefined };
@@ -171,6 +193,12 @@ export function clientTileViews(ports: ViewPorts): ClientTileViews {
171
193
  for (const { mesh, box } of lit) {
172
194
  if (box.max.y - box.min.y < FLAT && box.max.y <= floor + FLOOR) mesh.castShadow = false; else casters.push(mesh);
173
195
  }
196
+ // AP8: a fine tile's plain static meshes join their material's merge under the shared root, so a view draws each
197
+ // material once a 250 m block, not once a tile; each still casts itself (the shadow pass only) as its disc says
198
+ if (row.lod === 0 && (ports.mergeProps ?? true)) {
199
+ const meshes: Mesh[] = []; root.traverse((object) => { if (isMesh(object)) meshes.push(object); });
200
+ for (const mesh of meshes) if (mergeable(mesh)) mergeView(parent, mesh, mesh.material, scope);
201
+ }
174
202
  const shadow = (enabled: boolean): void => { for (const mesh of casters) mesh.castShadow = enabled; };
175
203
  if (row.lod === 1) {
176
204
  const apply = coarseTileMask(root, row.x, row.z, scope);
@@ -1,5 +1,5 @@
1
1
  import type { Scope } from '@wildshard/engine/app/scope';
2
- import { buildHeld, frameBudgetSpent, frameDue, presenting } from '@wildshard/engine/core/framePacing';
2
+ import { buildHeld, buildUrgent, frameBudgetSpent, frameDue, presenting } from '@wildshard/engine/core/framePacing';
3
3
  import { diagnosticNow } from '@wildshard/engine/core/clock';
4
4
  import { buildYield, WORK_SLICE_MS } from '@wildshard/engine/core/workSlice';
5
5
 
@@ -26,6 +26,6 @@ export function constructionCheckpoint(owner: Scope): Promise<void> | undefined
26
26
  return buildYield(owner).then(() => { requireOwner(owner); loadingAt = diagnosticNow(); return undefined; });
27
27
  }
28
28
  loadingAt = undefined;
29
- if (live && (buildHeld() || !frameDue()) && !frameBudgetSpent(WORK_SLICE_MS)) return undefined;
29
+ if (live && (buildHeld() || buildUrgent() || !frameDue()) && !frameBudgetSpent(WORK_SLICE_MS)) return undefined;
30
30
  return buildYield(owner).then(() => { requireOwner(owner); return undefined; });
31
31
  }