@benev/tact 0.1.0-1 → 0.1.0-2

package/README.md

@@ -1,50 +1,128 @@
 
 # @benev/tact
-> user input keybindings and gamepad support for web games
+> 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** user input coordinator with bindings 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 devices
-> produces user input "samples"
+## 🍋 tact deck
+> *user input coordinator with bindings persistence*
+
+the deck is the heart of tact.. it ties all the important parts together..
+
+### 🛹 deck setup
+- **import stuff from tact**
+    ```ts
+    import * as tact from "@benev/tact"
+    ```
+- **setup your deck**
+    ```ts
+    const deck = new tact.Deck({
+      ports: 4,
+      kv: tact.Deck.localStorageKv(),
+      defaultBindings: tact.Hub.bindings({
+        walking: {
+          forward: [
+            {lenses: [{code: "KeyW"}]},
+            {lenses: [{code: "gamepad.stick.left.up"}]},
+          ],
+          jump: [
+            {lenses: [{code: "Space"}]},
+            {lenses: [{code: "gamepad.a"}]},
+          ],
+        },
+        gunning: {
+          shoot: [
+            {lenses: [{code: "pointer.button.left"}]},
+            {lenses: [{code: "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.actions.walking.forward.pressed // true
+
+      // check how hard the second player is pulling that trigger
+      p2.actions.gunning.shoot.value // 0.123
+    })
+    ```
+
+
+
+<br/><br/>
 
-### 🥝 polling is good, actually
+## 🍋 tact controllers
+> *produces user input "samples"*
+
+### 🎮 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
+- dispose when you're done with it
     ```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,7 +135,7 @@ 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
+### 🎮 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
@@ -68,8 +146,8 @@ npm install @benev/tact
     - `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`
@@ -80,7 +158,7 @@ npm install @benev/tact
         - `alt-shift-Space`
         - `x-Digit2`
         - etc
-- **PointerDevice**
+- **PointerController**
     - mouse buttons (plus modprefixes)
         - `pointer.button.left`
         - `pointer.button.right`
@@ -97,7 +175,7 @@ npm install @benev/tact
         - `pointer.move.down`
         - `pointer.move.left`
         - `pointer.move.right`
-- **GamepadDevice**
+- **GamepadController**
     - gamepad buttons
         - `gamepad.a`
         - `gamepad.b`
@@ -126,17 +204,17 @@ 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
+### 🧩 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"}]}],
@@ -152,32 +230,46 @@ npm install @benev/tact
       - 🚨 TODO okay these rules are complex and i'm gonna rework them soon
     - whole modes can be enabled or disabled
 
+
+
 <br/><br/>
 
-## 🍋 tact station
-> polling gives you actions
+## 🍋 tact port
+> *polling gives you "actions"*
 
-### 🥝 creating a station
-- create a station
+### 🔌 port basics
+- **make a port**
     ```ts
-    import {Station} from "@benev/tact"
-
-    const station = new Station(bindings)
-      .addModes("walking")
-      .addDevices(
-        new KeyboardDevice(window),
-        new PointerDevice(window),
-      )
+    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
     ```
 
-### 🥝 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 +279,82 @@ 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?
 
-### 🥝 create a switchboard with stations
-- **adopt standard switchboard bindings**
+the hub embraces that analogy, helping you coordinate the plugging and unplugging of virtual controllers into its virtual ports.
+
+### 🛞 create a hub with ports
+- **adopt standard hub bindings**
     ```ts
