Getting Started.md

Getting Started

This page walks through the full first-mod workflow: installing OrcKit for testing, creating a loose folder mod, adding metadata, adding an autoload script, launching with mods, and packaging the result.

1. Install OrcKit in the Game Folder

Copy these into the game folder:

OrcLoader.gd
override.cfg
mods/

Default Steam game path:

C:\Program Files (x86)\Steam\steamapps\common\Sir, We Have an Orc Problem Playtest

override.cfg must contain:

[autoload]
OrcKit="*res://OrcLoader.gd"

Launch the game. If OrcKit is installed correctly, the main menu gets a Mods button.

2. Enable Developer Mode

Open Mods from the main menu and enable Developer Mode.

Developer Mode is important while building mods because it enables loose folder loading:

mods/MyDevMod/

Without Developer Mode, folder mods are hidden and only archive mods are loaded.

Developer Mode also adds verbose logging and compatibility reports, which are useful when you are testing hooks and overrides.

3. Create a Loose Folder Mod

Create this folder:

<game folder>/mods/MyFirstMod/

Inside it:

MyFirstMod/
  mod.txt
  scripts/
    my_first_mod.gd

4. Write mod.txt

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

Field meanings:

• id is the stable internal id. Use lowercase and underscores.
• name is what users see in the Mods menu.
• version helps OrcKit choose between duplicate installs.
• author is display-only.
• priority controls load order.
• [autoload] tells OrcKit to create a node from your script.

5. Write the Autoload Script

extends Node

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

Launch the game with your mod enabled. Check the game output for the print line.

6. Access the Loader API

extends Node

func _ready() -> void:
	if not Engine.has_meta("RTVModLib"):
		print("[MyFirstMod] OrcKit API is not available")
		return

	var modlib = Engine.get_meta("RTVModLib")
	print("[MyFirstMod] OrcKit version: ", modlib.version())

For hook registration, wait until frameworks_ready:

extends Node

func _ready() -> void:
	var modlib = Engine.get_meta("RTVModLib")
	if modlib._is_ready:
		_install(modlib)
	else:
		modlib.frameworks_ready.connect(func(): _install(modlib))

func _install(modlib) -> void:
	print("[MyFirstMod] OrcKit framework is ready")

7. Package the Mod

When the loose folder works, zip the contents of MyFirstMod, not the folder itself.

Correct:

mod.txt
scripts/my_first_mod.gd

Incorrect:

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

Rename the zip to:

MyFirstMod.vmz

Place it in:

<game folder>/mods/MyFirstMod.vmz

Disable or remove the loose folder when testing the packaged version, otherwise duplicate ids can hide one copy.

8. Basic Test Checklist

• The mod appears in the Mods menu.
• The display name is correct.
• The version is correct.
• The mod can be enabled and disabled.
• Autoload scripts run.
• Hook callbacks run after frameworks_ready.
• No mod.txt parse warnings appear.
• The packaged .vmz behaves like the loose folder.
• The mod still works with an otherwise empty mods folder.

Common First-Mod Problems

The mod does not appear

Developer Mode may be off for a loose folder mod, or mod.txt may be nested one folder too deep.

The autoload does not run

Check that the autoload path exists exactly as declared:

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

The packaged mod says invalid package

Open the .vmz with a zip tool and confirm mod.txt is at the top level.

The wrong version loads

If two mods share the same id, OrcKit keeps one. Remove old copies from mods/.