@benev/tact 0.1.0-1 → 0.1.0-3

package/README.md

@@ -1,50 +1,126 @@
 
-# @benev/tact
-> user input keybindings and gamepad support for web games
+# 🎮 @benev/tact
+> *web game input library, from keypress to couch co-op*
 
 ```ts
 npm install @benev/tact
 ```
 
-- 🛰️ **devices** are for sampling user inputs
-- 🔗 **bindings** describe how samples influence actions
-- 📡 **station** runs device samples through bindings, updating actions
-- 🔌 **switchboard** assigns devices to stations (multi-gamepad couch co-op!)
-- 🔘 **nubs** is mobile ui virtual gamepad stuff
+- 🛹 **deck** full setup with localstorate persistence
+- 🎮 **controllers** produce user input samples
+- 🧩 **bindings** describe how actions interpret samples
+- 🔌 **port** updates actions by interpreting samples
+- 🛞 **hub** plugs controllers into ports (multi-gamepad couch co-op!)
+- 📱 **nubs** is mobile ui virtual gamepad stuff
+
+
+
+<br/><br/>
+
+## 🍋 tact deck
+> *the full setup*
+
+the deck is the heart of tact, tying all the pieces together and putting a bow in it for you.
+
+### 🛹 deck setup
+- **import stuff from tact**
+    ```ts
+    import * as tact from "@benev/tact"
+    ```
+- **setup your deck, and your game's bindings**
+    ```ts
+    const deck = await tact.Deck.load({
+
+      // how many players ports are possible? 1 is fine..
+      portCount: 4,
+
+      // where to store the user-customized bindings
+      kv: tact.localStorageKv(),
+
+      // default archetypal bindings for your game
+      bindings: {
+        ...tact.hubBindings(),
+        walking: {
+          forward: "KeyW",
+          jump: "Space",
+        },
+        gunning: {
+          shoot: ["or", "pointer.button.left", "gamepad.trigger.right"],
+        },
+      },
+    })
+    ```
+
+### 🛹 plug controllers into the hub
+- **plug a keyboard/mouse player into the hub**
+    ```ts
+    deck.hub.plug(
+      new tact.GroupController(
+        new tact.KeyboardController(),
+        new tact.PointerController(),
+        new tact.VirtualGamepadController(),
+      )
+    )
+    ```
+- **auto connect/disconnect gamepads as they come and go**
+    ```ts
+    tact.autoGamepads(deck.hub.plug)
+    ```
+
+### 🛹 do your gameplay
+- **start with what modes you want enabled in your game**
+    ```ts
+    for (const port of deck.ports)
+      port.modes.adds("walking", "gunning")
+    ```
+- **poll the deck, interrogate actions for your gameplay**
+    ```ts
+    onEachTickInYourGame(() => {
+
+      // do your polling
+      const [p1, p2, p3, p4] = deck.hub.poll()
+
+      // check if the first player is pressing "forward" action
+      p1.walking.forward.pressed // true
+
+      // check how hard the second player is pulling that trigger
+      p2.gunning.shoot.value // 0.123
+    })
+    ```
+
+
 
 <br/><br/>
 
-## 🍋 tact devices
-> produces user input "samples"
+## 🍋 tact controllers
+> *sources of user input "samples"*
 
-### 🥝 polling is good, actually
+### 🎮 polling is good, actually
 - tact operates on the basis of *polling*
 - *"but polling is bad"* says you — but no — you're wrong — polling is unironically *based,* and you *should* do it
 - in a game, we want to be processing our inputs *every frame*
 - the gift of polling is total control over *when* inputs are processed
 - i will elaborate no further 🗿
 
-### 🥝 basically how a device works
-- make a keyboard device
+### 🎮 basically how a controller works
+- make a controller
     ```ts
-    import {KeyboardDevice} from "@benev/tact"
-
-    const device = new KeyboardDevice(window)
+    const keyboard = new tact.KeyboardController()
     ```
 - take samples each frame
     ```ts
-    const samples = device.takeSamples()
+    const samples = keyboard.takeSamples()
       // [
       //   ["KeyA", 1],
       //   ["Space", 0]
       // ]
     ```
