@thoughts-on-things/vantage-mc 0.6.0 → 0.8.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 +34 -2
- package/dist/{biome-NBWIY7dT.d.ts → biome-B6l-1yx4.d.ts} +60 -7
- package/dist/{chunk-46RBFJ4D.js → chunk-GGTVSB7H.js} +825 -36
- package/dist/{chunk-EVPUXVSB.js → chunk-LZCXJU4U.js} +113 -20
- package/dist/core/index.d.ts +1 -1
- package/dist/core/index.js +1 -1
- package/dist/react/index.d.ts +9 -7
- package/dist/react/index.js +17 -14
- package/dist/three/index.d.ts +8 -4
- package/dist/three/index.js +2 -2
- package/dist/{viewer-C5vYxrL1.d.ts → viewer-DkGKQozr.d.ts} +106 -11
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -64,6 +64,36 @@ pasting a new hash into the address bar pans there live. Pass
|
|
|
64
64
|
`urlState={false}` if your page owns its hash (e.g. a router); the plain
|
|
65
65
|
engine keeps it opt-in (`new VantageViewer(el, { urlState: true })`).
|
|
66
66
|
|
|
67
|
+
### Authenticated multiplayer servers
|
|
68
|
+
|
|
69
|
+
To exercise this integration from a repository checkout, run
|
|
70
|
+
`just server-dev` at the repository root. It launches an authenticated
|
|
71
|
+
loopback sidecar and this demo together, with a fresh credential and coordinated
|
|
72
|
+
shutdown. `just server-smoke` performs a headless protocol and lazy-bake
|
|
73
|
+
preflight. These credentials are for the local walkthrough only.
|
|
74
|
+
|
|
75
|
+
Use a `WorldSource` when a launcher needs to attach its existing session to
|
|
76
|
+
the manifest and every streamed artifact. `worldFromHttp` supports a custom
|
|
77
|
+
native fetch transport and confines manifest paths to the same origin and
|
|
78
|
+
directory before attaching credentials:
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
import { worldFromHttp } from '@thoughts-on-things/vantage-mc/core';
|
|
82
|
+
import { VantageViewer } from '@thoughts-on-things/vantage-mc/three';
|
|
83
|
+
|
|
84
|
+
const world = await worldFromHttp(
|
|
85
|
+
'https://host.example/map-app/world/manifest.json',
|
|
86
|
+
{ accessToken: sessionToken, fetch: nativeHttpFetch },
|
|
87
|
+
);
|
|
88
|
+
const viewer = await VantageViewer.mount('#app', { world });
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
For a direct connection to protocol v1, use
|
|
92
|
+
`worldFromVantageServer('https://map.example/', { accessToken })`. Hosts with
|
|
93
|
+
their own player sessions should prefer an existing session-gated same-origin
|
|
94
|
+
proxy. See the [multiplayer server guide](../docs/server.md) for the trust
|
|
95
|
+
boundary and deployment contract.
|
|
96
|
+
|
|
67
97
|
The viewer **renders on demand**: a frame draws only when something changed —
|
|
68
98
|
camera motion, tiles streaming in, a setting — plus a gentle 10 fps tick while
|
|
69
99
|
animated textures (water, lava) are on screen, so an idle map costs ~0 GPU/CPU
|
|
@@ -180,9 +210,11 @@ returns only the fields a given version carries (`textured`, `hasBiome`, `fluid`
|
|
|
180
210
|
|
|
181
211
|
**`@thoughts-on-things/vantage-mc/core`** — `parseTile`, `parseTextureArray`, `parseManifest`,
|
|
182
212
|
`parseLowresTile`, `maybeInflate`, `isGzip`, `tileKey`, `summarizeBiomes`,
|
|
183
|
-
`biomePalette`, `stripNamespace`, `ByteReader
|
|
213
|
+
`biomePalette`, `stripNamespace`, `ByteReader`, `worldFromUrl`,
|
|
214
|
+
`worldFromHttp`, `worldFromVantageServer`; types `DecodedTile`,
|
|
184
215
|
`MeshSection`, `SurfaceMap`, `DecodedTextureArray`, `WorldManifest`,
|
|
185
|
-
`ManifestTile`, `LowresTile`, `BiomeEntry`, `Rgb
|
|
216
|
+
`ManifestTile`, `LowresTile`, `BiomeEntry`, `Rgb`, `WorldSource`,
|
|
217
|
+
`WorldConditionalFetch`, `HttpWorldOptions`, `VantageServerOptions`.
|
|
186
218
|
|
|
187
219
|
**`@thoughts-on-things/vantage-mc/three`** — `buildTerrain`, `buildTileMeshes`,
|
|
188
220
|
`buildQuantizedTileMeshes`, `buildLowresMesh`, `TileManager`,
|
|
@@ -22,6 +22,11 @@ declare const TILE_MAGIC: {
|
|
|
22
22
|
/** VTL8 geometry + a losslessly packed RG8 lightmap (sky/block nibbles,
|
|
23
23
|
* full-byte AO), stored as gzip-friendly planes. */
|
|
24
24
|
readonly VTL9: "VTL9";
|
|
25
|
+
/** VTL9 + the cave partition: cave-dark quads (faces only sky-light-0,
|
|
26
|
+
* non-water cells can see) sit at the END of each lighting segment, with
|
|
27
|
+
* the boundaries in the section header — a viewer can draw a surface-only
|
|
28
|
+
* prefix while the camera is above ground. ("A" = 10.) */
|
|
29
|
+
readonly VTLA: "VTLA";
|
|
25
30
|
};
|
|
26
31
|
type TileMagic = (typeof TILE_MAGIC)[keyof typeof TILE_MAGIC];
|
|
27
32
|
/** VTL7 UV fixed-point steps per texture unit (uv = stored / UV_SCALE). */
|
|
@@ -163,6 +168,12 @@ interface QuantizedSection {
|
|
|
163
168
|
/** VTL8+: the tail's lightmap UVs in half-texel units, `2 * (vertexCount -
|
|
164
169
|
* lmStart)` values (delta coding already undone). */
|
|
165
170
|
lmuv?: Uint16Array;
|
|
171
|
+
/** VTLA+: first cave-dark vertex of the vertex-lit head `[0, lmStart)`.
|
|
172
|
+
* Vertices from here to `lmStart` face only sky-light-0 (non-water) cells —
|
|
173
|
+
* a renderer may skip them while the camera is above ground. */
|
|
174
|
+
caveStart?: number;
|
|
175
|
+
/** VTLA+: first cave-dark vertex of the atlas-lit tail `[lmStart, V)`. */
|
|
176
|
+
caveLmStart?: number;
|
|
166
177
|
}
|
|
167
178
|
/** A tile's baked light+AO atlas. VTL8 expands its planar payload to RGBA;
|
|
168
179
|
* VTL9 interleaves its packed-light/AO planes into a compact RG8 upload. */
|
|
@@ -174,9 +185,9 @@ interface Lightmap {
|
|
|
174
185
|
/** RGBA bytes when unpacked; interleaved packed-light/AO bytes otherwise. */
|
|
175
186
|
pixels: Uint8Array<ArrayBuffer>;
|
|
176
187
|
}
|
|
177
|
-
/** A VTL6/7/8/9 tile decoded without dequantization (see {@link QuantizedSection}). */
|
|
188
|
+
/** A VTL6/7/8/9/A tile decoded without dequantization (see {@link QuantizedSection}). */
|
|
178
189
|
interface QuantizedTile {
|
|
179
|
-
magic: 'VTL6' | 'VTL7' | 'VTL8' | 'VTL9';
|
|
190
|
+
magic: 'VTL6' | 'VTL7' | 'VTL8' | 'VTL9' | 'VTLA';
|
|
180
191
|
version: number;
|
|
181
192
|
solid: QuantizedSection;
|
|
182
193
|
fluid: QuantizedSection;
|
|
@@ -241,6 +252,9 @@ interface ManifestTile {
|
|
|
241
252
|
path: string;
|
|
242
253
|
/** File size in bytes (gzip-wrapped on disk), for progress UI / budgeting. */
|
|
243
254
|
bytes: number;
|
|
255
|
+
/** Opaque source revision. Continuous servers change this only when the
|
|
256
|
+
* region files that feed this tile (including its seam apron) change. */
|
|
257
|
+
revision?: string;
|
|
244
258
|
}
|
|
245
259
|
/** One lowres LOD level: the whole world at 1/2^level detail, in tiles of
|
|
246
260
|
* `tileBlocks` blocks (each a fixed cell grid — see {@link WorldManifest.lowres}). */
|
|
@@ -256,7 +270,8 @@ interface LowresLevel {
|
|
|
256
270
|
/** A parsed `manifest.json` for a tiled world render. */
|
|
257
271
|
interface WorldManifest {
|
|
258
272
|
/** Manifest schema version (1 = hires tiles only, 2 adds `lowres`,
|
|
259
|
-
* 3 = VTL7 compact tiles, 4 = lightmaps, 5 = packed RG8 lightmaps
|
|
273
|
+
* 3 = VTL7 compact tiles, 4 = lightmaps, 5 = packed RG8 lightmaps,
|
|
274
|
+
* 6 = VTLA cave-partitioned tiles). */
|
|
260
275
|
format: number;
|
|
261
276
|
/** Largest per-section vertex count across every tile (format 3+) — sizes
|
|
262
277
|
* the renderer's one shared quad index buffer before the first tile lands. */
|
|
@@ -285,9 +300,9 @@ interface WorldManifest {
|
|
|
285
300
|
/** Biome display names indexed by the per-vertex biome id (0 = no data).
|
|
286
301
|
* Globally consistent across every tile of the render. */
|
|
287
302
|
biomes: string[];
|
|
288
|
-
/** True while
|
|
289
|
-
*
|
|
290
|
-
*
|
|
303
|
+
/** True while the viewer should poll this manifest. A progressive batch
|
|
304
|
+
* flips false when finished; a continuous server keeps it true so saved
|
|
305
|
+
* terrain can revise tiles in place. */
|
|
291
306
|
rendering?: boolean;
|
|
292
307
|
/** True for an on-demand live server (`vantage live`): every populated tile
|
|
293
308
|
* is listed up front but baked lazily on first fetch. Implies `rendering`;
|
|
@@ -324,6 +339,13 @@ declare function parseManifest(data: unknown): WorldManifest;
|
|
|
324
339
|
* `tiles/t.0.0.vtile`). Reject with an `AbortError`-named error if `signal`
|
|
325
340
|
* fires mid-read. */
|
|
326
341
|
type WorldFetch = (path: string, signal?: AbortSignal) => Promise<ArrayBuffer>;
|
|
342
|
+
/** Conditionally fetch a file: present the validator from the previous read
|
|
343
|
+
* and resolve `'unchanged'` when the source still has that exact content
|
|
344
|
+
* (an HTTP 304). Resolves the bytes plus their new validator otherwise. */
|
|
345
|
+
type WorldConditionalFetch = (path: string, etag: string | undefined, signal?: AbortSignal) => Promise<{
|
|
346
|
+
buffer: ArrayBuffer;
|
|
347
|
+
etag?: string;
|
|
348
|
+
} | 'unchanged'>;
|
|
327
349
|
/** A tiled world render, wherever it lives. Pass one to the viewer's `world`
|
|
328
350
|
* option (or build one with {@link worldFromUrl}, {@link worldFromDirectory},
|
|
329
351
|
* or {@link worldFromFiles}). */
|
|
@@ -334,11 +356,42 @@ interface WorldSource {
|
|
|
334
356
|
label: string;
|
|
335
357
|
/** Fetch a file by manifest-relative path. */
|
|
336
358
|
fetch: WorldFetch;
|
|
359
|
+
/** Optional validator-aware fetch. The viewer's manifest poll uses it when
|
|
360
|
+
* present so an unchanged continuous manifest costs a 304, not a body. */
|
|
361
|
+
fetchConditional?: WorldConditionalFetch;
|
|
362
|
+
}
|
|
363
|
+
/** Fetch implementation used by authenticated/native HTTP sources. Tauri and
|
|
364
|
+
* Electron hosts can pass their CORS-exempt fetch without coupling Vantage to
|
|
365
|
+
* a particular desktop runtime. */
|
|
366
|
+
type WorldHttpFetch = (input: string, init?: RequestInit) => Promise<Response>;
|
|
367
|
+
interface HttpWorldOptions {
|
|
368
|
+
/** Resolve a relative manifest URL outside a browser document. */
|
|
369
|
+
base?: string;
|
|
370
|
+
/** Bearer credential sent in the Authorization header, never in the URL. */
|
|
371
|
+
accessToken?: string;
|
|
372
|
+
/** Additional headers applied to the manifest and every artifact request. */
|
|
373
|
+
headers?: Readonly<Record<string, string>>;
|
|
374
|
+
/** Alternate fetch implementation (for example `@tauri-apps/plugin-http`). */
|
|
375
|
+
fetch?: WorldHttpFetch;
|
|
376
|
+
/** Safe human-facing source name. Defaults to the manifest URL. */
|
|
377
|
+
label?: string;
|
|
378
|
+
}
|
|
379
|
+
interface VantageServerOptions extends Omit<HttpWorldOptions, 'base'> {
|
|
380
|
+
/** Opaque server world id. The v1 sidecar exposes `default`. */
|
|
381
|
+
worldId?: string;
|
|
337
382
|
}
|
|
338
383
|
/** A world served over HTTP: fetches `manifest.json` at `url` and resolves
|
|
339
384
|
* tile paths relative to it. This is what a plain string `world` option
|
|
340
385
|
* turns into. */
|
|
341
386
|
declare function worldFromUrl(url: string, base?: string): Promise<WorldSource>;
|
|
387
|
+
/** An HTTP world with optional bearer auth and a pluggable fetch transport.
|
|
388
|
+
* Manifest-owned paths are confined to the manifest directory before any
|
|
389
|
+
* credential is attached. */
|
|
390
|
+
declare function worldFromHttp(url: string, options?: HttpWorldOptions): Promise<WorldSource>;
|
|
391
|
+
/** Connect to the Vantage server protocol v1. This is the direct-server path
|
|
392
|
+
* for launchers; a host with its own player sessions can use
|
|
393
|
+
* {@link worldFromHttp} with a session-gated manifest URL instead. */
|
|
394
|
+
declare function worldFromVantageServer(endpoint: string, options?: VantageServerOptions): Promise<WorldSource>;
|
|
342
395
|
/** A world in a local directory picked with the File System Access API
|
|
343
396
|
* (`window.showDirectoryPicker()`, Chromium) — reads `manifest.json` from the
|
|
344
397
|
* directory root and resolves tile paths through subdirectory handles on
|
|
@@ -393,4 +446,4 @@ declare function summarizeSurfaceBiomes(surface: SurfaceMap, names: string[], pa
|
|
|
393
446
|
*/
|
|
394
447
|
declare function summarizeBiomes(tile: DecodedTile, palette?: Rgb[]): BiomeEntry[];
|
|
395
448
|
|
|
396
|
-
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
|
|
449
|
+
export { worldFromVantageServer as A, type BiomeEntry as B, type DecodedTile as D, type HttpWorldOptions as H, 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 VantageServerOptions as V, type WorldConditionalFetch 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 WorldFetch as i, type WorldHttpFetch as j, type WorldManifest as k, type WorldSource as l, biomePalette as m, canonicalQuadIndices as n, parseTextureArray as o, parseManifest as p, parseTile as q, parseTileQuantized as r, stripNamespace as s, summarizeBiomes as t, summarizeSurfaceBiomes as u, tileKey as v, worldFromDirectory as w, worldFromFiles as x, worldFromHttp as y, worldFromUrl as z };
|