OpenJoystickDriver/llms.txt at main · xsyetopz/OpenJoystickDriver · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
# OpenJoystickDriver

OpenJoystickDriver is a macOS userspace gamepad driver. It reads physical
controllers, parses native reports, and publishes consumer-facing compatibility
controllers through `IOHIDUserDevice`. An optional generated DriverKit relay is
used for integrity testing and diagnostics; it is not a consumer gamepad.

## Important Paths

- `Package.swift` and `Package.resolved`: SwiftPM graph and pinned package
  versions. SwifterKit is pinned here for reproducible DriverKit work.
- `Sources/OpenJoystickDriverKit/`: parsers, controller records, compatibility
  output policy, diagnostics, and application-service IPC. It must not import
  SwifterKit.
- `Sources/OpenJoystickDriverRelay/`: only runtime adapter allowed to import
  SwifterKit; owns the DriverKit relay configuration and lifecycle.
- `Sources/DriverKitGenerator/`: build-time executable that generates the
  SwifterKit native DriverKit project.
- `.build/driverkit/generated/`: ephemeral generated native project. Never edit
  or commit it; no post-generation patches are permitted.
- `Sources/OpenJoystickDriver/`: headless application host, persistent application
  service, headless CLI, and composition root.
- `Resources/SDL/openjoystickdriver.gamecontrollerdb.txt`: SDL mapping for the
  user-space OJD device; use `platform:macOS` for SDL3.
- `Sources/OpenJoystickDriverKit/Resources/Controllers/`: generated runtime
  controller records. `Resources/ControllerOverrides/` contains minimal source
  corrections; schemas are in `Resources/Schemas/`.
- `scripts/ojd`: supported developer command surface.
- `scripts/build-tools/driverkit.sh`: generated relay validation, build, signing,
  and embedding owner.
- `scripts/README.md`: signing, generation, installation, and release procedure.

## DriverKit Rules

- SwifterKit is the sole owner of generated native DriverKit project structure.
  Do not add a manual native build path, wrapper, or output patch.
- Keep `OpenJoystickDriverKit` independent of SwifterKit. `OpenJoystickDriverRelay`
  depends inward on it; `OpenJoystickDriver` and `DriverKitGenerator` are roots.
- Preserve bundle ID `com.openjoystickdriver.VirtualHIDDevice`. The host app's
  user-client entitlement must be exactly allowlisted to that ID; allow-any
  access is forbidden.
- Use `./scripts/ojd driverkit generate` to inspect fresh output and
  `./scripts/ojd check driverkit` to prove deterministic generation,
  metadata/entitlement constraints, dependency direction, and unsigned build.
  Signed activation and hardware delivery require a provisioned Mac and remain
  separate evidence.

## Current Status and Commands

- User-facing device/mode status: `docs/user/compatibility.md`.
- Runtime architecture: `docs/development/architecture.md`.
- Change rules and required checks: `AGENTS.md`.
- Never duplicate controller support claims in `llms*.txt`.

```bash
brew install libusb
./scripts/ojd catalog regenerate --check
./scripts/ojd check profiles
./scripts/ojd test parsers-macos14
./scripts/ojd check driverkit
./scripts/ojd check scripts
swift build
```

Controller JSON `$schema` values use repo raw GitHub URLs; VID/PID and endpoint
values are decimal. Read `AGENTS.md` before editing. `CLAUDE.md`, `GEMINI.md`,
and `.github/copilot-instructions.md` are symlinks to it.