@solidrt/core 0.0.55 → 0.0.57

package/src/input-axes.ts

@@ -0,0 +1,180 @@
+// The control side of the input abstraction (ARCHITECTURE.md: controls
+// through an abstraction, never direct event handling). A control - a
+// camera controller, a character controller - declares the axes it
+// consumes and receives input only through them, in device-free units:
+//
+// - rates: -1..1 values sampled at update time (a held key, a deflected
+//   stick, a value an app set), which the control integrates over dt at
+//   its own speeds. Sources are added, never set: several may feed one
+//   axis (keys and a stick), and the control sums and clamps them, so
+//   removing one never has to know what the others hold.
+// - nudges: immediate deltas (a drag, a wheel notch, a pinch) in the
+//   vocabulary's units - view heights of travel, octaves of zoom, turns -
+//   applied at once, with the focal point (a fraction of the element)
+//   when the gesture has one. begin/end bracket a gesture, so a control
+//   can tell a finger's tracking (apply exactly) from an impulse (a wheel
+//   notch, unbracketed: ease it), stop a glide when a finger lands, and
+//   fling when it lifts.
+//
+// The values use the screen convention throughout: x right, y down, the
+// way pointer deltas and the web Gamepad API report (a stick pushed up
+// reads y = -1). A control that means "forward" by a vec2 reads -y.
+//
+// `active()` is the frame-loop gate: reactive, true while any rate source
+// reads non-zero, so a control's loop runs only while something drives it.
+// A rate source must therefore read reactive state (a signal, gamepads());
+// a source over plain variables never wakes the loop - the caller runs
+// update(dt) itself then.
+//
+// An input map drives an Axes object by action name (InputMap.drive); an
+// app can also add its own sources and nudges directly.
+
+import { createMemo, createSignal, untrack } from "@solidjs/signals"
+
+export type AxisKind = "axis" | "vec2"
+export type Vec2 = [number, number]
+export type AxisValue<K extends AxisKind> = K extends "axis" ? number : Vec2
+
+export type AxesDecl = Record<string, AxisKind>
+
+export interface AxesHooks<A extends AxesDecl> {
+  /** An immediate delta on `name`: view heights for a vec2, the axis's
+   * unit (octaves, turns) for an axis; `focal` in 0..1 of the element
+   * when the gesture has one (a pinch, a wheel). */
+  onNudge?: <N extends keyof A & string>(name: N, delta: AxisValue<A[N]>, focal: Vec2 | undefined) => void
+  /** A gesture on `name` started (a finger landed) / ended (lifted). */
+  onBegin?: (name: keyof A & string) => void
+  onEnd?: (name: keyof A & string) => void
+}
+
+export interface Axes<A extends AxesDecl> {
+  /** The declared axes, name to kind - what a map's drive() reads. */
+  readonly kinds: A
+  /** Add a rate source (reactive read, -1..1 per component); returns the
+   * remover. Several sources sum, then clamp (an axis to -1..1, a vec2 to
+   * unit length). */
+  add<N extends keyof A & string>(name: N, rate: () => AxisValue<A[N]>): () => void
+  /** The combined rate of `name` now (reactive read). */
+  rate<N extends keyof A & string>(name: N): AxisValue<A[N]>
+  /** Reactive: whether any rate reads non-zero - the frame-loop gate. */
+  active(): boolean
+  /** Apply an immediate delta (see AxesHooks.onNudge). */
+  nudge<N extends keyof A & string>(name: N, delta: AxisValue<A[N]>, focal?: Vec2): void
+  /** Bracket a gesture on `name`; nested begins count. */
+  begin(name: keyof A & string): void
+  end(name: keyof A & string): void
+  /** Whether a gesture on `name` is open (between begin and end). */
+  inGesture(name: keyof A & string): boolean
+}
+
+let clampNum = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v))
+
+/** Sum rate values of one kind and clamp: an axis to -1..1, a vec2 to unit length. */
+export function combineRates(kind: AxisKind, values: (number | Vec2)[]): number | Vec2 {
+  if (kind === "axis") {
+    let sum = 0
+    for (let v of values) sum += v as number
+    return clampNum(sum, -1, 1)
+  }
+  let x = 0
+  let y = 0
+  for (let v of values) {
+    x += (v as Vec2)[0]
+    y += (v as Vec2)[1]
+  }
+  let len = Math.hypot(x, y)
+  return len > 1 ? [x / len, y / len] : [x, y]
+}
+
+function checkValue(what: string, kind: AxisKind, v: unknown): void {
+  if (kind === "axis") {
+    if (typeof v !== "number" || !Number.isFinite(v)) throw new Error(`${what}: expected a finite number, got ${String(v)}`)
+    return
+  }
+  if (!Array.isArray(v) || v.length !== 2 || !Number.isFinite(v[0]) || !Number.isFinite(v[1])) {
+    throw new Error(`${what}: expected [x, y] finite numbers, got ${JSON.stringify(v)}`)
+  }
+}
+
+/**
+ * Declare a control's axes: `createAxes({ rotate: "vec2", zoom: "axis" },
+ * { onNudge, onBegin, onEnd })`. The hooks are how nudges reach the
+ * control's pose; rates are read back with `rate()` from its update(dt).
+ */
+export function createAxes<A extends AxesDecl>(kinds: A, hooks: AxesHooks<A> = {}): Axes<A> {
+  for (let [name, kind] of Object.entries(kinds)) {
+    if (kind !== "axis" && kind !== "vec2") throw new Error(`createAxes: axis "${name}" has kind "${String(kind)}", expected "axis" or "vec2"`)
+  }
+  let check = (name: string): AxisKind => {
+    let kind = kinds[name]
+    if (!kind) throw new Error(`createAxes: no axis "${name}" (declared: ${Object.keys(kinds).join(", ")})`)
+    return kind
+  }
+  // Sources per axis: a plain list is the truth (a write and a read in
+  // the same synchronous block must agree, which a signal's deferred
+  // write does not give), and a version signal notifies the reactive
+  // readers - active() and whoever tracks rate() - of a change.
+  let sources = new Map<string, (() => number | Vec2)[]>()
+  // ownedWrite: add() runs from component bodies (a map's drive()).
+  let [version, setVersion] = createSignal(0, { ownedWrite: true })
+  let bump = () => setVersion(untrack(version) + 1)
+  for (let name of Object.keys(kinds)) sources.set(name, [])
+  let rate = (name: string): number | Vec2 => {
+    version()
+    let values: (number | Vec2)[] = []
+    for (let read of sources.get(name)!) values.push(read())
+    return combineRates(kinds[name]!, values)
+  }
+  let active = createMemo(() => {
+    for (let [name, kind] of Object.entries(kinds)) {
+      let v = rate(name)
+      if (kind === "axis" ? v !== 0 : (v as Vec2)[0] !== 0 || (v as Vec2)[1] !== 0) return true
+    }
+    return false
+  })
+  let open = new Map<string, number>()
+  return {
+    kinds,
+    add(name, read) {
+      check(name)
+      if (typeof read !== "function") throw new Error(`createAxes: add("${name}") expects a function`)
+      let list = sources.get(name)!
+      list.push(read)
+      bump()
+      return () => {
+        let i = list.indexOf(read)
+        if (i < 0) return
+        list.splice(i, 1)
+        bump()
+      }
+    },
+    rate(name) {
+      check(name)
+      return rate(name) as never
+    },
+    active,
+    nudge(name, delta, focal) {
+      let kind = check(name)
+      checkValue(`nudge("${name}")`, kind, delta)
+      if (focal !== undefined) checkValue(`nudge("${name}") focal`, "vec2", focal)
+      hooks.onNudge?.(name, delta, focal)
+    },
+    begin(name) {
+      check(name)
+      let depth = open.get(name) ?? 0
+      open.set(name, depth + 1)
+      if (depth === 0) hooks.onBegin?.(name)
+    },
+    end(name) {
+      check(name)
+      let depth = open.get(name) ?? 0
+      if (depth === 0) return
+      open.set(name, depth - 1)
+      if (depth === 1) hooks.onEnd?.(name)
+    },
+    inGesture(name) {
+      check(name)
+      return (open.get(name) ?? 0) > 0
+    },
+  }
+}

