@benev/tact 0.2.0 → 0.3.0-2

package/README.md

@@ -1,435 +1,93 @@
 
 # 🎮 @benev/tact
-> *web game input library, from keypress to couch co-op*
+> *from keypress to couch co-op*
 
 ```ts
 npm install @benev/tact
 ```
 
-tact is a toolkit for handling user inputs on the web.  
-it's good at user-customizable keybindings, multiple gamepad support, and mobile ui.  
+tact is a toolkit for handling user input on the web.  
+customizable keybindings, multiple-gamepad couch co-op, ready-made configurator ui, efficient networking, mobile virtual thumbsticks.  
 
-- 🛹 **[#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
-> *full setup with ui, batteries included*
-
-the deck ties together all the important pieces of tact into a single user experience, complete with ui views.
-
-tact's ui is built with [`@e280/sly` shadow views](https://github.com/e280/sly).
-
-### 🛹 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 player ports are possible? 1 is fine..
-      portCount: 4,
+<br/>
 
-      // where to store the user-customized bindings
-      kv: tact.localStorageKv(),
+## 🎮 tact basics
 
-      // default archetypal bindings for your game
-      bindings: {
-        walking: {forward: "KeyW", jump: "Space"},
-        gunning: {
-          shoot: ["or", "pointer.button.left", "gamepad.trigger.right"],
-        },
-      },
-    })
-    ```
-
-### 🛹 plug devices into the hub
-- **plug a keyboard/mouse player into the hub**
-    ```ts
-    deck.hub.plug(new tact.PrimaryDevice())
-    ```
-- **automatically detect and plug gamepads**
-    ```ts
-    tact.autoGamepads(deck.hub.plug)
-    ```
+```ts
+import {
+  Devices, KeyboardDevice, PointerDevice,
+  makeIntentsResolver, makeActionsResolver,
+} from "@benev/tact"
+```
 
-### 🛹 do your gameplay
-- **poll the deck, interrogate actions**
+1. **setup your game's keybindings**
     ```ts
-    myGameLoop(() => {
-
-      // 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
-    })
+    const bindings = {
+      running: {forward: "KeyW", jump: ["and", "ShiftLeft", "Space"]},
+      gunning: {shoot: ["or", "pointer.button.left", "gamepad.trigger.right"]},
+    }
     ```
-
-### 🛹 deck ui: the overlay
-- **render the deck overlay with sly**
+1. **create your devices (which provide raw input samples)**
     ```ts
