@thoughts-on-things/vantage-mc 0.11.0 → 0.13.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 +29 -8
- package/dist/{biome-CcJerc-b.d.ts → biome-RR-ydR2j.d.ts} +69 -1
- package/dist/{chunk-GKNIX375.js → chunk-CAQDMI2B.js} +86 -1
- package/dist/{chunk-QV6SDOVV.js → chunk-KGHALEXY.js} +967 -30
- package/dist/core/index.d.ts +1 -1
- package/dist/core/index.js +1 -1
- package/dist/react/index.d.ts +22 -6
- package/dist/react/index.js +186 -9
- package/dist/three/index.d.ts +51 -4
- package/dist/three/index.js +2 -2
- package/dist/{viewer-Cy9oGJ-F.d.ts → viewer-CXujqMxK.d.ts} +205 -5
- package/package.json +1 -1
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import * as THREE from 'three';
|
|
2
|
-
import {
|
|
2
|
+
import { p as WorldManifest, m as WorldFetch, R as Rgb, e as ManifestTile, c as LowresLevel, B as BiomeEntry, g as PlayerState, P as PlayerSnapshot, a as DecodedTextureArray, D as DecodedTile, q as WorldSource, l as WorldDimension } from './biome-RR-ydR2j.js';
|
|
3
3
|
|
|
4
4
|
interface TileManagerOptions {
|
|
5
5
|
manifest: WorldManifest;
|
|
@@ -101,8 +101,12 @@ declare class TileManager {
|
|
|
101
101
|
private readonly records;
|
|
102
102
|
private readonly emitter;
|
|
103
103
|
private readonly tileBlocks;
|
|
104
|
-
/** Lowres pyramid levels, finest first ([] when the manifest has none).
|
|
104
|
+
/** Lowres pyramid levels, finest first ([] when the manifest has none).
|
|
105
|
+
* A live world's pyramid grows mid-session — see {@link syncLowres}. */
|
|
105
106
|
private readonly lowLevels;
|
|
107
|
+
/** On-demand world (`vantage live`/`server`): tiles and the LOD pyramid are
|
|
108
|
+
* produced as the map is watched, so both keep being reconciled. */
|
|
109
|
+
private readonly dynamic;
|
|
106
110
|
/** Tile-existence index per lowres level (for the coverage pass). */
|
|
107
111
|
private readonly lowIndex;
|
|
108
112
|
/** Set when residency changed and lowres visibility needs recomputing. */
|
|
@@ -217,12 +221,25 @@ declare class TileManager {
|
|
|
217
221
|
syncTiles(tiles: ManifestTile[]): boolean;
|
|
218
222
|
private reconcileTiles;
|
|
219
223
|
/** Install the lowres pyramid once a progressive render finishes (its earlier
|
|
220
|
-
* manifests carried no lowres).
|
|
221
|
-
*
|
|
224
|
+
* manifests carried no lowres). Forces a re-plan so the coarse rings stream
|
|
225
|
+
* in. No-op without a lowres material. */
|
|
222
226
|
ingestLowres(lowres: {
|
|
223
227
|
grid: number;
|
|
224
228
|
levels: LowresLevel[];
|
|
225
229
|
}): void;
|
|
230
|
+
/**
|
|
231
|
+
* Reconcile the lowres pyramid from a continuous manifest.
|
|
232
|
+
*
|
|
233
|
+
* A live/server session builds its pyramid as tiles bake, so levels appear
|
|
234
|
+
* and individual overview tiles are rebuilt while the map is being watched.
|
|
235
|
+
* Tiles whose fingerprint moved are evicted so the next plan re-fetches
|
|
236
|
+
* them; everything unchanged stays on the GPU. Returns whether anything
|
|
237
|
+
* moved (the caller re-applies view limits and redraws).
|
|
238
|
+
*/
|
|
239
|
+
syncLowres(lowres: {
|
|
240
|
+
grid: number;
|
|
241
|
+
levels: LowresLevel[];
|
|
242
|
+
}): boolean;
|
|
226
243
|
/** Show or hide every resident tile's cave-dark geometry (VTLA tiles order
|
|
227
244
|
* it as a contiguous tail per mesh, so hiding is a shorter draw range —
|
|
228
245
|
* same draw calls, fewer vertices shaded). Tiles built while hidden come up
|
|
@@ -291,6 +308,110 @@ declare class TileManager {
|
|
|
291
308
|
dispose(): void;
|
|
292
309
|
}
|
|
293
310
|
|
|
311
|
+
/** How players are drawn. Every field is live-tunable. */
|
|
312
|
+
interface PlayerSettings {
|
|
313
|
+
/** Draw players at all. Default `true`. */
|
|
314
|
+
enabled?: boolean;
|
|
315
|
+
/** Name tags above each player. Default `true`. */
|
|
316
|
+
names?: boolean;
|
|
317
|
+
/** Show players whose position is a last-known one from disk rather than a
|
|
318
|
+
* live report. Default `true` — for a singleplayer map they are the only
|
|
319
|
+
* players there are. */
|
|
320
|
+
offline?: boolean;
|
|
321
|
+
/** Show players the source reports as being in another dimension. They are
|
|
322
|
+
* always listed; this is about placing them on *this* map, where their
|
|
323
|
+
* coordinates mean something else. Default `false`. */
|
|
324
|
+
foreign?: boolean;
|
|
325
|
+
/** Model size multiplier. `1` is life-size (2 blocks tall); a whole-world
|
|
326
|
+
* view can afford to exaggerate. Default `1`. */
|
|
327
|
+
scale?: number;
|
|
328
|
+
/** Name-tag height as a fraction of the viewport. Default `0.03`. */
|
|
329
|
+
tagSize?: number;
|
|
330
|
+
}
|
|
331
|
+
interface PlayerLayerOptions {
|
|
332
|
+
scene: THREE.Scene;
|
|
333
|
+
camera: THREE.PerspectiveCamera;
|
|
334
|
+
/** Read a skin image named by `players.json`, through the world source — so
|
|
335
|
+
* it is fetched from the map's own origin with the map's own credentials. */
|
|
336
|
+
fetchSkin?: (path: string) => Promise<ArrayBuffer>;
|
|
337
|
+
/** Resolve a player's skin to a URL the browser may load directly. The
|
|
338
|
+
* escape hatch for hosts with their own skin service; Vantage never calls
|
|
339
|
+
* one on its own, because doing so would tell a third party who is looking
|
|
340
|
+
* at the map and who is on the server. */
|
|
341
|
+
resolveSkin?: (player: PlayerState) => string | null | undefined;
|
|
342
|
+
settings?: PlayerSettings;
|
|
343
|
+
}
|
|
344
|
+
/** What the viewer needs to know about one player it is drawing. */
|
|
345
|
+
interface PlayerView extends PlayerState {
|
|
346
|
+
/** Live interpolated position — where the model actually is this frame. */
|
|
347
|
+
drawX: number;
|
|
348
|
+
drawY: number;
|
|
349
|
+
drawZ: number;
|
|
350
|
+
/** The player is placed on this map (not foreign, not filtered out). */
|
|
351
|
+
visible: boolean;
|
|
352
|
+
}
|
|
353
|
+
/**
|
|
354
|
+
* The live-players layer.
|
|
355
|
+
*
|
|
356
|
+
* Owns a group in the viewer's scene, one model per player, and the
|
|
357
|
+
* interpolation that carries them between snapshots.
|
|
358
|
+
*/
|
|
359
|
+
declare class PlayerLayer {
|
|
360
|
+
readonly root: THREE.Group<THREE.Object3DEventMap>;
|
|
361
|
+
private readonly scene;
|
|
362
|
+
private readonly camera;
|
|
363
|
+
private readonly fetchSkin;
|
|
364
|
+
private readonly resolveSkin;
|
|
365
|
+
private readonly models;
|
|
366
|
+
/** Skin loads in flight or done, so a roster that repeats every second
|
|
367
|
+
* doesn't re-fetch a skin every second. */
|
|
368
|
+
private readonly skinRequests;
|
|
369
|
+
private settings;
|
|
370
|
+
/** Who the camera is following, so their tag can say so. */
|
|
371
|
+
private followed;
|
|
372
|
+
private snapshot;
|
|
373
|
+
private lastSnapshotMs;
|
|
374
|
+
private lastFrameMs;
|
|
375
|
+
private tone;
|
|
376
|
+
private disposed;
|
|
377
|
+
constructor(options: PlayerLayerOptions);
|
|
378
|
+
/** The players the layer is tracking, with their live drawn positions. */
|
|
379
|
+
get players(): PlayerView[];
|
|
380
|
+
/** A player's face as a data URL, for a list or a tooltip in the DOM. */
|
|
381
|
+
headIcon(uuid: string): string | null;
|
|
382
|
+
/** Where a player is being drawn right now, for the camera to fly to. */
|
|
383
|
+
positionOf(uuid: string): THREE.Vector3 | null;
|
|
384
|
+
setSettings(settings: PlayerSettings): void;
|
|
385
|
+
/** Mark a player as the one the camera is following (`null` clears it). */
|
|
386
|
+
setFollowed(uuid: string | null): void;
|
|
387
|
+
/** Add or drop models so the scene matches the current roster and settings,
|
|
388
|
+
* without touching anybody's interpolation. */
|
|
389
|
+
private resync;
|
|
390
|
+
private spawn;
|
|
391
|
+
/** Follow the viewer's exposure so players sit in the same light as the
|
|
392
|
+
* terrain instead of glowing against a dimmed world. */
|
|
393
|
+
setTone(exposure: number): void;
|
|
394
|
+
/** Take a new roster. Players that are new appear, players that left fade
|
|
395
|
+
* out, and everyone else gets a fresh interpolation target. */
|
|
396
|
+
setSnapshot(snapshot: PlayerSnapshot, now: number): void;
|
|
397
|
+
/** Whether a player belongs on the map itself (as opposed to merely in the
|
|
398
|
+
* list): foreign coordinates mean something else, and last-known positions
|
|
399
|
+
* are opt-out. */
|
|
400
|
+
private shouldPlace;
|
|
401
|
+
/**
|
|
402
|
+
* Advance every model to `now`.
|
|
403
|
+
*
|
|
404
|
+
* Returns whether anything moved, which the viewer's render-on-demand loop
|
|
405
|
+
* uses to decide whether this frame is worth drawing — a map of standing
|
|
406
|
+
* players costs nothing, and one walking player wakes the loop.
|
|
407
|
+
*/
|
|
408
|
+
update(now: number): boolean;
|
|
409
|
+
dispose(): void;
|
|
410
|
+
/** Load a player's real skin, if there is one to load. Failures are silent:
|
|
411
|
+
* the procedural skin the model already has is a perfectly good fallback. */
|
|
412
|
+
private loadSkin;
|
|
413
|
+
}
|
|
414
|
+
|
|
294
415
|
/** A terrain-height lookup: world surface Y at (x, z), or `null` off the map. */
|
|
295
416
|
type HeightSampler = (x: number, z: number) => number | null;
|
|
296
417
|
interface MapControlsOptions {
|
|
@@ -551,6 +672,21 @@ interface StreamingSettings {
|
|
|
551
672
|
* (remembers 1024 tiles in a 2048² atlas ≈ 22 MiB of GPU memory). */
|
|
552
673
|
mapMemory?: number;
|
|
553
674
|
}
|
|
675
|
+
/** Live players: how the roster is fetched, and how the people in it are drawn.
|
|
676
|
+
* The display fields are the same ones {@link VantageViewer.setPlayers} takes. */
|
|
677
|
+
interface PlayerOptions extends PlayerSettings {
|
|
678
|
+
/** Roster path, relative to the manifest. Default `'players.json'` — what
|
|
679
|
+
* `vantage server`/`live` serves and what `vantage render` writes. */
|
|
680
|
+
path?: string;
|
|
681
|
+
/** Poll cadence in milliseconds while players are moving. A quiet roster
|
|
682
|
+
* relaxes toward four times this. Default `1000`, matching BlueMap. */
|
|
683
|
+
pollMs?: number;
|
|
684
|
+
/** Turn a player into a skin image URL the browser loads directly. Vantage
|
|
685
|
+
* ships no default: asking a public skin service for a player's face tells
|
|
686
|
+
* that service who is on the server and who is watching. A host that
|
|
687
|
+
* already runs (or proxies) one can wire it up here. */
|
|
688
|
+
resolveSkin?: (player: PlayerState) => string | null | undefined;
|
|
689
|
+
}
|
|
554
690
|
interface VantageViewerOptions {
|
|
555
691
|
/** Initial camera framing. Default `'orbit'`. */
|
|
556
692
|
view?: ViewMode;
|
|
@@ -577,6 +713,10 @@ interface VantageViewerOptions {
|
|
|
577
713
|
* frame it arrives. Default `true`; set `false` to render every frame
|
|
578
714
|
* (e.g. when driving external per-frame effects off the viewer's scene). */
|
|
579
715
|
renderOnDemand?: boolean;
|
|
716
|
+
/** Live player positions, streamed from `players.json` beside the manifest.
|
|
717
|
+
* Polling starts automatically when the world offers one and stops for good
|
|
718
|
+
* when it doesn't; pass `{ enabled: false }` to keep players off entirely. */
|
|
719
|
+
players?: PlayerOptions;
|
|
580
720
|
/** Cave-geometry draw policy for VTLA tiles (whose cave-dark quads sit in a
|
|
581
721
|
* toggleable tail per mesh). `'auto'` skips them whenever the camera is
|
|
582
722
|
* above ground with the depth slice closed — from up there they are hidden
|
|
@@ -643,6 +783,19 @@ interface ViewerEvents extends Record<string, unknown> {
|
|
|
643
783
|
total: number;
|
|
644
784
|
rendering: boolean;
|
|
645
785
|
};
|
|
786
|
+
/** The player roster changed — someone moved, joined, or left. Fires only
|
|
787
|
+
* when something actually differs, so it is safe to drive React state with.
|
|
788
|
+
* `available` goes false when the world serves no roster at all. */
|
|
789
|
+
players: {
|
|
790
|
+
players: PlayerView[];
|
|
791
|
+
source: PlayerSnapshot['source'];
|
|
792
|
+
updated: number;
|
|
793
|
+
available: boolean;
|
|
794
|
+
};
|
|
795
|
+
/** The camera started or stopped following a player. */
|
|
796
|
+
follow: {
|
|
797
|
+
uuid: string | null;
|
|
798
|
+
};
|
|
646
799
|
}
|
|
647
800
|
declare class VantageViewer {
|
|
648
801
|
readonly renderer: THREE.WebGLRenderer;
|
|
@@ -686,6 +839,13 @@ declare class VantageViewer {
|
|
|
686
839
|
/** An in-flight atlas re-fetch, so the tile-insert gate and the progressive
|
|
687
840
|
* poll coalesce onto one request instead of racing separate fetches. */
|
|
688
841
|
private atlasRefresh;
|
|
842
|
+
private playersLayer;
|
|
843
|
+
private playerSnapshot;
|
|
844
|
+
private playersAvailable;
|
|
845
|
+
/** Who the camera is glued to, and where follow last put the pivot — the
|
|
846
|
+
* comparison that lets a pan of the user's own release it. */
|
|
847
|
+
private following;
|
|
848
|
+
private readonly followAnchor;
|
|
689
849
|
private biomeEnabled;
|
|
690
850
|
private highlight;
|
|
691
851
|
private mixTarget;
|
|
@@ -762,6 +922,38 @@ declare class VantageViewer {
|
|
|
762
922
|
* atlas grows, and install the lowres pyramid once a batch bake completes.
|
|
763
923
|
* Continuous sources run until the world is replaced. */
|
|
764
924
|
private pollProgressive;
|
|
925
|
+
/**
|
|
926
|
+
* Follow `players.json` for as long as this world is loaded.
|
|
927
|
+
*
|
|
928
|
+
* The roster is small and changes constantly while anyone is moving, so this
|
|
929
|
+
* polls on its own short cadence rather than riding the manifest poll. A
|
|
930
|
+
* conditional source turns a still world into a `304` per tick, and repeated
|
|
931
|
+
* quiet ticks stretch the cadence — a map nobody is walking around on costs
|
|
932
|
+
* almost nothing, and a player who starts moving is on screen within a tick.
|
|
933
|
+
*
|
|
934
|
+
* A world that serves no roster answers 404: after a few consecutive
|
|
935
|
+
* failures the loop gives up for good rather than retrying forever against a
|
|
936
|
+
* static render that will never have one.
|
|
937
|
+
*/
|
|
938
|
+
private pollPlayers;
|
|
939
|
+
private emitPlayers;
|
|
940
|
+
/** The players on the map right now, with their live interpolated positions.
|
|
941
|
+
* Empty when the world serves no roster. */
|
|
942
|
+
get players(): PlayerView[];
|
|
943
|
+
/** A player's face as a data URL, for HTML chrome outside the canvas (a
|
|
944
|
+
* roster panel, a tooltip). Null until their model exists. */
|
|
945
|
+
playerIcon(uuid: string): string | null;
|
|
946
|
+
/** Change how players are drawn — names, offline/foreign visibility, model
|
|
947
|
+
* scale. Applied immediately, no reload. */
|
|
948
|
+
setPlayers(settings: PlayerSettings): void;
|
|
949
|
+
/** Fly the camera to a player. Returns false if they aren't on this map. */
|
|
950
|
+
focusPlayer(uuid: string): boolean;
|
|
951
|
+
/** Keep the camera pinned to a player as they move — `null` releases it.
|
|
952
|
+
* Panning the map releases it too: the pivot moving somewhere follow didn't
|
|
953
|
+
* put it is the user saying they want to look elsewhere. */
|
|
954
|
+
followPlayer(uuid: string | null): boolean;
|
|
955
|
+
/** Who the camera is following, if anyone. */
|
|
956
|
+
get followedPlayer(): string | null;
|
|
765
957
|
/** Ensure the terrain atlas covers at least `layers` texture-array layers,
|
|
766
958
|
* re-fetching `terrain.vtexarr` if it's behind. Coalesces concurrent callers
|
|
767
959
|
* — the on-demand tile-insert gate and the progressive poll — onto one
|
|
@@ -957,7 +1149,15 @@ declare class VantageViewer {
|
|
|
957
1149
|
/** Ceiling the poll cadence relaxes to while a continuous server reports no
|
|
958
1150
|
* changes — a saved world edit still shows up within ~one ceiling. */
|
|
959
1151
|
private static readonly POLL_MAX_MS;
|
|
1152
|
+
/** Player roster cadence, and how far a quiet one is allowed to relax. */
|
|
1153
|
+
private static readonly PLAYER_POLL_MS;
|
|
1154
|
+
private static readonly PLAYER_POLL_RELAX;
|
|
1155
|
+
/** Consecutive failed roster fetches before concluding this world has none. */
|
|
1156
|
+
private static readonly PLAYER_POLL_GIVE_UP;
|
|
960
1157
|
private frame;
|
|
1158
|
+
/** Glue the pivot to the followed player, unless the user has moved it
|
|
1159
|
+
* themselves since the last frame — a deliberate pan outranks follow. */
|
|
1160
|
+
private applyFollow;
|
|
961
1161
|
private draw;
|
|
962
1162
|
/** Draw a fresh frame and return the canvas as a PNG data URL, for a
|
|
963
1163
|
* screenshot button / download link. Draws synchronously first because the
|
|
@@ -969,4 +1169,4 @@ declare class VantageViewer {
|
|
|
969
1169
|
dispose(): void;
|
|
970
1170
|
}
|
|
971
1171
|
|
|
972
|
-
export { DEFAULT_ORBIT_ANGLE as D, type HeightSampler as H, type LightSettings as L, MapControls as M, type StreamingSettings as S, type TextureSource as T, VANILLA_DISPLAY as V, type DisplaySettings as a, type LoadOptions as b, type MapControlsOptions as c, type
|
|
1172
|
+
export { DEFAULT_ORBIT_ANGLE as D, type HeightSampler as H, type LightSettings as L, MapControls as M, PlayerLayer as P, type StreamingSettings as S, type TextureSource as T, VANILLA_DISPLAY as V, type DisplaySettings as a, type LoadOptions as b, type MapControlsOptions as c, type PlayerLayerOptions as d, type PlayerOptions as e, type PlayerSettings as f, type PlayerView as g, type TileInfo as h, TileManager as i, type TileManagerOptions as j, type TileSource as k, type TileStats as l, VantageViewer as m, type VantageViewerOptions as n, type ViewMode as o };
|
package/package.json
CHANGED