Mod Package Layout.md

Mod Package Layout

OrcKit mods are mounted into Godot's res:// filesystem. That means the paths inside your archive matter. A clean package layout makes your mod easier to debug and less likely to collide with other mods.

Recommended Folder Layout

During development:

mods/MyCoolMod/
  mod.txt
  scripts/
    my_cool_mod.gd
    hooks.gd
  scenes/
    my_scene.tscn
  resources/
    my_data.tres
  assets/
    icon.png

Packaged for release:

mod.txt
scripts/my_cool_mod.gd
scripts/hooks.gd
scenes/my_scene.tscn
resources/my_data.tres
assets/icon.png

The archive root must contain mod.txt.

Bad Layouts

Do not package an extra parent folder:

MyCoolMod/mod.txt
MyCoolMod/scripts/my_cool_mod.gd

Do not use Windows backslash paths:

scripts\my_cool_mod.gd

Do not scatter files directly at the root unless they are meant to be root-level resources:

mod.txt
my_cool_mod.gd
random_data.tres

This works, but it gets messy quickly and increases the chance of path conflicts.

How Archive Paths Become res:// Paths

Archive entry:

scripts/my_cool_mod.gd

Runtime path:

res://scripts/my_cool_mod.gd

Archive entry:

resources/items/orc_hammer.tres

Runtime path:

res://resources/items/orc_hammer.tres

Use these res:// paths in mod.txt.

mod.txt Placement

Correct:

mod.txt
scripts/mod_main.gd

Incorrect:

MyMod/mod.txt
MyMod/scripts/mod_main.gd

OrcKit explicitly warns about nested mod.txt files because it only reads metadata from the archive root.

Recommended Namespacing

Use a folder named after your mod id:

scripts/my_cool_mod/main.gd
resources/my_cool_mod/config.tres

Then reference:

[autoload]
MyCoolMod="res://scripts/my_cool_mod/main.gd"

Namespacing reduces collisions with other mods that may also have files named main.gd, config.tres, or hooks.gd.

Replacing Vanilla Resources

If you intentionally replace a vanilla file, your archive path must match the vanilla resource path after res://.

For example, if the vanilla game uses:

res://scripts/player.gd

then an archive entry at:

scripts/player.gd

will claim the same path.

Use this carefully. Replacing vanilla resources is the highest-conflict approach. Hooks or script overrides are often easier to reason about.

Tracked Conflict Extensions

OrcKit tracks claims for these resource extensions:

gd, tscn, tres, gdns, gdnlib, scn

If two enabled mods claim the same tracked path, Developer Mode can report the conflict.

Archive Type Guide

Format	Best use	Notes
.vmz	Normal OrcKit releases	Zip-compatible, supports mod.txt metadata
.zip	Development/testing	Same archive expectations as .vmz
.pck	Godot pack releases	Mounts as a pack, but normal mod.txt autoload handling is skipped
Folder	Development only	Requires Developer Mode

Practical Layout Checklist

• mod.txt is at the root.
• Paths use /, not \.
• Your own files are namespaced by mod id.
• Autoload paths exist exactly as declared.
• Hook target paths are vanilla game script paths.
• Override target paths are vanilla game script paths.
• Replacement resource paths are intentional.
• The packaged .vmz has the same root structure as the working loose folder.