> 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

Server groups and GameServer entries shown to the client on the selection screen

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