@thoughts-on-things/vantage-mc 0.4.0 → 0.5.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.
@@ -1,4 +1,4 @@
1
- import { biomePalette, LOWRES_EMPTY, tileKey, parseLowresTile, maybeInflate, parseTileQuantized, summarizeSurfaceBiomes, parseTile, summarizeBiomes, worldFromUrl, parseManifest, parseTextureArray } from './chunk-ILHVIGCI.js';
1
+ import { biomePalette, LOWRES_EMPTY, tileKey, parseLowresTile, maybeInflate, parseTileQuantized, summarizeSurfaceBiomes, parseTile, summarizeBiomes, worldFromUrl, parseManifest, parseTextureArray } from './chunk-EVPUXVSB.js';
2
2
  import * as THREE2 from 'three';
3
3
 
4
4
  var SKY_TOP = [0.3, 0.52, 0.84];
@@ -26,7 +26,7 @@ var VERT = (
26
26
  in float alight; // packed (sky<<4)|block, 0..255
27
27
  #endif
28
28
  #ifdef LIGHTMAP
29
- // Atlas-lit geometry (VTL8's greedy tail): baked light + AO come from a
29
+ // Atlas-lit geometry (VTL8+'s greedy tail): baked light + AO come from a
30
30
  // per-tile texture sampled in the fragment shader \u2014 per-BLOCK gradients on
31
31
  // arbitrarily large merged quads \u2014 instead of per-vertex values.
32
32
  in vec2 almuv; // half-texel atlas coords
@@ -127,6 +127,7 @@ var FRAG = (
127
127
  in float vWorldY;
128
128
  #ifdef LIGHTMAP
129
129
  uniform sampler2D uLightmap; // per-tile baked light+AO atlas
130
+ uniform float uLmPacked; // 1 = VTL9 packed RG8
130
131
  in vec2 vLmUv;
131
132
  #endif
132
133
  out vec4 frag;
@@ -182,6 +183,13 @@ var FRAG = (
182
183
  return max(c, vec3(0.0));
183
184
  }
184
185
 
186
+ #ifdef LIGHTMAP
187
+ vec3 decodePackedLight(vec2 rg) {
188
+ float packed = floor(rg.r * 255.0 + 0.5);
189
+ return vec3(floor(packed / 16.0), mod(packed, 16.0), rg.g);
190
+ }
191
+ #endif
192
+
185
193
  void main() {
186
194
  // Depth slice (cave view): cut everything above the clip plane. With
187
195
  // backface culling on, the first thing visible below the cut is a cave
@@ -194,10 +202,32 @@ var FRAG = (
194
202
  float blkL = vBlk;
195
203
  float aoV = vTint.a;
196
204
  #ifdef LIGHTMAP
197
- vec3 lmS = texture(uLightmap, vLmUv).rgb;
198
- skyL = lmS.r;
199
- blkL = lmS.g;
200
- aoV = lmS.b;
205
+ if (uLmPacked > 0.5) {
206
+ // Packing sky/block into one byte is lossless, but filtering that byte
207
+ // before unpacking would mix the nibbles. Fetch and decode the four
208
+ // neighbours first, then reproduce bilinear interpolation exactly.
209
+ vec2 p = vLmUv * vec2(textureSize(uLightmap, 0)) - 0.5;
210
+ ivec2 base = ivec2(floor(p));
211
+ vec2 f = fract(p);
212
+ ivec2 hi = textureSize(uLightmap, 0) - 1;
213
+ vec2 s00 = texelFetch(uLightmap, clamp(base, ivec2(0), hi), 0).rg;
214
+ vec2 s10 = texelFetch(uLightmap, clamp(base + ivec2(1, 0), ivec2(0), hi), 0).rg;
215
+ vec2 s01 = texelFetch(uLightmap, clamp(base + ivec2(0, 1), ivec2(0), hi), 0).rg;
216
+ vec2 s11 = texelFetch(uLightmap, clamp(base + ivec2(1, 1), ivec2(0), hi), 0).rg;
217
+ vec3 l00 = decodePackedLight(s00);
218
+ vec3 l10 = decodePackedLight(s10);
219
+ vec3 l01 = decodePackedLight(s01);
220
+ vec3 l11 = decodePackedLight(s11);
221
+ vec3 lmS = mix(mix(l00, l10, f.x), mix(l01, l11, f.x), f.y);
222
+ skyL = lmS.r / 15.0;
223
+ blkL = lmS.g / 15.0;
224
+ aoV = lmS.b;
225
+ } else {
226
+ vec3 lmS = texture(uLightmap, vLmUv).rgb;
227
+ skyL = lmS.r;
228
+ blkL = lmS.g;
229
+ aoV = lmS.b;
230
+ }
201
231
  #endif
202
232
  float lightAmt; vec3 lightCol;
203
233
  bakedLight(skyL, blkL, lightAmt, lightCol);
@@ -311,7 +341,7 @@ function paletteTexture(palette) {
311
341
  tex.needsUpdate = true;
312
342
  return tex;
313
343
  }
314
- function createTerrainMaterial(texData, opts = {}) {
344
+ function buildArrayTexture(texData) {
315
345
  const tex = new THREE2.DataArrayTexture(texData.pixels, texData.width, texData.height, texData.layers);
316
346
  tex.format = THREE2.RGBAFormat;
317
347
  tex.type = THREE2.UnsignedByteType;
@@ -322,6 +352,22 @@ function createTerrainMaterial(texData, opts = {}) {
322
352
  tex.wrapS = THREE2.RepeatWrapping;
323
353
  tex.wrapT = THREE2.RepeatWrapping;
324
354
  tex.needsUpdate = true;
355
+ return tex;
356
+ }
357
+ function updateTerrainTextures(material, texData) {
358
+ const mapU = material.uniforms["map"];
359
+ if (mapU) {
360
+ mapU.value?.dispose();
361
+ mapU.value = buildArrayTexture(texData);
362
+ }
363
+ const animU = material.uniforms["uAnim"];
364
+ if (animU) {
365
+ animU.value?.dispose();
366
+ animU.value = animLutTexture(texData.layers, texData.anims ?? []);
367
+ }
368
+ }
369
+ function createTerrainMaterial(texData, opts = {}) {
370
+ const tex = buildArrayTexture(texData);
325
371
  return new THREE2.ShaderMaterial({
326
372
  glslVersion: THREE2.GLSL3,
327
373
  defines: opts.quantized ? { QUANTIZED: "" } : {},
@@ -339,6 +385,7 @@ function createTerrainMaterial(texData, opts = {}) {
339
385
  // material — see createLightmappedMaterial; inert here).
340
386
  uLightmap: { value: null },
341
387
  uLmSize: { value: new THREE2.Vector2(1, 1) },
388
+ uLmPacked: { value: 0 },
342
389
  uPalette: { value: opts.quantized ? paletteTexture(opts.palette ?? []) : null },
343
390
  uFogCenter: { value: new THREE2.Vector2() },
344
391
  // streaming focus (world XZ)
@@ -559,12 +606,17 @@ function baseGeometry(section) {
559
606
  }
560
607
  var WATER_FALLBACK = [0.3, 0.5, 0.85];
561
608
  function lightmapTexture(lm) {
562
- const tex = new THREE2.DataTexture(lm.pixels, lm.width, lm.height, THREE2.RGBAFormat, THREE2.UnsignedByteType);
563
- tex.magFilter = THREE2.LinearFilter;
564
- tex.minFilter = THREE2.LinearFilter;
609
+ const format = lm.packed ? THREE2.RGFormat : THREE2.RGBAFormat;
610
+ const tex = new THREE2.DataTexture(lm.pixels, lm.width, lm.height, format, THREE2.UnsignedByteType);
611
+ tex.magFilter = lm.packed ? THREE2.NearestFilter : THREE2.LinearFilter;
612
+ tex.minFilter = lm.packed ? THREE2.NearestFilter : THREE2.LinearFilter;
565
613
  tex.wrapS = THREE2.ClampToEdgeWrapping;
566
614
  tex.wrapT = THREE2.ClampToEdgeWrapping;
567
615
  tex.generateMipmaps = false;
616
+ tex.userData["vantageGpuBytes"] = lm.pixels.byteLength;
617
+ tex.onUpdate = () => {
618
+ tex.image.data = null;
619
+ };
568
620
  tex.needsUpdate = true;
569
621
  return tex;
570
622
  }
@@ -656,6 +708,7 @@ function quantizedMesh(sec, material, lm) {
656
708
  if (lm) {
657
709
  m.uniforms["uLightmap"].value = lm.tex;
658
710
  m.uniforms["uLmSize"].value.copy(lm.size);
711
+ m.uniforms["uLmPacked"].value = lm.packed ? 1 : 0;
659
712
  }
660
713
  m.uniformsNeedUpdate = true;
661
714
  };
@@ -674,7 +727,11 @@ function buildQuantizedTileMeshes(tile, material, waterMaterial, lmMaterial) {
674
727
  const lm = tile.lightmap;
675
728
  lightmapTex = lightmapTexture(lm);
676
729
  const tail = sliceSection(solid, lmStart, solid.vertexCount);
677
- terrainLm = quantizedMesh(tail, lmMaterial, { tex: lightmapTex, size: new THREE2.Vector2(lm.width, lm.height) });
730
+ terrainLm = quantizedMesh(tail, lmMaterial, {
731
+ tex: lightmapTex,
732
+ size: new THREE2.Vector2(lm.width, lm.height),
733
+ packed: lm.packed
734
+ });
678
735
  terrainLm.geometry.setAttribute("almuv", new THREE2.BufferAttribute(solid.lmuv, 2, false));
679
736
  }
680
737
  let water;
@@ -778,6 +835,46 @@ var Emitter = class {
778
835
  }
779
836
  };
780
837
 
838
+ // src/three/streaming.ts
839
+ function nearbyTiles(index, tileBlocks, focusX, focusZ, radius, predictedX = focusX, predictedZ = focusZ) {
840
+ const radiusSq = radius * radius;
841
+ const minX = Math.floor((focusX - radius) / tileBlocks - 0.5);
842
+ const maxX = Math.ceil((focusX + radius) / tileBlocks - 0.5);
843
+ const minZ = Math.floor((focusZ - radius) / tileBlocks - 0.5);
844
+ const maxZ = Math.ceil((focusZ + radius) / tileBlocks - 0.5);
845
+ const out = [];
846
+ for (let z = minZ; z <= maxZ; z++) {
847
+ for (let x = minX; x <= maxX; x++) {
848
+ const ref = index.get(tileKey(x, z));
849
+ if (!ref) continue;
850
+ const cx = (x + 0.5) * tileBlocks;
851
+ const cz = (z + 0.5) * tileBlocks;
852
+ const dx = cx - focusX;
853
+ const dz = cz - focusZ;
854
+ const distanceSq = dx * dx + dz * dz;
855
+ if (distanceSq > radiusSq) continue;
856
+ const px = cx - predictedX;
857
+ const pz = cz - predictedZ;
858
+ const priority = distanceSq * 0.72 + (px * px + pz * pz) * 0.28;
859
+ out.push({ ref, distanceSq, priority });
860
+ }
861
+ }
862
+ out.sort((a, b) => a.priority - b.priority || a.distanceSq - b.distanceSq);
863
+ return out;
864
+ }
865
+ function admitTiles(candidates, maxTiles, maxBytes, estimateBytes) {
866
+ const admitted = [];
867
+ let bytes = 0;
868
+ for (const candidate of candidates) {
869
+ if (admitted.length >= maxTiles) break;
870
+ const weight = Math.max(1, estimateBytes(candidate.ref));
871
+ if (admitted.length > 0 && bytes + weight > maxBytes) continue;
872
+ admitted.push(candidate);
873
+ bytes += weight;
874
+ }
875
+ return admitted;
876
+ }
877
+
781
878
  // src/three/tiles.ts
782
879
  function recKey(level, x, z) {
783
880
  return level === 0 ? tileKey(x, z) : `l${level}:${x},${z}`;
@@ -791,10 +888,32 @@ function releaseAfterUpload(geom) {
791
888
  }
792
889
  if (geom.index && !isSharedQuadIndex(geom.index)) geom.index.onUpload(release);
793
890
  }
891
+ function arrayBytes(value) {
892
+ return ArrayBuffer.isView(value) ? value.byteLength : 0;
893
+ }
894
+ function geometryBytes(geom) {
895
+ let bytes = 0;
896
+ for (const name of Object.keys(geom.attributes)) {
897
+ bytes += arrayBytes(geom.getAttribute(name).array);
898
+ }
899
+ if (geom.index && !isSharedQuadIndex(geom.index)) bytes += arrayBytes(geom.index.array);
900
+ return bytes;
901
+ }
902
+ function textureBytes(texture) {
903
+ if (!texture) return 0;
904
+ const gpuBytes = texture.userData["vantageGpuBytes"];
905
+ return typeof gpuBytes === "number" ? gpuBytes : arrayBytes(texture.image.data);
906
+ }
794
907
  var TileManager = class _TileManager {
795
908
  opts;
796
909
  lowresMaterial;
797
910
  lmMaterial;
911
+ /** Widens the shared atlas to cover a tile's layers before it's drawn (live
912
+ * renders only); null when the atlas is complete. */
913
+ ensureAtlas;
914
+ /** Best-known covered atlas layer count. `Infinity` disables the gate — a
915
+ * static render never grows its atlas. */
916
+ atlasLayers;
798
917
  index = /* @__PURE__ */ new Map();
799
918
  records = /* @__PURE__ */ new Map();
800
919
  emitter = new Emitter();
@@ -811,6 +930,9 @@ var TileManager = class _TileManager {
811
930
  /** Built tiles awaiting scene insertion — flushed ONE per update() call so
812
931
  * multi-MB GPU uploads never pile into a single frame. */
813
932
  pendingAdd = [];
933
+ /** Built records still holding upload-pending typed arrays. Pumping pauses at
934
+ * one concurrency-window so decode cannot outrun GPU submission. */
935
+ pendingBuilt = 0;
814
936
  inFlight = 0;
815
937
  lastFocusX = Infinity;
816
938
  lastFocusZ = Infinity;
@@ -819,13 +941,18 @@ var TileManager = class _TileManager {
819
941
  * backoff escalates; cleared on success or unload (a fresh pan-in retries). */
820
942
  failCounts = /* @__PURE__ */ new Map();
821
943
  nextRetrySweep = 0;
944
+ /** Learned tile weights survive eviction and make future admission byte-aware. */
945
+ sizeHints = /* @__PURE__ */ new Map();
946
+ averageHiresBytes = 12 * 1024 * 1024;
947
+ focusX = 0;
948
+ focusZ = 0;
822
949
  biomesCache = null;
823
950
  statsCache = null;
824
951
  /** Y range of everything loaded so far, for ray-march bounds. */
825
952
  minY = 0;
826
953
  maxY = 320;
827
954
  constructor(options) {
828
- const { lowresMaterial, lmMaterial, ...rest } = options;
955
+ const { lowresMaterial, lmMaterial, ensureAtlas, ...rest } = options;
829
956
  this.opts = {
830
957
  viewDistance: 768,
831
958
  // Sized to fill the whole view-distance disc for 128-block tiles
@@ -833,16 +960,19 @@ var TileManager = class _TileManager {
833
960
  // panel's "med" preset exactly.
834
961
  maxTiles: 120,
835
962
  concurrency: 4,
963
+ maxBytes: 512 * 1024 * 1024,
836
964
  ...rest
837
965
  };
838
966
  this.lowresMaterial = lowresMaterial ?? null;
839
967
  this.lmMaterial = lmMaterial ?? null;
968
+ this.ensureAtlas = ensureAtlas ?? null;
969
+ this.atlasLayers = ensureAtlas ? options.manifest.textureLayers ?? 0 : Infinity;
840
970
  this.tileBlocks = options.manifest.tileBlocks;
841
971
  if (options.manifest.maxSectionVerts) sharedQuadIndex(options.manifest.maxSectionVerts);
842
972
  for (const t of options.manifest.tiles) this.index.set(tileKey(t.x, t.z), t);
843
973
  this.lowLevels = this.lowresMaterial ? [...options.manifest.lowres?.levels ?? []].sort((a, b) => a.level - b.level) : [];
844
974
  for (const lvl of this.lowLevels) {
845
- this.lowIndex.set(lvl.level, new Set(lvl.tiles.map((t) => tileKey(t.x, t.z))));
975
+ this.lowIndex.set(lvl.level, new Map(lvl.tiles.map((t) => [tileKey(t.x, t.z), t])));
846
976
  }
847
977
  }
848
978
  /** Tile span in blocks at a pyramid level (0 = hires). */
@@ -867,6 +997,8 @@ var TileManager = class _TileManager {
867
997
  */
868
998
  update(focusX, focusZ) {
869
999
  if (this.disposed) return;
1000
+ this.focusX = focusX;
1001
+ this.focusZ = focusZ;
870
1002
  this.flushOne();
871
1003
  this.retrySweep();
872
1004
  if (this.fadingKeys.size > 0) {
@@ -880,34 +1012,42 @@ var TileManager = class _TileManager {
880
1012
  }
881
1013
  }
882
1014
  if (this.coverageDirty) this.applyCoverage();
883
- const moved = Math.hypot(focusX - this.lastFocusX, focusZ - this.lastFocusZ);
1015
+ const priorX = this.lastFocusX;
1016
+ const priorZ = this.lastFocusZ;
1017
+ const moved = Math.hypot(focusX - priorX, focusZ - priorZ);
884
1018
  if (moved < this.tileBlocks / 4) {
885
1019
  this.pump();
886
1020
  return;
887
1021
  }
1022
+ const finitePrior = Number.isFinite(priorX) && Number.isFinite(priorZ);
1023
+ const dx = finitePrior ? focusX - priorX : 0;
1024
+ const dz = finitePrior ? focusZ - priorZ : 0;
1025
+ const travel = Math.hypot(dx, dz);
1026
+ const lookahead = travel > 0 ? Math.min(2, this.tileBlocks * 2 / travel) : 0;
1027
+ const predictedX = focusX + dx * lookahead;
1028
+ const predictedZ = focusZ + dz * lookahead;
888
1029
  this.lastFocusX = focusX;
889
1030
  this.lastFocusZ = focusZ;
890
- const { viewDistance, maxTiles } = this.opts;
891
- const desired = [];
892
- const viewDistSq = viewDistance * viewDistance;
893
- for (const t of this.index.values()) {
894
- const d = this.distSqTo(t, 0, focusX, focusZ);
895
- if (d <= viewDistSq) desired.push({ t, d });
896
- }
897
- desired.sort((a, b) => a.d - b.d);
898
- if (desired.length > maxTiles) desired.length = maxTiles;
1031
+ const { viewDistance, maxTiles, maxBytes } = this.opts;
1032
+ let lowBytes = 0;
1033
+ for (const rec of this.records.values()) if (rec.level > 0) lowBytes += rec.memoryBytes;
1034
+ const hiresBytes = Math.max(1, maxBytes - lowBytes);
1035
+ const desired = admitTiles(
1036
+ nearbyTiles(this.index, this.tileBlocks, focusX, focusZ, viewDistance, predictedX, predictedZ),
1037
+ maxTiles,
1038
+ hiresBytes,
1039
+ (t) => this.sizeHints.get(tileKey(t.x, t.z)) ?? Math.max(this.averageHiresBytes, t.bytes * 20)
1040
+ ).map((candidate) => ({ t: candidate.ref, d: candidate.distanceSq }));
899
1041
  const desiredKeys = new Set(desired.map(({ t }) => recKey(0, t.x, t.z)));
900
1042
  const lowDesired = [];
901
1043
  for (let i = 0; i < this.lowLevels.length; i++) {
902
1044
  const lvl = this.lowLevels[i];
903
1045
  const top = i === this.lowLevels.length - 1;
904
- const outer = top ? Infinity : (viewDistance * 2 ** lvl.level) ** 2;
1046
+ const outerDistance = viewDistance * 2 ** lvl.level;
1047
+ const outer = top ? Infinity : outerDistance ** 2;
905
1048
  const inner = top || i === 0 ? 0 : (viewDistance * 2 ** (lvl.level - 1) * 0.85) ** 2;
906
- const ring = [];
907
- for (const t of lvl.tiles) {
908
- const d = this.distSqTo(t, lvl.level, focusX, focusZ);
909
- if (d <= outer && d >= inner) ring.push({ ref: t, level: lvl.level, d });
910
- }
1049
+ const candidates = top ? lvl.tiles.map((ref) => ({ ref, distanceSq: this.distSqTo(ref, lvl.level, focusX, focusZ), priority: 0 })) : nearbyTiles(this.lowIndex.get(lvl.level), lvl.tileBlocks, focusX, focusZ, outerDistance, predictedX, predictedZ);
1050
+ const ring = candidates.filter((candidate) => candidate.distanceSq <= outer && candidate.distanceSq >= inner).map((candidate) => ({ ref: candidate.ref, level: lvl.level, d: candidate.distanceSq }));
911
1051
  ring.sort((a, b) => a.d - b.d);
912
1052
  if (ring.length > 160) ring.length = 160;
913
1053
  for (const r of ring) {
@@ -917,10 +1057,14 @@ var TileManager = class _TileManager {
917
1057
  }
918
1058
  for (const [key, rec] of this.records) {
919
1059
  if (desiredKeys.has(key)) continue;
1060
+ if (rec.level === 0) {
1061
+ this.unload(key, rec);
1062
+ continue;
1063
+ }
920
1064
  const top = this.lowLevels.length > 0 && rec.level === this.lowLevels[this.lowLevels.length - 1].level;
921
1065
  if (top) continue;
922
1066
  const d = this.distSqTo(rec.ref, rec.level, focusX, focusZ);
923
- const keep = rec.level === 0 ? viewDistance * 1.25 : viewDistance * 2 ** rec.level * 1.25;
1067
+ const keep = viewDistance * 2 ** rec.level * 1.25;
924
1068
  if (d > keep * keep) this.unload(key, rec);
925
1069
  }
926
1070
  const missing = (level, refs) => refs.filter(({ ref }) => !this.records.has(recKey(level, ref.x, ref.z)));
@@ -929,12 +1073,12 @@ var TileManager = class _TileManager {
929
1073
  ...missing(topLevel, lowDesired.filter((r) => r.level === topLevel)).map((r) => ({ ref: r.ref, level: topLevel })),
930
1074
  ...missing(0, desired.map((e) => ({ ref: e.t }))).map((r) => ({ ref: r.ref, level: 0 })),
931
1075
  ...lowDesired.filter((r) => r.level !== topLevel && !this.records.has(recKey(r.level, r.ref.x, r.ref.z))).sort((a, b) => a.level - b.level || a.d - b.d).map((r) => ({ ref: r.ref, level: r.level }))
932
- ];
1076
+ ].reverse();
933
1077
  this.pump();
934
1078
  }
935
1079
  pump() {
936
- while (this.inFlight < this.opts.concurrency && this.queue.length > 0) {
937
- const { ref, level } = this.queue.shift();
1080
+ while (this.inFlight < this.opts.concurrency && this.inFlight + this.pendingBuilt < this.opts.concurrency && this.queue.length > 0) {
1081
+ const { ref, level } = this.queue.pop();
938
1082
  if (level === 0) void this.loadTile(ref);
939
1083
  else void this.loadLowres(ref, level);
940
1084
  }
@@ -951,6 +1095,7 @@ var TileManager = class _TileManager {
951
1095
  const rec = this.records.get(key);
952
1096
  if (!rec || rec.state !== "built") continue;
953
1097
  rec.state = "ready";
1098
+ this.pendingBuilt--;
954
1099
  rec.fadeStart = performance.now();
955
1100
  this.fadingKeys.add(key);
956
1101
  this.opts.scene.add(rec.terrain);
@@ -961,6 +1106,7 @@ var TileManager = class _TileManager {
961
1106
  this.emitter.emit("change", this.stats);
962
1107
  budget--;
963
1108
  }
1109
+ this.pump();
964
1110
  }
965
1111
  /** Stream-in fade length. Long enough to read as a dissolve, short enough
966
1112
  * that a fast pan still feels instant. */
@@ -1024,12 +1170,47 @@ var TileManager = class _TileManager {
1024
1170
  finerIndex = this.lowIndex.get(lvl.level) ?? /* @__PURE__ */ new Set();
1025
1171
  }
1026
1172
  }
1173
+ /** Ingest tiles a progressive render has newly published. Unknown tiles join
1174
+ * the streaming index and force a re-plan so they stream in on the next
1175
+ * update(); already-known tiles are ignored. Returns whether anything was
1176
+ * added. */
1177
+ addTiles(tiles) {
1178
+ let added = false;
1179
+ for (const t of tiles) {
1180
+ const k = tileKey(t.x, t.z);
1181
+ if (!this.index.has(k)) {
1182
+ this.index.set(k, t);
1183
+ added = true;
1184
+ }
1185
+ }
1186
+ if (added) {
1187
+ this.lastFocusX = Infinity;
1188
+ this.lastFocusZ = Infinity;
1189
+ this.invalidate();
1190
+ this.emitter.emit("change", this.stats);
1191
+ }
1192
+ return added;
1193
+ }
1194
+ /** Install the lowres pyramid once a progressive render finishes (its earlier
1195
+ * manifests carried no lowres). No-op without a lowres material, or if a
1196
+ * pyramid is already present. Forces a re-plan so the coarse rings stream in. */
1197
+ ingestLowres(lowres) {
1198
+ if (!this.lowresMaterial || this.lowLevels.length > 0) return;
1199
+ const levels = [...lowres.levels].sort((a, b) => a.level - b.level);
1200
+ this.lowLevels.push(...levels);
1201
+ for (const lvl of levels) this.lowIndex.set(lvl.level, new Map(lvl.tiles.map((t) => [tileKey(t.x, t.z), t])));
1202
+ this.lastFocusX = Infinity;
1203
+ this.lastFocusZ = Infinity;
1204
+ this.coverageDirty = true;
1205
+ this.invalidate();
1206
+ }
1027
1207
  /** Live-tune streaming (view distance, tile budget, fetch concurrency).
1028
1208
  * Takes effect on the next update(): the plan is recomputed from scratch. */
1029
1209
  configure(settings) {
1030
1210
  if (settings.viewDistance !== void 0) this.opts.viewDistance = settings.viewDistance;
1031
1211
  if (settings.maxTiles !== void 0) this.opts.maxTiles = settings.maxTiles;
1032
1212
  if (settings.concurrency !== void 0) this.opts.concurrency = settings.concurrency;
1213
+ if (settings.maxBytes !== void 0) this.opts.maxBytes = settings.maxBytes;
1033
1214
  this.lastFocusX = Infinity;
1034
1215
  this.lastFocusZ = Infinity;
1035
1216
  }
@@ -1041,12 +1222,16 @@ var TileManager = class _TileManager {
1041
1222
  get maxTiles() {
1042
1223
  return this.opts.maxTiles;
1043
1224
  }
1225
+ /** The current estimated CPU+GPU residency budget. */
1226
+ get maxBytes() {
1227
+ return this.opts.maxBytes;
1228
+ }
1044
1229
  /** Fetch + decode one lowres LOD tile into a heightfield mesh. */
1045
1230
  async loadLowres(ref, level) {
1046
1231
  const key = recKey(level, ref.x, ref.z);
1047
1232
  if (this.records.has(key) || !this.lowresMaterial) return;
1048
1233
  const abort = new AbortController();
1049
- const rec = { ref, level, state: "loading", abort, vertexCount: 0, triangleCount: 0 };
1234
+ const rec = { ref, level, state: "loading", abort, vertexCount: 0, triangleCount: 0, memoryBytes: 0 };
1050
1235
  this.records.set(key, rec);
1051
1236
  this.inFlight++;
1052
1237
  try {
@@ -1071,7 +1256,9 @@ var TileManager = class _TileManager {
1071
1256
  };
1072
1257
  rec.vertexCount = tile.width * tile.depth;
1073
1258
  rec.triangleCount = mesh.geometry.index.count / 3;
1259
+ rec.memoryBytes = geometryBytes(mesh.geometry) + rec.low.heights.byteLength;
1074
1260
  rec.state = "built";
1261
+ this.pendingBuilt++;
1075
1262
  this.failCounts.delete(key);
1076
1263
  this.pendingAdd.push(key);
1077
1264
  this.invalidate();
@@ -1112,15 +1299,29 @@ var TileManager = class _TileManager {
1112
1299
  const key = tileKey(ref.x, ref.z);
1113
1300
  if (this.records.has(key)) return;
1114
1301
  const abort = new AbortController();
1115
- const rec = { ref, level: 0, state: "loading", abort, vertexCount: 0, triangleCount: 0 };
1302
+ const rec = { ref, level: 0, state: "loading", abort, vertexCount: 0, triangleCount: 0, memoryBytes: 0 };
1116
1303
  this.records.set(key, rec);
1117
1304
  this.inFlight++;
1118
1305
  try {
1119
1306
  const buffer = await maybeInflate(await this.opts.fetch(ref.path, abort.signal));
1120
1307
  if (this.disposed || rec.state !== "loading") return;
1308
+ if (buffer.byteLength === 0) {
1309
+ rec.state = "empty";
1310
+ return;
1311
+ }
1121
1312
  let meshes;
1122
1313
  const q = parseTileQuantized(buffer);
1123
1314
  if (q) {
1315
+ if (this.ensureAtlas) {
1316
+ let need = 0;
1317
+ for (const arr of [q.solid.layer, q.fluid.layer]) {
1318
+ for (let i = 0; i < arr.length; i++) if (arr[i] >= need) need = arr[i] + 1;
1319
+ }
1320
+ if (need > this.atlasLayers) {
1321
+ this.atlasLayers = await this.ensureAtlas(need);
1322
+ if (this.disposed || rec.state !== "loading") return;
1323
+ }
1324
+ }
1124
1325
  rec.biomes = summarizeSurfaceBiomes(q.surface, q.biomeNames, this.opts.palette);
1125
1326
  rec.surface = { ...q.surface, biome: q.surface.biome.slice(), height: q.surface.height.slice() };
1126
1327
  meshes = buildQuantizedTileMeshes(q, this.opts.material, this.opts.waterMaterial, this.lmMaterial ?? void 0);
@@ -1146,9 +1347,14 @@ var TileManager = class _TileManager {
1146
1347
  this.attachFade(rec, meshes.terrain, meshes.terrainLm, meshes.water);
1147
1348
  this.minY = Math.min(this.minY, meshes.bounds.min.y);
1148
1349
  this.maxY = Math.max(this.maxY, meshes.bounds.max.y);
1350
+ 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);
1351
+ this.sizeHints.set(key, rec.memoryBytes);
1352
+ this.averageHiresBytes = this.averageHiresBytes * 0.875 + rec.memoryBytes * 0.125;
1149
1353
  rec.state = "built";
1354
+ this.pendingBuilt++;
1150
1355
  this.failCounts.delete(key);
1151
1356
  this.pendingAdd.push(key);
1357
+ this.trimToMemoryBudget();
1152
1358
  this.invalidate();
1153
1359
  this.emitter.emit("change", this.stats);
1154
1360
  } catch (e) {
@@ -1163,6 +1369,7 @@ var TileManager = class _TileManager {
1163
1369
  }
1164
1370
  unload(key, rec) {
1165
1371
  rec.abort?.abort();
1372
+ if (rec.state === "built") this.pendingBuilt--;
1166
1373
  for (const mesh of [rec.terrain, rec.terrainLm, rec.water]) {
1167
1374
  if (!mesh) continue;
1168
1375
  this.opts.scene.remove(mesh);
@@ -1177,6 +1384,30 @@ var TileManager = class _TileManager {
1177
1384
  this.invalidate();
1178
1385
  this.emitter.emit("change", this.stats);
1179
1386
  }
1387
+ /** Correct estimation misses after a tile is decoded. Farthest hires records
1388
+ * leave first; one nearest tile is always kept so an oversized outlier does
1389
+ * not create an unload/refetch loop. Learned weights make the next plan fit. */
1390
+ trimToMemoryBudget() {
1391
+ let total = 0;
1392
+ const hires = [];
1393
+ for (const [key, rec] of this.records) {
1394
+ total += rec.memoryBytes;
1395
+ if (rec.level === 0 && rec.state !== "failed" && rec.state !== "empty") {
1396
+ hires.push({ key, rec, d: this.distSqTo(rec.ref, 0, this.focusX, this.focusZ) });
1397
+ }
1398
+ }
1399
+ if (total <= this.opts.maxBytes || hires.length <= 1) return;
1400
+ hires.sort((a, b) => b.d - a.d);
1401
+ let remaining = hires.length;
1402
+ for (const entry of hires) {
1403
+ if (total <= this.opts.maxBytes || remaining <= 1) break;
1404
+ total -= entry.rec.memoryBytes;
1405
+ remaining--;
1406
+ this.unload(entry.key, entry.rec);
1407
+ }
1408
+ this.lastFocusX = Infinity;
1409
+ this.lastFocusZ = Infinity;
1410
+ }
1180
1411
  invalidate() {
1181
1412
  this.biomesCache = null;
1182
1413
  this.statsCache = null;
@@ -1191,7 +1422,9 @@ var TileManager = class _TileManager {
1191
1422
  let vertexCount = 0;
1192
1423
  let triangleCount = 0;
1193
1424
  let bytes = 0;
1425
+ let residentBytes = 0;
1194
1426
  for (const rec of this.records.values()) {
1427
+ residentBytes += rec.memoryBytes;
1195
1428
  if (rec.state === "ready") {
1196
1429
  if (rec.level === 0) loaded++;
1197
1430
  else lowres++;
@@ -1200,7 +1433,7 @@ var TileManager = class _TileManager {
1200
1433
  bytes += rec.ref.bytes;
1201
1434
  } else if (rec.state === "loading" || rec.state === "built") loading++;
1202
1435
  }
1203
- this.statsCache = { loaded, loading, total: this.index.size, lowres, vertexCount, triangleCount, bytes };
1436
+ this.statsCache = { loaded, loading, total: this.index.size, lowres, vertexCount, triangleCount, bytes, residentBytes };
1204
1437
  return this.statsCache;
1205
1438
  }
1206
1439
  /** Aggregated biome share across every resident tile, most common first. */
@@ -2143,6 +2376,15 @@ var VantageViewer = class _VantageViewer {
2143
2376
  worldSpan = 0;
2144
2377
  tilesUnsub = null;
2145
2378
  lastBiomesEmit = 0;
2379
+ // Progressive render (manifest.rendering): the manager whose live bake we're
2380
+ // polling for, and the atlas layer count last uploaded — a growing count
2381
+ // triggers a texture-array re-fetch. Cleared when the render finishes or the
2382
+ // world reloads (the poll checks its manager is still current).
2383
+ progressiveManager = null;
2384
+ lastTextureLayers = 0;
2385
+ /** An in-flight atlas re-fetch, so the tile-insert gate and the progressive
2386
+ * poll coalesce onto one request instead of racing separate fetches. */
2387
+ atlasRefresh = null;
2146
2388
  // Biome layer state machine.
2147
2389
  biomeEnabled = false;
2148
2390
  highlight = null;
@@ -2288,12 +2530,13 @@ var VantageViewer = class _VantageViewer {
2288
2530
  const waterShader = createWaterMaterial(shader);
2289
2531
  shader.uniforms["uFogRadial"].value = 1;
2290
2532
  const lmShader = manifest.format >= 4 ? createLightmappedMaterial(shader) : void 0;
2291
- const lowresShader = manifest.lowres ? createLowresMaterial(shader) : void 0;
2533
+ const lowresShader = manifest.lowres || manifest.rendering ? createLowresMaterial(shader) : void 0;
2292
2534
  this.shader = shader;
2293
2535
  this.waterShader = waterShader;
2294
2536
  this.lowresShader = lowresShader ?? null;
2295
2537
  this.manifest = manifest;
2296
2538
  this.hasAnims = texData.anims.length > 0;
2539
+ this.lastTextureLayers = manifest.textureLayers ?? texData.layers;
2297
2540
  this.tile = null;
2298
2541
  this.tiles = new TileManager({
2299
2542
  manifest,
@@ -2304,6 +2547,10 @@ var VantageViewer = class _VantageViewer {
2304
2547
  ...lmShader ? { lmMaterial: lmShader } : {},
2305
2548
  ...lowresShader ? { lowresMaterial: lowresShader } : {},
2306
2549
  palette,
2550
+ // A live/progressive render grows its atlas as tiles bake; gate each
2551
+ // tile's insertion on the atlas covering its layers (a no-op once the
2552
+ // atlas is complete). Returns the layer count now loaded.
2553
+ ...manifest.rendering ? { ensureAtlas: (n) => this.ensureAtlasLayers(source, n).then(() => this.lastTextureLayers) } : {},
2307
2554
  ...this.options.streaming
2308
2555
  });
2309
2556
  this.setHeightSampler(this.tiles.heightAt);
@@ -2329,18 +2576,90 @@ var VantageViewer = class _VantageViewer {
2329
2576
  this._biomes = [];
2330
2577
  this.emitter.emit("load", {
2331
2578
  // Streamed worlds: the tile format follows the manifest schema version.
2332
- magic: manifest.format >= 4 ? "VTL8" : manifest.format >= 3 ? "VTL7" : "VTL6",
2579
+ magic: manifest.format >= 5 ? "VTL9" : manifest.format >= 4 ? "VTL8" : manifest.format >= 3 ? "VTL7" : "VTL6",
2333
2580
  vertexCount: 0,
2334
2581
  triangleCount: 0,
2335
2582
  size,
2336
2583
  biomes: this._biomes
2337
2584
  });
2585
+ if (manifest.rendering) {
2586
+ this.progressiveManager = this.tiles;
2587
+ this.emitProgress(manifest);
2588
+ void this.pollProgressive(source, this.tiles);
2589
+ }
2590
+ }
2591
+ /** Emit a `progress` event from a manifest (falling back to the tile count
2592
+ * when the generator didn't include a `progress` block). */
2593
+ emitProgress(m) {
2594
+ this.emitter.emit("progress", {
2595
+ done: m.progress?.done ?? m.tiles.length,
2596
+ total: m.progress?.total ?? m.tiles.length,
2597
+ rendering: m.rendering ?? false
2598
+ });
2338
2599
  }
2339
- /** Frame a streamed world: pivot on the spawn point when the manifest has
2340
- * one (that's where the builds are), else the centre of the tile extents.
2341
- * Distances are tied to the streaming view distance, not the world size —
2342
- * a 100k×100k world frames the same as a village. */
2343
- frameWorld(manifest, view) {
2600
+ /** Follow a live (`rendering: true`) render: re-fetch the manifest on an
2601
+ * interval, stream newly-baked tiles in, widen the texture array when the
2602
+ * atlas grows, and install the lowres pyramid once the bake completes. Runs
2603
+ * until the render finishes or the world is replaced. */
2604
+ async pollProgressive(source, manager) {
2605
+ const dec = new TextDecoder();
2606
+ for (; ; ) {
2607
+ await new Promise((r) => setTimeout(r, 1200));
2608
+ if (this.tiles !== manager || this.progressiveManager !== manager) return;
2609
+ let m;
2610
+ try {
2611
+ m = parseManifest(JSON.parse(dec.decode(await source.fetch("manifest.json"))));
2612
+ } catch {
2613
+ continue;
2614
+ }
2615
+ if ((m.textureLayers ?? 0) > this.lastTextureLayers) {
2616
+ await this.ensureAtlasLayers(source, m.textureLayers ?? 0);
2617
+ if (this.tiles !== manager) return;
2618
+ }
2619
+ manager.addTiles(m.tiles);
2620
+ this.emitProgress(m);
2621
+ if (!m.rendering) {
2622
+ this.manifest = m;
2623
+ if (m.lowres) manager.ingestLowres(m.lowres);
2624
+ this.updateWorldBounds(m);
2625
+ this.applyViewLimits();
2626
+ this.progressiveManager = null;
2627
+ this.needsRender = true;
2628
+ return;
2629
+ }
2630
+ }
2631
+ }
2632
+ /** Ensure the terrain atlas covers at least `layers` texture-array layers,
2633
+ * re-fetching `terrain.vtexarr` if it's behind. Coalesces concurrent callers
2634
+ * — the on-demand tile-insert gate and the progressive poll — onto one
2635
+ * request. Resolves once the atlas is current (or the fetch failed and the
2636
+ * old atlas stands, to be retried by a later gate/poll). */
2637
+ async ensureAtlasLayers(source, layers) {
2638
+ if (this.lastTextureLayers >= layers) return;
2639
+ await (this.atlasRefresh ??= this.refetchAtlas(source));
2640
+ if (this.lastTextureLayers < layers && !this.atlasRefresh) {
2641
+ await (this.atlasRefresh ??= this.refetchAtlas(source));
2642
+ }
2643
+ }
2644
+ /** Re-fetch `terrain.vtexarr` and widen every shared material's atlas (they
2645
+ * share the sampler uniform objects, so one update reaches all). */
2646
+ async refetchAtlas(source) {
2647
+ try {
2648
+ const td = parseTextureArray(await maybeInflate(await source.fetch(this.manifest.textures)));
2649
+ if (!this.shader) return;
2650
+ updateTerrainTextures(this.shader, td);
2651
+ this.hasAnims = td.anims.length > 0;
2652
+ this.lastTextureLayers = Math.max(this.lastTextureLayers, td.layers);
2653
+ this.needsRender = true;
2654
+ } catch {
2655
+ } finally {
2656
+ this.atlasRefresh = null;
2657
+ }
2658
+ }
2659
+ /** Set the world bounds + span from a manifest's tile extents, without moving
2660
+ * the camera. Used to frame a world on load and to widen the extent when a
2661
+ * progressive render finishes and the full size is finally known. */
2662
+ updateWorldBounds(manifest) {
2344
2663
  const tb = manifest.tileBlocks;
2345
2664
  let minX = Infinity;
2346
2665
  let minZ = Infinity;
@@ -2358,6 +2677,17 @@ var VantageViewer = class _VantageViewer {
2358
2677
  }
2359
2678
  this.bounds.set(new THREE2.Vector3(minX, -64, minZ), new THREE2.Vector3(maxX, 320, maxZ));
2360
2679
  this.worldSpan = Math.max(maxX - minX, maxZ - minZ);
2680
+ }
2681
+ /** Frame a streamed world: pivot on the spawn point when the manifest has
2682
+ * one (that's where the builds are), else the centre of the tile extents.
2683
+ * Distances are tied to the streaming view distance, not the world size —
2684
+ * a 100k×100k world frames the same as a village. */
2685
+ frameWorld(manifest, view) {
2686
+ this.updateWorldBounds(manifest);
2687
+ const minX = this.bounds.min.x;
2688
+ const minZ = this.bounds.min.z;
2689
+ const maxX = this.bounds.max.x;
2690
+ const maxZ = this.bounds.max.z;
2361
2691
  const viewDistance = this.tiles?.viewDistance ?? this.options.streaming.viewDistance ?? 768;
2362
2692
  const spawn = manifest.spawn;
2363
2693
  const pivot = spawn ? new THREE2.Vector3(spawn.x, spawn.y, spawn.z) : new THREE2.Vector3((minX + maxX) / 2, 80, (minZ + maxZ) / 2);
@@ -2763,18 +3093,19 @@ var VantageViewer = class _VantageViewer {
2763
3093
  this.needsRender = true;
2764
3094
  }
2765
3095
  // --- streaming -------------------------------------------------------------
2766
- /** The current streaming settings (view distance, tile budget, concurrency). */
3096
+ /** The current streaming settings (view distance, tile/byte budgets, concurrency). */
2767
3097
  get streamingSettings() {
2768
3098
  return {
2769
3099
  viewDistance: this.tiles?.viewDistance ?? this.options.streaming.viewDistance ?? 768,
2770
3100
  maxTiles: this.tiles?.maxTiles ?? this.options.streaming.maxTiles ?? 120,
2771
- concurrency: this.options.streaming.concurrency ?? 4
3101
+ concurrency: this.options.streaming.concurrency ?? 4,
3102
+ maxBytes: this.tiles?.maxBytes ?? this.options.streaming.maxBytes ?? 512 * 1024 * 1024
2772
3103
  };
2773
3104
  }
2774
- /** Live-tune streaming: view distance, resident-tile budget, concurrency.
3105
+ /** Live-tune streaming: view distance, resident tile/byte budgets, concurrency.
2775
3106
  * Applies immediately to a streamed world (tiles re-plan, fog and camera
2776
3107
  * range follow) and persists for future loads. The fidelity dial: raise
2777
- * viewDistance/maxTiles to see farther, lower them on weak hardware. */
3108
+ * viewDistance/maxTiles/maxBytes to see farther, lower them on weak hardware. */
2778
3109
  setStreaming(settings) {
2779
3110
  this.options.streaming = { ...this.options.streaming, ...settings };
2780
3111
  if (!this.tiles) return;
@@ -3052,6 +3383,7 @@ var VantageViewer = class _VantageViewer {
3052
3383
  this.tiles.dispose();
3053
3384
  this.tiles = null;
3054
3385
  this.manifest = null;
3386
+ this.progressiveManager = null;
3055
3387
  }
3056
3388
  if (this.shader) {
3057
3389
  this.shader.uniforms["map"]?.value?.dispose();