# 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](Getting-Started.md)
2. [Mod Package Layout](Mod-Package-Layout.md)
3. [mod.txt Reference](mod-txt-Reference.md)
4. [Developer Mode](Developer-Mode.md)
5. [Packaging and Release](Packaging-and-Release.md)

Developers writing code-heavy mods:

1. [Runtime API](Runtime-API.md)
2. [Hooks](Hooks.md)
3. [Script Overrides](Script-Overrides.md)
4. [Registry Facade](Registry-Facade.md)
5. [Example Mods](Example-Mods.md)

Compatibility and debugging:

1. [Loader Lifecycle](Loader-Lifecycle.md)
2. [Load Order and Conflicts](Load-Order-and-Conflicts.md)
3. [Security Scanner](Security-Scanner.md)
4. [Compatibility and Troubleshooting](Compatibility-and-Troubleshooting.md)
5. [FAQ](FAQ.md)

## 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

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

```ini
[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"
```

```gdscript
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.