Soulmask CopyRoles Tool Guide

Included with the Soulmask game installation is a tool called CopyRoles that can be used to copy player data from one save file to another.

Disclaimer: Testing was performed on a pre-release version of the game. There may be some differences in the final release that make some of this information no longer correct.

About Player Data

Within each world.db save file, among all the other things stored in there, is a "player state" actor for each player that has played in that world. (In a single player save, there would only be one.) This actor stores information about the player's initial character, their awareness level, tech unlocks, etc. It does not store things like their inventory, their tribesmen or their buildings. Those are stored separately.

In the case of a world.db from a dedicated server, the player state also stores the name and id of the server itself for each player. This imposes a limit on some of the player data copying you can do from a server save (more on that later).

For dedicated servers that are part of a server cluster, the player state data is stored in a separate file called account.db on the cluster's main server. In this configuration, world.db will not contain player states. It is important to know where the player state data is located when using the CopyRoles tool.

Tool Location

The CopyRoles tool can be found withing the game's installation. From your Steam library, right-click on Soulmask and select "Properties". Then go to "Installed Files" and press "Browse" to open the folder where the game is installed.

Within the game folder, navigate to WS\Plugins\DBAgent\ThirdParty\Binaries. In this folder, you should see CopyRoles and Readme. Click on the folder path at the top of the window to highlight it, then type cmd and press Enter. This should open a command prompt with the path set to this folder.

You will use this command prompt to run the CopyRoles tool in later steps. For now, leave the console window open but set it aside.

Note: The tool can also be found at the same relative location with the Windows dedicated server installation, but not in the Linux version of the server as of the time of writing this. Linux server operators will need to make use of the Windows tool and then copy the output file to their server.

Copy Local Saves

Copy player data between saves that are all local – either single player or hosted games that are not on a dedicated server.

NOTE: If you are starting a new save and want to copy an existing character, you can select the character to copy in-game during world creation and avoid needing to run this tool.

Locate save files

The CopyRoles tool will allow you to copy player data from one world.db file into another world.db file. The first thing you will want to do is locate your local saves.

Press Win+R on your keyboard to open the "Run" dialog.
Paste this into it: %LocalAppData%\WS
Press enter. It should open a folder with some additional folders inside of it. One of those folders will be a long number - your Steam ID. Open that folder.
Within that folder, open the folder named 2646460 (the Soulmask app id) and then the folder named AutoGames.

Within the AutoGames folder will be a separate folder for each of your local save games. I recommend that you back up everything in here to a separate location before you continue. Within each save will be a file named world.db. This is the save file for that world. You will need to know the locations of these when running the CopyRoles tool.

Select save files

Figure out which file you want to copy from and to. If you want to copy to a new save, make sure to create it first in game, load into it, then exit out (or even easier, just select the character to copy when creating the save and skip using the tool).

It can be difficult to tell which save files are which based on the names alone. You can look at the modified times of the files, or you can open the file named game.json within each folder to see the name of the save near the top like "NickName": "My World".

Run the tool

Once you have located the world.db files you want to copy player state data from and to, return to the console window we opened earlier to start entering the command. Start by typing this:

CopyRoles.exe -src=

Then, drag the file that will be the source of the copy into the console window. It will insert its path for you. Afterward, type a space and then:

 -dst=

Then, drag in the file that will be the destination for the copy. It will insert its path. Finally, type a space and this:

 -type=1

This tells it to replace player data in the destination with data from the source. The final command should look something like this, as an example.

CopyRoles.exe -src=C:\Users\name\AppData\Local\WS\76561198297047277\2646460\AutoGames\BAUPC9ZOGT6STZOGSLH8JFKSR\world.db -dst=C:\Users\name\AppData\Local\WS\76561198297047277\2646460\AutoGames\CDPNI4BF4024RRFCGZ5VS1WZN\world.db

Press Enter to run the command. It will print some information about the process, including the steam id of each player that gets copied. It will also create a backup of the unmodified destination file next to the modified one in case you need to roll back to it. Load into the game and load the save file to see if it worked.

