@thoughts-on-things/vantage-mc 0.8.0 → 0.9.1

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.
package/README.md CHANGED
@@ -55,7 +55,13 @@ applied live (`viewer.setStreaming` re-plans in place, no reload). Or set the
55
55
  ring up-front with
56
56
  `streaming={{ viewDistance: 1024, maxTiles: 128, maxBytes: 512 * 1024 * 1024 }}`.
57
57
  `maxTiles` is a count guard; `maxBytes` is the stronger residency limit for
58
- worlds whose tile complexity varies widely.
58
+ worlds whose tile complexity varies widely. When a budget cuts the ring short,
59
+ admission stays a contiguous nearest-first disc and the fog wall hugs the real
60
+ frontier, so limits read as distance haze rather than missing tiles. Evicted
61
+ tiles also keep their compressed payloads in a client-side cache
62
+ (`tileCacheBytes`, default 192 MiB), so panning back over explored terrain
63
+ rebuilds instantly instead of re-fetching — on a `vantage server`, instead of
64
+ re-baking.
59
65
 
60
66
  The camera also lives in the URL hash (`#@x,y,z,dist,rot,tilt`), so **every
61
67
  view is a shareable deep link**: the hash follows the camera (debounced,
@@ -853,9 +853,10 @@ var Emitter = class {
853
853
  this.listeners.clear();
854
854
  }
855
855
  };
856
- var GRID = 16;
856
+ var GRID = 24;
857
857
  var SLOTS = 32;
858
- var MAX_QUEUE = 12;
858
+ var MAX_QUEUE = 256;
859
+ var CAPTURES_PER_FRAME = 4;
859
860
  var SKIRT = 12;
