@benev/tact 0.1.0-2 → 0.1.0-3

package/README.md

@@ -1,12 +1,12 @@
 
-# @benev/tact
-> web game input library, from keypress to couch co-op
+# 🎮 @benev/tact
+> *web game input library, from keypress to couch co-op*
 
 ```ts
 npm install @benev/tact
 ```
 
-- 🛹 **deck** user input coordinator with bindings persistence
+- 🛹 **deck** full setup with localstorate persistence
 - 🎮 **controllers** produce user input samples
 - 🧩 **bindings** describe how actions interpret samples
 - 🔌 **port** updates actions by interpreting samples
@@ -18,38 +18,36 @@ npm install @benev/tact
 <br/><br/>
 
 ## 🍋 tact deck
-> *user input coordinator with bindings persistence*
+> *the full setup*
 
-the deck is the heart of tact.. it ties all the important parts together..
+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**
+- **setup your deck, and your game's bindings**
     ```ts
-    const deck = new tact.Deck({
-      ports: 4,
-      kv: tact.Deck.localStorageKv(),
-      defaultBindings: tact.Hub.bindings({
+    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: [
-            {lenses: [{code: "KeyW"}]},
-            {lenses: [{code: "gamepad.stick.left.up"}]},
-          ],
-          jump: [
-            {lenses: [{code: "Space"}]},
-            {lenses: [{code: "gamepad.a"}]},
-          ],
+          forward: "KeyW",
+          jump: "Space",
         },
         gunning: {
-          shoot: [
-            {lenses: [{code: "pointer.button.left"}]},
-            {lenses: [{code: "gamepad.trigger.right"}]},
-          ],
+          shoot: ["or", "pointer.button.left", "gamepad.trigger.right"],
         },
-      }),
+      },
     })
     ```
 
@@ -83,10 +81,10 @@ the deck is the heart of tact.. it ties all the important parts together..
       const [p1, p2, p3, p4] = deck.hub.poll()
 
       // check if the first player is pressing "forward" action
-      p1.actions.walking.forward.pressed // true
+      p1.walking.forward.pressed // true
 
       // check how hard the second player is pulling that trigger
-      p2.actions.gunning.shoot.value // 0.123
+      p2.gunning.shoot.value // 0.123
     })
     ```
 
@@ -95,7 +93,7 @@ the deck is the heart of tact.. it ties all the important parts together..
 <br/><br/>
 
 ## 🍋 tact controllers
-> *produces user input "samples"*
+> *sources of user input "samples"*
 
 ### 🎮 polling is good, actually
 - tact operates on the basis of *polling*
@@ -117,7 +115,7 @@ the deck is the heart of tact.. it ties all the important parts together..
       //   ["Space", 0]
       // ]
     ```
-- dispose when you're done with it
+- some controllers have disposers to call when you're done with them
     ```ts
     keyboard.dispose()
     ```
@@ -135,17 +133,6 @@ the deck is the heart of tact.. it ties all the important parts together..
   - 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
 - **KeyboardController**
     - any [standard keycode](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values)
@@ -153,19 +140,14 @@ the deck is the heart of tact.. it ties all the important parts together..
         - `Space`
         - `Digit2`
         - etc
-    - plus the modprefixes
-        - `ctrl-KeyA`
-        - `alt-shift-Space`
-        - `x-Digit2`
-        - etc
 - **PointerController**
-    - mouse buttons (plus modprefixes)
+    - 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`
@@ -212,23 +194,93 @@ the deck is the heart of tact.. it ties all the important parts together..
 > *keybindings! they describe how actions interpret samples*
 
 ### 🧩 bindings example
-- let's start with a small example:
+- **let's start with a small example:**
     ```ts
     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
 
 
 
@@ -237,6 +289,8 @@ the deck is the heart of tact.. it ties all the important parts together..
 ## 🍋 tact port
 > *polling gives you "actions"*
 
+a port represents a single playable port, and you poll it each frame to resolve actions for you to read.
+
 ### 🔌 port basics
 - **make a port**
     ```ts
@@ -261,6 +315,13 @@ the deck is the heart of tact.. it ties all the important parts together..
     ```ts
     port.bindings = freshBindings
     ```
+- **wire up gamepad auto connect/disconnect**
+    ```ts
+    tact.autoGamepads(controller => {
+      port.controllers.add(controller)
+      return () => port.controllers.delete(controller)
+    })
+    ```
 
 ### 🔌 interrogating actions
 - **poll the port every frame**
@@ -294,11 +355,14 @@ the hub embraces that analogy, helping you coordinate the plugging and unpluggin
 ### 🛞 create a hub with ports
 - **adopt standard hub bindings**
     ```ts
