How to install MoonLoader and SAMPFUNCS

MoonLoader 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 and Police Tools Lite. Below is the install order and what to check when something doesn't start.

What you need#

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, for example, was built for MoonLoader 0.26. Download everything from 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:

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.

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/:

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.