@benev/tact 0.4.0-0 → 0.4.0-10

package/README.md

@@ -2,104 +2,216 @@
 # 🎮 @benev/tact
 > *from keypress to couch co-op.*
 
-**tact is a tiny input toolkit for web games.**  
-keyboards, mice, gamepads. expressive bindings json dsl.  
-binary messages for efficient networking and web worker multithreading.  
+### tact is a user-input toolkit for web games.
 
-```ts
-npm install @benev/tact@next
-```
+🌐 👉 ***https://tact.benev.gg/*** 👈 *try now*  
+🖱 keyboards, mice, gamepads.  
+🔥 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)
+
+![](https://i.imgur.com/IBW5Kkd.png)
 
 
 
 <br/>
 
-## 🕹️ sources emit samples.
+## 🎮 let's play.
+> *here's the fully-featured, batteries-included, ready-for-anything web game starter pack.*
 
-- **samples look like** `{code: "KeyW", value: 1}`
+- 🍏 **install tact into your typescript project.**
+    ```sh
+    npm install @benev/tact@next
+    ```
+- 🍏 **establish your app's standard bindings.**
+    ```ts
+    import {asBindings} from "@benev/tact"
+
+    const bindings = asBindings({
+      jump: "Space",
+      forward: "KeyW",
+      look: ["accumulate", "pointer.x"],
+    })
+    ```
+- 🍏 **let's have two presets available to the user, with one for gamepads.**
+    ```ts
+    import {asPresets} from "@benev/tact"
+
+    const presets = asPresets<typeof bindings>({
+      standard: {label: "⌨️standard", bindings},
+      gamepad: {label: "🎮gamer", bindings: {
+        jump: "gamepad.1",
+        forward: ["remap", 0, -1, 0, 1, "gamepad.axis.2"],
+        look: ["*", ["dt"], "gamepad.axis.3", 100],
+      }},
+    })
+    ```
+- ⚙️ **setup tact.**
     ```ts
-    import {Sources, KeyboardSource, PointerSource} from "@benev/tact"
+    import {setupTact} from "@benev/tact"
+
+    const tact = await setupTact({presets, maxPlayers: 4})
+    tact.mouseKeyboard()
+    tact.gamepads("gamepad")
+    tact.registerElements()
     ```
+    - 💡 *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
-    const source = new Sources(
-      new KeyboardSource(),
-      new PointerSource(),
-    )
+    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)
+    ```
+    - 💡 *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
+    <tact-deck></tact-deck>
     ```
-    - proper sources: [GamepadSource](./s/lib/input/sources/gamepad.ts), [KeyboardSource](./s/lib/input/sources/keyboard.ts), [PointerSource](./s/lib/input/sources/pointer.ts), [StickSource](./s/lib/input/sources/stick.ts).
-    - utility sources: [Sources](./s/lib/input/sources/sources.ts) *(consolidates sources)*, [PlainSource](./s/lib/input/sources/plain.ts) *(handy base class)*.
+    - 💡 *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/>
 
-## 🕹️ bindings describe controls.
+## 🎮 get down to brass tacks.
+> *for simpler apps, you can use tact's composable parts more directly.*
 
-- **bindings are tiny programs,** a dsl in js data.
+- ⚙️ **pov: your app isn't a game, no multiplayer, no gamepads.**  
     ```ts
-    import {asBindings} 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
+
+    }, 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.**  
     ```ts
-    const bindings = asBindings({
-      forward: ["max", "KeyW", "ArrowUp"],
-      jump: ["down", "Space"],
-      look: ["accumulate", ["sum", "pointer.x"]],
-    })
+    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 inputs = decoder.decode(controller.encode())
+
+      // 🧙‍♂️ handle your inputs.
+      inputs.jump.value
+
+    }, 16.67)
     ```
-    - see [expression.ts](./s/lib/input/expression.ts) to learn what's possible.
 
 
 
 <br/>
 
-## 🕹️ encode and decode.
+## 🎮 bindings.
+> *bindings are a little json programming language.*
 
-- **the data is binary for efficient networking.**
+- 🧬 **see [expression.ts](./s/lib/input/expression.ts) to get an idea of what's possible.**  
+- 🧬 **arbitrary nesting is valid.**
     ```ts