-    // transform your game's bindings into hub-friendly bindings
-    const hubBindings = tact.Hub.bindings(bindings)
+    const hubBindings = {
+      ...yourBindings,
+
+      // mixin standard hub bindings
+      ...tact.hubBindings(),
+    }
     ```
-    - this augments your bindings with standard hub-specific bindings
-    - this lets players to shimmy what port their controller is plugged into
+    - 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 hub with multiple ports at the ready**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@benev/tact",
-	"version": "0.1.0-2",
+	"version": "0.1.0-3",
 	"description": "keybindings and gamepad support for web games",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -33,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/core/{port → bindings}/action.ts

@@ -1,5 +1,5 @@
 
-import {isPressed} from "./utils/is-pressed.js"
+import {isPressed} from "./parts/is-pressed.js"
 
 export class Action {
 	#value = 0

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,
+	}
+}
+

package/s/core/{port/resolution → bindings/parts}/lens-algo.ts

@@ -1,14 +1,13 @@
 
 import {pipe} from "@e280/stz"
 import {Scalar} from "@benev/math"
-
-import {LensState} from "./types.js"
+import {CodeState} from "../types.js"
+import {isPressed} from "./is-pressed.js"
 import {defaultHoldTime} from "./defaults.js"
-import {isPressed} from "../utils/is-pressed.js"
 
 export const lensAlgo = (
 		now: number,
-		state: LensState,
+		state: CodeState,
 		v: number,
 	) => pipe(v).line(
 
@@ -40,9 +39,9 @@ export const lensAlgo = (
 		const {settings} = state
 
 		const holdTime = (
-			settings.timing.style === "direct"
+			settings.timing[0] === "direct"
 				? undefined
-				: settings.timing.holdTime
+				: settings.timing[1]
 		) ?? defaultHoldTime
 
 		const isFreshlyPressed = !isPressed(state.lastValue) && isPressed(value)
@@ -54,7 +53,7 @@ export const lensAlgo = (
 
 		state.lastValue = value
 
-		switch (settings.timing.style) {
+		switch (settings.timing[0]) {
 			case "direct":
 				return value
 

package/s/core/bindings/resolver.ts

@@ -0,0 +1,96 @@
+
+import {MapG, pub, obMap} from "@e280/stz"
+import {Action} from "./action.js"
+import {lensAlgo} from "./parts/lens-algo.js"
+import {SampleMap} from "../controllers/types.js"
+import {tmax, tmin} from "../../utils/quick-math.js"
+import {defaultCodeState} from "./parts/defaults.js"
+import {Actions, Atom, Bindings, CodeSettings, CodeState} from "./types.js"
+
+export class Resolver<B extends Bindings> {
+	#actions: Actions<B>
+
+	#now = 0
+	#samples: SampleMap = new Map()
+	#codeStates = new MapG<number, CodeState>()
+	#update = pub()
+
+	constructor(public readonly bindings: B, modes: Set<keyof B>) {
+		this.#actions = obMap(bindings, (bracket, mode) => obMap(bracket, atom => {
+			const action = new Action()
+			this.#update.subscribe(() => {
+				const value = modes.has(mode)
+					? this.#resolveAtom()(atom)
+					: 0
+				Action.update(action, value)
+			})
+			return action
+		})) as Actions<B>
+	}
+
+	poll(now: number, samples: SampleMap) {
+		this.#now = now
+		this.#samples = samples
+		this.#update()
+		return this.#actions
+	}
+
+	#resolveCode(count: number, code: string, settings?: Partial<CodeSettings>) {
+		const state = this.#codeStates.guarantee(
+			count,
+			() => defaultCodeState(["code", code, settings]),
+		)
+		const value = this.#samples.get(code) ?? 0
+		return lensAlgo(this.#now, state, value)
+	}
+
+	#resolveAtom = (context: {count: number} = {count: 0}) => (atom: Atom): number => {
+		const resolveAtom = this.#resolveAtom(context)
+		if (typeof atom === "string") {
+			return this.#resolveCode(context.count++, atom)
+		}
+		else switch (atom[0]) {
+			case "code": {
+				const [, code, settings] = atom
+				return this.#resolveCode(context.count++, code, settings)
+			}
+			case "and": {
+				const [,...atoms] = atom
+				const values = atoms.map(resolveAtom)
+				return tmin(values)
+			}
+			case "or": {
+				const [,...atoms] = atom
+				const values = atoms.map(resolveAtom)
+				return tmax(values)
+			}
+			case "not": {
+				const [, subject] = atom
+				const value = resolveAtom(subject)
+				return (value > 0) ? 0 : 1
+			}
+			case "cond": {
+				const [, subject, guard] = atom
+				return (resolveAtom(guard) > 0)
+					? resolveAtom(subject)
+					: 0
+			}
+			case "mods": {
+				const [, subject, modifiers] = atom
+				const maybe = (x: boolean, ...codes: Atom[]): Atom => x
+					? ["or", ...codes]
+					: ["not", ["or", ...codes]]
+				const guard = resolveAtom(["cond", subject, ["and",
+					maybe(modifiers.ctrl ?? false, "ControlLeft", "ControlRight"),
+					maybe(modifiers.alt ?? false, "AltLeft", "AltRight"),
+					maybe(modifiers.meta ?? false, "MetaLeft", "MetaRight"),
+					maybe(modifiers.shift ?? false, "ShiftLeft", "ShiftRight"),
+				]])
+				return (guard > 0)
+					? resolveAtom(subject)
+					: 0
+			}
+		}
+	}
+}
+

package/s/core/bindings/types.ts

@@ -1,56 +1,57 @@
 
-export type Timing = (
-	| DirectTiming
-	| TapTiming
-	| HoldTiming
-)
-
-export type DirectTiming = {style: "direct"}
-export type TapTiming = {style: "tap", holdTime?: number}
-export type HoldTiming = {style: "hold", holdTime?: number}
+import {Action} from "./action.js"
 
-export type LensSettings = {
-	scale: number
-	invert: boolean
-	deadzone: number
-	timing: Timing
+export type Actions<B extends Bindings> = {
+	[Mode in keyof B]: {
+		[K in keyof B[Mode]]: Action
+	}
 }
 
-export type Lens = {
-	code: string
-	settings?: Partial<LensSettings>
-}
+export type Bindings = {[mode: string]: Bracket}
+export type Bracket = {[action: string]: Atom}
 
-export type Spoon = {
-	lenses: Lens[]
-	required?: Lens[]
-	forbidden?: Lens[]
+export type AsBindings<B extends Bindings> = B
+export function asBindings<B extends Bindings>(bindings: B) {
+	return bindings
 }
 
-export type Fork = Spoon[]
+export type Code = ["code", string, settings?: Partial<CodeSettings>]
+export type And = ["and", ...Atom[]]
+export type Or = ["or", ...Atom[]]
+export type Not = ["not", Atom]
+export type Cond = ["cond", Atom, guard: Atom]
+export type Mods = ["mods", Atom, modifiers: Partial<Modifiers>]
+
+export type Atom = string | (
+	| Code
+	| And
+	| Or
+	| Not
+	| Cond
+	| Mods
+)
 
-export type Bracket = {
-	[action: string]: Spoon[]
+export type CodeSettings = {
+	scale: number
+	invert: boolean
+	deadzone: number
+	timing: (
+		| ["direct"]
+		| ["tap", holdTime?: number]
+		| ["hold", holdTime?: number]
+	)
 }
 
-export type Bindings = {
-	[mode: string]: Bracket
+export type CodeState = {
+	settings: CodeSettings
+	lastValue: number
+	holdStart: number
 }
 
-export type AsBindings<B extends Bindings> = B
-
-export function asBindings<B extends Bindings>(bindings: B) {
-	return bindings
+export type Modifiers = {
+	ctrl: boolean
+	alt: boolean
+	shift: boolean
+	meta: boolean
 }
 
-export const hubMode = "hub" as const
-
-export type AsHubBindings<B extends Bindings> = {
-	[hubMode]: {
-		shimmyNext: Spoon[],
-		shimmyPrevious: Spoon[],
-	}
-} & B
-
-export type HubBindings = AsHubBindings<Bindings>
-

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

@@ -1,8 +1,8 @@
 
+import {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",
@@ -25,10 +25,6 @@ const gamepadButtonCodes = [
 ]
 
 export class GamepadController extends SamplerController {
-	static on(fn: (controller: GamepadController) => () => void) {
-		return gamepads(pad => fn(new this(pad)))
-	}
-
 	constructor(public pad: Pad) {
 		super()
 	}

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

@@ -2,7 +2,6 @@
 import {coalesce, ev, sub} from "@e280/stz"
 import {Sample} from "../types.js"
 import {Controller} from "../controller.js"
-import {modprefix} from "../utils/modprefix.js"
 
 export class KeyboardController extends Controller {
 	on = sub<Sample>()
@@ -27,11 +26,9 @@ export class KeyboardController extends Controller {
 				keydown: (event: KeyboardEvent) => {
 					if (event.repeat) return
 					down(event.code)
-					down(modprefix(event, event.code))
 				},
 				keyup: (event: KeyboardEvent) => {
 					up(event.code)
-					up(modprefix(event, event.code))
 				},
 			}),
 

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

@@ -1,7 +1,6 @@
 
 import {ev} from "@e280/stz"
 import {Vec2} from "@benev/math"
-import {modprefix} from "../utils/modprefix.js"
 import {splitAxis} from "../../../utils/split-axis.js"
 import {SamplerController} from "../infra/sampler.js"
 
@@ -13,20 +12,15 @@ export class PointerController extends SamplerController {
 	constructor(target: EventTarget = window) {
 		super()
 
-		const dispatch = (event: PointerEvent | WheelEvent, code: string, value: number) => {
-			this.setSample(code, value)
-			this.setSample(modprefix(event, code), value)
-		}
-
 		this.dispose = ev(target, {
 			pointerdown: (event: PointerEvent) => {
 				const code = PointerController.buttonCode(event)
-				dispatch(event, code, 1)
+				this.setSample(code, 1)
 			},
 
 			pointerup: (event: PointerEvent) => {
 				const code = PointerController.buttonCode(event)
-				dispatch(event, code, 0)
+				this.setSample(code, 0)
 			},
 
 			pointermove: (event: PointerEvent) => {
@@ -38,7 +32,7 @@ export class PointerController extends SamplerController {
 
 			wheel: (event: WheelEvent) => {
 				for (const [code, value] of PointerController.wheelCodes(event))
-					dispatch(event, code, value)
+					this.setSample(code, value)
 			},
 		})
 	}