GSP/Panel
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

woekshop phase 1

Browse source
This commit is contained in:
Frank Harris 2026-06-09 06:13:44 -05:00
parent 17a31b7f5f
commit 5a03946bdf
15 changed files with 409 additions and 357 deletions
Download patch file Download diff file Expand all files Collapse all files

27
docs/features/WORKSHOP_SYSTEM.md
View file

@ -54,7 +54,7 @@ The agent executes the generated script with the manifest path by using the exis
Script/job rules:
1. Server Content Manager always generates the primary Workshop job script per action.
2. Old XML/static script settings are logged as deprecated and ignored by the primary path.
2. Game XML does not define static agent script paths.
3. The default script filename must never be treated as a pre-existing agent path.
4. The agent does not require `generic_steam_workshop_linux.sh` or `generic_steam_workshop_windows_cygwin.sh` to exist on disk.
@ -88,9 +88,9 @@ Default install paths:
App ID rules:
- `workshop_app_id` must come from a Server Content template, Steam Workshop profile, or game XML.
- Game XML should declare Workshop support in the canonical `workshop_support` block.
- Do not silently use the dedicated server Steam app ID as the Workshop app ID unless a legacy profile explicitly does so.
- `workshop_app_id` must come from the selected game's canonical `workshop_support` XML block.
- Server Content admin forms must not ask for Workshop app IDs, target paths, launch params, or Workshop script paths.
- Do not silently use the dedicated server Steam app ID as the Workshop app ID.
- Arma 3 XML declares Workshop app ID `107410`; its dedicated server Steam app ID remains `233780`.
Canonical XML:
@ -111,10 +111,11 @@ Canonical XML:
<source_pattern>{MOD_PATH}/keys/*.bikey</source_pattern>
<target_path>{SERVER_ROOT}/keys</target_path>
</copy_keys>
<post_install_action></post_install_action>
</workshop_support>
```
The Panel helper parser reads `workshop_support` first. Older direct tags are tolerated only as a compatibility fallback in helper code; they are not the canonical XML format.
The Panel helper parser reads `workshop_support` as the source of truth. New game XML must not use loose top-level Workshop tags, and the schema no longer accepts per-game static agent script tags such as `script_linux` or `script_windows`.
## Database State
@ -150,6 +151,8 @@ Current install states used by Phase 1:
- `workshop_id`
- `app_id`
- `title`
- `author`
- `thumbnail_url`
- `install_count`
- `first_seen`
- `last_installed`
@ -159,7 +162,7 @@ Current install states used by Phase 1:
- `game_key`
- `local_cache_path`
The catalog is Panel-side and does not require Steam Web API metadata. Metadata can be added later.
The catalog is Panel-side and does not require Steam Web API metadata. It grows from real installs and can be searched by Workshop ID, Steam URL, keyword/title, author, tag, or game key. Metadata can be enriched later through Steam Web API or SteamCMD output parsing.
## What Exists Today
@ -169,9 +172,9 @@ The current direction already supports:
- Workshop item IDs
- installation metadata
- install history tables
- game compatibility fields
- launch parameter additions
- post-install behavior fields
- XML-owned game compatibility fields
- XML-owned launch parameter format
- XML-owned post-install action placeholder
## Main Limitations
@ -181,6 +184,7 @@ The current direction already supports:
- update/remove are synchronous and should become background jobs.
- caching and cleanup policy need product-level design, not just ad hoc scripts.
- `-mod=` / `-serverMod=` generation still needs a safe structured implementation.
- Steam keyword/tag search currently searches the local Panel catalog and links to Steam's app-scoped Workshop search; direct Steam Web API search is Phase 2.
## Scheduler Integration
@ -214,8 +218,9 @@ Per-item update policy values stored on `server_content_workshop.update_policy`:
| Symptom | Meaning | Fix |
|---|---|---|
| `Configured workshop script not found on agent host: generic_steam_workshop_windows_cygwin.sh` | Old Panel logic treated the default script filename as an agent path. | Update the Panel. Current logic generates a per-job script under `gsp_server_content/jobs/workshop/`. |
| `SteamCMD is missing on the agent host.` | The handler could not find SteamCMD at the configured path, `STEAMCMD_PATH`, or common locations. | Install SteamCMD on the agent and/or set the SteamCMD path in the Workshop profile/template. |
| `Workshop App ID is missing` | No template/profile/XML provided an app ID. | Add `workshop_app_id` to the Server Content template or game XML. |
| `SteamCMD is missing on the agent host.` | The generated job could not find SteamCMD at `STEAMCMD_PATH` or common locations. | Install SteamCMD on the agent or set `STEAMCMD_PATH` for the agent environment. |
| `Workshop App ID is missing` | The selected game XML does not provide `workshop_support/workshop_app_id`. | Add a canonical `workshop_support` block to the game XML and validate it. |
| `This game XML does not enable Steam Workshop support` | The user opened Workshop for a game whose XML lacks enabled Workshop capability. | Add `workshop_support` with `enabled` and `workshop_app_id`, or do not expose Workshop for that game. |
| Download succeeds but mod does not load | Startup parameters are not yet regenerated from installed Workshop rows. | Manually add the installed `@...` folders to the game startup params until Phase 2 startup integration is complete. |
## Recommended Mental Model

6
docs/features/XML_SYSTEM.md
View file

@ -94,7 +94,7 @@ XML definitions also feed:
## Workshop / Server Content Capability
Workshop-enabled games must use the canonical `workshop_support` block. Loose top-level tags such as `workshop_app_id` are compatibility parser fallbacks only and should not be used in new game XML because schema validation is intentionally strict.
Workshop-enabled games must use the canonical `workshop_support` block. The game XML is the source of truth for Steam Workshop capability and runtime behavior. Loose top-level tags such as `workshop_app_id` must not be used in new game XML because schema validation is intentionally strict.
The `workshop_support` block is a capability declaration only. It does not install mods by itself and it does not create an agent-side Workshop subsystem. Server Content Manager reads these values, writes a per-server manifest, writes a generated per-job script, and calls the agent's existing generic execution primitives.
@ -116,6 +116,7 @@ Example:
<source_pattern>{MOD_PATH}/keys/*.bikey</source_pattern>
<target_path>{SERVER_ROOT}/keys</target_path>
</copy_keys>
<post_install_action></post_install_action>
</workshop_support>
```
@ -132,10 +133,13 @@ Supported `install_strategy` values:
`workshop_app_id` is the Steam Workshop app ID used by `steamcmd +workshop_download_item`. It is not automatically the same as a dedicated server installer app ID. For Arma 3, Workshop content uses `107410` while the dedicated server installer remains defined on the normal mod installer entry.
`post_install_action` is reserved for a safe admin-owned post-install action identifier or template name. It is not customer input and must not be treated as an arbitrary shell command.
Ordering rule:
- `workshop_support` belongs after `game_name` and before `server_exec_name` in the current schema sequence.
- New XML files should not add top-level Workshop tags.
- New XML files should not define static agent script paths. Server Content Manager stages generated per-job scripts under the server home and invokes them through generic agent execution.
- If `install_path` is omitted, Server Content Manager defaults to `{SERVER_ROOT}/workshop/{MOD_FOLDER}` or `{SERVER_ROOT}/{MOD_FOLDER}` for DayZ/Arma strategies.
The current XML schema is validated by:

53
docs/modules/CONFIG_GAMES.md Normal file
View file

@ -0,0 +1,53 @@
# Config Games
Workspace reference: [`GSP-WORKSPACE.md`](../../../GSP-WORKSPACE.md)
This file is the prompt-facing entry point for the Config Games module. The historical lower-case document remains at [`config_games.md`](config_games.md).
## Purpose
Config Games owns game XML definitions, XML schema validation, startup parameter templates, mod definitions, port metadata, and game capability declarations used by Panel modules.
## Workshop XML Source Of Truth
Steam Workshop support is configured by game XML, not Server Content admin rows.
Canonical structure:
```xml
<workshop_support>
<enabled>1</enabled>
<provider>steam</provider>
<steam_app_id>107410</steam_app_id>
<workshop_app_id>107410</workshop_app_id>
<download_method>steamcmd</download_method>
<install_strategy>arma_mod_folder</install_strategy>
<install_path>{SERVER_ROOT}/{MOD_FOLDER}</install_path>
<startup_param_format>-mod={MOD_LIST}</startup_param_format>
<mod_separator>;</mod_separator>
<mod_prefix>@</mod_prefix>
<copy_keys enabled="1">
<source_pattern>{MOD_PATH}/keys/*.bikey</source_pattern>
<target_path>{SERVER_ROOT}/keys</target_path>
</copy_keys>
<post_install_action></post_install_action>
</workshop_support>
```
Rules:
- `workshop_support` belongs after `game_name` and before `server_exec_name`.
- `workshop_app_id` is required for customer Workshop installs.
- `install_path` defaults to `{SERVER_ROOT}/workshop/{MOD_FOLDER}` unless the install strategy is Arma/DayZ-style, where `{SERVER_ROOT}/{MOD_FOLDER}` is used.
- `post_install_action` is an admin-owned action/template identifier, not customer shell input.
- Static Workshop script paths are not part of the XML contract.
- Server Content Manager generates per-job scripts and calls generic agent execution.
## Validation
Validate all game XML definitions with:
```bash
php Panel/modules/config_games/tests/validate_server_configs.php
```

23
docs/modules/SERVER_CONTENT_MANAGER.md
View file

@ -42,24 +42,24 @@ For Workshop items, the current flow lets users enter Workshop IDs or full Steam
## Workshop Phase 1 Flow
1. Admin creates a Server Content template with install method `steam_workshop`.
2. Admin configures the Workshop App ID on the template or relies on the game XML/profile fallback.
1. Admin enables Workshop by adding a canonical `workshop_support` block to the game XML.
2. Server Content Manager detects that capability from the selected server's XML.
3. User opens `Server Content` from the game monitor.
4. User selects the Steam Workshop Mods category.
5. User enters one or more Workshop URLs or numeric IDs.
4. User selects the Steam Workshop Mods category. A Server Content template is no longer required just to expose Workshop for XML-enabled games.
5. User enters one or more Workshop URLs or numeric IDs, searches the local catalog, or opens Steam's app-scoped Workshop search from the page.
6. Panel parses IDs, rejects invalid entries, and records rows in `server_content_workshop`.
7. Panel writes a manifest to `{SERVER_HOME}/gsp_server_content/workshop_manifest.json`.
8. Panel writes a generated per-job shell script into `{SERVER_HOME}/gsp_server_content/jobs/workshop/`.
9. The generated job script creates a temporary SteamCMD runscript containing `workshop_download_item <appid> <workshop_id> validate`.
10. Agent executes the generated script with the manifest path through the existing authenticated `exec` RPC.
11. Script runs SteamCMD with `+runscript`, copies Workshop content into the configured target path, copies DayZ/Arma `.bikey` files when applicable, and writes a log under `gsp_server_content`.
11. Script runs SteamCMD with `+runscript`, copies Workshop content into the XML-configured target path, copies DayZ/Arma `.bikey` files when applicable, and writes a log under `gsp_server_content`.
The agents are intentionally generic executors in this design. New Workshop business logic should not be added to `Agent-Windows` or `Agent_Linux`; use `remote_writefile`, `exec`, log reads, and normal start/stop/restart primitives instead.
Current job-script behavior:
- Server Content Manager generates a new job script for each Workshop action.
- Admin-defined static Workshop script paths are deprecated and ignored by the primary path.
- Game XML does not define static Workshop script paths.
- Default script names such as `generic_steam_workshop_windows_cygwin.sh` must not be checked as bare files on the agent.
- Agents need only the generic `writefile` and `exec` primitives.
@ -68,7 +68,7 @@ Current default install paths:
- Generic Steam Workshop content: `{SERVER_ROOT}/workshop/{MOD_FOLDER}`
- DayZ / Arma strategy content: `{SERVER_ROOT}/{MOD_FOLDER}` for root `@<workshop_id>` folder compatibility
Game XML fallback should use the canonical `workshop_support` block:
Game XML must use the canonical `workshop_support` block:
```xml
<workshop_support>
@ -86,10 +86,11 @@ Game XML fallback should use the canonical `workshop_support` block:
<source_pattern>{MOD_PATH}/keys/*.bikey</source_pattern>
<target_path>{SERVER_ROOT}/keys</target_path>
</copy_keys>
<post_install_action></post_install_action>
</workshop_support>
```
The Panel helper parser reads this block first and only tolerates old direct tags as an internal compatibility fallback.
The Panel helper parser reads this block as the source of truth. Server Content admin forms do not collect Workshop app IDs, install paths, launch parameter additions, optional mod folder names, or static Workshop scripts.
SteamCMD requirements:
@ -104,6 +105,9 @@ The legacy `steam_workshop` monitor button is intentionally suppressed so users
The `workshop_content.php` page supports:
- direct install by numeric ID or Steam Workshop URL
- keyword/tag search against the local catalog
- app-scoped Steam Workshop search links for the selected game
- a list of Workshop-enabled games matching the current search terms
- installed item list
- enable/disable selected items
- update selected items
@ -111,7 +115,7 @@ The `workshop_content.php` page supports:
- download selected items without installing immediately
- update all saved Workshop items
- per-item update policy storage
- known/common item catalog sorted by name, install count, published date, last updated, or last installed
- known/common item catalog sorted by name, Workshop ID, install count, published date, last updated, or last installed
Update policies are stored as data for Scheduler/automation:
@ -131,6 +135,7 @@ Update policies are stored as data for Scheduler/automation:
- Install strategies are still being broadened and need consistent game-specific rules.
- DayZ/Arma style key-copy is implemented for Phase 1; startup-param behavior still needs a stronger canonical implementation.
- Cache and cleanup policy need a clearer product design.
- Direct Steam Web API keyword/tag search is not implemented yet; the current search page uses local catalog records and links out to Steam's Workshop search.
## Where To Start Reading

6
docs/modules/config_games.md
View file

@ -74,7 +74,9 @@ Key fields:
- `startup_param_format`
- `mod_separator`
- `mod_prefix`
- `mod_folder_format`
- `copy_keys`
- `post_install_action`
Validate changes with:
@ -85,7 +87,9 @@ php Panel/modules/config_games/tests/validate_server_configs.php
Important rules:
- Place `workshop_support` after `game_name` and before `server_exec_name`.
- Do not add loose top-level tags such as `workshop_app_id`; helper code may tolerate them for old configs, but schema-valid XML should use the canonical block.
- Do not add loose top-level tags such as `workshop_app_id`; schema-valid XML must use the canonical block.
- Do not add static Workshop script tags. Server Content Manager generates per-job scripts and uses generic agent execution.
- Do not configure Workshop App ID, target path, mod folder, or launch parameter fields in Server Content admin rows. These values come from this XML block.
- XML declares capability only. Server Content Manager owns the Panel-side install orchestration and uses agents only for generic file/command execution.
## Suggested Future Improvements