Soulmask Server Cluster Guide
This document details how to group multiple self-hosted dedicated Soulmask servers into a cluster. Clustered servers allow players to move characters between them.
Getting Started
The first step of setting up a cluster is setting up the individual servers that will be in the cluster. You can reference the dedicated server setup guide for information about this.
If the servers will be running at the same public IP, be sure to give them unique ports (game, query, etc.) and that all ports are open and properly forwarded. You can run the servers on the same host machine or separate machines as desired.
The intended use case for clustering is to have one server hosting each available game map. While it is possible to cluster servers that are hosting the same map, there may be some unexpected behavior of player progression that works differently when moving between different maps.
Also, it is recommended that all servers in a cluster are running the same game mode. Mixing game modes can lead to some confusing behavior when transferring characters.
TIP: Include information about which map each server is hosting as part of your server names. Otherwise, players will not be able to tell using the information provided in the game menu.
Once you have at least two servers installed and able to run, then you are ready to set up a cluster.
Cluster Setup
For each server that will be part of the cluster, you will need to add command line parameters to your server startup script.
Main Server
You will need to designate one server as the main server for the cluster. In addition to hosting a world, this server will also manage player accounts for the cluster. If this server is offline, client servers will not function.
Within your main server startup script, add the following command line parameters:
| Parameter | Example | Description |
|---|---|---|
| -serverid=[id] | -serverid=1 |
A numeric ID that identifies the server. This is necessary to allow characters to travel to the server. The ID must be unique within the cluster. |
| -mainserverport=[port] | -mainserverport=20000 |
The TCP broadcast port that client server will connect to. The presence of this parameter designates the server as a main server for a cluster. This port should not be open to the public, but needs to be accessible to servers within the cluster. Any server with access to the port can register as a client server. |
Example
Here is an example of a potential startup command line for a main server running the Cloud Mist Forest map.
WS\Binaries\Win64\WSServer-Win64-Shipping Level01_Main -log -server -UTF8Output -serverid=1 -mainserverport=20000 -PORT=8777 -QueryPort=27015 -EchoPort=18888 -forcepassthrough -SteamServerName="my main server name" -PSW="my password" -adminpsw="admin password" -saving=600 -backup=900
Client Server
A cluster can contain one or more client servers which connect to the main server to become part of the cluster. A client server will not function when the main server is offline.
Within your client server startup script, add the following command line parameters:
| Parameter | Example | Description |
|---|---|---|
| -serverid=[id] | -serverid=2 |
A numeric ID that identifies the server. This is necessary to allow characters to travel to the server. The ID must be unique within the cluster. |
| -clientserverconnect=[ip:port] | -clientserverconnect=10.10.1.5:20000 |
The IP and broadcast port of the main server to connect to. The presence of the parameter designates the server as a client server in a cluster. |
Example
Here is an example of a potential startup command line for a client server running the Shifting Sands map.
WS\Binaries\Win64\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 client server name" -PSW="my password" -adminpsw="admin password" -saving=600 -backup=900
Enable Character Transfers
If you want players to be able to travel from this server to others within the cluster, you will need to enable the "Cross-server Mode" toggle in the server settings. This can be done from the admin panel in-game.
Another option is to edit the file WS/Saved/GameplaySettings/GameXishu.json and set "KaiQiKuaFu=1". Note that the settings file has three sections named 0, 1 and 2. Each may have copies of all settings. Usually section 1 is the one you need to change, but you can also change the setting in all three sections to be sure.
If you want to start a fresh server with transfers enabled from the start, you can create a config file ahead of time at WS/Saved/GameplaySettings/GameXishu.json with that setting in it. The server will fill in the rest of the file when you run it. You can download a premade GameXishu.json or copy from this example:
{
"0":
{
},
"1":
{
"KaiQiKuaFu": 1
},
"2":
{
}
}
You can toggle "Cross-server Mode" on and off as desired depending whether you want to allow players to move characters out of the server or not. Each server in the cluster has independent control of whether characters are allowed to leave. The setting only controls outbound transfers. Inbound transfers are always allowed.
Server Shutdown/Restart
When shutting down or restarting clustered servers, the main server should always be the first one started and the last one stopped.
If the main server attempts to shut down while clients are still connected, it may hang. Afterwards, attempting to shut down the clients will result in errors. If you shut down clients first before the main server, then everything should shut down cleanly.
Servers can be started in any order, but client servers will not allow player connections until they have established a connection with the main server. Starting the main server first is usually the best option.
Migrate Existing Save
IMPORTANT PLEASE READ
If you are starting a fresh save, you can ignore this section. If you want to migrate a preexisting save, continue reading.
In order to convert an existing save into one that is compatible with a server cluster, you will need to perform a migration of the player account data. The reason for this is that player account data is stored differently on a standalone server compared to a server cluster. In a standalone server, the player account data is stored inside of world.db along with the rest of the save data. In a server cluster, the player account data is stored in a separate account.db file store on the main server of the cluster.
When migrating player data from a standalone server to a cluster, the server which will run the original map that the players were playing on must have the exact same name as it did before the migration. If the name is different, players will not be able to log in and will be presented with a message saying their data is on a different server.
How to Migrate
Within the files of the main server in a server cluster, player account data is stored at this path: WS/Saved/Accounts/account.db. Client servers do not contain player account data.
All other save data is stored at this path: WS/Saved/Worlds/Dedicated/[map_name]/world.db. This data exists independently for all servers.
For non-clustered servers (as well as local / single player saves), all data is combined into the world.db file. You will need to copy the player account data out of world.db into account.db when migrating to a cluster server.
CopyRoles Tool
A tool to assist with migrating save data is included with the game client, as well as with the Windows version of the dedicated server. This tool can be used to copy player account data from a world.db to a new account.db file.
This tool can be found at the following path within the dedicated server or game client install directory: WS/Plugins/DBAgent/ThirdParty/Binaries/CopyRoles.exe. There is also a Readme.txt file next to it with usage instructions.
Note: At the time of this writing, the Linux dedicated server distribution does not contain this tool, and no known Linux version of the tool exists. You can still use the Windows version of the tool to create an account.db file that will work on a Linux server.
IMPORTANT: Before running the tool, make sure you have a backup of your save file. Although it should be safe to use, if any mistake is made, you will want a backup to recover from.
Here is an example of running the tool to create an account.db from an existing world.db on an existing server.
WS/Plugins/DBAgent/ThirdParty/Binaries/CopyRoles.exe -src=WS/Saved/Worlds/Dedicated/Level01_Main/world.db -dst=WS/Saved/Accounts/account.db
After running that command, you should then be able to start your cluster servers and login to verify that players log into their existing characters. If players are prompted to create new characters, then something went wrong.
For more options and use cases, refer to the CopyRoles tool guide as well as the Readme.txt file included with the tool.
Character Transfer Details
When "Cross-server Mode" is enabled, players can visit the mysterious island location in the world using any character except for their initial character, then interact with the server travel object. This will present a list of server in the cluster that they can travel to. If "Cross-server Mode" is disabled, players will receive a message when attempting to interact informing them that the feature is disabled.
If the server the player is transferring to is password protected, they may be sent to the main menu of the game with an error that the password is incorrect. If this happens, they can simply log in to the server they were attempting to transfer to and will find that they have successfully transferred the character. This will hopefully be fixed in the future to allow a seamless transition to password protected servers.
A player may join any server in a cluster the first time they connect. Once they have created their server account by creating an initial character, they cannot log into other servers in the cluster without first using the mysterious portal to transfer a character to that server. Once they have transferred a character, they will then be locked into the new server until they transfer a character back. A player may only connect to the server they most recently transferred to. If they attempt to connect to another server in the cluster, they will be presented with a message and given the option to login to the connect to the appropriate server.
Move Between Servers
For players to move between servers in a cluster, they will need to visit the mysterious island in the ocean of either map while controlling a tribesman that is not their initial character.
Interact with the terminal in front of the portal to open a menu where you can select a server to transfer to. Once you confirm, you should get a loading screen and then appear in the other server at the mysterious island portal.
Transfer Errors
Common issues players may encounter when attempting to transfer between servers.
Incorrect Password
If you are sent to the main menu with a password error, that means the server you are transferring to does not have the same password as the server you are transferring from. In this case, you can manually join the destination server after initiating the transfer. However, it is ideal to set the same password on all servers in a cluster to allow for seamless transfers.
"Cross-server mode locked"
This message appears when you attempt to access the portal terminal while the current server has disabled cross-server mode in the game settings. To enable transfers, open the admin menu, then the coefficients menu, search the right column for "Cross-server Mode" and enable it. You will need to do this on each server that you want to allow players to transfer out of.
"Initial tribesmen cannot join the Cross-server mode"
This message appears when you attempt to initiate a server transfer with your initial character. Your initial character cannot travel through the portal to another server. You need to take control of a different tribesman and transfer them instead.
If you wish, you can summon your initial character on the other server from a bonfire by selecting "Remodel Initial Character" from the bonfire menu. Your initial character will then exist on both servers at the same time, but you still can only join the server you most recently transferred to.
Troubleshooting
Tips to help resolve potential server cluster issues.
Failing to create cluster
If you are having trouble linking your servers, you may have missing or incorrect parameters in your startup script. Double check that the broadcast port is available and reachable, and that the client server has specified the correct IP and port for the main server. Here are some log messages to check for to determine if the connection is working.
Main Server
When a client server connects to the main server, there should be a log message that looks something like this in the main server log. (The port will be a random dynamic port.)
logReactor: Display: [...][ProcessListenEvent]1.2@10.10.1.5:64825 connected.
Client Server
When a client is failing to connect to a main server, there will be messages that looks something like this in the client server log. The server will keep trying to connect, and these messages will continue to repeat each time it attempts.
LogFTCPClient: Error: [FTCPClient]:Connect:110.10.1.5:20000 Failed!
A message like the following will print each attempt regardless if the connection was successful or not.
LogFTCPClient: [FTCPClient]:Connect10.10.1.5:20000 Succeed!
Unable to transfer character
When attempting to access the mysterious island portal terminal, if you receive a message saying that cross server is unavailable, it means that "Cross-server Mode" is not enabled in the server settings. You can enable this from the coefficients menu within the admin menu in game.
If you receive a message that initial character is not allowed, that means you are attempting to change servers with your initial/starting character. Only a controlled tribesman is allowed to use the cross server terminal. If you want to move your initial character, cross over with a tribesman, and then respawn your initial character at a bonfire on the other server.
Unable to connect to server
When attempting to connect to a cluster server, if you receive the error "Failed to join the server. Please try again later.", it usually means the client server is not connected to the main cluster server. See failing to create cluster above.
Other Issues
For other server related issues, check the troubleshooting section of the dedicated server guide.
More Information
For additional server setup information, refer to the dedicated server guide.