# Space Engineers

Custom input scheme for the Thrustmaster Sol-R1 (grip + base) in Space
Engineers, on Arch/Hyprland, without Windows/T.A.R.G.E.T. Fixes the
"throttle behaves like a trigger" bug and adds a full custom mapping
via joyful plus a stateful daemon (`switch_sync.py`) for the 4 tilt
switches, which need game-state feedback that joyful can't provide.

**Status: draft.** No real evdev codes, SE keybinds, or HUD
calibration have been captured yet - every config file here is full of
`TODO_*` placeholders. See `mapping-brief.md` for the full design
rationale, the complete mapping table, and known caveats/open items.

## Files

- `mapping-brief.md` - design notes: stack decisions, full
  physical-control -> SE-function mapping table, caveats, next steps.
- `joyful-config.yml` - joyful rule config (**draft, unverified field
  names** - check against the installed version's
  `examples/ruletypes.yml` first).
- `switch_sync.py` - the daemon: reconciles physical switch position
  against actual in-game HUD state via `grim` screen-color sampling,
  and only sends a toggle keypress when they disagree.
- `switch_sync-config.yaml` - config for the 4 tilt switches.
- `launch-wrapper.sh` - Steam launch-options wrapper (`%command%`)
  that starts/stops joyful and `switch_sync.py` around the game
  session, cleaning up on exit.

(`find_codes.py`, the diagnostic tool used in step 2 below, lives at
the repo root - it's shared across all games.)

## Setup

1. Install dependencies:
   ```
   yay -S joyful
   sudo pacman -S grim
   pip install evdev pillow pyyaml --break-system-packages
   sudo usermod -aG input $USER   # for reading the joystick + uinput
   # re-login after this
   ```
2. Find real evdev codes:
   ```
   python3 ../find_codes.py --list
   python3 ../find_codes.py --device "<grip or base device name>"
   ```
   Exercise every physical control (axes through full range, buttons,
   both positions of every switch, both directions of every knob), and
   replace every `TODO_*` code in `joyful-config.yml` and
   `switch_sync-config.yaml` with what you observe.
3. In Space Engineers (Options -> Controls -> Controllers), confirm
   the actual keybinds for the jetpack/helmet/flashlight/parking
   toggles - don't assume defaults - and fill in `toggle_key` for each
   switch in `switch_sync-config.yaml`.
4. Calibrate the HUD regions/colors:
   ```
   python3 switch_sync.py --sample X,Y
   ```
   for each indicator in-game, and fill in `region`/`on_color` in
   `switch_sync-config.yaml`.
5. In Steam, set this game's launch options to:
   ```
   /path/to/sol-r1-linux-game-mappings/space-engineers/launch-wrapper.sh %command%
   ```
   Launch options are per-machine and not synced by Steam - repeat
   this step on every machine. Keeping this repo checked out at the
   same path on every machine keeps the launch-options string itself
   identical too.

See `mapping-brief.md` for the full mapping table and caveats:
SE-version-dependent joystick support, the dampener 3-state
limitation, HUD-detection fragility (breaks on Tab/resolution/UI-scale
changes), and the unverified joyful rule schema.