Loader Lifecycle.md

Loader Lifecycle

This page explains what OrcKit does during startup. Understanding the lifecycle helps when debugging hooks, autoload timing, script overrides, and restart behavior.

High-Level Flow

1. Godot loads override.cfg.
2. OrcLoader.gd is added as an autoload named OrcKit.
3. OrcKit waits one process frame.
4. OrcKit compiles its regex helpers.
5. OrcKit discovers game scripts and class names.
6. OrcKit loads Developer Mode and UI settings.
7. OrcKit scans the mods folder.
8. The Mods UI appears.
9. Enabled mods are mounted and processed.
10. Hooks, overrides, and autoloads are prepared.
11. OrcKit may restart the game for a second pass.
12. The runtime API is registered as Engine.get_meta("OrcmodLib").
13. frameworks_ready is emitted.
14. The current scene may be reloaded so mounted resources take effect.

Two-Pass Startup

Godot resource packs sometimes need to be mounted early to affect all resources consistently. OrcKit handles this with a restart pass.

Pass 1

Pass 1:

• scans mods
• shows the Mods UI
• writes selected archive state
• writes early autoloads into override.cfg
• generates a hook pack
• requests a restart with --modloader-restart

Pass 2

Pass 2:

• mounts previously selected archives at file scope
• restores pending script overrides
• rescans mods
• applies overrides
• generates and mounts hook wrappers
• instantiates autoloads
• emits frameworks_ready

State Hash

OrcKit computes a state hash from:

• enabled archive paths
• archive modified times
• mod versions
• early autoload declarations
• script overrides
• loader version
• loader file modified time

If the hash has not changed, OrcKit can skip an unnecessary restart.

Runtime API Registration

OrcKit registers:

Engine.set_meta("OrcmodLib", self)

Mods access:

var modlib = Engine.get_meta("OrcmodLib")

frameworks_ready

frameworks_ready means OrcKit has registered core hooks and the runtime facade is ready.

Register hooks after this signal:

if modlib._is_ready:
	_install(modlib)
else:
	modlib.frameworks_ready.connect(func(): _install(modlib))

Scene Reload

After mounting packs and instantiating autoloads, OrcKit may reload the current scene. This helps mounted resources and script rewrites take effect.

If your autoload stores state during startup, be aware that the current scene may reload after mods are applied.

Recovery

OrcKit writes heartbeat and pass-state files while launching. If a crash happens during startup, crash recovery can reset to a cleaner state.

Advanced sentinel files beside the game executable:

modloader_safe_mode
modloader_disabled

Use these only for recovery or debugging.