# MoonLoader and Lua scripting for GTA: San Andreas

> What MoonLoader is, how Lua scripts for GTA: San Andreas and SA:MP work, how they differ from CLEO, which libraries are used and how to get started.

- URL: https://pakulichev.com/en/wiki/moonloader-lua-gta-sa
- Author: Pakulichev (https://pakulichev.com/)
- Language: en
- Updated: 2026-10-15
- Whole site for LLMs: https://pakulichev.com/llms.txt (index), https://pakulichev.com/llms-full.txt (full text)

**MoonLoader** is a **Lua** script loader for GTA: San Andreas. It came out of the Russian-speaking modding community [BLAST.HK](https://www.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](https://pakulichev.com/en/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:

```lua
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](https://pakulichev.com/en/projects/sl-mp).

## Where Lua scripts are used

- On SA:MP role-play servers: faction helpers, binders, automating routine actions. One example is [Police Tools](https://pakulichev.com/en/projects/police-tools) for Advance RP police factions.
- In interfaces: windows, menus and editors built with Dear ImGui (see [ImGUI Editor](https://pakulichev.com/en/projects/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](https://www.blast.hk/), where most of the community's knowledge lives.
4. Start small (a chat command, a key bind), then add an ImGui interface.

## FAQ

### 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.