@benev/tact 0.4.0-1 → 0.4.0-10

package/README.md

@@ -2,16 +2,22 @@
 # 🎮 @benev/tact
 > *from keypress to couch co-op.*
 
-**tact is a user-input toolkit for web games.**
+### 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)
 
@@ -22,8 +28,9 @@
 <br/>
 
 ## 🎮 let's play.
+> *here's the fully-featured, batteries-included, ready-for-anything web game starter pack.*
 
-- 🍏 **install tact.**
+- 🍏 **install tact into your typescript project.**
     ```sh
     npm install @benev/tact@next
     ```
@@ -37,8 +44,7 @@
       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"
 
@@ -51,7 +57,7 @@
       }},
     })
     ```
-- 🍏 **now we can setup tact and register the html elements.**
+- ⚙️ **setup tact.**
     ```ts
     import {setupTact} from "@benev/tact"
 
@@ -60,70 +66,152 @@
     tact.gamepads("gamepad")
     tact.registerElements()
     ```
-- 🍏 **simply put the `<tact-deck>` in your html page.**
-    ```html
-    <tact-deck></tact-deck>
+    - 💡 *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 {Players} from "@benev/tact"
+
+    const players = new Players(bindings)
+
+    setInterval(() => {
+      const buffer = tact.encodeAll()
+      players.decodeAll(buffer)
+      for (const [playerId, inputs] of players) {
+
+        // your game logic can read these handy input values.
+        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.
+
+        inputs.forward.value
+        inputs.look.value
+      }
+    }, 16.67)
     ```
-    - 💡 *you also have each panel, `<tact-controllers>` and `<tact-customize>`.*
-- 🍏 **color the whole ui with css.**
+    - 💡 *maybe you'd like to stream the buffers over a network with [renraku](https://github.com/e280/renraku).*
+    - 💡 *maybe you'd like the tact deck on the clientside and the players on the serverside.*
+- 🍏 **put the `<tact-deck>` element in your html page.**
     ```html
-    <style>
-      html {
-        --tact-prime: aqua;
-        --tact-bg: black;
-      }
-    </style>
+    <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/>
 
-## 🎮 encoding, decoding, and your game logic.
+## 🎮 get down to brass tacks.
+> *for simpler apps, you can use tact's composable parts more directly.*
 
-- 🍏 **make a collector.**
+- ⚙️ **pov: your app isn't a game, no multiplayer, no gamepads.**  
     ```ts
-    import {Collector} from "@benev/tact"
+    import {setupTact, Decoder} from "@benev/tact"
+
+    const tact = await setupTact({presets, maxPlayers: 1})
+    const controller = tact.mouseKeyboard()
+    const decoder = new Decoder(bindings)
+    tact.registerElements()
+
+    setInterval(() => {
+      const inputs = decoder.decode(controller.encode())
+
+      // 🧙‍♂️ handle your inputs.
+      inputs.jump.value
 
-    const collector = new Collector(bindings)
+    }, 16.67)
     ```
-- 🍏 **now it's time for the real action!**
+    - 💡 *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.**  
     ```ts
+    import {Controller, Decoder, KeyboardSource, PointerSource, Sources} from "@benev/tact"
+
+    const source = new Sources(new KeyboardSource(), new PointerSource())
+    const controller = new Controller({bindings, source})
+    const decoder = new Decoder(bindings)
+
     setInterval(() => {
-      const buffer = tact.deck.hub.encodeAll()
-      for (const {playerId, inputs} of collector.decodeAll(buffer)) {
+      const inputs = decoder.decode(controller.encode())
 
-        // your game logic can read these handy input values.
-        inputs.jump.value // 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.
+      // 🧙‍♂️ handle your inputs.
+      inputs.jump.value
 
-        inputs.forward.value
-        inputs.look.value
-      }
     }, 16.67)
     ```
