mod txt Reference.md

mod.txt Reference

mod.txt is a Godot ConfigFile read by OrcKit. It uses INI-style sections and key-value pairs.

Keep mod.txt at the root of your .vmz, .zip, or Developer Mode folder.

Complete Example

[mod]
id="example_mod"
name="Example Mod"
version="1.0.0"
author="Your Name"
priority=0

[autoload]
ExampleMod="res://scripts/example_mod/main.gd"

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

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

[registry]
enabled=true

You do not need every section. A simple autoload mod only needs [mod] and [autoload].

Syntax Rules

Use quoted strings for text values:

name="My Mod"
version="1.0.0"

Use plain numbers for numeric values:

priority=25

Avoid trailing comments on values while debugging parse issues. Godot ConfigFile syntax is stricter than some INI parsers.

[mod]

[mod]
id="example_mod"
name="Example Mod"
version="1.0.0"
author="Your Name"
priority=0

id

Stable unique id for your mod.

Recommended style:

lowercase_words

Examples:

id="orc_balance_patch"
id="extra_maps"
id="estonias_big_content_pack"

Do not change the id between releases unless you intentionally want OrcKit to treat the new version as a different mod.

name

Display name shown in the Mods menu.

name="Extra Maps"

version

Version string used in duplicate selection and has_mod(id, min_version).

version="1.2.0"

OrcKit compares numeric dot-separated parts. Non-numeric parts are treated as 0 by the helper comparison.

author

Display-only author field.

author="Your Name"

priority

Load order value clamped from -999 to 999.

priority=0

Lower priority loads earlier. Higher priority loads later and wins when multiple mods claim the same resource path.

If priority is missing, OrcKit can also read a filename prefix:

100-MyMod.vmz

Explicit priority in mod.txt is clearer.

Duplicate Mod IDs

For .vmz, .zip, and folder mods with a valid id, OrcKit deduplicates by id.

If multiple copies share the same id:

1. Highest version wins.
2. If versions tie, newest modified file wins.
3. If still tied, file name breaks the tie.

This prevents users from accidentally loading multiple versions of the same mod.

[autoload]

[autoload]
ExampleMod="res://scripts/example_mod/main.gd"

Each key is the node name OrcKit tries to add to /root. Each value is a res:// path to a GDScript or PackedScene.

Script autoload

[autoload]
ExampleMod="res://scripts/example_mod/main.gd"

extends Node

func _ready() -> void:
	print("loaded")

Scene autoload

[autoload]
ExampleScene="res://scenes/example_mod/autoload_scene.tscn"

The scene must instantiate into a valid Node.

Early autoload

Prefix the path with !:

[autoload]
ExampleEarly="!res://scripts/example_mod/early.gd"

Early autoloads are written after OrcKit in override.cfg for the restart pass. Use this only when your script needs to exist very early in the engine lifecycle.

Duplicate autoload names

Autoload names must be unique. If two mods declare the same name, OrcKit skips later duplicates.

Use a mod-specific prefix:

[autoload]
ExampleModMain="res://scripts/example_mod/main.gd"

[hooks]

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

The key is a vanilla script path. The value is a comma-separated list of method names to wrap.

Wrap all methods:

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

Or with an empty value:

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

Prefer specific methods. Wrapping every method costs more and creates a larger compatibility surface.

[script_overrides]

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

The key is the vanilla path. The value is your replacement script.

The replacement script should keep the behavior and shape expected by scenes and other scripts. If the original has important properties or methods, preserve them.

[script_extend]

Accepted as an alias-style section for the same mapping behavior as [script_overrides]:

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

Internally, OrcKit processes both sections as pending script overrides.

[registry]

[registry]
enabled=true

Declaring [registry] opts into OrcKit's generic registry wrapper surface. The project-specific bundle helpers are not implemented for this game yet, so use the registry facade for shared mod data rather than native game content registration.

Minimal Templates

Autoload-only mod

[mod]
id="autoload_only"
name="Autoload Only"
version="1.0.0"
author="You"
priority=0

[autoload]
AutoloadOnly="res://scripts/autoload_only/main.gd"

Hook mod

[mod]
id="hook_example"
name="Hook Example"
version="1.0.0"
author="You"
priority=0

[autoload]
HookExample="res://scripts/hook_example/main.gd"

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

Override mod

[mod]
id="override_example"
name="Override Example"
version="1.0.0"
author="You"
priority=50

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

Validation Checklist

• mod.txt is root-level.
• Every section header has square brackets.
• String values are quoted.
• id is stable and unique.
• version is updated before release.
• priority is intentional.
• Autoload names are unique.
• Autoload paths exist.
• Hook target paths are vanilla paths.
• Override target paths are vanilla paths.