@navaramap/three-plugins 0.0.4 → 0.0.6

package/README.md

@@ -51,7 +51,7 @@ overlay.onUpdate(({ projected }) => {
 
 ## Documentation
 
-Each plugin's options and events are documented at https://navara-docs.netlify.app/.
+Each plugin's options and events are documented at https://navara-docs.reearth.workers.dev//.
 
 ## License
 

package/dist/index.d.ts

@@ -1,12 +1,16 @@
 import { default as default_2 } from '@navaramap/three';
 import { DefaultDescriptions } from '@navaramap/three-default-plugin';
+import { GLTFModelDesc } from '@navaramap/three-default-descs';
 import { Layer } from '@navaramap/three';
+import { MeshHandle } from '@navaramap/three';
 import { Plugin as Plugin_2 } from '@navaramap/three';
 import { QuantizedMeshSource } from '@navaramap/three';
 import { Source } from '@navaramap/three';
 import { TerrainSourceLayer } from '@navaramap/three';
 import { ViewContext } from '@navaramap/three';
 
+declare type ActionListener = (action: PersonViewAction) => void;
+
 /**
  * Animation configuration for the model.
  * Clip names are model-specific — check your GLTF file for available clips.
@@ -22,8 +26,14 @@ export declare type AnimationConfig = {
     walkClip?: string;
     /** Clip name played while the model is dashing (dash key held). */
     dashClip: string;
-    /** Playback speed multiplier. */
-    speed: number;
+    /** Playback speed for any clip without a per-clip override below. */
+    speed?: number;
+    /** Playback speed for the idle clip (falls back to {@link speed}). */
+    idleSpeed?: number;
+    /** Playback speed for the walk clip (falls back to {@link speed}). */
+    walkSpeed?: number;
+    /** Playback speed for the dash clip (falls back to {@link speed}). */
+    dashSpeed?: number;
     /** Duration in seconds for cross-fade transitions between clips. */
     crossfadeDuration: number;
 };
@@ -87,6 +97,57 @@ export declare type CharacterConfig = {
     receiveShadow?: boolean;
 };
 
+/** Terrain collision configuration. See {@link CollisionMode}. */
+export declare type CollisionConfig = {
+    /** @defaultValue `"off"` */
+    mode?: CollisionMode;
+    /**
+     * Height (meters) kept above the sampled terrain surface — the character's
+     * feet in `"ground"` mode, the floor it cannot sink below in `"clamp"`.
+     * @defaultValue `0`
+     */
+    groundOffset?: number;
+    /**
+     * Tilt the character to match the slope it stands on. Costs several extra
+     * terrain lookups per frame, and fades out as it leaves the ground in
+     * `"clamp"` mode.
+     * @defaultValue `true`
+     */
+    alignToSlope?: boolean;
+    /**
+     * Footprint (meters) the slope under the character is averaged over. The
+     * default suits the triangle spacing terrain meshes arrive at; below that
+     * there is nothing left to average and the tilt starts to step.
+     * @defaultValue `4`
+     */
+    slopeSampleDistance?: number;
+    /**
+     * Largest tilt (radians) {@link alignToSlope} may apply, so ground far
+     * steeper than anything walkable does not lay the character flat against it.
+     * @defaultValue `Math.PI / 4` (45°)
+     */
+    maxSlopeTilt?: number;
+    /**
+     * How much of the terrain's slope the camera pitch follows, from `0` (fixed
+     * pitch, so a steep hillside fills the frame) to `1` (the view runs parallel
+     * to the slope, looking up a climb and down a descent). Applies to the TPV
+     * chase camera and the FPV eye line alike.
+     * @defaultValue `1`
+     */
+    cameraSlopeFollow?: number;
+};
+
+/**
+ * How the character's altitude reacts to the terrain surface.
+ *
+ * - `"off"` — altitude is driven purely by the ascend / descend keys.
+ * - `"clamp"` — free flight, but the terrain acts as a floor: the character is
+ *   pushed up whenever it would end up below the surface.
+ * - `"ground"` — the character is glued to the terrain surface, so it walks up
+ *   and down slopes. The ascend / descend keys have no effect in this mode.
+ */
+export declare type CollisionMode = "off" | "clamp" | "ground";
+
 /**
  * Keyboard bindings. Each entry takes an array of `KeyboardEvent.code`
  * values (e.g. `["KeyW"]`, `["ArrowUp", "ControlLeft"]`) so multiple
@@ -158,8 +219,20 @@ export declare type OverlayState = {
     projected: Map<string, ProjectedPosition>;
 };
 
+/**
+ * A recognized control input. Delivered to {@link PersonViewPlugin.onAction}
+ * listeners on each keypress — e.g. to dismiss an on-screen controls hint once
+ * the user starts driving the character.
+ */
+export declare type PersonViewAction = "forward" | "backward" | "turnLeft" | "turnRight" | "ascend" | "descend" | "dash" | "orbitCamera" | "toggleView";
+
 export declare type PersonViewConfig = {
     character?: CharacterConfig;
+    /**
+     * Terrain collision. Off by default — the character flies freely and ignores
+     * the terrain surface.
+     */
+    collision?: CollisionConfig;
     /** When true, the camera is always free (no Alt-hold required). */
     allowCameraControl?: boolean;
     /** Initial view mode. */
@@ -170,6 +243,11 @@ export declare type PersonViewConfig = {
     rotationSpeed?: number;
     /** m/s */
     altSpeed?: number;
+    /**
+     * Factor applied to {@link moveSpeed} while the dash key is held.
+     * @defaultValue `2.5`
+     */
+    dashSpeedMultiplier?: number;
     minAlt?: number;
     maxAlt?: number;
     cameraDistance?: number;
@@ -223,17 +301,23 @@ export declare type PersonViewConfig = {
 export declare class PersonViewPlugin extends Plugin_2<View, ViewContext> {
     private view?;
     private config;
+    private collision;
     private character;
     private keys;
     private keyToAction;
     private handle;
     private modelRef;
     private animId;
+    /** Whether the character has been placed, so `start()` resumes from here. */
+    private placed;
     private lastTime;
     private state;
     private listeners;
+    private actionListeners;
     private heldActions;
-    private dashMultiplier;
+    /** Whether the dash key is held. Kept separate from the numeric speed factor
+     * so the dash animation still plays when `dashSpeedMultiplier` is 1 (or <1). */
+    private dashHeld;
     private orbitKeyHeld;
     private orbitLatched;
     private currentAnimState;
@@ -249,18 +333,69 @@ export declare class PersonViewPlugin extends Plugin_2<View, ViewContext> {
     private _north;
     private _worldForward;
     private _offset;
+    private _probePos;
     private _headingMatrix;
+    private _tiltMatrix;
     private _characterFrame;
+    /** Smoothed pitch (radians) the chase camera gives up to follow the slope. */
+    private cameraSlopePitch;
+    private slopeGradEast;
+    private slopeGradNorth;
+    /**
+     * Terrain height (meters) sampled under the character last frame, with the
+     * position it was taken at, so the next frame can re-sample the same spot and
+     * tell a change in the terrain data apart from the character having moved.
+     */
+    private lastGroundSample?;
+    /** Meters of terrain data shift not yet passed on to the character. */
+    private unabsorbedGroundShift;
+    /** Speed (m/s) that shift is being worked off at, positive when rising. */
+    private settleVelocity;
+    /** Surface height (meters) the character stands on, once settling is applied. */
+    private groundSurfaceHeight?;
     constructor(config?: PersonViewConfig);
     init(view: View, _ctx: ViewContext): Promise<void>;
+    /**
+     * Take over the camera and start reading the movement keys. Calling it again
+     * after {@link stop} resumes from wherever the character was left, rather
+     * than starting over at the configured position.
+     */
     start(): void;
+    /**
+     * Hand the camera back to the view's own controls and stop reading the
+     * movement keys, leaving the character where it stands. {@link start}
+     * resumes from there — use the two to step out of person view and back
+     * without losing the position.
+     */
+    stop(): void;
+    /** Stop the per-frame loop and the key handling, keeping everything else. */
+    private releaseControl;
+    /**
+     * Run the per-frame loop from now. The clock restarts with it, so a pause
+     * between `stop()` and `start()` is not delivered as one enormous frame.
+     */
+    private resumeLoop;
     /** Instantly move to a new geographic position. */
     teleport(options: TeleportOptions): void;
     getState(): PersonViewState;
     onStateChange(fn: StateListener): () => void;
+    /**
+     * Subscribe to control-input events. The callback fires once per keypress of
+     * any bound action (movement, dash, view toggle, orbit) — for example, to
+     * hide an on-screen controls hint once the user starts driving the
+     * character. Returns an unsubscribe function.
+     */
+    onAction(fn: ActionListener): () => void;
     setViewMode(mode: ViewMode): void;
     toggleViewMode(): void;
     setAllowCameraControl(value: boolean): void;
+    /**
+     * Update the terrain collision settings at runtime. Only the given fields
+     * change; the rest keep their current values.
+     */
+    setCollision(collision: CollisionConfig): void;
+    /** Current terrain collision settings. */
+    getCollision(): Readonly<ResolvedCollision>;
     /**
      * Rotate the character to the given heading in radians (0 = north,
      * increasing clockwise) without changing position. Snaps the chase camera to
@@ -293,7 +428,29 @@ export declare class PersonViewPlugin extends Plugin_2<View, ViewContext> {
     setFpvHeightOffset(meters: number): void;
     /** Current FPV eye height offset in meters. */
     getFpvHeightOffset(): number;
+    /**
+     * Set the base animation playback speed — the fallback used by any clip
+     * without a per-clip override (`idleSpeed` / `walkSpeed` / `dashSpeed`).
+     * Re-applies to the clip currently playing, so it takes effect immediately.
+     */
+    setAnimationSpeed(speed: number): void;
+    /** Current base animation playback speed (per-clip overrides aside). */
+    getAnimationSpeed(): number;
+    /**
+     * The loaded character model's mesh handle, or `null` before {@link start}
+     * has loaded it (or when no character is configured). Its `ref` is the
+     * GLTFModelDesc — reach the model itself through it, e.g. `model.ref.raw`
+     * for the underlying three.js object or `model.ref.getWorldPosition()`.
+     */
+    get model(): MeshHandle<GLTFModelDesc> | null;
+    /**
+     * Resolve the effective playback speed for a clip: its per-clip override
+     * (`idleSpeed` / `walkSpeed` / `dashSpeed`) if set, else the base `speed`.
+     */
+    private clipSpeed;
     dispose(): void;
+    /** Cross-fade the model onto `clip`, unless it is already the one playing. */
+    private playAnimation;
     private resolveCharacter;
     private buildKeyMap;
     private isFreeCamera;
@@ -309,6 +466,26 @@ export declare class PersonViewPlugin extends Plugin_2<View, ViewContext> {
      * the model, staying aimed at it so the model remains centered.
      */
     private placeChaseCamera;
+    /**
+     * Tilt `configured` (radians) with the slope the character is walking along,
+     * eased in over time. Position in degrees, `alt` in meters.
+     *
+     * A fixed pitch hugs a horizontal plane while the ground does not: on a steep
+     * climb the view runs into the hillside and the frame fills with ground. The
+     * slope is taken over the chase distance either side of the character, and
+     * fades out as it rises off the surface so a flying character in `"clamp"`
+     * mode keeps the pitch it was configured with.
+     */
+    private followSlopeWithPitch;
+    /**
+     * How much the ground still applies to a character at `alt`: `1` standing on
+     * the surface, fading to `0` once it is `scale` meters above it. Nothing the
+     * terrain does should tilt a character that is flying over it in `"clamp"`
+     * mode — neither the model nor the view follows a slope it has left behind.
+     */
+    private groundedFactor;
+    /** Terrain height `meters` along `heading` from a position in degrees. */
+    private terrainAlong;
     /**
      * Compose the character's world matrix as `ENU * Rz(-heading)`.
      *
@@ -323,11 +500,53 @@ export declare class PersonViewPlugin extends Plugin_2<View, ViewContext> {
      * its "facing-north, upright" rest pose. Heading then rotates the
      * already-upright model around world-up, regardless of which axis
      * the GLTF treats as forward.
+     *
+     * After the heading the frame's axes are X = right, Y = forward,
+     * Z = up, so `alignToSlope` tilts around X (nose up when climbing)
+     * then around Y (roll onto the side of the slope).
      */
     private composeCharacterFrame;
+    /** Eye-line height (meters) for a character standing at `alt`. */
+    private eyeHeightAt;
+    /** Terrain height at a position in radians, or `undefined` if not loaded. */
+    private sampleTerrain;
+    /**
+     * Apply terrain collision to a candidate altitude (meters). Positions are in
+     * radians. `deltaTime` drives the absorption of terrain data changes — pass
+     * `0` to land on the terrain the sampler reports right now.
+     */
+    private resolveGroundHeight;
+    /**
+     * Absorb terrain that moved because its *data* changed rather than because
+     * the character did, and return how much of that shift is still being held
+     * back (meters, positive when the data rose).
+     *
+     * Only one of the two is real ground: walking onto higher ground has to move
+     * the character at once or a climb buries it, while a tile re-measured at a
+     * finer LOD moving the surface hundreds of meters must not. Re-sampling the
+     * *previous* frame's position separates them — whatever the height there has
+     * changed by is data, and the rest is the character having moved.
+     */
+    private absorbGroundDataShift;
+    /** Drop the terrain history, so the next sample starts a fresh landing. */
+    private forgetGroundSamples;
+    /**
+     * Refresh the terrain gradient the slope tilt is built from, by probing a
+     * ring of points around the character (position in radians, `alt` in meters).
+     * `deltaTime` drives the smoothing — pass `0` to snap.
+     */
+    private updateSlopeTilt;
+    /**
+     * Terrain gradient (rise per meter, east and north) under a point given in
+     * radians, fitted to a ring of probes, or `undefined` while any of them is
+     * over terrain that has not loaded. The probes sit a few meters apart, so
+     * they share one ENU frame rather than each re-deriving its own.
+     */
+    private measureSlopeGradient;
     /** Advance a (lat,lng) point by `meters` along the given ENU heading. */
     private advanceLatLng;
     private notify;
+    private emitAction;
     private onKeyDown;
     private onKeyUp;
     private tick;
@@ -353,6 +572,8 @@ export declare type ProjectedPosition = {
     distance: number;
 };
 
+declare type ResolvedCollision = Required<CollisionConfig>;
+
 declare type StateListener = (s: PersonViewState) => void;
 
 /** Options for {@link PersonViewPlugin.teleport}. */
@@ -388,8 +609,28 @@ export declare type TileJson = {
     maxzoom?: number;
     /** Tiling scheme. `"tms"` flips the Y axis (raster sources only). @defaultValue "xyz" */
     scheme?: "xyz" | "tms";
+    /**
+     * Tile size in pixels. Not part of the TileJSON spec, but emitted by
+     * MapLibre-oriented tile servers; applied to `raster-dem` sources only.
+     * @defaultValue 512
+     */
+    tileSize?: number;
+    /**
+     * Elevation encoding of DEM tiles. Not part of the TileJSON spec, but
+     * emitted by MapLibre-oriented tile servers; applied to `raster-dem` sources
+     * only.
+     * @defaultValue "mapbox"
+     */
+    encoding?: TileJsonDemEncoding;
 };
 
+/**
+ * How a `raster-dem` document's RGB tiles encode elevation, matching MapLibre's
+ * `encoding` values. MapLibre's `"custom"` (free-form decode factors) is not
+ * supported.
+ */
+export declare type TileJsonDemEncoding = "mapbox" | "terrarium";
+
 /** Detail passed to the {@link TileJsonPlugin} `loaded` event. */
 export declare type TileJsonLoadedEvent = {
     /** The Navara source created for the document. */
@@ -420,9 +661,13 @@ export declare class TileJsonPlugin extends Plugin_2<View_4, ViewContext> {
      *
      * `desc.url` is the TileJSON document URL; the plugin fetches it, then creates
      * one source of the requested `desc.type` using the document's first tile
-     * endpoint, `minzoom`/`maxzoom`, and `scheme`. The document's `attribution` is
-     * surfaced through the view's built-in attribution UI (`view.attribution`), and
-     * a `loaded` event is emitted carrying the source, document, and attribution.
+     * endpoint, `minzoom`/`maxzoom`, and `scheme` — plus, for `raster-dem`, the
+     * MapLibre-compatible `tileSize` and `encoding` fields (defaulting to
+     * MapLibre's 512 and `"mapbox"`). Each of those fields can also be set on
+     * `desc` itself, taking precedence over the document. The document's
+     * `attribution` is surfaced through the view's built-in attribution UI
+     * (`view.attribution`), and a `loaded` event is emitted carrying the source,
+     * document, and attribution.
      *
      * A TileJSON `tiles` array lists mirror endpoints for the same tileset (as in
      * MapLibre, which shards requests across them). Navara sources take a single
@@ -456,15 +701,36 @@ export declare type TileJsonPluginEventMap = {
     loaded: (event: TileJsonLoadedEvent) => void;
 };
 
+/** Registers a TileJSON document as a `raster-dem` (elevation) source. */
+export declare type TileJsonRasterDemSourceDescription = TileJsonSourceDescriptionBase & {
+    type: "raster-dem";
+    /** Overrides the document's `tileSize` when set. @defaultValue 512 */
+    tileSize?: number;
+    /** Overrides the document's `encoding` when set. @defaultValue "mapbox" */
+    encoding?: TileJsonDemEncoding;
+};
+
+/** Registers a TileJSON document as a `raster-tile` (imagery) source. */
+export declare type TileJsonRasterTileSourceDescription = TileJsonSourceDescriptionBase & {
+    type: "raster-tile";
+};
+
 /**
  * Describes a TileJSON tile source to register via {@link TileJsonPlugin.addSource}.
  * Mirrors the shape of {@link ThreeView.addSource}, except `url` is the TileJSON
  * document URL (not a tile template) — the plugin fetches it and derives the tile
- * URL, zoom range, and attribution from the document.
+ * URL, zoom range, and attribution from the document. Document-derived fields
+ * (`minzoom`, `maxzoom`, `scheme` — plus `tileSize` and `encoding` for
+ * `raster-dem`) can also be set here to take precedence over the document.
  */
-export declare type TileJsonSourceDescription = {
-    /** Navara source type to create, as in `addSource`. */
-    type: TileJsonSourceType;
+export declare type TileJsonSourceDescription = TileJsonRasterTileSourceDescription | TileJsonVectorTileSourceDescription | TileJsonRasterDemSourceDescription;
+
+/**
+ * Fields shared by every {@link TileJsonSourceDescription} variant. Alongside
+ * `url` and `id`, it accepts the same optional fields the TileJSON document
+ * carries; a field set here takes precedence over the fetched document's value.
+ */
+declare type TileJsonSourceDescriptionBase = {
     /** URL of the TileJSON 3.0.0 document to fetch and expand. */
     url: string;
     /**
@@ -473,14 +739,25 @@ export declare type TileJsonSourceDescription = {
      * handle. When omitted, the engine generates one.
      */
     id?: string;
+    /** Overrides the document's `minzoom` when set. */
+    minzoom?: number;
+    /** Overrides the document's `maxzoom` when set. */
+    maxzoom?: number;
+    /** Overrides the document's `scheme` when set. */
+    scheme?: "xyz" | "tms";
 };
 
 /**
  * Which Navara source type a TileJSON document is materialized into. Declared by
  * the caller because TileJSON has no field that reliably distinguishes raster
- * imagery from vector tiles.
+ * imagery from vector or elevation tiles.
  */
-export declare type TileJsonSourceType = "raster-tile" | "vector-tile";
+export declare type TileJsonSourceType = "raster-tile" | "vector-tile" | "raster-dem";
+
+/** Registers a TileJSON document as a `vector-tile` (MVT) source. */
+export declare type TileJsonVectorTileSourceDescription = TileJsonSourceDescriptionBase & {
+    type: "vector-tile";
+};
 
 declare type UpdateListener = (state: OverlayState) => void;