Home

OrcKit Mod Developer Wiki

Welcome to the OrcKit mod developer wiki.

OrcKit is a mod loader for Sir, We Have an Orc Problem Playtest. It mounts mod packages from the game's mods folder, adds a native Mods button to the main menu, supports load order and profiles, and exposes a small runtime API for hooks, autoloads, mod detection, script overrides, and compatibility tooling.

This wiki is written for people making mods, debugging mods, or maintaining compatibility between mods. If you only want to install OrcKit, use the repository README.md.

Quick Facts

Topic	Value
Loader entrypoint	OrcLoader.gd
Loader version documented here	1.0.0
Game	Sir, We Have an Orc Problem Playtest
Mods folder	<game folder>/mods
Main metadata file	mod.txt
Recommended release format	.vmz
Also supported	.zip, .pck, Developer Mode folders
Runtime API key	Engine.get_meta("OrcmodLib")
GitHub wiki sidebar file	_Sidebar.md

What OrcKit Does

OrcKit scans the mods folder beside the game executable, builds a list of installed mods, shows them in its in-game UI, and launches the game with the enabled set. It can mount archives, remember profile-specific enable states, reorder mods by priority, instantiate mod autoloads, generate hook wrappers for selected vanilla scripts, apply script overrides, and report conflicts.

The core idea is simple:

1. A mod is placed in mods/.
2. OrcKit discovers it.
3. The user enables it and chooses priority.
4. OrcKit mounts the package and applies declared behavior.
5. Your mod code runs through autoloads, hooks, overrides, or normal resource replacement.

What OrcKit Loads

Supported mod inputs:

• .vmz archive mods with mod.txt
• .zip archive mods with mod.txt
• .pck Godot packs
• loose folder mods when Developer Mode is enabled

.vmz files are zip-compatible archives. OrcKit converts them into a temporary zip cache when needed, then mounts them through Godot's resource pack system.

Recommended Reading Order

New mod developers:

1. Getting Started
2. Mod Package Layout
3. mod.txt Reference
4. Developer Mode
5. Packaging and Release

Developers writing code-heavy mods:

1. Runtime API
2. Hooks
3. Script Overrides
4. Registry Facade
5. Example Mods

Compatibility and debugging:

1. Loader Lifecycle
2. Load Order and Conflicts
3. Security Scanner
4. Compatibility and Troubleshooting
5. FAQ

Core Concepts

mod.txt

Most OrcKit mods should include a mod.txt file at the archive root. It tells the loader the mod's id, display name, version, author, priority, autoloads, hooks, and script overrides.

Autoloads

Autoloads are mod scripts or scenes that OrcKit adds to the scene tree. They are usually the best place to register hooks, initialize shared state, or run compatibility checks.

Hooks

Hooks let a mod run code before, after, or instead of a selected vanilla method. Hooks are opt-in: declare target scripts in mod.txt, then register callbacks through Engine.get_meta("OrcmodLib").

Script Overrides

Script overrides map a vanilla script path to a replacement script path. They are stronger than hooks and should be used carefully because only one final script can win for a given path.

Load Order

OrcKit sorts enabled mods by priority. Lower numbers load first. Higher numbers load later and win when two mods touch the same resource path.

Developer Mode

Developer Mode enables loose folder mods, verbose logging, and compatibility reports. Use it while building mods. Ship .vmz or .pck files to users.

Minimum Mod Example

mods/MyFirstMod/
  mod.txt
  scripts/
    my_first_mod.gd

[mod]
id="my_first_mod"
name="My First Mod"
version="1.0.0"
author="You"
priority=0

[autoload]
MyFirstMod="res://scripts/my_first_mod.gd"

extends Node

func _ready() -> void:
	print("[MyFirstMod] loaded")

Good Mod Author Habits

• Use a stable, unique [mod] id.
• Keep mod.txt at the root of the package.
• Use explicit autoload paths and hook declarations.
• Keep priority as low as possible for the behavior you need.
• Prefer hooks over full script overrides when possible.
• Document anything that affects compatibility.
• Test with a clean mods folder before publishing.
• Avoid risky OS, process, runtime-code, and object-deserialization APIs.