Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -128,6 +128,13 @@ reaches `1.0.0`. Pre-1.0 minor versions may contain breaking changes.
per-server `<gameserver>-rcon` Secret, mounts nothing for the
agent and injects no password environment variable.

### Removed

- **Hell Let Loose module:** `hell-let-loose` is withdrawn from the
official catalog. Its dedicated-server files are distributed only to
Team17's licensed hosting partners, so no public image can install it.
Its hand-run e2e test and probe package are removed with it.

## [0.3.0] — 2026-10-05

The first Gameplane release without a pre-release suffix, a pre-v1 release. It
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,7 +185,7 @@ Gameplane extends Kubernetes using custom resources under `gameplane.local/v1alp
├── sentinel/ # Wake-on-connect daemon (Go)
├── tunnel/ # Relay client supervisor for frp/Tailscale/playit (Go)
├── web/ # Dashboard frontend (React, Vite, Monaco, xterm.js)
├── modules/ # Submodule: Game templates (30 games shipped)
├── modules/ # Submodule: Game templates (29 games shipped)
├── website/ # Submodule: Public documentation site
├── gameproto/ # Wire-protocol parsing library (Minecraft, Terraria)
├── gameaction/ # Console injection guard & action command renderer
Expand Down Expand Up @@ -268,7 +268,7 @@ The `make dev-up` target:
`kind-registry:5000`),
2. loads every locally-built image (operator, api, web, agent, and every
optional component's image),
3. pushes every directory under `modules/` (30 games at last count — see
3. pushes every directory under `modules/` (29 games at last count — see
`modules/` for the current list) to the local registry as an OCI module
bundle,
4. installs the Helm chart from `charts/gameplane/` with a default
Expand Down
2 changes: 0 additions & 2 deletions docs/game-coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,6 @@ Every Gameplane-shipped game module is listed here with its join-protocol covera
| `the-isle` | The Isle | blocked-doc | QUERY | TestGameServer_TheIsleBot_Query | bot-heavy | — | Unreal Engine 4 network protocol variant partially documented; stateless connect handshake requires packet capture | documentation |
| `ark-survival-evolved` | ARK: Survival Evolved | blocked-doc | QUERY | TestGameServer_ArkSurvivalEvolvedBot_Query | bot-heavy | — | Unreal Engine 4 custom net driver; A2S query verified but ShooterGame client login handshake requires reverse-engineering | documentation |
| `arma-reforger` | Arma Reforger | blocked-doc | QUERY | TestGameServer_ArmaReforgerBot_Query | bot-heavy | — | Bohemia Interactive Enfusion engine proprietary network protocol; A2S query verified but backend authentication format undocumented | documentation |
| `hell-let-loose` | Hell Let Loose | blocked-doc | QUERY | TestGameServer_HellLetLooseBot_Query | bot-heavy | — | Unreal Engine 4 network stack; Steam query verified but join handshake and Easy Anti-Cheat integration require reverse-engineering | documentation |
| `squad` | Squad | blocked-doc | QUERY | TestGameServer_SquadBot_Query | bot-heavy | — | Unreal Engine 4 network stack; Steam A2S query verified but client connection handshake format undocumented | documentation |

## Covered (in CI)
Expand Down Expand Up @@ -75,7 +74,6 @@ These modules lack a join-protocol client. The reason is documented as temporary
- **the-isle**: Unreal Engine 4 network protocol variant partially documented. Stateless connect handshake requires packet capture.
- **ark-survival-evolved**: Unreal Engine 4 custom net driver. A2S query verified but ShooterGame client login handshake requires reverse-engineering.
- **arma-reforger**: Bohemia Interactive Enfusion engine proprietary network protocol. A2S query verified but backend authentication format is undocumented.
- **hell-let-loose**: Unreal Engine 4 network stack. Steam query verified but join handshake and Easy Anti-Cheat integration require reverse-engineering.
- **squad**: Unreal Engine 4 network stack. Steam A2S query verified but client connection handshake format is undocumented.

## Out of Scope by Design
Expand Down
2 changes: 1 addition & 1 deletion docs/module-authoring.md
Original file line number Diff line number Diff line change
Expand Up @@ -483,7 +483,7 @@ wizard-managed server-settings.json, portal registry), **palworld**
catalog also includes 7-days-to-die, ark-survival-ascended,
ark-survival-evolved, arma-reforger, beammp, cs2, dayz, dont-starve-together,
enshrouded, euro-truck-simulator-2, farming-simulator-25, fivem, garrys-mod,
hell-let-loose, left-4-dead-2, mount-and-blade-2-bannerlord, nuclear-option,
left-4-dead-2, mount-and-blade-2-bannerlord, nuclear-option,
project-zomboid, rust, satisfactory, squad, team-fortress-2, the-isle,
tmodloader, and v-rising (see [Game Coverage](game-coverage.md) for full protocol and testing status).

Expand Down
2 changes: 1 addition & 1 deletion specs/015-top-steam-game-modules/OPEN-DECISIONS.md
Original file line number Diff line number Diff line change
Expand Up @@ -305,7 +305,7 @@ Open for maintainer ruling: (a) widen research.md Decision 1 to the six extra ga
| `the-isle` | Gameplane-built (`containers/games/the-isle/`) | No community image. SteamCMD app 412680, public `evrima` beta. |
| `ark-survival-evolved` | Gameplane-built (`containers/games/ark-survival-evolved/`), maintainer ruling 2026-10-09 | No clearly maintained community image: recent ones are single-maintainer, older popular ones are 2-5 years stale. SteamCMD app 376030, anonymous. |
| `mount-and-blade-2-bannerlord` | Gameplane-built (`containers/games/mount-and-blade-2-bannerlord/`) | No community image. Windows-only dedicated server (app 1863440), downloaded with `+@sSteamCmdForcePlatformType windows` and run under Wine; a missing `SERVER_TOKEN` idles with instructions (FR-013). |
| `hell-let-loose` | *Pending maintainer card* (recommended: keep the module, mark it blocked) | The server files go only to Team17's licensed hosting partners; there is no public SteamCMD download, so no image can install it. |
| `hell-let-loose` | **Removed** (maintainer ruling 2026-10-11): module, e2e test and probe package deleted; spec 015 now covers 25 games | The server files go only to Team17's licensed hosting partners; there is no public SteamCMD download, so no image can install it. |

Build location (maintainer ruling 2026-10-09): the Gameplane-built images live in this repo's `containers/games/<name>/` on the shared SteamCMD base (UID 10000) and are built by `.github/workflows/images.yaml`, which checks each build on PRs and publishes and signs to `ghcr.io/gameplanepanel/gameplane` on merge to `master`, as Nuclear Option does. This supersedes the "`modules/<game>/` + `modules/build-images.sh`" wording of the ruling above. `modules/.github/workflows/build-images.yml` still gets the lowercase registry-owner fix for its four existing images.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,5 +36,4 @@ This matrix defines the required configurations, port specifications, query prot
| `the-isle` | 412680 | A2S_INFO (UDP) | 7777 UDP | 7778 UDP | 8888 TCP (Source RCON) | `/serverdata/TheIsle/Saved` | `save` |
| `ark-survival-evolved`| 376030 | A2S_INFO (UDP) | 7777 UDP | 27015 UDP | 27020 TCP (Source RCON) | `/serverdata/ShooterGame/Saved` | `SaveWorld` |
| `arma-reforger` | 1874900 | A2S_INFO (UDP) | 2001 UDP | 17777 UDP | Stdin Console | `/home/steam/.local/share/ArmaReforgerServer` | `save` |
| `hell-let-loose` | 731790 | A2S_INFO (UDP) | 7787 UDP | 27165 UDP | 22222 TCP (UE4 RCON) | `/serverdata/HLL/Saved` | N/A (Match-based) |
| `squad` | 403240 | A2S_INFO (UDP) | 7787 UDP | 27165 UDP | 21114 TCP (Squad RCON) | `/serverdata/Squad/Saved` | N/A (Match-based) |
13 changes: 6 additions & 7 deletions specs/015-top-steam-game-modules/engine-matrix-resolved.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,24 +38,23 @@ No module is assigned `cli` pending maintainer ruling on its semantics (T005).
| `satisfactory` | Existing | `satisfactory` | `rcon` | `game` (7777/UDP), `game-tcp` (7777/TCP), `messaging` (8888/TCP) | `/config` (OD 7.11) | `["SaveGame"]` | `bot-heavy` | 25Gi storage + multi-GB SteamCMD download |
| `ark-survival-evolved` | New | `source` | `rcon` | `game` (7777/UDP), `query` (27015/UDP), `rcon` (27020/TCP) | `/data` | `["SaveWorld", "DoExit"]` | `bot-heavy` | SteamCMD download, cluster travel (>30Gi storage) |
| `arma-reforger` | New | `none` | `pty` | `game` (2001/UDP), `query` (17777/UDP) | `/reforger` | `["save"]` | `bot-heavy` | SteamCMD download, Enfusion engine (>25Gi storage) |
| `hell-let-loose` | New | `source` | `rcon` | `game` (7787/UDP), `query` (27165/UDP), `rcon` (22222/TCP) | `/serverdata/HLL/Saved` | `[]` (Match-based) | `bot-heavy` | SteamCMD download (>30Gi storage) |
| `squad` | New | `source` | `rcon` | `game` (7787/UDP), `query` (27165/UDP), `rcon` (21114/TCP) | `/data` | `[]` (Match-based) | `bot-heavy` | SteamCMD download (>35Gi storage) |

---

## 2. 13 New Modules Classification Summary
## 2. New Modules Classification Summary (12; `hell-let-loose` withdrawn 2026-10-11)

- **`bot-fast` (0 modules)**: none of the 13 new modules runs in CI's `bot-fast` bucket.
- **`bot-heavy` (13 modules)**:
- `fivem`, `team-fortress-2`, `farming-simulator-25`, `euro-truck-simulator-2`, `mount-and-blade-2-bannerlord`, `tmodloader`, `beammp`, `left-4-dead-2`, `the-isle`, `ark-survival-evolved`, `arma-reforger`, `hell-let-loose`, `squad` (`test/e2e/buckets.sh`, `bucket_bot_heavy`).
- **`bot-fast` (0 modules)**: none of the 12 new modules runs in CI's `bot-fast` bucket.
- **`bot-heavy` (12 modules)**:
- `fivem`, `team-fortress-2`, `farming-simulator-25`, `euro-truck-simulator-2`, `mount-and-blade-2-bannerlord`, `tmodloader`, `beammp`, `left-4-dead-2`, `the-isle`, `ark-survival-evolved`, `arma-reforger`, `squad` (`test/e2e/buckets.sh`, `bucket_bot_heavy`).
- All need multi-GB downloads, large volumes or emulation layers (Wine/Proton) beyond a GitHub Actions runner's disk and memory, so the bucket is hand-run only.

## 3. Distinction Between `fastGameSet` and CI Buckets

- `fastGameSet` (`test/e2e/gamebot_helpers_e2e_test.go:29`) controls the **local / default developer filter** when `GAMEPLANE_E2E_GAMES` is unset.
- `bucket_bot_fast` and `bucket_bot_heavy` in `test/e2e/buckets.sh` control **CI runner job segmentation**.
- For the 13 new modules:
- For the 12 new modules:
- `tmodloader` and `beammp` are in `fastGameSet` (`test/e2e/gamebot_helpers_e2e_test.go`) for local runs, but are bucketed in `bucket_bot_heavy`, not `bucket_bot_fast`.
- The other 11 are in `heavyGameSet` and bucketed in `bucket_bot_heavy` with CI-exclusion justification comments.
- The other 10 are in `heavyGameSet` and bucketed in `bucket_bot_heavy` with CI-exclusion justification comments.

Table values above (protocol, `consoleMode`, ports, mount path, stop, CI bucket) were re-read from the shipped `modules/<game>/template.yaml` files and `test/e2e/buckets.sh` on 2026-10-11 (T143); the templates are authoritative. "unset" means the template leaves `consoleMode` to its default. The justification column is unchanged.
6 changes: 3 additions & 3 deletions specs/015-top-steam-game-modules/plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,14 +126,14 @@ docs/

## Known Gaps (found during the 2026-10-09 refresh)

These were found by comparing the shipped templates with this plan. **Resolved 2026-10-11** by Phase 9 (T132-T146), except `hell-let-loose`, whose image ruling is still pending (T133, T138); see the note under each gap.
These were found by comparing the shipped templates with this plan. **Resolved 2026-10-11** by Phase 9 (T132-T146); `hell-let-loose` was removed by maintainer ruling 2026-10-11 (OPEN-DECISIONS.md §10, T138 withdrawn). See the note under each gap.

1. **Placeholder image digests (FR-003, SC-002).** Ten of the 13 new modules pin `@sha256:0000…0000`: `ark-survival-evolved`, `arma-reforger`, `beammp`, `euro-truck-simulator-2`, `farming-simulator-25`, `fivem`, `hell-let-loose`, `mount-and-blade-2-bannerlord`, `squad`, `the-isle`. T119 (digest-pinning pass) is marked done, but these images were never pinned.
*Resolved (T141, T142):* nine of the ten now pin real digests (GameplanePanel/module#48); `validate.py` reports 0 errors across all 30 modules. `hell-let-loose` keeps its placeholder (a warning) until its ruling.
*Resolved (T141, T142):* nine of the ten now pin real digests (GameplanePanel/module#48); `validate.py` reports 0 errors across all 30 modules. `hell-let-loose` was removed (T138 withdrawn).
2. **Images with no build source.** Six templates reference `ghcr.io/valgulnecron/gameplane/<game>` images that nothing in either repository builds: `mount-and-blade-2-bannerlord`, `the-isle`, `ark-survival-evolved`, `arma-reforger`, `hell-let-loose`, `squad`. `modules/build-images.sh` builds only the four images from research.md Decision 1. Either research.md Decision 1 widens to these six (with Dockerfiles), or the templates move to community images.
*Resolved (T133-T140, OPEN-DECISIONS §10):* `arma-reforger` moved to the ACE community image; `squad`, `the-isle`, `ark-survival-evolved` and `mount-and-blade-2-bannerlord` are built in this repo's `containers/games/` (#638), and the four original images moved there too (#651).
3. **Stale registry owner.** All ten Gameplane-owned image refs use `ghcr.io/valgulnecron/gameplane/…`; the repositories moved to `GameplanePanel` in October 2026, and `build-images.sh`'s own usage example pushes to `ghcr.io/gameplanepanel/gameplane`.
*Resolved (T141):* every Gameplane-built ref now points at `ghcr.io/gameplanepanel/gameplane/…`, except `hell-let-loose`.
*Resolved (T141):* every Gameplane-built ref now points at `ghcr.io/gameplanepanel/gameplane/…`; `hell-let-loose` was removed.
4. **Planning matrix drift.** `engine-matrix-resolved.md` no longer matches several shipped templates, for example `palworld` stop (`save`, `shutdown 1`), `rust` stop (`server.save`, `quit`), `ark-survival-ascended` stop (`SaveWorld`, `DoExit`), `tmodloader` mount path (`/opt/terraria/config`), and the CI bucket for `tmodloader`/`beammp` (shipped in `bot-heavy`, matrix says `bot-fast`). The templates are authoritative.
*Resolved (T143):* `engine-matrix-resolved.md` was re-read from the shipped templates and `test/e2e/buckets.sh`.

Expand Down
2 changes: 1 addition & 1 deletion specs/015-top-steam-game-modules/research.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ This research defines the architectural foundation, container configurations, pr
| 22 | `the-isle` | The Isle | 412680 | Unreal Engine 4/5 (Linux) | 7777 UDP (Game), 7778 UDP (Query), 8888 TCP (RCON) | Source RCON | Steam Workshop / `Game.ini` |
| 23 | `ark-survival-evolved` | ARK: Survival Evolved | 376030 | Unreal Engine 4 (Linux) | 7777-7778 UDP (Game/Raw), 27015 UDP (Query), 27020 TCP (RCON) | Source RCON | Steam Workshop / Cluster sync |
| 24 | `arma-reforger` | Arma Reforger | 1874900 | Enfusion (Linux) | 2001 UDP (Game), 17777 UDP (Query) | Stdin CLI / Bohemia API | Bohemia Interactive Workshop |
| 25 | `hell-let-loose` | Hell Let Loose | 731790 | Unreal Engine 4 (Linux) | 7787 UDP (Game), 27165 UDP (Query), 22222 TCP (RCON) | UE4 RCON Protocol | Community Maps / Vietnam Preset |
| 25 | `hell-let-loose` | Hell Let Loose | 731790 | Unreal Engine 4 (Linux) | 7787 UDP (Game), 27165 UDP (Query), 22222 TCP (RCON) | UE4 RCON Protocol | Community Maps / Vietnam Preset **Withdrawn 2026-10-11** (OPEN-DECISIONS.md §10). |
| 26 | `squad` | Squad | 403240 | Unreal Engine 4 (Linux) | 7787 UDP (Game), 27165 UDP (Query), 21114 TCP (RCON) | Squad RCON Protocol | Steam Workshop / `Admins.cfg` |

---
Expand Down
4 changes: 2 additions & 2 deletions specs/015-top-steam-game-modules/spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
### Session 2026-09-03

- Q: How should Gameplane handle auxiliary dependencies (such as external databases for FiveM or secondary web administration portals for Farming Simulator 25 and txAdmin) within these game modules? → A: Option B (All-in-One Bundles: Include lightweight auxiliary services such as embedded database processes and companion web interfaces within the container runtime for single-pod zero-dependency deployment).
- Q: Should module #25 target the standard official Hell Let Loose dedicated server (Steam AppID 731790) with support for community configurations/maps, or a specific Vietnam modded variant? → A: Option C (Both Variants: Provide standard Hell Let Loose as the default template version with an optional version profile / preset for Vietnam community conversions).
- Q: Should module #25 target the standard official Hell Let Loose dedicated server (Steam AppID 731790) with support for community configurations/maps, or a specific Vietnam modded variant? → A: Option C (Both Variants: Provide standard Hell Let Loose as the default template version with an optional version profile / preset for Vietnam community conversions). *Superseded 2026-10-11: module withdrawn (OPEN-DECISIONS.md §10).*
- Q: How should game modules that require external authorization keys or master server registration tokens (such as FiveM CFX keys, BeamMP auth keys, and ETS2 server tokens) behave when launched without a configured token? → A: Option A (Graceful Idle with Diagnostics: Containers missing mandatory registration tokens log a clear step-by-step diagnostic message for obtaining and setting the key, and idle cleanly without crash-looping).

---
Expand Down Expand Up @@ -141,7 +141,7 @@ Platform monitoring systems and cluster operators need continuous, accurate heal
22. The Isle (`the-isle`)
23. ARK: Survival Evolved (`ark-survival-evolved`)
24. Arma Reforger (`arma-reforger`)
25. Hell Let Loose with Vietnam community preset (`hell-let-loose`)
25. ~~Hell Let Loose with Vietnam community preset (`hell-let-loose`)~~ **Withdrawn 2026-10-11** (maintainer ruling, OPEN-DECISIONS.md §10): the server files go only to Team17's licensed hosting partners, so no image can install it.
26. Squad (`squad`)
- **FR-002**: Every game module MUST contain the complete, standardized file layout:
- `module.yaml`: Module metadata conforming to `module.schema.json` (name, display name, version, categories, summary, homepage, license, gameplaneMinVersion).
Expand Down
Loading
Loading