@thoughts-on-things/vantage-mc 0.2.0 → 0.4.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
@@ -61,6 +61,25 @@ pasting a new hash into the address bar pans there live. Pass
61
61
  `urlState={false}` if your page owns its hash (e.g. a router); the plain
62
62
  engine keeps it opt-in (`new VantageViewer(el, { urlState: true })`).
63
63
 
64
+ The viewer **renders on demand**: a frame draws only when something changed —
65
+ camera motion, tiles streaming in, a setting — plus a gentle 10 fps tick while
66
+ animated textures (water, lava) are on screen, so an idle map costs ~0 GPU/CPU
67
+ instead of a render loop. Input still draws the same frame it arrives. Pass
68
+ `renderOnDemand: false` to the engine if you drive per-frame effects off its
69
+ scene, or call `viewer.invalidate()` after mutating it externally.
70
+ `viewer.screenshot()` returns the current view as a PNG data URL (`<MapNav>`
71
+ has a button for it, next to its fullscreen toggle).
72
+
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.
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
@@ -173,7 +192,7 @@ returns only the fields a given version carries (`textured`, `hasBiome`, `fluid`
173
192
  `TileInfo`, `ViewMode`. Re-exports all of `core`.
174
193
 
175
194
  **`@thoughts-on-things/vantage-mc/react`** — `<VantageViewer>`, `<BiomeLayer>`, `<SettingsPanel>`,
176
- `<LightPanel>`, `<MapNav>`, `<Reticle>`, `<Panel>`, `useVantage`,
195
+ `<LightPanel>`, `<MapNav>`, `<DepthSlider>`, `<Reticle>`, `<Panel>`, `useVantage`,
177
196
  `injectStyles`, `QUALITY_PRESETS`; types `VantageViewerProps`,
178
197
  `BiomeLayerProps`, `SettingsPanelProps`, `VantageContextValue`,
179
198
  `VantageStatus`. Re-exports the engine and core types.
@@ -12,8 +12,17 @@ declare const TILE_MAGIC: {
12
12
  readonly VTL5: "VTL5";
13
13
  /** Quantized vertices: u16 positions (bbox transform) + u16 layer/biome. */
14
14
  readonly VTL6: "VTL6";
15
+ /** Compact quads: no index array (canonical quad topology is derived),
16
+ * delta-coded u16 positions, i16 fixed-point UV. */
17
+ readonly VTL7: "VTL7";
18
+ /** + a per-tile lightmap atlas: the greedy vertex tail samples baked
19
+ * light/AO from a texture instead of vertices, so lighting gradients no
20
+ * longer fragment greedy merges (~23% fewer vertices). */
21
+ readonly VTL8: "VTL8";
15
22
  };
16
23
  type TileMagic = (typeof TILE_MAGIC)[keyof typeof TILE_MAGIC];
24
+ /** VTL7 UV fixed-point steps per texture unit (uv = stored / UV_SCALE). */
25
+ declare const UV_SCALE = 128;
17
26
  /** Texture-array magic. */
18
27
  declare const TEXTURE_MAGIC: "VTA1";
19
28
  /**
@@ -68,6 +77,11 @@ interface MeshSection {
68
77
  /** `vertexCount` packed saved light `(sky << 4) | block` (each 0..15), carried
69
78
  * in the normal's spare 4th byte. Textured tiles only. */
70
79
  light?: Uint8Array;
80
+ /** VTL8: the first vertex of the atlas-lit tail (== vertexCount when the
81
+ * whole section is vertex-lit). */
82
+ lmStart?: number;
83
+ /** VTL8: the tail's lightmap UVs in half-texel units (delta coding undone). */
84
+ lmuv?: Uint16Array;
71
85
  }
72
86
  /**
73
87
  * A top-down surface map (VTL5): one column per XZ cell over a world-space
@@ -103,6 +117,8 @@ interface DecodedTile extends MeshSection {
103
117
  fluid?: MeshSection;
104
118
  /** Top-down surface map for picking (VTL5+). */
