GSP/Panel
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Panel/docs/features/WORKSHOP_SYSTEM.md

9.4 KiB
Raw Blame History

Workshop System

Current State

The current Workshop/content work is split across two module lines:

  • Panel/modules/steam_workshop - deprecated compatibility layer
  • Panel/modules/addonsmanager - the active Server Content Manager path

Important files:

  • Panel/modules/addonsmanager/module.php
  • Panel/modules/addonsmanager/user_addons.php
  • Panel/modules/addonsmanager/addons_manager.php
  • Panel/modules/addonsmanager/workshop_content.php
  • Panel/modules/addonsmanager/workshop_action.php
  • Panel/modules/addonsmanager/scripts/workshop/generic_steam_workshop_linux.sh
  • Panel/modules/addonsmanager/scripts/workshop/generic_steam_workshop_windows_cygwin.sh
  • Panel/modules/steam_workshop/module.php
  • Panel/modules/steam_workshop/agent_update_workshop.php

Current Implemented Behavior

Workshop is Panel-side orchestration. The active workflow lives in Server Content Manager and uses existing agent primitives only:

  • Panel writes manifests with validated numeric Workshop IDs.
  • Panel deploys an OS-appropriate bundled handler script into the server home.
  • Panel invokes the handler through the existing authenticated agent exec RPC.
  • Agents do not need new Workshop-specific business logic.
  • Legacy agent RPCs from the old steam_workshop module remain compatibility-only and are not the primary path.

The active user workflow is now addonsmanager -> workshop_content.

Users can enter either:

  • a numeric Workshop item ID
  • a full Steam Workshop URL containing id=<number>

The Panel extracts and stores only numeric Workshop IDs. Invalid text is rejected before any manifest or shell command is built.

The Panel writes a manifest under the server home:

  • {SERVER_HOME}/gsp_server_content/workshop_manifest.json

The Panel syncs the bundled install script to:

  • {SERVER_HOME}/gsp_server_content/scripts/workshop/generic_steam_workshop_linux.sh
  • {SERVER_HOME}/gsp_server_content/scripts/workshop/generic_steam_workshop_windows_cygwin.sh

The agent executes the synced script with the manifest path by using the existing generic command execution path. Customers do not need to place scripts manually on the agent.

Script selection rules:

  1. If game XML defines a custom workshop_script_linux or workshop_script_windows and that script exists on the agent, use it.
  2. If the custom script is missing, log a fallback warning and stage the bundled generic handler.
  3. If no custom script is defined, stage the bundled generic handler for the server OS.
  4. The default script filename must never be treated as a pre-existing agent path. The Panel must copy the bundled script first.

The manifest includes:

  • home_id
  • server/game path
  • workshop_app_id
  • Workshop item IDs
  • per-item target paths
  • install strategy
  • key-copy settings
  • content template metadata

Default install paths:

  • Generic Workshop installs default to {SERVER_ROOT}/workshop/{MOD_FOLDER}.
  • DayZ/Arma-style installs default to dayz_mod_folder or arma_mod_folder based on the game key/name/config file. Those strategies install to {SERVER_ROOT}/{MOD_FOLDER} so @<workshop_id> folders remain compatible with existing -mod= workflows.
  • DayZ/Arma key-copy behavior copies .bikey files into the server keys folder when found. Missing key files are logged but do not fail the install.

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.
  • Arma 3 XML declares Workshop app ID 107410; its dedicated server Steam app ID remains 233780.

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

Database State

server_content_workshop tracks:

  • content_id
  • home_id
  • workshop_app_id
  • workshop_item_id
  • title
  • install_path
  • install_strategy
  • enabled
  • load_order
  • update_policy
  • pending_action
  • install_state
  • last_installed_at
  • last_updated_at
  • last_error

Current install states used by Phase 1:

  • queued
  • installing
  • installed
  • downloaded
  • failed
  • removed

server_content_workshop_catalog tracks known/common Workshop items seen through Server Content Manager:

  • workshop_id
  • app_id
  • title
  • install_count
  • first_seen
  • last_installed
  • last_updated
  • published_date
  • tags
  • game_key
  • local_cache_path

The catalog is Panel-side and does not require Steam Web API metadata. Metadata can be added later.

What Exists Today

The current direction already supports:

  • content records in the Panel database
  • Workshop item IDs
  • installation metadata
  • install history tables
  • game compatibility fields
  • launch parameter additions
  • post-install behavior fields

Main Limitations

  • Workshop metadata is still incomplete.
  • Load order is tracked but not yet a full drag-and-drop or startup-param UX concept.
  • Enable/disable is exposed and stored but does not yet regenerate startup parameters.
  • 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.

Scheduler Integration

Workshop updates use the existing cron / Scheduler system. No second Workshop scheduler should be created.

Supported scheduler action keys:

  • workshop_update
  • workshop_update_and_restart
  • workshop_download_only
  • workshop_install_pending_on_restart

Compatibility Server Content keys remain available:

  • server_content_check_workshop_updates
  • server_content_update_workshop
  • server_content_install_updates_next_restart
  • server_content_install_updates_and_restart

Per-item update policy values stored on server_content_workshop.update_policy:

  • manual
  • scheduled
  • update_now
  • update_and_restart
  • download_only
  • install_on_restart

Troubleshooting

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 stages the bundled handler under gsp_server_content/scripts/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.
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

Use addonsmanager as the main future home for:

  • mods
  • add-ons
  • Workshop items
  • scripts
  • config packs
  • server content manifests
  • install history

Treat steam_workshop as a legacy bridge for migration only.

Panel-Agent Contract

Phase 1 does not use the legacy steam_workshop XML-RPC method for the primary user workflow. Instead:

  1. Panel parses customer input into numeric Workshop IDs.
  2. Panel writes {SERVER_HOME}/gsp_server_content/workshop_manifest.json.
  3. Panel stages the OS-appropriate bundled handler under {SERVER_HOME}/gsp_server_content/scripts/workshop/.
  4. Panel invokes the handler through the existing authenticated agent exec RPC.
  5. The handler writes workshop_install.log or workshop_install_windows.log under gsp_server_content.
  6. Panel updates server_content_workshop.install_state from queued/installing to installed/failed/removed.

Important manifest fields:

  • home_id
  • home_cfg_id
  • game_path
  • server_path
  • workshop_app_id
  • steam_app_id
  • items
  • item_details
  • install_strategy
  • target_path
  • extra.copy_keys
  • extra.keys_target_path

Both bundled handlers validate numeric item IDs, keep writes under the server home, use SteamCMD, copy files into the resolved target path, and copy .bikey files for DayZ/Arma strategies when enabled.

Bundled handler actions:

  • install - download with SteamCMD, copy/install into target path.
  • update - validate/download with SteamCMD, copy/install into target path.
  • check_updates - validate/download only; does not alter live mod folders.
  • download_only - download/cache only and leave install pending.
  • validate_files - SteamCMD validate/download only.
  • remove - move the installed target folder into gsp_server_content/workshop/removed/; this does not require SteamCMD.