-- dispose the device when you're done with it
+- some controllers have disposers to call when you're done with them
     ```ts
-    device.dispose()
+    keyboard.dispose()
     ```
 
-### 🥝 samples explained
+### 🎮 samples explained
 - a sample is a raw input of type `[code: string, value: number]`
 - a sample has a `code` string
   - it's either a [standard keycode](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values), like `KeyA`
@@ -57,37 +133,21 @@ npm install @benev/tact
   - sometimes we use numbers greater then `1`, like for dots of pointer movement like in `pointer.move.up`
   - don't worry about sensitivity, deadzones, values like `0.00001` — actions will account for all that using bindings later on
 
-### 🥝 sample code modprefixes
-- here at tact, we have this nifty `modprefix` convention
-- consider a keycode like `KeyA`
-    - `ctrl-KeyA` means the "ctrl" modifier was held
-    - `alt-KeyA` means the "alt" modifier was held
-    - `meta-KeyA` means the "meta" modifier was held (command or windows keys)
-    - `shift-KeyA` means the "shift" modifier was held
-    - `ctrl-alt-meta-shift-KeyA` they can stack, but always in this order (the word `cams` helps remind me the valid order)
-    - `x-KeyA` means *no* modifier was held (exclusive)
-    - `KeyA` doesn't care if any modifiers were held or not
-
-### 🥝 sample code reference
-- **KeyboardDevice**
+### 🎮 sample code reference
+- **KeyboardController**
     - any [standard keycode](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values)
         - `KeyA`
         - `Space`
         - `Digit2`
         - etc
-    - plus the modprefixes
-        - `ctrl-KeyA`
-        - `alt-shift-Space`
-        - `x-Digit2`
-        - etc
-- **PointerDevice**
-    - mouse buttons (plus modprefixes)
+- **PointerController**
+    - mouse buttons
         - `pointer.button.left`
         - `pointer.button.right`
         - `pointer.button.middle`
         - `pointer.button.4`
         - `pointer.button.5`
-    - mouse wheel (plus modprefixes)
+    - mouse wheel
         - `pointer.wheel.up`
         - `pointer.wheel.down`
         - `pointer.wheel.left`
@@ -97,7 +157,7 @@ npm install @benev/tact
         - `pointer.move.down`
         - `pointer.move.left`
         - `pointer.move.right`
-- **GamepadDevice**
+- **GamepadController**
     - gamepad buttons
         - `gamepad.a`
         - `gamepad.b`
@@ -126,58 +186,151 @@ npm install @benev/tact
         - `gamepad.stick.right.left`
         - `gamepad.stick.right.right`
 
+
+
 <br/><br/>
 
 ## 🍋 tact bindings
-> keybindings! they describe how actions interpret samples
+> *keybindings! they describe how actions interpret samples*
 
-### 🥝 bindings example
-- let's start with a small example:
+### 🧩 bindings example
+- **let's start with a small example:**
     ```ts
-    import {Bindings} from "@benev/tact"
-
-    const bindings = asBindings({
+    const bindings = tact.asBindings({
       walking: {
-        forward: [{lenses: [{code: "KeyW"}]}],
-        jump: [{lenses: [{code: "Space"}]}],
+        forward: "KeyW",
+        jump: "Space",
       },
       gunning: {
-        shoot: [{lenses: [{code: "pointer.button.left"}]}],
+        shoot: ["or", "pointer.button.left", "gamepad.trigger.right"],
       },
     })
     ```
     - `walking` and `gunning` are **modes**
     - `forward`, `jump`, and `shoot` are **actions**
