@thoughts-on-things/vantage-mc 0.3.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.
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,
@@ -61,6 +64,22 @@ pasting a new hash into the address bar pans there live. Pass
61
64
  `urlState={false}` if your page owns its hash (e.g. a router); the plain
62
65
  engine keeps it opt-in (`new VantageViewer(el, { urlState: true })`).
63
66
 
67
+ The viewer **renders on demand**: a frame draws only when something changed —
68
+ camera motion, tiles streaming in, a setting — plus a gentle 10 fps tick while
69
+ animated textures (water, lava) are on screen, so an idle map costs ~0 GPU/CPU
70
+ instead of a render loop. Input still draws the same frame it arrives. Pass
71
+ `renderOnDemand: false` to the engine if you drive per-frame effects off its
72
+ scene, or call `viewer.invalidate()` after mutating it externally.
73
+ `viewer.screenshot()` returns the current view as a PNG data URL (`<MapNav>`
74
+ has a button for it, next to its fullscreen toggle).
75
+
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
+
64
83
  Format-2 manifests carry a **lowres LOD pyramid** (`.vlr` colored
65
84
  heightfields): the viewer keeps coarse rings resident far beyond the hires
66
85
  disc — level 1 also underlays it as a loading placeholder — so the whole world
@@ -104,7 +123,8 @@ shader!.uniforms.uBiomeMix.value = 1; // recolour by biome
104
123
  ```
105
124
 
106
125
  Or stream a whole world into your scene with `TileManager` (shared materials,
107
- 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):
108
128
 
109
129
  ```ts
110
130
  import { biomePalette, maybeInflate, parseManifest, parseTextureArray } from '@thoughts-on-things/vantage-mc/core';
@@ -120,6 +140,7 @@ const tiles = new TileManager({
120
140
  material,
121
141
  waterMaterial: createWaterMaterial(material),
122
142
  palette: biomePalette(manifest.biomes.length),
143
+ maxBytes: 512 * 1024 * 1024,
123
144
  });
124
145
  // each frame: keep the resident set centred on your camera
125
146
  tiles.update(camera.position.x, camera.position.z);
@@ -133,7 +154,7 @@ import { VantageViewer } from '@thoughts-on-things/vantage-mc/three';
133
154
  const viewer = await VantageViewer.mount('#app', { world: '/manifest.json' });
134
155
  viewer.setBiomeLayer(true);
135
156
  viewer.on('hover', (biomeId) => { /* ... */ });
136
- viewer.on('stats', ({ loaded, triangleCount }) => { /* streaming HUD */ });
157
+ viewer.on('stats', ({ loaded, triangleCount, residentBytes }) => { /* streaming HUD */ });
137
158
  ```
138
159
 
139
160
  ## Just the format
@@ -173,7 +194,7 @@ returns only the fields a given version carries (`textured`, `hasBiome`, `fluid`
173
194
  `TileInfo`, `ViewMode`. Re-exports all of `core`.
174
195
 
175
196
  **`@thoughts-on-things/vantage-mc/react`** — `<VantageViewer>`, `<BiomeLayer>`, `<SettingsPanel>`,
176
- `<LightPanel>`, `<MapNav>`, `<Reticle>`, `<Panel>`, `useVantage`,
197
+ `<LightPanel>`, `<MapNav>`, `<DepthSlider>`, `<Reticle>`, `<Panel>`, `useVantage`,
177
198
  `injectStyles`, `QUALITY_PRESETS`; types `VantageViewerProps`,
178
199
  `BiomeLayerProps`, `SettingsPanelProps`, `VantageContextValue`,
179
200
  `VantageStatus`. Re-exports the engine and core types.
@@ -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. */
@@ -268,9 +273,34 @@ interface WorldManifest {
268
273
  y: number;
269
274
  z: number;
270
275
  };
276
+ /** True when the render kept full cave geometry (`--caves full`) — the
277
+ * viewer's depth-slice cave view has real caves to reveal. */
278
+ caves?: boolean;
279
+ /** World-Y extent across all tiles (min inclusive, max exclusive) — the
280
+ * bounds for the cave view's depth slider. */
281
+ yRange?: {
282
+ min: number;
283
+ max: number;
284
+ };
271
285
  /** Biome display names indexed by the per-vertex biome id (0 = no data).
272
286
  * Globally consistent across every tile of the render. */
273
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;
274
304
  /** Every rendered tile. */
275
305
  tiles: ManifestTile[];
276
306
  /** The lowres LOD pyramid (format 2+): coarse whole-world tiles the viewer