pack.toml reference

This page is the canonical reference for pack.toml. For a guided tour, see the Quickstart.

Top-level keys

Key	Type	Required	Notes
manifest	int	yes	Manifest schema version. Currently 1.
id	string	yes	Reverse-DNS Pack ID, e.g. org.mobrule.hello-world.
name	string	yes	Human-readable Pack name.
version	string	yes	SemVer-style version.
mpp	string	yes	MPP version requirement (SemVer range).
authors	array	no	List of author names / handles.

The Pack’s manifest_hash is a deterministic SHA-256 over the canonicalised Manifest. Equal content in, equal hash out — across Linux and Windows. Cosmetic edits (whitespace, comments, key reordering) do not change the hash; semantic edits (adding or renaming Events, changing a schema body, changing version) do. Compute it with mobrule pack print-hash <pack-dir>.

[adapter]

Tells the bridge how to launch the Adapter process.

[adapter]
command = "python3"
args    = ["-u", "adapter.py"]
restart = "on_crash"

[queues.<name>]

Every Pack must declare at least one queue. Within a queue, the bridge dispatches Invocations strictly one at a time; different queues are independent, so an Adapter can work N queues concurrently.

[queues.default]
ready_after = "applied"

Key	Type	Required	Notes
ready_after	string	no	"applied" (default) or "done" — when the queue is free to dispatch the next Invocation. See Dispatch semantics.

Use ready_after = "done" for queues whose effects must fully complete in-game before the next Invocation begins.

[events.<name>]

Each Event the Pack exposes. Required sub-keys:

• summary — short human description.
• queue — the declared [queues.<name>] this Event dispatches through.
• params_schema — a JSON Schema object describing the Invocation params.

Each property in params_schema.properties may be marked "x-mobrule-viewer-override" = true to let chat-time inputs override the default value at Cue-fire time.

[state.<key>]

Optional. Declares a Pack-state key the Adapter (or platform) can write at runtime, e.g. a counter an overlay widget subscribes to.

[state.play_count]
writer = "adapter"
[state.play_count.params_schema]
type = "integer"
minimum = 0

Key	Type	Required	Notes
writer	string	yes	Who may write the key. "adapter" lets your Adapter send state_write frames for it.
persist	bool	no	true to store the last value durably and replay it to the Adapter on reconnect. Default false.
params_schema	table	no	JSON Schema the written value must validate against.

[pack_config]

Optional. A JSON Schema describing the broadcaster-configurable settings the Pack exposes in the UI’s Pack Config editor. See Pack Config.

Full example

manifest = 1
id       = "org.mobrule.hello-world"
name     = "Hello World"
version  = "0.1.0"
mpp      = "1"
authors  = ["mobrule"]

[adapter]
command = "python3"
args    = ["-u", "adapter.py"]
restart = "on_crash"

[queues.default]
ready_after = "applied"

[state.play_count]
writer = "adapter"
[state.play_count.params_schema]
type = "integer"
minimum = 0

[events.play_sound]
summary = "Log a play-sound notification."
queue   = "default"
[events.play_sound.params_schema]
type = "object"
additionalProperties = false
required = ["sound_id"]
[events.play_sound.params_schema.properties.sound_id]
type = "string"
maxLength = 64
"x-mobrule-viewer-override" = true

See also

• Quickstart — the 15-minute walkthrough.
• Defining Events — params_schema patterns.
• MPP protocol — what the bridge does with these definitions.