@solidrt/3d 0.0.60 → 0.0.61

package/src/first-person.ts

@@ -47,12 +47,12 @@
 // control, not two mounts. Only the initial pose is copied at creation;
 // later pose changes go through set() and the verbs.
 
-import { createMemo, createSignal, untrack } from "@solidjs/signals"
+import { untrack } from "@solidjs/signals"
 import { createAxes } from "@solidrt/core/input"
 import type { Axes, Vec2 } from "@solidrt/core/input"
 import type { CameraUpdate } from "./camera.ts"
 import type { Vec3 } from "./math.ts"
-import { easeStep, GLIDE_EASE, GLIDE_EPSILON } from "./motion.ts"
+import { checkShake, createActivity, createLanes, easeStep, GLIDE_EASE, GLIDE_EPSILON } from "@solidrt/core/camera-control"
 
 // One element height of drag sweeps this many turns of look (half a turn:
 // a drag across the screen turns the walker around).
@@ -61,6 +61,8 @@ const DRAG_TURNS = 0.5
 const LOOK_RATE = 0.4
 // Default walking speed, world units per second.
 const MOVE_SPEED = 3
+// Default `boostSpeed`: the multiplier on moveSpeed while `boost` is held.
+const BOOST_SPEED = 2
 // Pitch clamps stop short of the poles so the look direction never
 // degenerates against world up.
 const PITCH_LIMIT = Math.PI / 2 - 0.01
