gameplane / docs
AUTHOR MODULES

Runtime capabilities and actions

Expose only the controls Gameplane can execute and observe reliably through console, logs, status, players, and providers.

Modules & Sourcesv0.219 MIN
Console & LifecycleChoose RCON or PTY, authoritative game logs, safe credentials, and bounded stop/quiesce hooks.
Actions & StatusUse strict templates and defensive parsers for user actions, live status, players, and moderation.
Mods & RegistriesDeclare directories, install methods, IDs, compatibility, providers, restart behavior, and safe download/extraction rules.
Capability gates should hide unsupported controls instead of allowing an action that will predictably fail.

When a capability is not available (e.g., RCON disabled, a player action not implemented), the dashboard hides the corresponding button or field rather than letting a user attempt an operation that will fail.

Console and lifecycle

Choose RCON or PTY, authoritative game logs, safe credentials, and bounded stop/quiesce hooks.

Never hard-code an RCON or console password.Use spec.rcon.passwordSecretRef to reference a Secret, spec.rcon.passwordEnv to inject it as an env var, or spec.rcon.passwordFile for game-managed password files.
Separate game log path from container stdout.Set spec.logPath to the in-pod path of the game's primary log file (e.g. /data/logs/latest.log). The agent tails this file for the Logs tab; omit it only for stdout-only games.
Provide graceful stop and backup quiesce/unquiesce with timeouts.spec.capabilities.lifecycle.stop runs before pod termination; spec.capabilities.quiesce and unquiesce bracket backups. All three are command sequences that run over RCON.

Actions and status

Use strict templates and defensive parsers for user actions, live status, players, and moderation.

Declare parameters, validation, labels, icons, and capability gates.Each spec.capabilities.actions entry has an id, displayName, description, icon, command or commands template, parameter declarations with validation, and optional confirm/danger flags. A parameter can include currentFrom to pre-fill its value from a live status metric.
Degrade stale or unsupported status instead of fabricating values.spec.capabilities.status.metrics run RCON commands and extract values via named-group regex. If a metric is unavailable, omit it from the status tab instead of showing a fallback.
Model kick, ban, whitelist, and other controls independently.spec.capabilities.players declares kick, ban, unban, banList, whitelist, and list commands and parsing rules separately, so each is optional. Only declare the actions your game supports.

Pre-fill parameters from status (v0.3.0)

A parameter with currentFrom: <metric-id> names a spec.capabilities.status.metrics[].id. When the action dialog opens, the dashboard pre-fills the parameter with that metric’s live value, so a “set” action starts on the current setting:

  • Enum parameters: the option matching case-insensitively (a reading of Easy selects easy)
  • Boolean parameters: true or false
  • Integer parameters: an integer parsed from the reading
  • No reading or no valid match: the parameter falls back to its default

The user’s own choice always wins; a reading that arrives later does not override it. Status metrics need RCON. Minecraft’s set-difficulty action uses it like this:

capabilities:
  actions:
    - id: set-difficulty
      displayName: Set difficulty
      command: "difficulty {{.Params.level}}"
      params:
        - name: level
          type: enum
          enum: ["peaceful", "easy", "normal", "hard"]
          default: normal
          currentFrom: difficulty  # pre-fill from status metric

Mods and registries

Declare directories, install methods, IDs, compatibility, providers, restart behavior, and safe download/extraction rules.

RUNTIME CONTRACT

01   spec.consoleMode + spec.rcon + spec.logPath
02   spec.capabilities.actions + spec.capabilities.status + spec.capabilities.players
03   spec.capabilities.mods + providers + loaders + install policy

Mods directory and loaders

Mods live in one of three ways:

  • Single shared directory (spec.capabilities.mods.path): all versions/loaders share one mods folder, e.g. “mods” or “plugins”. Set extensions to filter by file type (e.g. [".jar"]).
  • Per-loader volumes (spec.capabilities.mods.loaders): each loader ID (e.g. “paper”, “fabric”) gets its own PVC mounted at its path. Picked by spec.versions[].loader. Supports per-loader extensions and extract behavior.
  • Server-managed IDs (spec.capabilities.mods.idList): the game downloads its own mods given a list of IDs. The operator projects spec.mods.ids into an env var the game consumes (e.g. Steam Workshop collections, ARK’s CurseForge mods).

Registry providers and version filtering

When spec.capabilities.mods.registry is set, the dashboard offers a mod browser for one or more providers:

  • modrinth (Minecraft, keyless)
  • thunderstore (BepInEx games, keyless, requires community slug)
  • curseforge (mods/modpacks, needs API key, requires curseforgeGameID)
  • hangar (PaperMC plugins, keyless)
  • factorio (official Factorio mod portal, keyless browse / credentials for download)
  • steam (Steam Workshop, needs API key, requires steamAppID)
  • nexus (Nexus Mods, needs API key, browse-only, requires community slug)
  • spigot (SpigotMC plugins via Spiget, keyless)
  • github (one repository’s Releases, keyless, requires github object with owner/repo)
  • umod (Rust/Hurtworld/7DTD Oxide plugins, keyless)

Version filtering uses spec.versions[].gameVersion (e.g. “1.21.4” for Minecraft) and the active version’s loader ID. The registry provider matches these to its own version/loader facets — no mapping configuration needed.

Install policy and security

spec.capabilities.mods.install gates mod downloads:

  • AllowedHosts (required): hostname allowlist (exact match “cdn.modrinth.com” or suffix “.modrinth.com”). SSRF guard: downloads to private/loopback/link-local addresses are refused.
  • MaxSizeMB (default 256): cap per-download size in mebibytes.

Set extract: true on spec.capabilities.mods (shared) or on the relevant spec.capabilities.mods.loaders.<id> entry (per-loader) to treat downloads as archives (.zip, .tar.gz) and unpack each into its own folder so recursive loaders (BepInEx, Bukkit) find the contents.

Modpacks

When a registry provider has modpacks (e.g., Modrinth modpacks, Thunderstore collections), spec.capabilities.mods.registry.providers[].modpacks declares how installing one works:

  • RefEnv: the game-image environment variable that pins the modpack (e.g. “MODRINTH_MODPACK” for itzg/minecraft). Omit for collections-as-dependency-list games (e.g. Thunderstore BepInEx packs).
  • Env: additional fixed environment variables applied when the modpack is active (e.g. {TYPE: MODRINTH}).

Credentials for protected registries

spec.capabilities.mods.registry.providers[].credentialsSecretRef references a Secret with “username” and “token” keys. Currently used by the Factorio provider for mod-portal downloads; the agent injects credentials transparently during installs.

NEXT GUIDETest, Publish & Sign Modules