# How to Set Up a Soulmask Server Cluster (/docs/soulmask/cluster-setup) import { File, Folder, Files } from 'fumadocs-ui/components/files'; import { Step, Steps } from 'fumadocs-ui/components/steps'; A Soulmask cluster is two or more dedicated servers linked together so players can travel between maps with the same character. One server acts as the **main** server (which also stores the shared player accounts), and one or more **client** servers connect to it. > ⚠️ **Cluster setup is Windows-only for cross-server character migration.** The `CopyRoles.exe` tool used to onboard existing players to a cluster does not ship with the Linux dedicated server. New characters created inside the cluster work on either OS. *** How a Cluster Works [#how-a-cluster-works] | Server role | Stores | Notes | | ----------- | ------------------------------------------ | ------------------------------------------------------------------------- | | Main | World save **and** the shared `account.db` | Must start first, stop last. If offline, client servers stop functioning. | | Client | Its own world save only | Connects to the main server for player account data. | Each server gets a unique numeric ID (`-serverid`). World data — buildings, inventories, tribesmen — is per-server. Player progression — character, awareness, tech unlocks — lives on the main server's `account.db` and follows the player when they travel. *** Required Launch Parameters [#required-launch-parameters] Set these in the **Startup** tab of your [XGamingServer Panel](https://panel.xgamingserver.com). Main server [#main-server] | Parameter | Description | | ----------------------- | ------------------------------------------------------------------------------------------------------ | | `-serverid=1` | Unique numeric ID for this server. | | `-mainserverport=20000` | TCP port client servers connect to. **Do not expose publicly** — only accessible to the cluster nodes. | Client server [#client-server] | Parameter | Description | | ------------------------------------ | ----------------------------------------------------------------------------- | | `-serverid=2` | Unique numeric ID — must be different from every other server in the cluster. | | `-clientserverconnect=MAIN_IP:20000` | IP and `mainserverport` of the main server. | Example startup commands [#example-startup-commands] **Main server (Cloud Mist Forest):** ``` WSServer-Win64-Shipping Level01_Main -log -server -UTF8Output -serverid=1 -mainserverport=20000 -PORT=8777 -QueryPort=27015 -EchoPort=18888 -forcepassthrough -SteamServerName="My Cluster Main" -PSW="serverPass" -adminpsw="adminPass" -saving=600 -backup=900 ``` **Client server (Shifting Sands DLC):** ``` WSServer-Win64-Shipping DLC_Level01_Main -log -server -UTF8Output -serverid=2 -clientserverconnect=10.10.1.5:20000 -PORT=8778 -QueryPort=27016 -EchoPort=18889 -forcepassthrough -SteamServerName="My Cluster Sands" -PSW="serverPass" -adminpsw="adminPass" -saving=600 -backup=900 ``` *** Enable Cross-Server Travel [#enable-cross-server-travel] Cross-server travel is **off by default**. Enable it on every server you want players to be able to travel **out from** (incoming travel is always allowed). Option 1 — In-game admin panel [#option-1--in-game-admin-panel] After authenticating with `gm key `, open the GM panel and toggle **Cross-server Mode**. Option 2 — Edit the config file [#option-2--edit-the-config-file] Stop the server. In **File Manager**, open `WS/Saved/GameplaySettings/GameXishu.json`. Set: ```json "KaiQiKuaFu": 1 ``` Save and start the server. *** Onboarding Existing Players [#onboarding-existing-players] If your players already have characters on a standalone server, copy their progression into the cluster's `account.db` using the [CopyRoles tool](/docs/soulmask/copyroles-tool) before joining the world to the cluster. > The map name **must remain the same** after migration. If your standalone server ran `Level01_Main`, the cluster node hosting that map must also be `Level01_Main`. *** Networking Checklist [#networking-checklist] | Port | Purpose | Public? | | ----------------------- | ------------------------- | ------------------------------ | | `-PORT=8777` (game) | Game traffic | Yes | | `-QueryPort=27015` | Server browser query | Yes | | `-EchoPort=18888` | Telnet (loopback only) | No | | `-mainserverport=20000` | Cluster comms (main only) | **No — cluster-internal only** | Each server in the cluster needs **unique** `PORT`, `QueryPort`, and `EchoPort` values. The `mainserverport` only needs to be set on the main, and reachable from every client server. *** Troubleshooting [#troubleshooting] **Client server starts but won't accept players** * Check that the main server is online and started **first** * Confirm `-clientserverconnect` IP and port match the main's `-mainserverport` * Verify the `mainserverport` is reachable between the two hosts (firewall, VPC routing) **Players told their character is "on the original server"** * The standalone-to-cluster migration was not completed with `CopyRoles.exe`. See [CopyRoles tool](/docs/soulmask/copyroles-tool). **"Connecting to a cluster with mismatched server versions" warning / players asked to recreate character** * All servers in the cluster must run the same Soulmask version. Update every node, then if `account.db` is showing double-compressed actor data, run the [save fix tool](/docs/soulmask/save-fix). *** Related Guides [#related-guides] * [CopyRoles Tool](/docs/soulmask/copyroles-tool) * [Save Fix Tool](/docs/soulmask/save-fix) * [Building Transfer](/docs/soulmask/building-transfer) * [Server Configuration](/docs/soulmask/server-config) * [Update Your Server](/docs/soulmask/update-guide)