ConditionalConfigSync

Conditional Config Sync

> **Conditional Conditional Config Sync — embed the optional CCS adapter directly into your mod project (as a source file or via ILRepack) and automatically add config synchronization when CCS 1.0.10 or newer** is installed in the current modpack; without CCS, or with CCS 1.0.5-1.0.9, the same settings remain ordinary local BepInEx config entries.

Conditional Config Sync is a shared infrastructure library for Valheim mods. It does not add gameplay content, items, UI, or configuration options of its own. Install it when another mod lists it as a dependency.

The package provides centralized config synchronization, version checks, server-side ownership and admission policy overrides, protected locking, and synchronized runtime values. Keeping this logic in one standalone dependency means fixes can be shipped by updating this package instead of rebuilding every mod that uses it.

It is an independent synchronization option for mod authors who need per-setting ownership policy, hidden-setting controls, and expanded runtime-value behavior. Jotunn and ServerSync remain separate libraries with their own use cases and development paths.

For players

Normally, a mod manager installs Conditional Config Sync automatically as a dependency. Keep it installed while any enabled mod depends on it.

This package:

• does not replace, modify, or intercept ServerSync used by other mods;
• does not migrate or modify configuration belonging to other mods;
• can run alongside Jotunn and mods that use ServerSync;
• only handles mods that were explicitly built against Conditional Config Sync.

Installing this package alone has no gameplay effect.

Package contents

The Thunderstore package contains:

• ConditionalConfigSync.Plugin.dll - the BepInEx bootstrap registered as _shudnal.ConditionalConfigSync;
• ConditionalConfigSync.dll - the public API and synchronization runtime used by dependent mods;
• ConditionalConfigSync.xml - IntelliSense documentation for IDEs and mod authors;

Both DLL files must remain installed together. The XML and documentation files are optional at runtime but useful for development, verification, and redistribution.

Compatibility

Conditional Config Sync uses its own BepInEx and Harmony identifier:

_shudnal.ConditionalConfigSync

It does not patch, replace, or disable Jotunn synchronization or ServerSync. These libraries can coexist in the same process because each mod continues using the synchronization library it was compiled against.

Embedding or ILRepacking ConditionalConfigSync.dll into another mod is intentionally unsupported. An embedded copy rejects initialization and reports an explicit error. Use the standalone Thunderstore dependency instead.

For server administrators

Default behavior

Every registered setting has one of three ownership modes selected by its mod author:

• AlwaysServerControlled - always synchronized from the server and cannot be released by policy. Mod authors should use it for shared mechanics and synchronized state that must use the same effective value on the server and every client. Typical examples are gameplay rules, world-state generation, shared events, network-visible calculations, and feature switches that would malfunction when peers disagree;
• Conditional - uses the mod-defined server/client default and may be overridden by server policy. It is appropriate when an administrator may reasonably choose between one shared server value and per-client behavior;
• AlwaysClientControlled - always local to each client and cannot be forced by sync policy. It is intended for presentation, local UI, controls, and other behavior that does not participate in shared mechanics.

A mod may also register one locking setting that controls whether ordinary clients may publish changes to server-controlled settings. Hidden-state policy is independent and may hide settings from compatible configuration managers in any ownership mode. A mod author may additionally opt its remote-installation requirement into ModRequirementMode.Conditional, allowing the server to require or permit clients without that specific mod while retaining the author's declared default.

Policy files are created in BepInEx/config/shudnal.ConditionalConfigSync on the server. Existing files are read synchronously during server startup before the file watchers are used. Reads are retried until the file metadata is stable, so common editor save patterns such as truncate/write/rename do not replace a working policy with a partial snapshot. The files are then watched for changes and can be edited while the server is running.

Locking behavior

Conditional Config Sync provides a locking model familiar to ServerSync users and adds explicit protection for the locking setting itself.

When the lock is enabled:

• ordinary clients cannot publish changes to server-controlled settings;
• server administrators receive an exemption and may edit them;
• client-controlled settings remain local and editable.

When the lock is disabled, ordinary clients may publish changes to server-controlled settings only if the mod author explicitly enabled unlocked-client updates. This option is disabled by default; administrators remain authorized regardless of the option.

The locking setting is always protected:

• it is always server-controlled;
• it cannot be forced to client-controlled through policy;
• a non-admin client cannot change it even while the rest of the configuration is unlocked.

This prevents a client from attempting to grant itself permission by changing the lock setting first.