@edv4h/usketch-plugin-character 0.3.0 → 0.4.0

package/dist/character-layer.js

@@ -1,13 +1,18 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 // The one fixed (screen-space) layer that places every character — self and remote
 // — at `worldToScreen(position)`. It draws NOTHING itself: each spot is a zero-size,
 // pointer-transparent wrapper whose content is the host's `renderCharacter`. One
 // screen-space layer keeps self/remote consistent (same size under zoom, same
-// `screenHeading` math under camera rotation).
+// `screenHeading` math under camera rotation). The optional `renderShadow` gets a spot
+// of its own on the GROUND under each character, while the body stands at its feet
+// height — under a 3D view (Mode 7) a jump lifts the body off its shadow.
 import { viewportRotation, worldToScreen, wrapDeg } from "@edv4h/usketch-shared";
 import { useSyncExternalStore } from "react";
-function Spot({ x, y, lift, renderer, props, }) {
-    return (_jsx("div", { "data-character-id": props.id, style: {
+import { hoverGaugeOf } from "./character-store.js";
+/** Screen px a shadow floats above its ground, so it doesn't z-fight a raised terrain top. */
+const SHADOW_LIFT_PX = 0.5;
+function Spot({ shadow = false, x, y, lift, renderer, props, }) {
+    return (_jsx("div", { "data-character-id": shadow ? undefined : props.id, "data-character-shadow": shadow ? props.id : undefined, style: {
             position: "absolute",
             left: x,
             top: y,
@@ -22,12 +27,15 @@ export function CharacterLayer({ store, viewport, heightAt, }) {
     const renderer = store.getRenderer();
     if (!renderer)
         return null; // headless: no look supplied → draw nothing
+    const shadowRenderer = store.getShadowRenderer();
     const rot = viewportRotation(viewport);
-    const spots = [];
+    const bodies = [];
     for (const r of state.remotes.values()) {
-        const p = worldToScreen(r.x, r.y, viewport);
         const elevation = heightAt?.(r.x, r.y) ?? 0;
-        spots.push(_jsx(Spot, { x: p.x, y: p.y, lift: elevation * viewport.zoom, renderer: renderer, props: {
+        const z = Math.max(elevation, r.z ?? elevation);
+        bodies.push({
+            at: worldToScreen(r.x, r.y, viewport),
+            props: {
                 id: r.id,
                 isSelf: false,
                 heading: r.heading,
@@ -41,14 +49,24 @@ export function CharacterLayer({ store, viewport, heightAt, }) {
                 appearance: r.appearance,
                 name: r.name,
                 elevation,
-            } }, `remote-${r.id}`));
+                z,
+                altitude: z - elevation,
+                airborne: r.airborne,
+                verticalSpeed: r.vz,
+                hovering: r.hovering,
+                hoverGauge: r.hoverGauge,
+            },
+        });
     }
     if (state.enabled && state.spawned) {
         const { pose } = state;
-        const p = worldToScreen(pose.x, pose.y, viewport);
         const elevation = heightAt?.(pose.x, pose.y) ?? 0;
+        // Before the first vertical step a fresh spawn's `z` may still be below the ground.
+        const z = Math.max(elevation, pose.z);
         // Self last → drawn on top of the others.
-        spots.push(_jsx(Spot, { x: p.x, y: p.y, lift: elevation * viewport.zoom, renderer: renderer, props: {
+        bodies.push({
+            at: worldToScreen(pose.x, pose.y, viewport),
+            props: {
                 id: "self",
                 isSelf: true,
                 heading: pose.heading,
@@ -62,15 +80,28 @@ export function CharacterLayer({ store, viewport, heightAt, }) {
                 appearance: state.appearance,
                 name: state.name,
                 elevation,
-            } }, "self"));
+                z,
+                altitude: z - elevation,
+                airborne: pose.airborne,
+                verticalSpeed: pose.vz,
+                hovering: pose.hovering,
+                hoverGauge: hoverGaugeOf(state),
+            },
+        });
     }
-    if (spots.length === 0)
+    if (bodies.length === 0)
         return null;
-    return (_jsx("div", { style: {
+    const key = (props) => (props.isSelf ? "self" : `remote-${props.id}`);
+    // Shadows first, so every body draws over every shadow.
+    const shadowSpots = shadowRenderer
+        ? bodies.map(({ at, props }) => (_jsx(Spot, { shadow: true, x: at.x, y: at.y, lift: props.elevation * viewport.zoom + SHADOW_LIFT_PX, renderer: shadowRenderer, props: props }, `shadow-${key(props)}`)))
+        : [];
+    const bodySpots = bodies.map(({ at, props }) => (_jsx(Spot, { x: at.x, y: at.y, lift: props.z * viewport.zoom, renderer: renderer, props: props }, key(props))));
+    return (_jsxs("div", { style: {
             position: "absolute",
             inset: 0,
             pointerEvents: "none",
             transformStyle: "preserve-3d",
-        }, children: spots }));
+        }, children: [shadowSpots, bodySpots] }));
 }
 //# sourceMappingURL=character-layer.js.map

package/dist/character-layer.js.map

@@ -1 +1 @@
-{"version":3,"file":"character-layer.js","sourceRoot":"","sources":["../src/character-layer.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"character-layer.js","sourceRoot":"","sources":["../src/character-layer.tsx"],"names":[],"mappings":"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"}

package/dist/character-physics.d.ts

@@ -7,6 +7,19 @@ export interface MoveInput {
     right: boolean;
     /** Vehicle: the drift key (only acts when drift is enabled). */
     drift?: boolean;
+    /** The drift key was pressed since the previous step (an edge: starts a drift hop). */
+    driftPressed?: boolean;
+    /** The jump key is held (a release while rising cuts the jump short). */
+    jump?: boolean;
+    /** The jump key was pressed since the previous step (an edge, so a quick tap counts). */
+    jumpPressed?: boolean;
+    /**
+     * Analog forward / back, -1 (full reverse / screen down) … 1 (full throttle / screen
+     * up), e.g. from a touch stick. When set it replaces `up` / `down`.
+     */
+    throttle?: number;
+    /** Analog steering, -1 (left) … 1 (right). When set it replaces `left` / `right`. */
+    steer?: number;
 }
 export declare const NO_INPUT: MoveInput;
 export interface CharacterPose {
@@ -28,6 +41,23 @@ export interface CharacterPose {
     slip: number;
     /** Vehicle: the running drift's direction, -1 (left) / 1 (right), 0 = not drifting. */
     drift: -1 | 0 | 1;
+    /**
+     * Height of the character's feet, world units — absolute, like the ground height
+     * (0 = the flat board). On the ground it equals the ground height; it rises above it
+     * while jumping or falling, so it stays smooth across cliff edges.
+     */
+    z: number;
+    /** Vertical speed, world units / s (positive = rising). */
+    vz: number;
+    /** Whether the character is in the air (jumping or falling). */
+    airborne: boolean;
+    /** Hovering: the jump key held while falling slows the descent (see `HoverParams`). */
+    hovering: boolean;
+    /**
+     * Hover gauge, 0 (empty) … 1 (full): drains while hovering, refills on the ground.
+     * Stays 1 while hovering is off.
+     */
+    hoverGauge: number;
 }
 /** A pose at rest at the origin, facing up. */
 export declare const ORIGIN_POSE: CharacterPose;
@@ -71,6 +101,13 @@ export interface DriftParams {
     steerSlipAngle: number;
     /** How fast the slip follows its target (1/s, exponential). */
     recoveryRate: number;
+    /**
+     * Pressing the drift key on the ground hops first (a small jump; the drift starts on
+     * landing if still held and steering, since a car can't steer in the air).
+     */
+    hop: boolean;
+    /** Height of that hop, world units. */
+    hopHeight: number;
 }
 export declare const DEFAULT_DRIFT: DriftParams;
 /** Unit vector of a heading in world space (0° → (0, -1), 90° → (1, 0)). */
@@ -82,17 +119,25 @@ export declare function headingVector(deg: number): {
 export declare function vectorHeading(x: number, y: number): number;
 /** Move `from` toward `to` by at most `maxStep` degrees, the short way round. */
 export declare function turnToward(from: number, to: number, maxStep: number): number;
+/** Clamp to -1 … 1; a missing or non-finite value counts as 0 (released). */
+export declare const clampUnit: (v: number | undefined) => number;
+/** Forward / back of an input, -1 … 1: the analog `throttle` when set, else up − down. */
+export declare function inputThrottle(input: MoveInput): number;
+/** Left / right of an input, -1 … 1: the analog `steer` when set, else right − left. */
+export declare function inputSteer(input: MoveInput): number;
 /**
  * Advance `pose` by `dt` seconds.
  *
  * - `directional`: the held keys give a SCREEN-space direction (up = screen up),
  *   turned into world space through the camera rotation; the character moves that
  *   way at `moveSpeed` and its heading turns toward it at `turnRate`. (Turning
- *   rather than snapping keeps a heading-following camera from spinning.)
+ *   rather than snapping keeps a heading-following camera from spinning.) An analog
+ *   input (`steer` / `throttle`) moves at `moveSpeed` × its length (capped at 1).
  * - `vehicle`: up/down are throttle/reverse along the heading, left/right steer.
  *   Steering authority scales with speed (a stopped car can't turn) and inverts
  *   when reversing, like a car. With `driftParams`, holding the drift key while
- *   steering at speed drifts (see `DriftParams`).
+ *   steering at speed drifts (see `DriftParams`). An analog `throttle` aims for that
+ *   fraction of the top speed, and an analog `steer` turns by that fraction.
  */
 export declare function stepCharacter(pose: CharacterPose, input: MoveInput, dt: number, scheme: ControlScheme, params: MotionParams, cameraRotation?: number, driftParams?: DriftParams | null): CharacterPose;
 /** Ground height at a world point (world units; see `groundHeightService`). */
@@ -105,4 +150,113 @@ export type HeightAt = (x: number, y: number) => number;
  * vehicle also loses its speed, as if it bumped the wall). The heading still turns.
  */
 export declare function constrainToGround(prev: CharacterPose, next: CharacterPose, heightAt: HeightAt, maxStep: number): CharacterPose;
+/**
+ * Jump tuning. The arc is set by its apex `height` and `timeToApex`; gravity and the
+ * take-off speed follow from them (see `jumpArc`).
+ */
+export interface JumpParams {
+    /** Apex of a jump from the ground, world units above the take-off point. */
+    height: number;
+    /** Seconds from take-off to the apex. */
+    timeToApex: number;
+    /** Gravity multiplier while falling (> 1 = floaty rise, snappy fall). */
+    fallGravity: number;
+    /** Releasing the key while rising scales the vertical speed by this (0 … 1): a short hop. */
+    releaseCut: number;
+    /** Seconds after walking off a ledge during which a jump still counts as from the ground. */
+    coyoteTime: number;
+    /** Seconds a press just before landing is remembered and jumps on touchdown. */
+    bufferTime: number;
+    /** Extra jumps in the air (0 = a single jump, 1 = a double jump …), reset on landing. */
+    airJumps: number;
+    /** An air jump's height as a fraction of `height` (its take-off speed is × √ratio). */
+    airJumpRatio: number;
+    /** Hovering while the key is held in a fall, or `null` = off. */
+    hover: HoverParams | null;
+}
+/**
+ * Hover tuning. Once the air jumps are used up (or there are none), holding the jump key
+ * while falling fires a thrust and drains a gauge; an empty gauge falls normally. The
+ * gauge refills on the ground over `rechargeTime` (not instantly on landing).
+ *
+ * The thrust is a multiple of gravity (a thrust-to-weight ratio, so no mass is needed):
+ * below 1 the character still sinks, at 1 it keeps its vertical speed, above 1 it climbs
+ * for as long as the key is held. Sinking is capped at `fallSpeed`, climbing at
+ * `riseSpeed`.
+ */
+export interface HoverParams {
+    /** Seconds of hover a full gauge lasts. */
+    duration: number;
+    /** Fastest descent while hovering, world units / s (0 = never sink). */
+    fallSpeed: number;
+    /** Seconds on the ground to refill an empty gauge. */
+    rechargeTime: number;
+    /** Thrust as a multiple of gravity: < 1 sinks, 1 balances, > 1 climbs. */
+    thrust: number;
+    /** Fastest climb while hovering, world units / s. */
+    riseSpeed: number;
+}
+export declare const DEFAULT_HOVER: HoverParams;
+export declare const DEFAULT_JUMP: JumpParams;
+/** Gravity (world units / s²) and take-off speed (world units / s) of a jump. */
+export declare function jumpArc(params: JumpParams): {
+    gravity: number;
+    speed: number;
+};
+/** Per-character jump bookkeeping that is not part of the visible pose. */
+export interface JumpTimers {
+    /** Seconds since the character last stood on the ground. */
+    sinceGround: number;
+    /** Seconds since the jump key was last pressed (`Infinity` = no pending press). */
+    sincePress: number;
+    /** The current airtime started with a jump (not a fall), so coyote time is spent. */
+    jumped: boolean;
+    /** The rise has been cut short already (the key was released). */
+    cut: boolean;
+    /** Air jumps used since the character last stood on the ground. */
+    airJumpsUsed: number;
+}
+export declare const IDLE_JUMP: JumpTimers;
+/**
+ * Advance the vertical motion by `dt` seconds, after the horizontal step put the
+ * character over ground of height `ground`.
+ *
+ * - On the ground, a step up (already limited to `maxStep` by `constrainToGround`) or a
+ *   step down of at most `maxStep` keeps the feet on the ground; a bigger drop starts a
+ *   fall instead of snapping down.
+ * - With `jump` tuning, a press (or one buffered for `bufferTime`) jumps from the ground
+ *   or within `coyoteTime` of leaving it; releasing the key while rising cuts the jump.
+ * - A fresh press in the air uses one of the `airJumps` while any remain (`airJumpRatio`
+ *   of the height); they come back on landing.
+ * - With `hover` tuning, once the air jumps are used up, holding the key while falling
+ *   hovers: the thrust pushes against gravity (see `hoverSpeed`) while the gauge drains,
+ *   and it keeps firing while the key stays held, also once it climbs; an empty gauge
+ *   falls normally. On the ground the gauge refills over `rechargeTime`.
+ * - A `hopHeight` above 0 (a vehicle's drift hop) makes a drift-key press on the ground
+ *   hop that high, under the same gravity.
+ * - In the air, gravity pulls the feet down (`fallGravity` × while falling) until they
+ *   meet the ground. Without `jump` the default arc's gravity still drives falls.
+ */
+export declare function stepVertical(pose: CharacterPose, timers: JumpTimers, input: MoveInput, dt: number, ground: number, maxStep: number, jump: JumpParams | null, hopHeight?: number): {
+    pose: CharacterPose;
+    timers: JumpTimers;
+};
+/**
+ * The input for the horizontal step on a frame that may start a drift hop: the press
+ * that hops doesn't also start the drift (it would carry through the air), so the drift
+ * begins on landing if the key is still held and steering.
+ */
+export declare function holdDriftForHop(input: MoveInput, pose: CharacterPose, hopHeight: number): MoveInput;
+/** An air jump's take-off speed: the same gravity reaches `ratio` × the height. */
+export declare function airJumpSpeed(takeoffSpeed: number, ratio: number): number;
+/**
+ * The vertical speed after `dt` seconds of hovering from `vz`: the thrust (× `gravity`)
+ * against gravity, so the speed changes by (thrust − 1) × gravity per second, kept
+ * between −`fallSpeed` (a faster fall is caught at once) and `riseSpeed`.
+ */
+export declare function hoverSpeed(vz: number, dt: number, gravity: number, hover: HoverParams): number;
+/** The hover gauge after `dt` seconds of hovering (a full gauge lasts `duration`). */
+export declare function drainHoverGauge(gauge: number, dt: number, hover: HoverParams): number;
+/** The hover gauge after `dt` seconds on the ground (empty → full in `rechargeTime`). */
+export declare function rechargeHoverGauge(gauge: number, dt: number, hover: HoverParams): number;
 //# sourceMappingURL=character-physics.d.ts.map

package/dist/character-physics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"character-physics.d.ts","sourceRoot":"","sources":["../src/character-physics.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"character-physics.d.ts","sourceRoot":"","sources":["../src/character-physics.ts"],"names":[],"mappings":"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"}