ScriptBridge

A Lua scripting bridge for Hitman 3 using ZHMModSDK, powered by LuaJIT and Sol2.

Features

• LuaJIT Integration: Fast, JIT-compiled Lua scripting
• Sol2 Bindings: Modern C++17 Lua bindings for easy C++/Lua interop
• Full ImGui Support: 200+ ImGui functions exposed to Lua via sol_ImGui
• Hot Reloading: Reload Lua scripts without restarting the game
• Script UI: Scripts can create their own ImGui windows

Installation

1. Download and install ZHMModSDK
2. Download the latest ScriptBridge release
3. Copy ScriptBridge.dll to the ZHMModSDK mods folder (e.g. C:\Games\HITMAN 3\Retail\mods)
4. Launch the game, press ~ (^ on QWERTZ keyboards) and enable ScriptBridge

Building from Source

Prerequisites

• Visual Studio 2022 (with C++ and game development workloads)
• Python 3.x (for generating Sol2 single header)
• Git

1. Clone with submodules

git clone --recurse-submodules https://github.com/mertkug/ScriptBridge.git
cd ScriptBridge

Or if already cloned:

git submodule update --init --recursive

2. Build LuaJIT

Open a Visual Studio Developer Command Prompt and run:

cd libs/LuaJIT/src
msvcbuild.bat

3. Generate Sol2 single header

cd libs/sol2/single
python single.py

4. Build the project

Open the project in Visual Studio or use CMake:

cmake --preset x64-Debug
cmake --build _build/x64-Debug

The built files will be in _build/x64-Debug/:

• ScriptBridge.dll - The mod

Project Structure

ScriptBridge/
├── src/
│   ├── ScriptBridge.cpp      # Main mod implementation
│   ├── ScriptBridge.h
│   ├── features/             # High-level game APIs
│   └── scripting/            # Lua bindings & script management
├── libs/
│   ├── LuaJIT/               # LuaJIT submodule
│   ├── sol2/                 # Sol2 submodule
│   └── sol_ImGui/            # ImGui-Lua bindings (header-only)
├── scripts/                  # Example Lua scripts
│   ├── autorun/              # Scripts loaded automatically
│   └── *.lua
├── cmake/
├── vcpkg/                    # vcpkg submodule
└── CMakeLists.txt

Dependencies

Library	Version	Purpose
ZHMModSDK	v4.0.0-rc.2	Hitman 3 modding framework
LuaJIT	Latest	Lua runtime
Sol2	v3.5.0	C++ Lua bindings
sol_ImGui	Custom fork	ImGui bindings for Lua (header-only, included)

Note: sol_ImGui is included in the repository as a header-only library. No additional setup required.

Lua API

ImGui (200+ functions)

function OnDrawUI()
    ImGui.SetNextWindowSize(300, 200, ImGuiCond.FirstUseEver)
    
    if ImGui.Begin("My Window") then
        ImGui.Text("Hello from Lua!")
        
        if ImGui.Button("Click Me") then
            print("Button clicked!")
        end
        
        -- Sliders, inputs, color pickers, tables, menus, etc.
    end
    ImGui.End()  -- Always call End() after Begin()
end

Game API

-- Player
Game.Player.IsValid()
Game.Player.GetPosition()
Game.Player.SetPosition(x, y, z)
Game.Player.SetInvincible(bool)
Game.Player.SetInvisible(bool)

-- Camera
local cam = Game.Camera.GetCurrent()
cam.Fov = 90 * (3.14159 / 180)

License

See LICENSE for details.