860
861
  var EDGES = [
861
862
  [1, 0],
@@ -1004,7 +1005,10 @@ var ImpostorLayer = class _ImpostorLayer {
1004
1005
  float camXZ = distance(vWorld.xz, cameraPosition.xz);
1005
1006
  float above = max(cameraPosition.y - vWorld.y, 0.0);
1006
1007
  float hazeNear = max(uHazeMin, above * 2.0);
1007
- float haze = smoothstep(hazeNear, hazeNear * 2.2, camXZ);
1008
+ // A tight ramp: from a tilted camera the remembered band should
1009
+ // read as distance haze soon after the hires frontier, not stand
1010
+ // vivid for another whole frontier-width beyond it.
1011
+ float haze = smoothstep(hazeNear, hazeNear * 1.8, camXZ);
1008
1012
  float f = clamp(max(smoothstep(uFog.x, uFog.y, vFog), haze) * uFogDensity, 0.0, 1.0);
1009
1013
  frag = vec4(toSRGB(mix(c, toLinear(uFogColor), f)), 1.0);
1010
1014
  }
@@ -1052,9 +1056,21 @@ var ImpostorLayer = class _ImpostorLayer {
1052
1056
  const size = SLOTS * this.resolution;
1053
1057
  return Math.round(size * size * 4 * 1.34) + this.byKey.size * 8192;
1054
1058
  }
1059
+ /** Whether a tile is remembered — or about to be (its capture is queued).
1060
+ * The manager uses this as its "underlay exists" test when deciding
1061
+ * whether a streaming-in tile has anything to dissolve over. */
1062
+ has(key) {
1063
+ if (this.byKey.has(key)) return true;
1064
+ for (const p of this.queue) if (p.key === key) return true;
1065
+ return false;
1066
+ }
1055
1067
  /** Queue an evicted tile's meshes for snapshotting. Takes OWNERSHIP of the
1056
- * meshes — they are rendered once on a later update() tick, then disposed.
1057
- * A full queue drops its oldest entry (its meshes are simply disposed). */
1068
+ * meshes — including their SCENE membership: the caller leaves them in the
1069
+ * scene, and they keep drawing (real terrain, live uniforms) until the
1070
+ * snapshot render reparents them away in the same tick their impostor
1071
+ * appears. That closed-form swap is what keeps a pan's eviction wake free
1072
+ * of background-colored holes. A full queue drops its oldest entry (its
1073
+ * meshes are removed and disposed). */
1058
1074
  capture(tileX, tileZ, meshes, surface, minY, maxY) {
1059
1075
  if (this.retired) {
1060
1076
  disposeCapture(meshes);
@@ -1073,14 +1089,16 @@ var ImpostorLayer = class _ImpostorLayer {
1073
1089
  const imp = this.byKey.get(key);
1074
1090
  if (imp) this.releaseImpostor(imp);
1075
1091
  }
1076
- /** Drain one pending capture (bounded per frame so a ring of evictions
1092
+ /** Drain a few pending captures (bounded per frame so a ring of evictions
1077
1093
  * never stacks its snapshot renders into one frame). Returns whether the
1078
1094
  * scene changed (the caller redraws + re-runs coverage). */
1079
1095
  update(focusX, focusZ) {
1080
- const p = this.queue.shift();
1081
- if (!p) return false;
1082
- this.snapshot(p, focusX, focusZ);
1083
- disposeCapture(p.meshes);
1096
+ if (this.queue.length === 0) return false;
1097
+ const batch = this.queue.splice(0, CAPTURES_PER_FRAME);
1098
+ for (const p of batch) {
1099
+ this.snapshot(p, focusX, focusZ);
1100
+ disposeCapture(p.meshes);
1101
+ }
1084
1102
  return true;
1085
1103
  }
1086
1104
  /** Hide impostors whose hires tile is resident and fully faded in. */
@@ -1443,15 +1461,92 @@ function admitTiles(candidates, maxTiles, maxBytes, estimateBytes) {
1443
1461
  const admitted = [];
1444
1462
  let bytes = 0;
1445
1463
  for (const candidate of candidates) {
1446
- if (admitted.length >= maxTiles) break;
1464
+ if (admitted.length >= maxTiles) return { admitted, cutoffSq: candidate.distanceSq };
1447
1465
  const weight = Math.max(1, estimateBytes(candidate.ref));
1448
- if (admitted.length > 0 && bytes + weight > maxBytes) continue;
1466
+ if (admitted.length > 0 && bytes + weight > maxBytes) {
1467
+ return { admitted, cutoffSq: candidate.distanceSq };
1468
+ }
1449
1469
  admitted.push(candidate);
1450
1470
  bytes += weight;
1451
1471
  }
1452
- return admitted;
1472
+ return { admitted, cutoffSq: null };
1453
1473
  }
1454
1474
 
1475
+ // src/three/tilecache.ts
1476
+ var TileByteCache = class _TileByteCache {
1477
+ /** Cap on retained entries, independent of their bytes. */
1478
+ static MAX_ENTRIES = 4096;
1479
+ /** Insertion-ordered, and every hit re-inserts — so the front of the map is
1480
+ * always the least recently used entry. */
1481
+ entries = /* @__PURE__ */ new Map();
1482
+ bytes = 0;
1483
+ budget;
1484
+ constructor(budget) {
1485
+ this.budget = budget;
1486
+ }
1487
+ /** Retained payload bytes. */
1488
+ get size() {
1489
+ return this.bytes;
1490
+ }
1491
+ /** Retained entry count. */
1492
+ get count() {
1493
+ return this.entries.size;
1494
+ }
1495
+ /** Resize the byte budget, evicting immediately to fit it. `0` (or less)
1496
+ * disables the cache and drops everything: the setting is a memory
1497
+ * ceiling, so lowering it must take effect now rather than whenever the
1498
+ * next insertion happens to evict. */
1499
+ setBudget(budget) {
1500
+ this.budget = budget;
1501
+ if (budget <= 0) {
1502
+ this.clear();
1503
+ return;
1504
+ }
1505
+ this.trim();
1506
+ }
1507
+ /** The payload for `key` if it was cached at exactly `revision` (a revised
1508
+ * tile is different terrain, not a stale copy of the same). A hit counts
1509
+ * as a use and moves to the back of the LRU. */
1510
+ get(key, revision) {
1511
+ const hit = this.entries.get(key);
1512
+ if (!hit || hit.revision !== revision) return void 0;
1513
+ this.entries.delete(key);
1514
+ this.entries.set(key, hit);
1515
+ return hit.buffer;
1516
+ }
1517
+ /** Retain a payload, evicting least-recently-used entries to fit. Ignores
1518
+ * payloads larger than the whole budget, and empty ones: a tile that
1519
+ * meshes to nothing re-fetches as a 0-byte body without ever reaching a
1520
+ * bake, so caching it would only accumulate entries the byte budget can
1521
+ * never evict. */
1522
+ put(key, buffer, revision) {
1523
+ if (this.budget <= 0 || buffer.byteLength === 0 || buffer.byteLength > this.budget) return;
1524
+ this.drop(key);
1525
+ this.entries.set(key, { buffer, revision });
1526
+ this.bytes += buffer.byteLength;
1527
+ this.trim();
1528
+ }
1529
+ /** Forget one tile (its revision changed, it left the manifest, or its
1530
+ * bytes failed to parse and must not be served from here again). */
1531
+ drop(key) {
1532
+ const prev = this.entries.get(key);
1533
+ if (!prev) return;
1534
+ this.entries.delete(key);
1535
+ this.bytes -= prev.buffer.byteLength;
1536
+ }
1537
+ clear() {
1538
+ this.entries.clear();
1539
+ this.bytes = 0;
1540
+ }
1541
+ trim() {
1542
+ for (const [key, entry] of this.entries) {
1543
+ if (this.bytes <= this.budget && this.entries.size <= _TileByteCache.MAX_ENTRIES) break;
1544
+ this.entries.delete(key);
1545
+ this.bytes -= entry.buffer.byteLength;
1546
+ }
1547
+ }
1548
+ };
1549
+
1455
1550
  // src/three/tiles.ts
1456
1551
  function recKey(level, x, z) {
1457
1552
  return level === 0 ? tileKey(x, z) : `l${level}:${x},${z}`;
@@ -1526,6 +1621,15 @@ var TileManager = class _TileManager {
1526
1621
  /** Learned tile weights survive eviction and make future admission byte-aware. */
1527
1622
  sizeHints = /* @__PURE__ */ new Map();
1528
1623
  averageHiresBytes = 12 * 1024 * 1024;
1624
+ /** Distance² where the last plan ran out of budget (null = nothing cut).
1625
+ * Derives {@link admittedRadius} — the honest hires frontier. */
1626
+ planCutoffSq = null;
1627
+ /** When the last plan ran, so byte-estimate learning re-plans at a bounded
1628
+ * rate instead of once per tile load. */
1629
+ lastPlanMs = 0;
1630
+ /** Compressed tile payloads kept after eviction. A revisit rebuilds from
1631
+ * here — no network fetch, no server re-bake. */
1632
+ byteCache;
1529
1633
  /** Whether resident tiles draw their cave-dark tails (VTLA). The viewer's
1530
1634
  * cave policy toggles this off while the camera is above ground with the
1531
1635
  * depth slice closed. */
@@ -1545,10 +1649,12 @@ var TileManager = class _TileManager {
1545
1649
  // (π·(768/128)² ≈ 113) with a little slack — and to match the settings
1546
1650
  // panel's "med" preset exactly.
1547
1651
  maxTiles: 120,
1548
- concurrency: 4,
1652
+ concurrency: 6,
1549
1653
  maxBytes: 512 * 1024 * 1024,
1654
+ tileCacheBytes: 192 * 1024 * 1024,
1550
1655
  ...rest
1551
1656
  };
1657
+ this.byteCache = new TileByteCache(this.opts.tileCacheBytes);
1552
1658
  this.lowresMaterial = lowresMaterial ?? null;
1553
1659
  this.lmMaterial = lmMaterial ?? null;
1554
1660
  this.ensureAtlas = ensureAtlas ?? null;
@@ -1573,10 +1679,18 @@ var TileManager = class _TileManager {
1573
1679
  const rec = this.records.get(key);
1574
1680
  return rec?.level === 0 && rec.state === "ready" ? rec.surface : void 0;
1575
1681
  };
1576
- /** Keep the impostor haze floor tracking the guaranteed-hires radius (the
1577
- * view distance, unless the tile budget's disc runs out first). */
1682
+ /** The radius hires tiles are actually resident to: the view distance,
1683
+ * capped by whichever budget ran out first — the tile-count disc, or the
1684
+ * byte budget's cut in the last admission plan. The viewer sizes fog and
1685
+ * zoom off this so the frontier always reads as haze, never a cliff. */
1686
+ get admittedRadius() {
1687
+ const countRadius = this.tileBlocks * Math.sqrt(this.opts.maxTiles / Math.PI);
1688
+ const planRadius = this.planCutoffSq === null ? Infinity : Math.sqrt(this.planCutoffSq);
1689
+ return Math.min(this.opts.viewDistance, countRadius, planRadius);
1690
+ }
1691
+ /** Keep the impostor haze floor tracking the guaranteed-hires radius. */
1578
1692
  applyHazeFloor() {
1579
- this.impostors?.setHazeFloor(Math.min(this.opts.viewDistance, this.tileBlocks * Math.sqrt(this.opts.maxTiles / Math.PI)));
1693
+ this.impostors?.setHazeFloor(this.admittedRadius);
1580
1694
  }
1581
1695
  /** Tile span in blocks at a pyramid level (0 = hires). */
1582
1696
  levelBlocks(level) {
@@ -1640,12 +1754,16 @@ var TileManager = class _TileManager {
1640
1754
  let lowBytes = this.impostors?.gpuBytes ?? 0;
1641
1755
  for (const rec of this.records.values()) if (rec.level > 0) lowBytes += rec.memoryBytes;
1642
1756
  const hiresBytes = Math.max(1, maxBytes - lowBytes);
1643
- const desired = admitTiles(
1757
+ const plan = admitTiles(
1644
1758
  nearbyTiles(this.index, this.tileBlocks, focusX, focusZ, viewDistance, predictedX, predictedZ),
1645
1759
  maxTiles,
1646
1760
  hiresBytes,
1647
1761
  (t) => this.sizeHints.get(tileKey(t.x, t.z)) ?? Math.max(this.averageHiresBytes, t.bytes * 20)
1648
- ).map((candidate) => ({ t: candidate.ref, d: candidate.distanceSq }));
1762
+ );
1763
+ this.planCutoffSq = plan.cutoffSq;
1764
+ this.lastPlanMs = performance.now();
1765
+ this.applyHazeFloor();
1766
+ const desired = plan.admitted.map((candidate) => ({ t: candidate.ref, d: candidate.distanceSq }));
1649
1767
  const desiredKeys = new Set(desired.map(({ t }) => recKey(0, t.x, t.z)));
1650
1768
  const lowDesired = [];
1651
1769
  for (let i = 0; i < this.lowLevels.length; i++) {
@@ -1666,6 +1784,10 @@ var TileManager = class _TileManager {
1666
1784
  for (const [key, rec] of this.records) {
1667
1785
  if (desiredKeys.has(key)) continue;
1668
1786
  if (rec.level === 0) {
1787
+ if (rec.state === "ready") {
1788
+ const keep2 = this.admittedRadius * 1.15 + this.tileBlocks * 0.5;
1789
+ if (this.distSqTo(rec.ref, 0, focusX, focusZ) <= keep2 * keep2) continue;
1790
+ }
1669
1791
  this.unload(key, rec);
1670
1792
  continue;
1671
1793
  }
@@ -1685,13 +1807,25 @@ var TileManager = class _TileManager {
1685
1807
  this.pump();
1686
1808
  }
1687
1809
  pump() {
1688
- while (this.inFlight < this.opts.concurrency && this.inFlight + this.pendingBuilt < this.opts.concurrency && this.queue.length > 0) {
1810
+ const maxPendingBuilt = Math.max(8, this.opts.concurrency * 2);
1811
+ while (this.inFlight < this.opts.concurrency && this.pendingBuilt < maxPendingBuilt && this.queue.length > 0) {
1689
1812
  const { ref, level } = this.queue.pop();
1690
1813
  if (level === 0 && this.index.get(tileKey(ref.x, ref.z)) !== ref) continue;
1691
1814
  if (level === 0) void this.loadTile(ref);
1692
1815
  else void this.loadLowres(ref, level);
1693
1816
  }
1694
1817
  }
1818
+ /** Whether anything already draws terrain under hires tile (x,z) — a
1819
+ * remembered/queued impostor, or a resident lowres ring covering it. */
1820
+ hasUnderlay(x, z) {
1821
+ if (this.impostors?.has(tileKey(x, z))) return true;
1822
+ for (const lvl of this.lowLevels) {
1823
+ const f = 2 ** lvl.level;
1824
+ const rec = this.records.get(recKey(lvl.level, Math.floor(x / f), Math.floor(z / f)));
1825
+ if (rec?.state === "ready") return true;
1826
+ }
1827
+ return false;
1828
+ }
1695
1829
  /** Insert built tiles into the scene at a bounded per-frame rate (via
1696
1830
  * update()), so GPU buffer uploads are spread across frames instead of
1697
1831
  * bursting. Normally one per frame; when a backlog builds (a big preset
@@ -1705,8 +1839,10 @@ var TileManager = class _TileManager {
1705
1839
  if (!rec || rec.state !== "built") continue;
1706
1840
  rec.state = "ready";
1707
1841
  this.pendingBuilt--;
1708
- rec.fadeStart = performance.now();
1709
- this.fadingKeys.add(key);
1842
+ if (rec.level !== 0 || this.hasUnderlay(rec.ref.x, rec.ref.z)) {
1843
+ rec.fadeStart = performance.now();
1844
+ this.fadingKeys.add(key);
1845
+ }
1710
1846
  this.opts.scene.add(rec.terrain);
1711
1847
  if (rec.terrainLm) this.opts.scene.add(rec.terrainLm);
1712
1848
  if (rec.water) this.opts.scene.add(rec.water);
@@ -1804,6 +1940,7 @@ var TileManager = class _TileManager {
1804
1940
  const rec = this.records.get(key);
1805
1941
  if (rec) this.unload(key, rec);
1806
1942
  this.impostors?.remove(key);
1943
+ this.byteCache.drop(key);
1807
1944
  changed = true;
1808
1945
  }
1809
1946
  }
@@ -1817,6 +1954,7 @@ var TileManager = class _TileManager {
1817
1954
  this.index.set(k, t);
1818
1955
  const rec = this.records.get(k);
1819
1956
  if (rec) this.unload(k, rec);
1957
+ this.byteCache.drop(k);
1820
1958
  changed = true;
1821
1959
  } else {
1822
1960
  previous.path = t.path;
@@ -1871,6 +2009,10 @@ var TileManager = class _TileManager {
1871
2009
  if (settings.maxTiles !== void 0) this.opts.maxTiles = settings.maxTiles;
1872
2010
  if (settings.concurrency !== void 0) this.opts.concurrency = settings.concurrency;
1873
2011
  if (settings.maxBytes !== void 0) this.opts.maxBytes = settings.maxBytes;
2012
+ if (settings.tileCacheBytes !== void 0) {
2013
+ this.opts.tileCacheBytes = settings.tileCacheBytes;
2014
+ this.byteCache.setBudget(settings.tileCacheBytes);
2015
+ }
1874
2016
  if (settings.mapMemory !== void 0 && settings.mapMemory !== this.mapMemoryResolution) {
1875
2017
  this.impostors?.dispose();
1876
2018
  this.impostors = null;
@@ -1982,7 +2124,11 @@ var TileManager = class _TileManager {
1982
2124
  this.records.set(key, rec);
1983
2125
  this.inFlight++;
1984
2126
  try {
1985
- const buffer = await maybeInflate(await this.opts.fetch(ref.path, abort.signal));
2127
+ const cached = this.byteCache.get(key, ref.revision);
2128
+ const raw = cached ?? await this.opts.fetch(ref.path, abort.signal);
2129
+ if (this.disposed || rec.state !== "loading") return;
2130
+ if (!cached) this.byteCache.put(key, raw, ref.revision);
2131
+ const buffer = await maybeInflate(raw);
1986
2132
  if (this.disposed || rec.state !== "loading") return;
1987
2133
  if (buffer.byteLength === 0) {
1988
2134
  rec.state = "empty";
@@ -2034,6 +2180,10 @@ var TileManager = class _TileManager {
2034
2180
  rec.memoryBytes = geometryBytes(meshes.terrain.geometry) + (meshes.terrainLm ? geometryBytes(meshes.terrainLm.geometry) : 0) + (meshes.water ? geometryBytes(meshes.water.geometry) : 0) + textureBytes(meshes.lightmapTex) + (rec.surface ? rec.surface.biome.byteLength + rec.surface.height.byteLength : 0);
2035
2181
  this.sizeHints.set(key, rec.memoryBytes);
2036
2182
  this.averageHiresBytes = this.averageHiresBytes * 0.875 + rec.memoryBytes * 0.125;
2183
+ if (this.planCutoffSq !== null && performance.now() - this.lastPlanMs > 250) {
2184
+ this.lastFocusX = Infinity;
2185
+ this.lastFocusZ = Infinity;
2186
+ }
2037
2187
  rec.state = "built";
2038
2188
  this.pendingBuilt++;
2039
2189
  this.failCounts.delete(key);
@@ -2043,6 +2193,7 @@ var TileManager = class _TileManager {
2043
2193
  this.emitter.emit("change", this.stats);
2044
2194
  } catch (e) {
2045
2195
  if (e.name !== "AbortError") {
2196
+ this.byteCache.drop(key);
2046
2197
  this.markFailed(key, rec);
2047
2198
  console.warn(`vantage: tile ${key} failed to load:`, e);
2048
2199
  }
@@ -2059,8 +2210,8 @@ var TileManager = class _TileManager {
2059
2210
  const remember = this.impostors !== null && rec.level === 0 && priorState === "ready" && rec.terrain !== void 0 && rec.surface !== void 0;
2060
2211
  for (const mesh of [rec.terrain, rec.terrainLm, rec.water]) {
2061
2212
  if (!mesh) continue;
2062
- this.opts.scene.remove(mesh);
2063
2213
  if (remember) continue;
2214
+ this.opts.scene.remove(mesh);
2064
2215
  if (isSharedQuadIndex(mesh.geometry.index)) mesh.geometry.setIndex(null);
2065
2216
  mesh.geometry.dispose();
2066
2217
  }
@@ -2096,11 +2247,12 @@ var TileManager = class _TileManager {
2096
2247
  hires.push({ key, rec, d: this.distSqTo(rec.ref, 0, this.focusX, this.focusZ) });
2097
2248
  }
2098
2249
  }
2099
- if (total <= this.opts.maxBytes || hires.length <= 1) return;
2250
+ const maxResident = Math.ceil(this.opts.maxTiles * 1.25);
2251
+ if (total <= this.opts.maxBytes && hires.length <= maxResident || hires.length <= 1) return;
2100
2252
  hires.sort((a, b) => b.d - a.d);
2101
2253
  let remaining = hires.length;
2102
2254
  for (const entry of hires) {
2103
- if (total <= this.opts.maxBytes || remaining <= 1) break;
2255
+ if (total <= this.opts.maxBytes && remaining <= maxResident || remaining <= 1) break;
2104
2256
  total -= entry.rec.memoryBytes;
2105
2257
  remaining--;
2106
2258
  this.unload(entry.key, entry.rec);
@@ -2135,7 +2287,7 @@ var TileManager = class _TileManager {
2135
2287
  }
2136
2288
  const remembered = this.impostors?.count ?? 0;
2137
2289
  if (this.impostors) residentBytes += this.impostors.gpuBytes;
2138
- this.statsCache = { loaded, loading, total: this.index.size, lowres, remembered, vertexCount, triangleCount, bytes, residentBytes };
2290
+ this.statsCache = { loaded, loading, total: this.index.size, lowres, remembered, vertexCount, triangleCount, bytes, residentBytes, cachedBytes: this.byteCache.size };
2139
2291
  return this.statsCache;
2140
2292
  }
2141
2293
  /** Aggregated biome share across every resident tile, most common first. */
@@ -2235,6 +2387,7 @@ var TileManager = class _TileManager {
2235
2387
  this.impostors?.dispose();
2236
2388
  this.impostors = null;
2237
2389
  for (const [key, rec] of [...this.records]) this.unload(key, rec);
2390
+ this.byteCache.clear();
2238
2391
  this.emitter.clear();
2239
2392
  }
2240
2393
  };
@@ -3449,11 +3602,13 @@ var VantageViewer = class _VantageViewer {
3449
3602
  this.applyViewLimits();
3450
3603
  }
3451
3604
  /** The radius hires tiles are actually guaranteed resident to: the view
3452
- * distance, unless the tile budget runs out first (nearest-first fill ⇒ a
3453
- * disc of maxTiles tiles ⇒ radius tb·√(maxTiles/π)). */
3605
+ * distance, unless a budget runs out first. The manager reports its honest
3606
+ * frontier (tile count AND byte budget), so fog hugs where data really
3607
+ * stops — a budget cut reads as distance haze, not a cliff into the sky. */
3454
3608
  streamRadius() {
3455
- const vd = this.tiles?.viewDistance ?? this.options.streaming.viewDistance ?? 768;
3456
- const mt = this.tiles?.maxTiles ?? this.options.streaming.maxTiles ?? 120;
3609
+ if (this.tiles) return this.tiles.admittedRadius;
3610
+ const vd = this.options.streaming.viewDistance ?? 768;
3611
+ const mt = this.options.streaming.maxTiles ?? 120;
3457
3612
  const tb = this.manifest?.tileBlocks ?? 128;
3458
3613
  return Math.min(vd, tb * Math.sqrt(mt / Math.PI));
3459
3614
  }
@@ -3847,8 +4002,9 @@ var VantageViewer = class _VantageViewer {
3847
4002
  return {
3848
4003
  viewDistance: this.tiles?.viewDistance ?? this.options.streaming.viewDistance ?? 768,
3849
4004
  maxTiles: this.tiles?.maxTiles ?? this.options.streaming.maxTiles ?? 120,
3850
- concurrency: this.options.streaming.concurrency ?? 4,
4005
+ concurrency: this.options.streaming.concurrency ?? 6,
3851
4006
  maxBytes: this.tiles?.maxBytes ?? this.options.streaming.maxBytes ?? 512 * 1024 * 1024,
4007
+ tileCacheBytes: this.options.streaming.tileCacheBytes ?? 192 * 1024 * 1024,
3852
4008
  mapMemory: this.options.streaming.mapMemory ?? 64
3853
4009
  };
3854
4010
  }
@@ -2,8 +2,8 @@ import * as react from 'react';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
3
  import { l as WorldSource, B as BiomeEntry } from '../biome-B6l-1yx4.js';
4
4
  export { D as DecodedTile } from '../biome-B6l-1yx4.js';
5
- import { g as TileSource, T as TextureSource, S as StreamingSettings, k as ViewMode, L as LightSettings, a as DisplaySettings, d as TileInfo, i as VantageViewer$1 } from '../viewer-DkGKQozr.js';
6
- export { D as DEFAULT_ORBIT_ANGLE, V as VANILLA_DISPLAY } from '../viewer-DkGKQozr.js';
5
+ import { g as TileSource, T as TextureSource, S as StreamingSettings, k as ViewMode, L as LightSettings, a as DisplaySettings, d as TileInfo, i as VantageViewer$1 } from '../viewer-BgXAqYhr.js';
6
+ export { D as DEFAULT_ORBIT_ANGLE, V as VANILLA_DISPLAY } from '../viewer-BgXAqYhr.js';
7
7
  import 'three';
8
8
 
9
9
  interface VantageViewerProps {
@@ -1,5 +1,5 @@
1
- import { VantageViewer, DEFAULT_ORBIT_ANGLE } from '../chunk-GGTVSB7H.js';
2
- export { DEFAULT_ORBIT_ANGLE, VANILLA_DISPLAY } from '../chunk-GGTVSB7H.js';
1
+ import { VantageViewer, DEFAULT_ORBIT_ANGLE } from '../chunk-E7Y7K6NH.js';
2
+ export { DEFAULT_ORBIT_ANGLE, VANILLA_DISPLAY } from '../chunk-E7Y7K6NH.js';
3
3
  import '../chunk-LZCXJU4U.js';
4
4
  import { createContext, forwardRef, useRef, useState, useImperativeHandle, useEffect, useMemo, useContext } from 'react';
5
5
  import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
@@ -377,7 +377,7 @@ var VantageViewer2 = forwardRef(function VantageViewer3(props, ref) {
377
377
  }, [engine, display?.sharpness, display?.ao, display?.saturation, display?.contrast, display?.fog, display?.renderScale]);
378
378
  useEffect(() => {
379
379
  if (engine && streaming) engine.setStreaming(streaming);
380
- }, [engine, streaming?.viewDistance, streaming?.maxTiles, streaming?.concurrency, streaming?.maxBytes]);
380
+ }, [engine, streaming?.viewDistance, streaming?.maxTiles, streaming?.concurrency, streaming?.maxBytes, streaming?.tileCacheBytes, streaming?.mapMemory]);
381
381
  const ctx = useMemo(
382
382
  () => ({
383
383
  viewer: engine,
@@ -3,7 +3,7 @@ import { R as Rgb, Q as QuantizedTile, D as DecodedTile, a as DecodedTextureArra
3
3
  export { B as BiomeEntry, b as ByteReader, H as HttpWorldOptions, L as Lightmap, c as LowresLevel, M as ManifestTile, d as MeshSection, e as QuantizedSection, T as TEXTURE_MAGIC, f as TILE_MAGIC, g as TextureAnimation, h as TileMagic, U as UV_SCALE, V as VantageServerOptions, W as WorldConditionalFetch, i as WorldFetch, j as WorldHttpFetch, k as WorldManifest, l as WorldSource, m as biomePalette, n as canonicalQuadIndices, p as parseManifest, o as parseTextureArray, q as parseTile, r as parseTileQuantized, s as stripNamespace, t as summarizeBiomes, u as summarizeSurfaceBiomes, v as tileKey, w as worldFromDirectory, x as worldFromFiles, y as worldFromHttp, z as worldFromUrl, A as worldFromVantageServer } from '../biome-B6l-1yx4.js';
4
4
  import { LowresTile } from '../core/index.js';
5
5
  export { LOWRES_EMPTY, LOWRES_MAGIC, isGzip, maybeInflate, parseLowresTile } from '../core/index.js';
6
- export { D as DEFAULT_ORBIT_ANGLE, a as DisplaySettings, H as HeightSampler, L as LightSettings, b as LoadOptions, M as MapControls, c as MapControlsOptions, S as StreamingSettings, T as TextureSource, d as TileInfo, e as TileManager, f as TileManagerOptions, g as TileSource, h as TileStats, V as VANILLA_DISPLAY, i as VantageViewer, j as VantageViewerOptions, k as ViewMode } from '../viewer-DkGKQozr.js';
6
+ export { D as DEFAULT_ORBIT_ANGLE, a as DisplaySettings, H as HeightSampler, L as LightSettings, b as LoadOptions, M as MapControls, c as MapControlsOptions, S as StreamingSettings, T as TextureSource, d as TileInfo, e as TileManager, f as TileManagerOptions, g as TileSource, h as TileStats, V as VANILLA_DISPLAY, i as VantageViewer, j as VantageViewerOptions, k as ViewMode } from '../viewer-BgXAqYhr.js';
7
7
 
8
8
  /** The objects and metadata produced from a tile. */
9
9
  interface TerrainObjects {
@@ -1,2 +1,2 @@
1
- export { DEFAULT_ORBIT_ANGLE, MapControls, SKY_HORIZON, SKY_TOP, TileManager, VANILLA_DISPLAY, VantageViewer, applyCaveRange, buildLowresMesh, buildQuantizedTileMeshes, buildTerrain, buildTileMeshes, createLowresMaterial, createSky, createTerrainMaterial, createWaterMaterial, pickBiome } from '../chunk-GGTVSB7H.js';
1
+ export { DEFAULT_ORBIT_ANGLE, MapControls, SKY_HORIZON, SKY_TOP, TileManager, VANILLA_DISPLAY, VantageViewer, applyCaveRange, buildLowresMesh, buildQuantizedTileMeshes, buildTerrain, buildTileMeshes, createLowresMaterial, createSky, createTerrainMaterial, createWaterMaterial, pickBiome } from '../chunk-E7Y7K6NH.js';
2
2
  export { ByteReader, LOWRES_EMPTY, LOWRES_MAGIC, TEXTURE_MAGIC, TILE_MAGIC, UV_SCALE, biomePalette, canonicalQuadIndices, isGzip, maybeInflate, parseLowresTile, parseManifest, parseTextureArray, parseTile, parseTileQuantized, stripNamespace, summarizeBiomes, summarizeSurfaceBiomes, tileKey, worldFromDirectory, worldFromFiles, worldFromHttp, worldFromUrl, worldFromVantageServer } from '../chunk-LZCXJU4U.js';
@@ -24,12 +24,19 @@ interface TileManagerOptions {
24
24
  /** Hard cap on resident tiles (nearest win). Default `120` (fills the
25
25
  * default view-distance disc; matches the settings panel's "med" preset). */
26
26
  maxTiles?: number;
27
- /** Concurrent tile fetches. Default `4`. */
27
+ /** Concurrent tile fetches. Default `6` — enough to keep an on-demand
28
+ * server's bake slots saturated while staying within a browser's
29
+ * per-origin HTTP/1.1 connection budget. */
28
30
  concurrency?: number;
29
31
  /** Estimated CPU/GPU residency budget in bytes. Unlike `maxTiles`, this
30
32
  * accounts for large and small tiles having very different geometry. One
31
33
  * nearest oversized tile is allowed for forward progress. Default `512 MiB`. */
32
34
  maxBytes?: number;
35
+ /** Budget for evicted tiles' compressed payloads, in bytes. Tiles leaving
36
+ * the streaming ring keep their fetched bytes here so panning back
37
+ * rebuilds them without a network round-trip (or an on-demand server
38
+ * re-bake). `0` disables. Default `192 MiB` (~400 typical tiles). */
39
+ tileCacheBytes?: number;
33
40
  /** Live/on-demand renders grow the shared texture atlas in viewport order, so
34
41
  * a fetched tile can reference layers the atlas doesn't have yet. When set,
35
42
  * the manager widens the atlas (awaiting this) before building a tile that
@@ -68,6 +75,8 @@ interface TileStats {
68
75
  bytes: number;
69
76
  /** Estimated CPU/GPU bytes held by resident and upload-pending resources. */
70
77
  residentBytes: number;
78
+ /** Compressed payloads retained for instant revisits (the tile byte cache). */
79
+ cachedBytes: number;
71
80
  }
72
81
  interface TileEvents extends Record<string, unknown> {
73
82
  /** A tile finished loading or was unloaded; payload = live stats. */
@@ -118,6 +127,15 @@ declare class TileManager {
118
127
  /** Learned tile weights survive eviction and make future admission byte-aware. */
119
128
  private readonly sizeHints;
120
129
  private averageHiresBytes;
130
+ /** Distance² where the last plan ran out of budget (null = nothing cut).
131
+ * Derives {@link admittedRadius} — the honest hires frontier. */
132
+ private planCutoffSq;
133
+ /** When the last plan ran, so byte-estimate learning re-plans at a bounded
134
+ * rate instead of once per tile load. */
135
+ private lastPlanMs;
136
+ /** Compressed tile payloads kept after eviction. A revisit rebuilds from
137
+ * here — no network fetch, no server re-bake. */
138
+ private readonly byteCache;
121
139
  /** Whether resident tiles draw their cave-dark tails (VTLA). The viewer's
122
140
  * cave policy toggles this off while the camera is above ground with the
123
141
  * depth slice closed. */
@@ -133,8 +151,12 @@ declare class TileManager {
133
151
  /** Surface map of a fully-streamed resident hires tile (the impostor layer
134
152
  * stitches remembered rims onto live terrain with it). */
135
153
  private readonly readySurface;
136
- /** Keep the impostor haze floor tracking the guaranteed-hires radius (the
137
- * view distance, unless the tile budget's disc runs out first). */
154
+ /** The radius hires tiles are actually resident to: the view distance,
155
+ * capped by whichever budget ran out first — the tile-count disc, or the
156
+ * byte budget's cut in the last admission plan. The viewer sizes fog and
157
+ * zoom off this so the frontier always reads as haze, never a cliff. */
158
+ get admittedRadius(): number;
159
+ /** Keep the impostor haze floor tracking the guaranteed-hires radius. */
138
160
  private applyHazeFloor;
139
161
  /** Tile span in blocks at a pyramid level (0 = hires). */
140
162
  private levelBlocks;
@@ -150,6 +172,9 @@ declare class TileManager {
150
172
  */
151
173
  update(focusX: number, focusZ: number): void;
152
174
  private pump;
175
+ /** Whether anything already draws terrain under hires tile (x,z) — a
176
+ * remembered/queued impostor, or a resident lowres ring covering it. */
177
+ private hasUnderlay;
153
178
  /** Insert built tiles into the scene at a bounded per-frame rate (via
154
179
  * update()), so GPU buffer uploads are spread across frames instead of
155
180
  * bursting. Normally one per frame; when a backlog builds (a big preset
@@ -213,6 +238,7 @@ declare class TileManager {
213
238
  maxTiles?: number;
214
239
  concurrency?: number;
215
240
  maxBytes?: number;
241
+ tileCacheBytes?: number;
216
242
  mapMemory?: number;
217
243
  }): void;
218
244
  /** The active map-memory impostor resolution (0 = off/unavailable). */
@@ -508,10 +534,15 @@ interface StreamingSettings {
508
534
  viewDistance?: number;
509
535
  /** Hard cap on resident tiles (nearest win). Default `120`. */
510
536
  maxTiles?: number;
511
- /** Concurrent tile fetches. Default `4`. */
537
+ /** Concurrent tile fetches. Default `6`. */
512
538
  concurrency?: number;
513
539
  /** Estimated CPU/GPU tile residency budget, in bytes. Default `512 MiB`. */
514
540
  maxBytes?: number;
541
+ /** Budget for evicted tiles' compressed payloads, in bytes — panning back
542
+ * over explored terrain rebuilds tiles from this cache instead of
543
+ * re-fetching (and, on an on-demand server, re-baking) them. `0` turns it
544
+ * off. Default `192 MiB`. */
545
+ tileCacheBytes?: number;
515
546
  /** Map memory for worlds WITHOUT a baked lowres pyramid (live bakes,
516
547
  * `vantage server`): tiles leaving the streaming ring are snapshotted
517
548
  * top-down and persist as cheap textured impostors, so everywhere the
@@ -713,8 +744,9 @@ declare class VantageViewer {
713
744
  * a 100k×100k world frames the same as a village. */
714
745
  private frameWorld;
715
746
  /** The radius hires tiles are actually guaranteed resident to: the view
716
- * distance, unless the tile budget runs out first (nearest-first fill ⇒ a
717
- * disc of maxTiles tiles ⇒ radius tb·√(maxTiles/π)). */
747
+ * distance, unless a budget runs out first. The manager reports its honest
748
+ * frontier (tile count AND byte budget), so fog hugs where data really
749
+ * stops — a budget cut reads as distance haze, not a cliff into the sky. */
718
750
  private streamRadius;
719
751
  /** Zoom range, far plane, and fog for a streamed world.
720
752
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thoughts-on-things/vantage-mc",
3
- "version": "0.8.0",
3
+ "version": "0.9.1",
4
4
  "description": "Render a Minecraft (Java) world as a fast, beautiful 3D web map. The web frontend for the Vantage generator.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -82,7 +82,7 @@
82
82
  "@types/node": "^26.1.1",
83
83
  "@types/react": "^19.0.0",
84
84
  "@types/react-dom": "^19.0.0",
85
- "@types/three": "^0.160.0",
85
+ "@types/three": "^0.185.1",
86
86
  "@vitejs/plugin-react": "^6.0.2",
87
87
  "react": "^19.0.0",
88
88
  "react-dom": "^19.0.0",