@benev/tact 0.3.0-5 → 0.4.0-0

package/README.md

@@ -1,93 +1,112 @@
 
 # 🎮 @benev/tact
-> *from keypress to couch co-op*
+> *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.  
 
 ```ts
-npm install @benev/tact
+npm install @benev/tact@next
 ```
 
-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.  
-
 
 
 <br/>
 
-## 🎮 tact basics
+## 🕹️ sources emit samples.
 
-```ts
-import {
-  Devices, KeyboardDevice, PointerDevice,
-  makeIntentsResolver, makeActionsResolver,
-} from "@benev/tact"
-```
-
-1. **setup your game's keybindings**
+- **samples look like** `{code: "KeyW", value: 1}`
     ```ts
-    const bindings = {
-      running: {forward: "KeyW", jump: ["and", "ShiftLeft", "Space"]},
-      gunning: {shoot: ["or", "pointer.button.left", "gamepad.trigger.right"]},
-    }
+    import {Sources, KeyboardSource, PointerSource} from "@benev/tact"
     ```
-1. **create your devices (which provide raw input samples)**
     ```ts
-    const devices = new Devices(
-      new KeyboardDevice(),
-      new PointerDevice(),
+    const source = new Sources(
+      new KeyboardSource(),
+      new PointerSource(),
     )
     ```
-1. **make your resolvers**
-    ```ts
-    const resolveIntents = makeIntentsResolver(bindings)
-    const resolveActions = makeActionsResolver(bindings)
-    ```
-1. **run your resolvers, read your actions**
-    ```ts
-    import {cycle} from "@e280/stz"
+    - 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)*.
+
 
-    cycle(function myGameTick() {
 
-      // 🧙‍♂️ samples get resolved into compact intent tuples, good for networking.
-      const intents = resolveIntents(Date.now(), devices.samples())
+<br/>
 
-      // 🧙‍♂️ actions are your ergonomic accessors for values.
-      const actions = resolveActions(intents)
+## 🕹️ bindings describe controls.
 
-      // 🧙‍♂️ okay, now check your actions.
-      actions.running.forward.value // 1.0
-      actions.running.forward.pressed // true
+- **bindings are tiny programs,** a dsl in js data.
+    ```ts
+    import {asBindings} from "@benev/tact"
+    ```
+    ```ts
+    const bindings = asBindings({
+      forward: ["max", "KeyW", "ArrowUp"],
+      jump: ["down", "Space"],
+      look: ["accumulate", ["sum", "pointer.x"]],
     })
     ```
+    - see [expression.ts](./s/lib/input/expression.ts) to learn what's possible.
+
 
-### 🧙‍♂️ wizardly tips
 
-1. **for networking, you should encode intents as Uint8Array for better efficiency down the wire.**
+<br/>
+
+## 🕹️ encode and decode.
+
+- **the data is binary for efficient networking.**
+    ```ts
+    import {InputEncoder, InputDecoder} from "@benev/tact"
+    ```
     ```ts
-    import {encodeIntents, decodeIntents} from "@benev/tact"
+    const encoder = new InputEncoder(source, bindings)
+    const decoder = new InputDecoder(bindings)
+    ```
+    ```ts
+    function frame() {
 
-    const intents = [[1, 0.7853981633974483]]
+      // data is an ArrayBuffer (you could stream it over the network).
+      const data = encoder.encode()
 
-    console.log(JSON.stringify(intents).length)
-      // 22 — yikes
+      // decoding interprets the data as handy input objects.
+      const inputs = decoder.decode(data)
 
-    const bytes = encodeIntents(intents)
+      // 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.
 
-    console.log(bytes.length)
-      // 6 — noice
+      // this was so cool, let's do this forever.
+      requestAnimationFrame(frame)
+    }
 
-    const intents = decodeIntents(bytes)
+    requestAnimationFrame(frame)
     ```
-1. **you can normalize bindings**
+- **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.**
     ```ts