-    // transform your game's bindings into switchboard-friendly bindings
-    const sBindings = Switchboard.bindings(bindings)
+    // transform your game's bindings into hub-friendly bindings
+    const hubBindings = tact.Hub.bindings(bindings)
     ```
-    - this allows players to shimmy what station their controller controls
-    - gamepad: hold middle button and press bumpers
+    - this augments your bindings with standard hub-specific bindings
+    - this lets players to 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-2",
 	"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",

package/s/{station → core/bindings}/types.ts

@@ -1,15 +1,4 @@
 
-import {Action} from "./parts/action.js"
-
-export type Actions<B extends Bindings> = {
-	[Mode in keyof B]: {
-		[K in keyof B[Mode]]: Action
-	}
-}
-
-export type Sample = [code: string, value: number]
-export type SampleMap = Map<string, number>
-
 export type Timing = (
 	| DirectTiming
 	| TapTiming
@@ -32,11 +21,6 @@ export type Lens = {
 	settings?: Partial<LensSettings>
 }
 
-export type LensState = {
-	lastValue: number
-	holdStart: number
-}
-
 export type Spoon = {
 	lenses: Lens[]
 	required?: Lens[]
@@ -59,14 +43,14 @@ export function asBindings<B extends Bindings>(bindings: B) {
 	return bindings
 }
 
-export const switchboardMode = "switchboard" as const
+export const hubMode = "hub" as const
 
-export type AsSwitchboardBindings<B extends Bindings> = {
-	[switchboardMode]: {
+export type AsHubBindings<B extends Bindings> = {
+	[hubMode]: {
 		shimmyNext: Spoon[],
 		shimmyPrevious: Spoon[],
 	}
 } & B
 
-export type SwitchboardBindings = AsSwitchboardBindings<Bindings>
+export type HubBindings = AsHubBindings<Bindings>
 

package/s/core/controllers/controller.ts

@@ -0,0 +1,7 @@
+
+import {Sample} from "./types.js"
+
+export abstract class Controller {
+	abstract takeSamples(): Sample[]
+}
+

package/s/core/controllers/infra/group.ts

@@ -0,0 +1,17 @@
+
+import {SetG} from "@e280/stz"
+import {Controller} from "../controller.js"
+
+export class GroupController extends Controller {
+	controllers = new SetG<Controller>()
+
+	constructor(...controllers: Controller[]) {
+		super()
+		this.controllers.adds(...controllers)
+	}
+
+	takeSamples() {
+		return [...this.controllers].flatMap(controller => controller.takeSamples())
+	}
+}
+

package/s/{station/devices → core/controllers}/infra/sampler.ts

@@ -1,9 +1,9 @@
 
 import {sub} from "@e280/stz"
-import {Device} from "./device.js"
-import {Sample, SampleMap} from "../../types.js"
+import {Controller} from "../controller.js"
+import {Sample, SampleMap} from "../types.js"
 
-export class SamplerDevice extends Device {
+export class SamplerController extends Controller {
 	on = sub<Sample>()
 	#map: SampleMap = new Map()
 

package/s/{station/devices → core/controllers/standard}/gamepad.ts

@@ -1,8 +1,8 @@
 
-import {tmax} from "../utils/tmax.js"
-import {SamplerDevice} from "./infra/sampler.js"
-import {splitAxis} from "../../utils/split-axis.js"
-import {gamepads, Pad} from "../../utils/gamepads.js"
+import {tmax} from "../../../utils/quick-math.js"
+import {splitAxis} from "../../../utils/split-axis.js"
+import {SamplerController} from "../infra/sampler.js"
+import {gamepads, Pad} from "../../../utils/gamepads.js"
 
 const gamepadButtonCodes = [
 	"gamepad.a",
@@ -24,8 +24,8 @@ const gamepadButtonCodes = [
 	"gamepad.gamma",
 ]
 
-export class GamepadDevice extends SamplerDevice {
-	static on(fn: (device: GamepadDevice) => () => void) {
+export class GamepadController extends SamplerController {
+	static on(fn: (controller: GamepadController) => () => void) {
 		return gamepads(pad => fn(new this(pad)))
 	}
 

package/s/core/controllers/standard/index.ts

@@ -0,0 +1,7 @@
+
+export * from "./gamepad.js"
+export * from "./keyboard.js"
+export * from "./pointer.js"
+export * from "./stick.js"
+export * from "./virtual-gamepad.js"
+

package/s/{station/devices → core/controllers/standard}/keyboard.ts

@@ -1,15 +1,15 @@
 
 import {coalesce, ev, sub} from "@e280/stz"
 import {Sample} from "../types.js"
-import {Device} from "./infra/device.js"
+import {Controller} from "../controller.js"
 import {modprefix} from "../utils/modprefix.js"
 
-export class KeyboardDevice extends Device {
+export class KeyboardController extends Controller {
 	on = sub<Sample>()
 	dispose: () => void
 	#held = new Set<string>()
 
-	constructor(target: EventTarget) {
+	constructor(target: EventTarget = window) {
 		super()
 
 		const down = (code: string) => {