invilso/gta-fpv-drone

A fully scripted FPV drone for GTA San Andreas (MoonLoader) — spawn a quadcopter, freeze your character in place, and fly it FPV-style with real flight physics, flown from any connected controller (RC transmitter, DualSense, Xbox pad, generic joystick). Works in both singleplayer and SA-MP.

Video overview

Features

• Real flight physics — thrust, gravity, anisotropic drag, motor spool lag, ground/ceiling effect, optional wind/turbulence — not GTA's own vehicle physics, so full flips and inverted flight work.
• Three flight modes: ACRO (direct rate control), LEVEL (self-leveling), HORIZON (blends both by stick deflection) — plus an optional bidirectional 3D-throttle mode. Switchable by keyboard or a controller button.
• Flight recorder + VLC-style replay: records every flight (drone pose
  • nearby vehicles/peds/objects) to a fixed-memory ring buffer, save to disk, and play it back with speed control, scrubbing, and the game's own in-vehicle camera (including the V camera cycle).
• Four OSD styles: Classic (text readout), Skyline (clean white HD horizon + tapes), Recon (mono-green analog-camera look), Circuit (race-sim grid/crosshair/boxed readouts) — plus a color-coded drone HP indicator, signal-strength static effect, and flight timer.
• A settings menu built for it: glass window, macOS-style dock navigation, drone-status bar, live settings search, first-run setup wizard (controller detection, calibration, graphical deadzone tuning), and profile cards you can duplicate/rename/share as plain text.
• Motor audio with live pitch/volume from throttle and distance.
• Any controller — RC transmitters and modern gamepads alike, selected live from the in-game menu; plug in more than one and switch anytime.
• Configurable drone profiles (whoop / racer / heavy / default, or your own) — mass, thrust, drag, rates all editable live.

Quick start

Let an AI agent do it

GTA modding is mostly "which of these fifteen things is missing", which an AI coding agent handles well. If you use Claude Code, Codex, Cursor, Copilot, Antigravity or similar, open this repo in it and say:

Read AI-SETUP.md and set up this mod for me.

Answer its questions and it does the rest. This is the easiest route if you'd rather not touch a terminal — and it's just as useful later, when something breaks.

AI-SETUP.md is written for the agent, not for you. It tells it how to find your game, verify the version, check every dependency in one pass, install, and diagnose the failures that actually happen — including several non-obvious ones that took days to work out the first time.

No subscription needed. GitHub Copilot and Google Antigravity both have free tiers. They're rate-limited, but a mod install is a short job: the free allowance covers it, and covers debugging afterwards.

It's kept on a short leash, which matters if you'd rather it didn't rearrange your machine:

• Its working area is the game folder. Anything outside — your Wine prefix, Steam's settings, system packages — needs your permission for that one specific change, confirmed by pasting back a key it gives you, so it can't be waved through with a distracted "ok". A key covers one change, not a blank cheque.
• It's told never to delete or "tidy up" things it didn't put there: other mods, ASI plugins, savegames.
• It won't patch the mod's own code unless you ask for it — a locally modified copy makes the version identifier meaningless, which turns any bug report from that install into a dead end.
• Changes stay reversible, and it has to tell you what it changed.

Do it yourself

1. Run the installer for your OS from installer/:
   • Linux: ./installer/install.sh
   • Windows: right-click installer/install.ps1 → Run with PowerShell (or powershell -ExecutionPolicy Bypass -File installer/install.ps1)