-    import {normalizeBindings} from "@benev/tact"
-
-    const bindings = normalizeBindings(appBindings, susBindings)
+    // the new bindings must be schema-compatible or an error is thrown.
+    encoder.bindings = {
+      forward: "KeyE",
+      jump: "Space",
+      look: "gamepad.axis.2"
+    }
     ```
-    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/>
 
+---
+
 👼 *https://benev.gg/*
 

package/package.json

@@ -1,15 +1,14 @@
 {
 	"name": "@benev/tact",
-	"version": "0.3.0-5",
+	"version": "0.4.0-0",
 	"description": "🎮 keybindings and couch co-op",
 	"license": "MIT",
 	"author": "Chase Moskal <chasemoskal@gmail.com>",
 	"type": "module",
-	"main": "./x/index.js",
+	"main": "./x/lib/index.js",
 	"sideEffects": false,
 	"exports": {
-		".": "./x/index.js",
-		"./ui": "./x/index-ui.js"
+		".": "./x/lib/index.js"
 	},
 	"files": [
 		"x",
@@ -17,29 +16,32 @@
 	],
 	"scripts": {
 		"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",
+		"dev": "octo 'scute -vw' 'tsc -w' 'node --watch x/lib/test.js' 'hottie x --port=8081'",
+		"test": "node x/lib/test.js",
 		"count": "find s -path '*/_archive' -prune -o -name '*.ts' -exec wc -l {} +"
 	},
 	"peerDependencies": {
-		"@e280/sly": "^0.4.8",
-		"@e280/strata": "^0.5.2",
+		"@e280/sly": "^0.4.9",
+		"@e280/strata": "^0.5.6",
 		"lit": "^3.3.3"
 	},
 	"dependencies": {
-		"@benev/math": "^0.4.0-8",
-		"@e280/kv": "^0.2.1",
-		"@e280/stz": "^0.4.2"
+		"@benev/math": "0.4.0-9",
+		"@e280/kv": "^0.2.4",
+		"@e280/stz": "^0.4.11"
 	},
 	"devDependencies": {
-		"@e280/hottie": "^0.1.5",
-		"@e280/octo": "^0.1.5",
-		"@e280/science": "^0.1.12",
-		"@e280/scute": "^0.5.2",
+		"@e280/hottie": "^0.1.7",
+		"@e280/octo": "^0.1.7",
+		"@e280/science": "^0.1.14",
+		"@e280/scute": "^0.5.3",
 		"http-server": "^14.1.1",
 		"npm-run-all": "^4.1.5",
 		"typescript": "^7.0.2"
 	},
+	"allowScripts": {
+		"esbuild@0.28.2": true
+	},
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/benev-gg/tact.git"
@@ -53,9 +55,5 @@
 		"keybinds",
 		"keybindings",
 		"gamepad"
-	],
-	"allowScripts": {
-		"classic-level@3.0.0": true,
-		"esbuild@0.28.2": true
-	}
+	]
 }

package/s/_archive/deck/deck.ts

@@ -1,69 +1,92 @@
 
-import {Kv} from "@e280/kv"
-import {disposer, range} from "@e280/stz"
-
-import {Db} from "./parts/db.js"
-import {Hub} from "../core/hub/hub.js"
-import {Port} from "../core/hub/port.js"
-import {Bindings} from "../core/bindings/types.js"
-import {mergeBindings} from "./parts/merge-bindings.js"
-import {MetaBindings, metaMode} from "../core/hub/types.js"
-import {makeMetaBindings} from "../core/hub/meta-bindings.js"
-import {DeviceSkins} from "./parts/device-skins/device-skin.js"
-import {OverlayVisibility} from "./parts/overlay-visibility.js"
-import {PrimaryDevice} from "../core/devices/standard/primary.js"
-
-export type DeckOptions<B extends Bindings, MB extends MetaBindings = any> = {
-	kv: Kv
-	bindings: B
-	portCount: number
-	metaBindings?: MB
-}
+import {Cubby, debounce, guarantee} from "@e280/stz"
+import {Port} from "./port.js"
+import {Device} from "../core/types.js"
+import {Runtime} from "./parts/runtime.js"
+import {Controller} from "./controller.js"
+import {Profiles} from "./parts/profiles.js"
+import {Settings} from "./parts/settings.js"
+import {DeckState, Profile, ProfileKey} from "./types.js"
+
+export class Deck<StockProfileKey extends ProfileKey = ProfileKey> {
+	profiles
+	settings
+	#runtime = new Runtime()
+
+	constructor(options: {
+			store: Cubby<DeckState>
+			stockProfiles: Record<StockProfileKey, Profile>
+		}) {
+		this.settings = new Settings(options.store)
+		this.profiles = new Profiles(options.stockProfiles, this.settings.customProfiles)
+	}
 
-export class Deck<B extends Bindings, MB extends MetaBindings = any> {
-	static async load<B extends Bindings, MB extends MetaBindings = any>(options: DeckOptions<B, MB>) {
-		const db = await Db.load(options.kv.store("catalog"))
+	async load() {
+		await this.settings.load()
+		for (const controller of this.#runtime.controllers.keys())
+			this.#applyControllerProfile(controller)
+	}
 
-		const ports = range(options.portCount)
-			.map(index => db.$catalog().getProfileForPort(index))
-			.map(profile => mergeBindings(options.bindings, profile?.bindings))
-			.map(bindings => new Port<B>(bindings as B))
+	#save = debounce(100, () => this.settings.save())
 
-		const hub = new Hub<B>(
-			ports,
-			db.$catalog().metaBindings
-				?? options.metaBindings
-				?? makeMetaBindings(),
-		)
+	get ports() {
+		return [...this.#runtime.ports]
+	}
 
-		return new this(options.bindings, options.metaBindings, hub, db)
+	get controllers() {
+		return [...this.#runtime.controllers]
 	}
 
-	dispose = disposer()
-	deviceSkins = new DeviceSkins()
-	primaryDevice = new PrimaryDevice()
-	overlayVisibility: OverlayVisibility
+	get unassignedControllers() {
+		return [...this.#runtime.controllers]
+			.filter(controller => !this.#runtime.portAssignments.get(controller))
+	}
 
-	constructor(
-			public baseBindings: B,
-			public baseMetaBindings: MB,
-			public hub: Hub<B, MB>,
-			public db: Db,
+	createPort() {
+		const port = new Port(this.#runtime)
+		this.#runtime.ports.add(port)
+		return port
+	}
+
+	deletePort(port: Port) {
+		for (const controller of port.controllers)
+			port.unplug(controller)
+		this.#runtime.ports.delete(port)
+	}
+
+	createController<D extends Device = Device>(
+			handle: string,
+			stockProfileKey: StockProfileKey,
+			device: D,
 		) {
+		const profileKey = guarantee(this.settings.profileAssignments, handle, () => stockProfileKey)
+		const profile = this.profiles.get(profileKey)
+		const controller = new Controller(handle, profile.bindings, device)
+		this.#runtime.controllers.add(controller)
+		return controller
+	}
 
-		this.overlayVisibility = new OverlayVisibility(hub, this.deviceSkins)
+	deleteController(controller: Controller) {
+		this.#runtime.controllers.delete(controller)
+		this.#runtime.portAssignments.delete(controller)
+	}
+
+	async assignControllerProfile(controller: Controller, profileKey: StockProfileKey | ProfileKey) {
+		this.settings.profileAssignments.set(controller.handle, profileKey)
+		this.#applyControllerProfile(controller)
+		await this.#save()
+	}
 
-		// meta reveal overlay
-		this.dispose.schedule(
-			hub.metaPort.actions[metaMode].revealOverlay.on(action => {
-				if (action.pressed)
-					this.overlayVisibility.bump()
-			})
-		)
+	queryController(controller: Controller) {
+		const port = this.#runtime.portAssignments.get(controller)
+		const profileKey = this.settings.profileAssignments.get(controller.handle)
+		const profile = this.profiles.get(profileKey)
+		return {controller, port, profileKey, profile}
 	}
 
-	get catalog() {
-		return this.db.$catalog()
+	#applyControllerProfile(controller: Controller) {
+		const profileKey = this.settings.profileAssignments.get(controller.handle)
+		controller.bindings = this.profiles.get(profileKey).bindings
 	}
 }
 

package/s/_archive/demo/demo-app/element.ts

@@ -0,0 +1,17 @@
+
+import {html} from "lit"
+import {shadowElement, useCss} from "@e280/sly"
+import styleCss from "./style.css.js"
+import {Deck} from "../../deck/deck.js"
+import {DeskOptions, DeskView} from "../../ui/views/desk/view.js"
+
+export const setupDemoApp = (deck: Deck, options: DeskOptions = {}) => shadowElement(() => {
+	useCss(styleCss)
+
+	return html`
+		<div class=plate>
+			${DeskView(deck, options)}
+		</div>
+	`
+})
+

package/s/_archive/{deck/views/bindings → demo/demo-app}/style.css.ts

@@ -2,5 +2,9 @@
 import {css} from "lit"
 export default css`
 