@@ -84,6 +86,11 @@ export type FirstPersonCameraOptions = FirstPersonPose & {
   maxPitch?: number
   /** Movement speed in world units per second (default 3). */
   moveSpeed?: number
+  /** Multiplier on `moveSpeed` while the `boost` axis reads non-zero (a
+   * held Shift, a pressed stick; default 2): the sprint, walking and
+   * flying alike. Scales rates only; a `move` delta is a step in world
+   * units regardless. */
+  boostSpeed?: number
   /** Multiplier over the built-in look sensitivities (drags, mouse motion
    * and rates alike). */
   lookSpeed?: number
@@ -100,7 +107,7 @@ export type FirstPersonCameraOptions = FirstPersonPose & {
   clampPosition?: (next: Vec3, current: Vec3) => Vec3
 }
 
-export type FirstPersonAxes = { look: "vec2"; move: "vec2"; rise: "axis" }
+export type FirstPersonAxes = { look: "vec2"; move: "vec2"; rise: "axis"; boost: "axis" }
 
 export type FirstPersonCamera = {
   /** Eye position (a fresh array per call). */
@@ -127,7 +134,9 @@ export type FirstPersonCamera = {
   update(dt: number): boolean
   /** The input abstraction: `look` (vec2, element heights of drag / turns
    * per second), `move` (vec2 [right, forward], forward = -y; world units
-   * per delta, `moveSpeed` per second) and `rise` (axis, fly only). */
+   * per delta, `moveSpeed` per second), `rise` (axis, fly only) and
+   * `boost` (axis: non-zero multiplies the move and rise rates by
+   * `boostSpeed`; a button binding reads 1 while held). */
   axes: Axes<FirstPersonAxes>
   /** Turn by radians (yaw positive left, pitch positive up; clamps
    * apply) and push. */
@@ -136,6 +145,13 @@ export type FirstPersonCamera = {
    * projection when walking, the view direction when flying) and up
    * (world up, fly mode only), through `clampPosition`, and push. */
   moveBy(right: number, forward: number, up?: number): void
+  /** A shake on the lane (okf/design/camera-controls.md): a view KICK,
+   * the first-person convention - `strength` is the peak rotation in
+   * TURNS (0.01 is 3.6 degrees) of yaw (x) and pitch (y), the look
+   * axis's unit, `duration` seconds, an optional frequency and direction
+   * ([1, 0] yaws only). Shakes sum and decay; the pose is untouched - a
+   * hit, a recoil, a footstep. */
+  shake(strength: number, duration: number, opts?: { frequency?: number; direction?: Vec2 }): void
 }
 
 // The goal pose a glide eases toward (see the header).
@@ -174,6 +190,7 @@ export function createFirstPersonCamera(camera: FirstPersonTarget, options: Firs
   // Everything below the pose is read from `options` where it applies.
   let lookSpeed = () => options.lookSpeed ?? 1
   let moveSpeed = () => options.moveSpeed ?? MOVE_SPEED
+  let boostSpeed = () => options.boostSpeed ?? BOOST_SPEED
   let clampedPitch = (v: number) => clampNum(v, options.minPitch ?? -PITCH_LIMIT, options.maxPitch ?? PITCH_LIMIT)
   let clampPitch = () => {
     pitch = clampedPitch(pitch)
@@ -184,22 +201,25 @@ export function createFirstPersonCamera(camera: FirstPersonTarget, options: Firs
   // that starts or drops it refreshes (ownedWrite: entries run from
   // component bodies and handlers alike).
   let motion: Motion | null = null
-  let [motionActive, setMotionActive] = createSignal(false, { ownedWrite: true })
-  let notify = () => {
-    let now = motion !== null
-    if (now !== untrack(motionActive)) setMotionActive(now)
-  }
+  let lanes = createLanes()
+  // The frame-loop gate (core's createActivity), built once the axes exist.
+  let activity!: ReturnType<typeof createActivity>
+  let notify = () => activity.notify()
   let interrupt = () => {
     motion = null
   }
 
-  let forward = (): Vec3 => {
-    let cp = Math.cos(pitch)
-    return [-Math.sin(yaw) * cp, Math.sin(pitch), -Math.cos(yaw) * cp]
+  let forwardOf = (y: number, p: number): Vec3 => {
+    let cp = Math.cos(p)
+    return [-Math.sin(y) * cp, Math.sin(p), -Math.cos(y) * cp]
   }
+  let forward = (): Vec3 => forwardOf(yaw, pitch)
+  // The shake lane kicks the view: the pushed look direction turns by the
+  // lane's yaw and pitch (turns), the pose and the eye stay.
   let push = () => {
     changed = true
-    let f = forward()
+    let [ky, kp] = lanes.total(undefined)
+    let f = ky === 0 && kp === 0 ? forward() : forwardOf(yaw - ky * 2 * Math.PI, clampedPitch(pitch - kp * 2 * Math.PI))
     camera.setCamera({ position: copy(position), target: [position[0] + f[0], position[1] + f[1], position[2] + f[2]] })
   }
   let look = (dYaw: number, dPitch: number) => {
@@ -241,7 +261,7 @@ export function createFirstPersonCamera(camera: FirstPersonTarget, options: Firs
   }
 
   let axes = createAxes<FirstPersonAxes>(
-    { look: "vec2", move: "vec2", rise: "axis" },
+    { look: "vec2", move: "vec2", rise: "axis", boost: "axis" },
     {
       onBegin: () => {
         interrupt()
@@ -264,7 +284,8 @@ export function createFirstPersonCamera(camera: FirstPersonTarget, options: Firs
       },
     },
   )
-  let active = createMemo(() => motionActive() || axes.active())
+  activity = createActivity(() => motion !== null || lanes.active(), () => axes.active())
+  let active = activity.active
 
   clampPitch()
   push()
@@ -309,7 +330,9 @@ export function createFirstPersonCamera(camera: FirstPersonTarget, options: Firs
       let [mx, my] = untrack(() => axes.rate("move"))
       let rise = untrack(() => axes.rate("rise"))
       if (mx !== 0 || my !== 0 || rise !== 0) {
-        let speed = moveSpeed() * dt
+        // A held boost (any non-zero read) scales the rates, not a nudge.
+        let boost = untrack(() => axes.rate("boost")) !== 0 ? boostSpeed() : 1
+        let speed = moveSpeed() * boost * dt
         interrupt()
         step(mx * speed, -my * speed, rise * speed)
         moved = true
@@ -318,6 +341,10 @@ export function createFirstPersonCamera(camera: FirstPersonTarget, options: Firs
         glideStep(dt)
         moved = true
       }
+      if (lanes.active() && dt > 0) {
+        lanes.step(dt)
+        moved = true
+      }
       if (moved) push()
       notify()
       let result = changed
@@ -341,5 +368,10 @@ export function createFirstPersonCamera(camera: FirstPersonTarget, options: Firs
       push()
       notify()
     },
+    shake(strength, duration, opts) {
+      checkShake("createFirstPersonCamera", strength, duration, opts)
+      lanes.shake(strength, duration, opts)
+      notify()
+    },
   }
 }