@benev/tact 0.1.0-3 → 0.1.0-4

package/README.md

@@ -1,4 +1,17 @@
 
+
+> [!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*
 
@@ -6,21 +19,24 @@
 npm install @benev/tact
 ```
 
-- 🛹 **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
+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
-> *the full setup*
+> *full setup with ui, batteries included*
 
-the deck is the heart of tact, tying all the pieces together and putting a bow in it for you.
+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**
@@ -31,7 +47,7 @@ the deck is the heart of tact, tying all the pieces together and putting a bow i
     ```ts
     const deck = await tact.Deck.load({
 
-      // how many players ports are possible? 1 is fine..
+      // how many player ports are possible? 1 is fine..
       portCount: 4,
 
       // where to store the user-customized bindings
@@ -39,11 +55,7 @@ the deck is the heart of tact, tying all the pieces together and putting a bow i
 
       // default archetypal bindings for your game
       bindings: {
-        ...tact.hubBindings(),
-        walking: {
-          forward: "KeyW",
-          jump: "Space",
-        },
+        walking: {forward: "KeyW", jump: "Space"},
         gunning: {
           shoot: ["or", "pointer.button.left", "gamepad.trigger.right"],
         },
@@ -51,77 +63,73 @@ the deck is the heart of tact, tying all the pieces together and putting a bow i
     })
     ```
 
-### 🛹 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()
 
       // check if the first player is pressing "forward" action
-      p1.walking.forward.pressed // true
+      p1.actions.walking.forward.pressed // true
 
       // check how hard the second player is pulling that trigger
-      p2.gunning.shoot.value // 0.123
+      p2.actions.gunning.shoot.value // 0.123
     })
     ```
 
+### 🛹 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
+## 🍋 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]
     ```
-- some controllers have disposers to call when you're done with them
+- 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`
@@ -134,13 +142,13 @@ the deck is the heart of tact, tying all the pieces together and putting a bow i
   - don't worry about sensitivity, deadzones, values like `0.00001` — actions will account for all that using bindings later on
 
 ### 🎮 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
-- **PointerController**
+- **PointerDevice**
     - mouse buttons
         - `pointer.button.left`
         - `pointer.button.right`
@@ -157,7 +165,7 @@ the deck is the heart of tact, tying all the pieces together and putting a bow i
         - `pointer.move.down`
         - `pointer.move.left`
         - `pointer.move.right`
-- **GamepadController**
+- **GamepadDevice**
     - gamepad buttons
         - `gamepad.a`
         - `gamepad.b`
@@ -189,6 +197,7 @@ the deck is the heart of tact, tying all the pieces together and putting a bow i
 
 
 <br/><br/>
+<a id="bindings"></a>
 
 ## 🍋 tact bindings
 > *keybindings! they describe how actions interpret samples*
@@ -197,10 +206,7 @@ the deck is the heart of tact, tying all the pieces together and putting a bow i
 - **let's start with a small example:**
     ```ts
     const bindings = tact.asBindings({
-      walking: {
-        forward: "KeyW",
-        jump: "Space",
-      },
+      walking: {forward: "KeyW", jump: "Space"},
       gunning: {
         shoot: ["or", "pointer.button.left", "gamepad.trigger.right"],
       },
@@ -227,7 +233,7 @@ the deck is the heart of tact, tying all the pieces together and putting a bow i
 - **you can get really weird**
     ```ts
     ["cond",
-      ["code", "gamepad.trigger.right", {deadzone: 0.5, timing: ["tap"]}],
+      ["code", "gamepad.trigger.right", {range: [0, 0.5], timing: ["tap"]}],
       ["and", "gamepad.bumper.left", ["not", "gamepad.trigger.left"]],
     ]
     ```
@@ -240,7 +246,7 @@ the deck is the heart of tact, tying all the pieces together and putting a bow i
     ["code", "KeyA", {
 		  scale: 1,
 		  invert: false,
-		  deadzone: 0.2,
+		  deadzone: 0,
 		  timing: ["direct"],
     }]
     ```
@@ -285,30 +291,31 @@ the deck is the heart of tact, tying all the pieces together and putting a bow i
 
 
 <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 basics
+### 🔌 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**
@@ -317,20 +324,20 @@ a port represents a single playable port, and you poll it each frame to resolve
     ```
 - **wire up gamepad auto connect/disconnect**
     ```ts
-    tact.autoGamepads(controller => {
-      port.controllers.add(controller)
-      return () => port.controllers.delete(controller)
+    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`
@@ -344,80 +351,81 @@ a port represents a single playable port, and you poll it each frame to resolve
 
 
 <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
-    const hubBindings = {
-      ...yourBindings,
-
-      // mixin standard hub bindings
-      ...tact.hubBindings(),
-    }
-    ```
-    - 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**
     ```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-3",
+	"version": "0.1.0-4",
 	"description": "keybindings and gamepad support for web games",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -32,15 +32,15 @@
 		"lit": "^3.3.1"
 	},
 	"dependencies": {
-		"@benev/math": "^0.2.0-1",
+		"@benev/math": "^0.2.0-4",
 		"@e280/kv": "^0.1.0",
-		"@e280/sly": "^0.1.1",
-		"@e280/strata": "^0.1.0",
-		"@e280/stz": "^0.2.0-5"
+		"@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/bindings/action.ts

@@ -1,16 +1,26 @@
 
+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

@@ -15,7 +15,9 @@ function defaultCodeSettings(): CodeSettings {
 	return {
 		scale: 1,
 		invert: false,
-		deadzone: 0.2,
+		range: null,
+		bottom: null,
+		top: null,
 		timing: ["direct"],
 	}
 }

package/s/core/bindings/parts/lens-algo.ts

@@ -11,23 +11,27 @@ export const lensAlgo = (
 		v: number,
 	) => pipe(v).line(
 
-	function deadzone(value) {
-		if (value < state.settings.deadzone)
-			return 0
-
-		if (value > 1)
-			return value
-
-		return Scalar.remap(
-			value,
-			state.settings.deadzone, 1,
-			0, 1,
-		)
+	function clippings(value) {
+		const {settings} = state
+		if (settings.range) {
+			const [bottom, top] = settings.range
+			value = Scalar.isBetween(value, bottom, top)
+				? Scalar.remap(
+					value,
+					bottom, top,
+					0, 1,
+					true,
+				)
+				: 0
+		}
+		if (settings.bottom) value = Math.max(settings.bottom, value)
+		if (settings.top) value = Math.min(settings.top, value)
+		return value
 	},
 
 	function inversion(value) {
 		return state.settings.invert
-			? value * -1
+			? 1 - value
 			: value
 	},
 

package/s/core/bindings/resolver.ts

@@ -1,38 +1,38 @@
 
 import {MapG, pub, obMap} from "@e280/stz"
 import {Action} from "./action.js"
+import {SampleMap} from "./sample-map.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>
-
+	readonly actions: Actions<B>
+	#modes = new Set<keyof B>()
+	#sampleMap = new SampleMap()
 	#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 => {
+	constructor(public bindings: B) {
+		this.actions = obMap(bindings, (bracket, mode) => obMap(bracket, atom => {
 			const action = new Action()
 			this.#update.subscribe(() => {
-				const value = modes.has(mode)
+				action.value = this.#modes.has(mode)
 					? this.#resolveAtom()(atom)
 					: 0
-				Action.update(action, value)
 			})
 			return action
 		})) as Actions<B>
 	}
 
-	poll(now: number, samples: SampleMap) {
+	resolve(now: number, modes: Set<keyof B>, sampleMap: SampleMap) {
 		this.#now = now
-		this.#samples = samples
+		this.#modes = modes
+		this.#sampleMap = sampleMap
 		this.#update()
-		return this.#actions
+		return this.actions
 	}
 
 	#resolveCode(count: number, code: string, settings?: Partial<CodeSettings>) {
@@ -40,7 +40,7 @@ export class Resolver<B extends Bindings> {
 			count,
 			() => defaultCodeState(["code", code, settings]),
 		)
-		const value = this.#samples.get(code) ?? 0
+		const value = this.#sampleMap.get(code) ?? 0
 		return lensAlgo(this.#now, state, value)
 	}
 

package/s/core/bindings/sample-map.ts

@@ -0,0 +1,25 @@
+
+import {MapG} from "@e280/stz"
+import {Sample} from "../devices/types.js"
+
+export class SampleMap extends MapG<string, number> {
+	constructor(samples?: Iterable<Sample>) {
+		super()
+		if (samples) {
+			for (const [code, value] of samples)
+				this.set(code, value)
+		}
+	}
+
+	zero() {
+		for (const code of this.keys()) this.set(code, 0)
+		return this
+	}
+
+	mergeSample([code, value]: Sample) {
+		const previous = this.get(code) ?? 0
+		if (value > previous) this.set(code, value)
+		return this
+	}
+}
+

package/s/core/bindings/types.ts

@@ -34,7 +34,9 @@ export type Atom = string | (
 export type CodeSettings = {
 	scale: number
 	invert: boolean
-	deadzone: number
+	range: null | [number, number]
+	bottom: null | number
+	top: null | number
 	timing: (
 		| ["direct"]
 		| ["tap", holdTime?: number]