@benev/tact 0.1.0-1

package/LICENSE

@@ -0,0 +1,23 @@
+
+MIT License
+
+Copyright (c) 2025 Chase Moskal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,299 @@
+
+# @benev/tact
+> user input keybindings and gamepad support for web games
+
+```ts
+npm install @benev/tact
+```
+
+- 🛰️ **devices** are for sampling user inputs
+- 🔗 **bindings** describe how samples influence actions
+- 📡 **station** runs device samples through bindings, updating actions
+- 🔌 **switchboard** assigns devices to stations (multi-gamepad couch co-op!)
+- 🔘 **nubs** is mobile ui virtual gamepad stuff
+
+<br/><br/>
+
+## 🍋 tact devices
+> produces 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
+- i will elaborate no further 🗿
+
+### 🥝 basically how a device works
+- make a keyboard device
+    ```ts
+    import {KeyboardDevice} from "@benev/tact"
+
+    const device = new KeyboardDevice(window)
+    ```
+- take samples each frame
+    ```ts
+    const samples = device.takeSamples()
+      // [
+      //   ["KeyA", 1],
+      //   ["Space", 0]
+      // ]
+    ```
+- dispose the device when you're done with it
+    ```ts
+    device.dispose()
+    ```
+
+### 🥝 samples explained
+- a sample is a raw input 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`
+- a sample has a `value` number
+  - `0` means *"nothing is going on"*
+  - `1` means *"pressed"*
+  - we don't like negative numbers
+  - values between `0` and `1`, like `0.123`, are how triggers and thumbsticks express themselves
+  - sometimes we use numbers greater then `1`, like for dots of pointer movement like in `pointer.move.up`
+  - don't worry about sensitivity, deadzones, values like `0.00001` — actions will account for all that using bindings later on
+
+### 🥝 sample code modprefixes
+- here at tact, we have this nifty `modprefix` convention
+- consider a keycode like `KeyA`
+    - `ctrl-KeyA` means the "ctrl" modifier was held
+    - `alt-KeyA` means the "alt" modifier was held
+    - `meta-KeyA` means the "meta" modifier was held (command or windows keys)
+    - `shift-KeyA` means the "shift" modifier was held
+    - `ctrl-alt-meta-shift-KeyA` they can stack, but always in this order (the word `cams` helps remind me the valid order)
+    - `x-KeyA` means *no* modifier was held (exclusive)
+    - `KeyA` doesn't care if any modifiers were held or not
+
+### 🥝 sample code reference
+- **KeyboardDevice**
+    - any [standard keycode](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_code_values)
+        - `KeyA`
+        - `Space`
+        - `Digit2`
+        - etc
+    - plus the modprefixes
+        - `ctrl-KeyA`
+        - `alt-shift-Space`
+        - `x-Digit2`
+        - etc
+- **PointerDevice**
+    - mouse buttons (plus modprefixes)
+        - `pointer.button.left`
+        - `pointer.button.right`
+        - `pointer.button.middle`
+        - `pointer.button.4`
+        - `pointer.button.5`
+    - mouse wheel (plus modprefixes)
+        - `pointer.wheel.up`
+        - `pointer.wheel.down`
+        - `pointer.wheel.left`
+        - `pointer.wheel.right`
+    - mouse movements
+        - `pointer.move.up`
+        - `pointer.move.down`
+        - `pointer.move.left`
+        - `pointer.move.right`
+- **GamepadDevice**
+    - gamepad buttons
+        - `gamepad.a`
+        - `gamepad.b`
+        - `gamepad.x`
+        - `gamepad.y`
+        - `gamepad.bumper.left`
+        - `gamepad.bumper.right`
+        - `gamepad.trigger.left`
+        - `gamepad.trigger.right`
+        - `gamepad.alpha`
+        - `gamepad.beta`
+        - `gamepad.stick.left.click`
+        - `gamepad.stick.right.click`
+        - `gamepad.up`
+        - `gamepad.down`
+        - `gamepad.left`
+        - `gamepad.right`
+        - `gamepad.gamma`
+    - gamepad sticks
+        - `gamepad.stick.left.up`
+        - `gamepad.stick.left.down`
+        - `gamepad.stick.left.left`
+        - `gamepad.stick.left.right`
+        - `gamepad.stick.right.up`
+        - `gamepad.stick.right.down`
+        - `gamepad.stick.right.left`
+        - `gamepad.stick.right.right`
+
+<br/><br/>
+
+## 🍋 tact bindings
+> keybindings! they describe how actions interpret samples
+
+### 🥝 bindings example
+- let's start with a small example:
+    ```ts
+    import {Bindings} from "@benev/tact"
+
+    const bindings = asBindings({
+      walking: {
+        forward: [{lenses: [{code: "KeyW"}]}],
+        jump: [{lenses: [{code: "Space"}]}],
+      },
+      gunning: {
+        shoot: [{lenses: [{code: "pointer.button.left"}]}],
+      },
+    })
+    ```
+    - `walking` and `gunning` are **modes**
+    - `forward`, `jump`, and `shoot` are **actions**
+    - data like `[{lenses: [{code: "KeyW"}]}]` are the rules for triggering the action.
+      - 🚨 TODO okay these rules are complex and i'm gonna rework them soon
+    - whole modes can be enabled or disabled
+
+<br/><br/>
+
+## 🍋 tact station
+> polling gives you actions
+
+### 🥝 creating a station
+- create a station
+    ```ts
+    import {Station} from "@benev/tact"
+
+    const station = new Station(bindings)
+      .addModes("walking")
+      .addDevices(
+        new KeyboardDevice(window),
+        new PointerDevice(window),
+      )
+    ```
+
+### 🥝 how to use actions
+- poll the station every frame
+    ```ts
+    station.poll(Date.now())
+    ```
+- now you use the `actions`
+    ```ts
+    station.actions.walking.forward.value // 1
+    ```
+    - `walking` is a `mode`
+    - `forward` is an `action`
+    - `action.value` — current value
+    - `action.previous` — last frame's value
+    - `action.changed` — true if value and previous are different
+    - `action.pressed` — true if the value > 0
+    - `action.down` — true for one frame when the key goes from up to down
+    - `action.up` — true for one frame when the key goes from down to up
+    - `action.on(action => {})` — react to changes ([`@e280/stz`](https://github.com/e280/stz) sub fn)
+    - `action.onDown(action => {})` — react only on down ([`@e280/stz`](https://github.com/e280/stz) sub fn)
+
+### 🥝 more about station
+- you can enable/disable modes like this (it's a set)
+    ```ts
+    station.modes.add("gunning")
+      // now the "gunning" actions can fire
+
+    station.modes.delete("walking")
+      // now the "walking" actions *cannot* fire
+    ```
+- you can add/remove devices from the set any time
+    ```ts
+    station.devices.add(new GamepadDevice(pad))
+    ```
+- you can update the bindings at runtime
+    ```ts
+    station.bindings = bindings2
+    ```
+
+<br/><br/>
+
+## 🍋 tact switchboard
+> multiple gamepads! couch co-op is so back
+
+### 🥝 feel the vibes
+- you know the way old timey game consoles had controller ports? and then players could plug their controller into whatever port they wanted? and then you could unplug and replug your controller into a different port? yeah — that's what switchboard does.
+- with the switchboard, think of the "stations" as controller ports, and the "devices" as player controllers.
+- import stuff:
+    ```ts
+    import {
+      Switchboard, Station,
+      GroupDevice, GamepadDevice, KeyboardDevice, PointerDevice,
+    } from "@benev/tact"
+    ```
+
+### 🥝 create a switchboard with stations
+- **adopt standard switchboard bindings**
+    ```ts
+    // transform your game's bindings into switchboard-friendly bindings
+    const sBindings = Switchboard.bindings(bindings)
+    ```
+    - this allows players to shimmy what station their controller controls
+    - gamepad: hold middle button and press bumpers
+    - keyboard: left bracket or right bracket
+- **make switchboard with stations at the ready**
+    ```ts
+    const switchboard = new Switchboard([
+      new Station(sBindings),
+      new Station(sBindings),
+      new Station(sBindings),
+      new Station(sBindings),
+    ])
+    ```
+    - yes that's right — each player can have their own bindings 🤯
+
+### 🥝 connect player's devices to the switchboard
+- **let's connect the keyboard/mouse player**
+    ```ts
+    switchboard.connect(
+      new GroupDevice(
+        new KeyboardDevice(window),
+        new PointerDevice(window),
+      )
+    )
+    ```
+    - the switchboard assumes a single device represents a single player, thus we can use a `GroupDevice` to combine multple devices into one
+- **wire up gamepad auto connect/disconnect**
+    ```ts
+    GamepadDevice.on(device => switchboard.connect(device))
+    ```
+
+### 🥝 you're ready!
+- **do your polling, interrogate those actions**
+    ```ts
+    const [p1, p2, p3, p4] = switchboard.stations
+
+    // poll them all
+    switchboard.poll(Date.now())
+
+    p1.actions.walking.jump.value // 1
+    p2.actions.walking.jump.value // 0
+    ```
+
+### 🥝 the more you know, about the switchboard
+- `switchboard.stations` — direct access to the array of stations
+- `switchboard.isActive(p1)` — check if there's a switchboard-connected-device assigned to this station
+- `switchboard.shimmy(device, 1)` — shimmy a device forward one station
+- `switchboard.shimmy(device, -1)` — shimmy a device backward one station
+- `switchboard.connect(device, p4)` — connect-or-reassign a device to a specific station
+- `switchboard.connect(device)` — connect a device to the next unassigned station (or the last station)
+- `switchboard.disconnect(device)` — unassign a device and forget about it
+
+<br/><br/>
+
+## 🍋 tact nubs
+> mobile ui like virtual thumbsticks and buttons
+
+### 🥝 nub stick
+> TODO lol need to write docs
+
+### 🥝 nub virtual gamepad
+> TODO lol need to write docs
+
+<br/><br/>
+
+## 🍋 tact is by https://benevolent.games/
+> building the future of web games
+

package/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "@benev/tact",
+	"version": "0.1.0-1",
+	"description": "keybindings and gamepad support for web games",
+	"license": "MIT",
+	"author": "Chase Moskal <chasemoskal@gmail.com>",
+	"type": "module",
+	"main": "./x/index.js",
+	"sideEffects": false,
+	"exports": {
+		".": "./x/index.js"
+	},
+	"files": [
+		"x",
+		"s"
+	],
+	"scripts": {
+		"build": "run-s _clean _tsc _ln _scute",
+		"_clean": "rm -rf x",
+		"_tsc": "tsc",
+		"_scute": "scute -v",
+		"start": "octo 'scute -vw' 'tsc -w' 'node --watch x/tests.test.js' 'http-server x -c-1'",
+		"_ln": "run-s _ln-s _ln-assets",
+		"_ln-s": "ln -s \"$(realpath s)\" x/s",
+		"_ln-assets": "ln -s \"$(realpath assets)\" x/assets",
+		"test": "node x/tests.test.js",
+		"test-debug": "node inspect x/tests.test.js",
+		"count": "find s -path '*/_archive' -prune -o -name '*.ts' -exec wc -l {} +"
+	},
+	"peerDependencies": {
+		"lit": "^3.3.1"
+	},
+	"dependencies": {
+		"@benev/math": "^0.2.0-1",
+		"@e280/sly": "^0.1.1",
+		"@e280/strata": "^0.1.0",
+		"@e280/stz": "^0.2.0-4"
+	},
+	"devDependencies": {
+		"@e280/science": "^0.1.1",
+		"@e280/scute": "^0.0.0",
+		"http-server": "^14.1.1",
+		"npm-run-all": "^4.1.5",
+		"typescript": "^5.9.2"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/benevolent-games/tact.git"
+	},
+	"bugs": {
+		"url": "https://github.com/benevolent-games/tact/issues"
+	},
+	"homepage": "https://github.com/benevolent-games/tact#readme",
+	"keywords": [
+		"user input",
+		"keybinds",
+		"keybindings",
+		"gamepad"
+	]
+}

package/s/demo/main.bundle.ts

@@ -0,0 +1,14 @@
+
+import {$, view} from "@e280/sly"
+import {NubStick} from "../nubs/stick/view.js"
+import {StickDevice} from "../nubs/stick/device.js"
+
+$.register({
+	TactDemo: view.component(use => {
+		const stick = use.once(() => new StickDevice())
+		return NubStick(stick)
+	}),
+})
+
+console.log("tact")
+

package/s/demo/main.css

@@ -0,0 +1,57 @@
+
+@layer vars, core, basics, page;
+
+@layer vars {
+	:root {
+		color-scheme: dark;
+		--link: cyan;
+		--bg: #181818;
+		--prime: #aaa;
+	}
+}
+
+@layer core {
+	* {
+		padding: 0;
+		margin: 0;
+		box-sizing: border-box;
+	}
+
+	::-webkit-scrollbar { width: 4px; }
+	::-webkit-scrollbar-track { background: transparent; }
+	::-webkit-scrollbar-thumb { background: #333; border-radius: 1em; }
+	::-webkit-scrollbar-thumb:hover { background: #444; }
+
+	a {
+		color: var(--link);
+		text-decoration: none;
+
+		&:visited {
+			color: color-mix(in srgb, var(--link), purple 30%);
+		}
+
+		&:hover {
+			color: color-mix(in srgb, var(--link), white 10%);
+			text-decoration: underline;
+		}
+
+		&:active {
+			color: color-mix(in srgb, var(--link), white 50%);
+		}
+	}
+}
+
+@layer basics {
+	html { height: 100%; }
+	body { min-height: 100%; }
+
+	html, body {
+		font-size: 21px;
+		color: var(--prime);
+		background: var(--bg);
+	}
+}
+
+@layer page {
+}
+

package/s/index.html.ts

@@ -0,0 +1,42 @@
+
+import {ssg, html} from "@e280/scute"
+
+const title = "@benev/tact"
+const domain = "tact.benevolent.games"
+const favicon = "/assets/b.png"
+const description = "keybindings and gamepad support for web games"
+
+export default ssg.page(import.meta.url, async orb => ({
+	title,
+	js: "demo/main.bundle.min.js",
+	css: "demo/main.css",
+	dark: true,
+	favicon,
+	head: html`
+		<meta data-version="${orb.packageVersion()}" />
+	`,
+
+	socialCard: {
+		title,
+		description,
+		themeColor: "#f2ea8e",
+		siteName: domain,
+		image: `https://${domain}${favicon}`,
+	},
+
+	body: html`
+		<header>
+			<h1>
+				<strong>@benev/tact</strong>
+				<span>v${orb.packageVersion()}</span>
+			</h1>
+			<div class=deets>
+				<a href="https://github.com/benevolent-games/tact">github</a>
+				<a href="https://benevolent.games/">benevolent.games</a>
+			</div>
+		</header>
+
+		<tact-demo></tact-demo>
+	`,
+}))
+

