GamepadCompanionVS

Full native gamepad support for Vintage Story 1.22+, designed as a client-side mod. No Steam Input, AntiMicro, or external key mappers required — the mod reads the gamepad directly via GLFW and integrates with VS hotkeys, dialogs, and inventory UIs.

> **Language**: the in-game UI is localized in **English** and **Spanish** (Latin American and European), following your VS client language, with English as fallback for everything else. Want it in your language? PRs are welcome at the GitHub repo — it's just one JSON file in `assets/gamepadcompanion/lang/`, no code changes needed.

## Features

- **Movement and camera** via sticks, with configurable sensitivity (horizontal/vertical), dead zone, and pitch inversion.
- **12-slot radial menu** (LB + right stick). Defaults to Character, Chat, Handbook, Settings, and Virtual Keyboard; the remaining slots are assignable from the in-game dialog.
- **Contextual button mapping**: B closes the open dialog or drops the active item depending on context; A jumps; X/Y/Back/Start mapped to tool mode, inventory, map, and pause menu.
- **Virtual cursor over GUIs**: when a modal dialog is open, a yellow cursor appears. Hold RB for smooth right-stick movement; DPad without RB steps it slot-by-slot for fast inventory navigation. RT/LT click left/right.
- **World map zoom with the D-Pad**: with the fullscreen map open, D-Pad ↑/↓ zooms in/out (one mouse-wheel notch per press) while ←/→ keeps moving the cursor for clicking waypoints.
- **Ctrl and Shift toggles** via L3/R3 with a HUD indicator in the top-right corner. Enables shift-click in inventory, ctrl-click placement, etc.
- **Precision mode** (DPad Up) reduces camera sensitivity by a configurable factor for aiming at specific blocks.
- **Composite actions**: a single radial slot can execute several actions in sequence.
- **Per-key injection** (`KeyPressAction`): bind any keyboard key to a slot or gamepad button — useful for hotkeys not in the vanilla list.
- **On-screen virtual keyboard** for typing commands and chat with the gamepad. QWERTY + `/` and `.` for slash commands.
- **In-game editor** (`/gpconfig` or `Insert` by default): three tabs (Wheel, Buttons, Sensitivity) with automatic JSON persistence to `ModConfig/gamepadcompanion.json`.
- **Localized UI** (English/Spanish): dialogs, pickers, HUD indicators, and radial labels follow the game language — including labels of already-saved bindings.

## Compatibility

| Platform | Status |
|----------|--------|
| Linux | ✅ Thoroughly tested (CachyOS X11 + GameSir Cyclone 2) |
| Windows | ✅ Verified by user reports (XInput controllers: Xbox 360, 8BitDo Ultimate 2C) |
| macOS | ⚠️ Untested — cross-platform stack (GLFW / OpenTK / VS API), should work in theory |

The mod bypasses GLFW's SDL gamepad-mapping database and reads the joystick raw, auto-detecting one of five layouts on first poll (check the client log for `detected ... layout`):

| Controller | Status |
|------------|--------|
| Xbox 360 / One / Series (Linux and Windows) | ✅ xpad / WinXInput layouts |
| GameSir Cyclone 2 (Xbox and PS4 modes) | ✅ Thoroughly tested |
| 8BitDo, generic XInput-compatible | ✅ Same XInput layouts |
| Generic PS4-like DirectInput (Wired Controller, etc.) | ✅ Auto-detected by signed-trigger signature |
| X-D GamePad / SHANWAN PS3-DInput mode | ✅ Experimental — button map inferred, report issues |
| DualSense / DualShock 4 (official) | ⚠️ Driver-dependent — some firmwares match a heuristic, others need xpad emulation |
| Switch Pro | ⚠️ Depends on driver mode |
| Other non-xpad joysticks | ❌ Unknown layout, mappings will be off |

If your controller is not recognized, the `/gpaxes` command dumps raw axes to help diagnose.

## Steam Input

If you launch Vintage Story through Steam, **disable Steam Input for this game** — otherwise you'll get double input (Steam sends synthetic keyboard/mouse + the mod reads the gamepad raw → camera at double speed, duplicated clicks).

Steam → right-click Vintage Story → Properties → Controller → "Disable Steam Input". The rest of Steam (overlay, friends, playtime, screenshots) keeps working — only the gamepad remapping layer is turned off.

If your controller only shows up as a gamepad when Steam Input emulates it (typical for DualSense / DualShock 4 / Switch Pro), either use Steam Input in plain "Gamepad / X360 passthrough" mode (no kb/m remapping — the mod reads the virtual Xbox controller fine), or use an alternative driver (DS4Windows on Windows, `hid-playstation` on Linux) and disable Steam Input entirely.

This mod is essentially an alternative to Steam Input *specific to VS*, with knowledge of vanilla hotkeys and dialogs that a generic mapper cannot have. Use one or the other, not both.

## How it works internally (disclaimer)

To make vanilla GUIs react to the gamepad without per-dialog patches, the mod injects synthetic mouse and keyboard events into the VS engine: it writes `ClientMain.MouseCurrentX/Y`, calls `OnMouseDown` / `OnKeyDown` / `OnKeyPress` directly, and writes Ctrl/Shift state into `KeyboardState[]`. This is the legitimate VS modding API, but worth disclosing — the mod has access to the client input stack and generates events the game treats as if they came from the user. Nothing is sent over the network; no files are touched outside `ModConfig/gamepadcompanion.json`; no `unsafe` blocks. If that pattern makes you uncomfortable, don't install it.