> 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/connectserver.md).

# Overview

ConnectServer is the first component the game client talks to. It serves the group/server list that players see on the selection screen, then hands them off to the chosen GameServer. It also tracks which GameServers and JoinServer are alive via UDP heartbeats.

## Role

* Listens for client connections on TCP and replies with the server list
* Receives UDP heartbeats from GameServers (user counts, load)
* Receives UDP heartbeats from JoinServer (auth queue size)
* Marks any server silent for more than 10 seconds as offline
* Limits simultaneous connections per source IP

## File Location

```
ConnectServer/
├── ConnectServer.exe
├── ConnectServer.ini
├── ServerList.xml
├── msvcp100.dll
└── Log/
    └── YYYY-MM-DD.txt
```

All configuration lives in the ConnectServer root. There is no `Data/` subfolder.

## Configuration Files

| File                                                            | Purpose                                           |
| --------------------------------------------------------------- | ------------------------------------------------- |
| [`ConnectServer.ini`](/docs/connectserver/connectserver-ini.md) | Ports, per-IP connection cap, license             |
| [`ServerList.xml`](/docs/connectserver/serverlist-xml.md)       | Groups and GameServer entries shown to the client |

## Startup Order

{% stepper %}
{% step %}

#### License activation

Reads `LicenseKey` from `ConnectServer.ini`. Failure aborts startup.
{% endstep %}

{% step %}

#### Open TCP and UDP sockets

Opens `ConnectServerPortTCP` (clients) and `ConnectServerPortUDP` (heartbeats).
{% endstep %}

{% step %}

#### Load server list

Reads `ServerList.xml`. A malformed file prevents the list from loading; clients connect but see no servers.
{% endstep %}
{% endstepper %}

## Dependencies

* **JoinServer** reachable from the network; it sends UDP heartbeats to `ConnectServerPortUDP`
* **GameServers** configured to send UDP heartbeats to the same port
* Firewall rule opening `ConnectServerPortTCP` to the public internet

## Heartbeat and Offline Detection

ConnectServer expects each live GameServer and the JoinServer to send a UDP heartbeat every few seconds. Any source silent for more than 10 seconds is marked offline and logged.

* A GameServer marked offline is still listed to clients, but shown as offline (connect attempts will fail)
* If JoinServer is offline, every GameServer in the list is reported offline to clients regardless of its own heartbeat state, because login cannot proceed without JS
* Offline state clears automatically when heartbeats resume

## JoinServer Queue Backpressure

JoinServer reports its current auth queue size in each heartbeat. If the queue exceeds 100 entries, ConnectServer treats JoinServer as unavailable and reports all servers offline to new clients until the queue drains. This prevents a login storm from overwhelming JoinServer.

## Logs

`Log/YYYY-MM-DD.txt` is appended throughout the day. A new file is opened on the first log event after the local date changes. Old log files accumulate; archive or delete as needed.

## Common Issues

* **Client shows empty server list** - `ServerList.xml` failed to parse, or the file is missing
* **All servers always appear offline** - JoinServer is not reaching `ConnectServerPortUDP`, or its heartbeat queue is above 100
* **One GameServer always shows offline** - that GameServer's `ConnectServerIP` and heartbeat port do not match this host, or a firewall blocks UDP
* **Clients cannot connect at all** - `ConnectServerPortTCP` is blocked upstream, or `MaxIpConnection` is set to `0` (see [ConnectServer.ini](/docs/connectserver/connectserver-ini.md))

## Related

* [ConnectServer.ini](/docs/connectserver/connectserver-ini.md) - ports, per-IP connection cap, license
* [ServerList.xml](/docs/connectserver/serverlist-xml.md) - groups and per-server entries shown to clients
* [MapServerInfo.xml](/docs/data/mapserverinfo.md) - GameServer-side map ownership used for cross-server messaging