Skip to content

docs: plugin catalog for the 14 new game-ci/cli plugins #586

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
frostebite wants to merge 3 commits into from
Closed

docs: plugin catalog for the 14 new game-ci/cli plugins #586

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
58185bc
docs: add plugin catalog covering all 14 new game-ci/cli plugins
frostebite Aug 24, 2026
57db031
docs: mark runtime-test-framework as shipped, add its results contract
frostebite Aug 24, 2026
be23726
docs: add steam-workshop, github-release-deploy, code-signing drafts
frostebite Aug 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 80 additions & 0 deletions docs/03-github-cli/04-configuration-and-plugins.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -141,6 +141,86 @@ configuration-driven providers, executable providers, and TypeScript/JavaScript
Use the public CLI plugin API when you are adding command surface or engine behavior to `game-ci`
itself; use the Orchestrator provider extension points when you are changing where jobs run.

## Plugin Catalog

Beyond the built-in Unity/Godot/Unreal engine plugins and the built-in Orchestrator, a growing set
of plugins add engine support and cross-cutting capabilities. `steam-deploy` and
`runtime-test-framework` are shipped and in the CLI's default load list, the same way Orchestrator
is. Everything else below is a draft - load it explicitly with `--plugin @game-ci/<name>` (or a
`plugins:` entry in `.game-ci.yml`) once it's real.

| Plugin | Kind | Status |
| ---------------------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------- |
| `@game-ci/steam-deploy` | Deploy command | **Shipped.** `game-ci deploy steam <buildPath>` - VDF generation, local/Docker SteamCMD execution. |
| `@game-ci/runtime-test-framework` | Command | **Shipped.** `game-ci test-runtime <buildPath>` - see [below](#runtime-test-framework) for the results contract. |
| `@game-ci/gamemaker` | Engine | Draft - registration shape only, build logic not yet implemented. |
| `@game-ci/rpg-maker` | Engine | Draft. |
| `@game-ci/renpy` | Engine | Draft. |
| `@game-ci/itch-deploy` | Deploy command | Draft - mirrors `steam-deploy`'s shape. |
| `@game-ci/steam-workshop` | Deploy command | Draft - mods/maps via `workshop_build_item.vdf`, distinct from `steam-deploy`'s full-game upload. |
| `@game-ci/github-release-deploy` | Deploy command | Draft - mirrors `steam-deploy`'s shape. |
| `@game-ci/code-signing` | Command | Draft - command not yet registered in core either. |
| `@game-ci/crash-symbol-upload` | Command | Draft - command not yet registered in core either. |
| `@game-ci/screen-capture` | Command, GPU | Draft - command not yet registered in core either. |
| `@game-ci/live-show` | Command | Draft - command not yet registered in core either. |
| `@game-ci/dedicated-server-provisioning` | Command | Draft - command not yet registered in core either. |
| `@game-ci/anti-cheat` | Options | Draft - hooks into an existing build, not a new command. |
| `@game-ci/pseudo-localization` | Command | Draft - command not yet registered in core either. |
| `@game-ci/save-data-compat` | Command | Draft - command not yet registered in core either. |
| `@game-ci/dev-tunnel` | Command | Draft - command not yet registered in core either. |

"Draft" means a real, correctly-typed plugin skeleton exists (conforming to the plugin interface
above), but its actual domain logic is a documented TODO rather than an implementation - see each
plugin's own `README.md` under `plugins/<name>/` in the `game-ci/cli` repo for exactly what's real
versus planned. Several of the command-based drafts also need a small core change to register their
command name with the CLI at all (the same kind of change `deploy` itself needed - see the PR that
added `steam-deploy`) before they can be invoked even once their logic is implemented.

### Runtime Test Framework

`game-ci test-runtime <buildPath>` is a real, distinct capability from `game-ci test`: it launches
the actual _built player_ your build step produced (not the Editor, and not Unity's own Test
Framework's specialized test player, which `game-ci test`'s `-runTests` path uses) and reports on
whatever tests its own in-game harness ran.

```bash
game-ci test-runtime ./build/StandaloneLinux64 --timeout 60000
```

`buildPath` can point directly at the executable, or at a directory containing it - the plugin looks
for the single matching candidate (one `.exe` on Windows, one `.app` bundle on macOS, one
executable-bit file on Linux) and errors clearly if it finds none or more than one, rather than
guessing.

**This plugin never runs test code itself.** A game project's own in-game test harness does, against
a small results contract:

1. The plugin launches the player with `GAME_CI_RUNTIME_TEST_MODE=1` and
`GAME_CI_RUNTIME_TEST_RESULTS_PATH=<path>` set.
2. Your in-game harness checks for `GAME_CI_RUNTIME_TEST_MODE`, runs whatever tests it wants, and
writes a JSON file to `GAME_CI_RUNTIME_TEST_RESULTS_PATH` before exiting:

```json
{
"schemaVersion": 1,
"tests": [
{ "name": "player spawns at origin", "passed": true, "durationMs": 12 },
{
"name": "inventory persists across scene load",
"passed": false,
"message": "expected 3 items, got 2"
}
]
}
```

3. The plugin reads that file after the process exits (or kills it and fails the run if it doesn't
exit within `--timeout`) and fails the CI step on any `passed: false` entry, or if the file was
never written at all.

The results file, not the process exit code, is authoritative - a player that writes valid results
but happens to exit non-zero for an unrelated reason still has its real test results honored.

## Local Config Folder

Use `config open` to open the local GameCI folder:
Expand Down
Loading