Reference Manifest

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
category	string	"OTHER"	manager grouping
game_version	string	none	semver range the engine must satisfy
description	string	""	manager detail text
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.

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

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.