# How to Use the Soulmask CopyRoles Tool (/docs/soulmask/copyroles-tool)



import { File, Folder, Files } from 'fumadocs-ui/components/files';
import { Step, Steps } from 'fumadocs-ui/components/steps';

`CopyRoles.exe` is a utility that ships with the Soulmask dedicated server (Windows only). It copies the **player state** — initial character, awareness level, and tech unlocks — between save databases. Use it for save migration, switching from a single-player save to a dedicated server, or onboarding existing players into a [cluster](/docs/soulmask/cluster-setup).

> ⚠️ **Windows only.** The Linux dedicated server distribution does not include `CopyRoles.exe`. If you host on Linux, run the tool on a Windows machine against a copy of your `world.db` / `account.db`, then upload the result back.

> ⚠️ **What it does NOT copy:** inventory, tribesmen, buildings, or anything stored in the world data. Use [building transfer](/docs/soulmask/building-transfer) for buildings.

***

Tool Location [#tool-location]

<Files>
  <Folder name="WS" defaultOpen>
    <Folder name="Plugins">
      <Folder name="DBAgent">
        <Folder name="ThirdParty">
          <Folder name="Binaries" defaultOpen>
            <File name="CopyRoles.exe" />

            <File name="Readme.txt" />
          </Folder>
        </Folder>
      </Folder>
    </Folder>
  </Folder>
</Files>

***

Command Syntax [#command-syntax]

```
CopyRoles.exe -src=<source.db> -dst=<destination.db> -type=<0|1|2> [-userid=<steamid>]
```

| Flag       | Required | Description                                                                                                                                                     |
| ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-src=`    | Yes      | Source database file.                                                                                                                                           |
| `-dst=`    | Yes      | Destination database file. **A backup is automatically saved next to this file before modification.**                                                           |
| `-type=`   | No       | Conflict resolution. **`0`** (default) = keep the most recently modified player state. **`1`** = overwrite destination with source. **`2`** = keep destination. |
| `-userid=` | No       | Limit the copy to a single player by Steam ID. Omit to copy all players.                                                                                        |

The tool prints the Steam ID of every player it copies.

***

Common Use Cases [#common-use-cases]

<div className="fd-steps">
  <div className="fd-step">
    Onboard standalone server players into a cluster [#1-onboard-standalone-server-players-into-a-cluster]

    This is the cluster onboarding path — copies player state from a standalone server's `world.db` into the cluster main's shared `account.db`.

    <Steps>
      <Step>
        **Stop both the standalone server and the cluster main server.**
      </Step>

      <Step>
        Back up `account.db` and `world.db` to a safe location.
      </Step>

      <Step>
        Open Command Prompt and `cd` to `WS\Plugins\DBAgent\ThirdParty\Binaries` on the cluster main server.
      </Step>

      <Step>
        Run:

        ```
        CopyRoles.exe -src=..\..\..\..\Saved\Worlds\Dedicated\Level01_Main\world.db -dst=..\..\..\..\Saved\Accounts\account.db -type=1
        ```
      </Step>

      <Step>
        Start the cluster main server, then the client servers.
      </Step>
    </Steps>

    > The map name on the cluster node **must match** the map name from the standalone server, or characters won't be found. If the standalone ran `Level01_Main`, the cluster node also must run `Level01_Main`.
  </div>

  <div className="fd-step">
    Migrate a local single-player save to a dedicated server [#2-migrate-a-local-single-player-save-to-a-dedicated-server]

    <Steps>
      <Step>
        Stop the dedicated server. Locate the destination `world.db` at `WS/Saved/Worlds/Dedicated/Level01_Main/world.db`.
      </Step>

      <Step>
        Locate your local save's `world.db`. Default path on Windows:

        ```
        C:\Users\<name>\AppData\Local\WS\<steamid>\2646460\AutoGames\<save_id>\world.db
        ```
      </Step>

      <Step>
        Run:

        ```
        CopyRoles.exe -src=C:\path\to\local\world.db -dst=C:\path\to\server\world.db -type=1
        ```
      </Step>

      <Step>
        Start the dedicated server.
      </Step>
    </Steps>
  </div>

  <div className="fd-step">
    Copy a single player between worlds [#3-copy-a-single-player-between-worlds]

    ```
    CopyRoles.exe -src=source.db -dst=dest.db -type=1 -userid=76561198000000000
    ```

    Useful for transferring one player's progression without overwriting everyone else.

    ***
  </div>
</div>

Prerequisites [#prerequisites]

* Both source and destination saves must exist — create the destination world in-game once before running the tool
* Stop the server (or close the local save) before copying — the database is locked while the game is running
* Always back up the destination file separately even though the tool creates its own backup
* Server name and map name should remain unchanged across the migration

***

Known Limitations [#known-limitations]

* **No live server-to-server copying** — players will be told their character is on the original server if you try to copy between two running clusters
* **Celestial Wings mask issue** — known issue when copying player state into the Shifting Sands DLC map
* **Only player state copies** — for buildings, use the [building transfer commands](/docs/soulmask/building-transfer); for inventories and tribesmen, those stay with the world the player left

***

Troubleshooting [#troubleshooting]

**Players asked to create a new character after the copy**

* The destination's `account.db` may have double-compressed actor data from a version mismatch. Run the [save fix tool](/docs/soulmask/save-fix).

**"Database is locked" or copy fails**

* Server is still running — stop it from the panel and wait for the shutdown to complete before retrying.

**Copy succeeds but player has no character**

* Check that the source actually contains that player's data (use `-userid` with a known Steam ID and watch the printed output)
* Confirm the destination world map name matches the source

***

Related Guides [#related-guides]

* [Cluster Setup](/docs/soulmask/cluster-setup)
* [Save Fix Tool](/docs/soulmask/save-fix)
* [Building Transfer](/docs/soulmask/building-transfer)
* [Backup System](/docs/soulmask/backup-system)
* [Upload Save](/docs/soulmask/import-save)