HandlePro

HandlePro A controller layer for Minecraft, not a controller mod for one Minecraft version. Minecraft reads raw stick axes from GLFW, but it has never treated a gamepad as a gamepad: no device identity, no brand-correct button glyphs, no GUI navigation, no macros. HandlePro rebuilds SDL's GameController layer inside the client so a pad behaves the way players expect — on any version that does not ship that support natively. Client side only. Nothing is installed on the server, and no packets are forged. Why this exists System-level mappers (Steam Input, DS4Windows, reWASD) emulate a mouse and keyboard. That works, but it throws away everything that makes a controller a controller: System mapper HandlePro Knows which pad is connected No — it sees "a controller" Yes — SDL GUID + vendor/product + driver name Button prompts Always Xbox, or whatever you configure Brand-correct: A / ✕ / B for the same physical button GUI navigation Fake mouse only, no scroll or focus Right stick drives the real cursor, plus dpad row navigation Analog input Buttons only (triggers become on/off) Triggers and sticks stay analog, with deadzone and response curve Per-game tuning Copied by hand between profiles One config, read at runtime, per device Features Device identification

• Decodes USB vendor and product IDs out of the SDL GUID, cross-checks them against the driver name.
• Reports the brand: Xbox · PlayStation · Nintendo · GameSir · ShanWan · 8BitDo · Logitech · Valve · Razer · generic. Unrecognised pads are reported as generic rather than guessed.
• Handles hot-plugging in the background; the device list updates without restarting the game.
• Shows where a pad's layout came from — driver, mapping database, or raw fallback — so a wrong button map is diagnosable instead of mysterious. Brand-correct glyphs The same physical south button is printed differently by different vendors. HandlePro renders the label the pad actually has: Physical button Xbox PlayStation Nintendo South A ✕ B East B ○ A West X □ Y North Y △ X Hint pills are tinted with the brand palette, so the on-screen prompt matches the thing in your hands. Mapping database
• Bundles a subset of gamecontrollerdb.txt and loads a full copy from config/handlepro/gamecontrollerdb.txt if you drop one there.
• Pads with a mapping string use it. Pads without one (cheap clones, virtual drivers, some wireless dongles) fall back to selectable raw layouts: XInput / Switch / Legacy.
• Layout can be forced per device from the in-game screen, no file editing required. GUI adaptation
• The right stick drives the system cursor, so every vanilla screen — inventory, options, server list, chat — becomes clickable immediately, with working hover, tooltips and scrolling.
• The mod's own screens add dpad row navigation, sliders, toggles and inline text editing.
• Light and dark themes, English and Simplified Chinese UI. Gameplay
• Left stick moves, right stick looks. Look is pumped every frame rather than at tick rate, so it does not feel like a slideshow.
• Triggers fire attack and use with an analog threshold, not a binary click.
• Every other button maps onto a vanilla key binding. The server sees ordinary player input. Macros
• Recording samples real elapsed time, not ticks, so playback keeps its rhythm at any frame rate.
• Playback is fed back through the same input pipeline the pad uses — no synthetic packets.
• Loop, rename, delete. One JSON file per macro under config/handlepro/macros/, easy to back up or share.
• Locked by default in multiplayer. Recording and playback require an explicit opt-in in the macro tab; until then the tab reads macros locked and the hotkey refuses. This is a deliberate fair-play default, and the mod will not hide it from you. Default bindings Input Action A jump / confirm B sneak / right click X attack (hold) Y use / place LT / RT attack / use, analog threshold LB sprint (hold) RB swap offhand L3 sprint R3 look / GUI pointer D-pad scroll, or move the row selection in HandlePro screens D-pad up / down inventory / drop item D-pad left toggle perspective View (BACK) close the current screen Menu (START) inventory Keyboard: F9 opens HandlePro, F10 starts or stops a macro recording. The panic key is unbound by default — bind it in Controls, and pressing it suspends all controller takeover (useful when a stick gets stuck). Configuration config/handlepro/config.json: { "theme": "auto", // auto | light | dark "enabled": true, "guiCursor": true, "gameplay": true, "deadzone": 0.18, "responseCurve": 1.0, "lookSensitivity": 1.0, "triggerThreshold": 0.35, "rawLayout": "auto", // auto | xinput | switch | legacy "brandOverride": "auto", "macros": { "enabled": true, "allowInMultiplayer": false, "maxSeconds": 120 } } Every option is also editable in game (F9), so the file is for backups and bulk edits rather than a required step. Platform and version support HandlePro is built as a version-independent controller layer with thin per-platform shells. It is not a patch for one Minecraft release, and this description is deliberately not written around a single loader or a single game version. Platform Status Fabric — Minecraft Java 26.1 Released, v1.0.0 Other loaders (NeoForge, Quilt, Forge) Planned; the input, mapping and config layers contain no loader code Other Minecraft versions Planned; each version gets its own build with identical behaviour How that split works, and why the port is cheap:
• Version-independent: device enumeration, SDL GUID decoding, gamecontrollerdb parsing, deadzone and response curves, macro recording and playback, the multiplayer policy, and the config format.
• Version-specific: only the screen rendering, the event signatures and two mixins (a per-frame pump and a mouse-position accessor). That is the entire diff surface when a new Minecraft version lands.
• Pads are described by SDL strings and GUIDs, not by Minecraft classes, so a mod-side update never changes how your hardware is identified. Support requests and port priorities are tracked in the issue tracker; tell me which loader or version you need and it goes on the list. Install

1. Install a mod loader for your Minecraft version (see the versions tab for the exact build).
2. Put the HandlePro jar in mods/. If your loader needs an API mod for that version, install it as well — declared as a dependency on the version you download.
3. Client only. Servers neither need nor accept it. Compatibility notes

• No vibration / rumble. GLFW exposes no cross-platform rumble API; this is a platform limit, not a missing feature.
• No SDL hat support. Pads that report a hat instead of buttons (h0.1 style) need a mapping line with buttons; the common ones are already covered.
• GLFW sees joystick ids 0–15. A sixteenth-connected pad is invisible; unplug something.
• Vanilla screens keep keyboard focus logic. They are driven by cursor plus synthesised clicks, so focus rings behave like mouse interaction rather than console-style navigation.
• No server component, no packet forging, no macro sync. Everything happens on your client. Troubleshooting Symptom Fix No device listed Check the OS sees it, press rescan devices; GLFW only exposes joystick ids 0–15 Buttons are wrong The pad has no mapping line — try forced raw layout xinput / switch / legacy in the controller tab Look is too twitchy Lower look sensitivity, raise the deadzone Cursor does not move The right stick must pass 0.35, and gamepad drives cursor must be on Stuck keys Press the panic key, or toggle controller support off and on Macros greyed out You are on a server and the multiplayer opt-in is off — that is the intended default Links
• Source: https://gitee.com/hseisirs/handlepro
• Landing page: https://hseisirs.top/
• Issues and port requests: https://gitee.com/hseisirs/handlepro/issues 中文说明 HandlePro 是给 Minecraft 用的手柄输入层，不是"某个版本专用"的手柄模组。 GLFW 能读到摇杆的原始轴，但游戏从来不把手柄当手柄：没有设备身份、没有品牌刻字、界面点不动、 也没有宏。HandlePro 在客户端内部重建了 SDL 的 GameController 层，让手柄在任何没有原生支持的 版本上都能正常用。纯客户端，服务器不用装，也不伪造任何数据包。 主要能力
• 设备识别 — 解析 SDL GUID 中的厂商 / 产品号，结合驱动名认出品牌：Xbox、PlayStation、 Nintendo、GameSir、ShanWan、8BitDo、Logitech、Valve、Razer，认不出的老实报"通用"。
• 品牌刻字 — 同一颗物理按键，Xbox 显示 A、PlayStation 显示 ✕、Nintendo 显示 B； 提示药丸按品牌配色。
• 映射库 — 内置 gamecontrollerdb.txt 片段，也支持放在 config/handlepro/gamecontrollerdb.txt 的完整库；没有映射串的山寨手柄回落到 XInput / Switch / Legacy 三套预设布局，可在界面里按设备强制。
• 界面适配 — 右摇杆驱动系统光标，原版所有界面（背包、设置、服务器列表、聊天）立刻可点， 悬浮、工具提示、滚轮都正常；模组自绘界面支持方向键选行、滑杆、开关、行内改名。
• 游戏操作 — 左摇杆走位、右摇杆视角（每帧刷新，不是 20Hz）、扳机走模拟量阈值， 其余按键映射到原版键位。
• 宏 — 按真实时间采样录制，回放走同一条输入管线；支持循环、改名、删除，一个宏一个 JSON。 多人游戏默认锁定，必须在"宏"页显式打开才可录制 / 回放。
• 浅色 / 深色双主题，中英双语界面。 平台与版本 这份描述刻意不写成"26.1 + Fabric 专用"：模组的输入语义、映射库、配置格式和宏系统都不含 版本相关代码，换版本时真正要动的只有界面渲染、事件签名和两个 mixin。目前已发布 Fabric 26.1 的构建，其他加载器与其他 Minecraft 版本在计划中，行为保持一致，各自独立构建。 安装

1. 给对应 Minecraft 版本装好加载器（具体构建见版本页）。
2. 把 HandlePro 的 jar 放进 mods/；如果该版本需要加载器对应的 API 模组，一并装上（下载页会标注）。
3. 只装客户端，服务器不需要。 已知限制