Compatibility and Troubleshooting.md

Compatibility and Troubleshooting

This page is for debugging broken mods, missing autoloads, hook issues, package problems, and conflicts.

First Checks

Before deep debugging:

• Confirm OrcKit appears in the main menu.
• Confirm the mod is in the game's mods folder.
• Confirm the mod is enabled in the Mods menu.
• Confirm you clicked the launch button after changing mods.
• Confirm the package has mod.txt at the root.
• Confirm the package is not duplicated as both folder and archive.

The Mod Does Not Appear

Possible causes:

• The file is not in <game folder>/mods.
• The extension is not .vmz, .zip, or .pck.
• It is a loose folder but Developer Mode is off.
• mod.txt is nested one folder too deep.
• The mod shares an id with another installed mod and lost duplicate selection.

Check the package:

mod.txt
scripts/main.gd

not:

MyMod/mod.txt
MyMod/scripts/main.gd

The Mod Appears But Does Nothing

Check:

• The mod is enabled.
• The autoload is declared correctly.
• The autoload script compiles.
• The autoload path exists.
• Hooks are registered after frameworks_ready.
• Script overrides target the correct vanilla path.

Add a simple print to the autoload:

func _ready() -> void:
	print("[MyMod] autoload ready")

If this does not print, debug the autoload before debugging hooks.

Autoload Path Not Found

If mod.txt says:

[autoload]
MyMod="res://scripts/my_mod/main.gd"

the archive must contain:

scripts/my_mod/main.gd

Case and spelling matter.

Hooks Do Not Fire

Check:

• [hooks] declares the target script.
• The method name exists in the vanilla script.
• The method is not static.
• The hook name uses the correct script stem.
• The callback signature matches the method parameters.
• Registration happens after frameworks_ready.

Example:

[hooks]
res://scripts/player.gd="_ready"

func _install(modlib) -> void:
	modlib.hook("player-_ready-pre", Callable(self, "_before_player_ready"))

Replace Hook Does Not Replace

A no-suffix hook is a replace hook:

modlib.hook("player-_ready", Callable(self, "_replace_ready"))

Call skip_super() inside the callback to stop vanilla from running:

func _replace_ready() -> void:
	Engine.get_meta("OrcmodLib").skip_super()

If you do not call skip_super(), OrcKit runs vanilla after your replacement callback.

Script Override Does Not Apply

Check:

• The vanilla path is exact.
• Your replacement script path exists.
• Another higher-priority mod is not overriding the same path.
• Developer Mode conflict report does not show a later winner.
• The script compiles.

Use declared overrides instead of dynamic take_over_path() when possible.

Conflicts

Developer Mode writes:

user://modloader_conflicts.txt

If two mods claim the same path, the last loaded mod wins.

Use priority to intentionally order compatibility patches:

priority=100

Safe Mode and Disabled Sentinel Files

Advanced recovery files can be placed beside the game executable:

modloader_safe_mode
modloader_disabled

modloader_disabled makes OrcKit sit idle.

modloader_safe_mode tells OrcKit to reset to a clean state.

Remove the sentinel file when you want OrcKit to run normally again.

Stale Behavior After Changing Mods

OrcKit uses a two-pass restart and cached state for mounted archives and hook packs.

Try:

1. Launch unmodded from the Mods menu.
2. Disable the mod.
3. Launch.
4. Re-enable the mod.
5. Launch again.

If still broken, use safe mode or remove temporary loader state through the UI reset path.

Debugging Order

Use this order:

1. Confirm package layout.
2. Confirm mod.txt parses.
3. Confirm autoload prints.
4. Confirm API is available.
5. Confirm frameworks_ready fires.
6. Confirm hook declaration exists.
7. Confirm hook registration returns a non-negative id.
8. Confirm conflict report does not show another mod winning.
9. Test with only your mod installed.

Asking for Help

When reporting a problem, include:

• OrcKit version.
• Mod package layout screenshot or file list.
• mod.txt.
• Whether Developer Mode is enabled.
• Any Godot output errors.
• Conflict report if relevant.
• List of other enabled mods.