package/s/index.ts

@@ -0,0 +1,16 @@
+
+export * from "./station/devices/infra/device.js"
+export * from "./station/devices/infra/group.js"
+export * from "./station/devices/infra/sampler.js"
+export * from "./station/devices/gamepad.js"
+export * from "./station/devices/keyboard.js"
+export * from "./station/devices/pointer.js"
+export * from "./station/parts/action.js"
+export * from "./station/utils/modprefix.js"
+export * from "./station/station.js"
+export * from "./station/switchboard.js"
+export * from "./station/types.js"
+
+export * from "./utils/gamepads.js"
+export * from "./utils/split-axis.js"
+

package/s/nubs/lookpad/styles.ts

@@ -0,0 +1,21 @@
+
+import {css} from "lit"
+export const styles = css`
+
+:host {
+	display: block;
+	width: 10em;
+	height: 10em;
+
+	user-select: none;
+	border: 1px solid;
+
+	touch-action: none;
+}
+
+.pad {
+	width: 100%;
+	height: 100%;
+}
+
+`

package/s/nubs/lookpad/utils/listeners.ts

@@ -0,0 +1,53 @@
+
+export function lookpad_listeners({
+		onPointerDrag,
+		getPointerCaptureElement,
+	}: {
+		onPointerDrag: (event: PointerEvent) => void
+		getPointerCaptureElement: () => HTMLElement
+	}) {
+
+	let pointer_id: number | undefined
+
+	return {
+		pointerdown: {
+			options: undefined,
+			handleEvent: (event: PointerEvent) => {
+				event.preventDefault()
+
+				const element = getPointerCaptureElement()
+
+				if (pointer_id)
+					element.releasePointerCapture(pointer_id)
+
+				pointer_id = event.pointerId
+				element.setPointerCapture(pointer_id)
+				onPointerDrag(event)
+			},
+		},
+
+		pointermove: {
+			options: {passive: false},
+			handleEvent: (event: PointerEvent) => {
+				event.preventDefault()
+
+				if (event.pointerId === pointer_id)
+					onPointerDrag(event)
+			},
+		},
+
+		pointerup: {
+			options: undefined,
+			handleEvent: (event: PointerEvent) => {
+				event.preventDefault()
+
+				if (event.pointerId === pointer_id) {
+					getPointerCaptureElement().releasePointerCapture(pointer_id)
+					pointer_id = undefined
+					onPointerDrag(event)
+				}
+			},
+		},
+	}
+}
+

