RUEN

MoonLoader and Lua scripting for GTA: San Andreas

A reference on the technology behind modern GTA: San Andreas and SA:MP scripts – from MoonLoader to ImGui interfaces.

Author: Published: Updated: 2 min read

MoonLoader is a Lua script loader for GTA: San Andreas. It came out of the Russian-speaking modding community BLAST.HK and became the main tool for client-side modifications, used for anything from small key binders to complex systems with their own UI. Many of my projects are built on it.

How it works

MoonLoader is installed into the game folder as an ASI plugin (via ASI Loader). When GTA: San Andreas starts, it loads Lua scripts from the moonloader folder. Every script runs in its own coroutine, so it can wait without freezing the game.

A minimal script:

script_name("hello")
script_author("Pakulichev")
function main()
  while not isSampAvailable() do wait(100) end
  sampAddChatMessage("Script loaded", 0xF5A524)
  while true do
    wait(0)
    -- game loop: key checks, rendering, logic
  end
end

Ecosystem

Component Purpose
MoonLoader Lua script loader and game API
LuaJIT Fast Lua 5.1 implementation with FFI – access to game memory and native functions
SAMPFUNCS Plugin that extends access to the SA:MP client
SAMP.Lua Library for handling SA:MP events and packets from Lua
mimgui / imgui Dear ImGui bindings for in-game windowed interfaces
CLEO Classic opcode-based scripting library – the predecessor of the Lua approach

Lua vs CLEO

CLEO scripts were the first mass-market way to mod GTA: San Andreas, but they are written in opcodes and don't scale well. Lua has:

  • real data structures (tables), functions and modules;
  • files, JSON, INI configs and networking;
  • FFI to call game functions and read memory;
  • convenient debugging and logging.

With Lua you can build large projects, up to a whole multiplayer like SL:MP.

Where Lua scripts are used

  • On SA:MP role-play servers: faction helpers, binders, automating routine actions. One example is Police Tools for Advance RP police factions.
  • In interfaces: windows, menus and editors built with Dear ImGui (see ImGUI Editor).
  • In networking experiments: player sync, custom protocols, multiplayer.
  • In developer utilities: debugging, coordinate visualisation, editors.

Getting started

  1. Install a clean GTA: San Andreas (v1.0 US), ASI Loader and MoonLoader.
  2. Learn basic Lua 5.1 syntax.
  3. Read the documentation and Lua sections on BLAST.HK, where most of the community's knowledge lives.
  4. Start small (a chat command, a key bind), then add an ImGui interface.

Frequently asked questions

What is MoonLoader?

MoonLoader is a Lua script loader for GTA: San Andreas distributed by the BLAST.HK community. It hooks into the game as an ASI plugin and lets you write modifications in Lua instead of CLEO scripts.

Why use Lua instead of CLEO?

Lua is a full programming language: tables, functions, modules, string and file handling, and FFI for calling native code. Lua code is far easier to read, debug and maintain than low-level CLEO opcodes.

Do Lua scripts work on SA:MP servers?

Yes. MoonLoader scripts run inside the game client, including when playing on SA:MP servers. Always follow the rules of the specific server – many projects forbid scripts that give a gameplay advantage.

See also