package/src/input-gamepad-device.ts

@@ -0,0 +1,161 @@
+// A gamepad as input sources, over any accessor of pad snapshots: sticks
+// and the dpad as vec2, triggers and shoulders as axes, any button as a
+// button, any raw axis by name. Runtime-free (the accessor is injected,
+// the public `gamepad` in input-gamepad.ts hands in core's gamepads()),
+// so the join logic below runs headless in the checks.
+//
+// Every read is reactive when the accessor is (gamepads() is a signal),
+// so a stick moved while a control's frame loop is off wakes it. Sticks
+// pass through a radial dead zone; the screen convention holds (a stick
+// pushed up reads y = -1, as the web Gamepad API reports it).
+//
+// Joining: `createGamepadJoin` makes a device with no slot until a pad no
+// other joining device holds presses any button, then keeps that slot -
+// Unity's join manager, for a couch game that seats players in the order
+// they pick up a pad. A claim lasts until the owning scope is disposed
+// (an unmounted pane frees its pad); with no owner, for the session.
+
+import { createEffect, createRoot, createSignal, getOwner, onCleanup } from "@solidjs/signals"
+import type { GamepadState } from "./gamepad"
+import type { InputSource } from "./input-map"
+import type { Vec2 } from "./input-axes"
+
+// Stick deflection below which a resting stick reads as zero (radial:
+// the whole vector, so a stick nudged diagonally also rests).
+const STICK_DEADZONE = 0.15
+
+export type PadsAccessor = () => (GamepadState | null)[]
+
+export interface GamepadDevice {
+  /** The slot this device reads: a number for one pad, undefined for every
+   * connected pad (`gamepad()`) or for a joining device no pad has claimed
+   * yet (reactive: it resolves when one joins). */
+  readonly slot: number | undefined
+  leftStick: InputSource<"vec2">
+  rightStick: InputSource<"vec2">
+  /** The dpad as a digital vec2 (each component -1, 0 or 1). */
+  dpad: InputSource<"vec2">
+  /** Right trigger minus left trigger, -1..1. */
+  triggers: InputSource<"axis">
+  /** Right shoulder minus left shoulder, -1, 0 or 1. */
+  shoulders: InputSource<"axis">
+  /** A raw axis by SDL name ("leftX", "rightY", "leftTrigger", ...). */
+  axis(name: string): InputSource<"axis">
+  /** A button by SDL positional name ("south", "start", "leftShoulder", ...). */
+  button(name: string): InputSource<"button">
+}
+
+let deadzone = (x: number, y: number): Vec2 => (Math.hypot(x, y) < STICK_DEADZONE ? [0, 0] : [x, y])
+
+/**
+ * The sources over `pads()` (the pads this device reads now, reactive),
+ * with `slot()` as the device's slot and `who` as the label prefix.
+ */
+export function createGamepadDevice(pads: () => GamepadState[], slot: () => number | undefined, who: string): GamepadDevice {
+  let sumAxis = (read: (pad: GamepadState) => number) => (): number => {
+    let sum = 0
+    for (let pad of pads()) sum += read(pad)
+    return sum
+  }
+  let sumVec2 = (read: (pad: GamepadState) => Vec2) => (): Vec2 => {
+    let x = 0
+    let y = 0
+    for (let pad of pads()) {
+      let v = read(pad)
+      x += v[0]
+      y += v[1]
+    }
+    return [x, y]
+  }
+  let anyButton = (name: string) => (): boolean => pads().some(pad => pad.buttons.includes(name))
+  let pressed = (pad: GamepadState, name: string) => (pad.buttons.includes(name) ? 1 : 0)
+  let stick = (side: "left" | "right"): InputSource<"vec2"> => ({
+    kind: "vec2",
+    label: `${who} ${side} stick`,
+    rate: sumVec2(pad => deadzone(pad.axes[`${side}X`] ?? 0, pad.axes[`${side}Y`] ?? 0)),
+  })
+  return {
+    get slot() {
+      return slot()
+    },
+    leftStick: stick("left"),
+    rightStick: stick("right"),
+    dpad: {
+      kind: "vec2",
+      label: `${who} dpad`,
+      rate: sumVec2(pad => [pressed(pad, "dpadRight") - pressed(pad, "dpadLeft"), pressed(pad, "dpadDown") - pressed(pad, "dpadUp")]),
+    },
+    triggers: {
+      kind: "axis",
+      label: `${who} triggers`,
+      rate: sumAxis(pad => (pad.axes.rightTrigger ?? 0) - (pad.axes.leftTrigger ?? 0)),
+    },
+    shoulders: {
+      kind: "axis",
+      label: `${who} shoulders`,
+      rate: sumAxis(pad => pressed(pad, "rightShoulder") - pressed(pad, "leftShoulder")),
+    },
+    axis(name) {
+      if (typeof name !== "string" || name.length === 0) throw new Error(`gamepad.axis: expected an axis name, got ${String(name)}`)
+      return { kind: "axis", label: `${who} ${name}`, rate: sumAxis(pad => pad.axes[name] ?? 0) }
+    },
+    button(name) {
+      if (typeof name !== "string" || name.length === 0) throw new Error(`gamepad.button: expected a button name, got ${String(name)}`)
+      return { kind: "button", label: `${who} ${name}`, rate: anyButton(name) }
+    },
+  }
+}
+
+/** One slot, or every connected pad when `slot` is undefined. */
+export function createGamepadSlot(read: PadsAccessor, slot: number | undefined): GamepadDevice {
+  if (slot !== undefined && !(Number.isInteger(slot) && slot >= 0)) throw new Error(`gamepad: slot must be a non-negative integer, got ${String(slot)}`)
+  let pads = (): GamepadState[] => {
+    let all = read()
+    if (slot === undefined) return all.filter((p): p is GamepadState => p !== null)
+    let pad = all[slot]
+    return pad ? [pad] : []
+  }
+  return createGamepadDevice(pads, () => slot, slot === undefined ? "gamepad" : `gamepad ${slot}`)
+}
+
+// Slots held by joining devices, shared so a pad joins once.
+let claimed = new Set<number>()
+
+/** A device that claims the next unclaimed pad to press any button. */
+export function createGamepadJoin(read: PadsAccessor): GamepadDevice {
+  // ownedWrite: the claim lands inside an effect, the release in a cleanup.
+  let [slot, setSlot] = createSignal<number | undefined>(undefined, { ownedWrite: true })
+  let mine: number | undefined
+  // A root of its own: the watch outlives the render scope that created
+  // the device only when there is none to tie it to.
+  let dispose = createRoot(dispose => {
+    createEffect(
+      () => read(),
+      pads => {
+        if (mine !== undefined) return
+        for (let i = 0; i < pads.length; i++) {
+          let pad = pads[i]
+          if (!pad || claimed.has(i) || pad.buttons.length === 0) continue
+          mine = i
+          claimed.add(i)
+          setSlot(i)
+          return
+        }
+      },
+    )
+    return dispose
+  })
+  if (getOwner()) {
+    onCleanup(() => {
+      dispose()
+      if (mine !== undefined) claimed.delete(mine)
+    })
+  }
+  let pads = (): GamepadState[] => {
+    let s = slot()
+    if (s === undefined) return []
+    let pad = read()[s]
+    return pad ? [pad] : []
+  }
+  return createGamepadDevice(pads, slot, "gamepad (joined)")
+}