105
119
  surface?: SurfaceMap;
120
+ /** The baked light+AO atlas (VTL8 with atlas-lit geometry only). */
121
+ lightmap?: Lightmap;
106
122
  }
107
123
  /**
108
124
  * A VTL6 mesh section kept in its on-disk quantized encoding: every array is a
@@ -120,8 +136,11 @@ interface QuantizedSection {
120
136
  posMin: [number, number, number];
121
137
  /** World units per quantization step, per axis. */
122
138
  posScale: [number, number, number];
123
- /** `2 * vertexCount` texture coordinates. */
124
- uv: Float32Array;
139
+ /** `2 * vertexCount` texture coordinates — f32 (VTL6) or i16 fixed point
140
+ * (VTL7); multiply by {@link QuantizedSection.uvScale} for texture units. */
141
+ uv: Float32Array | Int16Array;
142
+ /** Texture units per stored uv step (1 for f32, 1/128 for VTL7's i16). */
143
+ uvScale: number;
125
144
  /** `4 * vertexCount` RGBA: tint RGB + packed AO/alpha. */
126
145
  colors: Uint8Array;
127
146
  /** `4 * vertexCount` int8: xyz normal + the packed light byte as the 4th
@@ -131,23 +150,45 @@ interface QuantizedSection {
131
150
  layer: Uint16Array;
132
151
  /** `vertexCount` u16 biome ids. */
133
152
  biome: Uint16Array;
134
- /** `indexCount` triangle indices. */
135
- indices: Uint32Array;
153
+ /** `indexCount` triangle indices — `null` for VTL7+, whose canonical quad
154
+ * topology `[b,b+1,b+2, b,b+2,b+3]` the renderer derives (and shares one
155
+ * GPU index buffer across every tile). */
156
+ indices: Uint32Array | null;
157
+ /** VTL8: the first vertex of the atlas-lit tail (== vertexCount when the
158
+ * whole section is vertex-lit). */
159
+ lmStart?: number;
160
+ /** VTL8: the tail's lightmap UVs in half-texel units, `2 * (vertexCount -
161
+ * lmStart)` values (delta coding already undone). */
162
+ lmuv?: Uint16Array;
136
163
  }
137
- /** A VTL6 tile decoded without dequantization (see {@link QuantizedSection}). */
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. */
166
+ interface Lightmap {
167
+ width: number;
168
+ height: number;
169
+ /** `4 * width * height` RGBA bytes. */
170
+ pixels: Uint8Array<ArrayBuffer>;
171
+ }
172
+ /** A VTL6/7/8 tile decoded without dequantization (see {@link QuantizedSection}). */
138
173
  interface QuantizedTile {
139
- magic: 'VTL6';
174
+ magic: 'VTL6' | 'VTL7' | 'VTL8';
140
175
  version: number;
141
176
  solid: QuantizedSection;
142
177
  fluid: QuantizedSection;
143
178
  surface: SurfaceMap;
144
179
  biomeNames: string[];
180
+ /** The baked light+AO atlas (VTL8 with atlas-lit geometry only). */
181
+ lightmap?: Lightmap;
145
182
  }
183
+ /** The canonical quad index pattern for `vertexCount` vertices (4 verts / 6
184
+ * indices per face) — the topology every Vantage mesher emits. */
185
+ declare function canonicalQuadIndices(vertexCount: number): Uint32Array;
146
186
  /**
147
- * Decode a VTL6 `.vtile` in its quantized on-disk encoding: every array is a
148
- * zero-copy view and positions/layer/biome stay u16 for the vertex shader to
149
- * dequantize (the streaming fast path — no per-vertex CPU work). Returns `null`
150
- * for any other tile version; callers fall back to {@link parseTile}.
187
+ * Decode a VTL6/7 `.vtile` in its quantized on-disk encoding: arrays are
188
+ * zero-copy views (VTL7 positions take one linear delta-decode pass) and stay
189
+ * u16/i16 for the vertex shader to dequantize (the streaming fast path — no
190
+ * per-vertex float expansion). Returns `null` for any other tile version;
191
+ * callers fall back to {@link parseTile}.
151
192
  */