+.plate {
+	background: black;
+}
+
 `
 

package/s/_archive/demo/main.bundle.ts

@@ -1,10 +1,71 @@
 
-import {dom} from "@e280/sly"
-import {Game} from "./game/game.js"
-import {DemoTheater} from "./ui/theater/view.js"
+import {Content, dom} from "@e280/sly"
+import {LocalStore} from "@e280/strata"
 
-const game = await Game.load()
+import {Deck} from "../deck/deck.js"
+import {DeckState} from "../deck/types.js"
+import {asBindings} from "../core/types.js"
+import {Devices} from "../device/devices.js"
+import {onPad} from "../device/pad/on-pad.js"
+import {Controller} from "../deck/controller.js"
+import {PointerDevice} from "../device/pointer.js"
+import {GamepadDevice} from "../device/gamepad.js"
+import {setupDemoApp} from "./demo-app/element.js"
+import {KeyboardDevice} from "../device/keyboard.js"
 
-dom.render(dom("#demo-theater"), DemoTheater(game))
+const bindings = asBindings({
+	play: {
+		action: ["or", "Space", "pointer.button.left", "gamepad.button.1"],
+		up: ["or", "KeyW", "gamepad.axis.2.pos"],
+		down: ["or", "KeyS", "gamepad.axis.2.neg"],
+		left: ["or", "KeyA", "gamepad.axis.1.pos"],
+		right: ["or", "KeyD", "gamepad.axis.1.neg"],
+	},
+})
+
+const store = new LocalStore<DeckState>("tactDeck")
+
+const deck = new Deck({
+	store,
+	stockProfiles: {
+		standard: {label: "📜standard", bindings},
+		micro: {label: "🦠micro", bindings: asBindings<typeof bindings>({
+			play: {
+				action: ["or", "Space", "pointer.button.left", "gamepad.button.1"],
+				up: ["or", "KeyW", "gamepad.axis.2.pos"],
+				down: ["or", "KeyS", "gamepad.axis.2.neg"],
+				left: ["or", "KeyA", "gamepad.axis.1.pos"],
+				right: ["or", "KeyD", "gamepad.axis.1.neg"],
+			},
+		})},
+	},
+})
+
+await deck.load()
+store.onStorageEvent(() => deck.load())
+
+const port = deck.createPort()
+const controller = deck.createController("primary", "standard", new Devices(
+	new KeyboardDevice(),
+	new PointerDevice(),
+))
+
+port.plug(controller)
+
+const labels = new Map<Controller, Content>()
+	.set(controller, "⌨️🖱keyboard+mouse")
+
+onPad(pad => {
+	const handle = `(${pad.gamepad.index + 1}) ${pad.gamepad.id}`
+	const controller = deck.createController(handle, "standard", new GamepadDevice(pad))
+	labels.set(controller, `🎮${handle}`)
+	port.plug(controller)
+	return () => deck.deleteController(controller)
+})
+
+dom.register({
+	DemoApp: setupDemoApp(deck, {
+		getControllerLabel: labels.get.bind(labels),
+	}),
+})
 
-console.log("🎮 tact")

package/s/_archive/demo/main.css

@@ -1,13 +1,13 @@
 
-@layer vars, core, basics, page;
+@layer vars, core, page;
 
 @layer vars {
 	:root {
 		color-scheme: dark;
+
 		--link: cyan;
-		--prime: #ccc;
+		--text: #ccc;
 		--bg: #181818;
-		--bg2: #111111;
 	}
 }
 
@@ -42,19 +42,17 @@
 	}
 }
 
-@layer basics {
+@layer page {
 	html { height: 100%; }
 	body { min-height: 100%; }
 
 	html, body {
 		font-family: sans-serif;
-		font-size: 12px;
-		color: var(--prime);
+		font-size: 16px;
+		color: var(--text);
 		background: var(--bg);
 	}
-}
 
-@layer page {
 	body {
 		display: flex;
 		flex-direction: column;

package/s/_archive/lib/bindings/resolver.ts

@@ -0,0 +1,61 @@
+
+import {deep} from "@e280/stz"
+import {Sample} from "../sampling/types.js"
+import {IntentResolver} from "./utils/intent-resolver.js"
+import {ActionResolver} from "./utils/action-resolver.js"
+import {investigateBindings} from "./utils/investigate.js"
+import {Actions, Bindings, Rebindings, Intent} from "./types.js"
+
+export class Resolver<B extends Bindings> {
+	#bindings
+	#hash
+	#actionlist
+	#expressionlist
+
+	#intentResolver = new IntentResolver()
+	#actionResolver = new ActionResolver()
+
+	readonly actions
+
+	constructor(bindings: B) {
+		const investigation = investigateBindings(bindings)
+		this.#bindings = deep.freeze(bindings) as any as Rebindings<B>
+		this.#hash = investigation.hash
+		this.actions = investigation.actions
+		this.#actionlist = investigation.actionlist
+		this.#expressionlist = investigation.expressionlist
+	}
+
+	get bindings() {
+		return this.#bindings
+	}
+
+	set bindings(bindings: Rebindings<B>) {
+		const investigation = investigateBindings(bindings)
+
+		if (investigation.hash !== this.#hash)
+			throw new Error("newly set bindings are not compatible, hash mismatch")
+
+		this.#bindings = deep.freeze(bindings)
+		this.#expressionlist = investigation.expressionlist
+	}
+
+	resolveIntent(samples: Sample[], now = performance.now()): Intent {
+		return this.#intentResolver.resolve(
+			this.#hash,
+			this.#expressionlist,
+			samples,
+			now,
+		)
+	}
+
+	resolveActions(intent: Intent): Actions<B> {
+		this.#actionResolver.resolve(
+			this.#hash,
+			this.#actionlist,
+			intent,
+		)
+		return this.actions
+	}
+}
+

package/s/_archive/lib/bindings/types.ts

@@ -0,0 +1,67 @@
+
+export type Intent = ArrayBuffer
+
+/** schema and dsl for controls and keybinds. */
+export type Bindings = Expression | {
+	[key: string]: Bindings
+}
+
+export type Rebindings<B extends Bindings> = (
+	B extends Expression
+		? Expression
+		: B extends {[key: string]: Bindings}
+			? {[K in keyof B]: Rebindings<B[K]>}
+			: never
+)
+
+export type Expression = (
+	| string // a code like "KeyW", "pointer.move.up"
+	| number // constants for doing math
+
+	// combiners
+	| ["min", ...Expression[]]
+	| ["max", ...Expression[]]
+	| ["+", ...(Expression | number)[]]
+	| ["*", ...(Expression | number)[]]
+
+	// comparisons
+	| ["==", Expression, Expression]
+	| ["!=", Expression, Expression]
+	| [">", Expression, Expression]
+	| ["<", Expression, Expression]
+	| [">=", Expression, Expression]
+	| ["<=", Expression, Expression]
+
+	// transforms
+	| ["!", Expression]
+	| ["!!", Expression]
+	| ["clamp", a: Expression | null, b: Expression | null, Expression]
+	| ["remap", [a: Expression, b: Expression], [c: Expression, d: Expression], Expression]
+
+	// temporal
+	| ["dt"] // delta time in seconds since last resolve, used for stick sensitivity
+	| ["accumulate", string] // sum all values of this expression since last resolve
+	| ["tapped", ms: number, taps: number, Expression]
+	| ["held", ms: number, Expression]
+)
+
+export type Action = {
+	value: number // latest-known value
+	previous: number // previously-known value
+
+	change: number // how many times the value has changed since previous resolve
+	up: number // how many times this button has been released since previous resolve
+	down: number // how many times this button has been pressed since previous resolve
+
+	lowest: number // lowest value since we last checked
+	highest: number // highest value since we last checked
+}
+
+export type Actions<B extends Bindings = any> = (
+	B extends Expression
+		? Action
+		: B extends {[key: string]: Bindings}
+			? {[K in keyof B]: Actions<B[K]>}
+			: never
+)
+