@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 +26 -5
- package/dist/{biome-CPP37ieY.d.ts → biome-NBWIY7dT.d.ts} +43 -13
- package/dist/{chunk-C7GIMQYZ.js → chunk-46RBFJ4D.js} +731 -78
- package/dist/{chunk-M6KVJXCR.js → chunk-EVPUXVSB.js} +46 -13
- package/dist/core/index.d.ts +1 -1
- package/dist/core/index.js +1 -1
- package/dist/react/index.d.ts +29 -8
- package/dist/react/index.js +262 -22
- package/dist/three/index.d.ts +6 -6
- package/dist/three/index.js +2 -2
- package/dist/{viewer-GsEn9RpF.d.ts → viewer-C5vYxrL1.d.ts} +178 -11
- package/package.json +10 -6
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
165
|
-
*
|
|
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
|
-
/**
|
|
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
|
|
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
|
|
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
|