152
193
  declare function parseTileQuantized(buffer: ArrayBuffer): QuantizedTile | null;
153
194
  /**
@@ -209,8 +250,12 @@ interface LowresLevel {
209
250
  }
210
251
  /** A parsed `manifest.json` for a tiled world render. */
211
252
  interface WorldManifest {
212
- /** Manifest schema version (1 = hires tiles only, 2 adds `lowres`). */
253
+ /** Manifest schema version (1 = hires tiles only, 2 adds `lowres`,
254
+ * 3 = VTL7 compact tiles + `maxSectionVerts`). */
213
255
  format: number;
256
+ /** Largest per-section vertex count across every tile (format 3+) — sizes
257
+ * the renderer's one shared quad index buffer before the first tile lands. */
258
+ maxSectionVerts?: number;
214
259
  /** Tile span in chunks per side. */
215
260
  tileChunks: number;
216
261
  /** Tile span in blocks per side (= tileChunks · 16). */
@@ -223,6 +268,15 @@ interface WorldManifest {
223
268
  y: number;
224
269
  z: number;
225
270
  };
271
+ /** True when the render kept full cave geometry (`--caves full`) — the
272
+ * viewer's depth-slice cave view has real caves to reveal. */
273
+ caves?: boolean;
274
+ /** World-Y extent across all tiles (min inclusive, max exclusive) — the
275
+ * bounds for the cave view's depth slider. */
276
+ yRange?: {
277
+ min: number;
278
+ max: number;
279
+ };
226
280
  /** Biome display names indexed by the per-vertex biome id (0 = no data).
227
281
  * Globally consistent across every tile of the render. */
228
282
  biomes: string[];
@@ -318,4 +372,4 @@ declare function summarizeSurfaceBiomes(surface: SurfaceMap, names: string[], pa
318
372
  */
319
373
  declare function summarizeBiomes(tile: DecodedTile, palette?: Rgb[]): BiomeEntry[];
320
374
 
321
- export { type BiomeEntry as B, type DecodedTile as D, type LowresLevel as L, type ManifestTile as M, type QuantizedTile as Q, type Rgb as R, type SurfaceMap as S, TEXTURE_MAGIC as T, type WorldFetch as W, type DecodedTextureArray as a, ByteReader as b, type MeshSection as c, type QuantizedSection as d, TILE_MAGIC as e, type TextureAnimation as f, type TileMagic as g, type WorldManifest as h, type WorldSource as i, biomePalette as j, parseTextureArray as k, parseTile as l, parseTileQuantized as m, summarizeBiomes as n, summarizeSurfaceBiomes as o, parseManifest as p, worldFromFiles as q, worldFromUrl as r, stripNamespace as s, tileKey as t, worldFromDirectory as w };
375
+ export { type BiomeEntry as B, type DecodedTile as D, type Lightmap as L, type ManifestTile as M, type QuantizedTile as Q, type Rgb as R, type SurfaceMap as S, TEXTURE_MAGIC as T, UV_SCALE as U, type WorldFetch as W, type DecodedTextureArray as a, ByteReader as b, type LowresLevel as c, type MeshSection as d, type QuantizedSection as e, TILE_MAGIC as f, type TextureAnimation as g, type TileMagic as h, type WorldManifest as i, type WorldSource as j, biomePalette as k, canonicalQuadIndices as l, parseTextureArray as m, parseTile as n, parseTileQuantized as o, parseManifest as p, summarizeBiomes as q, summarizeSurfaceBiomes as r, stripNamespace as s, tileKey as t, worldFromFiles as u, worldFromUrl as v, worldFromDirectory as w };