package/src/input-gamepad.ts

@@ -0,0 +1,24 @@
+// The gamepad device over core's gamepads() snapshot: `gamepad(slot)`
+// reads one pad (slots are stable per connection, so slot 0 is player
+// one for the session); `gamepad()` sums every connected pad, the right
+// default for a single-player app that does not care which pad is picked
+// up; `gamepad.next()` claims the next pad that presses any button, for
+// split screen that seats players in pick-up order. The sources and the
+// join logic live in input-gamepad-device.ts, runtime-free.
+
+import { gamepads } from "./gamepad"
+import { createGamepadJoin, createGamepadSlot } from "./input-gamepad-device"
+import type { GamepadDevice } from "./input-gamepad-device"
+
+export type { GamepadDevice } from "./input-gamepad-device"
+
+export function gamepad(slot?: number): GamepadDevice {
+  return createGamepadSlot(gamepads, slot)
+}
+
+/**
+ * A device with no pad until one no other joining device holds presses
+ * any button, then that pad for good (`slot` resolves, reactively). The
+ * claim is released when the creating scope is disposed.
+ */
+gamepad.next = (): GamepadDevice => createGamepadJoin(gamepads)

package/src/input-keyboard.ts

@@ -0,0 +1,156 @@
+// The keyboard as input sources: a key as a button, a key pair as an
+// axis, four keys as a vec2 (the WASD composite), each holding its own
+// pressed state from the key events an input map forwards to it
+// (InputMap.handlers, spread on the window or the focused leaf). Keys
+// match on the physical code ("KeyW", layout-independent) or the logical
+// key ("w", what a synthetic event or an odd layout reports), and a
+// letter code matches its letter either way, so "KeyW" and "w" both take
+// a shifted "W".
+//
+// A spec may name modifiers ahead of the key ("Shift+Tab", "Ctrl+KeyS";
+// Shift, Ctrl, Alt, Meta): the down must carry them, while a bare spec
+// ignores them (a shifted W still walks). Within one source the most
+// specific matching spec wins a down, so `axis("Shift+Tab", "Tab")` reads
+// -1, not 0, on Shift+Tab; and an up releases on the key alone, so a
+// modifier let go first cannot leave the key stuck.
+//
+// Held state is a count behind a signal, so a source's rate is reactive
+// (a held key wakes a control's frame loop) and a blur - the up that never
+// arrives once focus has left - clears it. Composites clamp nothing: the
+// map's combination does (W and D together read [1, -1] before the
+// vec2 clamp to unit length, so diagonals walk at the same speed).
+//
+// Values use the screen convention (x right, y down): W reads [0, -1], as
+// a stick pushed up does.
+
+import { createSignal } from "@solidjs/signals"
+import type { KeyEvent } from "./types"
+import type { InputSource } from "./input-map"
+import type { Vec2 } from "./input-axes"
+
+type Modifier = "shiftKey" | "ctrlKey" | "altKey" | "metaKey"
+
+const MODIFIERS: Record<string, Modifier> = { Shift: "shiftKey", Ctrl: "ctrlKey", Control: "ctrlKey", Alt: "altKey", Meta: "metaKey" }
+
+// A parsed spec: the text as given (the held-state key and the label),
+// the key it names, and the modifiers the down must carry.
+type Spec = { text: string; key: string; mods: Modifier[] }
+
+function parse(what: string, text: unknown): Spec {
+  if (typeof text !== "string" || text.length === 0) throw new Error(`keyboard.${what}: expected a key code or key name, got ${String(text)}`)
+  let parts = text.split("+")
+  let key = parts.pop()!
+  if (key.length === 0) throw new Error(`keyboard.${what}: "${text}" names no key`)
+  let mods: Modifier[] = []
+  for (let part of parts) {
+    let mod = MODIFIERS[part]
+    if (!mod) throw new Error(`keyboard.${what}: unknown modifier "${part}" in "${text}" (Shift, Ctrl, Alt or Meta)`)
+    if (!mods.includes(mod)) mods.push(mod)
+  }
+  return { text, key, mods }
+}
+
+// A key matches its physical code or its logical key; a letter code
+// ("KeyW") also matches the logical letter ("w", "W") and "Space" the
+// logical " ", so a synthetic event without a code (an agent's
+// send_input, an odd layout) still walks.
+let matches = (event: KeyEvent, key: string): boolean => {
+  if (event.code === key || event.key === key) return true
+  if (key === "Space" && event.key === " ") return true
+  if (event.key.length !== 1) return false
+  if (key.length === 1) return event.key.toLowerCase() === key.toLowerCase()
+  return key.length === 4 && key.startsWith("Key") && event.key.toLowerCase() === key[3]!.toLowerCase()
+}
+
+// A set of specs with a reactive "how many are held" count.
+function held(specs: Spec[]) {
+  let down = new Set<string>()
+  // ownedWrite: a map forwards key events from wherever its handlers sit.
+  let [count, setCount] = createSignal(0, { ownedWrite: true })
+  return {
+    count,
+    key(event: KeyEvent, isDown: boolean) {
+      // Every spec on this key is released first: a down settles the key
+      // on its most specific matches (a repeat under a newly held Shift
+      // moves "Tab" to "Shift+Tab" and back), an up frees them all.
+      let onKey = specs.filter(s => matches(event, s.key))
+      for (let s of onKey) down.delete(s.text)
+      if (isDown) {
+        let hits = onKey.filter(s => s.mods.every(m => event[m]))
+        let most = hits.reduce((n, s) => Math.max(n, s.mods.length), 0)
+        for (let s of hits) if (s.mods.length === most) down.add(s.text)
+      }
+      setCount(down.size)
+    },
+    blur() {
+      down.clear()
+      setCount(0)
+    },
+    has(text: string) {
+      return down.has(text)
+    },
+  }
+}
+
+/** One key as a button source (pressed while held). */
+function key(spec: string): InputSource<"button"> {
+  let state = held([parse("key", spec)])
+  return {
+    kind: "button",
+    label: `keyboard ${spec}`,
+    rate: () => state.count() > 0,
+    key: state.key,
+    blur: state.blur,
+  }
+}
+
+/** Two keys as an axis: `neg` reads -1, `pos` reads 1, both 0. */
+function axis(neg: string, pos: string): InputSource<"axis"> {
+  let state = held([parse("axis", neg), parse("axis", pos)])
+  return {
+    kind: "axis",
+    label: `keyboard ${neg}/${pos}`,
+    rate: () => {
+      state.count()
+      return (state.has(pos) ? 1 : 0) - (state.has(neg) ? 1 : 0)
+    },
+    key: state.key,
+    blur: state.blur,
+  }
+}
+
+export type KeyboardVec2Keys = { up: string; down: string; left: string; right: string }
+
+/** Four keys as a vec2 in the screen convention: up reads [0, -1], right
+ * reads [1, 0]; opposite keys cancel. */
+function vec2(keys: KeyboardVec2Keys): InputSource<"vec2"> {
+  let state = held((["up", "down", "left", "right"] as const).map(side => parse(`vec2 ${side}`, keys[side])))
+  return {
+    kind: "vec2",
+    label: `keyboard ${keys.up}/${keys.left}/${keys.down}/${keys.right}`,
+    rate: (): Vec2 => {
+      state.count()
+      return [(state.has(keys.right) ? 1 : 0) - (state.has(keys.left) ? 1 : 0), (state.has(keys.down) ? 1 : 0) - (state.has(keys.up) ? 1 : 0)]
+    },
+    key: state.key,
+    blur: state.blur,
+  }
+}
+
+/**
+ * The keyboard device: `keyboard.key("Space")`, `keyboard.axis("KeyQ",
+ * "KeyE")`, `keyboard.vec2({ up, down, left, right })`, and the two
+ * composites every game binds, `keyboard.wasd` and `keyboard.arrows`.
+ * A spec may carry modifiers ("Shift+Tab", "Ctrl+KeyS"). Each call makes
+ * an independent source with its own held state; the composites are
+ * shared singletons.
+ */
+export let keyboard = {
+  key,
+  axis,
+  vec2,
+  wasd: vec2({ up: "KeyW", down: "KeyS", left: "KeyA", right: "KeyD" }),
+  arrows: vec2({ up: "ArrowUp", down: "ArrowDown", left: "ArrowLeft", right: "ArrowRight" }),
+}
+
+export type KeyboardDevice = typeof keyboard