Guide for AI and Codex contributors

This repository is deliberately structured so an AI can add a game integration without reverse-engineering the manager. Treat normative prose, JSON Schemas and reference examples as a single contract set.

Before making a change

Read README.md product invariants and root AGENTS.md.
Identify the authoritative domain document.
Validate current schemas and examples before editing.
Inspect Palworld as the reference, but do not generalize a Palworld quirk into the core model.
State uncertain game behavior and cite primary game/container API documentation in contributor-facing notes.

Adding a game without an API

Create a template only. Declare container image, ports, storage, fields, health, backups, mods and update behavior. Do not invent a module merely to start/stop Docker; generic orchestration already handles that.

Adding a game with an API

Create:

catalog/<game>/template.yaml
modules/<module-id>/manifest.yaml
modules/<module-id>/README.md
modules/<module-id>/src/...     implementation phase
modules/<module-id>/tests/...

Choose only required capabilities. Translate game errors into normalized errors. Use the logical instance_api host functions; never accept arbitrary destination URLs. Keep game API credentials as declared secret configuration.

Required verification for a contribution

Template validates against specs/template.schema.json.
Manifest validates against specs/module-manifest.schema.json.
Declared capabilities correspond to normalized functions and module exports.
Template module version range accepts the manifest version.
All integration ports exist in the template and remain private unless explicitly required for players.
Backup source mount exists and strategy matches module capability.
Secret fields are write-only and excluded from examples/fixtures.
Minimum/recommended requirements and upstream image/API facts have primary-source evidence.
Failure behavior works when the game API is offline, slow, malformed or unauthorized.

Safe response to “add this new game”

An AI should produce a short evidence table first: upstream image, required ports, persistent player-data path, health method, configuration interface, save consistency, update mechanism, mod mechanism and API availability. Unknowns remain explicit TODO blockers or conservative template omissions; do not fabricate them.

Then implement the smallest valid surface:

Template-only when generic Docker lifecycle is enough.
Status-only module when only status is reliable.
Add player moderation or online save only with verified API behavior.

Contract-edit rule

If a new game cannot fit the current schema, first determine whether it exposes a genuinely generic need. Extend the schema narrowly with documentation, migration/compatibility analysis, validation, negative tests and updated examples. Never add an escape hatch such as arbitrary commands, raw Compose fragments, host paths or unrestricted network permissions.

3.0 KiB Raw Permalink Blame History