-    import {InputEncoder, InputDecoder} from "@benev/tact"
+    asBindings("KeyW")
+
+    inputs.value // 1
     ```
     ```ts
-    const encoder = new InputEncoder(source, bindings)
-    const decoder = new InputDecoder(bindings)
+    asBindings({
+      special: {
+        magic: {
+          castSpell: ["*", ["mod", "shift", "alt"], "KeyR"],
+        }
+      }
+    })
+
+    inputs.special.magic.castSpell.value // 1
     ```
+- 🧬 **you can differentiate taps versus holds on the same key.**
     ```ts
-    function frame() {
-
-      // data is an ArrayBuffer (you could stream it over the network).
-      const data = encoder.encode()
-
-      // decoding interprets the data as handy input objects.
-      const inputs = decoder.decode(data)
+    asBindings({
 
-      // your game logic can read these handy input values.
-      inputs.forward.value // current held state.
-      inputs.jump.value // down-presses this frame.
-      inputs.look.value // total accumulated mouse movement.
+      // tapping E yoinks a weapon into your inventory.
+      grab: ["taps", 1, 250, "KeyE"],
 
-      // this was so cool, let's do this forever.
-      requestAnimationFrame(frame)
-    }
+      // 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"],
+    })
 
-    requestAnimationFrame(frame)
+    inputs.lookX.sum // use sum instead of value.
     ```
-- **understanding networking situations.**
-  - the encoder could be on your clientside.
-  - the decoder could be on your serverside.
-  - thus, clients are streaming their input data to the serverside, which is decoding it and using it in game logic.
-  - don't worry, it's not a keylogger -- the encoded data is more like `jump: 1`, `look: 5`, etc.
-  - the decoder can accept multiple data packets at once, `decoder.decode(...datas)`.
-- **understanding multithreaded worker situations.**
-  - the encoder would be on the main thread, where javascript events are accessible.
-  - you can then send the encoded input data to the thread where you're simulating the game.
-  - you can have multiple encoders -- one encoder sending data to a worker thread -- another encoder sending data to the serverside.
-- **update the encoder's bindings anytime.**
+- 🧬 **gamepads thumbstick inputs are best done with some math.**
     ```ts
-    // the new bindings must be schema-compatible or an error is thrown.
-    encoder.bindings = {
-      forward: "KeyE",
-      jump: "Space",
-      look: "gamepad.axis.2"
-    }
+    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,7 +1,7 @@
 {
 	"name": "@benev/tact",
-	"version": "0.4.0-0",
-	"description": "🎮 keybindings and couch co-op",
+	"version": "0.4.0-10",
+	"description": "🎮 from keypress to couch co-op",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
 	"type": "module",
@@ -21,20 +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/stz": "^0.4.11"
+		"@e280/kv": "^0.2.6",
+		"@e280/shiny": "^0.1.1",
+		"@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.3",
+		"@e280/scute": "^0.5.5",
 		"http-server": "^14.1.1",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^7.0.2"

package/s/demo/main.bundle.ts

@@ -1,8 +1,23 @@
 
 import {dom} from "@e280/sly"
-import {setupDemoApp} from "./demo-app/element.js"
+import {cycle, nap} from "@e280/stz"
+import {presets} from "./presets.js"
+import {setupTact} from "../lib/ui/deck/setup/tact.js"
 
-dom.register({
-	DemoApp: setupDemoApp(),
+const tact = await setupTact({presets, maxPlayers: 4})
+tact.mouseKeyboard()
+tact.gamepads("gamer")
+tact.registerElements()
+
+cycle(async() => {
+	const data = tact.deck.hub.encodeAll()
+	tact.visualizer.update(data)
+	await nap(1000 / 60)
 })
 
+{
+	const input = dom<HTMLInputElement>('input[type="color"]')
+	input.value = "#ffbb00"
+	input.oninput = () => document.body.style.setProperty("--tact-prime", input.value)
+}
+

package/s/demo/main.css

@@ -53,23 +53,52 @@
 		background: var(--bg);
 	}
 
+	html {
+		scrollbar-gutter: stable;
+	}
+
 	body {
 		display: flex;
 		flex-direction: column;
 		align-items: center;
 
 		gap: 1em;
-		padding: 2em;
+		padding: 0.5em;
+		padding-bottom: 8em;
 
 		> * {
-			width: 100%;
-			max-width: 42em;
+			width: min(100%, 50em);
 		}
 
 		> 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; }
+
+			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 {
@@ -78,6 +107,13 @@
 				padding-left: 1em;
 			}
 		}
+
+		> footer {
+			padding: 1em 2em;
+			p {
+				opacity: 0.5;
+			}
+		}
 	}
 }
 