-    - data like `[{lenses: [{code: "KeyW"}]}]` are the rules for triggering the action.
-      - 🚨 TODO okay these rules are complex and i'm gonna rework them soon
-    - whole modes can be enabled or disabled
+    - note that whole modes can be enabled or disabled during gameplay
+
+### 🧩 bindings are a lispy domain-specific-language
+- **you can do complex stuff**
+    ```ts
+    ["or",
+      "KeyQ",
+      ["and",
+        "KeyA",
+        "KeyD",
+        ["not", "KeyS"],
+      ],
+    ]
+    ```
+    - press Q, or
+    - press A + D, while not pressing S
+- **you can get really weird**
+    ```ts
+    ["cond",
+      ["code", "gamepad.trigger.right", {deadzone: 0.5, timing: ["tap"]}],
+      ["and", "gamepad.bumper.left", ["not", "gamepad.trigger.left"]],
+    ]
+    ```
+    - hold LB and tap RT halfway while not holding LT
+
+### 🧩 bindings atom reference
+- **string** — strings are interpreted as "code" atoms with default settings
+- **"code"** — allows you to customize the settings
+    ```ts
+    ["code", "KeyA", {
+		  scale: 1,
+		  invert: false,
+		  deadzone: 0.2,
+		  timing: ["direct"],
+    }]
+    ```
+    - defaults shown
+    - `scale` is sensitivity, the value gets multiplied by this
+    - `invert` will invert a value by subtracting it from 1
+    - `deadzone` ignores values below the threshold (and remaps to preserve the range)
+    - `timing` lets you specify special timing considerations
+      - `["direct"]` ignores timing considerations
+      - `["tap", 250]` only fires for taps under 250ms
+      - `["hold", 250]` only fires for holds over 250ms
+- **"or"** — resolves to the maximum value
+    ```ts
+    ["or", "KeyA", "KeyB", "KeyC"]
+    ```
+- **"and"** — resolves to the minimum value
+    ```ts
+    ["and", "KeyA", "KeyB", "KeyC"]
+    ```
+- **"not"** — resolves to the opposite effect
+    ```ts
+    ["not", "KeyA"]
+    ```
+- **"cond"** — conditional situation (example for modifiers shown)
+    ```ts
+    ["cond", "KeyA", ["and",
+      ["or", "ControlLeft", "ControlRight"],
+      ["not", ["or", "AltLeft", "AltRight"]],
+      ["not", ["or", "MetaLeft", "MetaRight"]],
+      ["not", ["or", "ShiftLeft", "ShiftRight"]],
+    ]]
+    ```
+    - KeyA is the value that gets used
+    - but only if the following condition passes
+- **"mods"** — macro for modifiers
+    ```ts
+    ["mods", "KeyA", {ctrl: true}]
+    ```
+    - equivalent to the "cond" example above
+    - `ctrl`, `alt`, `meta`, `shift` are available
+
+
 
 <br/><br/>
 
-## 🍋 tact station
-> polling gives you actions
+## 🍋 tact port
+> *polling gives you "actions"*
 
-### 🥝 creating a station
-- create a station
-    ```ts
-    import {Station} from "@benev/tact"
+a port represents a single playable port, and you poll it each frame to resolve actions for you to read.
 
-    const station = new Station(bindings)
-      .addModes("walking")
-      .addDevices(
-        new KeyboardDevice(window),
-        new PointerDevice(window),
-      )
+### 🔌 port basics
+- **make a port**
+    ```ts
+    const port = new tact.Port(bindings)
+    ```
+- **attach some controllers to the port**
+    ```ts
+    port.controllers
+      .add(new tact.KeyboardController())
+      .add(new tact.PointerController())
+      .add(new tact.VirtualGamepadController())
+    ```
+    - you can add/delete controllers from the set any time
+- **don't forget to enable modes!**
+    ```ts
+    port.modes.add("walking")
+    ```
+    - if you don't enable any modes, no actions will happen
+    - actions only happen for enabled modes
+    - you can toggle modes on and off by adding/deleting them from the modes set
+- **you can update the bindings any time**
+    ```ts
+    port.bindings = freshBindings
+    ```
+- **wire up gamepad auto connect/disconnect**
+    ```ts
+    tact.autoGamepads(controller => {
+      port.controllers.add(controller)
+      return () => port.controllers.delete(controller)
+    })
     ```
 
-### 🥝 how to use actions
-- poll the station every frame
+### 🔌 interrogating actions
+- **poll the port every frame**
     ```ts
-    station.poll(Date.now())
+    const actions = port.poll()
     ```
-- now you use the `actions`
+- **now you can inspect the `actions`**
     ```ts
