Skip to content

Commit 55bff5b

Browse files
frostebitefrostebite
committed
docs: merge the plugin catalog into this PR's configuration-and-plugins page
Consolidates #586 (docs: plugin catalog for the 14 new game-ci/cli plugins) into this PR instead of merging it separately - #586 targeted docs/03-github-cli/04-configuration-and-plugins.mdx, which this PR renumbers to 05-configuration-and-plugins.mdx (it inserts 04-orchestrate-advanced/), so the two would otherwise collide on the same page under different filenames. Content is updated to match what actually shipped, not #586's original snapshot: - live-show, dev-tunnel, crash-symbol-upload, screen-capture, dedicated-server-provisioning and anti-cheat are removed from the plugin list - the first was dropped entirely (game-ci/cli#146: duplicated runtime-test-framework's player-launching, and the rest of its scope - broadcast, an AI-driven playthrough agent - doesn't belong in a CI tool), the other five were re-implemented as real Orchestrator capabilities rather than plugin skeletons (game-ci/cli#144), and are documented in a new "Not plugins: build-lifecycle capabilities" section instead. - steam-deploy and runtime-test-framework are marked "Implemented, loaded by default" rather than folded in with the drafts - they are real, working commands, just still subject to change. - Added a warning block reflecting game-ci/cli#145: every plugin here is experimental, none are published to npm, and each one warns at runtime (drafts on load, the two implemented ones when their command is actually used). #586 will be closed as superseded once this merges.
1 parent 40ac17d commit 55bff5b

1 file changed

Lines changed: 93 additions & 0 deletions

File tree

‎docs/03-github-cli/05-configuration-and-plugins.mdx‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,99 @@ configuration-driven providers, executable providers, and TypeScript/JavaScript
135135
Use the public CLI plugin API when you are adding command surface or engine behavior to `game-ci`
136136
itself; use the Orchestrator provider extension points when you are changing where jobs run.
137137

138+
## Plugin Catalog
139+
140+
Beyond the built-in Unity/Godot/Unreal engine plugins and the built-in Orchestrator, a set of
141+
plugins add engine support and cross-cutting capabilities.
142+
143+
:::warning Every plugin below is experimental
144+
145+
None of them are published to npm, and each one warns at runtime when used. Two of them
146+
(`steam-deploy`, `runtime-test-framework`) are implemented and loaded by default, but their options
147+
may still change without a major version bump. **The rest are structural drafts: the plugin shape is
148+
real, but the domain logic is not written, so any command they claim will throw.** Load a draft only
149+
with an explicit `--plugin @game-ci/<name>` (or a `plugins:` entry in `.game-ci.yml`).
150+
151+
:::
152+
153+
| Plugin | Kind | Status |
154+
| -------------------------------- | -------------- | -------------------------------------------------------------------------------------------- |
155+
| `@game-ci/steam-deploy` | Deploy command | **Implemented**, loaded by default. `game-ci deploy steam <buildPath>` - VDF generation, local/Docker SteamCMD. |
156+
| `@game-ci/runtime-test-framework`| Command | **Implemented**, loaded by default. `game-ci test-runtime <buildPath>` - see [below](#runtime-test-framework). |
157+
| `@game-ci/gamemaker` | Engine | Draft - registration shape only, build logic not implemented. |
158+
| `@game-ci/rpg-maker` | Engine | Draft. |
159+
| `@game-ci/renpy` | Engine | Draft. |
160+
| `@game-ci/itch-deploy` | Deploy command | Draft - mirrors `steam-deploy`'s shape. |
161+
| `@game-ci/steam-workshop` | Deploy command | Draft - mods/maps via `workshop_build_item.vdf`, distinct from a full-game upload. |
162+
| `@game-ci/github-release-deploy` | Deploy command | Draft - attaches artifacts to a GitHub/GitLab Release. |
163+
| `@game-ci/code-signing` | Command | Draft - command not yet registered in core either. |
164+
| `@game-ci/pseudo-localization` | Command | Draft - command not yet registered in core either. |
165+
| `@game-ci/save-data-compat` | Command | Draft - command not yet registered in core either. |
166+
167+
Several of the command-based drafts also need a small core change to register their command name
168+
with the CLI at all (the same change `deploy` itself once needed) before they can be invoked, even
169+
once their logic exists. Each plugin's own `README.md` under `plugins/<name>/` in the `game-ci/cli`
170+
repo states exactly what is real versus planned.
171+
172+
### Not plugins: build-lifecycle capabilities
173+
174+
A plugin exists to add **command surface** - a new verb, engine, or deploy target. Things that
175+
happen _to_ a build or a running job belong to the Orchestrator instead, which already owns where
176+
jobs run plus caching, hooks, output collection, preflight and secrets. These capabilities live
177+
there rather than as plugins:
178+
179+
| Capability | Where it lives |
180+
| -------------------------------- | ----------------------------------------------------------------------- |
181+
| Crash-symbol collection | `symbols` output type + symbol collector (dSYM, PDB, Breakpad, IL2CPP maps) |
182+
| Visual-regression comparison | `visual-baseline` output type + digest comparison against a reference set |
183+
| Dedicated-server provisioning | docker-compose / systemd / firewall generation |
184+
| Exposed-service directory | Registry for job endpoints, with public/private disclosure rules |
185+
| Anti-cheat / build integrity | A `post-build` middleware preset |
186+
187+
### Runtime Test Framework
188+
189+
`game-ci test-runtime <buildPath>` is a distinct capability from `game-ci test`: it launches the
190+
actual _built player_ your build step produced (not the Editor, and not Unity's own Test Framework
191+
player, which `game-ci test`'s `-runTests` path uses) and reports on whatever tests its in-game
192+
harness ran.
193+
194+
```bash
195+
game-ci test-runtime ./build/StandaloneLinux64 --timeout 60000
196+
```
197+
198+
`buildPath` can point at the executable or at a directory containing it - the plugin looks for the
199+
single matching candidate (one `.exe` on Windows, one `.app` bundle on macOS, one executable-bit
200+
file on Linux) and errors clearly if it finds none or several, rather than guessing.
201+
202+
**This plugin never runs test code itself.** Your project's own in-game harness does, against a
203+
small results contract:
204+
205+
1. The plugin launches the player with `GAME_CI_RUNTIME_TEST_MODE=1` and
206+
`GAME_CI_RUNTIME_TEST_RESULTS_PATH=<path>` set.
207+
2. Your harness checks for `GAME_CI_RUNTIME_TEST_MODE`, runs whatever tests it likes, and writes a
208+
JSON file to `GAME_CI_RUNTIME_TEST_RESULTS_PATH` before exiting:
209+
210+
```json
211+
{
212+
"schemaVersion": 1,
213+
"tests": [
214+
{ "name": "player spawns at origin", "passed": true, "durationMs": 12 },
215+
{
216+
"name": "inventory persists across scene load",
217+
"passed": false,
218+
"message": "expected 3 items, got 2"
219+
}
220+
]
221+
}
222+
```
223+
224+
3. The plugin reads that file after the process exits (or kills it and fails the run if it does not
225+
exit within `--timeout`) and fails the step on any `passed: false` entry, or if the file was
226+
never written.
227+
228+
The results file, not the exit code, is authoritative - a player that writes valid results but
229+
happens to exit non-zero for an unrelated reason still has its real results honored.
230+
138231
## Local Config Folder
139232

140233
Use `config open` to open the local GameCI folder:

0 commit comments

Comments
 (0)