-    💡 *you could stream the buffers across the network to a remote collector.*
 
 
 
 <br/>
 
-## 🎮 get down to brass tacks.
+## 🎮 bindings.
+> *bindings are a little json programming language.*
 
-- 🍏 **use the core facilities directly,** without the ui or multiplayer.  
+- 🧬 **see [expression.ts](./s/lib/input/expression.ts) to get an idea of what's possible.**  
+- 🧬 **arbitrary nesting is valid.**
     ```ts
-    import {Controller, InputDecoder, KeyboardSource, PointerSource, Sources} from "@benev/tact"
+    asBindings("KeyW")
 
-    const controller = new Controller({
-      bindings,
-      source: new Sources(new KeyboardSource(), new PointerSource()),
+    inputs.value // 1
+    ```
+    ```ts
+    asBindings({
+      special: {
+        magic: {
+          castSpell: ["*", ["mod", "shift", "alt"], "KeyR"],
+        }
+      }
     })
 
-    const decoder = new InputDecoder(bindings)
+    inputs.special.magic.castSpell.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"],
+    })
 
-    // call this in your gameloop:
-    const inputs = decoder.decode(controller.encode())
+    inputs.lookX.sum // use sum instead of value.
+    ```
+- 🧬 **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 different gamepads represent the values differently.
+        ["remap", 0, -1, 0, 1, "gamepad.axis.1"],
+      ],
+    })
     ```
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@benev/tact",
-	"version": "0.4.0-1",
+	"version": "0.4.0-10",
 	"description": "🎮 from keypress to couch co-op",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
@@ -21,21 +21,22 @@
 		"count": "find s -path '*/_archive' -prune -o -name '*.ts' -exec wc -l {} +"
 	},
 	"peerDependencies": {
-		"@e280/sly": "^0.4.9",
-		"@e280/strata": "^0.5.6",
+		"@e280/sly": "^0.4.14",
+		"@e280/strata": "^0.5.7",
 		"lit": "^3.3.3"
 	},
 	"dependencies": {
+		"@awasm/noble": "^0.1.4",
 		"@benev/math": "0.4.0-9",
-		"@e280/kv": "^0.2.4",
+		"@e280/kv": "^0.2.6",
 		"@e280/shiny": "^0.1.1",
-		"@e280/stz": "^0.4.14"
+		"@e280/stz": "^0.4.16"
 	},
 	"devDependencies": {
 		"@e280/hottie": "^0.1.7",
 		"@e280/octo": "^0.1.7",
 		"@e280/science": "^0.1.14",
-		"@e280/scute": "^0.5.4",
+		"@e280/scute": "^0.5.5",
 		"http-server": "^14.1.1",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^7.0.2"

package/s/demo/main.css

@@ -53,6 +53,10 @@
 		background: var(--bg);
 	}
 
+	html {
+		scrollbar-gutter: stable;
+	}
+
 	body {
 		display: flex;
 		flex-direction: column;
@@ -67,10 +71,34 @@
 		}
 
 		> header {
+			display: flex;
+			flex-wrap: wrap;
+			justify-content: space-between;
+			align-items: end;
+			gap: 1em;
 			padding: 0 2em;
-			h1 small { font-size: 0.6em; font-weight: normal; }
-			* + * { margin-top: 0.5em; }
-			label { padding-left: 1em; }
+
+			h1 small {
+				font-size: 0.6em;
+				font-weight: normal;
+			}
+
+			blockquote {
+				opacity: 0.5;
+				font-style: italic;
+				padding-left: 1em;
+			}
+
+			label {
+				display: flex;
+				flex-direction: column;
+				align-items: end;
+				gap: 0.1em;
+			}
+
+			.links span {
+				opacity: 0.5;
+			}
 		}
 
 		> section {
@@ -79,6 +107,13 @@
 				padding-left: 1em;
 			}
 		}
+
+		> footer {
+			padding: 1em 2em;
+			p {
+				opacity: 0.5;
+			}
+		}
 	}
 }
 

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>
@@ -31,30 +31,36 @@ export default template(import.meta.url, async orb => html`
 		</head>
 		<body>
 			<header>
