Skip to content

Installation

You do not need to compile anything to use LuaModLoader. Grab the latest build from the Download page, then follow the steps below.

Supported build

The 2020 Steam re-release of GTA IV, "Complete Edition", build 1.2.0.59, x86. Other builds already have ScriptHookIV and the classic ASI Loader. LuaModLoader exists because those do not work on this one.

Install

The archive contains four files, dinput8.dll, LuaModLoader.dll, Scintilla.dll and Lexilla.dll, plus an empty mods/ folder.

  1. Open the root folder of GTA IV, the one containing GTAIV.exe.
  2. Copy everything from the archive into that same folder, the four files and the mods/ folder. If you already have a mods/ folder, keep yours: the one in the archive is empty and has nothing to bring.

That is all. Nothing is renamed and no file of the game is replaced: the game does not ship a dinput8.dll, so the one from the archive is simply picked up at launch, exactly the way Ultimate ASI Loader is.

Launch the game. Press F6 at any time to open the built-in Lua editor.

Already using Ultimate ASI Loader?

Its dinput8.dll and ours occupy the same slot, so ours replaces it. Say yes when Windows asks to overwrite. Your .asi plugins keep working: LuaModLoader loads them itself, from the game folder, plugins/ and scripts/, and it speaks the same protocol, so FusionFix and the other plugins written for Ultimate ASI Loader initialise the way they expect.

To uninstall: delete the four copied files. Put Ultimate ASI Loader's dinput8.dll back if you had one.

Upgrading from v1.2.0

Up to v1.2.0 the proxy was called binkw32.dll, and the install had you rename the game's own file to binkw32_orig.dll. That slot does not hold on Complete Edition: Rockstar's integrity wrapper restores the game's binkw32.dll about fifteen seconds after launch, so the proxy only ever worked for one session after each copy. Undo that install first:

  1. Delete the binkw32.dll that came from the LuaModLoader archive.
  2. Rename binkw32_orig.dll back to binkw32.dll. If the game already put a fresh binkw32.dll back by itself, just delete binkw32_orig.dll.
  3. Copy the four files from the new archive as described above.

Your mods/ folder is not affected.

Where the files end up

📁 Grand Theft Auto IV/
├── 📄 GTAIV.exe
├── 📄 dinput8.dll          <-- from the archive
├── 📄 LuaModLoader.dll
├── 📄 Scintilla.dll
├── 📄 Lexilla.dll
├── 📄 LuaModLoader.log     <-- created at runtime
├── 📄 asi_loader.log       <-- created at runtime
├── 📁 plugins/             <-- optional, your .asi plugins
└── 📁 mods/
    └── 📁 MyFirstMod/
        ├── 📄 manifest.lua
        └── 📄 main.lua

Everything lives in the game folder, including your mods. Ready to write one? Head to Your first Lua mod.

When the game folder is read-only

Some installs (Rockstar Games Launcher under Program Files, for one) refuse writes without administrator rights. LuaModLoader checks once at launch and, if the game folder cannot be written, keeps its logs and its cache under %LOCALAPPDATA%\LuaModLoader\ instead. Look there when you do not find a log next to GTAIV.exe.

ASI plugins

LuaModLoader doubles as an ASI loader, which the classic one can no longer do on this build. Drop any .asi file next to GTAIV.exe, in plugins/ or in scripts/, and it is loaded at startup, before the Lua engine. Plugins that patch memory early, such as the fastman92 limit adjuster, fixes and ASI trainers, therefore install themselves first.

Every load, success or failure, is written to asi_loader.log with its Windows error code. That file is the first place to look when a plugin does nothing.

Log files and troubleshooting

File Contents
LuaModLoader.log Startup, hooks, mod scan, Lua errors
asi_loader.log The proxy: file redirections, streaming archives, one line per .asi found, loaded or failed
asi_loader_crash.log Written only when the game dies: each access violation with its module and offset

LuaModLoader.log uses [info] / [warn] / [error] levels. Periodic and per-frame traces sit at [debug] and write nothing by default. They used to bury real errors under hundreds of kilobytes per session.

Turning debug logging back on

Drop an empty file named LuaModLoader.debug next to the log. LuaModLoader checks for it once, on the first log call, and says so in the log when it finds it. Witness files are always looked up next to the log, so if your log lives under %LOCALAPPDATA%\LuaModLoader\, that is where the witness goes too.

Common symptoms:

  • Nothing happens, no log file. LuaModLoader never loaded. Check that dinput8.dll sits right next to GTAIV.exe, not in a subfolder, and look for the logs under %LOCALAPPDATA%\LuaModLoader\ before concluding.
  • It worked once, then never again. You are still on the v1.2.0 binkw32.dll proxy, which the game restores after each launch. Follow Upgrading from v1.2.0.
  • Input.IsKeyDown always returns false. This is deliberate: key reads return false unless one of our own windows has focus, which means GTA IV itself or the standalone editor. Switch to a browser or to Discord and keys stop being read. The in-game F6 editor also swallows keys while you are typing in it.
  • A mod does not autostart. Check its manifest.lua, described in Mod structure. Mods start on the first tick that is genuinely in-game, never during the loading screen.
  • The game crashes at launch with episode content on. Drop an empty LuaModLoader.noepisodes next to the log to turn the episode bridge off for one launch, and send asi_loader_crash.log on the Discord.