@thoughts-on-things/vantage-mc 0.1.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/LICENSE +21 -0
- package/README.md +200 -0
- package/dist/biome-LCQwACRa.d.ts +275 -0
- package/dist/chunk-7V27NYZD.js +2605 -0
- package/dist/chunk-X7ZJUHP2.js +483 -0
- package/dist/core/index.d.ts +39 -0
- package/dist/core/index.js +1 -0
- package/dist/react/index.d.ts +157 -0
- package/dist/react/index.js +715 -0
- package/dist/three/index.d.ts +110 -0
- package/dist/three/index.js +2 -0
- package/dist/viewer-DkAMDMtW.d.ts +628 -0
- package/package.json +91 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ThoughtsOnThings LLC
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# @thoughts-on-things/vantage-mc
|
|
2
|
+
|
|
3
|
+
The web frontend for [Vantage](../README.md) — render a Minecraft (Java) world as
|
|
4
|
+
a fast, beautiful, navigable 3D map in the browser. The native Zig generator bakes
|
|
5
|
+
versioned binary tiles (`.vtile` / `.vtexarr`); this package streams and shades
|
|
6
|
+
them with three.js.
|
|
7
|
+
|
|
8
|
+
It ships in three layers so you can enter at whatever altitude you need:
|
|
9
|
+
|
|
10
|
+
| Import | What it is | Depends on |
|
|
11
|
+
| --- | --- | --- |
|
|
12
|
+
| `@thoughts-on-things/vantage-mc/core` | Zero-dependency, isomorphic decoder for the binary tile format | — |
|
|
13
|
+
| `@thoughts-on-things/vantage-mc/three` (also the default package export) | three.js meshes/materials + a framework-agnostic viewer engine | `three` |
|
|
14
|
+
| `@thoughts-on-things/vantage-mc/react` | Drop-in React components | `three`, `react` |
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
```sh
|
|
19
|
+
npm install @thoughts-on-things/vantage-mc three
|
|
20
|
+
npm install react react-dom # if you use the React entry point
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
`three`, `react`, and `react-dom` are peer dependencies — you bring your own.
|
|
24
|
+
The package is ESM-only: CJS consumers need `"type": "module"` or a dynamic
|
|
25
|
+
`import()`.
|
|
26
|
+
|
|
27
|
+
## Quick start (React)
|
|
28
|
+
|
|
29
|
+
The whole map in one component. Point it at the manifest the generator produced
|
|
30
|
+
(`just render <save>` writes `manifest.json` + `tiles/` + the texture array to
|
|
31
|
+
`web/public/`). Tiles stream in around the camera as the user pans — world size
|
|
32
|
+
doesn't matter.
|
|
33
|
+
|
|
34
|
+
```tsx
|
|
35
|
+
import { VantageViewer, BiomeLayer } from '@thoughts-on-things/vantage-mc/react';
|
|
36
|
+
|
|
37
|
+
export function Map() {
|
|
38
|
+
return (
|
|
39
|
+
<div style={{ width: '100%', height: '100vh' }}>
|
|
40
|
+
<VantageViewer world="/manifest.json">
|
|
41
|
+
<BiomeLayer legend hover />
|
|
42
|
+
</VantageViewer>
|
|
43
|
+
</div>
|
|
44
|
+
);
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
`<VantageViewer>` fills its parent, frames the world at its spawn point, and
|
|
49
|
+
provides the engine state to children via context. `<BiomeLayer>` adds the
|
|
50
|
+
interactive biome legend (click to isolate, hover the map to identify, press
|
|
51
|
+
`B` to toggle) — aggregated live across whatever tiles are resident. Add
|
|
52
|
+
`<SettingsPanel />` for a quality menu: low/med/high/ultra
|
|
53
|
+
presets plus view-distance, tile-budget, render-scale, and haze sliders, all
|
|
54
|
+
applied live (`viewer.setStreaming` re-plans in place, no reload). Or set the
|
|
55
|
+
ring up-front with `streaming={{ viewDistance: 1024, maxTiles: 128 }}`.
|
|
56
|
+
|
|
57
|
+
The camera also lives in the URL hash (`#@x,y,z,dist,rot,tilt`), so **every
|
|
58
|
+
view is a shareable deep link**: the hash follows the camera (debounced,
|
|
59
|
+
`history.replaceState` — no history spam), a link opens at its saved view, and
|
|
60
|
+
pasting a new hash into the address bar pans there live. Pass
|
|
61
|
+
`urlState={false}` if your page owns its hash (e.g. a router); the plain
|
|
62
|
+
engine keeps it opt-in (`new VantageViewer(el, { urlState: true })`).
|
|
63
|
+
|
|
64
|
+
Format-2 manifests carry a **lowres LOD pyramid** (`.vlr` colored
|
|
65
|
+
heightfields): the viewer keeps coarse rings resident far beyond the hires
|
|
66
|
+
disc — level 1 also underlays it as a loading placeholder — so the whole world
|
|
67
|
+
stays visible at any zoom, right out to a satellite view.
|
|
68
|
+
|
|
69
|
+
A single standalone tile (from `vantage meshtex`) still works:
|
|
70
|
+
|
|
71
|
+
```tsx
|
|
72
|
+
<VantageViewer tile="/terrain.vtile" textures="/terrain.vtexarr" />
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Reach the engine for custom UI with the `useVantage()` hook or a `ref`:
|
|
76
|
+
|
|
77
|
+
```tsx
|
|
78
|
+
import { useVantage } from '@thoughts-on-things/vantage-mc/react';
|
|
79
|
+
|
|
80
|
+
function Stats() {
|
|
81
|
+
const { info, biomes, hoveredBiome } = useVantage();
|
|
82
|
+
return <span>{info?.triangleCount.toLocaleString()} tris · {biomes.length} biomes</span>;
|
|
83
|
+
}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
## As a backend — your own three.js scene
|
|
87
|
+
|
|
88
|
+
Skip the engine and drop Vantage meshes into a scene you control (your own
|
|
89
|
+
camera, lighting, post-processing):
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
import { maybeInflate, parseTile, parseTextureArray } from '@thoughts-on-things/vantage-mc/core';
|
|
93
|
+
import { buildTerrain } from '@thoughts-on-things/vantage-mc/three';
|
|
94
|
+
|
|
95
|
+
const tile = parseTile(await maybeInflate(await (await fetch('/tiles/t.0.0.vtile')).arrayBuffer()));
|
|
96
|
+
const tex = parseTextureArray(await maybeInflate(await (await fetch('/terrain.vtexarr')).arrayBuffer()));
|
|
97
|
+
|
|
98
|
+
const { terrain, water, bounds, shader } = buildTerrain(tile, tex);
|
|
99
|
+
scene.add(terrain);
|
|
100
|
+
if (water) scene.add(water);
|
|
101
|
+
|
|
102
|
+
// `shader` exposes the live uniforms: biome mix, fog, light direction.
|
|
103
|
+
shader!.uniforms.uBiomeMix.value = 1; // recolour by biome
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Or stream a whole world into your scene with `TileManager` (shared materials,
|
|
107
|
+
nearest-first fetch queue, distance-based unload, height/biome queries):
|
|
108
|
+
|
|
109
|
+
```ts
|
|
110
|
+
import { biomePalette, maybeInflate, parseManifest, parseTextureArray } from '@thoughts-on-things/vantage-mc/core';
|
|
111
|
+
import { createTerrainMaterial, createWaterMaterial, TileManager } from '@thoughts-on-things/vantage-mc/three';
|
|
112
|
+
|
|
113
|
+
const manifest = parseManifest(await (await fetch('/manifest.json')).json());
|
|
114
|
+
const tex = parseTextureArray(await maybeInflate(await (await fetch(manifest.textures)).arrayBuffer()));
|
|
115
|
+
const material = createTerrainMaterial(tex);
|
|
116
|
+
const tiles = new TileManager({
|
|
117
|
+
manifest,
|
|
118
|
+
baseUrl: location.origin + '/',
|
|
119
|
+
scene,
|
|
120
|
+
material,
|
|
121
|
+
waterMaterial: createWaterMaterial(material),
|
|
122
|
+
palette: biomePalette(manifest.biomes.length),
|
|
123
|
+
});
|
|
124
|
+
// each frame: keep the resident set centred on your camera
|
|
125
|
+
tiles.update(camera.position.x, camera.position.z);
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
Or the batteries-included engine without React:
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
import { VantageViewer } from '@thoughts-on-things/vantage-mc/three';
|
|
132
|
+
|
|
133
|
+
const viewer = await VantageViewer.mount('#app', { world: '/manifest.json' });
|
|
134
|
+
viewer.setBiomeLayer(true);
|
|
135
|
+
viewer.on('hover', (biomeId) => { /* ... */ });
|
|
136
|
+
viewer.on('stats', ({ loaded, triangleCount }) => { /* streaming HUD */ });
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## Just the format
|
|
140
|
+
|
|
141
|
+
`@thoughts-on-things/vantage-mc/core` has no dependencies and runs anywhere (browser, worker, Node) —
|
|
142
|
+
use it to inspect or transcode tiles without a renderer:
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
import { parseTile, summarizeBiomes } from '@thoughts-on-things/vantage-mc/core';
|
|
146
|
+
|
|
147
|
+
const tile = parseTile(buffer);
|
|
148
|
+
console.log(tile.magic, tile.vertexCount, tile.indexCount / 3, 'tris');
|
|
149
|
+
for (const b of summarizeBiomes(tile)) console.log(b.label, `${Math.round(b.fraction * 100)}%`);
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
The decoder handles every tile version the generator emits (`VTL1`–`VTL6`) and
|
|
153
|
+
returns only the fields a given version carries (`textured`, `hasBiome`, `fluid`,
|
|
154
|
+
`surface`). Tiles and the texture array ship gzip-wrapped on disk (~8× smaller);
|
|
155
|
+
`maybeInflate` sniffs the magic and inflates via the platform's native
|
|
156
|
+
`DecompressionStream` — a no-op when the server already handled it.
|
|
157
|
+
|
|
158
|
+
## API surface
|
|
159
|
+
|
|
160
|
+
**`@thoughts-on-things/vantage-mc/core`** — `parseTile`, `parseTextureArray`, `parseManifest`,
|
|
161
|
+
`parseLowresTile`, `maybeInflate`, `isGzip`, `tileKey`, `summarizeBiomes`,
|
|
162
|
+
`biomePalette`, `stripNamespace`, `ByteReader`; types `DecodedTile`,
|
|
163
|
+
`MeshSection`, `SurfaceMap`, `DecodedTextureArray`, `WorldManifest`,
|
|
164
|
+
`ManifestTile`, `LowresTile`, `BiomeEntry`, `Rgb`.
|
|
165
|
+
|
|
166
|
+
**`@thoughts-on-things/vantage-mc/three`** — `buildTerrain`, `buildTileMeshes`,
|
|
167
|
+
`buildQuantizedTileMeshes`, `buildLowresMesh`, `TileManager`,
|
|
168
|
+
`createTerrainMaterial`, `createWaterMaterial`, `createLowresMaterial`,
|
|
169
|
+
`createSky`, `pickBiome`, `MapControls`, `VantageViewer` (engine),
|
|
170
|
+
`VANILLA_DISPLAY`, `DEFAULT_ORBIT_ANGLE`; types `TerrainObjects`,
|
|
171
|
+
`TileMeshes`, `TileManagerOptions`, `TileStats`, `VantageViewerOptions`,
|
|
172
|
+
`LoadOptions`, `StreamingSettings`, `LightSettings`, `DisplaySettings`,
|
|
173
|
+
`TileInfo`, `ViewMode`. Re-exports all of `core`.
|
|
174
|
+
|
|
175
|
+
**`@thoughts-on-things/vantage-mc/react`** — `<VantageViewer>`, `<BiomeLayer>`, `<SettingsPanel>`,
|
|
176
|
+
`<LightPanel>`, `<MapNav>`, `<Reticle>`, `<Panel>`, `useVantage`,
|
|
177
|
+
`injectStyles`, `QUALITY_PRESETS`; types `VantageViewerProps`,
|
|
178
|
+
`BiomeLayerProps`, `SettingsPanelProps`, `VantageContextValue`,
|
|
179
|
+
`VantageStatus`. Re-exports the engine and core types.
|
|
180
|
+
|
|
181
|
+
## Develop
|
|
182
|
+
|
|
183
|
+
This directory is both the published package and its demo (the reference
|
|
184
|
+
consumer in [`demo/`](./demo/main.tsx)).
|
|
185
|
+
|
|
186
|
+
```sh
|
|
187
|
+
npm install
|
|
188
|
+
npm run dev # Vite dev server at http://127.0.0.1:8753 (serves public/)
|
|
189
|
+
npm run typecheck # tsc --noEmit
|
|
190
|
+
npm run build # tsup → dist/ (ESM + .d.ts for each entry)
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
From the repo root the [`Justfile`](../Justfile) wraps the loop:
|
|
194
|
+
`just render "<save>"` bakes tiles into `public/`, then `just serve` runs the
|
|
195
|
+
dev server.
|
|
196
|
+
|
|
197
|
+
The generator and this package are decoupled by the **versioned binary tile
|
|
198
|
+
contract** ([`src/core/format.ts`](./src/core/format.ts)): the frontend only
|
|
199
|
+
needs the format, never the world — so a new Minecraft version "just works"
|
|
200
|
+
once the generator can read it.
|
|
@@ -0,0 +1,275 @@
|
|
|
1
|
+
/** Tile format magics, in order of capability. */
|
|
2
|
+
declare const TILE_MAGIC: {
|
|
3
|
+
/** Flat per-vertex colour, no textures. */
|
|
4
|
+
readonly VTL1: "VTL1";
|
|
5
|
+
/** Textured: UV + texture-array layer + tint. */
|
|
6
|
+
readonly VTL2: "VTL2";
|
|
7
|
+
/** + per-vertex biome id and a named legend. */
|
|
8
|
+
readonly VTL3: "VTL3";
|
|
9
|
+
/** + a transparent fluid (water) sub-section. */
|
|
10
|
+
readonly VTL4: "VTL4";
|
|
11
|
+
/** + a top-down surface map for O(ray) biome picking. */
|
|
12
|
+
readonly VTL5: "VTL5";
|
|
13
|
+
/** Quantized vertices: u16 positions (bbox transform) + u16 layer/biome. */
|
|
14
|
+
readonly VTL6: "VTL6";
|
|
15
|
+
};
|
|
16
|
+
type TileMagic = (typeof TILE_MAGIC)[keyof typeof TILE_MAGIC];
|
|
17
|
+
/** Texture-array magic. */
|
|
18
|
+
declare const TEXTURE_MAGIC: "VTA1";
|
|
19
|
+
/**
|
|
20
|
+
* A forward-only cursor over an `ArrayBuffer`. Scalar reads advance the offset;
|
|
21
|
+
* typed-array reads return zero-copy views into the buffer and advance past them.
|
|
22
|
+
*/
|
|
23
|
+
declare class ByteReader {
|
|
24
|
+
readonly buffer: ArrayBuffer;
|
|
25
|
+
readonly view: DataView;
|
|
26
|
+
off: number;
|
|
27
|
+
constructor(buffer: ArrayBuffer, off?: number);
|
|
28
|
+
/** Read a 4-byte ASCII magic without advancing past version fields. */
|
|
29
|
+
magic(): string;
|
|
30
|
+
u8(): number;
|
|
31
|
+
u16(): number;
|
|
32
|
+
u32(): number;
|
|
33
|
+
i32(): number;
|
|
34
|
+
f32(n: number): Float32Array<ArrayBuffer>;
|
|
35
|
+
u8a(n: number): Uint8Array<ArrayBuffer>;
|
|
36
|
+
i8a(n: number): Int8Array<ArrayBuffer>;
|
|
37
|
+
u16a(n: number): Uint16Array<ArrayBuffer>;
|
|
38
|
+
i16a(n: number): Int16Array<ArrayBuffer>;
|
|
39
|
+
u32a(n: number): Uint32Array<ArrayBuffer>;
|
|
40
|
+
/** Advance the cursor to the next 4-byte boundary (skips section padding). */
|
|
41
|
+
align4(): void;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/**
|
|
45
|
+
* One indexed geometry section. The solid terrain is the top-level section;
|
|
46
|
+
* VTL4+ tiles carry an additional transparent {@link DecodedTile.fluid} section
|
|
47
|
+
* in the same shape.
|
|
48
|
+
*/
|
|
49
|
+
interface MeshSection {
|
|
50
|
+
/** Vertex count. */
|
|
51
|
+
vertexCount: number;
|
|
52
|
+
/** Index count (triangles = indexCount / 3). */
|
|
53
|
+
indexCount: number;
|
|
54
|
+
/** `3 * vertexCount` packed XYZ positions. */
|
|
55
|
+
positions: Float32Array;
|
|
56
|
+
/** `3 * vertexCount` normals, expanded from the packed int8 storage. */
|
|
57
|
+
normals: Float32Array;
|
|
58
|
+
/** `indexCount` triangle indices. */
|
|
59
|
+
indices: Uint32Array;
|
|
60
|
+
/** `2 * vertexCount` texture coordinates (textured tiles only). */
|
|
61
|
+
uv?: Float32Array;
|
|
62
|
+
/** `vertexCount` texture-array layer indices (textured tiles only). */
|
|
63
|
+
layer?: Float32Array;
|
|
64
|
+
/** `4 * vertexCount` RGBA: tint RGB + packed AO/alpha (textured tiles only). */
|
|
65
|
+
colors?: Uint8Array;
|
|
66
|
+
/** `vertexCount` per-vertex biome ids (biome tiles only). */
|
|
67
|
+
biome?: Float32Array;
|
|
68
|
+
/** `vertexCount` packed saved light `(sky << 4) | block` (each 0..15), carried
|
|
69
|
+
* in the normal's spare 4th byte. Textured tiles only. */
|
|
70
|
+
light?: Uint8Array;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* A top-down surface map (VTL5): one column per XZ cell over a world-space
|
|
74
|
+
* footprint. Enables O(ray-length) biome picking independent of mesh size.
|
|
75
|
+
*/
|
|
76
|
+
interface SurfaceMap {
|
|
77
|
+
/** Columns in X. */
|
|
78
|
+
width: number;
|
|
79
|
+
/** Columns in Z. */
|
|
80
|
+
depth: number;
|
|
81
|
+
/** World X of column 0. */
|
|
82
|
+
originX: number;
|
|
83
|
+
/** World Z of column 0. */
|
|
84
|
+
originZ: number;
|
|
85
|
+
/** `width * depth` biome ids, row-major (z-major). */
|
|
86
|
+
biome: Uint16Array;
|
|
87
|
+
/** `width * depth` surface heights, row-major (z-major). */
|
|
88
|
+
height: Int16Array;
|
|
89
|
+
}
|
|
90
|
+
/** A fully decoded tile. Optional fields are present per format capability. */
|
|
91
|
+
interface DecodedTile extends MeshSection {
|
|
92
|
+
/** The format magic this tile was decoded from. */
|
|
93
|
+
magic: TileMagic;
|
|
94
|
+
/** Format version field. */
|
|
95
|
+
version: number;
|
|
96
|
+
/** Whether the tile carries textures (VTL2+). */
|
|
97
|
+
textured: boolean;
|
|
98
|
+
/** Whether the tile carries biome data (VTL3+). */
|
|
99
|
+
hasBiome: boolean;
|
|
100
|
+
/** Biome legend, indexed by biome id (VTL3+). */
|
|
101
|
+
biomeNames?: string[];
|
|
102
|
+
/** Transparent fluid geometry, drawn after opaque terrain (VTL4+). */
|
|
103
|
+
fluid?: MeshSection;
|
|
104
|
+
/** Top-down surface map for picking (VTL5+). */
|
|
105
|
+
surface?: SurfaceMap;
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* A VTL6 mesh section kept in its on-disk quantized encoding: every array is a
|
|
109
|
+
* zero-copy view into the tile buffer, ready to hand straight to the GPU. The
|
|
110
|
+
* dequantization (`world = posMin + q * posScale`) happens in the vertex
|
|
111
|
+
* shader, so decoding a tile costs no per-vertex CPU work at all and streaming
|
|
112
|
+
* never stutters on decode.
|
|
113
|
+
*/
|
|
114
|
+
interface QuantizedSection {
|
|
115
|
+
vertexCount: number;
|
|
116
|
+
indexCount: number;
|
|
117
|
+
/** `3 * vertexCount` quantized u16 positions. */
|
|
118
|
+
positions: Uint16Array;
|
|
119
|
+
/** World-space position of quantized (0,0,0). */
|
|
120
|
+
posMin: [number, number, number];
|
|
121
|
+
/** World units per quantization step, per axis. */
|
|
122
|
+
posScale: [number, number, number];
|
|
123
|
+
/** `2 * vertexCount` texture coordinates. */
|
|
124
|
+
uv: Float32Array;
|
|
125
|
+
/** `4 * vertexCount` RGBA: tint RGB + packed AO/alpha. */
|
|
126
|
+
colors: Uint8Array;
|
|
127
|
+
/** `4 * vertexCount` int8: xyz normal + the packed light byte as the 4th
|
|
128
|
+
* component (bit pattern; recover unsigned in-shader). */
|
|
129
|
+
normals: Int8Array;
|
|
130
|
+
/** `vertexCount` u16 texture-array layer indices. */
|
|
131
|
+
layer: Uint16Array;
|
|
132
|
+
/** `vertexCount` u16 biome ids. */
|
|
133
|
+
biome: Uint16Array;
|
|
134
|
+
/** `indexCount` triangle indices. */
|
|
135
|
+
indices: Uint32Array;
|
|
136
|
+
}
|
|
137
|
+
/** A VTL6 tile decoded without dequantization (see {@link QuantizedSection}). */
|
|
138
|
+
interface QuantizedTile {
|
|
139
|
+
magic: 'VTL6';
|
|
140
|
+
version: number;
|
|
141
|
+
solid: QuantizedSection;
|
|
142
|
+
fluid: QuantizedSection;
|
|
143
|
+
surface: SurfaceMap;
|
|
144
|
+
biomeNames: string[];
|
|
145
|
+
}
|
|
146
|
+
/**
|
|
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}.
|
|
151
|
+
*/
|
|
152
|
+
declare function parseTileQuantized(buffer: ArrayBuffer): QuantizedTile | null;
|
|
153
|
+
/**
|
|
154
|
+
* Decode a `.vtile` buffer. Detects the format version from the magic and
|
|
155
|
+
* returns a {@link DecodedTile} with exactly the fields that version carries.
|
|
156
|
+
*
|
|
157
|
+
* @throws if the magic is not a recognized `VTLn`.
|
|
158
|
+
*/
|
|
159
|
+
declare function parseTile(buffer: ArrayBuffer): DecodedTile;
|
|
160
|
+
|
|
161
|
+
/** A decoded texture array: `layers` images of `width`×`height` RGBA pixels. */
|
|
162
|
+
interface DecodedTextureArray {
|
|
163
|
+
width: number;
|
|
164
|
+
height: number;
|
|
165
|
+
layers: number;
|
|
166
|
+
/** `width * height * layers * 4` tightly-packed RGBA bytes. */
|
|
167
|
+
pixels: Uint8Array<ArrayBuffer>;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* Decode a `.vtexarr` buffer.
|
|
171
|
+
*
|
|
172
|
+
* @throws if the magic is not `VTA1`.
|
|
173
|
+
*/
|
|
174
|
+
declare function parseTextureArray(buffer: ArrayBuffer): DecodedTextureArray;
|
|
175
|
+
|
|
176
|
+
/** One tile's manifest record. `x`/`z` are tile coords (world block = x · tileBlocks). */
|
|
177
|
+
interface ManifestTile {
|
|
178
|
+
x: number;
|
|
179
|
+
z: number;
|
|
180
|
+
/** Path relative to the manifest's directory. */
|
|
181
|
+
path: string;
|
|
182
|
+
/** File size in bytes (gzip-wrapped on disk), for progress UI / budgeting. */
|
|
183
|
+
bytes: number;
|
|
184
|
+
}
|
|
185
|
+
/** One lowres LOD level: the whole world at 1/2^level detail, in tiles of
|
|
186
|
+
* `tileBlocks` blocks (each a fixed cell grid — see {@link WorldManifest.lowres}). */
|
|
187
|
+
interface LowresLevel {
|
|
188
|
+
/** Pyramid level (1 = half detail, 2 = quarter, …). */
|
|
189
|
+
level: number;
|
|
190
|
+
/** Tile span in blocks per side at this level (hires tileBlocks · 2^level). */
|
|
191
|
+
tileBlocks: number;
|
|
192
|
+
/** Blocks per heightfield cell (2^level). */
|
|
193
|
+
span: number;
|
|
194
|
+
tiles: ManifestTile[];
|
|
195
|
+
}
|
|
196
|
+
/** A parsed `manifest.json` for a tiled world render. */
|
|
197
|
+
interface WorldManifest {
|
|
198
|
+
/** Manifest schema version (1 = hires tiles only, 2 adds `lowres`). */
|
|
199
|
+
format: number;
|
|
200
|
+
/** Tile span in chunks per side. */
|
|
201
|
+
tileChunks: number;
|
|
202
|
+
/** Tile span in blocks per side (= tileChunks · 16). */
|
|
203
|
+
tileBlocks: number;
|
|
204
|
+
/** Path of the shared texture array, relative to the manifest. */
|
|
205
|
+
textures: string;
|
|
206
|
+
/** World spawn point, when the generator could read level.dat. */
|
|
207
|
+
spawn?: {
|
|
208
|
+
x: number;
|
|
209
|
+
y: number;
|
|
210
|
+
z: number;
|
|
211
|
+
};
|
|
212
|
+
/** Biome display names indexed by the per-vertex biome id (0 = no data).
|
|
213
|
+
* Globally consistent across every tile of the render. */
|
|
214
|
+
biomes: string[];
|
|
215
|
+
/** Every rendered tile. */
|
|
216
|
+
tiles: ManifestTile[];
|
|
217
|
+
/** The lowres LOD pyramid (format 2+): coarse whole-world tiles the viewer
|
|
218
|
+
* keeps resident far beyond the hires ring, so zoom-out shows the world. */
|
|
219
|
+
lowres?: {
|
|
220
|
+
/** Heightfield samples per lowres tile edge (cells + 1 shared-edge apron). */
|
|
221
|
+
grid: number;
|
|
222
|
+
levels: LowresLevel[];
|
|
223
|
+
};
|
|
224
|
+
}
|
|
225
|
+
/** Tile-coordinate key for maps/sets. */
|
|
226
|
+
declare function tileKey(x: number, z: number): string;
|
|
227
|
+
/**
|
|
228
|
+
* Validate and type a fetched `manifest.json` value.
|
|
229
|
+
*
|
|
230
|
+
* @throws if the shape is not a Vantage world manifest this decoder understands.
|
|
231
|
+
*/
|
|
232
|
+
declare function parseManifest(data: unknown): WorldManifest;
|
|
233
|
+
|
|
234
|
+
/** An RGB triple in 0..1. */
|
|
235
|
+
type Rgb = readonly [number, number, number];
|
|
236
|
+
/**
|
|
237
|
+
* A categorical palette of `n` well-separated hues (golden-angle spacing) so
|
|
238
|
+
* adjacent biomes never collide and borders read at a glance. Index 0 is the
|
|
239
|
+
* "no data" sentinel and maps to a neutral gray.
|
|
240
|
+
*/
|
|
241
|
+
declare function biomePalette(n: number): Rgb[];
|
|
242
|
+
/** Strip a `minecraft:` namespace prefix for display. */
|
|
243
|
+
declare function stripNamespace(name: string): string;
|
|
244
|
+
/** A biome present in a tile, with its colour and share of the surface. */
|
|
245
|
+
interface BiomeEntry {
|
|
246
|
+
id: number;
|
|
247
|
+
name: string;
|
|
248
|
+
/** Display name with the namespace stripped. */
|
|
249
|
+
label: string;
|
|
250
|
+
color: Rgb;
|
|
251
|
+
/** Exposed surface area (in block² units) carrying this biome. */
|
|
252
|
+
count: number;
|
|
253
|
+
/** Share of named, present surface area (0..1). */
|
|
254
|
+
fraction: number;
|
|
255
|
+
}
|
|
256
|
+
/**
|
|
257
|
+
* Summarize biomes from a tile's top-down surface map: one block² per column,
|
|
258
|
+
* empty columns skipped. O(columns) instead of O(triangles) — the streaming
|
|
259
|
+
* path uses this so an arriving tile costs no pass over its mesh; the map-area
|
|
260
|
+
* share it reports is also the more intuitive number for a map legend.
|
|
261
|
+
*/
|
|
262
|
+
declare function summarizeSurfaceBiomes(surface: SurfaceMap, names: string[], palette?: Rgb[]): BiomeEntry[];
|
|
263
|
+
/**
|
|
264
|
+
* Summarize the biomes actually present in a tile, most common first. Returns an
|
|
265
|
+
* empty list for tiles without biome data. Pass a `palette` to reuse one already
|
|
266
|
+
* built for rendering; otherwise one is derived from the legend length.
|
|
267
|
+
*
|
|
268
|
+
* Biomes are weighted by exposed triangle *area*, not vertex count: greedy
|
|
269
|
+
* meshing merges a run of identical faces into one big quad with the same 4
|
|
270
|
+
* vertices, so a vertex tally would under-count flat, mergeable biomes. Area is
|
|
271
|
+
* mesh-independent — the share is the same whether or not the faces were merged.
|
|
272
|
+
*/
|
|
273
|
+
declare function summarizeBiomes(tile: DecodedTile, palette?: Rgb[]): BiomeEntry[];
|
|
274
|
+
|
|
275
|
+
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 WorldManifest as W, type DecodedTextureArray as a, ByteReader as b, type MeshSection as c, type QuantizedSection as d, TILE_MAGIC as e, type TileMagic as f, biomePalette as g, parseTextureArray as h, parseTile as i, parseTileQuantized as j, summarizeBiomes as k, summarizeSurfaceBiomes as l, parseManifest as p, stripNamespace as s, tileKey as t };
|