2. Follow the prompts — it asks for your GTA San Andreas folder, checks for the MoonLoader libraries this script needs (and tells you exactly what's missing and where to get it, all at once), and sets up the controller bridge.
3. Plug in a controller, launch the game, type DRONE in chat/console to spawn (default cheat phrase — throttle must be near zero, like a real arm sequence), and CFGD to open the settings menu.

See the installer's own summary output for the exact command to start the controller bridge if you chose manual startup.

Manual install

If you'd rather not use the installer: copy drone.lua and the drone/ folder into <your GTA SA folder>/moonloader/, then run uv run drone/bridge/controllerd.py (get uv if you don't have it — it installs the bridge's one dependency automatically on first run) whenever you want to fly. See drone/bridge/README.md.

If you have make, the repo has shortcuts for the two commands you'll actually repeat — make install and make bridge (the bridge has to be running whenever you fly). Run make on its own for the full list, including the contributor and release ones.

Default controls

All keybinds and the cheat phrases themselves are rebindable from the menu.

Dependencies

This is a MoonLoader script — it assumes you already have (or the installer will tell you exactly what to get):

• MoonLoader itself — config file I/O and replay file listing use MoonLoader's own native decodeJson/encodeJson and findFirstFile/findNextFile, no separate JSON or filesystem library needed
• mimgui — the settings menu
• SAMemory — direct memory access for the vehicle/camera matrix writes (search blast.hk's MoonLoader library section; no single canonical link found for this one)
• luasocket — UDP (controller bridge, both scripts' receivers)
• bass.lua + bass.dll — motor audio, via the BASS audio library (free for non-commercial use)
• uv — runs the controller bridge daemon (drone/bridge/controllerd.py); its one Python dependency (pysdl2) is declared inline and installed automatically on first run
• SA-MP client installed — needed even if you only play singleplayer. MoonLoader registers its SA-MP natives (isSampAvailable, which this script calls) only when samp.dll is present in the game folder; without it every script calling them dies at startup. Installing SA-MP does not affect singleplayer in any way — the game still launches and plays exactly as before, samp.dll just sits there. SAMPFUNCS is not required: nothing here uses it.

Wine/Proton note: mimgui (and the older imgui.lua many other scripts use) hard-requires C:\windows\Fonts\trebucbd.ttf (Trebuchet MS Bold) and dies with a font assert if the Wine prefix doesn't have it — fresh Proton prefixes don't. This mod handles it automatically: if the file is missing at startup, the bundled Inter.ttf is planted under that path (mimgui loads whatever bytes live there), so every imgui-based script in the game starts normally. Installing real corefonts (winetricks corefonts) also works if you prefer the authentic font.

Update notices: on startup the script checks drone/VERSION (the commit hash it was released at) against the same file on GitHub's main branch, and shows a small dismissible banner in the settings menu if a newer commit exists. No auto-update, no telemetry beyond that one file fetch, silently does nothing if you're offline.

Roadmap

Planned, in this order:

• ArduPilot SITL backend — the mod acts as the flight dynamics model for a real ArduPilot instance over SITL's JSON interface: actual autopilot modes (Loiter, RTL, Auto), Mission Planner / QGroundControl waypoint missions flown over San Andreas, failsafe behavior you can trigger for free. San Andreas gets pinned to fake GPS coordinates for this, which is its own kind of fun.
• PX4 HITL — the same sensor pipeline feeding a physical flight controller over MAVLink (HIL_SENSOR / HIL_ACTUATOR_CONTROLS): a real Pixhawk on the desk, armed with a real switch, flying the drone in-game.
• Betaflight/INAV SITL — both ship a SITL target with a UDP flight-dynamics interface, so the same idea applies; INAV is the more interesting of the two here (missions/RTH on top of an FPV stack). Hardware-in-the-loop for these exists only as community forks, so that part is a maybe.
• Autonomy scripting API — a per-tick hook exposing drone + world state and taking control outputs, so anyone can script autonomous behaviors without touching the core: follow/track a target, waypoint navigation, or computer-vision experiments driven over the existing UDP bridge (feed frames to your own Python/ML process, fly on its output). The mod stays a generic sandbox -- what the brain does is up to whoever writes it.

How it's built

See ARCHITECTURE.md for a system-level overview, and drone/docs/ for design write-ups on specific tricky parts (camera orientation, the physics model, collision handling, the replay format, motor audio, the controller bridge).

License

This project's own code is MIT — see LICENSE. The bundled Inter font is SIL Open Font License 1.1 — see drone/resources/Inter-OFL.txt. Third-party MoonLoader libraries listed above are not bundled and keep their own licenses.