-    import {dom} from "@e280/sly"
-
-    dom.render(
-      dom("#game-ui"),
-      tact.DeckOverlay(deck),
+    const devices = new Devices(
+      new KeyboardDevice(),
+      new PointerDevice(),
     )
     ```
-- **place the ui on top of your game canvas**
-    ```html
-    <div id="game-ui"></div>
-    ```
-
-
-
-<br/><br/>
-<a id="devices"></a>
-
-## 🍋 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
-- 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 device works
-- make a device
-    ```ts
-    const keyboard = new tact.KeyboardDevice()
-    ```
-- reading samples looks like this
+1. **make your resolvers**
     ```ts
-    for (const sample of keyboard.samples())
-      console.log(sample) // ["KeyA", 1]
+    const resolveIntents = makeIntentsResolver(bindings)
+    const resolveActions = makeActionsResolver(bindings)
     ```
-- some devices have disposers to call when you're done with them
+1. **run your resolvers, read your actions**
     ```ts
-    keyboard.dispose()
-    ```
-
-### 🎮 samples explained
-- 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`
-- a sample has a `value` number
-  - `0` means *"nothing is going on"*
-  - `1` means *"pressed"*
-  - we don't like negative numbers
-  - values between `0` and `1`, like `0.123`, are how triggers and thumbsticks express themselves
-  - 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 reference
-- **KeyboardDevice**
-    - any [standard keycode](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values)
-        - `KeyA`
-        - `Space`
-        - `Digit2`
-        - etc
-- **PointerDevice**
-    - mouse buttons
-        - `pointer.button.left`
-        - `pointer.button.right`
-        - `pointer.button.middle`
-        - `pointer.button.4`
-        - `pointer.button.5`
-    - mouse wheel
-        - `pointer.wheel.up`
-        - `pointer.wheel.down`
-        - `pointer.wheel.left`
-        - `pointer.wheel.right`
-    - mouse movements
-        - `pointer.move.up`
-        - `pointer.move.down`
-        - `pointer.move.left`
-        - `pointer.move.right`
-- **GamepadDevice**
-    - gamepad buttons
-        - `gamepad.a`
-        - `gamepad.b`
-        - `gamepad.x`
-        - `gamepad.y`
-        - `gamepad.bumper.left`
-        - `gamepad.bumper.right`
-        - `gamepad.trigger.left`
-        - `gamepad.trigger.right`
-        - `gamepad.alpha`
-        - `gamepad.beta`
-        - `gamepad.stick.left.click`
-        - `gamepad.stick.right.click`
-        - `gamepad.up`
-        - `gamepad.down`
-        - `gamepad.left`
-        - `gamepad.right`
-        - `gamepad.gamma`
-    - gamepad sticks
-        - `gamepad.stick.left.up`
-        - `gamepad.stick.left.down`
-        - `gamepad.stick.left.left`
-        - `gamepad.stick.left.right`
-        - `gamepad.stick.right.up`
-        - `gamepad.stick.right.down`
-        - `gamepad.stick.right.left`
-        - `gamepad.stick.right.right`
+    import {cycle} from "@e280/stz"
 
+    cycle(function myGameTick() {
 
+      // 🧙‍♂️ samples get resolved into compact intent tuples, good for networking.
+      const intents = resolveIntents(Date.now(), devices.samples())
 
-<br/><br/>
-<a id="bindings"></a>
-
-## 🍋 tact bindings
-> *keybindings! they describe how actions interpret samples*
+      // 🧙‍♂️ actions are your ergonomic accessors for values.
+      const actions = resolveActions(intents)
 
-### 🧩 bindings example
-- **let's start with a small example:**
-    ```ts
-    const bindings = tact.asBindings({
-      walking: {forward: "KeyW", jump: "Space"},
-      gunning: {
-        shoot: ["or", "pointer.button.left", "gamepad.trigger.right"],
-      },
+      // 🧙‍♂️ okay, now check your actions.
+      actions.running.forward.value // 1.0
+      actions.running.forward.pressed // true
     })
     ```
-    - `walking` and `gunning` are **modes**
-    - `forward`, `jump`, and `shoot` are **actions**
-    - 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
+### 🧙‍♂️ wizardly tips
 
-### 🧩 bindings atom reference
-- **string** — strings are interpreted as "code" atoms with default settings
-- **"code"** — allows you to customize the settings
+1. **for networking, you should encode intents as Uint8Array for better efficiency down the wire.**
     ```ts
-    ["code", "KeyA", {
-		  scale: 1,
-		  invert: false,
-		  timing: ["direct"],
-    }]
-    ```
-    - defaults shown
-    - `scale` is sensitivity, the value gets multiplied by this
-    - `invert` will invert a value by subtracting it from 1
-    - `clamp` clamps the value with a lower and upper bound
-    - `range` restricts value to the given range, and remaps that range 0 to 1
-    - `bottom` zeroes the value if it's less than the given bottom value
-    - `top` clamps the value to an upper bound
-    - `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"*
-
-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 devices to the port**
-    ```ts
-    port.devices
-      .add(new tact.KeyboardDevice())
-      .add(new tact.PointerDevice())
-      .add(new tact.VpadDevice())
-    ```
-    - you can add/delete devices from the set any time
-- **manipulate modes**
-    ```ts
-    port.modes.clear()
-    port.modes.add("walking")
-    ```
-    - 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
-    port.poll()
-    ```
-- **now you can inspect the `actions`**
-    ```ts
-    port.actions.walking.forward.value // 1
-    ```
-    - `walking` is a `mode`
-    - `forward` is an `action`
-    - `action.value` — current value
-    - `action.previous` — last frame's value
-    - `action.changed` — true if value and previous are different
-    - `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
-
+    import {encodeIntents, decodeIntents} from "@benev/tact"
 
+    const intents = [[1, 0.7853981633974483]]
 
-<br/><br/>
-<a id="hub"></a>
-
-## 🍋 tact hub
-> *multiple gamepads! couch co-op is so back*
+    console.log(JSON.stringify(intents).length)
+      // 22 — yikes
 
-you know the way old-timey game consoles had four controller ports on the front?
+    const bytes = encodeIntents(intents)
 
-the hub embraces that analogy, helping you coordinate the plugging and unplugging of virtual controller devices into its virtual ports.
+    console.log(bytes.length)
+      // 6 — noice
 
-### 🛞 create a hub with ports
-- **make hub with multiple ports at the ready**
-    ```ts
-    const hub = new tact.Hub([
-      new tact.Port(bindings),
-      new tact.Port(bindings),
-      new tact.Port(bindings),
-      new tact.Port(bindings),
-    ])
+    const intents = decodeIntents(bytes)
     ```
-    - yes that's right — each player port gets its own bindings 🤯
-
-### 🛞 plug in some devices
-- **let's plug in the keyboard/mouse player**
+1. **you can normalize bindings**
     ```ts
-    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)
-    ```
+    import {normalizeBindings} from "@benev/tact"
 
-### 🛞 now we're gaming
-- **do your polling, interrogate those actions**
-    ```ts
-    const [p1, p2, p3, p4] = hub.poll()
-
-    p1.actions.walking.jump.value // 1
-    p2.actions.walking.jump.value // 0
+    const bindings = normalizeBindings(appBindings, susBindings)
     ```
+    this clones your app bindings and cherry-picks any compatible user bindings. useful when loading from localStorage, so changes to your schema don’t break things.
 
 
 
 <br/><br/>
-<a id="nubs"></a>
-
-## 🍋 tact nubs
-> *mobile ui like virtual thumbsticks and buttons*
-
-### 📱 nubs setup
-- **render nub views with sly**
-    ```ts
-    import {dom} from "@e280/sly"
-
-    const stick = new tact.StickDevice()
 
-    dom.render(
-      dom("#controls"),
-      tact.NubStick(stick),
-    )
-    ```
-
-### 📱 nub stick
-- **place a mount point onto your page**
-    ```html
-    <div id="controls"></div>
-    ```
-- **make the stick device yourself, then plug it into your hub or whatever**
-    ```ts
-    const stick = new tact.StickDevice()
-
-    dom.render(
-      dom("#controls"),
-      tact.NubStick(stick),
-    )
-
-    deck.hub.plug(stick)
-    ```
-
-
-
-<br/><br/>
-<a id="benev"></a>
+👼 *https://benev.gg/*
 
-## 🍋 tact is by https://benevolent.games/
-> *building the future of web games*

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@benev/tact",
-	"version": "0.2.0",
-	"description": "keybindings and gamepad support for web games",
+	"version": "0.3.0-2",
+	"description": "🎮 keybindings and couch co-op",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
 	"type": "module",
@@ -9,55 +9,53 @@
 	"sideEffects": false,
 	"exports": {
 		".": "./x/index.js",
-		"./core": "./x/core/index.js"
+		"./ui": "./x/index-ui.js"
 	},
 	"files": [
 		"x",
 		"s"
 	],
 	"scripts": {
-		"build": "octo-s --npm-run _clean _tsc _ln _scute",
-		"dev": "octo 'scute -vw' 'tsc -w' 'node --watch x/tests.test.js' 'hottie x'",
-		"_clean": "rm -rf x",
-		"_tsc": "tsc",
-		"_scute": "scute -v",
-		"_ln": "run-s _ln-s _ln-assets",
-		"_ln-s": "ln -s \"$(realpath s)\" x/s",
-		"_ln-assets": "ln -s \"$(realpath assets)\" x/assets",
-		"test": "node x/tests.test.js",
+		"build": "octo-s 'rm -rf x' 'tsc' 'scute -v'",
+		"dev": "octo 'scute -vw' 'tsc -w' 'node --watch x/test.js' 'hottie x --port=8081'",
+		"test": "node x/test.js",
 		"count": "find s -path '*/_archive' -prune -o -name '*.ts' -exec wc -l {} +"
 	},
 	"peerDependencies": {
-		"lit": "^3.3.2"
+		"@e280/sly": "^0.4.6",
+		"@e280/strata": "^0.4.3",
+		"lit": "^3.3.3"
 	},
 	"dependencies": {
-		"@benev/math": "^0.3.0-5",
-		"@e280/kv": "^0.1.2",
-		"@e280/sly": "^0.3.7",
-		"@e280/strata": "^0.3.3",
-		"@e280/stz": "^0.2.32"
+		"@benev/math": "^0.4.0-2",
+		"@e280/kv": "^0.2.0",
+		"@e280/stz": "^0.3.10"
 	},
 	"devDependencies": {
-		"@e280/hottie": "^0.1.0",
-		"@e280/octo": "^0.1.0",
-		"@e280/science": "^0.1.10",
-		"@e280/scute": "^0.3.2",
+		"@e280/hottie": "^0.1.5",
+		"@e280/octo": "^0.1.5",
+		"@e280/science": "^0.1.12",
+		"@e280/scute": "^0.5.1",
 		"http-server": "^14.1.1",
 		"npm-run-all": "^4.1.5",
-		"typescript": "^6.0.2"
+		"typescript": "^7.0.2"
 	},
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/benevolent-games/tact.git"
+		"url": "git+https://github.com/benev-gg/tact.git"
 	},
 	"bugs": {
-		"url": "https://github.com/benevolent-games/tact/issues"
+		"url": "https://github.com/benev-gg/tact/issues"
 	},
-	"homepage": "https://github.com/benevolent-games/tact#readme",
+	"homepage": "https://github.com/benev-gg/tact#readme",
 	"keywords": [
 		"user input",
 		"keybinds",
 		"keybindings",
 		"gamepad"
-	]
+	],
+	"allowScripts": {
+		"classic-level@3.0.0": true,
+		"esbuild@0.28.2": true
+	}
 }