Instrument Mode allows a mod a chance to inject extra code very early in all Lua states. One mod at a time may be enabled for 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 LuaProfiler. Multiplayer is disabled while an Instrument Mode mod is enabled. The following additions to the usual Data Lifecycle apply:
If the Instrument Mode mod has a file instrument-settings.lua, it is loaded in settings stage before all mods. Settings stage then proceeds as normal.
If the Instrument Mode mod has a file instrument-data.lua, it is loaded in data stage before all mods. Data stage then proceeds as normal. If the Instrument Mode mod has a file instrument-after-data.lua, it is loaded after all mods have completed data-final-fixes.lua.
If the Instrument Mode mod has a file instrument-control.lua, it is loaded in every mod's control stage Lua state before control.lua. Control stage then proceeds as normal.
In all three instrument files, an extra 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.