🎮 3D Controller Overlay + v1.0.0
Feature‑complete stable release — built for streamers, tinkerers, and controller enthusiasts.
⚠️ A word on AI
This is a passion project built with heavy AI assistance (ChatGPT/Claude). I’m being fully transparent about that.
Every architectural decision — how input flows from SDL into the mesh hierarchy, how the settings/import system is structured, what gets a raw joystick fallback vs. a GameController mapping, how the build/packaging pipeline is put together — was made, reviewed, and debugged by me.
AI was my collaborator; the design, testing, and responsibility for what ships are mine.
If you find something wrong, please open an issue — I'd genuinely rather know.
✨ What's new in 1.0.0
This fork builds on the original 3D Controller Overlay by Larf. The + brings a massive set of improvements:
🖥️ Rendering & Customisation
- Custom model import via Assimp (FBX, glTF, OBJ, etc.) — assign meshes to controller parts directly in the app.
- Pivot‑point editing — drag any mesh's pivot in the 3D viewport instead of editing raw numbers.
- Per‑part material alpha — make individual buttons transparent if you need to.
- Dual‑highlight colors for axes (positive vs. negative) with adjustable deadzone.
- Touch‑area visualisation — see exactly where the touchpad hit‑box is on your mesh.
- Multi‑touchpad support — up to 4 pads × 2 fingers each.
🎮 Input
- Keyboard & mouse overlays (system‑wide) — works even when the app doesn't have focus.
- Raw joystick fallback — if SDL doesn't recognise your controller, you can still map it manually.
- Gyro & accelerometer — sensitivity, drift correction, and a configurable reset button combo.
- Manual mapping UI — bind any button, axis, or hat to any mesh, with inversion support.
🔧 Engineering
- Structured logging (spdlog) with an in‑app log window.
- CMake build system + Docker cross‑build scripts for reproducible packaging.
- AppImage, Windows
.exe, and macOS universal.appbuilds via GitHub Actions. - Embedded model library — the bundled models are packed into the binary, no separate assets folder to lose.
- Updated to SDL3 and latest Dear ImGui for better performance and bug fixes.
📦 Downloads
| Platform | File | Notes |
|---|---|---|
| 🐧 Linux | 3dco+.AppImage |
Self‑contained, run chmod +x and execute. |
| 🪟 Windows | 3dco+.exe |
May trigger SmartScreen – click "More info" → "Run anyway". |
| 🍎 macOS | 3dco+-macos.zip |
Contains universal 3dco+.app. Right‑click → Open to bypass Gatekeeper. |
👉 All assets are attached to this release below.
🔧 Quick start
- Download the package for your OS.
- Run the executable.
- The app will extract the built‑in model library on first launch (takes a few seconds).
- Open a controller window, pick a model, and start mapping your inputs.
For detailed instructions, see the README and INSTRUCTIONS.md.
🐛 Known issues (tracked)
| Issue | Status | Notes |
|---|---|---|
| Transparent background not working on some GPUs/drivers | Depends on driver support; a warning is shown in the UI. | |
| macOS: Accessibility permission required for keyboard/mouse | 🧾 By design | Grant in System Settings → Privacy & Security → Accessibility. |
| Gyro reset combo not working on certain controllers | 🕵️ Under investigation | Use the "Reset Gyro" button as a workaround. |
| Imported model preview sometimes crashes on large files | Reduce polygon count or use OBJ format. | |
| Racing wheel / pedals | 🚧 Planned | Not yet in model library or input path (coming in a future release). |
🙏 Credits
- Original creator & engine: Larf — 3D Controller Overlay
- This fork: designed, built, and maintained by me (Khyretos) as a homage and a personal test of AI‑assisted coding.
- Third‑party libraries: GLFW, glad, SDL3, GLM, Dear ImGui, stb_image, Assimp, spdlog, fmt, nlohmann_json, miniz.
💬 Feedback
If you use this and enjoy it, please star the repo ⭐ – it means a lot.
Found a bug or have a feature request? Open an issue.
Happy streaming and gaming! 🎮