From e1e30adeee7737099a76f52d95de8214b73a35cd Mon Sep 17 00:00:00 2001 From: Frank Harris Date: Sat, 20 Jun 2026 13:04:55 -0500 Subject: [PATCH] Import and rebrand OGP wiki documentation for GSP --- Development.md | 16 +- Game-Configuration-Examples.md | 110 ++++++ Game-Template-XML.md | 555 +++++++++++++++++++++++++----- Getting-Started.md | 30 +- Home.md | 30 +- Installation.md | 129 +++++-- Module-Reference.md | 147 +++++--- Modules.md | 81 ++++- OGP-Fork-Notes.md | 45 ++- Remote-Servers-and-Agents.md | 28 +- Requirements-and-Prerequisites.md | 141 ++++++++ Steam-and-Workshop.md | 20 +- Troubleshooting.md | 35 +- XML-Schema-and-Validation.md | 165 +++++++-- 14 files changed, 1245 insertions(+), 287 deletions(-) create mode 100644 Game-Configuration-Examples.md create mode 100644 Requirements-and-Prerequisites.md diff --git a/Development.md b/Development.md index b5b4543..79c96c1 100644 --- a/Development.md +++ b/Development.md @@ -6,23 +6,23 @@ This wiki follows a source-first workflow. 1. Read the relevant wiki page. 2. Inspect the current GSP source file. -3. Compare with `references/OGP/` only when upstream behavior matters. +3. Compare with earlier inherited behavior only when that history helps explain the current design. 4. Implement the change in the GSP codebase. 5. Validate syntax and schemas. 6. Update documentation when behavior changes. ## Validation Expectations -- Run PHP lint on modified PHP files. -- Run the XML validation script when game configs change. -- Keep reference material untouched. +- run PHP lint on modified PHP files +- run the XML validation script when game configs change +- keep generated or imported documentation aligned with current source evidence ## Good Practices -- Preserve existing conventions unless there is a clear reason to change them. -- Use TODO markers when source evidence is incomplete. -- Keep Workshop work in the dedicated `steam_workshop` module. +- preserve existing conventions unless there is a clear reason to change them +- use `Needs Verification` markers when source evidence is incomplete +- keep Workshop work in the dedicated `steam_workshop` module ## TODO -- Add repo-specific branching and review rules if the project adopts a formal release workflow. +- add repo-specific branching and review rules if the project adopts a formal release workflow diff --git a/Game-Configuration-Examples.md b/Game-Configuration-Examples.md new file mode 100644 index 0000000..fea4485 --- /dev/null +++ b/Game-Configuration-Examples.md @@ -0,0 +1,110 @@ +# Game Configuration Examples + +This page provides practical examples based on current GSP template files. The examples are taken from real files in `Panel/Panel/modules/config_games/server_configs/` and are useful when comparing template styles across different games and operating systems. + +## Arma 3 Linux 64-bit + +Template file: + +- `Panel/Panel/modules/config_games/server_configs/arma3_linux64.xml` + +Notable traits: + +- includes `workshop_support` +- uses `steamcmd` install flow +- uses `arma_mod_folder` workshop install strategy +- includes `copy_keys` behavior +- includes startup parameters and replace-text rules + +Useful when you need an example of: + +- current GSP Workshop-enabled XML +- Linux-focused dedicated server config +- modern schema usage for Workshop metadata + +## Arma 3 Windows 64-bit + +Template file: + +- `Panel/Panel/modules/config_games/server_configs/arma3_win64.xml` + +Notable traits: + +- mirrors the Linux Arma 3 template structure closely +- includes `workshop_support` +- useful for comparing Windows and Linux variants of the same game + +Useful when you need an example of: + +- cross-OS template alignment +- same game with platform-specific executable and config differences + +## Garry's Mod Linux + +Template file: + +- `Panel/Panel/modules/config_games/server_configs/garrysmod_linux.xml` + +Notable traits: + +- strong example of classic command-line template behavior +- includes `replace_texts` +- includes `server_params` +- includes player-management tags such as `list_players_command`, `player_info_regex`, `player_info`, and `player_commands` +- uses `rcon2` + +Useful when you need an example of: + +- classic OGP-style XML patterns still present in GSP +- RCON-driven server management +- player parsing and command support + +## DayZ Epoch Mod Windows 32-bit + +Template file: + +- `Panel/Panel/modules/config_games/server_configs/dayz_epoch_mod_win32.xml` + +Notable traits: + +- includes a large `post_install` section +- includes `reserve_ports` +- includes extensive `replace_texts` +- includes `server_params` + +Useful when you need an example of: + +- script-heavy install logic +- complex config replacement rules +- templates that were affected by CDATA and XML sanitization fixes in current history + +## What To Compare Between Templates + +When reviewing or creating a template, compare: + +- `game_key` +- `installer` +- `server_exec_name` +- `cli_template` +- `cli_params` +- `reserve_ports` +- `replace_texts` +- `server_params` +- `mods` +- `workshop_support`, if present +- `post_install` and `pre_start` behavior + +## Practical Use + +Use these examples to answer questions such as: + +- how should a Linux and Windows version of the same game differ +- how should Workshop metadata be represented +- how should config-file replacement rules be structured +- how are player-list parsing and control commands described + +## Related Pages + +- [Game Template XML](Game-Template-XML.md) +- [XML Schema and Validation](XML-Schema-and-Validation.md) +- [Steam and Workshop](Steam-and-Workshop.md) diff --git a/Game-Template-XML.md b/Game-Template-XML.md index 66ce07f..873e022 100644 --- a/Game-Template-XML.md +++ b/Game-Template-XML.md @@ -1,77 +1,474 @@ # Game Template XML -Game template XML defines how a game server is installed, started, queried, and customized. +Game template XML files define how GSP installs, starts, updates, queries, and customizes supported game servers. -## Purpose +The detailed structure in this page is imported from the original OGP XML notes and then checked against the current GSP schema and parser. -The XML files in `Panel/Panel/modules/config_games/server_configs/` describe: +## Where The Files Live -- the game key -- game name -- installer type -- startup command templates -- CLI parameter definitions -- mod definitions -- file replacement rules -- custom fields -- post-install and pre-start hooks -- Workshop capability metadata +Current template files are stored in: -## Current GSP Schema +- `Panel/Panel/modules/config_games/server_configs/` -The current schema is in: +Current schema and parser files: - `Panel/Panel/modules/config_games/schema_server_config.xml` - -The schema validates with: - +- `Panel/Panel/modules/config_games/server_config_parser.php` - `Panel/Panel/modules/config_games/tests/validate_server_configs.php` -## Confirmed Tags In Current GSP +## Purpose Of The XML Templates -From the schema and current XML files, these tags are confirmed: +Each game template can define: -- `game_key` -- `protocol` -- `lgsl_query_name` -- `gameq_query_name` -- `installer` -- `game_name` -- `workshop_support` -- `server_exec_name` -- `query_port` -- `cli_template` -- `cli_params` -- `reserve_ports` -- `cli_allow_chars` -- `maps_location` -- `map_list` -- `console_log` -- `exe_location` -- `max_user_amount` -- `control_protocol` -- `control_protocol_type` -- `mods` -- `replace_texts` -- `server_params` -- `custom_fields` -- `list_players_command` -- `player_info_regex` -- `player_info` -- `player_commands` -- `pre_install` -- `post_install` -- `pre_start` -- `post_start` -- `environment_variables` -- `lock_files` -- `configuration_files` +- the unique game key +- the installer type +- game display name +- executable name +- query and control protocol details +- startup command generation +- reserved port behavior +- map handling +- config-file replacement rules +- user-editable startup parameters +- custom fields +- lifecycle scripts +- lock files and configuration files +- Steam Workshop capability metadata in current GSP -## Workshop Support Block +## Element Order Matters -The schema includes a `workshop_support` block between `game_name` and `server_exec_name`. +The original OGP XML documentation is explicit about this and the current GSP schema confirms it: the order of elements matters. XML files should follow the schema ordering, not just include the right tags. -Confirmed children: +## Base Structure + +There is one top-level `` element: + +```xml + + ... + +``` + +All remaining elements appear inside that root element. + +## Core Identification And Query Tags + +### `` + +Unique identifier for the game template. + +Example: + +```xml +space_engineers_win64 +``` + +The original OGP notes describe OS suffixes such as `_win32`, `_win64`, `_linux32`, and `_linux64`. Current GSP templates still follow that general naming pattern. + +### `` + +Defines the query protocol family. + +Example: + +```xml +lgsl +``` + +The imported OGP notes document values such as `lgsl`, `gameq`, and RCON-oriented protocol flows. Current GSP schema still includes related query and control protocol handling. + +### `` + +LGSL-specific query key. + +Example: + +```xml +killingfloor2 +``` + +### `` + +GameQ-specific query key. + +Example: + +```xml +redorchestra2 +``` + +## Installation And Display Tags + +### `` + +Defines how the game server is installed. + +Example: + +```xml +steamcmd +``` + +The imported OGP documentation uses this to represent installers such as SteamCMD. Current GSP templates still rely on installer metadata in this area. + +### `` + +Friendly display name shown in the panel. + +Example: + +```xml +Killing Floor 2 +``` + +### `` + +Executable used in the generated start command. + +Example: + +```xml +SpaceEngineersDedicated.exe +``` + +### `` + +Describes how the query port relates to the base server port. + +Example: + +```xml +13 +``` + +The original OGP notes describe `type="add"` and arithmetic offset behavior. Current GSP schema still includes query-port structure in this area. + +## Command-Line Generation + +### `` + +Defines the startup command template appended after the executable name. + +Examples: + +```xml +-console %BASE_PATH% -ignorelastsession +``` + +```xml +%MAP%%GAMEMODE%%DIFFICULTY%%GAMELENGTH%%PLAYERS%%MUTATOR% %PORT% %IP% %WEB_ADMIN_PORT% %QUERY_PORT% +``` + +The imported OGP notes document built-in variables including: + +- `GAME_TYPE` +- `HOSTNAME` +- `IP` +- `MAP` +- `PID_FILE` +- `PLAYERS` +- `PORT` +- `QUERY_PORT` +- `BASE_PATH` +- `HOME_PATH` +- `SAVE_PATH` +- `OUTPUT_PATH` +- `CONTROL_PASSWORD` + +Templates may also use custom variables defined elsewhere in the XML. + +### `` + +Defines variables used in the CLI template. + +Example: + +```xml + + + + + +``` + +The imported OGP explanation still applies: + +- `id` matches a variable in `` +- `cli_string` is the prefix inserted before the value +- `options` affects spacing and quoting + +## Port Reservation + +### `` + +Defines additional ports derived from the base server port. + +Example: + +```xml + + 5 + 19238 + 666 + +``` + +Imported OGP behavior: + +- `type="add"` adds to the main port +- `type="subtract"` subtracts from the main port +- a reserved port can be exposed only for firewall bookkeeping even if no CLI string is emitted + +### `` + +Allows selected characters in the generated command line. + +Example: + +```xml +; +``` + +The original OGP notes describe a default escaped set and using this tag to allow selected characters where required. + +## Maps, Logs, And Executable Paths + +### `` + +Path to the map directory used to generate a selectable map list. + +### `` + +Path to a file containing one map per line. + +### `` + +Path to a log file shown in the panel log view. + +### `` + +Path to the executable directory when the executable is not in the server root. + +### `` + +Maximum player count allowed by the panel UI for that template. + +## Control Protocol + +### `` + +Defines the remote control protocol used by the panel. + +Imported OGP notes describe values such as: + +- `rcon` +- `rcon2` +- `lcon` + +Current GSP schema confirms: + +- `rcon` +- `rcon2` +- `lcon` +- `armabe` + +### `` + +Used with RCON to distinguish protocol variants. + +Current GSP schema confirms: + +- `new` +- `old` + +## Mods + +### `` + +Defines available game variants or install targets. + +Example: + +```xml + + + none + 237410 + + +``` + +The imported OGP notes describe `` as the install target identifier, commonly a Steam app ID. + +Current GSP schema confirms additional mod child tags: + +- `name` +- `installer_name` +- `installer_login` +- `betaname` +- `betapwd` +- `steam_bitness` + +## Config File Editing + +### `` + +Defines text replacement operations applied to configuration files. + +Example: + +```xml + + + ServerAdminPassword=.* + ServerAdminPassword= + ShooterGame/Saved/Config/LinuxServer/GameUserSettings.ini + sq + + +``` + +Imported OGP behavior: + +- `` identifies what existing line pattern should be replaced +- `` is the prefix kept in the target file +- `` selects the file to edit +- `` controls spacing, quoting, and comma behavior + +Documented option values: + +- empty: write as-is +- `s`: add a space +- `q`: quote the value +- `sq`: add a space and quote the value +- `sc`: add a space and trailing comma +- `sqc`: add a space, quotes, and trailing comma + +Current GSP schema also confirms: + +- `` +- `` + +inside each replacement text definition. + +## User-Facing Startup Parameters + +### `` + +Defines editable parameters that are used to build the startup command line. + +Example: + +```xml + + + + Server Password + Players must know this password to connect. + + +``` + +Imported OGP parameter types: + +- `text` +- `select` +- `checkbox_key_value` + +Imported OGP option rules: + +- `ns`: no space between key and value +- `q`: quotes around the value with no added space +- `s`: add a space before the value +- anything else: space plus quotes + +Current GSP schema also confirms richer structure for server params, including: + +- `group` +- `param` +- `option` +- `attribute` +- `default` +- `caption` +- `desc` +- `options` +- `access` + +## Custom Fields + +### `` + +Defines fields stored by the panel for use outside the startup command line. + +Current GSP schema confirms: + +- `default_value` +- `occurrence` +- `access` + +Imported OGP notes indicate these fields are intended for values the panel needs to capture and reuse even when they are not direct command-line substitutions. + +## Player Management Tags + +### `` + +Command used to request the current player list. + +### `` + +Regular expression used to parse player rows from command output. + +### `` + +Maps parsed values into player fields. + +### `` + +Defines commands such as kick or ban against selected players. + +These sections are documented in the imported OGP XML notes and still appear in the current schema. + +## Lifecycle Scripts + +### `` + +Commands or actions that run before installation. + +### `` + +Commands or actions that run after installation. + +### `` + +Commands or actions that run before server start. + +The original OGP XML notes include both Linux and Windows style examples for pre-start logic. Current GSP history also shows post-install XML fixes, including CDATA cleanup for DayZ scripts. + +## Environment And Locking + +### `` + +Defines environment variables exported for the server process. + +### `` + +Defines files used to detect running or locked server states. + +## Configuration File Registration + +### `` + +Registers configuration files known to the panel. + +Current GSP schema confirms `` entries with a `description` attribute. + +## GSP Verification Notes + +The current GSP schema adds a major block that is not described in the original OGP XML notes: + +### `` + +Current confirmed child tags: - `enabled` - `provider` @@ -87,12 +484,12 @@ Confirmed children: - `copy_keys` - `post_install_action` -Confirmed `copy_keys` children: +Confirmed `copy_keys` child tags: - `source_pattern` - `target_path` -Confirmed install strategies in the schema: +Confirmed `install_strategy` values in the current schema: - `game_managed_workshop` - `steamcmd_download_only` @@ -103,35 +500,19 @@ Confirmed install strategies in the schema: - `config_only` - `custom_scripted_install` -## Example +This block is visible in current templates such as: -The Arma 3 templates currently include a `workshop_support` block: +- `arma3_linux64.xml` +- `arma3_win64.xml` -```xml - - 1 - steam - 107410 - 107410 - steamcmd - arma_mod_folder - {SERVER_ROOT}/{MOD_FOLDER} - -mod={MOD_LIST} - ; - @ - - {MOD_PATH}/keys/*.bikey - {SERVER_ROOT}/keys - - -``` +## Related Pages -## Compare With OGP +- [XML Schema and Validation](XML-Schema-and-Validation.md) +- [Game Configuration Examples](Game-Configuration-Examples.md) +- [Steam and Workshop](Steam-and-Workshop.md) -The OGP wiki notes in `references/OGP/OGP-Website.wiki/XML-Notes.md` describe the older XML model without the current GSP `workshop_support` block. +## Needs Verification -## TODO / Needs Verification - -- Which older XML tags are still accepted only for legacy compatibility -- Whether any additional tags are currently parsed by code outside the schema -- Whether any module-specific XML tags were added in a commit after the current schema +- whether any legacy tags remain accepted by runtime code even when not present in the current schema +- whether any module-specific XML conventions exist outside `config_games` +- whether every older OGP XML example remains valid without adjustment under the current GSP schema diff --git a/Getting-Started.md b/Getting-Started.md index 5543a40..52018a1 100644 --- a/Getting-Started.md +++ b/Getting-Started.md @@ -1,42 +1,34 @@ # Getting Started -This wiki documents the GSP Panel as a fork of Open Game Panel and a separate product with its own current behavior. +This wiki documents Game Server Panel as its own current product while preserving necessary attribution to its Open Game Panel origins. ## First Read - [Home](Home.md) - [Installation](Installation.md) +- [Requirements and Prerequisites](Requirements-and-Prerequisites.md) - [Configuration](Configuration.md) - [Modules](Modules.md) ## What GSP Is -GSP is the control-plane web panel for game server administration. It coordinates server management, XML-based game templates, file operations, and module pages. - -## Workspace Layout - -In this workspace: - -- `Panel/Panel/` contains the current GSP Panel source tree. -- `Panel.wiki/` contains this wiki. -- `references/OGP/` contains read-only upstream reference material. +GSP is the control-plane web panel for game server administration. It coordinates server management, XML-based game templates, file operations, remote agents, user access, and dedicated modules such as Steam Workshop. ## Recommended First Steps -1. Read the relevant wiki page for the feature you want to change. -2. Inspect the current source file in `Panel/Panel/modules/...`. -3. Compare with `references/OGP/` when original behavior matters. -4. Make the change in GSP code, not in `references/`. -5. Run the applicable validation or syntax checks. +1. Read the installation and prerequisites pages. +2. Review the module inventory and identify the feature area you are working in. +3. Inspect the current source files in `Panel/Panel/modules/...`. +4. Validate any XML or PHP changes before treating the work as complete. ## Good Starting Points - `Panel/Panel/modules/config_games/` for XML game templates and schema validation -- `Panel/Panel/modules/steam_workshop/` for dedicated Workshop administration and installs +- `Panel/Panel/modules/steam_workshop/` for Workshop administration and installs - `Panel/Panel/modules/gamemanager/` for server lifecycle actions -- `Panel/Panel/modules/addonsmanager/` for server content workflows +- `Panel/Panel/modules/addonsmanager/` for legacy server-content workflows ## Notes -- This wiki is a first-pass operational guide. -- Pages marked with TODO or Needs Verification indicate areas where source evidence was incomplete or intentionally conservative. +- pages marked with `Needs Verification` identify areas where the current source should be checked before making stronger claims +- newer GSP behavior should override older inherited assumptions where the code confirms a difference diff --git a/Home.md b/Home.md index f40b7c3..e703856 100644 --- a/Home.md +++ b/Home.md @@ -2,26 +2,40 @@ Game Server Panel is a fork of Open Game Panel. -Game Server Panel, or GSP, is being developed as a modernized game server control panel for managing game servers, Workshop content, server files, users, and supporting XML-driven game templates. +Game Server Panel, or GSP, is being developed as a modernized game server control panel for managing game servers, remote agents, XML-driven game templates, server files, Steam content, and Workshop-enabled deployments. -Start here: +## Start Here - [Getting Started](Getting-Started.md) - [Installation](Installation.md) +- [Requirements and Prerequisites](Requirements-and-Prerequisites.md) - [Configuration](Configuration.md) - [Administration](Administration.md) - [Game Server Management](Game-Server-Management.md) -- [Modules](Modules.md) -- [Steam and Workshop](Steam-and-Workshop.md) -- [XML Schema and Validation](XML-Schema-and-Validation.md) -- [Troubleshooting](Troubleshooting.md) -Key reference pages: +## Core Technical Reference - [Game Template XML](Game-Template-XML.md) +- [XML Schema and Validation](XML-Schema-and-Validation.md) +- [Game Configuration Examples](Game-Configuration-Examples.md) +- [Modules](Modules.md) - [Module Reference](Module-Reference.md) - [Database](Database.md) - [Remote Servers and Agents](Remote-Servers-and-Agents.md) +- [Steam and Workshop](Steam-and-Workshop.md) +- [Troubleshooting](Troubleshooting.md) + +## Project Notes + +- [Development](Development.md) +- [Release Process](Release-Process.md) - [OGP Fork Notes](OGP-Fork-Notes.md) -The upstream OGP reference material is stored in `references/OGP/` in this workspace and is read-only. Use it to compare original behavior, then document GSP behavior in this wiki. +## What This Wiki Covers + +- Installing the GSP panel and preparing the required web stack +- Understanding game template XML and current schema validation +- Managing modules, users, permissions, files, and remote servers +- Working with Steam and Workshop features in the current panel + +This wiki is intended to be practical first. Where the upstream OGP documentation still reflects the current architecture, it has been imported and reworked for GSP. Where current GSP behavior differs, the GSP behavior takes precedence. diff --git a/Installation.md b/Installation.md index 0b0b158..204140a 100644 --- a/Installation.md +++ b/Installation.md @@ -1,34 +1,119 @@ # Installation -This page is a practical overview, not a packaging guide. +This page combines the original Open Game Panel installation guidance with the current GSP panel source tree and installer checks. -## What To Install +## Overview -- A working web stack for the Panel -- PHP with XML support -- A database server for Panel data -- The GSP Panel source tree -- The appropriate agent repositories for server execution +GSP has two major parts: -## Workspace Guidance +- the panel, which provides the PHP web interface +- one or more remote agents, which execute server actions on host machines -- Keep `references/OGP/` read-only. -- Install or deploy from the GSP source tree, not from reference material. -- Validate XML-related changes with the bundled schema check before treating them as complete. +For the panel itself, start with a working Linux web server, install the required PHP extensions and database services, place the panel in the web document root, then complete the web installer. -## Where To Look In Source +## Recommended Panel Installation Flow -- `Panel/Panel/modules/config_games/tests/validate_server_configs.php` -- `Panel/Panel/modules/config_games/schema_server_config.xml` -- `Panel/Panel/modules/steam_workshop/` +1. Prepare the web server and database host. +2. Install the required packages listed in [Requirements and Prerequisites](Requirements-and-Prerequisites.md). +3. Place the panel source tree in the intended document root or subdirectory. +4. Ensure writable paths and the configuration file are writable for installation. +5. Run the environment check page. +6. Run the installer page. +7. Remove installation write access that is no longer needed. +8. Connect the panel to remote agent hosts. -## First Checks After Installation +## Current Ubuntu 24.04 Quick Install Example -1. Open the Panel home page. -2. Confirm module navigation loads. -3. Confirm XML game configs parse and validate. -4. Confirm the Workshop and game management pages open without PHP errors. +The current `Panel/Panel/INSTALL_README.md` includes this package baseline for Ubuntu 24.04: -## TODO +```bash +sudo apt update +sudo apt install -y apache2 mysql-client unzip tar screen sudo subversion git rsync \ + php8.3 php8.3-mysql php8.3-gd php8.3-curl php8.3-mbstring php8.3-zip \ + php8.3-xml php8.3-xmlrpc php-pear libapache2-mod-php8.3 +sudo a2enmod rewrite +sudo systemctl restart apache2 +``` -- Add a full platform-specific install walkthrough once the current deployment path is finalized. +That package set matches the current GSP environment checker closely, but the exact package names should still be verified for the target operating system and PHP packaging model. + +## Manual Linux Web Installation + +The upstream OGP wiki documents the classic manual installation model, which still matches the general panel architecture: + +1. Install Apache or a compatible web server. +2. Install PHP and the required extensions. +3. Install MySQL or MariaDB. +4. Enable Apache rewrite support if Apache is used. +5. Copy the panel files into the web root. +6. Open the installer in a browser and complete database configuration. + +Typical document-root placement examples: + +- `/var/www/html/` +- `/var/www/html/gsp/` +- another configured virtual-host document root + +If the panel is deployed into a subdirectory rather than the root site, confirm the web server routing and permissions are correct before running the installer. + +## Environment Check And Installer + +Current GSP ships two important web installer entry points: + +- `Panel/Panel/check.php` +- `Panel/Panel/install.php` + +Recommended flow: + +1. Open `check.php` first and clear every reported blocker. +2. Open `install.php`. +3. Enter the database connection details. +4. Keep the default table prefix of `gsp_` unless there is a deliberate reason to change it. +5. Finish the installer and confirm the panel login page loads. + +## Filesystem Permissions + +The current checker verifies these paths: + +- `includes/` +- `modules/` +- `upload/` +- `cache/` +- `log/` +- `temp/` +- `includes/config.inc.php` + +During installation, the web server user must be able to write the paths the installer needs. After installation, reduce permissions to the minimum required by normal runtime behavior. + +## Database Notes + +- MySQL and MariaDB are both reasonable targets for the panel database layer. +- The current installer defaults to the `gsp_` table prefix. +- Legacy `ogp_` prefixes may still appear in older documentation or compatibility paths, but new GSP installations should use `gsp_`. + +## Remote Agent Notes + +The original OGP documentation separated panel installation from agent installation. That still applies to GSP in principle: + +- the panel is installed on the web server +- agents are installed on the game-host machines + +See [Remote Servers and Agents](Remote-Servers-and-Agents.md) for panel-side integration notes. + +## After Installation + +Verify these items before treating the panel as ready: + +1. The login page loads without PHP warnings. +2. `check.php` no longer reports missing requirements. +3. The database tables were created with the expected prefix. +4. Modules load in navigation without fatal errors. +5. XML game configs validate and load correctly. +6. A configured remote server can connect to the panel. + +## Related Pages + +- [Requirements and Prerequisites](Requirements-and-Prerequisites.md) +- [Configuration](Configuration.md) +- [Remote Servers and Agents](Remote-Servers-and-Agents.md) +- [Troubleshooting](Troubleshooting.md) diff --git a/Module-Reference.md b/Module-Reference.md index d19e4ae..28e80da 100644 --- a/Module-Reference.md +++ b/Module-Reference.md @@ -1,57 +1,114 @@ # Module Reference -This page is a working inventory of modules discovered in the current GSP Panel tree. +This page combines the current GSP module inventory with imported upstream module documentation where that older documentation still explains the module accurately. -## Core Modules +## Inventory | Module | Path | Purpose | Main files | Notes | | --- | --- | --- | --- | --- | -| TS3Admin | `Panel/Panel/modules/TS3Admin/` | TeamSpeak 3 admin integration | `module.php`, `navigation.xml` | TODO: confirm current feature scope | -| addonsmanager | `Panel/Panel/modules/addonsmanager/` | Server content workflows and legacy add-ons area | `module.php`, `addons_manager.php`, `workshop_content.php`, `workshop_action.php`, `server_content_helpers.php` | Workshop entry point should remain dedicated to `steam_workshop` | -| administration | `Panel/Panel/modules/administration/` | Admin utilities and system settings | `module.php`, page files | TODO | -| backup-restore | `Panel/Panel/modules/backup-restore/` | Backup and restore functions | `module.php` | TODO | -| billing | `Panel/Panel/modules/billing/` | Billing / storefront integration | `module.php`, admin pages, docs | Relevant DB tables exist in billing code, but not fully inventoried here | -| circular | `Panel/Panel/modules/circular/` | Small utility module | `module.php` | TODO | -| config_games | `Panel/Panel/modules/config_games/` | XML game templates, schema, and config parsing | `config_servers.php`, `server_config_parser.php`, `schema_server_config.xml`, `tests/validate_server_configs.php` | High-confidence module | -| cron | `Panel/Panel/modules/cron/` | Scheduled task handling | `module.php` | TODO | -| dashboard | `Panel/Panel/modules/dashboard/` | Home/dashboard pages | `module.php` | TODO | -| dsi | `Panel/Panel/modules/dsi/` | Game-related service integration | `module.php` | TODO | -| editconfigfiles | `Panel/Panel/modules/editconfigfiles/` | Config file editing | `module.php` | Works with file/config management flows | -| faq | `Panel/Panel/modules/faq/` | FAQ pages | `module.php` | TODO | -| fast_download | `Panel/Panel/modules/fast_download/` | Download helper paths | `module.php` | TODO | -| ftp | `Panel/Panel/modules/ftp/` | FTP-related file access | `module.php` | TODO | -| gamemanager | `Panel/Panel/modules/gamemanager/` | Server lifecycle and game monitoring | `module.php`, `mini_start.php`, `home_handling_functions.php`, `update_actions.php` | Central gameplay management module | -| lgsl_with_img_mod | `Panel/Panel/modules/lgsl_with_img_mod/` | LGSL query integration | `module.php` | TODO | +| TS3Admin | `Panel/Panel/modules/TS3Admin/` | TeamSpeak 3 admin integration | `module.php`, `navigation.xml` | Verify current scope | +| addonsmanager | `Panel/Panel/modules/addonsmanager/` | Legacy add-ons and server-content workflows | `module.php`, `addons_manager.php`, `workshop_content.php`, `workshop_action.php`, `server_content_helpers.php` | Workshop should stay centered in `steam_workshop` | +| administration | `Panel/Panel/modules/administration/` | Administration pages and utilities | `module.php` and page files | Verify current breakdown | +| backup-restore | `Panel/Panel/modules/backup-restore/` | Backup and restore operations | `module.php` | Verify runtime details | +| billing | `Panel/Panel/modules/billing/` | Billing and storefront integration | `module.php`, admin pages | Upstream billing docs exist | +| circular | `Panel/Panel/modules/circular/` | Utility module | `module.php` | Needs verification | +| config_games | `Panel/Panel/modules/config_games/` | Game template XML, schema, parser, and validation | `config_servers.php`, `server_config_parser.php`, `schema_server_config.xml`, `tests/validate_server_configs.php` | High-confidence module | +| cron | `Panel/Panel/modules/cron/` | Scheduled jobs | `module.php` | Upstream README explains scheduling intent | +| dashboard | `Panel/Panel/modules/dashboard/` | Dashboard and home experience | `module.php` | Verify current page scope | +| dsi | `Panel/Panel/modules/dsi/` | Dynamic server image integration | `module.php` | Upstream README explains core feature | +| editconfigfiles | `Panel/Panel/modules/editconfigfiles/` | Config file editing | `module.php` | Upstream README provides baseline behavior | +| faq | `Panel/Panel/modules/faq/` | FAQ pages | `module.php` | Verify current content source | +| fast_download | `Panel/Panel/modules/fast_download/` | Fast-download / HTTP redirect support | `module.php` | Upstream README explains purpose | +| ftp | `Panel/Panel/modules/ftp/` | FTP-related access | `module.php` | Verify current behavior | +| gamemanager | `Panel/Panel/modules/gamemanager/` | Core server lifecycle management | `module.php`, `mini_start.php`, `home_handling_functions.php`, `update_actions.php` | Central game management module | +| lgsl_with_img_mod | `Panel/Panel/modules/lgsl_with_img_mod/` | LGSL query integration | `module.php` | Verify image/query role | | litefm | `Panel/Panel/modules/litefm/` | File manager | `module.php` | User-facing file operations | -| lostpwd | `Panel/Panel/modules/lostpwd/` | Lost password flow | `module.php` | TODO | -| mods | `Panel/Panel/modules/mods/` | Mod definitions and mod tools | `module.php` | TODO | -| modulemanager | `Panel/Panel/modules/modulemanager/` | Module enable/disable or management | `module.php` | TODO | -| mysql | `Panel/Panel/modules/mysql/` | MySQL database tools | `module.php` | TODO | -| news | `Panel/Panel/modules/news/` | News / announcements | `module.php` | TODO | -| rcon | `Panel/Panel/modules/rcon/` | Remote console tools | `module.php` | TODO | -| register | `Panel/Panel/modules/register/` | User registration | `module.php` | TODO | -| reseller | `Panel/Panel/modules/reseller/` | Reseller admin flows | `module.php`, `navigation.xml` | Seen in Git history and navigation | -| server | `Panel/Panel/modules/server/` | Server views / server-side pages | `module.php` | TODO | -| settings | `Panel/Panel/modules/settings/` | Panel settings | `module.php` | TODO | -| steam_workshop | `Panel/Panel/modules/steam_workshop/` | Dedicated Steam Workshop module | `module.php`, `main.php`, `workshop_admin.php`, `uninstall.php`, `functions.php` | Active dedicated Workshop module | -| subusers | `Panel/Panel/modules/subusers/` | Sub-user management | `module.php` | TODO | -| support | `Panel/Panel/modules/support/` | Support pages | `module.php` | TODO | -| teamspeak3 | `Panel/Panel/modules/teamspeak3/` | TeamSpeak 3 integration | `module.php` | TODO | -| tickets | `Panel/Panel/modules/tickets/` | Ticketing / support tickets | `module.php`, `navigation.xml` | TODO | -| tshock | `Panel/Panel/modules/tshock/` | TShock / Terraria-related admin | `module.php` | TODO | -| update | `Panel/Panel/modules/update/` | Update flow | `module.php` | TODO | +| lostpwd | `Panel/Panel/modules/lostpwd/` | Password reset flow | `module.php` | Verify current routing | +| mods | `Panel/Panel/modules/mods/` | Mod-related definitions or tools | `module.php` | Needs verification | +| modulemanager | `Panel/Panel/modules/modulemanager/` | Module management | `module.php` | Verify enable/disable flows | +| mysql | `Panel/Panel/modules/mysql/` | MySQL helper pages | `module.php` | Verify scope | +| news | `Panel/Panel/modules/news/` | News and announcements | `module.php` | Verify current usage | +| rcon | `Panel/Panel/modules/rcon/` | Remote console tools | `module.php` | Verify current actions | +| register | `Panel/Panel/modules/register/` | User registration | `module.php` | Verify config dependencies | +| reseller | `Panel/Panel/modules/reseller/` | Reseller management | `module.php`, `navigation.xml` | Verify current privileges | +| server | `Panel/Panel/modules/server/` | Server-specific pages | `module.php` | Verify scope | +| settings | `Panel/Panel/modules/settings/` | Panel settings | `module.php` | Verify current ownership | +| status | `Panel/Panel/modules/status/` | Status views | `module.php` | Verify current function | +| steam_workshop | `Panel/Panel/modules/steam_workshop/` | Dedicated Steam Workshop management | `module.php`, `main.php`, `workshop_admin.php`, `functions.php`, `uninstall.php` | Active GSP Workshop module | +| subusers | `Panel/Panel/modules/subusers/` | Sub-user management | `module.php` | User delegation module | +| support | `Panel/Panel/modules/support/` | Support pages | `module.php` | Upstream support docs exist | +| teamspeak3 | `Panel/Panel/modules/teamspeak3/` | TeamSpeak 3 integration | `module.php` | Verify relationship to TS3Admin | +| tickets | `Panel/Panel/modules/tickets/` | Ticketing system | `module.php`, `navigation.xml` | Upstream README explains ticket purpose | +| tshock | `Panel/Panel/modules/tshock/` | TShock or Terraria-oriented features | `module.php` | Needs verification | +| update | `Panel/Panel/modules/update/` | Update flow | `module.php` | Verify current mechanics | | user_admin | `Panel/Panel/modules/user_admin/` | User administration | `module.php` | Admin-facing | -| user_games | `Panel/Panel/modules/user_games/` | User game server list and access | `module.php` | User-facing | -| util | `Panel/Panel/modules/util/` | Shared utilities | `module.php` | TODO | -| website | `Panel/Panel/modules/website/` | Website integration pages | `module.php` | TODO | +| user_games | `Panel/Panel/modules/user_games/` | User game-server pages | `module.php` | User-facing | +| util | `Panel/Panel/modules/util/` | Shared utilities | `module.php` | Cross-module support | +| website | `Panel/Panel/modules/website/` | Website integration pages | `module.php` | Related to panel website features | -## Additional Workshop-Related Files +## Imported Upstream Module Notes -- `Panel/Panel/modules/steam_workshop/game_configs/` contains per-game Workshop XML profiles. -- `Panel/Panel/modules/steam_workshop/navigation.xml` exposes the dedicated pages. -- `Panel/Panel/modules/steam_workshop/simple_admin_helper.php` adds a simple admin UI helper. +These notes come from upstream OGP module documentation and remain useful as first-pass descriptions unless contradicted by current GSP source. -## Notes +### `cron` -- Some modules may contain subpages not listed here because their behavior is still being inventoried. -- For any module not yet fully understood, treat this as a first-pass reference and add TODOs rather than assumptions. +- purpose: schedule server start, stop, restart, or other jobs +- upstream note: designed to support both Linux and Windows job scheduling flows +- GSP verification note: current source presence is confirmed; exact current UI and scheduler implementation should be verified in module pages + +### `dsi` + +- purpose: Dynamic Server Image generation +- upstream note: requires PHP GD and Apache `mod_rewrite` +- upstream note: depends on writable folders for generated image assets +- GSP verification note: the module still exists; verify exact image-generation flow in current code before documenting setup details more deeply + +### `editconfigfiles` + +- purpose: edit server configuration files through panel tooling +- upstream note: intended to simplify config editing without manual file browsing +- GSP verification note: current module path is confirmed; exact editable file registration should be documented together with XML `configuration_files` + +### `fast_download` + +- purpose: configure fast-download aliases or HTTP paths for game content delivery +- upstream note: integrates HTTP daemon aliasing or redirect-style download support +- GSP verification note: current module exists; deployment specifics depend on the active web-server layout and should be verified before claiming full automation + +### `steam_workshop` + +- purpose: manage Steam Workshop configuration and content installs from a dedicated module +- upstream note: upstream README describes Workshop installs using XML-generated metadata +- GSP verification note: current GSP goes further with a dedicated admin profile page, per-game Workshop XML profiles, and schema-level `workshop_support` in game templates + +### `tickets` + +- purpose: support ticket module +- upstream note: provides user-to-admin support workflow +- GSP verification note: current module path and navigation are confirmed; exact database tables and role handling need a focused code pass + +### `billing` + +- purpose: billing and storefront workflows +- upstream note: bundled with cron-driven recurring or timed operations +- GSP verification note: current module exists, but exact payment-provider and automation coverage should be documented only after module-level source review + +### `support` + +- purpose: support or help workflows in the panel +- upstream note: can be installed and exposed through module management +- GSP verification note: current module path is confirmed; precise relationship to `tickets` should be reviewed + +## Workshop-Related Files + +Current dedicated Workshop assets include: + +- `Panel/Panel/modules/steam_workshop/game_configs/` +- `Panel/Panel/modules/steam_workshop/navigation.xml` +- `Panel/Panel/modules/steam_workshop/simple_admin_helper.php` + +## Needs Verification + +- exact database tables touched by each module +- exact navigation ownership for overlapping modules such as `support`, `tickets`, `TS3Admin`, and `teamspeak3` +- which legacy modules remain enabled in normal GSP deployments versus retained for compatibility diff --git a/Modules.md b/Modules.md index 0b94e58..f9fb0ec 100644 --- a/Modules.md +++ b/Modules.md @@ -1,27 +1,78 @@ # Modules -GSP modules are organized under `Panel/Panel/modules/`. +GSP modules are organized under `Panel/Panel/modules/`. This page gives a high-level view of how modules are structured and where to find the current inventory. ## How Modules Work -- Each module lives in its own directory. -- Most modules expose a `module.php` entry point and one or more page files. -- Many modules also provide `navigation.xml`, styles, or helper scripts. -- Module behavior is usually split between user-facing pages and admin pages. +- each module lives in its own directory +- most modules expose a `module.php` entry point +- many modules include page handlers, helper functions, `navigation.xml`, templates, assets, or small support scripts +- some modules are primarily admin-facing, some user-facing, and some are shared infrastructure + +The current `Panel/Panel/modules/README.modules` file also reflects the long-standing module-based architecture inherited from OGP. ## Major Module Areas -- Server management -- User and permission management -- Configuration and XML tools -- Workshop and content management -- Billing and website integration +- server lifecycle and game management +- XML game configuration +- file and FTP management +- Steam and Workshop management +- user, subuser, reseller, and admin management +- support, billing, website, and utility modules -## Discovered Modules +## Current Module Inventory -See [Module Reference](Module-Reference.md) for the current module inventory and the main files in each module. +The current GSP tree includes these module directories: -## Notes +- `TS3Admin` +- `addonsmanager` +- `administration` +- `backup-restore` +- `billing` +- `circular` +- `config_games` +- `cron` +- `dashboard` +- `dsi` +- `editconfigfiles` +- `faq` +- `fast_download` +- `ftp` +- `gamemanager` +- `lgsl_with_img_mod` +- `litefm` +- `lostpwd` +- `mods` +- `modulemanager` +- `mysql` +- `news` +- `rcon` +- `register` +- `reseller` +- `server` +- `settings` +- `status` +- `steam_workshop` +- `subusers` +- `support` +- `teamspeak3` +- `tickets` +- `tshock` +- `update` +- `user_admin` +- `user_games` +- `util` +- `website` -- `references/OGP/` contains upstream module documentation for comparison only. -- When a module is unclear, document it as TODO instead of inventing behavior. +## Documentation Strategy + +[Module Reference](Module-Reference.md) expands each discovered module with: + +- purpose +- path +- main files +- admin or user-facing role +- known notes from current source +- upstream behavior where it still helps explain the module + +Where exact behavior is still uncertain, the reference page keeps the imported baseline and adds verification notes rather than inventing behavior. diff --git a/OGP-Fork-Notes.md b/OGP-Fork-Notes.md index 8d941e2..e8d942f 100644 --- a/OGP-Fork-Notes.md +++ b/OGP-Fork-Notes.md @@ -2,32 +2,39 @@ Game Server Panel is a fork of Open Game Panel. -## Reference Policy +## Upstream Relationship -- `references/OGP/` is read-only upstream reference material. -- Use it to understand old behavior, then implement changes in GSP source only. -- Do not edit, move, rename, or delete anything under `references/`. +GSP inherits major architectural patterns from OGP, including: -## Confirmed Differences +- the split between the panel and remote agents +- the module-based panel layout +- XML-driven game template definitions +- long-standing game server lifecycle concepts such as installer metadata, CLI templates, and config-file replacement rules -- GSP has a dedicated `steam_workshop` module that is active in this workspace. -- GSP also has a schema-level `workshop_support` block for XML game templates. -- GSP has a bundled XML validation script for game configs. -- GSP's Steam Workshop handling has been rewritten multiple times in the current history, including admin profile and server-settings work. -- GSP's DayZ/Arma XML handling includes CDATA and validation cleanup that is not described in the older OGP wiki notes. +## Confirmed Current Differences -## Likely Differences That Need More Review +- GSP has a dedicated `steam_workshop` module as an active first-class module +- GSP includes a schema-level `workshop_support` block in game templates +- GSP ships a bundled XML validation script for server configs +- current history shows repeated Workshop and XML maintenance, including admin profile work and XML editor validation improvements +- current installation guidance defaults to the `gsp_` database prefix -- Exactly which legacy OGP XML tags remain supported only for compatibility -- Which modules have diverged from upstream beyond naming and rebranding -- Which database schema differences are intentional versus historical leftovers +## Where Upstream Documentation Still Helps -## Useful Upstream References +The older OGP wiki remains useful as source material for: -- `references/OGP/OGP-Website.wiki/XML-Notes.md` -- `references/OGP/Module-Steam_Workshop/README.md` -- `references/OGP/OGP-Website.wiki/Home.md` +- installation structure +- XML template tag descriptions +- module intent for older or lightly changed modules + +That upstream material has been imported into this wiki where it still matches current GSP behavior, then revised where GSP diverges. + +## Differences That Still Need Review + +- exact compatibility behavior for older XML tags and templates +- which modules have significantly diverged from upstream beyond naming and branding +- which database-level differences are intentional versus historical leftovers ## TODO -- Expand this page with a module-by-module diff once the source audit is complete. +- expand this page with a tighter module-by-module upstream comparison after a deeper source audit diff --git a/Remote-Servers-and-Agents.md b/Remote-Servers-and-Agents.md index 9bab9da..a213cc3 100644 --- a/Remote-Servers-and-Agents.md +++ b/Remote-Servers-and-Agents.md @@ -1,13 +1,13 @@ # Remote Servers and Agents -GSP uses remote communication to control game servers through agents. +GSP uses remote communication to control game servers through agents installed on host machines. -## Current Panel-Side Flow +## Panel-Side Flow -- Panel modules build an action. -- The Panel sends the action through its remote library. -- The agent executes the request. -- The Panel reads back status or logs. +- the panel builds an action request +- the panel sends the request through its remote library +- the remote agent executes the request on the host +- the panel reads back status, output, or file content ## Important Source Areas @@ -15,7 +15,7 @@ GSP uses remote communication to control game servers through agents. - `Panel/Panel/modules/gamemanager/` - `Panel/Panel/modules/steam_workshop/` -## Confirmed Remote Methods Used In Workshop Paths +## Confirmed Remote Methods Seen In Workshop Paths - `steam_cmd(...)` - `steam_workshop(...)` @@ -24,12 +24,14 @@ GSP uses remote communication to control game servers through agents. - `remote_readfile(...)` - `exec(...)` -## Agent Repositories +## Operational Notes -The agent code lives in the separate GSP agent repositories, not in the Panel wiki or the Panel source tree. +- the panel decides policy and prepares trusted requests +- agents execute those requests on the managed host +- agent setup and operating-system packages should be verified against the active agent repository used by the deployment -## Notes +## Related Pages -- The Panel decides policy. -- The agents execute trusted requests and report back. -- Reference material under `references/OGP/` is read-only and should only be used to compare old behavior. +- [Installation](Installation.md) +- [Game Server Management](Game-Server-Management.md) +- [Steam and Workshop](Steam-and-Workshop.md) diff --git a/Requirements-and-Prerequisites.md b/Requirements-and-Prerequisites.md new file mode 100644 index 0000000..3244ee0 --- /dev/null +++ b/Requirements-and-Prerequisites.md @@ -0,0 +1,141 @@ +# Requirements and Prerequisites + +This page collects the practical prerequisites for running the GSP panel. It is based on the original OGP installation documentation and verified against the current GSP environment checker in `Panel/Panel/check.php`. + +## Required Platform + +- Linux web server +- Apache or a compatible web server +- PHP +- MySQL or MariaDB +- Shell utilities used by the panel + +The current panel source strongly indicates Linux as the primary supported panel host environment. + +## Current PHP Baseline + +The current environment checker defines: + +- minimum recommended PHP version: `8.3.0` + +If a different PHP baseline is adopted later, verify `Panel/Panel/check.php` and `Panel/Panel/INSTALL_README.md`. + +## Required PHP Extensions + +The current checker explicitly tests for these PHP extensions or capabilities: + +- `mysqli` +- `curl` +- `gd` +- `mbstring` +- `zip` +- `xml` +- `json` +- `openssl` +- `fileinfo` +- `session` + +It also checks for: + +- `xmlrpc` as an optional or warning-level dependency in the current code path +- PEAR availability + +If packaging differs by distribution, install the equivalent extension names for that OS and PHP version. + +## Web Server Requirements + +For Apache deployments, enable: + +- `mod_rewrite` + +The original OGP installation guidance assumed Apache, and the current GSP checker still validates rewrite support. If a compatible alternative web server is used, verify the equivalent routing and PHP handling manually. + +## Database Requirements + +- MySQL or MariaDB server +- a database and user account for the panel installer +- permission to create tables with the configured prefix + +Current GSP defaults to: + +- table prefix `gsp_` + +## Required Linux Commands + +The current checker looks for these commands: + +- `unzip` +- `tar` +- `screen` +- `sudo` +- `subversion` +- `git` +- `rsync` +- `mysql` + +These should be available in the panel host environment before installation or before using the affected features. + +## Filesystem And Permission Requirements + +The current checker verifies write access to: + +- `includes/` +- `modules/` +- `upload/` +- `cache/` +- `log/` +- `temp/` +- `includes/config.inc.php` + +Practical implications: + +- the web server user must be able to write the configuration file during installation +- runtime cache, upload, temp, and log directories must remain writable +- permissions should be tightened after installation as far as the panel runtime allows + +## Common Package Baseline + +The current Ubuntu 24.04 install notes in `Panel/Panel/INSTALL_README.md` use: + +- `apache2` +- `mysql-client` +- `unzip` +- `tar` +- `screen` +- `sudo` +- `subversion` +- `git` +- `rsync` +- `php8.3` +- `php8.3-mysql` +- `php8.3-gd` +- `php8.3-curl` +- `php8.3-mbstring` +- `php8.3-zip` +- `php8.3-xml` +- `php8.3-xmlrpc` +- `php-pear` +- `libapache2-mod-php8.3` + +Version-specific package names should be verified for the current GSP deployment target. + +## Agent-Side Dependencies + +The original OGP installation docs document a separate set of dependencies for the remote agent layer, including Perl packages and utility tools on the host machine. That separation still matters conceptually for GSP, but the exact current agent package list should be verified against the active GSP agent repository before publishing a production install procedure. + +## Verification Checklist + +Before running the installer: + +1. PHP meets or exceeds the current checked version. +2. Required PHP extensions are installed. +3. Apache rewrite support or equivalent routing is enabled. +4. Database access is ready. +5. Required shell utilities exist in `PATH`. +6. Writable panel directories are writable by the web server. + +## Needs Verification + +- exact non-Apache deployment guidance for Nginx or other web servers +- current agent package matrix by Linux distribution +- whether `xmlrpc` remains optional long-term or becomes removable in a future release diff --git a/Steam-and-Workshop.md b/Steam-and-Workshop.md index 99204ef..71f31a5 100644 --- a/Steam-and-Workshop.md +++ b/Steam-and-Workshop.md @@ -4,10 +4,10 @@ GSP keeps Steam Workshop behavior in the dedicated `steam_workshop` module. ## Current Module Scope -- User-facing Workshop installs and uninstalls +- user-facing Workshop installs and uninstalls - Workshop search and item lookup -- Admin Workshop XML profile management -- Copying Workshop configuration settings between XML files +- admin Workshop XML profile management +- copying Workshop configuration settings between XML files ## Important Paths @@ -17,14 +17,14 @@ GSP keeps Steam Workshop behavior in the dedicated `steam_workshop` module. ## Confirmed Behavior -- The dedicated Workshop module is the active Workshop path in this workspace. -- The admin copy feature copies configuration settings only. -- Installed mods, mod folders, and game server files are not copied by that feature. -- Blank `File Path` means config-file editing is skipped. +- the dedicated Workshop module is the active Workshop path in the current panel +- the admin copy feature is for copying configuration settings only +- installed mods, mod folders, and game server files are not the payload of that copy feature +- blank `File Path` means config-file editing is skipped ## Workshop Config Copy Rule -The copy source dropdown should use a safe XML filename value and the handler should validate that filename before reading from `game_configs/`. +The copy source selector should submit a safe XML filename value, and the handler should validate that filename before reading from `game_configs/`. ## GSP Game XML Support @@ -37,5 +37,5 @@ See: ## Notes -- Do not move Workshop back into `addonsmanager`. -- Treat `references/OGP/` as upstream reference code only. +- do not move Workshop behavior back into `addonsmanager` +- Workshop configuration copying should not touch the game home directory diff --git a/Troubleshooting.md b/Troubleshooting.md index 25f7a6a..57e9506 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -1,25 +1,34 @@ # Troubleshooting -Use this page for fast triage. +Use this page for practical first-pass triage. ## XML Problems -- If a game config fails to load, check `Panel/Panel/modules/config_games/schema_server_config.xml`. -- Run the XML validation script. -- Compare against `references/OGP/` only if you need upstream behavior. +- if a game config fails to load, inspect `Panel/Panel/modules/config_games/schema_server_config.xml` +- run the XML validation script before assuming the runtime parser is wrong +- compare the failing template with a known-good current template such as Arma 3 or Garry's Mod +- verify element order as well as tag names ## Workshop Problems -- If Workshop copy validation fails, verify the source is a safe XML filename under `Panel/Panel/modules/steam_workshop/game_configs/`. -- If the module complains about a missing config file, check the destination XML file and path rules. -- If blank `File Path` still tries to edit a game file, that is a bug. +- if Workshop config copy validation fails, verify the source identifier is only a safe XML filename from the Workshop config set +- if the module complains about a missing config file, verify path normalization and that the file remains inside the expected `game_configs` directory +- if blank `File Path` still triggers config-file editing against a game home path, that is a bug +- if Workshop behavior differs between games, compare both the dedicated Workshop XML profile and the related game template's `workshop_support` block -## Remote and Agent Problems +## Installation Problems -- Confirm the agent is online. -- Confirm the remote library can reach the server. -- Confirm the requested action is still within the module's supported workflow. +- run `check.php` and clear every blocker before retrying `install.php` +- verify required PHP extensions, PEAR, and shell utilities are installed +- verify writable directories and `includes/config.inc.php` +- verify Apache rewrite support if Apache is the active web server -## Notes +## Remote And Agent Problems -- When a problem seems to involve old OGP behavior, inspect the matching file under `references/OGP/` and fix the GSP code only. +- confirm the remote agent is reachable and registered correctly +- confirm the panel-side remote library can perform the expected action +- confirm the requested operation still belongs to the currently supported module workflow + +## Legacy Behavior Questions + +If current behavior is unclear, older OGP behavior may still explain why a workflow exists, but current GSP source and current GSP templates should be treated as authoritative. diff --git a/XML-Schema-and-Validation.md b/XML-Schema-and-Validation.md index 4db2450..74a269c 100644 --- a/XML-Schema-and-Validation.md +++ b/XML-Schema-and-Validation.md @@ -1,55 +1,164 @@ # XML Schema and Validation -This page explains where GSP validates XML and how to check changes safely. +This page documents how GSP validates game template XML, where the schema lives, and which current differences have been confirmed against the older OGP XML documentation. -## Current Validation Path +## Current Validation Files -Primary files: +Primary files in the current panel tree: - `Panel/Panel/modules/config_games/schema_server_config.xml` - `Panel/Panel/modules/config_games/server_config_parser.php` - `Panel/Panel/modules/config_games/tests/validate_server_configs.php` -- `Panel/Panel/includes/lib_remote.php` +- `Panel/Panel/modules/config_games/xml_tag_descriptions.php` -## How Validation Works +## Runtime Validation Flow -- `read_server_config()` loads a game XML file and validates it against the bundled schema. -- The validation test script loads every XML file in `server_configs/` and validates each one against the same schema. -- XML parse failures and schema failures are treated as real errors, not warnings. +The current parser in `server_config_parser.php` uses a schema-validated load path: -## How To Validate XML Changes +1. load the XML with DOM support +2. validate it against `schema_server_config.xml` +3. import the validated DOM into SimpleXML for normal runtime access -1. Edit the XML file in `Panel/Panel/modules/config_games/server_configs/`. -2. Confirm the XML is well-formed. -3. Run the bundled validation script: +That is materially stronger than documentation-only validation. Current GSP expects template files to be both well-formed and schema-valid. + +## Developer Validation Workflow + +When editing a game template or the schema: + +1. update the XML file under `Panel/Panel/modules/config_games/server_configs/` +2. keep the element order aligned with the schema +3. run the bundled validation script +4. fix every parse or schema error before treating the change as complete + +Validation command: ```bash php Panel/modules/config_games/tests/validate_server_configs.php ``` -4. Fix any schema or parse errors before merging. +## What The Schema Covers -## GSP-Specific XML Findings +The current schema validates the classic OGP-era template structure, including: -Confirmed from the current source: +- identification tags such as `game_key` and `game_name` +- query and control protocol tags +- installer and mod definitions +- CLI templates and CLI parameter definitions +- reserved ports +- replace-text instructions +- custom fields +- player parsing and player actions +- lifecycle scripts +- environment variables +- lock files +- configuration file registration -- `workshop_support` is part of the schema. -- `workshop_support` is positioned after `game_name` and before `server_exec_name`. -- The schema includes explicit Workshop install strategy values. -- The validation script is part of the current Panel tree, not just a reference note. +The detailed tag guide remains in [Game Template XML](Game-Template-XML.md). + +## Confirmed GSP XML Differences + +Compared with the older OGP XML notes, the current GSP schema clearly includes additional or more explicit behavior. + +### 1. `workshop_support` block + +Current GSP includes a schema-level `workshop_support` section. This is the largest confirmed difference from the older upstream XML notes. + +Confirmed child tags: + +- `enabled` +- `provider` +- `steam_app_id` +- `workshop_app_id` +- `download_method` +- `install_strategy` +- `install_path` +- `startup_param_format` +- `mod_separator` +- `mod_prefix` +- `mod_folder_format` +- `copy_keys` +- `post_install_action` + +### 2. Expanded control protocol values + +Current schema confirms support for: + +- `rcon` +- `rcon2` +- `lcon` +- `armabe` + +and also confirms `control_protocol_type` values: + +- `new` +- `old` + +### 3. Expanded mod metadata + +Current schema confirms additional mod fields beyond the older basic examples: + +- `installer_login` +- `betaname` +- `betapwd` +- `steam_bitness` + +### 4. Expanded replace-text metadata + +Current schema confirms additional replacement fields: + +- `alltext` +- `occurrence` + +### 5. Expanded server parameter structure + +Current schema confirms richer parameter metadata: + +- `group` +- `attribute` +- `default` +- `access` + +### 6. Configuration file metadata + +Current schema confirms `configuration_files` entries with file descriptions. + +## Current Source Evidence + +The following current templates are useful concrete examples: + +- `Panel/Panel/modules/config_games/server_configs/arma3_linux64.xml` +- `Panel/Panel/modules/config_games/server_configs/arma3_win64.xml` +- `Panel/Panel/modules/config_games/server_configs/garrysmod_linux.xml` +- `Panel/Panel/modules/config_games/server_configs/dayz_epoch_mod_win32.xml` + +These files demonstrate both classic template structure and current GSP additions. ## Git History Notes -Searches in the current Panel history show several XML-related changes, including: +Current Panel history shows multiple XML-related changes, including: -- `5a03946d...` `woekshop phase 1` -- `69f415ad...` `feat(steam_workshop): production rewrite with full admin profile page and server settings` -- `6d9cd28a...` `feat: Server Content Phase 2 - schema, cache mode setting, install history, manifest, requires_stop` -- `de80f896...` `fix: wrap DayZ post_install scripts in CDATA, add XML editor auto-sanitizer` -- `d564476d...` `feat: GSP 1.0 baseline - module versions, FAQ refresh, XML editor validation, Obsidian theme` +- `5a03946b` `woekshop phase 1` +- `69f415ad` `feat(steam_workshop): production rewrite with full admin profile page and server settings` +- `6d9cd28a` `feat: Server Content Phase 2 – schema, cache mode setting, install history, manifest, requires_stop` +- `de80f896` `fix: wrap DayZ post_install scripts in CDATA, add XML editor auto-sanitizer` +- `d564476d` `feat: GSP 1.0 baseline – module versions, FAQ refresh, XML editor validation, Obsidian theme` +- `3e704551` `removed .32bit xml files` + +From those commits, the most defensible current conclusions are: + +- Workshop-aware XML support has been added and revised in GSP. +- XML editor and validation behavior has been actively maintained. +- Some legacy templates were removed or consolidated over time. + +## How Admins And Developers Should Validate XML + +- use the schema validator before deploying a modified template +- keep examples aligned with real files already present in `server_configs/` +- treat parser or schema failures as blocking errors +- verify any script-heavy template changes, especially `post_install`, with extra care because GSP history shows active fixes in that area ## Needs Verification -- The exact timeline of every XML tag addition -- Whether any non-schema XML tags are intentionally accepted by runtime code -- Whether additional validation exists in any module outside `config_games` +- exact commit-by-commit introduction point for every new XML tag +- whether any runtime-only compatibility behavior accepts out-of-schema legacy tags +- whether all XML tag descriptions in `xml_tag_descriptions.php` fully match the runtime parser semantics