Script Overrides.md

Script Overrides

Script overrides replace a vanilla script path with a mod script path.

Use them when you need to change large parts of a script and hooks are not enough. Overrides are powerful, but they are more conflict-prone than hooks because only one final script can own a path.

Declaration

[script_overrides]
res://scripts/vanilla_script.gd="res://scripts/my_mod/vanilla_script_override.gd"

[script_extend] is also accepted:

[script_extend]
res://scripts/vanilla_script.gd="res://scripts/my_mod/extended_script.gd"

Both sections are processed as pending script overrides.

Load Order

Overrides are sorted by mod priority. Higher priority mods apply later, so they win if multiple mods target the same vanilla path.

Example:

Mod A priority 0 overrides res://scripts/player.gd
Mod B priority 50 overrides res://scripts/player.gd

Mod B wins.

Replacement Script Shape

Your replacement script should be compatible with everything that expects the original script.

Preserve:

• base class or expected inheritance behavior
• exported properties used by scenes
• public methods called by other scripts
• signal names and connection assumptions
• important lifecycle methods

If a vanilla scene expects fields that your override removed, the scene may load but fail later.

Compatibility-Friendly Override Pattern

Start by copying only what you must change.

extends "res://scripts/player.gd"

func some_method() -> void:
	# Custom behavior.
	super.some_method()

This pattern depends on the game's script structure and may not work for every target, but it is often safer than replacing everything.

Declared Override vs Dynamic take_over_path

OrcKit detects scripts that call take_over_path(...) or similar dynamic override behavior and prints timing warnings in Developer Mode.

Prefer declared overrides:

[script_overrides]
res://scripts/player.gd="res://scripts/my_mod/player_override.gd"

Declared overrides are visible to the loader, participate in priority sorting, and show up in conflict reports.

Autofix Helpers

When applying override scripts, OrcKit attempts some compatibility repairs:

• bodyless legacy syntax
• tool to @tool
• onready to @onready
• export to @export
• old base() calls to super

These are compatibility helpers. Do not rely on them as your normal authoring workflow.

Conflicts

In Developer Mode, OrcKit reports conflicting resource paths:

user://modloader_conflicts.txt

If two mods override the same path, the later-loaded mod wins.

When to Use Hooks Instead

Use hooks when:

• you only need to run before or after one method
• you only need to alter a return value
• you want better compatibility with other mods
• you do not need to replace exported fields or script-level structure

Use script overrides when:

• the vanilla method is too large to patch cleanly with hooks
• you need to change script-level state
• you need to replace several related methods together
• you are intentionally making a compatibility patch for another override

Testing Checklist

• Test with only your mod installed.
• Test with Developer Mode enabled and inspect conflicts.
• Test with common mods that target nearby systems.
• Confirm load priority behaves as intended.
• Confirm no required vanilla methods or fields were accidentally removed.
• Confirm scenes that use the script still instantiate correctly.