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

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.
@@ -21,7 +21,12 @@ var TILE_MAGIC = {
21
21
  VTL8: "VTL8",
22
22
  /** VTL8 geometry + a losslessly packed RG8 lightmap (sky/block nibbles,
23
23
  * full-byte AO), stored as gzip-friendly planes. */
24
- VTL9: "VTL9"
24
+ VTL9: "VTL9",
25
+ /** VTL9 + the cave partition: cave-dark quads (faces only sky-light-0,
26
+ * non-water cells can see) sit at the END of each lighting segment, with
27
+ * the boundaries in the section header — a viewer can draw a surface-only
28
+ * prefix while the camera is above ground. ("A" = 10.) */
29
+ VTLA: "VTLA"
25
30
  };
26
31
  var UV_SCALE = 128;
27
32
  var TEXTURE_MAGIC = "VTA1";
@@ -252,9 +257,21 @@ function readCompactSectionRaw(r) {
252
257
  indices: null
253
258
  };
254
259
  }
255
- function readLitSectionRaw(r) {
260
+ function readLitSectionRaw(r, withCave) {
256
261
  const vertexCount = r.u32();
257
262
  const lmStart = r.u32();
263
+ const caveStart = withCave ? r.u32() : void 0;
264
+ const caveLmStart = withCave ? r.u32() : void 0;
265
+ if (vertexCount % 4 !== 0 || lmStart % 4 !== 0 || lmStart > vertexCount) {
266
+ throw new Error(`vantage: corrupt lit section header (V=${vertexCount}, lmStart=${lmStart})`);
267
+ }
268
+ if (caveStart !== void 0 && caveLmStart !== void 0) {
269
+ if (caveStart % 4 !== 0 || caveLmStart % 4 !== 0 || caveStart > lmStart || caveLmStart < lmStart || caveLmStart > vertexCount) {
270
+ throw new Error(
271
+ `vantage: corrupt VTLA cave boundaries (V=${vertexCount}, lmStart=${lmStart}, caveStart=${caveStart}, caveLmStart=${caveLmStart})`
272
+ );
273
+ }
274
+ }
258
275
  const uv = r.i16a(2 * vertexCount);
259
276
  const colors = r.u8a(4 * vertexCount);
260
277
  const normals = r.i8a(4 * vertexCount);
@@ -280,7 +297,8 @@ function readLitSectionRaw(r) {
280
297
  biome,
281
298
  indices: null,
282
299
  lmStart,
283
- lmuv
300
+ lmuv,
301
+ ...caveStart !== void 0 ? { caveStart, caveLmStart } : {}
284
302
  };
285
303
  }
286
304
  function readLightmap(r) {
@@ -370,13 +388,13 @@ function bakeVertexLight(sec, lm) {
370
388
  function parseTileQuantized(buffer) {
371
389
  const r = new ByteReader(buffer);
372
390
  const magic = r.magic();
373
- if (magic !== TILE_MAGIC.VTL6 && magic !== TILE_MAGIC.VTL7 && magic !== TILE_MAGIC.VTL8 && magic !== TILE_MAGIC.VTL9) return null;
391
+ if (magic !== TILE_MAGIC.VTL6 && magic !== TILE_MAGIC.VTL7 && magic !== TILE_MAGIC.VTL8 && magic !== TILE_MAGIC.VTL9 && magic !== TILE_MAGIC.VTLA) return null;
374
392
  r.off = 4;
375
393
  const version = r.u32();
376
- const readSection = magic === TILE_MAGIC.VTL8 || magic === TILE_MAGIC.VTL9 ? readLitSectionRaw : magic === TILE_MAGIC.VTL7 ? readCompactSectionRaw : readQuantizedSectionRaw;
394
+ const readSection = magic === TILE_MAGIC.VTL8 || magic === TILE_MAGIC.VTL9 || magic === TILE_MAGIC.VTLA ? (reader) => readLitSectionRaw(reader, magic === TILE_MAGIC.VTLA) : magic === TILE_MAGIC.VTL7 ? readCompactSectionRaw : readQuantizedSectionRaw;
377
395
  const solid = readSection(r);
378
396
  const fluid = readSection(r);
379
- const lightmap = magic === TILE_MAGIC.VTL9 ? readPackedLightmap(r) : magic === TILE_MAGIC.VTL8 ? readLightmap(r) : void 0;
397
+ const lightmap = magic === TILE_MAGIC.VTL9 || magic === TILE_MAGIC.VTLA ? readPackedLightmap(r) : magic === TILE_MAGIC.VTL8 ? readLightmap(r) : void 0;
380
398
  const surface = readSurface(r);
381
399
  const biomeNames = readLegend(r);
382
400
  return { magic, version, solid, fluid, surface, biomeNames, ...lightmap ? { lightmap } : {} };
@@ -406,10 +424,11 @@ function parseTile(buffer) {
406
424
  const magic = r.magic();
407
425
  r.off = 4;
408
426
  const version = r.u32();
409
- if (magic === TILE_MAGIC.VTL8 || magic === TILE_MAGIC.VTL9) {
410
- const solid = expandSection(readLitSectionRaw(r));
411
- const fluid = expandSection(readLitSectionRaw(r));
412
- const lightmap = magic === TILE_MAGIC.VTL9 ? readPackedLightmap(r) : readLightmap(r);
427
+ if (magic === TILE_MAGIC.VTL8 || magic === TILE_MAGIC.VTL9 || magic === TILE_MAGIC.VTLA) {
428
+ const withCave = magic === TILE_MAGIC.VTLA;
429
+ const solid = expandSection(readLitSectionRaw(r, withCave));
430
+ const fluid = expandSection(readLitSectionRaw(r, withCave));
431
+ const lightmap = magic === TILE_MAGIC.VTL8 ? readLightmap(r) : readPackedLightmap(r);
413
432
  if (lightmap) bakeVertexLight(solid, lightmap);
414
433
  const surface = readSurface(r);
415
434
  const biomeNames = readLegend(r);
@@ -493,7 +512,7 @@ function parseTile(buffer) {
493
512
  indices
494
513
  };
495
514
  }
496
- throw new Error(`vantage: unrecognized tile magic "${magic}" (expected VTL1\u2013VTL7)`);
515
+ throw new Error(`vantage: unrecognized tile magic "${magic}" (expected VTL1\u2013VTLA)`);
497
516
  }
498
517
 
499
518
  // src/core/texture.ts
@@ -532,8 +551,8 @@ function parseManifest(data) {
532
551
  if (typeof data !== "object" || data === null) throw new Error("vantage: manifest is not an object");
533
552
  const m = data;
534
553
  const format = m["format"];
535
- if (format !== 1 && format !== 2 && format !== 3 && format !== 4 && format !== 5) {
536
- throw new Error(`vantage: unsupported manifest format ${String(format)} (expected 1..5)`);
554
+ if (format !== 1 && format !== 2 && format !== 3 && format !== 4 && format !== 5 && format !== 6) {
555
+ throw new Error(`vantage: unsupported manifest format ${String(format)} (expected 1..6)`);
537
556
  }
538
557
  const tileChunks = m["tileChunks"];
539
558
  const tileBlocks = m["tileBlocks"];
@@ -552,7 +571,17 @@ function parseManifest(data) {
552
571
  if (typeof o !== "object" || o === null || typeof o["x"] !== "number" || typeof o["z"] !== "number" || typeof o["path"] !== "string" || typeof o["bytes"] !== "number") {
553
572
  throw new Error(`vantage: manifest ${what} ${i} is malformed`);
554
573
  }
555
- return { x: o["x"], z: o["z"], path: o["path"], bytes: o["bytes"] };
574
+ const revision = o["revision"];
575
+ if (revision !== void 0 && (typeof revision !== "string" || revision.length === 0 || revision.length > 128)) {
576
+ throw new Error(`vantage: manifest ${what} ${i} has an invalid revision`);
577
+ }
578
+ return {
579
+ x: o["x"],
580
+ z: o["z"],
581
+ path: o["path"],
582
+ bytes: o["bytes"],
583
+ ...typeof revision === "string" ? { revision } : {}
584
+ };
556
585
  });
557
586
  const parsedTiles = parseTiles(tiles, "tile");
558
587
  let lowres;
@@ -619,22 +648,86 @@ function throwIfAborted(signal) {
619
648
  function normalizePath(path) {
620
649
  return path.startsWith("./") ? path.slice(2) : path;
621
650
  }
651
+ function safeRemotePath(path) {
652
+ const normalized = normalizePath(path);
653
+ if (normalized.length === 0 || normalized.length > 512 || !/^[A-Za-z0-9._/-]+$/.test(normalized)) {
654
+ throw new Error(`vantage: unsafe remote artifact path ${path}`);
655
+ }
656
+ const segments = normalized.split("/");
657
+ if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
658
+ throw new Error(`vantage: unsafe remote artifact path ${path}`);
659
+ }
660
+ return normalized;
661
+ }
622
662
  async function worldFromUrl(url, base) {
623
- const abs = new URL(url, base ?? (typeof document !== "undefined" ? document.baseURI : void 0)).toString();
624
- const res = await fetch(abs);
663
+ return worldFromHttp(url, { base });
664
+ }
665
+ async function worldFromHttp(url, options = {}) {
666
+ const abs = new URL(
667
+ url,
668
+ options.base ?? (typeof document !== "undefined" ? document.baseURI : void 0)
669
+ ).toString();
670
+ const manifestUrl = new URL(abs);
671
+ if (manifestUrl.protocol !== "http:" && manifestUrl.protocol !== "https:") {
672
+ throw new Error(`vantage: HTTP world requires an http(s) manifest URL`);
673
+ }
674
+ if (manifestUrl.username || manifestUrl.password) {
675
+ throw new Error(`vantage: HTTP world credentials belong in headers, not the manifest URL`);
676
+ }
677
+ const root = new URL(".", manifestUrl);
678
+ const http = options.fetch ?? ((input, init) => fetch(input, init));
679
+ const headers = {};
680
+ for (const [name, value] of Object.entries(options.headers ?? {})) headers[name.toLowerCase()] = value;
681
+ if (options.accessToken) headers["authorization"] = `Bearer ${options.accessToken}`;
682
+ const request = (target, signal, extra) => http(target, {
683
+ ...Object.keys(headers).length > 0 || extra ? { headers: { ...headers, ...extra } } : {},
684
+ ...signal ? { signal } : {}
685
+ });
686
+ const resolveTarget = (path) => {
687
+ const targetUrl = new URL(safeRemotePath(path), root);
688
+ if (targetUrl.origin !== root.origin || !targetUrl.pathname.startsWith(root.pathname)) {
689
+ throw new Error(`vantage: unsafe remote artifact path ${path}`);
690
+ }
691
+ return targetUrl.toString();
692
+ };
693
+ const res = await request(abs);
625
694
  if (!res.ok) throw new Error(`${res.status} ${res.statusText} for ${abs}`);
626
695
  const manifest = await res.json();
627
696
  return {
628
697
  manifest,
629
- label: abs,
698
+ label: options.label ?? abs,
630
699
  fetch: async (path, signal) => {
631
- const target = new URL(normalizePath(path), abs).toString();
632
- const r = await fetch(target, signal ? { signal } : void 0);
700
+ const target = resolveTarget(path);
701
+ const r = await request(target, signal);
633
702
  if (!r.ok) throw new Error(`${r.status} ${r.statusText} for ${target}`);
634
703
  return r.arrayBuffer();
704
+ },
705
+ fetchConditional: async (path, etag, signal) => {
706
+ const target = resolveTarget(path);
707
+ const r = await request(target, signal, etag ? { "if-none-match": etag } : void 0);
708
+ if (r.status === 304) return "unchanged";
709
+ if (!r.ok) throw new Error(`${r.status} ${r.statusText} for ${target}`);
710
+ const next = r.headers.get("etag");
711
+ return { buffer: await r.arrayBuffer(), ...next ? { etag: next } : {} };
635
712
  }
636
713
  };
637
714
  }
715
+ function worldFromVantageServer(endpoint, options = {}) {
716
+ const worldId = options.worldId ?? "default";
717
+ if (!/^[A-Za-z0-9_-]{1,64}$/.test(worldId)) throw new Error(`vantage: invalid server world id`);
718
+ const base = new URL(endpoint);
719
+ if (base.protocol !== "http:" && base.protocol !== "https:") {
720
+ throw new Error(`vantage: server endpoint must use http(s)`);
721
+ }
722
+ if (base.username || base.password) {
723
+ throw new Error(`vantage: server credentials belong in headers, not the endpoint URL`);
724
+ }
725
+ base.pathname = base.pathname.endsWith("/") ? base.pathname : `${base.pathname}/`;
726
+ base.search = "";
727
+ base.hash = "";
728
+ const manifest = new URL(`v1/worlds/${encodeURIComponent(worldId)}/manifest.json`, base).toString();
729
+ return worldFromHttp(manifest, options);
730
+ }
638
731
  async function worldFromDirectory(dir) {
639
732
  const readFile = async (path, signal) => {
640
733
  throwIfAborted(signal);
@@ -810,4 +903,4 @@ function summarizeBiomes(tile, palette) {
810
903
  return toEntries(counts, names, pal);
811
904
  }
812
905
 
813
- 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, worldFromUrl };
906
+ 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 };
@@ -1,4 +1,4 @@
1
- export { B as BiomeEntry, b as ByteReader, a as DecodedTextureArray, D as DecodedTile, L as Lightmap, c as LowresLevel, M as ManifestTile, d as MeshSection, e as QuantizedSection, Q as QuantizedTile, R as Rgb, S as SurfaceMap, T as TEXTURE_MAGIC, f as TILE_MAGIC, g as TextureAnimation, h as TileMagic, U as UV_SCALE, W as WorldFetch, i as WorldManifest, j as WorldSource, k as biomePalette, l as canonicalQuadIndices, p as parseManifest, m as parseTextureArray, n as parseTile, o as parseTileQuantized, s as stripNamespace, q as summarizeBiomes, r as summarizeSurfaceBiomes, t as tileKey, w as worldFromDirectory, u as worldFromFiles, v as worldFromUrl } from '../biome-NBWIY7dT.js';
1
+ export { B as BiomeEntry, b as ByteReader, a as DecodedTextureArray, D as DecodedTile, H as HttpWorldOptions, L as Lightmap, c as LowresLevel, M as ManifestTile, d as MeshSection, e as QuantizedSection, Q as QuantizedTile, R as Rgb, S as SurfaceMap, 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';
2
2
 
3
3
  declare const LOWRES_MAGIC = "VLR1";
4
4
  /** Height sentinel for samples with no terrain (unpopulated chunks). */
@@ -1 +1 @@
1
- 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, worldFromUrl } from '../chunk-EVPUXVSB.js';
1
+ 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';
@@ -1,9 +1,9 @@
1
1
  import * as react from 'react';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
- import { j as WorldSource, B as BiomeEntry } from '../biome-NBWIY7dT.js';
4
- export { D as DecodedTile } from '../biome-NBWIY7dT.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-C5vYxrL1.js';
6
- export { D as DEFAULT_ORBIT_ANGLE, V as VANILLA_DISPLAY } from '../viewer-C5vYxrL1.js';
3
+ import { l as WorldSource, B as BiomeEntry } from '../biome-B6l-1yx4.js';
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';
7
7
  import 'three';
8
8
 
9
9
  interface VantageViewerProps {
@@ -104,15 +104,17 @@ interface SettingsPanelProps {
104
104
  defaultCollapsed?: boolean;
105
105
  className?: string;
106
106
  }
107
- /** A quality preset: streamed range, resident-tile budget, and render scale.
108
- * Tile budgets are sized to fill the view-distance disc (π·(vd/tileBlocks)²
109
- * for 128-block tiles) so the range is actually reachable. */
107
+ /** A quality preset: streamed range, resident-tile budget, render scale, and
108
+ * map-memory snapshot resolution. Tile budgets are sized to fill the
109
+ * view-distance disc (π·(vd/tileBlocks)² for 128-block tiles) so the range
110
+ * is actually reachable. */
110
111
  interface QualityPreset {
111
112
  name: string;
112
113
  viewDistance: number;
113
114
  maxTiles: number;
114
115
  maxBytes: number;
115
116
  renderScale: number;
117
+ mapMemory: number;
116
118
  }
117
119
  declare const QUALITY_PRESETS: QualityPreset[];
118
120
  declare function SettingsPanel({ title, defaultCollapsed, className }: SettingsPanelProps): react.JSX.Element | null;
@@ -1,6 +1,6 @@
1
- import { VantageViewer, DEFAULT_ORBIT_ANGLE } from '../chunk-46RBFJ4D.js';
2
- export { DEFAULT_ORBIT_ANGLE, VANILLA_DISPLAY } from '../chunk-46RBFJ4D.js';
3
- import '../chunk-EVPUXVSB.js';
1
+ import { VantageViewer, DEFAULT_ORBIT_ANGLE } from '../chunk-GGTVSB7H.js';
2
+ export { DEFAULT_ORBIT_ANGLE, VANILLA_DISPLAY } from '../chunk-GGTVSB7H.js';
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';
6
6
 
@@ -576,40 +576,43 @@ function LightPanel({ title = "lighting", defaultCollapsed = true, className })
576
576
  }
577
577
  var MiB = 1024 * 1024;
578
578
  var QUALITY_PRESETS = [
579
- { name: "low", viewDistance: 448, maxTiles: 44, maxBytes: 320 * MiB, renderScale: 0.75 },
580
- { name: "med", viewDistance: 768, maxTiles: 120, maxBytes: 512 * MiB, renderScale: 1 },
581
- { name: "high", viewDistance: 1152, maxTiles: 264, maxBytes: 768 * MiB, renderScale: 1 },
582
- { name: "ultra", viewDistance: 1408, maxTiles: 400, maxBytes: 1024 * MiB, renderScale: 1 }
579
+ { name: "low", viewDistance: 448, maxTiles: 44, maxBytes: 320 * MiB, renderScale: 0.75, mapMemory: 32 },
580
+ { name: "med", viewDistance: 768, maxTiles: 120, maxBytes: 512 * MiB, renderScale: 1, mapMemory: 64 },
581
+ { name: "high", viewDistance: 1152, maxTiles: 264, maxBytes: 768 * MiB, renderScale: 1, mapMemory: 128 },
582
+ { name: "ultra", viewDistance: 1408, maxTiles: 400, maxBytes: 1024 * MiB, renderScale: 1, mapMemory: 128 }
583
583
  ];
584
584
  function SettingsPanel({ title = "quality", defaultCollapsed = true, className }) {
585
585
  const { viewer } = useVantage();
586
- const [k, setK] = useState({ viewDistance: 768, maxTiles: 120, maxBytes: 512 * MiB, renderScale: 1, fog: 1 });
586
+ const [k, setK] = useState({ viewDistance: 768, maxTiles: 120, maxBytes: 512 * MiB, renderScale: 1, fog: 1, mapMemory: 64 });
587
587
  useEffect(() => {
588
588
  if (!viewer) return;
589
589
  const s = viewer.streamingSettings;
590
590
  const d = viewer.displaySettings;
591
- setK({ viewDistance: s.viewDistance, maxTiles: s.maxTiles, maxBytes: s.maxBytes, renderScale: d.renderScale, fog: d.fog });
591
+ setK({ viewDistance: s.viewDistance, maxTiles: s.maxTiles, maxBytes: s.maxBytes, renderScale: d.renderScale, fog: d.fog, mapMemory: s.mapMemory });
592
592
  }, [viewer]);
593
593
  if (!viewer) return null;
594
594
  const apply = (next) => {
595
595
  const merged = { ...k, ...next };
596
596
  setK(merged);
597
- if (next.viewDistance !== void 0 || next.maxTiles !== void 0 || next.maxBytes !== void 0) {
598
- viewer.setStreaming({ viewDistance: merged.viewDistance, maxTiles: merged.maxTiles, maxBytes: merged.maxBytes });
597
+ if (next.viewDistance !== void 0 || next.maxTiles !== void 0 || next.maxBytes !== void 0 || next.mapMemory !== void 0) {
598
+ viewer.setStreaming({ viewDistance: merged.viewDistance, maxTiles: merged.maxTiles, maxBytes: merged.maxBytes, mapMemory: merged.mapMemory });
599
599
  }
600
600
  if (next.renderScale !== void 0 || next.fog !== void 0) {
601
601
  viewer.setDisplay({ renderScale: merged.renderScale, fog: merged.fog });
602
602
  }
603
603
  };
604
604
  const active = QUALITY_PRESETS.find(
605
- (p) => p.viewDistance === k.viewDistance && p.maxTiles === k.maxTiles && p.maxBytes === k.maxBytes && p.renderScale === k.renderScale
605
+ (p) => p.viewDistance === k.viewDistance && p.maxTiles === k.maxTiles && p.maxBytes === k.maxBytes && p.renderScale === k.renderScale && p.mapMemory === k.mapMemory
606
606
  );
607
607
  const SLIDERS = [
608
608
  { key: "viewDistance", label: "view distance", min: 256, max: 2048, step: 64, fmt: (v) => `${v}m` },
609
609
  { key: "maxTiles", label: "tile budget", min: 24, max: 512, step: 8, fmt: (v) => `${v}` },
610
610
  { key: "maxBytes", label: "memory budget", min: 128 * MiB, max: 1536 * MiB, step: 64 * MiB, fmt: (v) => `${Math.round(v / MiB)} MiB` },
611
611
  { key: "renderScale", label: "render scale", min: 0.5, max: 2, step: 0.05, fmt: (v) => `${v.toFixed(2)}\xD7` },
612
- { key: "fog", label: "haze", min: 0, max: 1, step: 0.05, fmt: (v) => v.toFixed(2) }
612
+ { key: "fog", label: "haze", min: 0, max: 1, step: 0.05, fmt: (v) => v.toFixed(2) },
613
+ // Snapshot resolution for remembered (evicted) tiles on pyramid-less
614
+ // streamed worlds — see StreamingSettings.mapMemory.
615
+ { key: "mapMemory", label: "map memory", min: 0, max: 128, step: 32, fmt: (v) => v === 0 ? "off" : `${v}px` }
613
616
  ];
614
617
  return /* @__PURE__ */ jsx(
615
618
  Panel,
@@ -624,7 +627,7 @@ function SettingsPanel({ title = "quality", defaultCollapsed = true, className }
624
627
  "button",
625
628
  {
626
629
  className: active?.name === p.name ? "vtg-seg-on" : void 0,
627
- onClick: () => apply({ viewDistance: p.viewDistance, maxTiles: p.maxTiles, maxBytes: p.maxBytes, renderScale: p.renderScale }),
630
+ onClick: () => apply({ viewDistance: p.viewDistance, maxTiles: p.maxTiles, maxBytes: p.maxBytes, renderScale: p.renderScale, mapMemory: p.mapMemory }),
628
631
  children: p.name
629
632
  },
630
633
  p.name
@@ -1,9 +1,9 @@
1
1
  import * as THREE from 'three';
2
- import { R as Rgb, Q as QuantizedTile, D as DecodedTile, a as DecodedTextureArray, S as SurfaceMap } from '../biome-NBWIY7dT.js';
3
- export { B as BiomeEntry, b as ByteReader, 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, W as WorldFetch, i as WorldManifest, j as WorldSource, k as biomePalette, l as canonicalQuadIndices, p as parseManifest, m as parseTextureArray, n as parseTile, o as parseTileQuantized, s as stripNamespace, q as summarizeBiomes, r as summarizeSurfaceBiomes, t as tileKey, w as worldFromDirectory, u as worldFromFiles, v as worldFromUrl } from '../biome-NBWIY7dT.js';
2
+ import { R as Rgb, Q as QuantizedTile, D as DecodedTile, a as DecodedTextureArray, S as SurfaceMap } from '../biome-B6l-1yx4.js';
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-C5vYxrL1.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';
7
7
 
8
8
  /** The objects and metadata produced from a tile. */
9
9
  interface TerrainObjects {
@@ -41,6 +41,10 @@ interface TileMeshes {
41
41
  * its own materials, use {@link buildTerrain}.
42
42
  */
43
43
  declare function buildTileMeshes(tile: DecodedTile, palette: Rgb[], material: THREE.ShaderMaterial, waterMaterial: THREE.ShaderMaterial): TileMeshes;
44
+ /** Point a tagged mesh's draw range at its full geometry or its surface-only
45
+ * prefix. Draw-range state only — no buffers move, no draw calls are added;
46
+ * hiding a tile's cave tail just makes its one draw shorter. */
47
+ declare function applyCaveRange(mesh: THREE.Mesh | undefined, showCaves: boolean): void;
44
48
  /**
45
49
  * Build a VTL6+ tile's meshes in the quantized fast path: shared QUANTIZED
46
50
  * materials (from `createTerrainMaterial(tex, { quantized: true, palette })`),
@@ -116,4 +120,4 @@ declare function createSky(): THREE.Mesh;
116
120
  */
117
121
  declare function pickBiome(ray: THREE.Ray, surf: SurfaceMap, bounds: THREE.Box3): number;
118
122
 
119
- export { DecodedTextureArray, DecodedTile, LowresTile, QuantizedTile, Rgb, SKY_HORIZON, SKY_TOP, SurfaceMap, type TerrainMaterialOptions, type TerrainObjects, type TileMeshes, buildLowresMesh, buildQuantizedTileMeshes, buildTerrain, buildTileMeshes, createLowresMaterial, createSky, createTerrainMaterial, createWaterMaterial, pickBiome };
123
+ export { DecodedTextureArray, DecodedTile, LowresTile, QuantizedTile, Rgb, SKY_HORIZON, SKY_TOP, SurfaceMap, type TerrainMaterialOptions, type TerrainObjects, type TileMeshes, applyCaveRange, buildLowresMesh, buildQuantizedTileMeshes, buildTerrain, buildTileMeshes, createLowresMaterial, createSky, createTerrainMaterial, createWaterMaterial, pickBiome };
@@ -1,2 +1,2 @@
1
- export { DEFAULT_ORBIT_ANGLE, MapControls, SKY_HORIZON, SKY_TOP, TileManager, VANILLA_DISPLAY, VantageViewer, buildLowresMesh, buildQuantizedTileMeshes, buildTerrain, buildTileMeshes, createLowresMaterial, createSky, createTerrainMaterial, createWaterMaterial, pickBiome } from '../chunk-46RBFJ4D.js';
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, worldFromUrl } from '../chunk-EVPUXVSB.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-GGTVSB7H.js';
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';
@@ -1,5 +1,5 @@
1
1
  import * as THREE from 'three';
2
- import { i as WorldManifest, W as WorldFetch, R as Rgb, M as ManifestTile, c as LowresLevel, B as BiomeEntry, a as DecodedTextureArray, D as DecodedTile, j as WorldSource } from './biome-NBWIY7dT.js';
2
+ import { k as WorldManifest, i as WorldFetch, R as Rgb, M as ManifestTile, c as LowresLevel, B as BiomeEntry, a as DecodedTextureArray, D as DecodedTile, l as WorldSource } from './biome-B6l-1yx4.js';
3
3
 
4
4
  interface TileManagerOptions {
5
5
  manifest: WorldManifest;
@@ -37,6 +37,17 @@ interface TileManagerOptions {
37
37
  * atlas. Returns the atlas layer count now loaded. Omitted for a
38
38
  * static/complete render, whose atlas never grows. */
39
39
  ensureAtlas?: (layers: number) => Promise<number>;
40
+ /** The renderer, enabling map memory for worlds WITHOUT a lowres pyramid
41
+ * (live bakes, `vantage server`): evicted tiles are snapshotted into a
42
+ * shared atlas and persist as cheap textured impostors, so everywhere the
43
+ * camera has been stays visible when zoomed out. See `mapMemory`. */
44
+ renderer?: THREE.WebGLRenderer;
45
+ /** Map-memory impostor resolution in pixels per (128-block) tile — the
46
+ * quality knob for remembered terrain. `0` disables. Default `64`
47
+ * (a 2048² atlas remembering 1024 tiles ≈ 22 MB of GPU memory). Ignored
48
+ * when the manifest ships a lowres pyramid (that covers the whole world
49
+ * already) or without `renderer`. */
50
+ mapMemory?: number;
40
51
  }
41
52
  /** Live totals across resident tiles. */
42
53
  interface TileStats {
@@ -48,6 +59,9 @@ interface TileStats {
48
59
  total: number;
49
60
  /** Lowres LOD tiles resident. */
50
61
  lowres: number;
62
+ /** Tiles remembered as map-memory impostors (streamed worlds without a
63
+ * lowres pyramid). */
64
+ remembered: number;
51
65
  vertexCount: number;
52
66
  triangleCount: number;
53
67
  /** Compressed bytes fetched and resident. */
@@ -63,6 +77,11 @@ declare class TileManager {
63
77
  private readonly opts;
64
78
  private readonly lowresMaterial;
65
79
  private readonly lmMaterial;
80
+ /** Map memory (impostor snapshots of evicted tiles); null when the world
81
+ * ships a lowres pyramid, when disabled, or without a renderer. */
82
+ private impostors;
83
+ /** Kept for live map-memory reconfiguration (resolution changes). */
84
+ private readonly renderer;
66
85
  /** Widens the shared atlas to cover a tile's layers before it's drawn (live
67
86
  * renders only); null when the atlas is complete. */
68
87
  private readonly ensureAtlas;
@@ -99,6 +118,10 @@ declare class TileManager {
99
118
  /** Learned tile weights survive eviction and make future admission byte-aware. */
100
119
  private readonly sizeHints;
101
120
  private averageHiresBytes;
121
+ /** Whether resident tiles draw their cave-dark tails (VTLA). The viewer's
122
+ * cave policy toggles this off while the camera is above ground with the
123
+ * depth slice closed. */
124
+ private caveGeometry;
102
125
  private focusX;
103
126
  private focusZ;
104
127
  private biomesCache;
@@ -107,6 +130,12 @@ declare class TileManager {
107
130
  private minY;
108
131
  private maxY;
109
132
  constructor(options: TileManagerOptions);
133
+ /** Surface map of a fully-streamed resident hires tile (the impostor layer
134
+ * stitches remembered rims onto live terrain with it). */
135
+ 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). */
138
+ private applyHazeFloor;
110
139
  /** Tile span in blocks at a pyramid level (0 = hires). */
111
140
  private levelBlocks;
112
141
  /** Squared distance from the focus to a tile centre. The re-plan compares
@@ -157,6 +186,11 @@ declare class TileManager {
157
186
  * update(); already-known tiles are ignored. Returns whether anything was
158
187
  * added. */
159
188
  addTiles(tiles: ManifestTile[]): boolean;
189
+ /** Reconcile the complete hires index from a continuous server manifest.
190
+ * Revision changes evict only affected resident tiles; removed coordinates
191
+ * disappear. Unchanged terrain remains on the GPU without a network fetch. */
192
+ syncTiles(tiles: ManifestTile[]): boolean;
193
+ private reconcileTiles;
160
194
  /** Install the lowres pyramid once a progressive render finishes (its earlier
161
195
  * manifests carried no lowres). No-op without a lowres material, or if a
162
196
  * pyramid is already present. Forces a re-plan so the coarse rings stream in. */
@@ -164,14 +198,29 @@ declare class TileManager {
164
198
  grid: number;
165
199
  levels: LowresLevel[];
166
200
  }): void;
167
- /** Live-tune streaming (view distance, tile budget, fetch concurrency).
168
- * Takes effect on the next update(): the plan is recomputed from scratch. */
201
+ /** Show or hide every resident tile's cave-dark geometry (VTLA tiles order
202
+ * it as a contiguous tail per mesh, so hiding is a shorter draw range —
203
+ * same draw calls, fewer vertices shaded). Tiles built while hidden come up
204
+ * hidden. Tiles without a cave tail (older formats, all-surface tiles) are
205
+ * untouched. Returns whether anything changed (the caller redraws). */
206
+ setCaveGeometry(visible: boolean): boolean;
207
+ /** Live-tune streaming (view distance, tile budget, fetch concurrency,
208
+ * map-memory resolution). Takes effect on the next update(): the plan is
209
+ * recomputed from scratch. Changing `mapMemory` rebuilds the impostor
210
+ * atlas, which forgets remembered terrain (it re-accumulates as you pan). */
169
211
  configure(settings: {
170
212
  viewDistance?: number;
171
213
  maxTiles?: number;
172
214
  concurrency?: number;
173
215
  maxBytes?: number;
216
+ mapMemory?: number;
174
217
  }): void;
218
+ /** The active map-memory impostor resolution (0 = off/unavailable). */
219
+ get mapMemoryResolution(): number;
220
+ /** How far remembered (impostor) terrain reaches from (x,z), in blocks —
221
+ * 0 without map memory. The viewer sizes zoom range and fog off this so
222
+ * the remembered map is actually visible. */
223
+ mapMemoryExtent(x: number, z: number): number;
175
224
  /** The current stream-in radius, in blocks. */
176
225
  get viewDistance(): number;
177
226
  /** The current resident-tile budget. */
@@ -463,6 +512,13 @@ interface StreamingSettings {
463
512
  concurrency?: number;
464
513
  /** Estimated CPU/GPU tile residency budget, in bytes. Default `512 MiB`. */
465
514
  maxBytes?: number;
515
+ /** Map memory for worlds WITHOUT a baked lowres pyramid (live bakes,
516
+ * `vantage server`): tiles leaving the streaming ring are snapshotted
517
+ * top-down and persist as cheap textured impostors, so everywhere the
518
+ * camera has been stays on the map when zoomed out. The value is the
519
+ * snapshot resolution in pixels per tile (`0` = off). Default `64`
520
+ * (remembers 1024 tiles in a 2048² atlas ≈ 22 MiB of GPU memory). */
521
+ mapMemory?: number;
466
522
  }
467
523
  interface VantageViewerOptions {
468
524
  /** Initial camera framing. Default `'orbit'`. */
@@ -490,6 +546,13 @@ interface VantageViewerOptions {
490
546
  * frame it arrives. Default `true`; set `false` to render every frame
491
547
  * (e.g. when driving external per-frame effects off the viewer's scene). */
492
548
  renderOnDemand?: boolean;
549
+ /** Cave-geometry draw policy for VTLA tiles (whose cave-dark quads sit in a
550
+ * toggleable tail per mesh). `'auto'` skips them whenever the camera is
551
+ * above ground with the depth slice closed — from up there they are hidden
552
+ * behind terrain and cost pure vertex work — and brings them back the
553
+ * moment the slice opens or the camera dips underground. `'always'` keeps
554
+ * every quad drawn. Default `'auto'`. */
555
+ caveGeometry?: 'auto' | 'always';
493
556
  }
494
557
  /** A tile source: a URL to fetch, a raw buffer, or already-decoded data. */
495
558
  type TileSource = string | ArrayBuffer | DecodedTile;
@@ -536,8 +599,8 @@ interface ViewerEvents extends Record<string, unknown> {
536
599
  slice: {
537
600
  y: number | null;
538
601
  };
539
- /** Progressive render progress, while a live bake streams in. `done` reaches
540
- * `total` and `rendering` flips false on the final manifest. */
602
+ /** Progressive/live render progress. Finished batch renders flip false;
603
+ * continuous multiplayer sources keep rendering true for change polling. */
541
604
  progress: {
542
605
  done: number;
543
606
  total: number;
@@ -573,6 +636,8 @@ declare class VantageViewer {
573
636
  private lastBiomesEmit;
574
637
  private progressiveManager;
575
638
  private lastTextureLayers;
639
+ /** Last progress payload emitted, for deduplication across identical polls. */
640
+ private lastProgress;
576
641
  /** An in-flight atlas re-fetch, so the tile-insert gate and the progressive
577
642
  * poll coalesce onto one request instead of racing separate fetches. */
578
643
  private atlasRefresh;
@@ -587,6 +652,8 @@ declare class VantageViewer {
587
652
  private lastSliceY;
588
653
  /** The dark "unexplored rock" floor under a sliced world. */
589
654
  private slicePlane;
655
+ private caveMode;
656
+ private cavesShown;
590
657
  private light;
591
658
  private display;
592
659
  private readonly raycaster;
@@ -617,12 +684,15 @@ declare class VantageViewer {
617
684
  * without ever holding more than the streaming budget in memory. */
618
685
  private loadWorld;
619
686
  /** Emit a `progress` event from a manifest (falling back to the tile count
620
- * when the generator didn't include a `progress` block). */
687
+ * when the generator didn't include a `progress` block). Deduplicated: a
688
+ * continuous server reports the same numbers poll after poll, and repeating
689
+ * them would tick every listener (React state, HUDs) for nothing. Returns
690
+ * whether anything actually changed (and was emitted). */
621
691
  private emitProgress;
622
692
  /** Follow a live (`rendering: true`) render: re-fetch the manifest on an
623
- * interval, stream newly-baked tiles in, widen the texture array when the
624
- * atlas grows, and install the lowres pyramid once the bake completes. Runs
625
- * until the render finishes or the world is replaced. */
693
+ * interval, stream new/revised tiles in, widen the texture array when the
694
+ * atlas grows, and install the lowres pyramid once a batch bake completes.
695
+ * Continuous sources run until the world is replaced. */
626
696
  private pollProgressive;
627
697
  /** Ensure the terrain atlas covers at least `layers` texture-array layers,
628
698
  * re-fetching `terrain.vtexarr` if it's behind. Coalesces concurrent callers
@@ -653,8 +723,15 @@ declare class VantageViewer {
653
723
  * fog retreats to the world edge — a faint horizon haze, never a wall. The
654
724
  * hires→lowres seam needs no hiding: finer data simply overlays coarser.
655
725
  *
656
- * Without one (format 1), zoom and fog hug the hires ring so the map never
657
- * becomes a field of holes: solid haze right where tiles stop. */
726
+ * Without one, zoom and fog hug the drawable frontier: the hires ring on a
727
+ * fresh session (so the map never becomes a field of holes — solid haze
728
+ * right where tiles stop), growing to the remembered map-memory extent as
729
+ * the camera explores. Re-applied on tile 'change' events, so the fog wall
730
+ * recedes as snapshots land.
731
+ *
732
+ * Both branches share hard sanity ceilings (60k zoom, 250k far plane):
733
+ * beyond them depth precision and control feel degrade faster than any
734
+ * real overview gains — a 60k-block eye already frames a 100k-block map. */
658
735
  private applyViewLimits;
659
736
  private setTile;
660
737
  /** Where the *land* is, from the surface heightmap: the elevation-weighted
@@ -784,9 +861,27 @@ declare class VantageViewer {
784
861
  * itself for everything it owns (camera motion, tile streaming, settings,
785
862
  * the biome layer); call this only if you mutate the scene from outside. */
786
863
  invalidate(): void;
864
+ /** Set the cave-geometry draw policy (see the option of the same name).
865
+ * Takes effect on the next frame. */
866
+ setCaveGeometry(mode: 'auto' | 'always'): void;
867
+ /** The current cave-geometry draw policy. */
868
+ get caveGeometry(): 'auto' | 'always';
869
+ /** Re-evaluate whether cave-dark tails belong in the draw ranges. Above
870
+ * ground with the depth slice closed they are provably behind terrain from
871
+ * the camera's side of the surface, so 'auto' trims every tile's draw range
872
+ * to its surface prefix; opening the slice or descending underground brings
873
+ * them straight back. The underground test rides the streamed surface maps
874
+ * (the same data the terrain-following pivot uses) with a couple of blocks
875
+ * of hysteresis so skimming the terrain doesn't flicker the ranges. */
876
+ private applyCavePolicy;
787
877
  /** Idle animation cadence (ms). Water/lava bake at a 2-tick frametime
788
878
  * (100 ms), so a 10 fps tick steps them at exactly their authored rate. */
789
879
  private static readonly ANIM_TICK_MS;
880
+ /** Manifest poll cadence (ms) while a render is streaming in. */
881
+ private static readonly POLL_MS;
882
+ /** Ceiling the poll cadence relaxes to while a continuous server reports no
883
+ * changes — a saved world edit still shows up within ~one ceiling. */
884
+ private static readonly POLL_MAX_MS;
790
885
  private frame;
791
886
  private draw;
792
887
  /** Draw a fresh frame and return the canvas as a PNG data URL, for a
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thoughts-on-things/vantage-mc",
3
- "version": "0.6.0",
3
+ "version": "0.8.0",
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",