Load Order and Conflicts.md

Load Order and Conflicts

Load order decides which mod wins when multiple mods touch the same path.

Sorting Rules

OrcKit sorts enabled mods by:

1. priority
2. lowercase mod_name
3. lowercase file_name

Lower values load first. Higher priority values load later.

The Winner Rule

When two mods claim the same resource path:

last loader wins

Because higher priority loads later, higher priority wins.

Priority Range

OrcKit clamps priority from:

-999 to 999

Most mods should use:

priority=0

Compatibility patches often use higher values:

priority=100

Filename Priority Fallback

If mod.txt does not declare priority, OrcKit can read a numeric filename prefix:

100-MyMod.vmz

Prefer explicit priority in mod.txt.

Conflict Report

In Developer Mode, OrcKit writes:

user://modloader_conflicts.txt

It reports conflicted paths and marks the winner.

Example concept:

CONFLICT: res://scripts/player.gd
    [1] Balance Mod via BalanceMod.vmz
    [2] Compatibility Patch via CompatPatch.vmz <-- wins

What Counts as a Conflict

OrcKit tracks these extensions:

gd, tscn, tres, gdns, gdnlib, scn

Conflicts are usually caused by:

• replacing the same vanilla script
• replacing the same scene
• overriding the same .tres data
• multiple mods shipping the same root path

Reducing Conflicts

Prefer:

• namespaced files for your own content
• hooks instead of replacing vanilla scripts
• declared script overrides instead of dynamic overrides
• low priority unless you intentionally need to win
• compatibility patches for known overlaps

Avoid:

• root-level generic file names like main.gd
• replacing large vanilla scripts for one small change
• using maximum priority as a default
• silently overriding another mod's path

Compatibility Patch Pattern

If Mod A and Mod B conflict, create a third patch:

[mod]
id="mod_a_mod_b_patch"
name="Mod A + Mod B Compatibility Patch"
version="1.0.0"
priority=100

The patch should load after both mods and intentionally resolve the conflict.

Document:

• required mods
• required versions
• priority
• paths touched
• what behavior is preserved from each mod