A Lua modding framework for Sniper Ghost Warrior 3, plus a set of mods built on it: a Quake-style bunny hop, an ImGui trainer with a debug console, an NPC spawner, and an in-game map editor that can export layouts as mods.

🤖 This project is vibecoded. Almost all of the code, reverse engineering and documentation was written by an AI (Claude, via Claude Code), directed and play-tested by a human. Every feature was tested in the real game, but the code has not been audited line by line. Read AI disclosure before relying on it, and please report anything odd.

• Mods without replacing game files. sgw3_modloader.asi hooks the game's Lua loader and starts the framework itself, so any number of mods load side by side, even next to mods that replace Scripts/main.lua.
• A small, stable API. Per-frame ticks that survive deaths, checkpoints and level loads; level-load events; keyboard input; logging; and placing/editing objects in levels. Each mod runs isolated: one broken mod can't stop the others.
• Drop-in mods. A mod is a .pak with Scripts/AutoLoad/<mod>/init.lua. That's it.

SGW3.RegisterMod{ name = "Hello World", version = "1.0", author = "you" }
SGW3.OnLevelLoad("hello_world", function(level) SGW3.Log("hello_world", "entered " .. level) end)
SGW3.OnTick("hello_world", function(player, dt)
  if player and SGW3.KeyPressed(0x78) then SGW3.Log("hello_world", "F9 pressed") end   -- F9
end)

Requires Sniper Ghost Warrior 3 3.8.6.53 (GOG). Other builds: the loader detects the mismatch and stays off.

1. Install Ultimate ASI Loader x64: copy its dinput8.dll into <game>\win_x64\.
2. From the latest release, extract SGW3-Mod-Framework into the game folder (adds win_x64\sgw3_modloader.asi).
3. Optional: extract SGW3-Mods too (bunny hop, trainer, map editor).

Logs: %USERPROFILE%\Saved Games\Sniper Ghost Warrior 3\sgw3_mods.log. Details: docs/INSTALL.md.

Start with docs/MODDING_GUIDE.md: API reference, pak layout, compatibility rules and game facts. The hello world example is a complete mod.

Windows, Visual Studio 2022 (C++ workload), CMake 3.21+, Python 3.10+.

git clone --recurse-submodules https://github.com/Gh0stPacket/sgw3-modding-framework
cd sgw3-modding-framework
python tools/build.py
cmake -B build -A x64
cmake --build build --config Release
python tools/package.py 1.0.0

See CONTRIBUTING.md for the dev workflow (hot reload, in-game exec) and repository rules.

modloader/        sgw3_modloader.asi - Lua injection + keyboard bridge (the framework core)
framework/        Framework.lua (the SGW3 API) and examples
mods/bhop/        Bunny Hop
mods/trainer/     Trainer + map editor (Lua) and the ImGui overlay (native/)
tools/            build, packaging, pak extraction, CryXmlB decoding, Lua-API locator, catalog generation
docs/             guides, RE notes, AI disclosure
deps/             Dear ImGui, MinHook (git submodules)

• universal-modder by rehan-remade: the Claude Code plugin this project was built with. Its recon, reverse-engineering, game-automation (in-game screenshots and input for testing) and publishing guidance drove the whole workflow.
• Claude (Anthropic), via Claude Code: wrote the code, the reverse engineering and the docs. See AI disclosure.
• Ultimate ASI Loader by ThirteenAG: loads the plugins.
• Dear ImGui by Omar Cornut: trainer and editor UI.
• MinHook by Tsuda Kageyu: function hooking.
• unluac and Capstone: used to read the game's Lua bytecode and locate the Lua API in the executable (not distributed).
• Sniper Ghost Warrior 3 by CI Games, built on CRYENGINE.

Fan project, not affiliated with or endorsed by CI Games. Single-player only. No game files are included or distributed; the tools read your own installation. Use at your own risk and back up your saves (%USERPROFILE%\Saved Games\Sniper Ghost Warrior 3).

MIT. Third-party components: see THIRD_PARTY_NOTICES.md.