Packaging and Release.md

Packaging and Release

This page covers preparing a mod for users after it works as a Developer Mode folder.

Recommended Release Format

Use .vmz for normal OrcKit mod releases.

A .vmz is a zip-compatible archive renamed to .vmz.

Build the Archive

Start from your working mod folder:

MyMod/
  mod.txt
  scripts/
  resources/

Open the folder and zip the contents, not the folder itself.

Correct archive:

mod.txt
scripts/main.gd
resources/data.tres

Incorrect archive:

MyMod/mod.txt
MyMod/scripts/main.gd
MyMod/resources/data.tres

Rename:

MyMod.zip

to:

MyMod.vmz

File Paths

Use forward slashes inside the archive:

scripts/main.gd

Avoid backslashes:

scripts\main.gd

OrcKit warns about backslash entries because they can break res:// path resolution.

Release Metadata

Before release, update:

[mod]
id="my_mod"
name="My Mod"
version="1.2.0"
author="You"
priority=0

Use semantic-ish versions where possible:

1.0.0
1.1.0
1.1.1

This helps duplicate detection and compatibility checks.

Choosing Priority

Most mods should use:

priority=0

Use a higher priority when your mod intentionally must win conflicts, such as compatibility patches:

priority=100

Avoid using 999 by default. If every mod uses maximum priority, load order stops being meaningful.

Clean Install Test

Before publishing:

1. Move every other mod out of mods/.
2. Put only your packaged .vmz in mods/.
3. Launch OrcKit.
4. Enable your mod.
5. Launch with mods.
6. Confirm the feature works.
7. Restart once more and confirm it still works.

This catches folder-only assumptions and stale cache issues.

Compatibility Test

Then test with likely overlapping mods:

• mods that change the same scripts
• mods that replace the same scenes
• mods with similar gameplay scope
• compatibility patches

Use Developer Mode and read the conflict report.

Safety Scanner Readiness

OrcKit scans mods for risky patterns. Avoid unnecessary use of process spawning, shell opening, runtime code generation, and object deserialization.

If your mod legitimately needs a flagged API, disclose why in your release notes.

Example release note:

This mod opens an HTTPS URL only when the user clicks the documentation button.
It does not run local files or external programs.

Release Checklist

• mod.txt is at archive root.
• id is unique and stable.
• version is updated.
• author is filled in.
• Priority is intentional.
• Autoload paths exist.
• Hook targets exist.
• Override paths exist.
• Archive paths use /.
• The loose folder is not installed during package testing.
• A clean install test passes.
• Compatibility notes are written.
• Known conflicts are documented.

Suggested Release Description Template

# My Mod v1.0.0

## Requires

- OrcKit 1.0.0
- Sir, We Have an Orc Problem Playtest

## Install

1. Install OrcKit.
2. Put `MyMod.vmz` into the game's `mods` folder.
3. Launch the game.
4. Open Mods and enable `My Mod`.
5. Launch with mods.

## Compatibility

- Priority: 0
- Hooks: `player-_ready-pre`
- Overrides: none
- Known conflicts: none

## Changelog

- Initial release.