-				<h1>
-					<strong>@benev/tact</strong>
-					<small>v${orb.packageVersion()}</small>
-				</h1>
 				<div>
-					<blockquote>"from keypress to couch co-op"</blockquote>
-					<p class=links>
-						<a href="./gamepad/">gamepad visualizer</a>
-						—
-						<a href="https://github.com/benev-gg/tact">github</a>
-						—
-						<a href="https://benev.gg/">benev.gg</a>
-					</p>
-					<p>
-						<label>
-							<span>➣ choose your color:</span>
-							<input type="color"/>
-						</label>
-					</p>
+					<h1>
+						<strong>@benev/tact</strong>
+						<small>v${orb.packageVersion()}</small>
+					</h1>
+					<div>
+						<blockquote>"from keypress to couch co-op"</blockquote>
+						<p class=links>
+							<a href="./gamepad/">gamepad visualizer</a>
+							<span>—</span>
+							<a href="https://github.com/benev-gg/tact">github</a>
+							<span>—</span>
+							<a href="https://benev.gg/">benev.gg</a>
+						</p>
+					</div>
+				</div>
+				<div>
+					<label>
+						<input type="color"/>
+						<span>choose your color ☝️</span>
+					</label>
 				</div>
 			</header>
 
 			<tact-deck></tact-deck>