package/s/demo/presets.ts

@@ -0,0 +1,54 @@
+
+import {asBindings} from "../lib/input/types.js"
+import {asPresets} from "../lib/ui/deck/types.js"
+
+export const bindings = asBindings({
+	looking: {
+		horizontal: ["accumulate", "pointer.x"],
+		vertical: ["accumulate", "pointer.y"],
+	},
+	moving: {
+		forward: "KeyW",
+		backward: "KeyS",
+		leftward: "KeyA",
+		rightward: "KeyD",
+	},
+	interactions: {
+		use: "KeyE",
+	},
+})
+
+export const presets = asPresets<typeof bindings>({
+	standard: {label: "⌨️standard", bindings},
+	gamer: {label: "🎮gamer", bindings: {
+		looking: {
+			horizontal: ["*", ["dt"], "gamepad.axis.3", 100],
+			vertical: ["*", ["dt"], "gamepad.axis.4", 100],
+		},
+		moving: {
+			forward: ["remap", 0, -1, 0, 1, "gamepad.axis.2"],
+			backward: ["remap", 0, 1, 0, 1, "gamepad.axis.2"],
+			leftward: ["remap", 0, -1, 0, 1, "gamepad.axis.1"],
+			rightward: ["remap", 0, 1, 0, 1, "gamepad.axis.1"],
+		},
+		interactions: {
+			use: "gamepad.1",
+		},
+	}},
+	micro: {label: "🦠micro", bindings: {
+		looking: {
+			horizontal: ["*", ["dt"], ["+", "gamepad.1", ["-", "gamepad.4"]], 100],
+			vertical: ["*", ["dt"], ["+", "gamepad.2", ["-", "gamepad.3"]], 100],
+		},
+		moving: {
+			forward: ["remap", 0, -1, 0, 1, "gamepad.axis.2"],
+			backward: ["remap", 0, 1, 0, 1, "gamepad.axis.2"],
+			leftward: ["remap", 0, -1, 0, 1, "gamepad.axis.1"],
+			rightward: ["remap", 0, 1, 0, 1, "gamepad.axis.1"],
+		},
+		interactions: {
+			use: ["*", "gamepad.5", "gamepad.6"],
+		},
+	}},
+})
+

package/s/gamepad/gamepad-app/element.ts

@@ -35,12 +35,15 @@ export const GamepadApp = shadowElement(() => {
 	}))
 
 	const renderSample = ([code, value]: [string, number]) => html`
-		<li style="${`--percent: ${value * 100}%;`}">
+		<li ?data-neg="${value < 0}" style="${`--percent: ${Math.abs(value) * 100}%;`}">
 			<span>${code}</span>
 			<span>${value.toFixed(3)}</span>
 		</li>
 	`
 
+	const sortSamples = (a: [string, number], b: [string, number]) =>
+		a[0].localeCompare(b[0])
+
 	return html`
 		<div class=plate>
 			${connected.size > 0 ? [...connected].map(({samples, source: {gamepad}}) => html`
