Mod Manifest (mod.json)#

Every mod directory must contain a file named mod.json or manifest.json at its root. Petrichor reads this file to identify the mod, choose a backend, and verify compatibility before loading anything.

Interactive mod.json Generator#

Use this tool to customize, preview, copy, and download your mod configuration file:

Minimal example#

{
  "id": "my-mod",
  "name": "My Mod",
  "type": "luau",
  "entry": "main.luau",
  "version": "1.0.0",
  "hostVersion": "0.8.0",
  "engineVersion": "1.0.0"
}

Fields#

id (required)#

"id": "my-mod"

A short, unique identifier for your mod. Used in log messages and for internal tracking. Must not contain spaces or special characters.

• Type: string
• Max length: 63 characters

name (optional)#

"name": "My Mod"

A human-readable display name shown in log output. Falls back to id if omitted.

• Type: string
• Max length: 127 characters

type (required)#

"type": "luau"

Selects the backend that will load this mod. Petrichor ships two built-in backends:

• Type: string
• Max length: 31 characters

entry (optional)#

"entry": "main.luau"

Path to the mod's entry-point file, relative to the mod directory. For the luau backend this is the Luau source file that will be compiled and executed. Defaults to main.luau if omitted.

• Type: string
• Max length: 127 characters

version (optional)#

"version": "1.0.0"

The semantic version of the mod package.

• Type: string
• Default: "1.0.0"
• Max length: 31 characters

hostVersion (optional)#

"hostVersion": "0.8.0"

The version of the host game (Courage Reborn) this mod requires.

• If the running game version is lower than hostVersion, the mod will fail to load.

• If the running game version has a higher major or minor version, the mod loads, but Petrichor logs a warning (for a major version mismatch, it warns that the mod may be unstable).

• Type: string

• Max length: 31 characters

engineVersion (optional)#

"engineVersion": "1.0.0"

The version of the Petrichor engine this mod requires.

• If the running Petrichor version is lower than engineVersion, the mod will fail to load.

• If the running Petrichor version has a higher major or minor version, the mod loads, but Petrichor logs a warning.

• Type: string

• Max length: 31 characters

Full example#

{
  "id":            "damage-tweak",
  "name":          "Damage Tweak",
  "type":          "luau",
  "entry":         "src/main.luau",
  "version":       "1.0.0",
  "hostVersion":   "0.8.0",
  "engineVersion": "1.0.0"
}

Optional fields (mod list UI)#

The in-game Installed Mods screen reads these optional keys from mod.json. Petrichor ignores them at load time.

author (optional)#

"author": "Your Name"

Shown as "by ..." in the mod list.

description or desc (optional)#

"description": "Replaces gossip text on Ordon signs."

Short summary under the mod name.

kind (optional)#

"kind": "code"

If kind is omitted, the game infers Code from type: luau, lua or script. Any other type is treated as Assets.

conflicts (optional)#

"conflicts": ["other-mod-id", "another-mod"]

Array of mod id strings. The UI shows a warning when this list is non-empty. The engine does not block loading or resolve conflicts automatically.

loadOrder (optional)#

"loadOrder": 0

Integer used to sort rows in Installed Mods. Lower numbers appear higher. Players can reorder mods in the menu and the game saves the new order.

This value does not change Petrichor's script init order. Luau mods still initialize in filesystem scan order under mods/. Plan cross-mod startup with Petrichor.Events.

enabled (optional)#

"enabled": true

Updated when the player uses the on/off toggle in Installed Mods. At the time of writing this flag is for the mod manager only. Petrichor still loads the mod while mod.json is present.

For a release checklist and folder layout, see Publishing a mod.