@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 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`; types `DecodedTile`,
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 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. */
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 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 };
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 };