Instrument Mode gives a mod the ability to inject extra code very early on in all Lua states. At most one mod may be enabled in Instrument Mode, using the command line argument --instrument-mod modname. This is intended to be used to provide mod development tools and other instrumentation, in combination with the Lua debug library and the LuaProfiler. Multiplayer is disabled while an Instrument Mode mod is in use, as it is not desync-safe. The following additions to the usual Data Lifecycle apply:
If the Instrument Mode mod has an instrument-settings.lua file, it is loaded before all other mods. The settings stage then proceeds as normal.
If the Instrument Mode mod has an instrument-data.lua file, it is loaded before all other mods. The data stage then proceeds as normal. If the Instrument Mode mod has an instrument-after-data.lua file, it is loaded after all other mods have completed their data-final-fixes.lua stage.
If the Instrument Mode mod has an instrument-control.lua file, it is loaded in every mod's Lua state before their own control.lua file. The control stage then proceeds as normal.
In all three instrument files, the additional global function on_error(f) may be used to register an error handler for that Lua state. The handler receives the thrown error object (a LocalisedString) and may return a LocalisedString to be added to the displayed error message.