@thoughts-on-things/vantage-mc 0.3.0 → 0.4.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.
@@ -1,5 +1,5 @@
1
1
  import * as THREE from 'three';
2
- import { i as WorldManifest, W as WorldFetch, R as Rgb, B as BiomeEntry, a as DecodedTextureArray, D as DecodedTile, j as WorldSource } from './biome-CPP37ieY.js';
2
+ import { i as WorldManifest, W as WorldFetch, R as Rgb, B as BiomeEntry, a as DecodedTextureArray, D as DecodedTile, j as WorldSource } from './biome-uodZHCCI.js';
3
3
 
4
4
  interface TileManagerOptions {
5
5
  manifest: WorldManifest;
@@ -21,7 +21,8 @@ interface TileManagerOptions {
21
21
  palette: Rgb[];
22
22
  /** Stream-in radius around the focus, in blocks. Default `768`. */
23
23
  viewDistance?: number;
24
- /** Hard cap on resident tiles (nearest win). Default `96`. */
24
+ /** Hard cap on resident tiles (nearest win). Default `120` (fills the
25
+ * default view-distance disc; matches the settings panel's "med" preset). */
25
26
  maxTiles?: number;
26
27
  /** Concurrent tile fetches. Default `4`. */
27
28
  concurrency?: number;
@@ -59,6 +60,8 @@ declare class TileManager {
59
60
  private readonly lowIndex;
60
61
  /** Set when residency changed and lowres visibility needs recomputing. */
61
62
  private coverageDirty;
63
+ /** Tiles mid stream-in fade; drained by update(), keeps the viewer drawing. */
64
+ private readonly fadingKeys;
62
65
  private queue;
63
66
  /** Built tiles awaiting scene insertion — flushed ONE per update() call so
64
67
  * multi-MB GPU uploads never pile into a single frame. */
@@ -97,6 +100,16 @@ declare class TileManager {
97
100
  * loading hundreds of tiles) it drains faster so the map sharpens in a
98
101
  * couple of seconds instead of many. */
99
102
  private flushOne;
103
+ /** Stream-in fade length. Long enough to read as a dissolve, short enough
104
+ * that a fast pan still feels instant. */
105
+ static readonly FADE_MS = 280;
106
+ /** Whether any tile is mid stream-in fade — the viewer keeps drawing while
107
+ * true so the dissolve actually animates under render-on-demand. */
108
+ get fading(): boolean;
109
+ /** Chain a per-draw uFade write onto each mesh's onBeforeRender (after the
110
+ * dequantize-uniform hook terrain.ts installs). Every TileManager mesh gets
111
+ * one — the materials are shared, so each draw must set its own fade. */
112
+ private attachFade;
100
113
  /**
101
114
  * Hide every lowres tile whose footprint is fully SHOWN by finer data.
102
115
  * "Shown" is transitive, computed bottom-up: a hires tile shows its area by
@@ -422,6 +435,13 @@ interface VantageViewerOptions {
422
435
  * or pasted into the address bar — is applied to the camera. Default `false`
423
436
  * (the React `<VantageViewer>` turns it on). */
424
437
  urlState?: boolean;
438
+ /** Render only when something changed (camera, streaming tiles, settings) —
439
+ * plus a steady ~10 fps tick while animated textures (water, lava) are
440
+ * loaded, matching their baked 2-tick frametime. An idle view costs ~0
441
+ * GPU/CPU instead of a full render loop; input still renders the same
442
+ * frame it arrives. Default `true`; set `false` to render every frame
443
+ * (e.g. when driving external per-frame effects off the viewer's scene). */
444
+ renderOnDemand?: boolean;
425
445
  }
426
446
  /** A tile source: a URL to fetch, a raw buffer, or already-decoded data. */
427
447
  type TileSource = string | ArrayBuffer | DecodedTile;
@@ -464,6 +484,10 @@ interface ViewerEvents extends Record<string, unknown> {
464
484
  mode: {
465
485
  fly: boolean;
466
486
  };
487
+ /** The depth slice (cave view) moved or toggled. `null` = off. */
488
+ slice: {
489
+ y: number | null;
490
+ };
467
491
  }
468
492
  declare class VantageViewer {
469
493
  readonly renderer: THREE.WebGLRenderer;
@@ -496,6 +520,13 @@ declare class VantageViewer {
496
520
  private highlight;
497
521
  private mixTarget;
498
522
  private mixCurrent;
523
+ private sliceTarget;
524
+ private sliceCurrent;
525
+ private sliceActive;
526
+ /** The last depth used, so re-opening the cave view returns there. */
527
+ private lastSliceY;
528
+ /** The dark "unexplored rock" floor under a sliced world. */
529
+ private slicePlane;
499
530
  private light;
500
531
  private display;
501
532
  private readonly raycaster;
@@ -505,6 +536,9 @@ declare class VantageViewer {
505
536
  private dragging;
506
537
  private lastHover;
507
538
  private lastFrameMs;
539
+ private needsRender;
540
+ private hasAnims;
541
+ private lastRenderMs;
508
542
  private framedState;
509
543
  private hashTimer;
510
544
  private lastWrittenHash;
@@ -571,13 +605,49 @@ declare class VantageViewer {
571
605
  * immediately, no re-bake). */
572
606
  setLight(settings: LightSettings): void;
573
607
  private applyLight;
608
+ /** Whether the loaded world was baked with full cave geometry
609
+ * (`vantage render --caves full`) — i.e. the depth slice has real caves to
610
+ * reveal. The slice API works regardless; this is the "show the UI?" bit. */
611
+ get hasCaves(): boolean;
612
+ /** The world-Y bounds for the depth slice, from the manifest's baked extent
613
+ * (falling back to the loaded bounds / vanilla build limits). */
614
+ get sliceRange(): {
615
+ min: number;
616
+ max: number;
617
+ };
618
+ /** The current depth-slice Y, or `null` when the cave view is off. */
619
+ get slice(): number | null;
620
+ /** Slice the world at world-Y `y` (everything above is cut away, exposing
621
+ * the caves below — the cave / X-ray view); `null` turns it off. The plane
622
+ * eases to its target, so toggling peels the world open. Emits `'slice'`. */
623
+ setSlice(y: number | null): void;
624
+ /** Toggle the cave view: off → the last used depth (or a sensible cave
625
+ * depth on first open), on → off. */
626
+ toggleSlice(): void;
627
+ /** Push slice state to the shader + scene: clip uniform, ambient floor, and
628
+ * the void floor's presence. Also called on (re)load to seed a fresh shader. */
629
+ private applySlice;
630
+ /** The "unexplored rock" floor under a sliced world: a huge dark plane at
631
+ * the world's bottom, so solid ground reads as solid where no cave is
632
+ * exposed (instead of sky bleeding through the planet). Carries a faint
633
+ * 16-block chunk grid for scale and shares the terrain's fog uniforms so
634
+ * its distance haze matches. Follows the camera focus each frame. */
635
+ private buildSlicePlane;
636
+ /** Install the terrain-follow height source, wrapped so the controls' pivot
637
+ * never rides the (now invisible) surface above an open depth slice —
638
+ * zooming in descends to the exposed cave level instead of stopping at the
639
+ * clipped-away hilltops. */
640
+ private setHeightSampler;
574
641
  /** The current live display fidelity (sharpness, colour grade, fog, scale). */
575
642
  get displaySettings(): Required<DisplaySettings>;
576
643
  /** Update the live display fidelity (merges with current; immediate, no
577
644
  * re-bake). `renderScale` resizes the framebuffer; the rest are shader uniforms. */
578
645
  setDisplay(settings: DisplaySettings): void;
579
646
  /** devicePixelRatio × renderScale, capped by maxPixelRatio (and a hard 4 so a
580
- * fat-fingered scale can't allocate a giant framebuffer). */
647
+ * fat-fingered scale can't allocate a giant framebuffer). Floored at 0.25:
648
+ * a hidden/headless window can report devicePixelRatio 0, which would
649
+ * otherwise zero the framebuffer and break screenshot() and the first
650
+ * visible frame. */
581
651
  private targetPixelRatio;
582
652
  private applyDisplay;
583
653
  /** The current streaming settings (view distance, tile budget, concurrency). */
@@ -587,15 +657,19 @@ declare class VantageViewer {
587
657
  * range follow) and persists for future loads. The fidelity dial: raise
588
658
  * viewDistance/maxTiles to see farther, lower them on weak hardware. */
589
659
  setStreaming(settings: StreamingSettings): void;
590
- /** The current view serialized as a `#@x,y,z,dist,rot,tilt` hash fragment —
591
- * paste-able into any URL serving the same world. */
660
+ /** The current view serialized as a `#@x,y,z,dist,rot,tilt[,sliceY]` hash
661
+ * fragment — paste-able into any URL serving the same world. The trailing
662
+ * component appears only while the cave view is open, so those deep links
663
+ * reopen sliced at the same depth. */
592
664
  getViewHash(): string;
593
- /** Apply a `#@x,y,z,dist,rot,tilt` hash to the camera (leading `#` optional).
594
- * Returns whether the hash parsed. */
665
+ /** Apply a `#@x,y,z,dist,rot,tilt[,sliceY]` hash to the camera (leading `#`
666
+ * optional). Returns whether the hash parsed. */
595
667
  applyViewHash(hash: string): boolean;
596
668
  /** Debounced camera→hash sync plus hashchange→camera (pasted links apply
597
669
  * live). `history.replaceState` avoids history spam and hashchange echo. */
598
670
  private bindUrlState;
671
+ /** Debounce a hash write — camera motion and slice changes funnel here. */
672
+ private queueHashWrite;
599
673
  private writeHash;
600
674
  /** Smoothly zoom by `steps` wheel-notches (positive = in). Drives the same
601
675
  * inertial zoom as the wheel, so on-screen buttons feel identical. */
@@ -625,7 +699,19 @@ declare class VantageViewer {
625
699
  private bindInput;
626
700
  private emitHover;
627
701
  private pickHover;
702
+ /** Request a redraw on the next animation frame. The viewer invalidates
703
+ * itself for everything it owns (camera motion, tile streaming, settings,
704
+ * the biome layer); call this only if you mutate the scene from outside. */
705
+ invalidate(): void;
706
+ /** Idle animation cadence (ms). Water/lava bake at a 2-tick frametime
707
+ * (100 ms), so a 10 fps tick steps them at exactly their authored rate. */
708
+ private static readonly ANIM_TICK_MS;
628
709
  private frame;
710
+ private draw;
711
+ /** Draw a fresh frame and return the canvas as a PNG data URL, for a
712
+ * screenshot button / download link. Draws synchronously first because the
713
+ * default framebuffer is not preserved between the on-demand renders. */
714
+ screenshot(): string;
629
715
  private resize;
630
716
  private disposeCurrent;
631
717
  /** Tear down the renderer, controls, observers, and remove the canvas. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@thoughts-on-things/vantage-mc",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "description": "Render a Minecraft (Java) world as a fast, beautiful 3D web map. The web frontend for the Vantage generator.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -49,6 +49,7 @@
49
49
  "dev": "vite",
50
50
  "build": "tsup",
51
51
  "build:demo": "vite build",
52
+ "build:viewer": "vite build -c vite.viewer.config.ts",
52
53
  "preview": "vite preview",
53
54
  "typecheck": "tsc --noEmit",
54
55
  "test": "vitest run",