-    station.actions.walking.forward.value // 1
+    actions.walking.forward.value // 1
     ```
     - `walking` is a `mode`
     - `forward` is an `action`
@@ -187,113 +340,85 @@ npm install @benev/tact
     - `action.pressed` — true if the value > 0
     - `action.down` — true for one frame when the key goes from up to down
     - `action.up` — true for one frame when the key goes from down to up
-    - `action.on(action => {})` — react to changes ([`@e280/stz`](https://github.com/e280/stz) sub fn)
-    - `action.onDown(action => {})` — react only on down ([`@e280/stz`](https://github.com/e280/stz) sub fn)
 
-### 🥝 more about station
-- you can enable/disable modes like this (it's a set)
-    ```ts
-    station.modes.add("gunning")
-      // now the "gunning" actions can fire
 
-    station.modes.delete("walking")
-      // now the "walking" actions *cannot* fire
-    ```
-- you can add/remove devices from the set any time
-    ```ts
-    station.devices.add(new GamepadDevice(pad))
-    ```
-- you can update the bindings at runtime
-    ```ts
-    station.bindings = bindings2
-    ```
 
 <br/><br/>
 
-## 🍋 tact switchboard
-> multiple gamepads! couch co-op is so back
+## 🍋 tact hub
+> *multiple gamepads! couch co-op is so back*
 
-### 🥝 feel the vibes
-- you know the way old timey game consoles had controller ports? and then players could plug their controller into whatever port they wanted? and then you could unplug and replug your controller into a different port? yeah — that's what switchboard does.
-- with the switchboard, think of the "stations" as controller ports, and the "devices" as player controllers.
-- import stuff:
-    ```ts
-    import {
-      Switchboard, Station,
-      GroupDevice, GamepadDevice, KeyboardDevice, PointerDevice,
-    } from "@benev/tact"
-    ```
+you know the way old-timey game consoles had four controller ports on the front?
+
+the hub embraces that analogy, helping you coordinate the plugging and unplugging of virtual controllers into its virtual ports.
 
-### 🥝 create a switchboard with stations
-- **adopt standard switchboard bindings**
+### 🛞 create a hub with ports
+- **adopt standard hub bindings**
     ```ts
-    // transform your game's bindings into switchboard-friendly bindings
-    const sBindings = Switchboard.bindings(bindings)
+    const hubBindings = {
+      ...yourBindings,
+
+      // mixin standard hub bindings
+      ...tact.hubBindings(),
+    }
     ```
-    - this allows players to shimmy what station their controller controls
-    - gamepad: hold middle button and press bumpers
+    - hub bindings let players shimmy what port their controller is plugged into
+    - gamepad: hold gamma (middle button) and press bumpers
     - keyboard: left bracket or right bracket
-- **make switchboard with stations at the ready**
+- **make hub with multiple ports at the ready**
     ```ts