package/s/nubs/lookpad/view.ts

@@ -0,0 +1,32 @@
+
+import {html} from "lit"
+import {view} from "@e280/sly"
+
+import {styles} from "./styles.js"
+import {lookpad_listeners} from "./utils/listeners.js"
+
+export const NubLookpad = view(use => () => {
+	use.name("nub-lookpad")
+	use.styles(styles)
+
+	const pad = use.life(() => {
+		const pad = document.createElement("div")
+		pad.className = "pad"
+
+		const listeners = lookpad_listeners({
+			getPointerCaptureElement: () => pad,
+			onPointerDrag: () => {},
+		})
+
+		for (const [event, {handleEvent, options}] of Object.entries(listeners))
+			pad.addEventListener(event as any, handleEvent, options)
+
+		return [pad, () => {
+			for (const [event, {handleEvent}] of Object.entries(listeners))
+				pad.removeEventListener(event as any, handleEvent)
+		}]
+	})
+
+	return html`${pad}`
+})
+

package/s/nubs/stick/device.ts

@@ -0,0 +1,30 @@
+
+import {Vec2} from "@benev/math"
+import {signal} from "@e280/strata"
+import {Disposable} from "@e280/stz"
+import {splitAxis} from "../../utils/split-axis.js"
+import {SamplerDevice} from "../../station/devices/infra/sampler.js"
+
+export class StickDevice extends SamplerDevice implements Disposable {
+	vector = signal(Vec2.zero())
+	dispose: () => void
+
+	constructor(public channel = "stick") {
+		super()
+		this.dispose = this.vector.on(() => {
+			const {up, down, left, right} = this.breakdown()
+			this.setSample(`${channel}.up`, up)
+			this.setSample(`${channel}.down`, down)
+			this.setSample(`${channel}.left`, left)
+			this.setSample(`${channel}.right`, right)
+		})
+	}
+
+	breakdown() {
+		const {x, y} = this.vector.get()
+		const [down, up] = splitAxis(y)
+		const [left, right] = splitAxis(x)
+		return {up, down, left, right}
+	}
+}
+

package/s/nubs/stick/styles.ts

@@ -0,0 +1,22 @@
+
+import {css} from "lit"
+export const styles = css`
+
+:host {
+	display: block;
+	width: 8em;
+	aspect-ratio: 1 / 1;
+	touch-action: none;
+}
+
+.container {
+	width: 100%;
+	height: 100%;
+}
+
+[part="graphic"] {
+	width: 100%;
+	height: 100%;
+}
+
+`