@@ -49,14 +52,18 @@ export const GamepadApp = shadowElement(() => {
 					<div class=stats>
 						<span>index ${gamepad.index}</span>
 						<span>connected ${gamepad.connected ? "yes" : "no"}</span>
-						<span>mapping ${gamepad.mapping}</span>
+						<span>mapping "${gamepad.mapping}"</span>
 						<span>vibrationActuator ${gamepad.vibrationActuator ? "yes" : "no"}</span>
 					</div>
 					<ul>
-						${[...samples].filter(([code]) => code.startsWith("gamepad.button")).map(renderSample)}
+						${[...samples]
+							.sort(sortSamples)
+							.filter(([code]) => !code.startsWith("gamepad.axis")).map(renderSample)}
 					</ul>
 					<ul>
-						${[...samples].filter(([code]) => code.startsWith("gamepad.axis")).map(renderSample)}
+						${[...samples]
+							.sort(sortSamples)
+							.filter(([code]) => code.startsWith("gamepad.axis")).map(renderSample)}
 					</ul>
 				</div>
 			`) : html`

package/s/gamepad/gamepad-app/style.css.ts

@@ -57,10 +57,14 @@ export default css`
 				display: block;
 				content: "";
 				inset: 0;
-				background: #f004;
+				background: #08f4;
 				width: var(--percent);
 			}
 
+			&[data-neg]::before {
+				background: #f004;
+			}
+
 			> span {
 				position: relative;
 				z-index: 2;

package/s/gamepad/index.html.ts

@@ -15,7 +15,7 @@ export default template(import.meta.url, async orb => html`
 			<meta charset="utf-8"/>
 			<meta name="viewport" content="width=device-width,initial-scale=1"/>
 			<meta name="darkreader-lock"/>
-			<style>@layer base{html{background:#000}}</style>
+			<style>@layer base{html{background:#111}}</style>
 
 			<link rel="icon" href="${dataSvgEmoji("🎮")}"/>
 			<link rel="stylesheet" href="${orb.hashurl("main.css")}"/>

package/s/gamepad/main.css

@@ -54,7 +54,16 @@
 	}
 
 	body {
-		padding: 1em;
+		display: flex;
+		flex-direction: column;
+		align-items: center;
+
+		gap: 1em;
+		padding: 0.5em;
+
+		> * {
+			width: min(100%, 50em);
+		}
 	}
 }
 

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>
@@ -15,7 +15,7 @@ export default template(import.meta.url, async orb => html`
 			<meta charset="utf-8"/>
 			<meta name="viewport" content="width=device-width,initial-scale=1"/>
 			<meta name="darkreader-lock"/>
-			<style>@layer base{html{background:#000}}</style>
+			<style>@layer base{html{background:#111}}</style>
 
 			<link rel="icon" href="${dataSvgEmoji("🎮")}"/>
 			<link rel="stylesheet" href="${orb.hashurl("demo/main.css")}"/>
@@ -31,23 +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>
-						<a href="./gamepad/">gamepad visualizer</a>.
-					</p>
-					<p>
-						<a href="https://github.com/benev-gg/tact">github</a>.
-						<a href="https://benev.gg/">benev.gg</a>.
-					</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>
 
-			<demo-app></demo-app>
+			<tact-deck></tact-deck>
+
+			<footer>
+				<p>binary data visualizer</p>
+				<tact-visualizer></tact-visualizer>
+			</footer>
 		</body>
 	</html>
 `)

package/s/lib/index.ts

@@ -1,18 +1,29 @@
 
 export * from "./input/investigate/is-compatible.js"
-
 export * from "./input/sources/gamepad.js"
 export * from "./input/sources/keyboard.js"
 export * from "./input/sources/plain.js"
 export * from "./input/sources/pointer.js"
 export * from "./input/sources/sources.js"
 export * from "./input/sources/stick.js"
-
 export * from "./input/utils/pad/on-pad.js"
 export * from "./input/utils/pad/pad.js"
 export * from "./input/utils/is-down.js"
-
-export * from "./input/encoder.js"
+export * from "./input/controller.js"
 export * from "./input/decoder.js"
+export * from "./input/expression.js"
 export * from "./input/types.js"
 
+export * from "./ui/deck/controls/controls.js"
+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/players.js"
+export * from "./ui/deck/hub.js"
+export * from "./ui/deck/types.js"
+export * from "./ui/views/customize/view.js"
+export * from "./ui/views/deck/view.js"
+export * from "./ui/views/controllers/view.js"
+export * from "./ui/views/visualizer/view.js"
+