> For the complete documentation index, see [llms.txt](https://axiomemu.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://axiomemu.gitbook.io/docs/connectserver/serverlist-xml.md).

# ServerList.xml

Defines the groups (world tabs) and GameServers players see when choosing where to play. Every entry here must have a matching GameServer running and configured with the same code.

## File Location

```
ConnectServer/ServerList.xml
```

Loaded once at startup. Changes require a ConnectServer restart.

## Structure

```xml
<ServerList>
    <Group Name="..." Position="..." Sequence="..." Description="...">
        <Server Code="..." IP="..." Port="..." Visible="..." NonPVP="..." Description="..." />
    </Group>
</ServerList>
```

## Group Attributes

| Attribute     | Type   | Range         | Default   | Effect                                                                             |
| ------------- | ------ | ------------- | --------- | ---------------------------------------------------------------------------------- |
| `Name`        | string | <= 31 chars   | `Server`  | Group name shown as a tab/button on the server select screen                       |
| `Position`    | int    | `0`, `1`, `2` | `0`       | Layout column: `0` = left, `1` = right, `2` = center                               |
| `Sequence`    | int    | 0-255         | `0`       | Sort order within its position column. Lower shows first. Keep unique per position |
| `Description` | string | <= 63 chars   | *(empty)* | Tooltip text when hovering the group on the client                                 |

## Server Attributes

| Attribute     | Type   | Range       | Default      | Effect                                                                                                              |
| ------------- | ------ | ----------- | ------------ | ------------------------------------------------------------------------------------------------------------------- |
| `Code`        | int    | 0-65535     | *(required)* | Unique server code. Must match the GameServer's `ServerCode`. See [Code ranges and groups](#code-ranges-and-groups) |
| `IP`          | string | IPv4        | `127.0.0.1`  | Public IP of the GameServer as reached by game clients                                                              |
| `Port`        | int    | 1-65535     | *(required)* | TCP port of that GameServer                                                                                         |
| `Visible`     | 0 or 1 |             | `1`          | `1` = shown in the list. `0` = hidden (used for Castle Siege sub-servers and other internal instances)              |
| `NonPVP`      | 0-3    |             | `0`          | PVP mode flag. See [NonPVP](#nonpvp)                                                                                |
| `Description` | string | <= 63 chars | *(empty)*    | Per-server tooltip shown beside the entry                                                                           |

## Code Ranges and Groups

Each group owns a 20-code range derived from the first server's `Code`:

* Group containing `Code = 0` covers codes 0-19
* Group containing `Code = 20` covers codes 20-39
* Group containing `Code = 40` covers codes 40-59

Servers inside a group must use codes within the group's range. The client packs per-server data using `Code / 20` as the group index, so a stray code in the wrong range will appear on the wrong tab or not at all.

{% hint style="warning" %}
Maximum 20 servers per group. Extra `<Server>` entries beyond the 20th are silently dropped at load time.
{% endhint %}

## NonPVP

Per-server gameplay mode flag sent to the client.

| Value | Label   | PVP      |
| ----- | ------- | -------- |
| `0`   | Normal  | Enabled  |
| `1`   | Non-PVP | Disabled |
| `2`   | Gold    | Enabled  |
| `3`   | Gold    | Disabled |

"Gold" servers are shown with a different icon on the selection screen; the value does not change GameServer behavior on its own. The matching GameServer still needs its own PVP and rate configuration.

## Online/Offline State

The state shown to the client is not set in this file. It comes from live heartbeats:

* If the GameServer has not sent a UDP heartbeat in the last 10 seconds, it is shown offline
* If JoinServer is offline or its queue is above 100, every server is shown offline regardless

See [ConnectServer overview](/docs/connectserver/connectserver.md#heartbeat-and-offline-detection) for details.

## Important Behavior

* If the XML parser fails on any syntax error the entire file is rejected and no servers are loaded
* Duplicate `Code` values across groups produce undefined behavior on the client; each code must be unique across the entire file
* `Port` applies to the GameServer's client-facing TCP port, not its DataServer or JoinServer ports
* `Visible="0"` servers still need to be listed here if the GameServer is running; otherwise heartbeats from that server are dropped
* Changing `Name`, `Position`, or `Sequence` reorders the client UI; players may be confused on first login after edits
* The menu item Reload > Reload ServerList re-reads this file without restarting ConnectServer

## Examples

{% tabs %}
{% tab title="Single group, four servers" %}
{% code title="ServerList.xml" %}

```xml
<ServerList>
    <Group Name="Tarkan [EU]" Position="0" Sequence="0" Description="Main European Server">
        <Server Code="0" IP="127.0.0.1" Port="55901" Visible="1" NonPVP="0" Description="Standard with PVP" />
        <Server Code="1" IP="127.0.0.1" Port="55903" Visible="1" NonPVP="1" Description="Standard Non-PVP" />
        <Server Code="2" IP="127.0.0.1" Port="55904" Visible="1" NonPVP="2" Description="Gold with PVP" />
        <Server Code="3" IP="127.0.0.1" Port="55905" Visible="1" NonPVP="3" Description="Gold Non-PVP" />
    </Group>
</ServerList>
```

{% endcode %}
{% endtab %}

{% tab title="Two groups on two columns" %}
{% code title="ServerList.xml" %}

```xml
<ServerList>
    <Group Name="Tarkan [EU]" Position="0" Sequence="0" Description="Main EU">
        <Server Code="0" IP="10.0.0.10" Port="55901" Visible="1" NonPVP="0" />
        <Server Code="1" IP="10.0.0.10" Port="55903" Visible="1" NonPVP="1" />
    </Group>
    <Group Name="Aida [EU]" Position="0" Sequence="1" Description="Low rates">
        <Server Code="20" IP="10.0.0.11" Port="55902" Visible="1" NonPVP="0" />
    </Group>
    <Group Name="Atlans [US]" Position="1" Sequence="0" Description="North America">
        <Server Code="40" IP="10.0.1.10" Port="55901" Visible="1" NonPVP="0" />
    </Group>
</ServerList>
```

{% endcode %}
{% endtab %}

{% tab title="Hidden Castle Siege sub-server" %}
{% code title="ServerList.xml" %}

```xml
<ServerList>
    <Group Name="Tarkan" Position="0" Sequence="0" Description="Main">
        <Server Code="0" IP="10.0.0.10" Port="55901" Visible="1" NonPVP="0" />
        <Server Code="1" IP="10.0.0.10" Port="55902" Visible="0" NonPVP="0" Description="Castle Siege" />
    </Group>
</ServerList>
```

{% endcode %}

The hidden server still needs its own GameServer process and heartbeat; it just does not appear on the selection UI.
{% endtab %}
{% endtabs %}

## Common Issues

* **Server appears in wrong tab** - `Code` does not fall inside the group's 20-code range
* **21st server in a group is missing** - only the first 20 load; split into a second group
* **Server listed but always offline** - GameServer process not running, its `ConnectServerIP` points elsewhere, or UDP is blocked between hosts
* **File loads but no servers show** - every server has `Visible="0"`
* **"Gold" icon missing for gold servers** - `NonPVP` set to `0` or `1` instead of `2` or `3`
* **Client crashes on server select** - an XML syntax error truncated the file at load time; check ConnectServer logs

## Related

* [ConnectServer.ini](/docs/connectserver/connectserver-ini.md) - ports, per-IP connection cap, license
* [MapServerInfo.xml](/docs/data/mapserverinfo.md) - how GameServer instances discover each other for cross-server operations; `Code` values there must match `<Server Code>` here