@benev/tact 0.1.0-2 → 0.1.0-4

package/README.md

@@ -1,83 +1,82 @@
 
-# @benev/tact
-> web game input library, from keypress to couch co-op
+
+> [!CAUTION]
+> ### 🚨🚨 TACT IS UNDER DEVELOPMENT!! 🚨🚨
+> *everything is half-broken right now.. just gimmie a minute to finish coding this, will ya?*
+
+<br></br>
+
+---
+
+---
+
+<br></br>
+
+# 🎮 @benev/tact
+> *web game input library, from keypress to couch co-op*
 
 ```ts
 npm install @benev/tact
 ```
 
-- 🛹 **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
+tact is a toolkit for handling user inputs on the web.  
+it's good at user-customizable keybindings, multiple gamepad support, and mobile ui.  
 
+- 🛹 **[#deck](#deck)** full setup with localstorage persistence
+- 🎮 **[#devices](#devices)** produce user input samples
+- 🧩 **[#bindings](#bindings)** describe how actions interpret samples
+- 🔌 **[#port](#port)** updates actions by interpreting samples
+- 🛞 **[#hub](#hub)** plugs devices into ports (multi-gamepad couch co-op!)
+- 📱 **[#nubs](#nubs)** is mobile ui virtual gamepad stuff
 
 
 <br/><br/>
+<a id="deck"></a>
 
 ## 🍋 tact deck
-> *user input coordinator with bindings persistence*
+> *full setup with ui, batteries included*
 
-the deck is the heart of tact.. it ties all the important parts together..
+the deck ties together all the important pieces of tact into a single user experience, complete with ui components.
 
 ### 🛹 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({
-        walking: {
-          forward: [
-            {lenses: [{code: "KeyW"}]},
-            {lenses: [{code: "gamepad.stick.left.up"}]},
-          ],
-          jump: [
-            {lenses: [{code: "Space"}]},
-            {lenses: [{code: "gamepad.a"}]},
-          ],
-        },
+    const deck = await tact.Deck.load({
+
+      // how many player 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: {
+        walking: {forward: "KeyW", jump: "Space"},
         gunning: {
-          shoot: [
-            {lenses: [{code: "pointer.button.left"}]},
-            {lenses: [{code: "gamepad.trigger.right"}]},
-          ],
+          shoot: ["or", "pointer.button.left", "gamepad.trigger.right"],
         },
-      }),
+      },
     })
     ```
 
-### 🛹 plug controllers into the hub
+### 🛹 plug devices 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**
+    deck.hub.plug(new tact.PrimaryDevice())
+    ```
+- **automatically detect and plug gamepads**
     ```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**
+- **poll the deck, interrogate actions**
     ```ts
-    onEachTickInYourGame(() => {
+    myGameLoop(() => {
 
       // do your polling
       const [p1, p2, p3, p4] = deck.hub.poll()
@@ -90,40 +89,47 @@ the deck is the heart of tact.. it ties all the important parts together..
     })
     ```
 
+### 🛹 deck ui: the overlay
+- **register the deck's web components to the dom**
+    ```ts
+    deck.registerComponents()
+    ```
+- **place the ui on top of your game canvas**
+    ```html
+    <deck-overlay></deck-overlay>
+    ```
+
 
 
 <br/><br/>
+<a id="devices"></a>
 
-## 🍋 tact controllers
-> *produces user input "samples"*
+## 🍋 tact devices
+> *sources of 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
+- the gift of polling is total control over *when* inputs are processed, this is good for games
 - i will elaborate no further 🗿
 
-### 🎮 basically how a controller works
-- make a controller
+### 🎮 basically how a device works
+- make a device
     ```ts
-    const keyboard = new tact.KeyboardController()
+    const keyboard = new tact.KeyboardDevice()
     ```
-- take samples each frame
+- reading samples looks like this
     ```ts
-    const samples = keyboard.takeSamples()
-      // [
-      //   ["KeyA", 1],
-      //   ["Space", 0]
-      // ]
+    for (const sample of keyboard.samples())
+      console.log(sample) // ["KeyA", 1]
     ```
-- dispose when you're done with it
+- some devices have disposers to call when you're done with them
     ```ts
     keyboard.dispose()
     ```
 
 ### 🎮 samples explained
-- a sample is a raw input of type `[code: string, value: number]`
+- a sample is a raw input tuple 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`
   - or it's something we made up, like `pointer.button.left` or `gamepad.trigger.right`
@@ -135,37 +141,21 @@ 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**
+- **KeyboardDevice**
     - 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
-- **PointerController**
-    - mouse buttons (plus modprefixes)
+- **PointerDevice**
+    - 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`
@@ -175,7 +165,7 @@ the deck is the heart of tact.. it ties all the important parts together..
         - `pointer.move.down`
         - `pointer.move.left`
         - `pointer.move.right`
-- **GamepadController**
+- **GamepadDevice**
     - gamepad buttons
         - `gamepad.a`
         - `gamepad.b`
@@ -207,69 +197,147 @@ the deck is the heart of tact.. it ties all the important parts together..
 
 
 <br/><br/>
+<a id="bindings"></a>
 
 ## 🍋 tact bindings
 > *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"}]}],
-      },
+      walking: {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", {range: [0, 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,
+		  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/>
+<a id="port"></a>
 
 ## 🍋 tact port
 > *polling gives you "actions"*
 
-### 🔌 port basics
+a port represents a single playable port, and you poll it each frame to resolve actions for you to read.
+
+### 🔌 port setup
 - **make a port**
     ```ts
     const port = new tact.Port(bindings)
     ```
-- **attach some controllers to the port**
+- **attach some devices to the port**
     ```ts
-    port.controllers
-      .add(new tact.KeyboardController())
-      .add(new tact.PointerController())
-      .add(new tact.VirtualGamepadController())
+    port.devices
+      .add(new tact.KeyboardDevice())
+      .add(new tact.PointerDevice())
+      .add(new tact.VpadDevice())
     ```
-    - you can add/delete controllers from the set any time
-- **don't forget to enable modes!**
+    - you can add/delete devices from the set any time
+- **manipulate modes**
     ```ts
+    port.modes.clear()
     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(device => {
+      port.devices.add(device)
+      return () => port.devices.delete(device)
+    })
+    ```
 
 ### 🔌 interrogating actions
 - **poll the port every frame**
     ```ts
-    const actions = port.poll()
+    port.poll()
     ```
 - **now you can inspect the `actions`**
     ```ts
-    actions.walking.forward.value // 1
+    port.actions.walking.forward.value // 1
     ```
     - `walking` is a `mode`
     - `forward` is an `action`
@@ -283,77 +351,81 @@ the deck is the heart of tact.. it ties all the important parts together..
 
 
 <br/><br/>
+<a id="hub"></a>
 
 ## 🍋 tact hub
 > *multiple gamepads! couch co-op is so back*
 
 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.
+the hub embraces that analogy, helping you coordinate the plugging and unplugging of virtual controller devices into its virtual ports.
 
 ### 🛞 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)
-    ```
-    - 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 hub with multiple ports at the ready**
     ```ts
     const hub = new tact.Hub([
-      new tact.Port(hubBindings),
-      new tact.Port(hubBindings),
-      new tact.Port(hubBindings),
-      new tact.Port(hubBindings),
+      new tact.Port(bindings),
+      new tact.Port(bindings),
+      new tact.Port(bindings),
+      new tact.Port(bindings),
     ])
     ```
     - yes that's right — each player port gets its own bindings 🤯
 
-### 🛞 plug in some controllers
+### 🛞 plug in some devices
 - **let's plug in the keyboard/mouse player**
     ```ts
-    hub.plug(
-      new tact.GroupController(
-        new tact.KeyboardController(),
-        new tact.PointerController(),
-        new tact.VirtualGamepadController(),
-      )
-    )
-    ```
-    - the hub requires a single controller to represent a player, thus we can use a `GroupController` to combine multple controllers into one
+    hub.plug(new tact.PrimaryDevice())
+    ```
+    - the hub requires a single device to represent a player, so you can use a `GroupDevice` to combine multple devices into one
 - **wire up gamepad auto connect/disconnect**
     ```ts
     tact.autoGamepads(hub.plug)
     ```
 
-### 🛞 it's gaming time
+### 🛞 now we're gaming
 - **do your polling, interrogate those actions**
     ```ts
     const [p1, p2, p3, p4] = hub.poll()
 
-    p1.walking.jump.value // 1
-    p2.walking.jump.value // 0
+    p1.actions.walking.jump.value // 1
+    p2.actions.walking.jump.value // 0
     ```
 
 
 
 <br/><br/>
+<a id="nubs"></a>
 
 ## 🍋 tact nubs
 > *mobile ui like virtual thumbsticks and buttons*
 
+### 📱 nubs setup
+- **register nub components to dom**
+    ```ts
+    tact.registerNubs()
+    ```
+- **place nub components onto your html page**
+    ```html
+    <nub-stick></nub-stick>
+    ```
+
 ### 📱 nub stick
-> TODO lol need to write docs
+- **place a nub-stick onto your page**
+    ```html
+    <nub-stick></nub-stick>
+    ```
+- **get the stick device, plug it into your hub or whatever**
+    ```ts
+    const nubStick = document.queryElement<tact.NubStick>("nub-stick")!
 
-### 📱 nub virtual gamepad
-> TODO lol need to write docs
+    deck.hub.plug(nubStick.device)
+    ```
 
 
 
 <br/><br/>
+<a id="benev"></a>
 
 ## 🍋 tact is by https://benevolent.games/
 > *building the future of web games*

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@benev/tact",
-	"version": "0.1.0-2",
+	"version": "0.1.0-4",
 	"description": "keybindings and gamepad support for web games",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -32,14 +32,15 @@
 		"lit": "^3.3.1"
 	},
 	"dependencies": {
-		"@benev/math": "^0.2.0-1",
-		"@e280/sly": "^0.1.1",
-		"@e280/strata": "^0.1.0",
-		"@e280/stz": "^0.2.0-4"
+		"@benev/math": "^0.2.0-4",
+		"@e280/kv": "^0.1.0",
+		"@e280/sly": "^0.2.0-16",
+		"@e280/strata": "^0.2.0-13",
+		"@e280/stz": "^0.2.5"
 	},
 	"devDependencies": {
-		"@e280/science": "^0.1.1",
-		"@e280/scute": "^0.0.0",
+		"@e280/science": "^0.1.2",
+		"@e280/scute": "^0.1.0",
 		"http-server": "^14.1.1",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^5.9.2"

package/s/core/{port → bindings}/action.ts

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

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

@@ -0,0 +1,31 @@
+
+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,
+		range: null,
+		bottom: null,
+		top: null,
+		timing: ["direct"],
+	}
+}
+
+function defaultifyCodeSettings(partial: Partial<CodeSettings> = {}): CodeSettings {
+	return {
+		...defaultCodeSettings(),
+		...partial,
+	}
+}
+