@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
package/README.md
CHANGED
|
@@ -155,6 +155,23 @@ heightfields): the viewer keeps coarse rings resident far beyond the hires
|
|
|
155
155
|
disc — level 1 also underlays it as a loading placeholder — so the whole world
|
|
156
156
|
stays visible at any zoom, right out to a satellite view.
|
|
157
157
|
|
|
158
|
+
**Live players** appear as real Minecraft player models when the world serves a
|
|
159
|
+
`players.json` (`vantage live --players-file`, `vantage server`, or the
|
|
160
|
+
last-known positions `vantage render` writes out of the save). The viewer finds
|
|
161
|
+
it on its own, interpolates between roster polls so players walk rather than
|
|
162
|
+
teleport, and gives each one a constant-size name tag drawn through terrain.
|
|
163
|
+
Drop in `<PlayerList />` for a roster panel with click-to-fly and follow, or
|
|
164
|
+
drive it yourself: `viewer.players`, `viewer.setPlayers({ names, offline,
|
|
165
|
+
foreign, scale })`, `viewer.focusPlayer(uuid)`, `viewer.followPlayer(uuid |
|
|
166
|
+
null)`, and `'players'` / `'follow'` events. Full guide:
|
|
167
|
+
[docs/players.md](../docs/players.md).
|
|
168
|
+
|
|
169
|
+
```tsx
|
|
170
|
+
<VantageViewer world="/manifest.json" players={{ offline: false }}>
|
|
171
|
+
<PlayerList />
|
|
172
|
+
</VantageViewer>
|
|
173
|
+
```
|
|
174
|
+
|
|
158
175
|
A single standalone tile (from `vantage meshtex`) still works:
|
|
159
176
|
|
|
160
177
|
```tsx
|
|
@@ -254,22 +271,26 @@ returns only the fields a given version carries (`textured`, `hasBiome`, `fluid`
|
|
|
254
271
|
`worldFromHttp`, `worldFromVantageServer`; types `DecodedTile`,
|
|
255
272
|
`MeshSection`, `SurfaceMap`, `DecodedTextureArray`, `WorldManifest`,
|
|
256
273
|
`ManifestTile`, `LowresTile`, `BiomeEntry`, `Rgb`, `WorldSource`,
|
|
257
|
-
`WorldConditionalFetch`, `HttpWorldOptions`, `VantageServerOptions
|
|
274
|
+
`WorldConditionalFetch`, `HttpWorldOptions`, `VantageServerOptions`,
|
|
275
|
+
`PlayerState`, `PlayerSnapshot`; `parsePlayers`, `samePlayers`.
|
|
258
276
|
|
|
259
277
|
**`@thoughts-on-things/vantage-mc/three`** — `buildTerrain`, `buildTileMeshes`,
|
|
260
278
|
`buildQuantizedTileMeshes`, `buildLowresMesh`, `TileManager`,
|
|
261
279
|
`createTerrainMaterial`, `createWaterMaterial`, `createLowresMaterial`,
|
|
262
|
-
`createSky`, `pickBiome`, `MapControls`, `
|
|
263
|
-
`
|
|
280
|
+
`createSky`, `pickBiome`, `MapControls`, `PlayerLayer`, `boxFaces`,
|
|
281
|
+
`defaultSkinCanvas`, `headIconCanvas`, `normalizeSkin`, `VantageViewer`
|
|
282
|
+
(engine), `VANILLA_DISPLAY`, `DEFAULT_ORBIT_ANGLE`; types `TerrainObjects`,
|
|
264
283
|
`TileMeshes`, `TileManagerOptions`, `TileStats`, `VantageViewerOptions`,
|
|
265
284
|
`LoadOptions`, `StreamingSettings`, `LightSettings`, `DisplaySettings`,
|
|
266
|
-
`
|
|
285
|
+
`PlayerOptions`, `PlayerSettings`, `PlayerView`, `TileInfo`, `ViewMode`.
|
|
286
|
+
Re-exports all of `core`.
|
|
267
287
|
|
|
268
288
|
**`@thoughts-on-things/vantage-mc/react`** — `<VantageViewer>`, `<BiomeLayer>`, `<SettingsPanel>`,
|
|
269
|
-
`<LightPanel>`, `<MapNav>`, `<DepthSlider>`, `<
|
|
270
|
-
`injectStyles`, `QUALITY_PRESETS`; types
|
|
271
|
-
`
|
|
272
|
-
`VantageStatus`. Re-exports the
|
|
289
|
+
`<LightPanel>`, `<MapNav>`, `<DepthSlider>`, `<PlayerList>`, `<Reticle>`,
|
|
290
|
+
`<Panel>`, `useVantage`, `injectStyles`, `QUALITY_PRESETS`; types
|
|
291
|
+
`VantageViewerProps`, `BiomeLayerProps`, `SettingsPanelProps`,
|
|
292
|
+
`PlayerListProps`, `VantageContextValue`, `VantageStatus`. Re-exports the
|
|
293
|
+
engine and core types.
|
|
273
294
|
|
|
274
295
|
## Develop
|
|
275
296
|
|
|
@@ -368,6 +368,74 @@ declare function tileKey(x: number, z: number): string;
|
|
|
368
368
|
*/
|
|
369
369
|
declare function parseManifest(data: unknown): WorldManifest;
|
|
370
370
|
|
|
371
|
+
/** One player, as the map knows them. */
|
|
372
|
+
interface PlayerState {
|
|
373
|
+
/** Stable identity across polls. Compared, never parsed. */
|
|
374
|
+
uuid: string;
|
|
375
|
+
/** Display name. Falls back to the uuid when the source has no name. */
|
|
376
|
+
name: string;
|
|
377
|
+
x: number;
|
|
378
|
+
y: number;
|
|
379
|
+
z: number;
|
|
380
|
+
/** Degrees, Minecraft's convention: 0 faces +Z (south), increasing toward -X. */
|
|
381
|
+
yaw: number;
|
|
382
|
+
/** Degrees, negative looking up. */
|
|
383
|
+
pitch: number;
|
|
384
|
+
/** Resource id of the dimension they are in, when the source reports one. */
|
|
385
|
+
dimension?: string;
|
|
386
|
+
/** They are not in the dimension this map covers. Listed, but not placed. */
|
|
387
|
+
foreign: boolean;
|
|
388
|
+
/** A last-known position from disk rather than a live report. */
|
|
389
|
+
stale: boolean;
|
|
390
|
+
health?: number;
|
|
391
|
+
gamemode?: string;
|
|
392
|
+
/** Skin image path, relative to the manifest's own directory. */
|
|
393
|
+
skin?: string;
|
|
394
|
+
/** Epoch milliseconds when the position was observed, when known. */
|
|
395
|
+
seen?: number;
|
|
396
|
+
}
|
|
397
|
+
/** A parsed `players.json`. */
|
|
398
|
+
interface PlayerSnapshot {
|
|
399
|
+
/** Where the positions came from: a live host feed, or the save's own files. */
|
|
400
|
+
source: 'host' | 'playerdata' | 'unknown';
|
|
401
|
+
/** Epoch milliseconds the source was last updated (0 when unknown). */
|
|
402
|
+
updated: number;
|
|
403
|
+
players: PlayerState[];
|
|
404
|
+
}
|
|
405
|
+
/** Nothing at all — what a viewer shows before the first poll answers. */
|
|
406
|
+
declare const NO_PLAYERS: PlayerSnapshot;
|
|
407
|
+
/** Wrap to [-180, 180) so interpolating between two samples takes the short way
|
|
408
|
+
* around instead of spinning a player through a full turn. The seam sits at
|
|
409
|
+
* half a turn, where `180` comes back as `-180` — the same direction, and the
|
|
410
|
+
* same distance from anywhere. */
|
|
411
|
+
declare function wrapDegrees(deg: number): number;
|
|
412
|
+
/** The signed shortest angular distance from `from` to `to`, in degrees. */
|
|
413
|
+
declare function angleDelta(from: number, to: number): number;
|
|
414
|
+
/**
|
|
415
|
+
* Validate and type a fetched `players.json` value.
|
|
416
|
+
*
|
|
417
|
+
* Unlike the manifest parser this never throws on a bad entry: a player list is
|
|
418
|
+
* decoration on a map that has to keep working, and a host mid-rewrite is an
|
|
419
|
+
* expected state, not an error. A document that isn't a player list at all
|
|
420
|
+
* does throw, so the viewer can tell "no players here" from "this isn't the
|
|
421
|
+
* file I asked for".
|
|
422
|
+
*
|
|
423
|
+
* @param mapDimension resource id of the dimension the map covers; players
|
|
424
|
+
* elsewhere come back flagged `foreign`.
|
|
425
|
+
*/
|
|
426
|
+
declare function parsePlayers(data: unknown, mapDimension?: string): PlayerSnapshot;
|
|
427
|
+
/**
|
|
428
|
+
* Whether two snapshots describe the same roster — the test the viewer uses to
|
|
429
|
+
* skip re-rendering and re-notifying on a poll that brought nothing new.
|
|
430
|
+
*
|
|
431
|
+
* Matched by uuid rather than by position in the list. A source is free to
|
|
432
|
+
* reorder (a directory listing, a map iteration, a host that sorts by rank),
|
|
433
|
+
* and re-drawing the world because two names swapped places would defeat the
|
|
434
|
+
* quiet-poll behaviour this exists to enable. Uuids are unique after parsing,
|
|
435
|
+
* so equal lengths plus a match for every entry means the same set of people.
|
|
436
|
+
*/
|
|
437
|
+
declare function samePlayers(a: PlayerSnapshot, b: PlayerSnapshot): boolean;
|
|
438
|
+
|
|
371
439
|
/** One dimension of a rendered world. */
|
|
372
440
|
interface WorldDimension extends ManifestDimension {
|
|
373
441
|
/** This dimension's `manifest.json`, relative to `world.json`. */
|
|
@@ -529,4 +597,4 @@ declare function summarizeSurfaceBiomes(surface: SurfaceMap, names: string[], pa
|
|
|
529
597
|
*/
|
|
530
598
|
declare function summarizeBiomes(tile: DecodedTile, palette?: Rgb[]): BiomeEntry[];
|
|
531
599
|
|
|
532
|
-
export {
|
|
600
|
+
export { worldFromVantageServer as $, parseWorldIndex as A, type BiomeEntry as B, pickDimension as C, type DecodedTile as D, resolveManifestPath as E, samePlayers as F, stripNamespace as G, type HttpWorldOptions as H, summarizeBiomes as I, summarizeSurfaceBiomes as J, tileKey as K, type Lightmap as L, type ManifestAtmosphere as M, NO_PLAYERS as N, worldFromDirectory as O, type PlayerSnapshot as P, 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, worldFromFiles as X, worldFromHttp as Y, worldFromIndexEntry as Z, worldFromUrl as _, type DecodedTextureArray as a, wrapDegrees as a0, ByteReader as b, type LowresLevel as c, type ManifestDimension as d, type ManifestTile as e, type MeshSection as f, type PlayerState as g, type QuantizedSection as h, TILE_MAGIC as i, type TextureAnimation as j, type TileMagic as k, type WorldDimension as l, type WorldFetch as m, type WorldHttpFetch as n, type WorldIndex as o, type WorldManifest as p, type WorldSource as q, angleDelta as r, biomePalette as s, canonicalQuadIndices as t, isWorldIndex as u, parseManifest as v, parsePlayers as w, parseTextureArray as x, parseTile as y, parseTileQuantized as z };
|
|
@@ -680,6 +680,91 @@ function parseManifest(data) {
|
|
|
680
680
|
};
|
|
681
681
|
}
|
|
682
682
|
|
|
683
|
+
// src/core/players.ts
|
|
684
|
+
var NO_PLAYERS = { source: "unknown", updated: 0, players: [] };
|
|
685
|
+
var MAX_PLAYERS = 512;
|
|
686
|
+
var WORLD_LIMIT = 3e7;
|
|
687
|
+
var SKIN_PATH_RE = /^(?!.*(?:^|\/)\.\.?(?:\/|$))[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/;
|
|
688
|
+
function num(value) {
|
|
689
|
+
return typeof value === "number" && Number.isFinite(value) ? value : void 0;
|
|
690
|
+
}
|
|
691
|
+
function str(value, max) {
|
|
692
|
+
return typeof value === "string" && value.length > 0 ? value.slice(0, max) : void 0;
|
|
693
|
+
}
|
|
694
|
+
function wrapDegrees(deg) {
|
|
695
|
+
const wrapped = ((deg + 180) % 360 + 360) % 360;
|
|
696
|
+
return wrapped - 180;
|
|
697
|
+
}
|
|
698
|
+
function angleDelta(from, to) {
|
|
699
|
+
return wrapDegrees(to - from);
|
|
700
|
+
}
|
|
701
|
+
function parsePlayer(entry, mapDimension) {
|
|
702
|
+
if (typeof entry !== "object" || entry === null) return null;
|
|
703
|
+
const o = entry;
|
|
704
|
+
const pos = typeof o["position"] === "object" && o["position"] !== null ? o["position"] : o;
|
|
705
|
+
const x = num(pos["x"]);
|
|
706
|
+
const y = num(pos["y"]);
|
|
707
|
+
const z = num(pos["z"]);
|
|
708
|
+
if (x === void 0 || y === void 0 || z === void 0) return null;
|
|
709
|
+
if (Math.abs(x) > WORLD_LIMIT || Math.abs(z) > WORLD_LIMIT) return null;
|
|
710
|
+
const rot = typeof o["rotation"] === "object" && o["rotation"] !== null ? o["rotation"] : o;
|
|
711
|
+
const uuid = str(o["uuid"], 64);
|
|
712
|
+
const name = str(o["name"], 64);
|
|
713
|
+
if (!uuid && !name) return null;
|
|
714
|
+
const dimension = str(o["dimension"], 128) ?? str(o["world"], 128);
|
|
715
|
+
const skin = str(o["skin"], 256);
|
|
716
|
+
return {
|
|
717
|
+
uuid: uuid ?? name,
|
|
718
|
+
name: name ?? uuid,
|
|
719
|
+
x,
|
|
720
|
+
y,
|
|
721
|
+
z,
|
|
722
|
+
yaw: wrapDegrees(num(rot["yaw"]) ?? 0),
|
|
723
|
+
pitch: Math.max(-90, Math.min(90, num(rot["pitch"]) ?? 0)),
|
|
724
|
+
...dimension ? { dimension } : {},
|
|
725
|
+
// A dimension the map doesn't cover makes a player foreign whatever the
|
|
726
|
+
// source claimed; the source's own flag still counts on top of that.
|
|
727
|
+
foreign: o["foreign"] === true || dimension !== void 0 && mapDimension !== void 0 && dimension !== mapDimension,
|
|
728
|
+
stale: o["stale"] === true,
|
|
729
|
+
...num(o["health"]) !== void 0 ? { health: num(o["health"]) } : {},
|
|
730
|
+
...str(o["gamemode"], 32) ? { gamemode: str(o["gamemode"], 32) } : {},
|
|
731
|
+
...skin && SKIN_PATH_RE.test(skin) ? { skin } : {},
|
|
732
|
+
...num(o["seen"]) !== void 0 ? { seen: num(o["seen"]) } : {}
|
|
733
|
+
};
|
|
734
|
+
}
|
|
735
|
+
function parsePlayers(data, mapDimension) {
|
|
736
|
+
const list = Array.isArray(data) ? data : typeof data === "object" && data !== null && Array.isArray(data["players"]) ? data["players"] : null;
|
|
737
|
+
if (!list) throw new Error("vantage: players.json has no players array");
|
|
738
|
+
const players = [];
|
|
739
|
+
const seen = /* @__PURE__ */ new Set();
|
|
740
|
+
for (const entry of list) {
|
|
741
|
+
if (players.length >= MAX_PLAYERS) break;
|
|
742
|
+
const player = parsePlayer(entry, mapDimension);
|
|
743
|
+
if (!player || seen.has(player.uuid)) continue;
|
|
744
|
+
seen.add(player.uuid);
|
|
745
|
+
players.push(player);
|
|
746
|
+
}
|
|
747
|
+
const root = typeof data === "object" && data !== null ? data : {};
|
|
748
|
+
const source = root["source"];
|
|
749
|
+
return {
|
|
750
|
+
source: source === "host" || source === "playerdata" ? source : "unknown",
|
|
751
|
+
updated: num(root["updated"]) ?? 0,
|
|
752
|
+
players
|
|
753
|
+
};
|
|
754
|
+
}
|
|
755
|
+
function samePlayer(p, q) {
|
|
756
|
+
return p.x === q.x && p.y === q.y && p.z === q.z && p.yaw === q.yaw && p.pitch === q.pitch && p.name === q.name && p.foreign === q.foreign && p.stale === q.stale && p.dimension === q.dimension && p.skin === q.skin && p.health === q.health && p.gamemode === q.gamemode && p.seen === q.seen;
|
|
757
|
+
}
|
|
758
|
+
function samePlayers(a, b) {
|
|
759
|
+
if (a.players.length !== b.players.length) return false;
|
|
760
|
+
const byId = new Map(b.players.map((p) => [p.uuid, p]));
|
|
761
|
+
for (const player of a.players) {
|
|
762
|
+
const other = byId.get(player.uuid);
|
|
763
|
+
if (!other || !samePlayer(player, other)) return false;
|
|
764
|
+
}
|
|
765
|
+
return true;
|
|
766
|
+
}
|
|
767
|
+
|
|
683
768
|
// src/core/world.ts
|
|
684
769
|
var KINDS = /* @__PURE__ */ new Set(["overworld", "nether", "end", "custom"]);
|
|
685
770
|
var SLUG_RE2 = /^[a-z0-9._-]{1,64}$/;
|
|
@@ -1018,4 +1103,4 @@ function summarizeBiomes(tile, palette) {
|
|
|
1018
1103
|
return toEntries(counts, names, pal);
|
|
1019
1104
|
}
|
|
1020
1105
|
|
|
1021
|
-
export { ByteReader, LOWRES_EMPTY, LOWRES_MAGIC, TEXTURE_MAGIC, TILE_MAGIC, UV_SCALE, biomePalette, canonicalQuadIndices, isGzip, isWorldIndex, maybeInflate, parseLowresTile, parseManifest, parseTextureArray, parseTile, parseTileQuantized, parseWorldIndex, pickDimension, resolveManifestPath, stripNamespace, summarizeBiomes, summarizeSurfaceBiomes, tileKey, worldFromDirectory, worldFromFiles, worldFromHttp, worldFromIndexEntry, worldFromUrl, worldFromVantageServer };
|
|
1106
|
+
export { ByteReader, LOWRES_EMPTY, LOWRES_MAGIC, NO_PLAYERS, TEXTURE_MAGIC, TILE_MAGIC, UV_SCALE, angleDelta, biomePalette, canonicalQuadIndices, isGzip, isWorldIndex, maybeInflate, parseLowresTile, parseManifest, parsePlayers, parseTextureArray, parseTile, parseTileQuantized, parseWorldIndex, pickDimension, resolveManifestPath, samePlayers, stripNamespace, summarizeBiomes, summarizeSurfaceBiomes, tileKey, worldFromDirectory, worldFromFiles, worldFromHttp, worldFromIndexEntry, worldFromUrl, worldFromVantageServer, wrapDegrees };
|