sol-r1-linux-game-mappings/template/README.md

Template - adding a new game

Copy this whole folder to ../<game-name>/ and work through it top to bottom.

1. joyful-config.yml - bare 1:1 passthrough (every physical control mapped straight through, no remapping, no key emulation). Run find_codes.py (repo root) against the hardware and fill in every TODO_*. Get the game running with this first, so you have a known-good baseline before customizing anything.
2. Customize the mapping for what the game actually needs: axis remaps, key emulation for toggles, buttons bound in the game's own control menu, etc. See ../space-engineers/ for a worked example (including the "throttle read as a trigger" class of bug this exists to fix).
3. Do you need input_converter_daemon.py at all? Only if some physical control is a real on/off switch (not a momentary button) and the game only exposes the equivalent action as a stateless toggle key. If every control you're mapping is a stateless passthrough, delete input_converter_daemon.py, TODO-daemon-config.yaml (once created), and the daemon block in launch-wrapper.sh - joyful alone is enough, and you're done after step 2.
4. If you do need it: rename the example config (input_converter_daemon.py --dump-example-config > <game>-daemon-config.yaml), fill in real evdev codes (find_codes.py), confirm the game's actual toggle keybinds in its own settings menu (never assume defaults), and calibrate HUD regions/colors with input_converter_daemon.py --sample X,Y. Point launch-wrapper.sh's DAEMON_CONFIG at it.
5. launch-wrapper.sh - set as the Steam launch options: /path/to/<game>/launch-wrapper.sh %command%. Per-machine, not synced by Steam - repeat on every machine.