Manifest reference

Every mod is a directory under mods/ with a manifest.json beside its entry file. Manifest v2 is a superset of v1: a manifest written for the first API still validates unchanged.

Fields

Field	Type	Default	Meaning
`id`	string	required	`[A-Za-z0-9_-]+`, unique across installed mods
`name`	string	required	display name in the manager
`version`	string	required	your own version; semver if you want other mods to range-check it
`entry`	string	required	Lua file run at load time, relative to the mod dir
`api`	number	`1`	mod API this mod is written against; `2` is the current one
`priority`	number	`0`	lower loads first, after dependencies
`dependencies`	array	`[]`	`"id"` or `"id@<range>"`; enforced
`optional_dependencies`	array	`[]`	same syntax; ordering and `mod.find` only
`conflicts`	array	`[]`	`"id"` or `"id@<range>"`; enforced
`incompatible`	array	`[]`	alias for `conflicts`; merged into it at validate (same `"id"` / `"id@<range>"` syntax)
`category`	string	`"OTHER"`	manager grouping
`game_version`	string	none	semver range the engine must satisfy
`description`	string	`""`	manager detail text
`github`	string	none	`"owner/repo"` or a `github.com` URL; enables launcher auto-update and Other versions
`experimental`	boolean	`false`	when true, the mod stays off until the player enables it (with a confirm dialog)
`profile`	string	`"content"`	`content`, `overhaul` or `total_conversion`
`affects_link`	boolean	`true` unless `profile` is `content`	whether the mod is expected to move the link fingerprint
`permissions`	array	`[]`	`network`, `filesystem`, `engine_internals`
`options_schema`	string	none	file declaring the mod's options; must exist
`assets_transforms`	string	none	file declaring asset transforms; must exist

api above the number this engine provides is refused with requires mod API <n>; this engine provides <m>. An unknown profile or permission is a load error at api = 2 and an attributed warning at api = 1, where it falls back to content and to no permission.

Version ranges

The same grammar serves game_version and the @range half of a dependency or conflict entry.

Form	Matches
`1.2.3`	exactly that version (`=1.2.3` is the same)
`>=1.0`	that version or later; also `>`, `<`, `<=`
`^1.2`	`>=1.2 <2.0`; the caret pins the leftmost non-zero component, so `^0.2` is `>=0.2 <0.3`
`>=1.0 <2.0`	space-separated comparators all have to hold
`^1.4 \|\| ^2.0`	`\|\|` separates alternatives

Missing components default to zero (1.2 is 1.2.0) and a pre-release sorts before its release (1.0.0-beta < 1.0.0). A malformed range fails manifest validation, so a typo is caught before the mod runs.

Dependencies and conflicts

Resolution runs over the enabled mods and fails only the mods that cannot be satisfied. A hard dependency that is missing, disabled, failed, or outside its declared range fails the mod that declared it, and anything depending on that mod fails in turn. optional_dependencies never fail a mod: they order the load so a present target is already loaded when mod.find asks for it.

A conflicts entry that is co-enabled fails the declaring mod -- it asserted the incompatibility, so the outcome does not depend on priority. Two mods naming each other both fail, and the manager offers to switch one off. incompatible is the same list under a friendlier name: both arrays are merged (first-wins on duplicate entries) before conflict checks run.

A dependency cycle fails exactly the mods in the cycle. Mods beside it load normally.

GitHub and experimental

github is optional. When set, the launcher MODS panel can check that repo's GitHub Releases for installable .zip assets: Update installs a newer release, Versions lets the player pick any published release (including older ones) to roll forward or back. Accepts owner/repo or a https://github.com/owner/repo URL; the loader normalizes both to owner/repo. A malformed value fails validation. Absent or empty means no auto-update UI for that mod.

experimental defaults to false. When true:

a missing options.mods[id] entry means disabled (normal mods default to enabled)
enabling in the launcher or in-game manager asks for confirmation ("this mod is marked experimental")
the MODS panel badges the row EXPERIMENTAL

Permissions

Permissions are disclosure, not a sandbox. The manager shows them before you enable a mod; nothing is blocked at runtime.

Permission	Covers
`network`	link play, sockets, anything that reaches the wire
`filesystem`	writing outside the mod's own directory
`engine_internals`	requiring or patching modules outside the mod API

Run with POKEPORT_DEV=1 while developing: a mod that requires a private engine module without declaring the matching permission logs one warning per module, naming the mod and the module. Declare the permission or move to the supported surface.

Home

Start here

Concepts

Tutorials

Reference

Guides

Playing

Engine 1.0.0 · mod API 2 · repository · Discord

This project ships no ROM data. All game content is decoded on the player's machine from their own verified Pokemon Red ROM; mods ship recipes and original assets, never extracted content.