@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.
@@ -0,0 +1,483 @@
1
+ // src/core/format.ts
2
+ var TILE_MAGIC = {
3
+ /** Flat per-vertex colour, no textures. */
4
+ VTL1: "VTL1",
5
+ /** Textured: UV + texture-array layer + tint. */
6
+ VTL2: "VTL2",
7
+ /** + per-vertex biome id and a named legend. */
8
+ VTL3: "VTL3",
9
+ /** + a transparent fluid (water) sub-section. */
10
+ VTL4: "VTL4",
11
+ /** + a top-down surface map for O(ray) biome picking. */
12
+ VTL5: "VTL5",
13
+ /** Quantized vertices: u16 positions (bbox transform) + u16 layer/biome. */
14
+ VTL6: "VTL6"
15
+ };
16
+ var TEXTURE_MAGIC = "VTA1";
17
+ var ByteReader = class {
18
+ constructor(buffer, off = 0) {
19
+ this.buffer = buffer;
20
+ this.view = new DataView(buffer);
21
+ this.off = off;
22
+ }
23
+ buffer;
24
+ view;
25
+ off;
26
+ /** Read a 4-byte ASCII magic without advancing past version fields. */
27
+ magic() {
28
+ const { view, off } = this;
29
+ return String.fromCharCode(view.getUint8(off), view.getUint8(off + 1), view.getUint8(off + 2), view.getUint8(off + 3));
30
+ }
31
+ u8() {
32
+ return this.view.getUint8(this.off++);
33
+ }
34
+ u16() {
35
+ const v = this.view.getUint16(this.off, true);
36
+ this.off += 2;
37
+ return v;
38
+ }
39
+ u32() {
40
+ const v = this.view.getUint32(this.off, true);
41
+ this.off += 4;
42
+ return v;
43
+ }
44
+ i32() {
45
+ const v = this.view.getInt32(this.off, true);
46
+ this.off += 4;
47
+ return v;
48
+ }
49
+ f32(n) {
50
+ const a = new Float32Array(this.buffer, this.off, n);
51
+ this.off += 4 * n;
52
+ return a;
53
+ }
54
+ u8a(n) {
55
+ const a = new Uint8Array(this.buffer, this.off, n);
56
+ this.off += n;
57
+ return a;
58
+ }
59
+ i8a(n) {
60
+ const a = new Int8Array(this.buffer, this.off, n);
61
+ this.off += n;
62
+ return a;
63
+ }
64
+ u16a(n) {
65
+ const a = new Uint16Array(this.buffer, this.off, n);
66
+ this.off += 2 * n;
67
+ return a;
68
+ }
69
+ i16a(n) {
70
+ const a = new Int16Array(this.buffer, this.off, n);
71
+ this.off += 2 * n;
72
+ return a;
73
+ }
74
+ u32a(n) {
75
+ const a = new Uint32Array(this.buffer, this.off, n);
76
+ this.off += 4 * n;
77
+ return a;
78
+ }
79
+ /** Advance the cursor to the next 4-byte boundary (skips section padding). */
80
+ align4() {
81
+ this.off = this.off + 3 & -4;
82
+ }
83
+ };
84
+
85
+ // src/core/tile.ts
86
+ function expandNormals(packed, vertexCount) {
87
+ const out = new Float32Array(3 * vertexCount);
88
+ for (let i = 0; i < vertexCount; i++) {
89
+ out[i * 3 + 0] = packed[i * 4 + 0];
90
+ out[i * 3 + 1] = packed[i * 4 + 1];
91
+ out[i * 3 + 2] = packed[i * 4 + 2];
92
+ }
93
+ return out;
94
+ }
95
+ function extractLight(packed, vertexCount) {
96
+ const out = new Uint8Array(vertexCount);
97
+ for (let i = 0; i < vertexCount; i++) out[i] = packed[i * 4 + 3] & 255;
98
+ return out;
99
+ }
100
+ function readTexturedBiomeSection(r) {
101
+ const vertexCount = r.u32();
102
+ const indexCount = r.u32();
103
+ const positions = r.f32(3 * vertexCount);
104
+ const uv = r.f32(2 * vertexCount);
105
+ const layer = r.f32(vertexCount);
106
+ const colors = r.u8a(4 * vertexCount);
107
+ const normalsI8 = r.i8a(4 * vertexCount);
108
+ const biome = r.f32(vertexCount);
109
+ const indices = r.u32a(indexCount);
110
+ return {
111
+ vertexCount,
112
+ indexCount,
113
+ positions,
114
+ uv,
115
+ layer,
116
+ colors,
117
+ biome,
118
+ normals: expandNormals(normalsI8, vertexCount),
119
+ light: extractLight(normalsI8, vertexCount),
120
+ indices
121
+ };
122
+ }
123
+ function readQuantizedSection(r) {
124
+ const vertexCount = r.u32();
125
+ const indexCount = r.u32();
126
+ const uv = r.f32(2 * vertexCount);
127
+ const colors = r.u8a(4 * vertexCount);
128
+ const normalsI8 = r.i8a(4 * vertexCount);
129
+ const indices = r.u32a(indexCount);
130
+ const bbox = r.f32(6);
131
+ const mnx = bbox[0], mny = bbox[1], mnz = bbox[2];
132
+ const scx = bbox[3], scy = bbox[4], scz = bbox[5];
133
+ const posQ = r.u16a(3 * vertexCount);
134
+ const layerQ = r.u16a(vertexCount);
135
+ const biomeQ = r.u16a(vertexCount);
136
+ r.align4();
137
+ const positions = new Float32Array(3 * vertexCount);
138
+ const layer = new Float32Array(vertexCount);
139
+ const biome = new Float32Array(vertexCount);
140
+ for (let i = 0; i < vertexCount; i++) {
141
+ positions[i * 3 + 0] = mnx + posQ[i * 3 + 0] * scx;
142
+ positions[i * 3 + 1] = mny + posQ[i * 3 + 1] * scy;
143
+ positions[i * 3 + 2] = mnz + posQ[i * 3 + 2] * scz;
144
+ layer[i] = layerQ[i];
145
+ biome[i] = biomeQ[i];
146
+ }
147
+ return {
148
+ vertexCount,
149
+ indexCount,
150
+ positions,
151
+ uv,
152
+ layer,
153
+ colors,
154
+ biome,
155
+ normals: expandNormals(normalsI8, vertexCount),
156
+ light: extractLight(normalsI8, vertexCount),
157
+ indices
158
+ };
159
+ }
160
+ function readQuantizedSectionRaw(r) {
161
+ const vertexCount = r.u32();
162
+ const indexCount = r.u32();
163
+ const uv = r.f32(2 * vertexCount);
164
+ const colors = r.u8a(4 * vertexCount);
165
+ const normals = r.i8a(4 * vertexCount);
166
+ const indices = r.u32a(indexCount);
167
+ const bbox = r.f32(6);
168
+ const posMin = [bbox[0], bbox[1], bbox[2]];
169
+ const posScale = [bbox[3], bbox[4], bbox[5]];
170
+ const positions = r.u16a(3 * vertexCount);
171
+ const layer = r.u16a(vertexCount);
172
+ const biome = r.u16a(vertexCount);
173
+ r.align4();
174
+ return { vertexCount, indexCount, positions, posMin, posScale, uv, colors, normals, layer, biome, indices };
175
+ }
176
+ function parseTileQuantized(buffer) {
177
+ const r = new ByteReader(buffer);
178
+ if (r.magic() !== TILE_MAGIC.VTL6) return null;
179
+ r.off = 4;
180
+ const version = r.u32();
181
+ const solid = readQuantizedSectionRaw(r);
182
+ const fluid = readQuantizedSectionRaw(r);
183
+ const surface = readSurface(r);
184
+ const biomeNames = readLegend(r);
185
+ return { magic: TILE_MAGIC.VTL6, version, solid, fluid, surface, biomeNames };
186
+ }
187
+ function readSurface(r) {
188
+ const width = r.u32();
189
+ const depth = r.u32();
190
+ const originX = r.i32();
191
+ const originZ = r.i32();
192
+ const n = width * depth;
193
+ const biome = r.u16a(n);
194
+ const height = r.i16a(n);
195
+ return { width, depth, originX, originZ, biome, height };
196
+ }
197
+ function readLegend(r) {
198
+ const count = r.u32();
199
+ const dec = new TextDecoder();
200
+ const names = [];
201
+ for (let i = 0; i < count; i++) {
202
+ const len = r.u16();
203
+ names.push(dec.decode(r.u8a(len)));
204
+ }
205
+ return names;
206
+ }
207
+ function parseTile(buffer) {
208
+ const r = new ByteReader(buffer);
209
+ const magic = r.magic();
210
+ r.off = 4;
211
+ const version = r.u32();
212
+ if (magic === TILE_MAGIC.VTL6) {
213
+ const solid = readQuantizedSection(r);
214
+ const fluid = readQuantizedSection(r);
215
+ const surface = readSurface(r);
216
+ const biomeNames = readLegend(r);
217
+ return { magic, version, textured: true, hasBiome: true, ...solid, biomeNames, fluid, surface };
218
+ }
219
+ if (magic === TILE_MAGIC.VTL3 || magic === TILE_MAGIC.VTL4 || magic === TILE_MAGIC.VTL5) {
220
+ const solid = readTexturedBiomeSection(r);
221
+ let fluid;
222
+ let surface;
223
+ if (magic === TILE_MAGIC.VTL4 || magic === TILE_MAGIC.VTL5) fluid = readTexturedBiomeSection(r);
224
+ if (magic === TILE_MAGIC.VTL5) surface = readSurface(r);
225
+ const biomeNames = readLegend(r);
226
+ return { magic, version, textured: true, hasBiome: true, ...solid, biomeNames, fluid, surface };
227
+ }
228
+ if (magic === TILE_MAGIC.VTL2) {
229
+ const vertexCount = r.u32();
230
+ const indexCount = r.u32();
231
+ const positions = r.f32(3 * vertexCount);
232
+ const uv = r.f32(2 * vertexCount);
233
+ const layer = r.f32(vertexCount);
234
+ const colors = r.u8a(4 * vertexCount);
235
+ const normalsI8 = r.i8a(4 * vertexCount);
236
+ const indices = r.u32a(indexCount);
237
+ return {
238
+ magic,
239
+ version,
240
+ textured: true,
241
+ hasBiome: false,
242
+ vertexCount,
243
+ indexCount,
244
+ positions,
245
+ uv,
246
+ layer,
247
+ colors,
248
+ normals: expandNormals(normalsI8, vertexCount),
249
+ light: extractLight(normalsI8, vertexCount),
250
+ indices
251
+ };
252
+ }
253
+ if (magic === TILE_MAGIC.VTL1) {
254
+ const vertexCount = r.u32();
255
+ const indexCount = r.u32();
256
+ const positions = r.f32(3 * vertexCount);
257
+ const colors = r.u8a(4 * vertexCount);
258
+ const normalsI8 = r.i8a(4 * vertexCount);
259
+ const indices = r.u32a(indexCount);
260
+ return {
261
+ magic,
262
+ version,
263
+ textured: false,
264
+ hasBiome: false,
265
+ vertexCount,
266
+ indexCount,
267
+ positions,
268
+ colors,
269
+ normals: expandNormals(normalsI8, vertexCount),
270
+ indices
271
+ };
272
+ }
273
+ throw new Error(`vantage: unrecognized tile magic "${magic}" (expected VTL1\u2013VTL6)`);
274
+ }
275
+
276
+ // src/core/texture.ts
277
+ function parseTextureArray(buffer) {
278
+ const r = new ByteReader(buffer);
279
+ const magic = r.magic();
280
+ if (magic !== TEXTURE_MAGIC) {
281
+ throw new Error(`vantage: unrecognized texture magic "${magic}" (expected ${TEXTURE_MAGIC})`);
282
+ }
283
+ r.off = 8;
284
+ const width = r.u32();
285
+ const height = r.u32();
286
+ const layers = r.u32();
287
+ const pixels = r.u8a(width * height * layers * 4);
288
+ return { width, height, layers, pixels };
289
+ }
290
+
291
+ // src/core/manifest.ts
292
+ function tileKey(x, z) {
293
+ return `${x},${z}`;
294
+ }
295
+ function parseManifest(data) {
296
+ if (typeof data !== "object" || data === null) throw new Error("vantage: manifest is not an object");
297
+ const m = data;
298
+ const format = m["format"];
299
+ if (format !== 1 && format !== 2) {
300
+ throw new Error(`vantage: unsupported manifest format ${String(format)} (expected 1 or 2)`);
301
+ }
302
+ const tileChunks = m["tileChunks"];
303
+ const tileBlocks = m["tileBlocks"];
304
+ const textures = m["textures"];
305
+ const biomes = m["biomes"];
306
+ const tiles = m["tiles"];
307
+ if (typeof tileChunks !== "number" || tileChunks < 1) throw new Error("vantage: manifest missing tileChunks");
308
+ if (typeof tileBlocks !== "number" || tileBlocks < 16) throw new Error("vantage: manifest missing tileBlocks");
309
+ if (typeof textures !== "string") throw new Error("vantage: manifest missing textures path");
310
+ if (!Array.isArray(biomes) || biomes.some((b) => typeof b !== "string")) {
311
+ throw new Error("vantage: manifest biomes must be a string array");
312
+ }
313
+ if (!Array.isArray(tiles)) throw new Error("vantage: manifest missing tiles array");
314
+ const parseTiles = (list, what) => list.map((t, i) => {
315
+ const o = t;
316
+ if (typeof o !== "object" || o === null || typeof o["x"] !== "number" || typeof o["z"] !== "number" || typeof o["path"] !== "string" || typeof o["bytes"] !== "number") {
317
+ throw new Error(`vantage: manifest ${what} ${i} is malformed`);
318
+ }
319
+ return { x: o["x"], z: o["z"], path: o["path"], bytes: o["bytes"] };
320
+ });
321
+ const parsedTiles = parseTiles(tiles, "tile");
322
+ let lowres;
323
+ const lr = m["lowres"];
324
+ if (typeof lr === "object" && lr !== null) {
325
+ const grid = lr["grid"];
326
+ const levels = lr["levels"];
327
+ if (typeof grid !== "number" || grid < 2 || !Array.isArray(levels)) {
328
+ throw new Error("vantage: manifest lowres section is malformed");
329
+ }
330
+ lowres = {
331
+ grid,
332
+ levels: levels.map((lv, i) => {
333
+ const o = lv;
334
+ if (typeof o !== "object" || o === null || typeof o["level"] !== "number" || typeof o["tileBlocks"] !== "number" || typeof o["span"] !== "number" || !Array.isArray(o["tiles"])) {
335
+ throw new Error(`vantage: manifest lowres level ${i} is malformed`);
336
+ }
337
+ return {
338
+ level: o["level"],
339
+ tileBlocks: o["tileBlocks"],
340
+ span: o["span"],
341
+ tiles: parseTiles(o["tiles"], `lowres level ${o["level"]} tile`)
342
+ };
343
+ })
344
+ };
345
+ }
346
+ let spawn;
347
+ const s = m["spawn"];
348
+ if (typeof s === "object" && s !== null && typeof s["x"] === "number" && typeof s["y"] === "number" && typeof s["z"] === "number") {
349
+ spawn = { x: s["x"], y: s["y"], z: s["z"] };
350
+ }
351
+ return {
352
+ format,
353
+ tileChunks,
354
+ tileBlocks,
355
+ textures,
356
+ ...spawn ? { spawn } : {},
357
+ ...lowres ? { lowres } : {},
358
+ biomes,
359
+ tiles: parsedTiles
360
+ };
361
+ }
362
+
363
+ // src/core/lowres.ts
364
+ var LOWRES_MAGIC = "VLR1";
365
+ var LOWRES_EMPTY = -32768;
366
+ function parseLowresTile(buffer) {
367
+ const r = new ByteReader(buffer);
368
+ const magic = r.magic();
369
+ if (magic !== LOWRES_MAGIC) throw new Error(`vantage: unrecognized lowres magic "${magic}" (expected VLR1)`);
370
+ r.off = 4;
371
+ const version = r.u32();
372
+ if (version !== 1) throw new Error(`vantage: unsupported VLR version ${version}`);
373
+ const width = r.u32();
374
+ const depth = r.u32();
375
+ const originX = r.i32();
376
+ const originZ = r.i32();
377
+ const span = r.u32();
378
+ const n = width * depth;
379
+ const heights = r.i16a(n);
380
+ const rgb = r.u8a(3 * n);
381
+ return { width, depth, originX, originZ, span, heights, rgb };
382
+ }
383
+
384
+ // src/core/gzip.ts
385
+ function isGzip(buffer) {
386
+ if (buffer.byteLength < 2) return false;
387
+ const b = new Uint8Array(buffer, 0, 2);
388
+ return b[0] === 31 && b[1] === 139;
389
+ }
390
+ async function maybeInflate(buffer) {
391
+ if (!isGzip(buffer)) return buffer;
392
+ const ds = new DecompressionStream("gzip");
393
+ const stream = new Response(buffer).body.pipeThrough(ds);
394
+ return new Response(stream).arrayBuffer();
395
+ }
396
+
397
+ // src/core/biome.ts
398
+ function hsv2rgb(h, s, v) {
399
+ const i = Math.floor(h * 6);
400
+ const f = h * 6 - i;
401
+ const p = v * (1 - s);
402
+ const q = v * (1 - f * s);
403
+ const t = v * (1 - (1 - f) * s);
404
+ const table = [
405
+ [v, t, p],
406
+ [q, v, p],
407
+ [p, v, t],
408
+ [p, q, v],
409
+ [t, p, v],
410
+ [v, p, q]
411
+ ];
412
+ return table[i % 6];
413
+ }
414
+ function biomePalette(n) {
415
+ const out = new Array(n);
416
+ for (let i = 0; i < n; i++) {
417
+ if (i === 0) {
418
+ out[i] = [0.55, 0.55, 0.6];
419
+ continue;
420
+ }
421
+ const h = (i - 1) * 0.61803398875 % 1;
422
+ const sat = 0.55 + 0.12 * (i * 7 % 3) / 2;
423
+ out[i] = hsv2rgb(h, sat, 0.96);
424
+ }
425
+ return out;
426
+ }
427
+ function stripNamespace(name) {
428
+ const c = name.indexOf(":");
429
+ return c >= 0 ? name.slice(c + 1) : name;
430
+ }
431
+ function toEntries(counts, names, pal) {
432
+ const present = [];
433
+ let total = 0;
434
+ for (let id = 0; id < names.length; id++) {
435
+ const count = counts[id];
436
+ if (count > 0 && names[id].length > 0) {
437
+ present.push({ id, name: names[id], label: stripNamespace(names[id]), color: pal[id] ?? pal[0], count, fraction: 0 });
438
+ total += count;
439
+ }
440
+ }
441
+ present.sort((a, b) => b.count - a.count);
442
+ const denom = total || 1;
443
+ for (const e of present) e.fraction = e.count / denom;
444
+ return present;
445
+ }
446
+ function summarizeSurfaceBiomes(surface, names, palette) {
447
+ const pal = palette ?? biomePalette(names.length);
448
+ const counts = new Array(names.length).fill(0);
449
+ const { biome, height } = surface;
450
+ for (let i = 0; i < biome.length; i++) {
451
+ if (height[i] < 1) continue;
452
+ const id = biome[i];
453
+ if (id < counts.length) counts[id]++;
454
+ }
455
+ return toEntries(counts, names, pal);
456
+ }
457
+ function summarizeBiomes(tile, palette) {
458
+ const names = tile.biomeNames;
459
+ const biome = tile.biome;
460
+ if (!names || !biome) return [];
461
+ const pal = palette ?? biomePalette(names.length);
462
+ const counts = new Array(names.length).fill(0);
463
+ const pos = tile.positions;
464
+ const idx = tile.indices;
465
+ for (let t = 0; t + 2 < idx.length; t += 3) {
466
+ const a = idx[t];
467
+ const b = idx[t + 1];
468
+ const c = idx[t + 2];
469
+ const e1x = pos[b * 3] - pos[a * 3];
470
+ const e1y = pos[b * 3 + 1] - pos[a * 3 + 1];
471
+ const e1z = pos[b * 3 + 2] - pos[a * 3 + 2];
472
+ const e2x = pos[c * 3] - pos[a * 3];
473
+ const e2y = pos[c * 3 + 1] - pos[a * 3 + 1];
474
+ const e2z = pos[c * 3 + 2] - pos[a * 3 + 2];
475
+ const crx = e1y * e2z - e1z * e2y;
476
+ const cry = e1z * e2x - e1x * e2z;
477
+ const crz = e1x * e2y - e1y * e2x;
478
+ counts[biome[a] | 0] += 0.5 * Math.hypot(crx, cry, crz);
479
+ }
480
+ return toEntries(counts, names, pal);
481
+ }
482
+
483
+ export { ByteReader, LOWRES_EMPTY, LOWRES_MAGIC, TEXTURE_MAGIC, TILE_MAGIC, biomePalette, isGzip, maybeInflate, parseLowresTile, parseManifest, parseTextureArray, parseTile, parseTileQuantized, stripNamespace, summarizeBiomes, summarizeSurfaceBiomes, tileKey };
@@ -0,0 +1,39 @@
1
+ export { B as BiomeEntry, b as ByteReader, a as DecodedTextureArray, D as DecodedTile, L as LowresLevel, M as ManifestTile, c as MeshSection, d as QuantizedSection, Q as QuantizedTile, R as Rgb, S as SurfaceMap, T as TEXTURE_MAGIC, e as TILE_MAGIC, f as TileMagic, W as WorldManifest, g as biomePalette, p as parseManifest, h as parseTextureArray, i as parseTile, j as parseTileQuantized, s as stripNamespace, k as summarizeBiomes, l as summarizeSurfaceBiomes, t as tileKey } from '../biome-LCQwACRa.js';
2
+
3
+ declare const LOWRES_MAGIC = "VLR1";
4
+ /** Height sentinel for samples with no terrain (unpopulated chunks). */
5
+ declare const LOWRES_EMPTY = -32768;
6
+ /**
7
+ * A decoded lowres tile: a `width`×`depth` grid of (height, color) samples.
8
+ * Sample (i,j) sits at world (originX + (i+0.5)·span, originZ + (j+0.5)·span);
9
+ * the last row/column duplicates the +x/+z neighbours' first samples so
10
+ * adjacent tiles share edge vertices (seamless heightfields).
11
+ */
12
+ interface LowresTile {
13
+ /** Samples per row. */
14
+ width: number;
15
+ /** Sample rows. */
16
+ depth: number;
17
+ /** World block coords of cell (0,0)'s corner. */
18
+ originX: number;
19
+ originZ: number;
20
+ /** Blocks per cell (2^level). */
21
+ span: number;
22
+ /** `width·depth` world-Y heights of the top block ({@link LOWRES_EMPTY} = none). */
23
+ heights: Int16Array;
24
+ /** `3·width·depth` sRGB colors (lighting/tint baked by the generator). */
25
+ rgb: Uint8Array;
26
+ }
27
+ /**
28
+ * Decode a `.vlr` buffer (gunzip first via `maybeInflate` when fetched raw).
29
+ *
30
+ * @throws if the magic is not `VLR1`.
31
+ */
32
+ declare function parseLowresTile(buffer: ArrayBuffer): LowresTile;
33
+
34
+ /** Whether the buffer starts with the gzip magic (0x1f 0x8b). */
35
+ declare function isGzip(buffer: ArrayBuffer): boolean;
36
+ /** Inflate the buffer if it is gzip-wrapped; return it untouched otherwise. */
37
+ declare function maybeInflate(buffer: ArrayBuffer): Promise<ArrayBuffer>;
38
+
39
+ export { LOWRES_EMPTY, LOWRES_MAGIC, type LowresTile, isGzip, maybeInflate, parseLowresTile };
@@ -0,0 +1 @@
1
+ export { ByteReader, LOWRES_EMPTY, LOWRES_MAGIC, TEXTURE_MAGIC, TILE_MAGIC, biomePalette, isGzip, maybeInflate, parseLowresTile, parseManifest, parseTextureArray, parseTile, parseTileQuantized, stripNamespace, summarizeBiomes, summarizeSurfaceBiomes, tileKey } from '../chunk-X7ZJUHP2.js';