Lua Hot Reload

Lua Hot Reload

Lua Hot Reload is a Rivet mod for Scrap Mechanic. It watches the game's Lua

source directories and asks the game to reload changed files through its own

native reload path.

It supports built-in Survival scripts and Lua files from installed mods when

those files are located in directories discovered by the game.

Requirements

• Scrap Mechanic
• Rivet
• Scrap Mechanic SDK
• A Windows installation of the game

The SDK is declared as a dependency, so a Rivet package manager

can install it automatically.

Installation

The recommended installation method is [r2modman for Scrap

Mechanic]( Create or

select a Scrap Mechanic profile, then install Lua Hot Reload package list. r2modman installs Rivet, the SDK, and the required

dependencies into the profile for you.

You do not need to copy files into the Scrap Mechanic installation directory.

For users who need to load the DLL outside r2modman, see [Manual

loading](#manual-loading) below.

The packages are kept together in the profile managed by r2modman:

Mods/

├── BenMcAvoy-ScrapMechanicSDK-0.1.1/

│ └── scrap_mechanic_sdk.dll

└── BenMcAvoy-Lua_Hot_Reload-0.1.2/

└── lua_hot_reload.dll

Start Scrap Mechanic normally through Rivet. The mod starts after Rivet loads

the DLL and installs the native hooks. No separate launcher or command-line

flag is required for normal use.

Manual loading

The hot-reload DLL can also be loaded directly with an injector or with

LoadLibraryW. The Scrap Mechanic SDK must be loadable first because

lua_hot_reload.dll links against scrap_mechanic_sdk.dll and cannot start on

its own.

For manual loading, keep both DLLs in a staging directory outside the Scrap

Mechanic installation directory before loading the hot-reload DLL:

manual-load/

├── scrap_mechanic_sdk.dll

└── lua_hot_reload.dll

Use matching x64 release builds. If the injector uses an absolute DLL path,

Windows will normally search the directory containing that DLL for its native

dependency. An injector that changes the DLL search path should add the

directory containing both files before calling LoadLibraryW. Code that uses

LoadLibraryExW should use LOAD_LIBRARY_SEARCH_DLL_LOAD_DIR with the full

path to lua_hot_reload.dll.

Load scrap_mechanic_sdk.dll first when the injector controls the order, then

load lua_hot_reload.dll. Loading the hot-reload DLL directly also starts its

fallback bootstrap from DllMain, outside the loader lock. If Rivet is already

running, the fallback detects Rivet and leaves startup to Rivet's registered

mod entrypoint.

The manual loading order is therefore:

• Start Scrap Mechanic and wait until its process is available.
• Load scrap_mechanic_sdk.dll from the staging directory.
• Load lua_hot_reload.dll from the staging directory.
• Wait for the game world to finish loading before editing Lua files.

Do not unload either DLL by force while the game is running. The hot-reload DLL

exports LuaHotReload_Unload for injectors that support clean unloading. Call

that export first, wait for it to return, and only then unload the SDK if no

other mod is using it.

How it works

The file watcher uses Windows directory change notifications. It does not poll

the filesystem and it does not execute Lua from a worker thread.

When a Lua file changes:

• The watcher records the change.
• The game thread receives a reload request.
• The game's native cache generation is advanced.
• The game's normal reload routine checks source timestamps and reloads the

changed Lua source.

• The SDK coordinates any class refresh at a safe game callback boundary.

The reload is performed by the game so its normal script ordering,

environments, and dependency handling remain in control.

Notifications

After a successful reload, Windows displays a notification containing the

changed file path. The notification has an Open in VS Code button when VS

Code is installed. If Windows toast delivery is unav