@thoughts-on-things/vantage-mc 0.7.0 → 0.9.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"];
@@ -1,4 +1,4 @@
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-CelByWgf.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, worldFromHttp, worldFromUrl, worldFromVantageServer } from '../chunk-QQJHRHBC.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 { l as WorldSource, B as BiomeEntry } from '../biome-CelByWgf.js';
4
- export { D as DecodedTile } from '../biome-CelByWgf.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-DYu-AUUt.js';
6
- export { D as DEFAULT_ORBIT_ANGLE, V as VANILLA_DISPLAY } from '../viewer-DYu-AUUt.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-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 {
@@ -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-F5RGBOVF.js';
2
- export { DEFAULT_ORBIT_ANGLE, VANILLA_DISPLAY } from '../chunk-F5RGBOVF.js';
3
- import '../chunk-QQJHRHBC.js';
1
+ import { VantageViewer, DEFAULT_ORBIT_ANGLE } from '../chunk-E7Y7K6NH.js';
2
+ export { DEFAULT_ORBIT_ANGLE, VANILLA_DISPLAY } from '../chunk-E7Y7K6NH.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
 
@@ -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,
@@ -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-CelByWgf.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-CelByWgf.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-DYu-AUUt.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 {
@@ -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-F5RGBOVF.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-QQJHRHBC.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
+ 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 { 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-CelByWgf.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;
@@ -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
@@ -37,6 +44,17 @@ interface TileManagerOptions {
37
44
  * atlas. Returns the atlas layer count now loaded. Omitted for a
38
45
  * static/complete render, whose atlas never grows. */
39
46
  ensureAtlas?: (layers: number) => Promise<number>;
47
+ /** The renderer, enabling map memory for worlds WITHOUT a lowres pyramid
48
+ * (live bakes, `vantage server`): evicted tiles are snapshotted into a
49
+ * shared atlas and persist as cheap textured impostors, so everywhere the
50
+ * camera has been stays visible when zoomed out. See `mapMemory`. */
51
+ renderer?: THREE.WebGLRenderer;
52
+ /** Map-memory impostor resolution in pixels per (128-block) tile — the
53
+ * quality knob for remembered terrain. `0` disables. Default `64`
54
+ * (a 2048² atlas remembering 1024 tiles ≈ 22 MB of GPU memory). Ignored
55
+ * when the manifest ships a lowres pyramid (that covers the whole world
56
+ * already) or without `renderer`. */
57
+ mapMemory?: number;
40
58
  }
41
59
  /** Live totals across resident tiles. */
42
60
  interface TileStats {
@@ -48,12 +66,17 @@ interface TileStats {
48
66
  total: number;
49
67
  /** Lowres LOD tiles resident. */
50
68
  lowres: number;
69
+ /** Tiles remembered as map-memory impostors (streamed worlds without a
70
+ * lowres pyramid). */
71
+ remembered: number;
51
72
  vertexCount: number;
52
73
  triangleCount: number;
53
74
  /** Compressed bytes fetched and resident. */
54
75
  bytes: number;
55
76
  /** Estimated CPU/GPU bytes held by resident and upload-pending resources. */
56
77
  residentBytes: number;
78
+ /** Compressed payloads retained for instant revisits (the tile byte cache). */
79
+ cachedBytes: number;
57
80
  }
58
81
  interface TileEvents extends Record<string, unknown> {
59
82
  /** A tile finished loading or was unloaded; payload = live stats. */
@@ -63,6 +86,11 @@ declare class TileManager {
63
86
  private readonly opts;
64
87
  private readonly lowresMaterial;
65
88
  private readonly lmMaterial;
89
+ /** Map memory (impostor snapshots of evicted tiles); null when the world
90
+ * ships a lowres pyramid, when disabled, or without a renderer. */
91
+ private impostors;
92
+ /** Kept for live map-memory reconfiguration (resolution changes). */
93
+ private readonly renderer;
66
94
  /** Widens the shared atlas to cover a tile's layers before it's drawn (live
67
95
  * renders only); null when the atlas is complete. */
68
96
  private readonly ensureAtlas;
@@ -99,6 +127,19 @@ declare class TileManager {
99
127
  /** Learned tile weights survive eviction and make future admission byte-aware. */
100
128
  private readonly sizeHints;
101
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;
139
+ /** Whether resident tiles draw their cave-dark tails (VTLA). The viewer's
140
+ * cave policy toggles this off while the camera is above ground with the
141
+ * depth slice closed. */
142
+ private caveGeometry;
102
143
  private focusX;
103
144
  private focusZ;
104
145
  private biomesCache;
@@ -107,6 +148,16 @@ declare class TileManager {
107
148
  private minY;
108
149
  private maxY;
109
150
  constructor(options: TileManagerOptions);
151
+ /** Surface map of a fully-streamed resident hires tile (the impostor layer
152
+ * stitches remembered rims onto live terrain with it). */
153
+ private readonly readySurface;
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. */
160
+ private applyHazeFloor;
110
161
  /** Tile span in blocks at a pyramid level (0 = hires). */
111
162
  private levelBlocks;
112
163
  /** Squared distance from the focus to a tile centre. The re-plan compares
@@ -121,6 +172,9 @@ declare class TileManager {
121
172
  */
122
173
  update(focusX: number, focusZ: number): void;
123
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;
124
178
  /** Insert built tiles into the scene at a bounded per-frame rate (via
125
179
  * update()), so GPU buffer uploads are spread across frames instead of
126
180
  * bursting. Normally one per frame; when a backlog builds (a big preset
@@ -169,14 +223,30 @@ declare class TileManager {
169
223
  grid: number;
170
224
  levels: LowresLevel[];
171
225
  }): void;
172
- /** Live-tune streaming (view distance, tile budget, fetch concurrency).
173
- * Takes effect on the next update(): the plan is recomputed from scratch. */
226
+ /** Show or hide every resident tile's cave-dark geometry (VTLA tiles order
227
+ * it as a contiguous tail per mesh, so hiding is a shorter draw range —
228
+ * same draw calls, fewer vertices shaded). Tiles built while hidden come up
229
+ * hidden. Tiles without a cave tail (older formats, all-surface tiles) are
230
+ * untouched. Returns whether anything changed (the caller redraws). */
231
+ setCaveGeometry(visible: boolean): boolean;
232
+ /** Live-tune streaming (view distance, tile budget, fetch concurrency,
233
+ * map-memory resolution). Takes effect on the next update(): the plan is
234
+ * recomputed from scratch. Changing `mapMemory` rebuilds the impostor
235
+ * atlas, which forgets remembered terrain (it re-accumulates as you pan). */
174
236
  configure(settings: {
175
237
  viewDistance?: number;
176
238
  maxTiles?: number;
177
239
  concurrency?: number;
178
240
  maxBytes?: number;
241
+ tileCacheBytes?: number;
242
+ mapMemory?: number;
179
243
  }): void;
244
+ /** The active map-memory impostor resolution (0 = off/unavailable). */
245
+ get mapMemoryResolution(): number;
246
+ /** How far remembered (impostor) terrain reaches from (x,z), in blocks —
247
+ * 0 without map memory. The viewer sizes zoom range and fog off this so
248
+ * the remembered map is actually visible. */
249
+ mapMemoryExtent(x: number, z: number): number;
180
250
  /** The current stream-in radius, in blocks. */
181
251
  get viewDistance(): number;
182
252
  /** The current resident-tile budget. */
@@ -464,10 +534,22 @@ interface StreamingSettings {
464
534
  viewDistance?: number;
465
535
  /** Hard cap on resident tiles (nearest win). Default `120`. */
466
536
  maxTiles?: number;
467
- /** Concurrent tile fetches. Default `4`. */
537
+ /** Concurrent tile fetches. Default `6`. */
468
538
  concurrency?: number;
469
539
  /** Estimated CPU/GPU tile residency budget, in bytes. Default `512 MiB`. */
470
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;
546
+ /** Map memory for worlds WITHOUT a baked lowres pyramid (live bakes,
547
+ * `vantage server`): tiles leaving the streaming ring are snapshotted
548
+ * top-down and persist as cheap textured impostors, so everywhere the
549
+ * camera has been stays on the map when zoomed out. The value is the
550
+ * snapshot resolution in pixels per tile (`0` = off). Default `64`
551
+ * (remembers 1024 tiles in a 2048² atlas ≈ 22 MiB of GPU memory). */
552
+ mapMemory?: number;
471
553
  }
472
554
  interface VantageViewerOptions {
473
555
  /** Initial camera framing. Default `'orbit'`. */
@@ -495,6 +577,13 @@ interface VantageViewerOptions {
495
577
  * frame it arrives. Default `true`; set `false` to render every frame
496
578
  * (e.g. when driving external per-frame effects off the viewer's scene). */
497
579
  renderOnDemand?: boolean;
580
+ /** Cave-geometry draw policy for VTLA tiles (whose cave-dark quads sit in a
581
+ * toggleable tail per mesh). `'auto'` skips them whenever the camera is
582
+ * above ground with the depth slice closed — from up there they are hidden
583
+ * behind terrain and cost pure vertex work — and brings them back the
584
+ * moment the slice opens or the camera dips underground. `'always'` keeps
585
+ * every quad drawn. Default `'auto'`. */
586
+ caveGeometry?: 'auto' | 'always';
498
587
  }
499
588
  /** A tile source: a URL to fetch, a raw buffer, or already-decoded data. */
500
589
  type TileSource = string | ArrayBuffer | DecodedTile;
@@ -594,6 +683,8 @@ declare class VantageViewer {
594
683
  private lastSliceY;
595
684
  /** The dark "unexplored rock" floor under a sliced world. */
596
685
  private slicePlane;
686
+ private caveMode;
687
+ private cavesShown;
597
688
  private light;
598
689
  private display;
599
690
  private readonly raycaster;
@@ -653,8 +744,9 @@ declare class VantageViewer {
653
744
  * a 100k×100k world frames the same as a village. */
654
745
  private frameWorld;
655
746
  /** The radius hires tiles are actually guaranteed resident to: the view
656
- * distance, unless the tile budget runs out first (nearest-first fill ⇒ a
657
- * 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. */
658
750
  private streamRadius;
659
751
  /** Zoom range, far plane, and fog for a streamed world.
660
752
  *
@@ -663,8 +755,15 @@ declare class VantageViewer {
663
755
  * fog retreats to the world edge — a faint horizon haze, never a wall. The
664
756
  * hires→lowres seam needs no hiding: finer data simply overlays coarser.
665
757
  *
666
- * Without one (format 1), zoom and fog hug the hires ring so the map never
667
- * becomes a field of holes: solid haze right where tiles stop. */
758
+ * Without one, zoom and fog hug the drawable frontier: the hires ring on a
759
+ * fresh session (so the map never becomes a field of holes — solid haze
760
+ * right where tiles stop), growing to the remembered map-memory extent as
761
+ * the camera explores. Re-applied on tile 'change' events, so the fog wall
762
+ * recedes as snapshots land.
763
+ *
764
+ * Both branches share hard sanity ceilings (60k zoom, 250k far plane):
765
+ * beyond them depth precision and control feel degrade faster than any
766
+ * real overview gains — a 60k-block eye already frames a 100k-block map. */
668
767
  private applyViewLimits;
669
768
  private setTile;
670
769
  /** Where the *land* is, from the surface heightmap: the elevation-weighted
@@ -794,6 +893,19 @@ declare class VantageViewer {
794
893
  * itself for everything it owns (camera motion, tile streaming, settings,
795
894
  * the biome layer); call this only if you mutate the scene from outside. */
796
895
  invalidate(): void;
896
+ /** Set the cave-geometry draw policy (see the option of the same name).
897
+ * Takes effect on the next frame. */
898
+ setCaveGeometry(mode: 'auto' | 'always'): void;
899
+ /** The current cave-geometry draw policy. */
900
+ get caveGeometry(): 'auto' | 'always';
901
+ /** Re-evaluate whether cave-dark tails belong in the draw ranges. Above
902
+ * ground with the depth slice closed they are provably behind terrain from
903
+ * the camera's side of the surface, so 'auto' trims every tile's draw range
904
+ * to its surface prefix; opening the slice or descending underground brings
905
+ * them straight back. The underground test rides the streamed surface maps
906
+ * (the same data the terrain-following pivot uses) with a couple of blocks
907
+ * of hysteresis so skimming the terrain doesn't flicker the ranges. */
908
+ private applyCavePolicy;
797
909
  /** Idle animation cadence (ms). Water/lava bake at a 2-tick frametime
798
910
  * (100 ms), so a 10 fps tick steps them at exactly their authored rate. */
799
911
  private static readonly ANIM_TICK_MS;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thoughts-on-things/vantage-mc",
3
- "version": "0.7.0",
3
+ "version": "0.9.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",
@@ -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",