@thoughts-on-things/vantage-mc 0.4.0 → 0.6.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.
package/README.md CHANGED
@@ -50,9 +50,12 @@ provides the engine state to children via context. `<BiomeLayer>` adds the
50
50
  interactive biome legend (click to isolate, hover the map to identify, press
51
51
  `B` to toggle) — aggregated live across whatever tiles are resident. Add
52
52
  `<SettingsPanel />` for a quality menu: low/med/high/ultra
53
- presets plus view-distance, tile-budget, render-scale, and haze sliders, all
53
+ presets plus view-distance, tile-count, memory-budget, render-scale, and haze sliders, all
54
54
  applied live (`viewer.setStreaming` re-plans in place, no reload). Or set the
55
- ring up-front with `streaming={{ viewDistance: 1024, maxTiles: 128 }}`.
55
+ ring up-front with
56
+ `streaming={{ viewDistance: 1024, maxTiles: 128, maxBytes: 512 * 1024 * 1024 }}`.
57
+ `maxTiles` is a count guard; `maxBytes` is the stronger residency limit for
58
+ worlds whose tile complexity varies widely.
56
59
 
57
60
  The camera also lives in the URL hash (`#@x,y,z,dist,rot,tilt`), so **every
58
61
  view is a shareable deep link**: the hash follows the camera (debounced,
@@ -70,15 +73,12 @@ scene, or call `viewer.invalidate()` after mutating it externally.
70
73
  `viewer.screenshot()` returns the current view as a PNG data URL (`<MapNav>`
71
74
  has a button for it, next to its fullscreen toggle).
72
75
 
73
- Worlds baked with `vantage render --caves full` unlock the **cave view**: a
74
- depth slice that cuts the world open at any Y — press `C`, click `<MapNav>`'s
75
- layers button, or drag the `<DepthSlider>` gauge that appears on the left
76
- edge. The cut peels open with an eased reveal, a warm rim outlines the
77
- section, unexplored rock reads as a dark chunk-gridded floor, and the slice
78
- depth rides the URL hash (`#@x,y,z,dist,rot,tilt,sliceY`) so cave finds are
79
- shareable links. Engine API: `viewer.setSlice(y | null)`,
80
- `viewer.toggleSlice()`, `viewer.slice`, `viewer.sliceRange`,
81
- `viewer.hasCaves`, and a `'slice'` event.
76
+ Worlds baked with `vantage render --caves full` get the **cave view**: a
77
+ depth slice that cuts the world at any Y. Toggle it with `C` or `<MapNav>`'s
78
+ layers button, set the depth with the `<DepthSlider>` gauge, and share it —
79
+ the slice is part of the URL hash (`#@x,y,z,dist,rot,tilt,sliceY`). Engine
80
+ API: `viewer.setSlice(y | null)`, `viewer.toggleSlice()`, `viewer.slice`,
81
+ `viewer.sliceRange`, `viewer.hasCaves`, and a `'slice'` event.
82
82
 
83
83
  Format-2 manifests carry a **lowres LOD pyramid** (`.vlr` colored
84
84
  heightfields): the viewer keeps coarse rings resident far beyond the hires
@@ -123,7 +123,8 @@ shader!.uniforms.uBiomeMix.value = 1; // recolour by biome
123
123
  ```
124
124
 
125
125
  Or stream a whole world into your scene with `TileManager` (shared materials,
126
- nearest-first fetch queue, distance-based unload, height/biome queries):
126
+ camera-lookahead priority, bounded fetch/decode/upload backpressure,
127
+ byte-weighted residency, height/biome queries):
127
128
 
128
129
  ```ts
129
130
  import { biomePalette, maybeInflate, parseManifest, parseTextureArray } from '@thoughts-on-things/vantage-mc/core';
@@ -139,6 +140,7 @@ const tiles = new TileManager({
139
140
  material,
140
141
  waterMaterial: createWaterMaterial(material),
141
142
  palette: biomePalette(manifest.biomes.length),
143
+ maxBytes: 512 * 1024 * 1024,
142
144
  });
143
145
  // each frame: keep the resident set centred on your camera
144
146
  tiles.update(camera.position.x, camera.position.z);
@@ -152,7 +154,7 @@ import { VantageViewer } from '@thoughts-on-things/vantage-mc/three';
152
154
  const viewer = await VantageViewer.mount('#app', { world: '/manifest.json' });
153
155
  viewer.setBiomeLayer(true);
154
156
  viewer.on('hover', (biomeId) => { /* ... */ });
155
- viewer.on('stats', ({ loaded, triangleCount }) => { /* streaming HUD */ });
157
+ viewer.on('stats', ({ loaded, triangleCount, residentBytes }) => { /* streaming HUD */ });
156
158
  ```
157
159
 
158
160
  ## Just the format
@@ -19,6 +19,9 @@ declare const TILE_MAGIC: {
19
19
  * light/AO from a texture instead of vertices, so lighting gradients no
20
20
  * longer fragment greedy merges (~23% fewer vertices). */
21
21
  readonly VTL8: "VTL8";
22
+ /** VTL8 geometry + a losslessly packed RG8 lightmap (sky/block nibbles,
23
+ * full-byte AO), stored as gzip-friendly planes. */
24
+ readonly VTL9: "VTL9";
22
25
  };
23
26
  type TileMagic = (typeof TILE_MAGIC)[keyof typeof TILE_MAGIC];
24
27
  /** VTL7 UV fixed-point steps per texture unit (uv = stored / UV_SCALE). */
@@ -77,10 +80,10 @@ interface MeshSection {
77
80
  /** `vertexCount` packed saved light `(sky << 4) | block` (each 0..15), carried
78
81
  * in the normal's spare 4th byte. Textured tiles only. */
79
82
  light?: Uint8Array;
80
- /** VTL8: the first vertex of the atlas-lit tail (== vertexCount when the
83
+ /** VTL8+: the first vertex of the atlas-lit tail (== vertexCount when the
81
84
  * whole section is vertex-lit). */
82
85
  lmStart?: number;
83
- /** VTL8: the tail's lightmap UVs in half-texel units (delta coding undone). */
86
+ /** VTL8+: the tail's lightmap UVs in half-texel units (delta coding undone). */
84
87
  lmuv?: Uint16Array;
85
88
  }
86
89
  /**
@@ -117,7 +120,7 @@ interface DecodedTile extends MeshSection {
117
120
  fluid?: MeshSection;
118
121
  /** Top-down surface map for picking (VTL5+). */
119
122
  surface?: SurfaceMap;
120
- /** The baked light+AO atlas (VTL8 with atlas-lit geometry only). */
123
+ /** The baked light+AO atlas (VTL8+ with atlas-lit geometry only). */
121
124
  lightmap?: Lightmap;
122
125
  }
123
126
  /**
@@ -154,37 +157,39 @@ interface QuantizedSection {
154
157
  * topology `[b,b+1,b+2, b,b+2,b+3]` the renderer derives (and shares one
155
158
  * GPU index buffer across every tile). */
156
159
  indices: Uint32Array | null;
157
- /** VTL8: the first vertex of the atlas-lit tail (== vertexCount when the
160
+ /** VTL8+: the first vertex of the atlas-lit tail (== vertexCount when the
158
161
  * whole section is vertex-lit). */
159
162
  lmStart?: number;
160
- /** VTL8: the tail's lightmap UVs in half-texel units, `2 * (vertexCount -
163
+ /** VTL8+: the tail's lightmap UVs in half-texel units, `2 * (vertexCount -
161
164
  * lmStart)` values (delta coding already undone). */
162
165
  lmuv?: Uint16Array;
163
166
  }
164
- /** A VTL8 tile's baked light+AO atlas, interleaved RGBA (R sky, G block,
165
- * B AO, A 255) ready for texture upload; sample bilinearly. */
167
+ /** A tile's baked light+AO atlas. VTL8 expands its planar payload to RGBA;
168
+ * VTL9 interleaves its packed-light/AO planes into a compact RG8 upload. */
166
169
  interface Lightmap {
167
170
  width: number;
168
171
  height: number;
169
- /** `4 * width * height` RGBA bytes. */
172
+ /** True for VTL9's two-byte RG8 representation. */
173
+ packed: boolean;
174
+ /** RGBA bytes when unpacked; interleaved packed-light/AO bytes otherwise. */
170
175
  pixels: Uint8Array<ArrayBuffer>;
171
176
  }
172
- /** A VTL6/7/8 tile decoded without dequantization (see {@link QuantizedSection}). */
177
+ /** A VTL6/7/8/9 tile decoded without dequantization (see {@link QuantizedSection}). */
173
178
  interface QuantizedTile {
174
- magic: 'VTL6' | 'VTL7' | 'VTL8';
179
+ magic: 'VTL6' | 'VTL7' | 'VTL8' | 'VTL9';
175
180
  version: number;
176
181
  solid: QuantizedSection;
177
182
  fluid: QuantizedSection;
178
183
  surface: SurfaceMap;
179
184
  biomeNames: string[];
180
- /** The baked light+AO atlas (VTL8 with atlas-lit geometry only). */
185
+ /** The baked light+AO atlas (VTL8+ with atlas-lit geometry only). */
181
186
  lightmap?: Lightmap;
182
187
  }
183
188
  /** The canonical quad index pattern for `vertexCount` vertices (4 verts / 6
184
189
  * indices per face) — the topology every Vantage mesher emits. */
185
190
  declare function canonicalQuadIndices(vertexCount: number): Uint32Array;
186
191
  /**
187
- * Decode a VTL6/7 `.vtile` in its quantized on-disk encoding: arrays are
192
+ * Decode a VTL6+ `.vtile` in its quantized on-disk encoding: arrays are
188
193
  * zero-copy views (VTL7 positions take one linear delta-decode pass) and stay
189
194
  * u16/i16 for the vertex shader to dequantize (the streaming fast path — no
190
195
  * per-vertex float expansion). Returns `null` for any other tile version;
@@ -251,7 +256,7 @@ interface LowresLevel {
251
256
  /** A parsed `manifest.json` for a tiled world render. */
252
257
  interface WorldManifest {
253
258
  /** Manifest schema version (1 = hires tiles only, 2 adds `lowres`,
254
- * 3 = VTL7 compact tiles + `maxSectionVerts`). */
259
+ * 3 = VTL7 compact tiles, 4 = lightmaps, 5 = packed RG8 lightmaps). */
255
260
  format: number;
256
261
  /** Largest per-section vertex count across every tile (format 3+) — sizes
257
262
  * the renderer's one shared quad index buffer before the first tile lands. */
@@ -280,6 +285,22 @@ interface WorldManifest {
280
285
  /** Biome display names indexed by the per-vertex biome id (0 = no data).
281
286
  * Globally consistent across every tile of the render. */
282
287
  biomes: string[];
288
+ /** True while a progressive render is still baking: the manifest grows and
289
+ * the viewer polls it, streaming new tiles in as they land. Absent/false in
290
+ * a finished render. */
291
+ rendering?: boolean;
292
+ /** True for an on-demand live server (`vantage live`): every populated tile
293
+ * is listed up front but baked lazily on first fetch. Implies `rendering`;
294
+ * the viewer gates each tile's insertion on the atlas covering its layers. */
295
+ dynamic?: boolean;
296
+ /** Tiles finished / total, for a live progress readout (progressive only). */
297
+ progress?: {
298
+ done: number;
299
+ total: number;
300
+ };
301
+ /** Atlas layer count backing `textures`. When it grows between progressive
302
+ * polls, the viewer re-fetches the texture array (layers are append-only). */
303
+ textureLayers?: number;
283
304
  /** Every rendered tile. */
284
305
  tiles: ManifestTile[];
285
306
  /** The lowres LOD pyramid (format 2+): coarse whole-world tiles the viewer