# Server Content Manager

Workspace reference: [`GSP-WORKSPACE.md`](../../../GSP-WORKSPACE.md)

## Current State

`Panel/modules/addonsmanager` is the current home of GSP's Server Content / Add-ons / Workshop work.

The module title has already been moved toward `Server Content Manager`, but the schema and some folder names remain backward-compatible.

Important files:

- `Panel/modules/addonsmanager/module.php`
- `Panel/modules/addonsmanager/addons_manager.php`
- `Panel/modules/addonsmanager/user_addons.php`
- `Panel/modules/addonsmanager/workshop_content.php`
- `Panel/modules/addonsmanager/workshop_action.php`
- `Panel/modules/addonsmanager/server_content_helpers.php`
- `Panel/modules/addonsmanager/server_content_categories.php`

## Database Tables

Known tables used by the module:

- `addons`
- `server_content_workshop`
- `server_content_workshop_catalog`
- `server_content_manifest`
- `server_content_install_history`

## What It Already Does

The module can already represent several content types, including:

- downloads/extracted packages
- post-script driven installs
- workshop-oriented items
- config packs
- future profile-type content

For Workshop items, the current flow lets users enter Workshop IDs or full Steam Workshop URLs and routes the install through module pages, staged manifests, and Panel-bundled scripts executed through existing agent primitives.

## Workshop Phase 1 Flow

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. 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 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.
- 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.

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 must use the canonical `workshop_support` block:

```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>
```

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:

- Linux agents need SteamCMD available at the configured profile/template path, `STEAMCMD_PATH`, `/home/gameserver/steamcmd/steamcmd.sh`, or in `PATH`.
- Windows agents currently use the existing Cygwin agent model and run the Panel-generated shell job. SteamCMD may be provided as `steamcmd.exe`, `steamcmd.sh`, an explicit configured path, or via `STEAMCMD_PATH`.
- Missing SteamCMD should return a clear error, not a generic script failure.

The legacy `steam_workshop` monitor button is intentionally suppressed so users are not sent to the deprecated standalone module.

## Current User Controls

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
- remove selected items
- download selected items without installing immediately
- update all saved Workshop items
- per-item update policy storage
- 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:

- `manual`
- `scheduled`
- `update_now`
- `update_and_restart`
- `download_only`
- `install_on_restart`

## Current Limitations

- Workshop and content metadata is still partial.
- Load order is tracked but not yet reorderable through a polished drag-and-drop UI.
- Enable/disable is tracked but not wired into startup-parameter generation yet.
- Async install job progress should be more visible.
- 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

1. `Panel/modules/addonsmanager/module.php`
2. `Panel/modules/addonsmanager/addons_manager.php`
3. `Panel/modules/addonsmanager/user_addons.php`
4. `Panel/modules/addonsmanager/workshop_content.php`
5. `Panel/modules/addonsmanager/workshop_action.php`

## Important Concept

This module is the right place for:

- mods
- add-ons
- Workshop content
- config packs
- script-driven installs
- server content manifests
- install history

The old `steam_workshop` module should be treated as a deprecated compatibility layer, not the main future path.

## Validation

Relevant smoke tests:

```bash
php Panel/modules/addonsmanager/tests/workshop_helpers_test.php
php Panel/modules/config_games/tests/validate_server_configs.php
```

`validate_server_configs.php` validates every XML file under `Panel/modules/config_games/server_configs/` against `schema_server_config.xml`.