57 lines
3.0 KiB
Markdown
57 lines
3.0 KiB
Markdown
# 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
|
|
|
|
1. Read `README.md` product invariants and root `AGENTS.md`.
|
|
2. Identify the authoritative domain document.
|
|
3. Validate current schemas and examples before editing.
|
|
4. Inspect Palworld as the reference, but do not generalize a Palworld quirk into the core model.
|
|
5. 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:
|
|
|
|
```text
|
|
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.
|
|
|