-			<tact-visualizer></tact-visualizer>
+
+			<footer>
+				<p>binary data visualizer</p>
+				<tact-visualizer></tact-visualizer>
+			</footer>
 		</body>
 	</html>
 `)

package/s/lib/index.ts

@@ -19,7 +19,7 @@ export * from "./ui/deck/controls/types.js"
 export * from "./ui/deck/setup/deck.js"
 export * from "./ui/deck/setup/tact.js"
 export * from "./ui/deck/auto-gamepads.js"
-export * from "./ui/deck/collector.js"
+export * from "./ui/deck/players.js"
 export * from "./ui/deck/hub.js"
 export * from "./ui/deck/types.js"
 export * from "./ui/views/customize/view.js"

package/s/lib/input/controller.ts

@@ -58,7 +58,10 @@ export class Controller<B extends Bindings = any> {
 	}
 
 	encode(time = performance.now()) {
-		return encodeIntents(this.#investigation.hash, [...this.evaluate(time)])
+		return encodeIntents(
+			this.#investigation.minihash,
+			[...this.evaluate(time)],
+		)
 	}
 
 	clear() {

package/s/lib/input/data/intent/decode.ts

@@ -8,7 +8,7 @@ export function decodeIntents(buffer: ArrayBuffer) {
 	const dv = new DataView(buffer)
 	let cursor = 0
 
-	const hash = dv.getUint32(cursor, endian)
+	const minihash = dv.getUint32(cursor, endian)
 	cursor += sizeHash
 
 	while (cursor < buffer.byteLength) {
@@ -21,6 +21,6 @@ export function decodeIntents(buffer: ArrayBuffer) {
 		intents.push({id, value})
 	}
 
-	return {hash, intents}
+	return {minihash, intents}
 }
 

package/s/lib/input/data/intent/encode.ts

@@ -3,13 +3,13 @@ import {Intent} from "./types.js"
 import {endian} from "../endian.js"
 import {sizeHash, sizeId, sizeIntent, sizeValue} from "./sizes.js"
 
-export function encodeIntents(hash: number, intents: Intent[]) {
+export function encodeIntents(minihash: number, intents: Intent[]) {
 	const byteCount = sizeHash + (intents.length * sizeIntent)
 	const buffer = new ArrayBuffer(byteCount)
 	const dv = new DataView(buffer)
 	let cursor = 0
 
-	dv.setUint32(cursor, hash, endian)
+	dv.setUint32(cursor, minihash, endian)
 	cursor += sizeHash
 
 	for (const intent of intents) {

package/s/lib/input/data/intent/minihash.ts

@@ -0,0 +1,5 @@
+
+export function minihash(hash: string) {
+	return Number.parseInt(hash.slice(0, 8), 16)
+}
+

package/s/lib/input/decoder.ts

@@ -3,7 +3,7 @@ import {Inputs, Bindings} from "./types.js"
 import {decodeIntents} from "./data/intent/decode.js"
 import {investigate} from "./investigate/investigate.js"
 
-export class InputDecoder<B extends Bindings> {
+export class Decoder<B extends Bindings> {
 	#investigation
 
 	constructor(bindings: B) {
@@ -25,7 +25,7 @@ export class InputDecoder<B extends Bindings> {
 		for (const buffer of buffers) {
 			const decoded = decodeIntents(buffer)
 
-			if (decoded.hash !== this.#investigation.hash)
+			if (decoded.minihash !== this.#investigation.minihash)
 				throw new Error("intent bindings hash mismatch")
 
 			for (const input of inputs)

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/investigate/hash-bindings.ts

@@ -1,6 +1,7 @@
 
-import {hash32} from "@e280/stz"
+import {hex} from "@e280/stz"
 import {Bindings} from "../types.js"
+import {hash} from "../../utils/hash.js"
 import {isExpression} from "./is-expression.js"
 
 export function hashBindings(bindings: Bindings) {
@@ -8,7 +9,7 @@ export function hashBindings(bindings: Bindings) {
 
 	function recurse(b: Bindings, path: string[]) {
 		if (isExpression(b)) {
-			paths.push(path.join("."))
+			paths.push(JSON.stringify(path))
 		}
 		else {
 			for (const [key, value] of Object.entries(b))
@@ -17,6 +18,7 @@ export function hashBindings(bindings: Bindings) {
 	}
 
 	recurse(bindings, ["b"])
-	return hash32(...paths)
+	paths.sort()
+	return hex(hash("tact/bindings/v1", ...paths).slice(16))
 }
 

package/s/lib/input/investigate/investigate.ts

@@ -5,31 +5,46 @@ import {Expression} from "../expression.js"
 import {hashBindings} from "./hash-bindings.js"
 import {isExpression} from "./is-expression.js"
 import {Bindings, Input, Inputs} from "../types.js"
+import {minihash} from "../data/intent/minihash.js"
 
 export function investigate<B extends Bindings>(bindings: B) {
 	const hash = hashBindings(bindings)
-	const inputList: Input[] = []
-	const rootList: Expression[] = []
 
-	function makeInputs(b: Bindings): unknown {
+	const leaves: {
+		path: string
+		input: Input
+		expression: Expression
+	}[] = []
+
+	function makeInputs(b: Bindings, path: string[]): unknown {
 		if (isExpression(b)) {
 			const input = makeInput()
-			inputList.push(input)
-			rootList.push(b)
+			leaves.push({
+				path: JSON.stringify(path),
+				input,
+				expression: b,
+			})
 			return input
 		}
 		else {
-			return obmap(b, makeInputs)
+			return obmap(b, (value, key) =>
+				makeInputs(value, [...path, key as string])
+			)
 		}
 	}
 
-	const inputs = makeInputs(bindings) as Inputs<B>
+	const inputs = makeInputs(bindings, ["b"]) as Inputs<B>
+
+	leaves.sort((a, b) =>
+		a.path < b.path ? -1 : a.path > b.path ? 1 : 0
+	)
 
 	return {
 		hash,
+		minihash: minihash(hash),
 		inputs,
-		inputList,
-		rootList,
+		inputList: leaves.map(l => l.input),
+		rootList: leaves.map(l => l.expression),
 	}
 }