# How to install MoonLoader and SAMPFUNCS

> Installing MoonLoader and SAMPFUNCS for GTA: San Andreas and SA:MP 0.3.7-R1: what to download, where the files go, how the moonloader folder is laid out and how to check the log.

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

# How to install MoonLoader and SAMPFUNCS

[MoonLoader](https://pakulichev.com/en/wiki/moonloader-lua-gta-sa) loads Lua scripts into GTA: San Andreas, and SAMPFUNCS adds functions for working with the SA:MP client. Almost every script for role-play servers needs both, including my [Police Tools](https://pakulichev.com/en/projects/police-tools) and [Police Tools Lite](https://pakulichev.com/en/projects/police-tools-lite). Below is the install order and what to check when something doesn't start.

## What you need

| Component | Why |
| --- | --- |
| GTA: San Andreas 1.0 US | the executable the plugins are built for |
| ASI Loader | loads .asi plugins when the game starts |
| MoonLoader | the Lua script loader itself |
| SA:MP 0.3.7-R1 | the client SAMPFUNCS is compatible with |
| CLEO | a library SAMPFUNCS won't start without |
| SAMPFUNCS | SA:MP functions for Lua: chat, commands, players, dialogs |

The game version matters more than anything else. Plugins work with the memory of a specific gta_sa.exe, and on the Steam release or other editions the addresses won't match. A Steam copy has to be downgraded to 1.0 US first.

My [Speeder radar](https://pakulichev.com/en/projects/police-radar), for example, was built for MoonLoader 0.26. Download everything from [BLAST.HK](https://www.blast.hk/), where the authors of MoonLoader and SAMPFUNCS publish them. Builds from file hosts and YouTube "packs" often carry extra .asi files, and figuring out which one breaks the game takes longer than a clean install.

## Install order

1. Back up the game folder. Restoring a copy is easier than hunting for a stray file.
2. Install SA:MP 0.3.7-R1 into the game folder.
3. Put ASI Loader in the root, next to gta_sa.exe. Many game builds already include one; you don't need a second.
4. Unpack the MoonLoader archive into the game root. You'll get the loader's .asi file and a `moonloader` folder.
5. Install CLEO, then SAMPFUNCS. SAMPFUNCS is also unpacked into the game root.
6. Launch the game through SA:MP and join any server.

The CLEO → SAMPFUNCS order matters: SAMPFUNCS looks for CLEO on startup and won't load without it.

## The moonloader folder

After installing and running the game once, the root will look roughly like this:

```text
GTA San Andreas/
  gta_sa.exe
  moonloader/
    lib/
    config/
    moonloader.log
    my_script.lua
```

`moonloader/` holds the scripts themselves: every .lua or .luac file there is loaded on game start. `moonloader/lib/` holds libraries that scripts pull in with `require`, such as `inicfg`, `encoding`, `vkeys` or imgui. `moonloader/config/` is where scripts keep their settings. Police Tools Lite, for example, stores binds in `PToolsLite.list` and settings in `PToolsLite.cfg` there. Working with that folder from your own code is covered in the article on [inicfg and CP1251](https://pakulichev.com/en/wiki/moonloader-config).

To remove a script, just take its file out of `moonloader/`. Its config in `config/` stays, so a reinstalled script picks up the old settings.

## Checking that it works

The main diagnostic tool is `moonloader.log` in the `moonloader` folder. MoonLoader writes to it on every launch: which version loaded, which scripts were found, which crashed and with what error. If there is no log at all, MoonLoader didn't load, and the cause is ASI Loader or the game version.

The quickest test is a `test.lua` file in `moonloader/`:

```lua
script_name("test")

function main()
  while not isSampAvailable() do wait(100) end
  sampAddChatMessage("MoonLoader and SAMPFUNCS are working", 0x33AA33)
end
```

If a green line shows up in chat after you join a server, both parts work: MoonLoader ran the script and SAMPFUNCS provided `sampAddChatMessage`. If there's no line and the log shows an error like `attempt to call global ... (a nil value)` for a samp-prefixed function, MoonLoader works and SAMPFUNCS doesn't. Russian text appears as garbage if the file is saved in UTF-8, since SA:MP expects CP1251.

## Common problems

The game crashes on startup. Almost always it's the gta_sa.exe version or two ASI Loaders conflicting. Check that the executable is 1.0 US and that the root doesn't contain two loaders under different names.

The log is empty or never created. An antivirus may have deleted or blocked the .asi file: these plugins inject into another process, and heuristics react to that. If you trust the source, add the game folder to exclusions and reinstall MoonLoader.

SAMPFUNCS doesn't load. Check the SA:MP client version: it has to be 0.3.7-R1. The other usual cause is missing CLEO.

The script is in the folder but does nothing. Open `moonloader.log` and search for the script's name. There's usually a line number with the error or the name of a library missing from `moonloader/lib/`.

Before installing any script, read your server's rules. Many role-play projects allow binders and helpers but forbid anything that gives a gameplay advantage.

## FAQ

### Do I need SAMPFUNCS if a script doesn't use SA:MP?

No. MoonLoader also runs in single player without SAMPFUNCS. The plugin is needed by scripts that call sampSendChat, sampRegisterChatCommand and other functions with the samp prefix.

### Where do I put a downloaded script?

The .lua or .luac file goes straight into the moonloader folder in the game root. Libraries the script requires go into moonloader/lib unless the author says otherwise.

### Why did a script stop working after a SA:MP update?

SAMPFUNCS is tied to a specific SA:MP client version. If the client was updated to another revision, the plugin and the scripts that depend on it won't load until a compatible client is back in place.