# XML Game Configuration System

## Purpose

The XML game configuration system describes how a game server should be started, queried, and customized.

Primary files:

- `Panel/modules/config_games/schema_server_config.xml`
- `Panel/modules/config_games/server_config_parser.php`
- `Panel/modules/config_games/xml_config_creator.php`
- `Panel/modules/config_games/config_servers.php`
- `Panel/modules/config_games/cli-params.php`
- `Panel/modules/config_games/set_params.php`

## What XML Controls

The schema supports:

- game and installer names
- startup command templates
- CLI parameter substitution
- reserved ports
- query port calculation
- control protocol selection
- mod definitions
- Workshop / Server Content capability declarations
- custom fields
- server parameter groups
- text replacement helpers

## Important Variables

The schema and startup builder can work with variables such as:

- `GAME_TYPE`
- `HOSTNAME`
- `IP`
- `MAP`
- `PID_FILE`
- `PLAYERS`
- `PORT`
- `QUERY_PORT`
- `BASE_PATH`
- `HOME_PATH`
- `SAVE_PATH`
- `OUTPUT_PATH`
- `USER_PATH`
- `CONTROL_PASSWORD`

## Startup Parameters

The Panel builds startup parameters from the XML template and the stored server configuration.

Key concepts:

- `cli_template`
- `cli_params`
- `reserve_ports`
- `server_params`
- `custom_fields`
- `clean_server_param_value`

The XML file defines:

- which parameters exist
- how they are quoted or spaced
- whether the parameter is editable by the customer
- what defaults should be used

## Query Definitions

The XML schema supports query-related concepts such as:

- `gameq`
- `lgsl`
- `teamspeak3`
- query port offset calculations
- control protocol selection

These values are used by `gamemanager` and the agent status logic to calculate query metadata, not to decide online/offline by themselves.

## Installation and File Editing

XML definitions also feed:

- config file shortcuts
- install-time behavior
- docs links
- reserved ports
- mod or content behavior

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

Example:

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

Supported `install_strategy` values:

- `game_managed_workshop`
- `steamcmd_download_only`
- `copy_to_game_root`
- `copy_to_mod_folder`
- `dayz_mod_folder`
- `arma_mod_folder`
- `config_only`
- `custom_scripted_install`

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

The current XML schema is validated by:

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

## Recommended Mental Model

Think of the XML system as the capability definition layer:

```text
game XML
  -> startup template
  -> parameter rules
  -> query rules
  -> content/mod hooks
  -> docs links
  -> scheduler and status hints
```