@benev/tact 0.4.0-5 → 0.4.0-7

package/README.md

@@ -2,19 +2,21 @@
 # 🎮 @benev/tact
 > *from keypress to couch co-op.*
 
-**tact is a user-input toolkit for web games.**  
-i made tact because i want to make indie web game development easier. user input seems like it should be easy, but doing it well is actually really complex. especially when you start thinking of multiplayer and multithreading. my goal with tact is to tame the complexity and give people something elegant and flexible that "just works".
+### tact is a user-input toolkit for web games.
 
 🌐 👉 ***https://tact.benev.gg/*** 👈 *try now*  
-
 🖱 keyboards, mice, gamepads.  
-🧩 expressive bindings json dsl.  
-🎨 bindings are user-customizable.  
-🫂 multiplayer and splitscreen capable.  
-🧬 binary for efficient workers and networking.  
-🎸 ready-to-rock drop-in user-interface.  
+🔥 powerful enough for multiplayer games, simple enough for any app.  
+🎸 users can customize keybinds with the ready-to-rock ui.  
+🧬 expressive bindings json dsl.  
+📡 binary streaming for multiplayer and multithreading.  
 ✍️ handcrafted by a human being.  
 
+user input isn't as simple as you'd think.  
+after many design iterations, tact has evolved into an elegant system that handles hard problems for you like customizability, multiplayer, and multithreading. i'm trying to give you the *"it just works"* experience.
+
+i care about the little things. all input types are boiled down to simple numbers, and packed up into efficient binary packets for streaming across networks and web workers. mouse movement precision and accuracy is holy, so there's careful design to make it resilient in the face of encoder/decoder sampling frequency mismatches. the bindings language is an infinitely capable recursive dsl so you can remap values from funky gamepads and make ridiculously complex logical hotkey combinations.
+
 
 
 ![](https://i.imgur.com/dCAlD14.png)
@@ -26,6 +28,7 @@ i made tact because i want to make indie web game development easier. user input
 <br/>
 
 ## 🎮 let's play.
+> *here's the fully-featured, batteries-included, ready-for-anything web game starter pack.*
 
 - 🍏 **install tact into your typescript project.**
     ```sh
@@ -41,8 +44,7 @@ i made tact because i want to make indie web game development easier. user input
       look: ["accumulate", "pointer.x"],
     })
     ```
-    - 💡 *bindings is a tiny json dsl. see [expression.ts](./s/lib/input/expression.ts).*
-- 🍏 **let's have two presets available to the user. one for gamepads.**
+- 🍏 **let's have two presets available to the user, with one for gamepads.**
     ```ts
     import {asPresets} from "@benev/tact"
 
@@ -55,7 +57,7 @@ i made tact because i want to make indie web game development easier. user input
       }},
     })
     ```
-- 🍏 **setup tact.**
+- ⚙️ **setup tact.**
     ```ts
     import {setupTact} from "@benev/tact"
 
@@ -64,41 +66,22 @@ i made tact because i want to make indie web game development easier. user input
     tact.gamepads("gamepad")
     tact.registerElements()
     ```
-    - 💡 *set `maxPlayers` to 1 for single player.*
-- 🍏 **put the `<tact-deck>` in your html page.**
-    ```html
-    <tact-deck></tact-deck>
-    ```
-    - 💡 *you also have each panel, `<tact-controllers>` and `<tact-customize>`.*
-    - 💡 *you can customize the colors with css.*
-        ```html
-        <style>
-          html {
-            --tact-prime: aqua;
-            --tact-bg: black;
-          }
-        </style>
-        ```
-- 🎉 **now users can configure controllers and customize bindings!**
-
-
-
-<br/>
-
-## 🎮 encoding, decoding, and your game logic.
-
-- 🍏 **now it's time for the real action!**
+    - 💡 *you can set `{maxPlayers: 1}` for a single player game.*
+    - 💡 *you can pass `{namespace: "falrysk"}` if you need to run multiple games on one website.*
+    - 💡 *you can register elements manually like `customElements.define("tact-deck-falrysk", tact.elements.TactDeck)`.*
+    - 💡 *you can call `tact.dispose()` to release resources.*
+- 🍏 **encoding, decoding, and your game logic.**
     ```ts
     import {Collector} from "@benev/tact"
 
     const collector = new Collector(bindings)
 
     setInterval(() => {
-      const buffer = tact.deck.hub.encodeAll()
+      const buffer = tact.encodeAll()
       for (const {playerId, inputs} of collector.decodeAll(buffer)) {
 
         // your game logic can read these handy input values.
-        inputs.jump.value // values are numbers 0  to 1.
+        inputs.jump.value // button-like values are numbers 0 to 1.
         inputs.jump.was // previous value (to detect up/down).
         inputs.jump.sum // sum of values reported since last frame.
 
@@ -107,16 +90,31 @@ i made tact because i want to make indie web game development easier. user input
       }
     }, 16.67)
     ```
-    - 💡 *you could stream the buffers across the network to a remote collector.*
-    - 💡 *maybe imagine having the tact deck on the clientside, and the collector on the serverside (or a web worker!).*
+    - 💡 *you could stream the buffers across the network to a remote collector, maybe with [renraku](https://github.com/e280/renraku).*
+    - 💡 *you could have the tact deck on the clientside, and the collector on the serverside (or a web worker!).*
+- 🍏 **put the `<tact-deck>` element in your html page.**
+    ```html
+    <tact-deck></tact-deck>
+    ```
+    - 💡 *or just use the sub-panels directly, `<tact-controllers>` and `<tact-customize>`.*
+    - 💡 *you can customize the colors with css.*
+        ```html
+        <style>
+          html {
+            --tact-prime: aqua;
+          }
+        </style>
+        ```
+- 🎉 **you're done! your users can manage controllers and customize bindings!**
 
 
 
 <br/>
 
 ## 🎮 get down to brass tacks.
+> *for simpler apps, you can use tact's composable parts more directly.*
 
-- 🍏 **pov: your app isn't a game, no multiplayer, no gamepads.**  
+- ⚙️ **pov: your app isn't a game, no multiplayer, no gamepads.**  
     ```ts
     import {setupTact, InputDecoder} from "@benev/tact"
 
@@ -134,7 +132,7 @@ i made tact because i want to make indie web game development easier. user input
     }, 16.67)
     ```
     - 💡 *then the only ui you need is the `<tact-customize>` panel (also available as a sly view `CustomizeView`).*
-- 🍏 **pov: your app doesn't even want any ui, or persistence.**  
+- ⚙️ **pov: your app doesn't even want any ui, or persistence.**  
     ```ts
     import {Controller, InputDecoder, KeyboardSource, PointerSource, Sources} from "@benev/tact"
 
@@ -153,6 +151,67 @@ i made tact because i want to make indie web game development easier. user input
 
 
 
+<br/>
+
+## 🎮 bindings.
+> *bindings are a little json programming language.*
+
+- 🧬 **see [expression.ts](./s/lib/input/expression.ts) to get an idea of what's possible.**  
+- 🧬 **arbitrary nesting is valid.**
+    ```ts
+    asBindings("KeyW")
+
+    inputs.value // 1
+    ```
+    ```ts
+    asBindings({
+      actions: {
+        special: {
+          castMagicSpell: ["*", ["mod", "shift", "alt"], "KeyR"],
+        }
+      }
+    })
+
+    inputs.actions.special.castMagicSpell.value // 1
+    ```
+- 🧬 **you can differentiate taps versus holds on the same key.**
+    ```ts
+    asBindings({
+
+      // tapping E yoinks a weapon into your inventory.
+      grab: ["taps", 1, 250, "KeyE"],
+
+      // holding E equips the weapon as your primary.
+      equip: ["held", 250, "KeyE"],
+    })
+    ```
+- 🧬 **you can "accumulate" mouse inputs accurately,** to avoid losses in sampling frequency mismatches.
+    ```ts
+    asBindings({
+      lookX: ["accumulate", "pointer.x"],
+    })
+
+    inputs.lookX.sum // use sum instead of value, to ensure you don't lose any pointer movement.
+    ```
+- 🧬 **gamepads thumbstick inputs are best done with some math.**
+    ```ts
+    asBindings({
+      forward: ["*",
+
+        // user-customizable sensitivity, equivalent with pointer-pixels-per-second.
+        1234,
+
+        // delta time factor, to ensure sensitivity is framerate-independent.
+        ["dt"],
+
+        // remapping the ranges because gamepads are naughty and often have jiggly deadzones.
+        ["remap", -0.1, -0.9, 0, 1, "gamepad.axis.1"],
+      ],
+    })
+    ```
+
+
+
 <br/><br/>
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@benev/tact",
-	"version": "0.4.0-5",
+	"version": "0.4.0-7",
 	"description": "🎮 from keypress to couch co-op",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",

package/s/index.html.ts

@@ -4,7 +4,7 @@ import {template, html, dataSvgEmoji, socialCard} from "@e280/scute"
 const title = "@benev/tact"
 const domain = "tact.benev.gg"
 const favicon = "/assets/b.png"
-const description = "🎮 keybindings and couch co-op"
+const description = "🎮 from keypress to couch co-op"
 
 export default template(import.meta.url, async orb => html`
 	<!doctype html>

package/s/lib/input/evaluate/context.ts

@@ -11,6 +11,10 @@ export class EvaluationContext {
 	previousValues = new Map<string, number>()
 
 	holding = new Map<object, {start: number}>()
-	tapping = new Map<object, {events: number[]}>()
+	tapping = new Map<object, {
+		wasDown: boolean
+		startedAt: number | null
+		count: number
+	}>()
 }
 

package/s/lib/input/evaluate/evaluate.ts

@@ -1,6 +1,6 @@
 
 import {remap} from "@benev/math"
-import {arraylimit, guarantee, isHappy, isNumber, isString} from "@e280/stz"
+import {guarantee, isHappy, isNumber, isString} from "@e280/stz"
 
 import {isDown} from "../utils/is-down.js"
 import {EvaluationContext} from "./context.js"
@@ -181,27 +181,40 @@ export function evaluate(
 
 		case "taps": {
 			const [, taps, ms, subexpression] = expression
-			const presses = e(subexpression)
+			const down = isDown(e(subexpression))
 			const now = context.clock.time
 
-			const tapped = guarantee(context.tapping, expression, () => ({
-				events: [] as number[],
+			const state = guarantee(context.tapping, expression, () => ({
+				wasDown: false,
+				startedAt: null as number | null,
+				count: 0,
 			}))
 
-			for (let i = 0; i < presses; i++)
-				tapped.events.push(now)
+			const pressed = down && !state.wasDown
+			const released = !down && state.wasDown
 
-			tapped.events = arraylimit(
-				tapped.events.filter(time => time >= now - ms),
-				128,
-			)
+			if (state.startedAt !== null && now - state.startedAt >= ms) {
+				state.startedAt = null
+				state.count = 0
+			}
+
+			let result = 0
 
-			if (tapped.events.length >= taps) {
-				tapped.events = []
-				return 1
+			if (pressed && state.startedAt === null)
+				state.startedAt = now
+
+			if (released && state.startedAt !== null) {
+				state.count++
+
+				if (state.count === taps) {
+					result = 1
+					state.count = 0
+					state.startedAt = null
+				}
 			}
 
-			return 0
+			state.wasDown = down
+			return result
 		}
 
 		case "mod": {

package/s/lib/input/test.ts

@@ -103,16 +103,28 @@ export default suite({
 		expect(inputs.sum).is(0)
 	}),
 
-	"double tap in one frame": test(async() => {
-		const {sample, solve} = quickbind(
-			["taps", 2, 300, ["down", "KeyE"]]
-		)
-
-		for (const value of [1, 0, 1, 0])
+	"single tap": test(async() => {
+		const {sample, solve} = quickbind(["taps", 1, 400, "KeyE"])
+		const hit = (time: number, value: number) => {
 			sample({code: "KeyE", value})
+			return solve(time).value
+		}
+		expect(hit(0, 0)).is(0)
+		expect(hit(100, 1)).is(0)
+		expect(hit(200, 0)).is(1)
+	}),
 
-		expect(solve(100).value).is(1)
-		expect(solve(200).value).is(0)
+	"double tap": test(async() => {
+		const {sample, solve} = quickbind(["taps", 2, 400, "KeyE"])
+		const hit = (time: number, value: number) => {
+			sample({code: "KeyE", value})
+			return solve(time).value
+		}
+		expect(hit(0, 0)).is(0)
+		expect(hit(100, 1)).is(0)
+		expect(hit(200, 0)).is(0)
+		expect(hit(300, 1)).is(0)
+		expect(hit(400, 0)).is(1)
 	}),
 
 	"held across empty frames": test(async() => {
@@ -136,30 +148,29 @@ export default suite({
 		expect(solve(900).value).is(1)
 	}),
 
-	"taps and holds coexist": test(async() => {
+	"taps vs held": test(async() => {
 		const {sample, solve} = quickbind({
-			tapper: ["taps", 1, 10, ["down", "KeyE"]],
-			holder: ["held", 10, "KeyE"],
+			tappy: ["taps", 1, 300, "KeyE"],
+			holdy: ["held", 300, "KeyE"],
 		})
-
-		solve(0)
-
-		sample({code: "KeyE", value: 1})
-		expect(solve(1).tapper.value).is(1)
-
-		sample({code: "KeyE", value: 0})
-		const released = solve(2)
-		expect(released.tapper.value).is(0)
-		expect(released.holder.value).is(0)
-
-		sample({code: "KeyE", value: 1})
-		const pressed = solve(3)
-		expect(pressed.tapper.value).is(1)
-		expect(pressed.holder.value).is(0)
-
-		const holding = solve(13)
-		expect(holding.tapper.value).is(0)
-		expect(holding.holder.value).is(1)
+		const hit = (time: number, value: number) => {
+			sample({code: "KeyE", value})
+			return solve(time)
+		}
+		const __up = (time: number) => hit(time, 0)
+		const DOWN = (time: number) => hit(time, 1)
+
+		expect(__up(1000).tappy.value).is(0)
+		expect(DOWN(1100).tappy.value).is(0)
+		expect(__up(1200).tappy.value).is(1)
+		expect(__up(1300).tappy.value).is(0)
+
+		expect(__up(2000).holdy.value).is(0)
+		expect(DOWN(2100).holdy.value).is(0)
+		expect(DOWN(2200).holdy.value).is(0)
+		expect(DOWN(2300).holdy.value).is(0)
+		expect(DOWN(2400).holdy.value).is(1)
+		expect(__up(2500).tappy.value).is(0) // FAILS
 	}),
 
 	"independent controller consumers": test(async() => {

package/s/lib/ui/deck/auto-gamepads.ts

@@ -21,6 +21,7 @@ export function autoGamepads(
 		const dispose = fn?.(controller, source)
 
 		return () => {
+			controller.dispose()
 			hub.remove(controller)
 			dispose?.()
 		}

package/s/lib/ui/deck/setup/deck.ts

@@ -1,31 +1,44 @@
 
-import {IdbMagazine, idbOpen, Kv} from "@e280/kv"
-
+import {disposer, ev} from "@e280/stz"
 import {Hub} from "../hub.js"
 import {asDeck} from "../types.js"
+import {setupKv} from "./utils/kv.js"
 import {SetupParams} from "./types.js"
 import {Controls} from "../controls/controls.js"
 import {Bindings} from "../../../input/types.js"
 import {firstPreset} from "../utils/first-preset.js"
+import {setupBroadcastChannel} from "./utils/broadcast-channel.js"
 
 export async function setupDeck<B extends Bindings>(params: SetupParams<B>) {
-	const kv = params.kv
-		?? new Kv(new IdbMagazine(await idbOpen("tact", "kv")))
-
-	const broadcastChannel = params.broadcastChannel
-		?? new BroadcastChannel("tact")
-
-	const {maxPlayers} = params
-	const {bindings} = firstPreset(params.presets).profile
-
-	const hub = new Hub(bindings)
-	const controls = new Controls({...params, kv})
-
-	await controls.load()
-
-	broadcastChannel.onmessage = () => controls.load()
-	controls.on(() => broadcastChannel.postMessage({}))
-
-	return asDeck({hub, controls, maxPlayers})
+	const {dispose, schedule, disposable} = disposer()
+
+	const namespace = params.namespace
+		? `tact_${params.namespace}`
+		: "tact"
+
+	const {kv} = disposable(
+		await setupKv(namespace, params.kv)
+	)
+
+	const {broadcastChannel} = disposable(
+		await setupBroadcastChannel(namespace, params.broadcastChannel)
+	)
+
+	try {
+		const {maxPlayers} = params
+		const {bindings} = firstPreset(params.presets).profile
+		const hub = new Hub(bindings)
+		const controls = new Controls({...params, kv})
+
+		schedule(ev(broadcastChannel, {message: () => controls.load()}))
+		schedule(controls.on(() => broadcastChannel.postMessage({})))
+
+		await controls.load()
+		return asDeck({hub, controls, maxPlayers, dispose})
+	}
+	catch (error) {
+		dispose()
+		throw error
+	}
 }
 

package/s/lib/ui/deck/setup/tact.ts

@@ -1,4 +1,5 @@
 
+import {disposer} from "@e280/stz"
 import {register} from "@e280/sly"
 
 import {setupDeck} from "./deck.js"
@@ -22,7 +23,10 @@ import devicesSvg from "../../icons/akar/devices.svg.js"
 import gameControllerSvg from "../../icons/akar/game-controller.svg.js"
 
 export async function setupTact<B extends Bindings>(params: SetupParams<B>) {
-	const deck = await setupDeck(params)
+	const {dispose, schedule, disposable} = disposer()
+
+	const deck = disposable(await setupDeck(params))
+	const first = firstPreset(deck.controls.presets)
 	const visualizer = new Visualizer()
 
 	const elements = {
@@ -33,29 +37,31 @@ export async function setupTact<B extends Bindings>(params: SetupParams<B>) {
 	}
 
 	function gamepads(defaultProfileKey?: string) {
-		return autoGamepads(deck.hub, (controller, source) => {
+		const stop = autoGamepads(deck.hub, (controller, source) => {
 			const handle = `${source.pad.gamepad.id} ${source.pad.gamepad.index + 1}`
 			deck.controls.attach(controller, {
 				icon: gameControllerSvg,
 				handle,
 				tooltip: handle,
 				name: ellipsis(handle, 32),
-				defaultProfileKey: defaultProfileKey ?? firstPreset(deck.controls.presets).key,
+				defaultProfileKey: defaultProfileKey ?? first.key,
 			})
 			return () => deck.controls.detach(controller)
 		})
+		schedule(stop)
+		return stop
 	}
 
 	function mouseKeyboard() {
-		const {key, profile} = firstPreset(deck.controls.presets)
+		const {key, profile} = first
 
-		const controller = new Controller({
+		const controller = disposable(new Controller({
 			bindings: profile.bindings,
-			source: new Sources(
-				new KeyboardSource(),
-				new PointerSource(),
-			),
-		})
+			source: disposable(new Sources(
+				disposable(new KeyboardSource()),
+				disposable(new PointerSource()),
+			)),
+		}))
 
 		deck.hub.plug(controller)
 
@@ -67,6 +73,11 @@ export async function setupTact<B extends Bindings>(params: SetupParams<B>) {
 			defaultProfileKey: key,
 		})
 
+		schedule(() => {
+			deck.hub.remove(controller)
+			deck.controls.detach(controller)
+		})
+
 		return controller
 	}
 
@@ -81,6 +92,8 @@ export async function setupTact<B extends Bindings>(params: SetupParams<B>) {
 		visualizer,
 		elements,
 		registerElements,
+		encodeAll: deck.hub.encodeAll.bind(deck.hub),
+		dispose,
 	}
 }
 

package/s/lib/ui/deck/setup/types.ts

@@ -6,6 +6,7 @@ import {Bindings} from "../../../input/types.js"
 export type SetupParams<B extends Bindings> = {
 	maxPlayers: number
 	presets: Presets<B>
+	namespace?: string
 	kv?: Kv
 	broadcastChannel?: BroadcastChannel
 }

package/s/lib/ui/deck/setup/utils/broadcast-channel.ts

@@ -0,0 +1,17 @@
+
+export async function setupBroadcastChannel(
+		namespace: string,
+		broadcastChannel: BroadcastChannel | undefined,
+	) {
+
+	let dispose = () => {}
+
+	if (!broadcastChannel) {
+		const bc = new BroadcastChannel(namespace)
+		broadcastChannel = bc
+		dispose = () => bc.close()
+	}
+
+	return {broadcastChannel, dispose}
+}
+

package/s/lib/ui/deck/setup/utils/kv.ts

@@ -0,0 +1,20 @@
+
+import {IdbMagazine, idbOpen, Kv} from "@e280/kv"
+
+export async function setupKv(
+		namespace: string,
+		kv: Kv | undefined,
+	) {
+
+	let dispose = () => {}
+
+	if (!kv) {
+		const idb = await idbOpen(namespace, "kv")
+		const magazine = new IdbMagazine(idb)
+		kv = new Kv(magazine)
+		dispose = () => idb.db.close()
+	}
+
+	return {kv, dispose}
+}
+

package/s/lib/ui/deck/types.ts

@@ -4,7 +4,6 @@ import {Bindings} from "../../input/types.js"
 import {Controls} from "./controls/controls.js"
 
 export type PlayerId = number
-
 export type ProfileKey = string
 
 export type Profile<B extends Bindings = any> = {
@@ -19,6 +18,7 @@ export type Deck<B extends Bindings = any> = {
 	hub: Hub<B>
 	maxPlayers: number
 	controls: Controls<B>
+	dispose: () => void
 }
 
 export const asDeck = <B extends Bindings>(deck: Deck<B>) => deck

package/s/lib/ui/views/customize/view.ts

@@ -27,17 +27,17 @@ export const [CustomizeView, makeCustomizeElement] = shadowDuplex((options: {con
 		? profiles.get(profile.basedOn)
 		: profile
 
-	const updateBindings = (bindings: Bindings) => {
+	const updateBindings = async(bindings: Bindings) => {
 		let key = $profileKey()
 
 		if (profiles.isPreset(key)) {
 			const basedOn = key
 			const freshKey = makeId()
 			key = freshKey
-			profiles.clone(freshKey, basedOn)
+			await profiles.clone(freshKey, basedOn)
 		}
 
-		profiles.update(key, {bindings})
+		await profiles.update(key, {bindings})
 		$profileKey(key)
 	}