Celestial Mask

As of the time this was written, if you copy player data from a Cloud Mist Forest save into a Shifting Sands save, you will find that the player has not been given a celestial mask as they normally would if starting fresh on this map. There is no way to obtain this mask in this case through normal gameplay. You will want to use the admin menu to spawn one in.

To access the admin menu after loading into the save, open the console by pressing the appropriate console key (usually either the grave key ` or minus on the number pad -). Enter the following command:

gm key 123456

Press enter to run the command, and the admin console should appear on screen. Search for the Celestial Wings mask in the item list and click on it to give yourself one. You will then need to take the mask to a mysterious stone table where you can equip it (either build the table through normal gameplay or spawn one using the same admin menu).

Copy Server Saves

Copying player data between server saves can be a bit tricky due to some apparent limitation in the server's ability to interpret the data. If you want to copy from a local save to a dedicated server, you should be able to use the method described in copy local saves above, using your server world.db as the output file. However, if you want to copy from one server save to another, follow the process below.

Switching maps on the same server

At the time of writing this, servers will not properly read player data that has been copied into their world.db using the CopyRoles tool if the source of the copy is also a server save. As a workaround, you can copy the data to an account.db and configure the server as a cluster main server (even if there will never be another server in the cluster). To switch the server to a cluster main server and cause it to use account.db for player data, add the following option to your server startup command line.

-mainserverport=20000

Note that you need to set a valid and available TCP port that the server can bind to. This port should not be open externally or port-forwarded. By doing this, the server will now use the following file for player state data: WS/Saved/Accounts/account.db

Now, run the tool to copy player data from world.db to account.db. If you are using a Windows server, the tool will be located at WS/Plugins/DBAgent/ThirdParty/Binaries within the server install directory. If you are using a Linux server, you will need to use the tool from either the Windows server or from the game client, which will be located at the same path relative to the game installation.

The tool interprets all paths as relative to itself, so if not specifying full paths, you probably want to cd into the tool's directory and run it from there. To copy from a Cloud Mist Forest world save, run the following command:

CopyRoles.exe -src=..\..\..\..\Saved\Worlds\Dedicated\Level01_Main\world.db -dst=..\..\..\..\Saved\Accounts\account.db type=1

Adjust the world.db path as necessary for your source save file. Running this will generate an account.db. Now you should be able to start your server on a different map and connect to it.

When migrating player data, the server must have the exact same name as it did before the migration, and cannot be changed in the future. If the name changes, players will not be able to log in and will be presented with a message saying their data is on a different server.

Copy between servers

As of the time of this writing, copying player data from server to another will not work. When a player attempts to log in, they will be told their character is on the original server and will not be allowed to log in to the new server.

Celestial Mask

As of the time this was written, if you copy player data from a Cloud Mist Forest save and then load directly into a Shifting Sands save, you will find that the player has not been given a celestial mask as they normally would if starting fresh on this map. There is no way to obtain this mask in this case through normal gameplay. You will want to use the admin menu to spawn one in.

gm key 123456

Copy to Server Cluster

If you want to create a server cluster, follow the server cluster guide. There is a section in that guide specifically explaining how to use CopyRoles to transfer player data to account.db. This method will allow players to receive a Celestial Wings mask when they first portal into Shifting Sands, avoiding the issue present in other copy methods.

Additional Options

The CopyRoles tool comes with a readme.txt file covering command line parameters and some example use cases. Refer to this file for up-to-date information. At the time of this writing, these are the available options:

-src=source.db [Required] The source file for the copy
-dst=destination.db [Required] The destination file for the copy
-type=value [Optional] How to resolve conflicts if the same player exists in both src and dst. Values:
- 0 - (default) keep whichever player state was most recently modified
- 1 - overwrite the destination player state with the source
- 2 - keep the destination player data
-userid=steamid [Optional] Specify a single player by Steam ID to copy. If omitted, will attempt to copy all palyers.