CharactersVault

CharactersVault makes the server the authoritative source for player characters in Valheim. It locks each platform ID to one character and synchronizes that character between the server and the client.

WARNING: Joining a CharactersVault server with an existing character WILL wipe that character.

Use a new character when joining a CharactersVault server for the first time. Back up any character you care about before connecting.

What Players Need to Know

• CharactersVault must be installed on the dedicated server and on every connecting client.
• On a first join, the server creates a blank character. Inventory, skills, recipes, food, trophies, and other progression are cleared. Appearance details such as hair and clothing are preserved.
• On later joins, the server replaces the local character file with the server's saved copy. Any items, skills, or other progress made offline are discarded.
• Each platform ID is locked to the first character it registers. Joining with a different character is rejected.
• The client sends character updates to the server after relevant actions, such as picking up or discarding items and gaining or losing skills. It also performs a general profile sync automatically, normally every five minutes.

Installation

1. Install BepInEx on the dedicated server and on every client.
2. Install CharactersVault.dll in BepInEx/plugins/CharactersVault/ on both the server and clients.
3. Start the server and connect with a new character.

Clients without CharactersVault, or clients running a different version, are disconnected.

PC Xbox Game Pass users should also be supported when connecting through Valheim crossplay, but this has not been tested with CharactersVault. They must still be able to install and run BepInEx and CharactersVault on the client.

Server Data

CharactersVault stores its data on the server in:

BepInEx/config/CharacterVault/
|-- bindings.json                 Platform ID to character name bindings
`-- snapshots/
    `-- Steam_76561198XXXXXXXXX.json
                                  Saved character data for each player

The configuration file is:

BepInEx/config/CharacterVault.cfg

Admin Commands

These commands require the admin to be listed in the server's adminlist.txt.

Configuration

Changes take effect on the next player join.

Upgrading from CharacterVault

Install CharactersVault.dll on the server and every client, then remove the old CharacterVault.dll. Do not install both files at the same time. Existing CharacterVault.cfg settings and BepInEx/config/CharacterVault/ data are preserved.

Limitations

• CharactersVault is designed for dedicated servers. The host player in a peer-to-peer game does not go through the normal server join flow.
• Profile synchronization is not atomic. If the server stops while a save is being received, the next join may use the last successfully stored snapshot.
• The server stores character data in the Valheim profile format. Back up the snapshots directory before major Valheim updates.

v2.6.0

• Unified Player Reset Action: Streamlined unbinding and progression wipes into a single Reset Player action (/cv reset [playerId]) that safely wipes server-side progression, deletes old snapshots, and removes the character lock.
• Smoother Syncing & Performance: Fast actions (like sorting items in chests or rapid skilling) are now bundled intelligently, greatly reducing network lag and server load without risking any lost progress.
• Admin Commands Prefix: Updated admin commands to /cv (with /vault alias).

Bug Fixes

• Chat Formatting Fix: Fixed an issue where raw color tags were displayed in chat when running admin commands.
• Character Reset & Unbind Fix: Fixed an issue where unbinding a character would allow old inventory, skills, and appearance to carry over when the player rejoined with a new character.

v2.4.0

• Character Selection Warning: Added a reminder banner on the Character Selection screen to prevent accidental loss of existing character progression (can be toggled in config).
• Clear Disconnect Messages: If a connection fails or is rejected (such as a mod version mismatch), the exact reason is now displayed directly on the disconnect screen.

v2.3.4

• Resolved Thunderstore packaging and automated scanner compatibility issues.
• Excluded bundled Newtonsoft.Json.dll dependency from package output.
• General packaging and internal cleanup.

v2.3.1

• Platform ID Support: Added support for platform IDs (Steam_... and Xbox_...) for player bindings and snapshot files.
• Sync Reliability: Added transfer size limits, chunk validation, and timeout handling for safer profile syncs.
• Data Safety: Atomic file saves for bindings and snapshots to prevent corruption if the server crashes.
• Cleanup: Removed obsolete config options, unused mismatch reports, and legacy code.