-    const switchboard = new Switchboard([
-      new Station(sBindings),
-      new Station(sBindings),
-      new Station(sBindings),
-      new Station(sBindings),
+    const hub = new tact.Hub([
+      new tact.Port(hubBindings),
+      new tact.Port(hubBindings),
+      new tact.Port(hubBindings),
+      new tact.Port(hubBindings),
     ])
     ```
-    - yes that's right — each player can have their own bindings 🤯
+    - yes that's right — each player port gets its own bindings 🤯
 
-### 🥝 connect player's devices to the switchboard
-- **let's connect the keyboard/mouse player**
+### 🛞 plug in some controllers
+- **let's plug in the keyboard/mouse player**
     ```ts
-    switchboard.connect(
-      new GroupDevice(
-        new KeyboardDevice(window),
-        new PointerDevice(window),
+    hub.plug(
+      new tact.GroupController(
+        new tact.KeyboardController(),
+        new tact.PointerController(),
+        new tact.VirtualGamepadController(),
       )
     )
     ```
-    - the switchboard assumes a single device represents a single player, thus we can use a `GroupDevice` to combine multple devices into one
+    - the hub requires a single controller to represent a player, thus we can use a `GroupController` to combine multple controllers into one
 - **wire up gamepad auto connect/disconnect**
     ```ts
-    GamepadDevice.on(device => switchboard.connect(device))
+    tact.autoGamepads(hub.plug)
     ```
 
-### 🥝 you're ready!
+### 🛞 it's gaming time
 - **do your polling, interrogate those actions**
     ```ts
-    const [p1, p2, p3, p4] = switchboard.stations
-
-    // poll them all
-    switchboard.poll(Date.now())
+    const [p1, p2, p3, p4] = hub.poll()
 
-    p1.actions.walking.jump.value // 1
-    p2.actions.walking.jump.value // 0
+    p1.walking.jump.value // 1
+    p2.walking.jump.value // 0
     ```
 
-### 🥝 the more you know, about the switchboard
-- `switchboard.stations` — direct access to the array of stations
-- `switchboard.isActive(p1)` — check if there's a switchboard-connected-device assigned to this station
-- `switchboard.shimmy(device, 1)` — shimmy a device forward one station
-- `switchboard.shimmy(device, -1)` — shimmy a device backward one station
-- `switchboard.connect(device, p4)` — connect-or-reassign a device to a specific station
-- `switchboard.connect(device)` — connect a device to the next unassigned station (or the last station)
-- `switchboard.disconnect(device)` — unassign a device and forget about it
+
 
 <br/><br/>
 
 ## 🍋 tact nubs
-> mobile ui like virtual thumbsticks and buttons
+> *mobile ui like virtual thumbsticks and buttons*
 
-### 🥝 nub stick
+### 📱 nub stick
 > TODO lol need to write docs
 
-### 🥝 nub virtual gamepad
+### 📱 nub virtual gamepad
 > TODO lol need to write docs
 
+
+
 <br/><br/>
 
 ## 🍋 tact is by https://benevolent.games/
-> building the future of web games
+> *building the future of web games*
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@benev/tact",
-	"version": "0.1.0-1",
+	"version": "0.1.0-3",
 	"description": "keybindings and gamepad support for web games",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -8,7 +8,8 @@
 	"main": "./x/index.js",
 	"sideEffects": false,
 	"exports": {
-		".": "./x/index.js"
+		".": "./x/index.js",
+		"./core": "./x/core/index.js"
 	},
 	"files": [
 		"x",
@@ -32,9 +33,10 @@
 	},
 	"dependencies": {
 		"@benev/math": "^0.2.0-1",
+		"@e280/kv": "^0.1.0",
 		"@e280/sly": "^0.1.1",
 		"@e280/strata": "^0.1.0",
-		"@e280/stz": "^0.2.0-4"
+		"@e280/stz": "^0.2.0-5"
 	},
 	"devDependencies": {
 		"@e280/science": "^0.1.1",

package/s/{station/parts → core/bindings}/action.ts

@@ -1,21 +1,15 @@
 
-import {sub} from "@e280/stz"
-import {isPressed} from "../utils/is-pressed.js"
+import {isPressed} from "./parts/is-pressed.js"
 
 export class Action {
 	#value = 0
 	#previous = 0
 
-	static updateValue(action: Action, newValue: number) {
+	static update(action: Action, value: number) {
 		action.#previous = action.#value
-		action.#value = newValue
-		if (action.changed) action.on.pub(action)
-		if (action.down) action.onDown.pub(action)
+		action.#value = value
 	}
 
-	readonly on = sub<[Action]>()
-	readonly onDown = sub<[Action]>()
-
 	get value() { return this.#value }
 	get previous() { return this.#previous }
 	get changed() { return this.#value !== this.#previous }

package/s/core/bindings/parts/defaults.ts

@@ -0,0 +1,29 @@
+
+import {Code, CodeSettings, CodeState} from "../types.js"
+
+export const defaultHoldTime = 250
+
+export function defaultCodeState([,,settings]: Code): CodeState {
+	return {
+		lastValue: 0,
+		holdStart: 0,
+		settings: defaultifyCodeSettings(settings),
+	}
+}
+
+function defaultCodeSettings(): CodeSettings {
+	return {
+		scale: 1,
+		invert: false,
+		deadzone: 0.2,
+		timing: ["direct"],
+	}
+}
+
+function defaultifyCodeSettings(partial: Partial<CodeSettings> = {}): CodeSettings {
+	return {
+		...defaultCodeSettings(),
+		...partial,
+	}
+}
+