@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.
- package/LICENSE +21 -0
- package/README.md +200 -0
- package/dist/biome-LCQwACRa.d.ts +275 -0
- package/dist/chunk-7V27NYZD.js +2605 -0
- package/dist/chunk-X7ZJUHP2.js +483 -0
- package/dist/core/index.d.ts +39 -0
- package/dist/core/index.js +1 -0
- package/dist/react/index.d.ts +157 -0
- package/dist/react/index.js +715 -0
- package/dist/three/index.d.ts +110 -0
- package/dist/three/index.js +2 -0
- package/dist/viewer-DkAMDMtW.d.ts +628 -0
- package/package.json +91 -0
|
@@ -0,0 +1,628 @@
|
|
|
1
|
+
import * as THREE from 'three';
|
|
2
|
+
import { W as WorldManifest, R as Rgb, B as BiomeEntry, a as DecodedTextureArray, D as DecodedTile } from './biome-LCQwACRa.js';
|
|
3
|
+
|
|
4
|
+
interface TileManagerOptions {
|
|
5
|
+
manifest: WorldManifest;
|
|
6
|
+
/** URL the manifest was fetched from — tile paths resolve relative to it. */
|
|
7
|
+
baseUrl: string;
|
|
8
|
+
scene: THREE.Scene;
|
|
9
|
+
/** The shared terrain shader (from {@link createTerrainMaterial}). */
|
|
10
|
+
material: THREE.ShaderMaterial;
|
|
11
|
+
/** The shared water shader (from {@link createWaterMaterial}). */
|
|
12
|
+
waterMaterial: THREE.ShaderMaterial;
|
|
13
|
+
/** The shared lowres LOD shader (from {@link createLowresMaterial}); required
|
|
14
|
+
* to stream a format-2 manifest's lowres pyramid. */
|
|
15
|
+
lowresMaterial?: THREE.ShaderMaterial;
|
|
16
|
+
/** Biome palette indexed by the manifest's biome ids. */
|
|
17
|
+
palette: Rgb[];
|
|
18
|
+
/** Stream-in radius around the focus, in blocks. Default `768`. */
|
|
19
|
+
viewDistance?: number;
|
|
20
|
+
/** Hard cap on resident tiles (nearest win). Default `96`. */
|
|
21
|
+
maxTiles?: number;
|
|
22
|
+
/** Concurrent tile fetches. Default `4`. */
|
|
23
|
+
concurrency?: number;
|
|
24
|
+
}
|
|
25
|
+
/** Live totals across resident tiles. */
|
|
26
|
+
interface TileStats {
|
|
27
|
+
/** Hires tiles fully loaded (in the scene). */
|
|
28
|
+
loaded: number;
|
|
29
|
+
/** Tiles currently fetching/decoding (hires + lowres). */
|
|
30
|
+
loading: number;
|
|
31
|
+
/** Total hires tiles in the manifest. */
|
|
32
|
+
total: number;
|
|
33
|
+
/** Lowres LOD tiles resident. */
|
|
34
|
+
lowres: number;
|
|
35
|
+
vertexCount: number;
|
|
36
|
+
triangleCount: number;
|
|
37
|
+
/** Compressed bytes fetched and resident. */
|
|
38
|
+
bytes: number;
|
|
39
|
+
}
|
|
40
|
+
interface TileEvents extends Record<string, unknown> {
|
|
41
|
+
/** A tile finished loading or was unloaded; payload = live stats. */
|
|
42
|
+
change: TileStats;
|
|
43
|
+
}
|
|
44
|
+
declare class TileManager {
|
|
45
|
+
private readonly opts;
|
|
46
|
+
private readonly lowresMaterial;
|
|
47
|
+
private readonly index;
|
|
48
|
+
private readonly records;
|
|
49
|
+
private readonly emitter;
|
|
50
|
+
private readonly tileBlocks;
|
|
51
|
+
/** Lowres pyramid levels, finest first ([] when the manifest has none). */
|
|
52
|
+
private readonly lowLevels;
|
|
53
|
+
/** Tile-existence index per lowres level (for the coverage pass). */
|
|
54
|
+
private readonly lowIndex;
|
|
55
|
+
/** Set when residency changed and lowres visibility needs recomputing. */
|
|
56
|
+
private coverageDirty;
|
|
57
|
+
private queue;
|
|
58
|
+
/** Built tiles awaiting scene insertion — flushed ONE per update() call so
|
|
59
|
+
* multi-MB GPU uploads never pile into a single frame. */
|
|
60
|
+
private pendingAdd;
|
|
61
|
+
private inFlight;
|
|
62
|
+
private lastFocusX;
|
|
63
|
+
private lastFocusZ;
|
|
64
|
+
private disposed;
|
|
65
|
+
/** Fetch-failure counts per record key, surviving record deletion so retry
|
|
66
|
+
* backoff escalates; cleared on success or unload (a fresh pan-in retries). */
|
|
67
|
+
private failCounts;
|
|
68
|
+
private nextRetrySweep;
|
|
69
|
+
private biomesCache;
|
|
70
|
+
private statsCache;
|
|
71
|
+
/** Y range of everything loaded so far, for ray-march bounds. */
|
|
72
|
+
private minY;
|
|
73
|
+
private maxY;
|
|
74
|
+
constructor(options: TileManagerOptions);
|
|
75
|
+
/** Tile span in blocks at a pyramid level (0 = hires). */
|
|
76
|
+
private levelBlocks;
|
|
77
|
+
/** Squared distance from the focus to a tile centre. The re-plan compares
|
|
78
|
+
* and sorts distances over every manifest tile (potentially 10⁵ on a big
|
|
79
|
+
* world), so it stays in squared space — one sqrt per tile is the single
|
|
80
|
+
* hottest thing the planner does. */
|
|
81
|
+
private distSqTo;
|
|
82
|
+
/**
|
|
83
|
+
* Re-plan streaming around the focus point (the controls' pivot / the fly
|
|
84
|
+
* camera). Call every frame — it no-ops until the focus has moved a quarter
|
|
85
|
+
* tile, so the cost is a cheap distance check.
|
|
86
|
+
*/
|
|
87
|
+
update(focusX: number, focusZ: number): void;
|
|
88
|
+
private pump;
|
|
89
|
+
/** Insert built tiles into the scene at a bounded per-frame rate (via
|
|
90
|
+
* update()), so GPU buffer uploads are spread across frames instead of
|
|
91
|
+
* bursting. Normally one per frame; when a backlog builds (a big preset
|
|
92
|
+
* loading hundreds of tiles) it drains faster so the map sharpens in a
|
|
93
|
+
* couple of seconds instead of many. */
|
|
94
|
+
private flushOne;
|
|
95
|
+
/**
|
|
96
|
+
* Hide every lowres tile whose footprint is fully SHOWN by finer data.
|
|
97
|
+
* "Shown" is transitive, computed bottom-up: a hires tile shows its area by
|
|
98
|
+
* being resident; a lowres tile's area is shown if the tile is resident OR
|
|
99
|
+
* all of its existing children's areas are shown (so a coarse blanket tile
|
|
100
|
+
* hides when hires covers it even if the middle rings were never fetched).
|
|
101
|
+
*
|
|
102
|
+
* This is what keeps the underlay honest: a smooth interpolated heightfield
|
|
103
|
+
* coexisting with real voxel terrain leaks through everything hires
|
|
104
|
+
* deliberately opens — cave-culled pockets, ravines, underwater cliffs,
|
|
105
|
+
* gaps in tree canopies. Where finer data is on screen, the underlay is
|
|
106
|
+
* simply switched off; it reappears the moment coverage breaks (unload,
|
|
107
|
+
* ring edge, loading).
|
|
108
|
+
*/
|
|
109
|
+
private applyCoverage;
|
|
110
|
+
/** Live-tune streaming (view distance, tile budget, fetch concurrency).
|
|
111
|
+
* Takes effect on the next update(): the plan is recomputed from scratch. */
|
|
112
|
+
configure(settings: {
|
|
113
|
+
viewDistance?: number;
|
|
114
|
+
maxTiles?: number;
|
|
115
|
+
concurrency?: number;
|
|
116
|
+
}): void;
|
|
117
|
+
/** The current stream-in radius, in blocks. */
|
|
118
|
+
get viewDistance(): number;
|
|
119
|
+
/** The current resident-tile budget. */
|
|
120
|
+
get maxTiles(): number;
|
|
121
|
+
/** Fetch + decode one lowres LOD tile into a heightfield mesh. */
|
|
122
|
+
private loadLowres;
|
|
123
|
+
/** A transient failure (network blip, 5xx) retries with exponential backoff
|
|
124
|
+
* while the tile stays in view — otherwise one blip is a permanent hole in
|
|
125
|
+
* the map until the user pans away and back. Capped so a genuinely bad tile
|
|
126
|
+
* (corrupt file, future format) settles instead of hammering the server.
|
|
127
|
+
* Attempt counts live outside the record because a retry deletes it. */
|
|
128
|
+
private markFailed;
|
|
129
|
+
/** Re-queue failed records whose backoff has expired (cheap; throttled). */
|
|
130
|
+
private retrySweep;
|
|
131
|
+
private loadTile;
|
|
132
|
+
private unload;
|
|
133
|
+
private invalidate;
|
|
134
|
+
/** Live totals across resident tiles. */
|
|
135
|
+
get stats(): TileStats;
|
|
136
|
+
/** Aggregated biome share across every resident tile, most common first. */
|
|
137
|
+
get biomes(): BiomeEntry[];
|
|
138
|
+
/** The surface map cell under world (x,z), from whichever tile owns it. */
|
|
139
|
+
private surfaceAt;
|
|
140
|
+
/** Lightly smoothed terrain height at world (x,z) for the terrain-riding
|
|
141
|
+
* pivot; falls back to the lowres heightfields (finest resident level)
|
|
142
|
+
* beyond the hires ring, so the pivot still rides the terrain when zoomed
|
|
143
|
+
* out. Null when nothing at all is resident there. */
|
|
144
|
+
heightAt: (x: number, z: number) => number | null;
|
|
145
|
+
/** Height from the finest resident lowres level covering (x,z), or null. */
|
|
146
|
+
private lowresHeightAt;
|
|
147
|
+
/** March the ray across resident tiles' surface maps; the biome id at the
|
|
148
|
+
* first column the ray drops below, or -1. O(ray length), tile-count-free. */
|
|
149
|
+
pickBiome(ray: THREE.Ray): number;
|
|
150
|
+
on<K extends keyof TileEvents>(event: K, listener: (payload: TileEvents[K]) => void): () => void;
|
|
151
|
+
/** Abort every fetch, remove and dispose every mesh. */
|
|
152
|
+
dispose(): void;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** A terrain-height lookup: world surface Y at (x, z), or `null` off the map. */
|
|
156
|
+
type HeightSampler = (x: number, z: number) => number | null;
|
|
157
|
+
interface MapControlsOptions {
|
|
158
|
+
/** Closest the camera may dolly to the pivot. Default `4`. */
|
|
159
|
+
minDistance?: number;
|
|
160
|
+
/** Farthest the camera may dolly out. Default `100000`. */
|
|
161
|
+
maxDistance?: number;
|
|
162
|
+
}
|
|
163
|
+
type Listener = () => void;
|
|
164
|
+
declare class MapControls {
|
|
165
|
+
readonly camera: THREE.PerspectiveCamera;
|
|
166
|
+
readonly domElement: HTMLElement;
|
|
167
|
+
/** The look-at pivot in world space (camera orbits and zooms about this). */
|
|
168
|
+
readonly position: THREE.Vector3;
|
|
169
|
+
/** Camera-to-pivot distance: this IS the zoom level. */
|
|
170
|
+
distance: number;
|
|
171
|
+
/** Azimuth in radians; 0 looks toward −Z (north). Wrapped to [−π, π]. */
|
|
172
|
+
rotation: number;
|
|
173
|
+
/** Pitch in radians; 0 = straight top-down, π/2 = horizon, π = straight up. */
|
|
174
|
+
angle: number;
|
|
175
|
+
/** Active control scheme. `'map'` orbits/pans a ground pivot (distance > 0);
|
|
176
|
+
* `'fly'` is a free-flight spectator camera — the eye sits AT `position`
|
|
177
|
+
* (distance 0), full perspective, pitch free across the whole sky. Both
|
|
178
|
+
* modes share one camera state. */
|
|
179
|
+
mode: 'map' | 'fly';
|
|
180
|
+
/** Free-flight move speed; the wheel scales it (0.05‥5) while in `'fly'`. */
|
|
181
|
+
moveSpeed: number;
|
|
182
|
+
minDistance: number;
|
|
183
|
+
maxDistance: number;
|
|
184
|
+
/** Optional terrain sampler; when set the pivot rides the surface. */
|
|
185
|
+
heightAt: HeightSampler | null;
|
|
186
|
+
/** Pivot Y the view relaxes toward when zoomed far out (set by the framer). */
|
|
187
|
+
floorY: number;
|
|
188
|
+
/** Master enable. */
|
|
189
|
+
enabled: boolean;
|
|
190
|
+
private readonly panBuf;
|
|
191
|
+
private rotBuf;
|
|
192
|
+
private angleBuf;
|
|
193
|
+
private zoomBuf;
|
|
194
|
+
private readonly lookBuf;
|
|
195
|
+
private readonly moveBuf;
|
|
196
|
+
private readonly lastLook;
|
|
197
|
+
private pointerLocked;
|
|
198
|
+
private flyPointerDown;
|
|
199
|
+
private savedDistance;
|
|
200
|
+
private readonly pointers;
|
|
201
|
+
private lastPan;
|
|
202
|
+
private lastOrbit;
|
|
203
|
+
private orbiting;
|
|
204
|
+
private panning;
|
|
205
|
+
private startDistance;
|
|
206
|
+
private dynamicDistance;
|
|
207
|
+
private moved;
|
|
208
|
+
private downPos;
|
|
209
|
+
private readonly _ndc;
|
|
210
|
+
private readonly _orbitV;
|
|
211
|
+
private readonly _orbitAxis;
|
|
212
|
+
private readonly _gpA;
|
|
213
|
+
private readonly _gpB;
|
|
214
|
+
private touchDist;
|
|
215
|
+
private touchAngle;
|
|
216
|
+
private readonly keys;
|
|
217
|
+
private avgDt;
|
|
218
|
+
private targetHeight;
|
|
219
|
+
private cameraHeight;
|
|
220
|
+
private goal;
|
|
221
|
+
private readonly listeners;
|
|
222
|
+
private readonly onPointerDown;
|
|
223
|
+
private readonly onPointerMove;
|
|
224
|
+
private readonly onPointerUp;
|
|
225
|
+
private readonly onWheel;
|
|
226
|
+
private readonly onContextMenu;
|
|
227
|
+
private readonly onKeyDown;
|
|
228
|
+
private readonly onKeyUp;
|
|
229
|
+
private readonly onBlur;
|
|
230
|
+
private readonly onPointerLockChange;
|
|
231
|
+
constructor(camera: THREE.PerspectiveCamera, domElement: HTMLElement, options?: MapControlsOptions);
|
|
232
|
+
addEventListener(type: 'start' | 'end' | 'change', fn: Listener): void;
|
|
233
|
+
removeEventListener(type: 'start' | 'end' | 'change', fn: Listener): void;
|
|
234
|
+
private emit;
|
|
235
|
+
/** Compatibility alias: the look-at pivot (some callers still read `.target`). */
|
|
236
|
+
get target(): THREE.Vector3;
|
|
237
|
+
/** True while a drag (pan or orbit) is in progress. */
|
|
238
|
+
get isInteracting(): boolean;
|
|
239
|
+
/** Smoothly zoom by `steps` notches (positive = in, negative = out) — the same
|
|
240
|
+
* unit as a wheel notch, so the zoom buttons match scrolling. */
|
|
241
|
+
zoom(steps: number): void;
|
|
242
|
+
/** True when the free-flight (spectator) camera is active. */
|
|
243
|
+
get flyMode(): boolean;
|
|
244
|
+
/** Whether the pointer is currently captured for mouse-look. */
|
|
245
|
+
get isPointerLocked(): boolean;
|
|
246
|
+
/** Switch control scheme, transitioning the camera continuously. Entering
|
|
247
|
+
* `'fly'` reinterprets the current eye as the free-flight position (the view
|
|
248
|
+
* doesn't jump); exiting drops the orbit pivot back onto the point the eye
|
|
249
|
+
* looks at, at the remembered dolly distance. */
|
|
250
|
+
setMode(mode: 'map' | 'fly'): void;
|
|
251
|
+
/** Toggle between map and free-flight. */
|
|
252
|
+
toggleFly(): void;
|
|
253
|
+
/** The unit forward (look) direction from yaw `rotation` + pitch `angle`. */
|
|
254
|
+
private lookDir;
|
|
255
|
+
/** Capture the pointer for mouse-look (free-flight). Prefers raw/unaccelerated
|
|
256
|
+
* movement, falling back to standard capture where unsupported. */
|
|
257
|
+
private requestPointerLock;
|
|
258
|
+
private exitPointerLock;
|
|
259
|
+
/** Ease the view toward a partial target state (rotation/angle/distance/pivot),
|
|
260
|
+
* e.g. compass→north or a home re-frame. Cancelled by any drag, key, or wheel. */
|
|
261
|
+
animateTo(goal: {
|
|
262
|
+
position?: THREE.Vector3;
|
|
263
|
+
distance?: number;
|
|
264
|
+
rotation?: number;
|
|
265
|
+
angle?: number;
|
|
266
|
+
}): void;
|
|
267
|
+
/** Jump the view to an explicit state and stop all motion (used for framing).
|
|
268
|
+
* `angle`/`distance` are clamped to the legal tilt envelope. */
|
|
269
|
+
setView(state: {
|
|
270
|
+
position: THREE.Vector3;
|
|
271
|
+
distance: number;
|
|
272
|
+
rotation: number;
|
|
273
|
+
angle: number;
|
|
274
|
+
floorY?: number;
|
|
275
|
+
}): void;
|
|
276
|
+
/** Advance the simulation by `deltaMs` and update the camera. Returns whether
|
|
277
|
+
* anything moved this frame. */
|
|
278
|
+
update(deltaMs: number): boolean;
|
|
279
|
+
dispose(): void;
|
|
280
|
+
/** `stiffness` is the per-frame lerp at 60fps, scaled by
|
|
281
|
+
* the (averaged) frame time so feel is frame-rate independent. */
|
|
282
|
+
private smoothing;
|
|
283
|
+
/** Max tilt (radians from top-down) allowed at a dolly distance, scaled to
|
|
284
|
+
* *this* world's zoom range: full tilt up close, eased to a flat top-down
|
|
285
|
+
* exactly at `maxDistance` — so zooming all the way out always levels the
|
|
286
|
+
* view, whatever the world's size. */
|
|
287
|
+
private maxAngleForDistance;
|
|
288
|
+
/** Inverse: the farthest distance at which `angle` is still a legal tilt. */
|
|
289
|
+
private maxDistanceForAngle;
|
|
290
|
+
private applyPan;
|
|
291
|
+
private applyRotate;
|
|
292
|
+
private applyAngle;
|
|
293
|
+
private applyZoom;
|
|
294
|
+
/** While orbiting from a close-in view, tilting toward the horizon also dollies
|
|
295
|
+
* the camera in so the requested tilt becomes legal (a coupled dolly+pitch).
|
|
296
|
+
* A wheel event cancels it (you asked for a specific distance). */
|
|
297
|
+
private applyDynamicDistance;
|
|
298
|
+
/** Drain the look buffer into yaw/pitch (mouse-look + Q/E/R/F keys), smoothed
|
|
299
|
+
* like every other motion. Pixel deltas are normalized to screen height so
|
|
300
|
+
* sensitivity is resolution-independent. */
|
|
301
|
+
private applyFlyLook;
|
|
302
|
+
/** Drain the move buffer into the eye position: WASD strafes/advances on the
|
|
303
|
+
* heading plane (yaw only — looking down doesn't sink you),
|
|
304
|
+
* space/shift raise/lower. The `dt·0.06` factor makes the steady-state speed
|
|
305
|
+
* frame-rate independent. */
|
|
306
|
+
private applyFlyMove;
|
|
307
|
+
/** Free-flight bounds: pitch spans nearly the whole sky (just shy of the poles
|
|
308
|
+
* to dodge the gimbal flip), distance is pinned to the eye, azimuth wraps. */
|
|
309
|
+
private applyFlyBounds;
|
|
310
|
+
/** Ease toward an animation goal (frame-rate-normalized), clearing it once the
|
|
311
|
+
* view has settled close enough. */
|
|
312
|
+
private applyGoal;
|
|
313
|
+
private applyBounds;
|
|
314
|
+
/** Keep the orbit pivot on the terrain surface so the view rotates and tilts
|
|
315
|
+
* about the ground under the screen centre.
|
|
316
|
+
*
|
|
317
|
+
* The pivot Y rides the single-column surface height + 3, temporally smoothed
|
|
318
|
+
* (so panning over uneven ground glides, doesn't bob). A `minCameraHeight`
|
|
319
|
+
* term lifts the pivot just enough that the orbiting camera clears the terrain
|
|
320
|
+
* it hovers over at steep tilt (no dipping below ground / staring into the
|
|
321
|
+
* void). Riding the surface is harmless zoomed out, where the view is forced
|
|
322
|
+
* near top-down (insensitive to pivot Y). */
|
|
323
|
+
private applyHeight;
|
|
324
|
+
/** Translate held keys into the same input buffers the mouse fills, in
|
|
325
|
+
* pixel-equivalent units scaled by frame time. Holding a key tops the buffer
|
|
326
|
+
* up to a steady velocity; releasing lets it decay, so key moves glide and
|
|
327
|
+
* feel identical to a drag — no separate code path. */
|
|
328
|
+
private feedKeys;
|
|
329
|
+
/** Project a screen-pixel point onto the horizontal plane at world height
|
|
330
|
+
* `planeY`, writing the world (x, z) into `out`. Returns false when the ray
|
|
331
|
+
* runs parallel to / away from the plane (e.g. aimed above the horizon). This
|
|
332
|
+
* is what anchors the pan to the cursor: the world point under the cursor is
|
|
333
|
+
* recoverable, so we can keep it pinned there. */
|
|
334
|
+
private groundPoint;
|
|
335
|
+
private updateCamera;
|
|
336
|
+
/** A cheap scalar that changes iff the view changed (skips redundant emits). */
|
|
337
|
+
private changeKey;
|
|
338
|
+
private localXY;
|
|
339
|
+
private pointerDown;
|
|
340
|
+
private beginOrbit;
|
|
341
|
+
private pointerMove;
|
|
342
|
+
/** Two-finger pinch (zoom) + twist (rotate). */
|
|
343
|
+
private pinch;
|
|
344
|
+
private pointerUp;
|
|
345
|
+
private endDrag;
|
|
346
|
+
private wheel;
|
|
347
|
+
private static readonly MOVE_KEYS;
|
|
348
|
+
private isTyping;
|
|
349
|
+
private keyDown;
|
|
350
|
+
private keyUp;
|
|
351
|
+
}
|
|
352
|
+
|
|
353
|
+
/** How the camera frames the world on load. */
|
|
354
|
+
type ViewMode = 'orbit' | 'top';
|
|
355
|
+
/** Live, render-time lighting appearance — tunable without re-baking the tile. */
|
|
356
|
+
interface LightSettings {
|
|
357
|
+
/** Brightness floor at zero baked light, 0..1. Higher = more readable caves.
|
|
358
|
+
* Default `0.12`. */
|
|
359
|
+
ambient?: number;
|
|
360
|
+
/** Daylight factor scaling sky light, 0..1 (0 = night, 1 = noon). Default `1`. */
|
|
361
|
+
daylight?: number;
|
|
362
|
+
/** Overall brightness/tone multiplier (1 = neutral). Default `1`. */
|
|
363
|
+
exposure?: number;
|
|
364
|
+
}
|
|
365
|
+
/** Live, render-time display tuning — texture crispness, baked-AO strength,
|
|
366
|
+
* colour grade, haze, and render scale. All neutral by default (the shipped
|
|
367
|
+
* vanilla look); every knob takes effect immediately, no re-bake. */
|
|
368
|
+
interface DisplaySettings {
|
|
369
|
+
/** Texture mip LOD bias. 0 = smooth (anti-shimmer), higher = crisper distant
|
|
370
|
+
* texels at the cost of some shimmer. Default `0`. */
|
|
371
|
+
sharpness?: number;
|
|
372
|
+
/** Baked ambient-occlusion darkening scale. 1 = as-baked, 0 = off, >1 = deeper
|
|
373
|
+
* contact shadows / more block definition. Default `1`. */
|
|
374
|
+
ao?: number;
|
|
375
|
+
/** Colour saturation (1 = neutral, 0 = greyscale, >1 = punchier). Default `1`. */
|
|
376
|
+
saturation?: number;
|
|
377
|
+
/** Colour contrast around mid grey (1 = neutral). Default `1`. */
|
|
378
|
+
contrast?: number;
|
|
379
|
+
/** Atmospheric haze amount (1 = full, 0 = clear distance). Default `1`. */
|
|
380
|
+
fog?: number;
|
|
381
|
+
/** Super-/sub-sampling factor on devicePixelRatio (1 = native; 2 = 2× SSAA for
|
|
382
|
+
* extra crispness; <1 = faster/softer). Capped by `maxPixelRatio`. Default `1`. */
|
|
383
|
+
renderScale?: number;
|
|
384
|
+
}
|
|
385
|
+
/** The single, vanilla-faithful display look: neutral grade, full haze, native
|
|
386
|
+
* scale — clean flat-lit colours that read like the game. */
|
|
387
|
+
declare const VANILLA_DISPLAY: Required<DisplaySettings>;
|
|
388
|
+
/** The pitch (radians off top-down) the orbit view loads at and the "3D" tilt
|
|
389
|
+
* toggle returns to — a gentle aerial that reads relief without leaning toward
|
|
390
|
+
* the horizon. `0` = straight top-down (the "2D" toggle). */
|
|
391
|
+
declare const DEFAULT_ORBIT_ANGLE = 0.42;
|
|
392
|
+
/** Streaming knobs for tiled worlds (the `world` load source). */
|
|
393
|
+
interface StreamingSettings {
|
|
394
|
+
/** Stream-in radius around the camera focus, in blocks. Default `768`. */
|
|
395
|
+
viewDistance?: number;
|
|
396
|
+
/** Hard cap on resident tiles (nearest win). Default `120`. */
|
|
397
|
+
maxTiles?: number;
|
|
398
|
+
/** Concurrent tile fetches. Default `4`. */
|
|
399
|
+
concurrency?: number;
|
|
400
|
+
}
|
|
401
|
+
interface VantageViewerOptions {
|
|
402
|
+
/** Initial camera framing. Default `'orbit'`. */
|
|
403
|
+
view?: ViewMode;
|
|
404
|
+
/** Antialias the WebGL context. Default `true`. */
|
|
405
|
+
antialias?: boolean;
|
|
406
|
+
/** Device pixel-ratio cap. Default `2`. */
|
|
407
|
+
maxPixelRatio?: number;
|
|
408
|
+
/** Initial lighting appearance (live-tunable later via {@link VantageViewer.setLight}). */
|
|
409
|
+
light?: LightSettings;
|
|
410
|
+
/** Initial display fidelity (live-tunable later via {@link VantageViewer.setDisplay}). */
|
|
411
|
+
display?: DisplaySettings;
|
|
412
|
+
/** Tile-streaming behaviour for `world` sources. */
|
|
413
|
+
streaming?: StreamingSettings;
|
|
414
|
+
/** Keep the camera state in the URL hash (`#@x,y,z,dist,rot,tilt`) so any
|
|
415
|
+
* view is a shareable deep link: the hash updates (debounced, via
|
|
416
|
+
* `history.replaceState`) as the camera moves, and a hash present at load —
|
|
417
|
+
* or pasted into the address bar — is applied to the camera. Default `false`
|
|
418
|
+
* (the React `<VantageViewer>` turns it on). */
|
|
419
|
+
urlState?: boolean;
|
|
420
|
+
}
|
|
421
|
+
/** A tile source: a URL to fetch, a raw buffer, or already-decoded data. */
|
|
422
|
+
type TileSource = string | ArrayBuffer | DecodedTile;
|
|
423
|
+
type TextureSource = string | ArrayBuffer | DecodedTextureArray;
|
|
424
|
+
interface LoadOptions {
|
|
425
|
+
/** A tiled world to stream: the `manifest.json` URL. Takes precedence over `tile`. */
|
|
426
|
+
world?: string;
|
|
427
|
+
/** A single `.vtile` to render (the non-streaming path). */
|
|
428
|
+
tile?: TileSource;
|
|
429
|
+
/** The `.vtexarr` texture array (required for textured tiles). */
|
|
430
|
+
textures?: TextureSource;
|
|
431
|
+
/** Override the initial framing for this load. */
|
|
432
|
+
view?: ViewMode;
|
|
433
|
+
}
|
|
434
|
+
/** Metadata describing a loaded tile. */
|
|
435
|
+
interface TileInfo {
|
|
436
|
+
magic: string;
|
|
437
|
+
vertexCount: number;
|
|
438
|
+
triangleCount: number;
|
|
439
|
+
size: THREE.Vector3;
|
|
440
|
+
biomes: BiomeEntry[];
|
|
441
|
+
}
|
|
442
|
+
interface ViewerEvents extends Record<string, unknown> {
|
|
443
|
+
/** Fired after a tile/world is loaded and framed. */
|
|
444
|
+
load: TileInfo;
|
|
445
|
+
/** Streaming totals changed (tiles loaded/unloaded). Streamed worlds only. */
|
|
446
|
+
stats: TileStats;
|
|
447
|
+
/** The aggregated biome legend changed as tiles streamed in/out. */
|
|
448
|
+
biomes: BiomeEntry[];
|
|
449
|
+
/** The biome id under the cursor, or `null` when off-terrain. */
|
|
450
|
+
hover: number | null;
|
|
451
|
+
/** Biome layer state changed. */
|
|
452
|
+
biomelayer: {
|
|
453
|
+
enabled: boolean;
|
|
454
|
+
highlight: number | null;
|
|
455
|
+
};
|
|
456
|
+
/** Camera control scheme changed (map ⇄ free-flight). */
|
|
457
|
+
mode: {
|
|
458
|
+
fly: boolean;
|
|
459
|
+
};
|
|
460
|
+
}
|
|
461
|
+
declare class VantageViewer {
|
|
462
|
+
readonly renderer: THREE.WebGLRenderer;
|
|
463
|
+
readonly scene: THREE.Scene;
|
|
464
|
+
readonly camera: THREE.PerspectiveCamera;
|
|
465
|
+
readonly controls: MapControls;
|
|
466
|
+
private readonly container;
|
|
467
|
+
private readonly options;
|
|
468
|
+
private readonly emitter;
|
|
469
|
+
private readonly sky;
|
|
470
|
+
private readonly resizeObserver;
|
|
471
|
+
private msaa;
|
|
472
|
+
private readonly present;
|
|
473
|
+
private readonly presentCamera;
|
|
474
|
+
private presentMaterial;
|
|
475
|
+
private tile;
|
|
476
|
+
private shader;
|
|
477
|
+
private bounds;
|
|
478
|
+
private current;
|
|
479
|
+
private _biomes;
|
|
480
|
+
private tiles;
|
|
481
|
+
private manifest;
|
|
482
|
+
private waterShader;
|
|
483
|
+
private lowresShader;
|
|
484
|
+
/** Populated world extent (max of X/Z spans), for whole-world zoom limits. */
|
|
485
|
+
private worldSpan;
|
|
486
|
+
private tilesUnsub;
|
|
487
|
+
private lastBiomesEmit;
|
|
488
|
+
private biomeEnabled;
|
|
489
|
+
private highlight;
|
|
490
|
+
private mixTarget;
|
|
491
|
+
private mixCurrent;
|
|
492
|
+
private light;
|
|
493
|
+
private display;
|
|
494
|
+
private readonly raycaster;
|
|
495
|
+
private readonly ndc;
|
|
496
|
+
private pointerInside;
|
|
497
|
+
private pointerDirty;
|
|
498
|
+
private dragging;
|
|
499
|
+
private lastHover;
|
|
500
|
+
private lastFrameMs;
|
|
501
|
+
private framedState;
|
|
502
|
+
private hashTimer;
|
|
503
|
+
private lastWrittenHash;
|
|
504
|
+
private urlUnsub;
|
|
505
|
+
constructor(container: HTMLElement | string, options?: VantageViewerOptions);
|
|
506
|
+
/** Build the offscreen multisampled target and the fullscreen present pass.
|
|
507
|
+
* The scene already writes display-ready sRGB, so present is a raw passthrough
|
|
508
|
+
* drawn over one oversized clip-space triangle. */
|
|
509
|
+
private buildAA;
|
|
510
|
+
/** Construct a viewer and load a tile in one call. */
|
|
511
|
+
static mount(container: HTMLElement | string, options: VantageViewerOptions & LoadOptions): Promise<VantageViewer>;
|
|
512
|
+
/** Load (fetch/decode as needed), build, and frame a tile or a streamed world. */
|
|
513
|
+
load(opts: LoadOptions): Promise<void>;
|
|
514
|
+
/** Stream a tiled world render from its `manifest.json`. Tiles load around
|
|
515
|
+
* the camera as it moves and unload behind it; the whole world is reachable
|
|
516
|
+
* without ever holding more than the streaming budget in memory. */
|
|
517
|
+
private loadWorld;
|
|
518
|
+
/** Frame a streamed world: pivot on the spawn point when the manifest has
|
|
519
|
+
* one (that's where the builds are), else the centre of the tile extents.
|
|
520
|
+
* Distances are tied to the streaming view distance, not the world size —
|
|
521
|
+
* a 100k×100k world frames the same as a village. */
|
|
522
|
+
private frameWorld;
|
|
523
|
+
/** The radius hires tiles are actually guaranteed resident to: the view
|
|
524
|
+
* distance, unless the tile budget runs out first (nearest-first fill ⇒ a
|
|
525
|
+
* disc of maxTiles tiles ⇒ radius tb·√(maxTiles/π)). */
|
|
526
|
+
private streamRadius;
|
|
527
|
+
/** Zoom range, far plane, and fog for a streamed world.
|
|
528
|
+
*
|
|
529
|
+
* With a lowres pyramid (format 2) the whole world is drawable, so zoom-out
|
|
530
|
+
* is bounded by the world extent, the far plane covers it, and the radial
|
|
531
|
+
* fog retreats to the world edge — a faint horizon haze, never a wall. The
|
|
532
|
+
* hires→lowres seam needs no hiding: finer data simply overlays coarser.
|
|
533
|
+
*
|
|
534
|
+
* Without one (format 1), zoom and fog hug the hires ring so the map never
|
|
535
|
+
* becomes a field of holes: solid haze right where tiles stop. */
|
|
536
|
+
private applyViewLimits;
|
|
537
|
+
private setTile;
|
|
538
|
+
/** Where the *land* is, from the surface heightmap: the elevation-weighted
|
|
539
|
+
* centroid (so flat ocean is ignored) and the span of the elevated region.
|
|
540
|
+
* Falls back to the geometric centre for tiles without a surface map. Keeps
|
|
541
|
+
* the demo's first frame on the interesting terrain, not out over the water. */
|
|
542
|
+
private landTarget;
|
|
543
|
+
/** Camera-to-pivot distance that vertically fits a world span of `s` blocks at
|
|
544
|
+
* the current FOV, so framing is FOV-independent: widening the lens (60→75)
|
|
545
|
+
* doesn't silently zoom the load view out. The callers' multipliers preserve
|
|
546
|
+
* the previously-tuned on-screen framing. */
|
|
547
|
+
private fitDistance;
|
|
548
|
+
private frameCamera;
|
|
549
|
+
/** Biomes present in the current tile, most common first. */
|
|
550
|
+
get biomes(): BiomeEntry[];
|
|
551
|
+
/** Whether the biome recolour layer is active. */
|
|
552
|
+
get biomeLayerEnabled(): boolean;
|
|
553
|
+
/** The currently isolated biome id, or `null`. */
|
|
554
|
+
get highlightedBiome(): number | null;
|
|
555
|
+
/** Turn the biome recolour layer on or off (crossfades). */
|
|
556
|
+
setBiomeLayer(enabled: boolean): void;
|
|
557
|
+
toggleBiomeLayer(): void;
|
|
558
|
+
/** Isolate a biome by id (fades the rest); `null` clears. Enables the layer. */
|
|
559
|
+
setHighlightedBiome(id: number | null): void;
|
|
560
|
+
private applyBiomeUniforms;
|
|
561
|
+
/** The current live lighting appearance. */
|
|
562
|
+
get lightSettings(): Required<LightSettings>;
|
|
563
|
+
/** Update the live lighting appearance (merges with current; takes effect
|
|
564
|
+
* immediately, no re-bake). */
|
|
565
|
+
setLight(settings: LightSettings): void;
|
|
566
|
+
private applyLight;
|
|
567
|
+
/** The current live display fidelity (sharpness, colour grade, fog, scale). */
|
|
568
|
+
get displaySettings(): Required<DisplaySettings>;
|
|
569
|
+
/** Update the live display fidelity (merges with current; immediate, no
|
|
570
|
+
* re-bake). `renderScale` resizes the framebuffer; the rest are shader uniforms. */
|
|
571
|
+
setDisplay(settings: DisplaySettings): void;
|
|
572
|
+
/** devicePixelRatio × renderScale, capped by maxPixelRatio (and a hard 4 so a
|
|
573
|
+
* fat-fingered scale can't allocate a giant framebuffer). */
|
|
574
|
+
private targetPixelRatio;
|
|
575
|
+
private applyDisplay;
|
|
576
|
+
/** The current streaming settings (view distance, tile budget, concurrency). */
|
|
577
|
+
get streamingSettings(): Required<StreamingSettings>;
|
|
578
|
+
/** Live-tune streaming: view distance, resident-tile budget, concurrency.
|
|
579
|
+
* Applies immediately to a streamed world (tiles re-plan, fog and camera
|
|
580
|
+
* range follow) and persists for future loads. The fidelity dial: raise
|
|
581
|
+
* viewDistance/maxTiles to see farther, lower them on weak hardware. */
|
|
582
|
+
setStreaming(settings: StreamingSettings): void;
|
|
583
|
+
/** The current view serialized as a `#@x,y,z,dist,rot,tilt` hash fragment —
|
|
584
|
+
* paste-able into any URL serving the same world. */
|
|
585
|
+
getViewHash(): string;
|
|
586
|
+
/** Apply a `#@x,y,z,dist,rot,tilt` hash to the camera (leading `#` optional).
|
|
587
|
+
* Returns whether the hash parsed. */
|
|
588
|
+
applyViewHash(hash: string): boolean;
|
|
589
|
+
/** Debounced camera→hash sync plus hashchange→camera (pasted links apply
|
|
590
|
+
* live). `history.replaceState` avoids history spam and hashchange echo. */
|
|
591
|
+
private bindUrlState;
|
|
592
|
+
private writeHash;
|
|
593
|
+
/** Smoothly zoom by `steps` wheel-notches (positive = in). Drives the same
|
|
594
|
+
* inertial zoom as the wheel, so on-screen buttons feel identical. */
|
|
595
|
+
zoomBy(steps: number): void;
|
|
596
|
+
/** Smoothly rotate the view back to north, keeping the current tilt and
|
|
597
|
+
* position. For the compass click. */
|
|
598
|
+
resetNorth(): void;
|
|
599
|
+
/** Smoothly set the pitch (radians off top-down): `0` = top-down map ("2D"),
|
|
600
|
+
* {@link DEFAULT_ORBIT_ANGLE} = the gentle aerial ("3D"). The tilt control. */
|
|
601
|
+
setTilt(angle: number): void;
|
|
602
|
+
/** Smoothly drop to a clean, north-up top-down map (the "2D" toggle): levels
|
|
603
|
+
* the tilt and straightens the heading so the world is axis-aligned. */
|
|
604
|
+
flatten(): void;
|
|
605
|
+
/** The current pitch in radians (0 = top-down), for a tilt toggle's state. */
|
|
606
|
+
get tilt(): number;
|
|
607
|
+
/** Smoothly return to the framing the tile loaded into (the home button). */
|
|
608
|
+
resetView(): void;
|
|
609
|
+
/** Whether the free-flight (spectator) camera is active. */
|
|
610
|
+
get isFlying(): boolean;
|
|
611
|
+
/** Enter or leave free-flight. In fly mode the camera becomes a first-person
|
|
612
|
+
* spectator: WASD to move, space/shift up-down, mouse (click to capture) to
|
|
613
|
+
* look, wheel to trim speed. Emits `'mode'`. */
|
|
614
|
+
setFlyMode(on: boolean): void;
|
|
615
|
+
/** Toggle free-flight on/off. */
|
|
616
|
+
toggleFly(): void;
|
|
617
|
+
on<K extends keyof ViewerEvents>(event: K, listener: (payload: ViewerEvents[K]) => void): () => void;
|
|
618
|
+
private bindInput;
|
|
619
|
+
private emitHover;
|
|
620
|
+
private pickHover;
|
|
621
|
+
private frame;
|
|
622
|
+
private resize;
|
|
623
|
+
private disposeCurrent;
|
|
624
|
+
/** Tear down the renderer, controls, observers, and remove the canvas. */
|
|
625
|
+
dispose(): void;
|
|
626
|
+
}
|
|
627
|
+
|
|
628
|
+
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 TileInfo as d, TileManager as e, type TileManagerOptions as f, type TileSource as g, type TileStats as h, VantageViewer as i, type VantageViewerOptions as j, type ViewMode as k };
|