Gamepad module

Reusable controller mapping engine and React interface. This is a private release candidate.

Exports: core client, React panel/provider, Tauri host and transport, generated plugin commands (./commands), generated native contract, locales and assets. The Tauri plugin is alwith-gamepad on crates.io; this package carries the native libraries. Import styles.css once and explicitly register gamepadResources in the host i18n instance. Wrap GamepadPanel in GamepadProvider with native transport, permissions, capture lifecycle, and error reporting.

Cargo consumers depend on alwith-gamepad by version; the application's stager takes the native library from this package.

The native service owns profiles, revisions, startup/shutdown, and input injection. Selecting a controller automatically activates its saved profile. All controllers retain the shared mapping policy. System injection ownership is exclusive among hosts that implement the shared lock. An unmodified Desktop does not yet participate in this lock.

Build and tests use Bun and Cargo. Run bun run build, bun run test, and bun run test:rust from this directory. Native smoke tests marked ignored require explicit execution. Physical device coverage and Windows validation remain required before a stable release. This package has not been published.

Host integration

import { createGamepadClient } from "@alwith/module-gamepad"
import { createTauriGamepadHost } from "@alwith/module-gamepad/tauri"
import { GamepadPanel, GamepadProvider } from "@alwith/module-gamepad/react"
import { gamepadResources } from "@alwith/module-gamepad/locales"
import "@alwith/module-gamepad/styles.css"

The root entry has no React, DOM or Tauri imports and does not start native services. createTauriGamepadHost({ platform, onError, applications, generateConfig }) builds a complete host from the plugin commands; supply applications from @alwith/module-installed-apps with createInstalledApplications(onError) from @alwith/module-gamepad/installed-apps (that package is an optional peer, needed only for this entry):

import { createTauriGamepadHost } from "@alwith/module-gamepad/tauri"
import { createInstalledApplications } from "@alwith/module-gamepad/installed-apps"

const host = createTauriGamepadHost({ platform, onError, applications: createInstalledApplications(onError) })

A headless consumer can provide GamepadTransport directly. Register the desired entries from gamepadResources under the gamepad namespace (13 languages). The panel uses the host's semantic color variables. Portals carry their own style scope.

[dependencies]
alwith-gamepad = "0.6"

.plugin(alwith_gamepad::init(Config { development_directory, ..Default::default() }))
// in the application's ordered shutdown
alwith_gamepad::shutdown(app)?;

Config takes the debug-build development_directory of the native libraries and overrides the profile path (default gamepad/profiles.json in app data) and the shared per-user injection-lock path. legacy_profile_path names ALwith Desktop's gamepad-devices.json ({ "<device name>": Config }, grip color inside each config): when the profile store does not exist yet, every device is imported as the profile of that name at revision 1 with its color, none active; the legacy file is left untouched and an invalid entry fails the start with its device name. Rust hosts outside init use GamepadService::with_legacy_profiles. ALwith U always stored profiles at the default path in this format, so it passes no legacy path. The default permission set alwith-gamepad:default covers the panel; grant it only to trusted application windows in the app's capabilities. Profile saves require the expected revision. savedRevision and appliedRevision are distinct: persistence while stopped does not imply injection is active. Selecting a device automatically loads and activates its profile; subsequent edits are saved and applied immediately. Controllers share that mapping but own separate layer, axis, held-action and repeat states.

The plugin owns key-capture policy: it suspends injection, removes the application menu where needed, and restores both on stop, failure, focus loss, window destruction and shutdown. Pending starts are cancelled on focus loss. Engine events and captured keys reach only the webviews that subscribed through their channels. A destroyed window's virtual controller is detached natively; stopping application-owned AI tasks stays with the host. Native global capture is implemented for macOS and Windows; other hosts use DOM capture with injection suspended. AI generation is optional, receives an AbortSignal, and never imports a model provider. The ./ai entry provides prompt construction and validated full/incremental JSON parsing.

The panel retains a 320px device column and fixed-size controller diagram. Use a dedicated window at least 1250 by 750 pixels. Semantic host colors theme the interface and its portals.

Validation and release status

macOS arm64 verification includes unit tests, profile persistence/conflict tests, client subscription races, a React stale-save test, and explicit native virtual-controller tests with system output disabled. Physical controllers, rumble hardware, permission UI, global key interception, and Windows execution still require manual validation. The package remains private and must not be published as a stable release on this evidence.