ConditionalConfigSync
Registers and synchronizes BepInEx config entries and runtime custom values for one mod.
Create one instance per mod, normally with the mod GUID as . The standalone
ConditionalConfigSync BepInEx plugin must be installed and declared as a hard dependency.
[BepInDependency("_shudnal.ConditionalConfigSync", BepInDependency.DependencyFlags.HardDependency)]
public sealed class Plugin : BaseUnityPlugin
{
private static readonly ConditionalConfigSync sync = new("author.mod")
{
DisplayName = "My Mod",
CurrentVersion = "1.2.0",
MinimumRequiredVersion = "1.2.0"
};
}
Indicates that at least one incoming synchronization package is currently being applied.
This remains public for compatibility and diagnostics. Consumers should not build their own ServerSync-style
queues around it; ConditionalConfigSync already defers outgoing changes safely while processing or sending.
Domain-specific gates, such as waiting for texture-cache generation, may still be appropriate.
Stable synchronization identifier, normally the owning mod's BepInEx GUID.
It is used in RPC names and policy keys, so it must be unique and must not change between releases.
Human-readable mod name used in logs. Falls back to when omitted.
Current version of the owning mod, for example 1.4.2.
Oldest remote version accepted by this mod instance.
Set it independently from when compatible mod releases span several versions.
Gets or sets whether the owning mod must be installed and compatible on the remote peer.
Set this to for mods that require matching code on both sides of the connection.
On a client, the connected server must have a compatible copy of the mod. On a server, every connecting
client must have a compatible copy. Missing or incompatible copies reject the connection during the normal
peer version handshake.
Leave this only when the mod can operate correctly while absent from the remote side,
such as a genuinely client-only or otherwise optional integration. The local BepInEx hard dependency on
Conditional Config Sync is separate: it requires CCS on the same machine as the owning mod, not automatically
on the remote server or client. After successful client admission without a matching server handshake, the
optional instance returns to local source-of-truth ownership; this does not count as a completed server sync.
Set this before a connection is established, preferably in the object initializer.
Allows an unlocked non-admin client to send config and custom-value changes to the server.
The default is so server-controlled values remain server-originated unless a mod
explicitly opts into collaborative unlocked-client updates. Administrator clients are not affected by this option.
Gets the effective locking-setting state for the local process after applying the local admin exemption.
The getter combines the locking config entry, an optional programmatic override, and the local admin exemption.
Assigning this property sets a programmatic override for the current process. A value of
does not by itself grant ordinary clients write access; must also
be enabled by the mod.
Gets whether the local side is the source of truth or has received an admin exemption from the server.
Gets whether the local side currently owns and publishes synchronized values.
This is normally true on the server and in local worlds, and false on a connected client.
Gets whether the initial server synchronization has completed for this instance.
Raised when this process changes between source-of-truth and client-replica roles.
The argument is when the local side becomes the source of truth.
Raised once when the first complete server synchronization package has been applied successfully.
Use this on clients when runtime systems must wait until all initial server-controlled config and custom values
are available. It is not raised for later partial updates. A new server connection can raise it again after
.
Raised after a server connection ends and server-owned values have been replaced with their saved local values.
Use this to discard caches derived from server settings or rebuild client-local state after disconnecting,
returning to the menu, or shutting down the current network session.
Raised when either the effective server-controlled state or hidden state changes for one config entry.
This is the combined policy event. It is useful for tools that need one notification for any policy transition.
More focused consumers may subscribe to or .
Raised when a config entry becomes server-controlled or client-controlled.
The first argument is the entry and the second is its new state. Use it when runtime behavior must switch
between the received server value and the client's retained local fallback.
Raised when a config entry becomes hidden or visible through effective server policy.
The first argument is the entry and the second is its new hidden state. This can be used by custom config UIs
that do not rely on Configuration Manager's Browsable metadata.
Raised when the effective configuration lock is first evaluated and whenever it changes for this synchronization instance.
The argument is the new effective lock state after applying admin exemption and any programmatic override.
The initial evaluation may therefore raise the event with . Use it to refresh custom
configuration UIs or explain why a client can no longer publish changes.
Raised when an incoming package or outgoing synchronization operation is rejected deliberately.
Useful for diagnostics and telemetry implemented by the owning mod. The library itself performs no external
telemetry. The event is raised on the thread that detects the rejection; marshal to Unity's main thread before
touching Unity objects. Do not retry blindly because permission and size rejections are persistent.
Creates a synchronization instance for one mod.
Stable unique identifier, normally the mod's BepInEx GUID.
Thrown when the standalone ConditionalConfigSync plugin is not initialized or when an embedded copy is used.
Registers a config as policy-controlled and server-controlled by default.
The config value type.
The entry returned by Config.Bind.
The existing or newly created typed synchronization wrapper.
Equivalent to AddConfigEntry(configEntry, ConfigSyncMode.Conditional, true).
Registers a policy-controlled config with an explicit default ownership.
The entry returned by Config.Bind.
for server-controlled by default; otherwise client-controlled.
Registers a config with an explicit synchronization mode.
The entry returned by Config.Bind.
Whether ownership is fixed or may be overridden by policy.
is server-controlled by default in this overload. Choose
for shared mechanics that require the same effective value
on the server and every client.
Registers a config with a complete synchronization-mode definition.
The entry returned by Config.Bind.
Whether ownership is fixed or may be overridden by policy.
Default ownership used only for .
This overload configures the wrapper before registration, avoiding the temporary default state caused by assigning
after AddConfigEntry returns.
Binds and registers a Conditional config in one call using a text description and explicit default ownership.
Binds and registers a config entry in one call using a text description.
Binds and registers a Conditional config in one call using a full BepInEx description and explicit default ownership.
Binds and registers a config entry in one call using a full BepInEx description.
Binds and registers a Conditional config in one call using a , text description, and explicit default ownership.
Binds and registers a config entry in one call using a and text description.
Binds and registers a Conditional config in one call using a and explicit default ownership.
Binds and registers a config entry in one call using a .
Registers the single protected config entry that controls whether clients may edit synchronized settings.
A convertible value type, commonly or an integer.
The BepInEx entry used as the lock switch. Zero/false means unlocked.
The synchronization wrapper for the locking entry.
Thrown when a second locking entry is registered for the same instance.
The locking entry is always server-controlled. A ForceClientControlled policy override is ignored,
and the server rejects attempts by non-admin clients to change this entry even while the rest of the
configuration is unlocked. This prevents a client from granting itself permission to edit server settings.
var lockEntry = Config.Bind("General", "Lock Configuration", true, "Server controls settings");
configSync.AddLockingConfigEntry(lockEntry);
Returns the synchronization wrapper attached to a registered BepInEx config entry.
The config value type.
The BepInEx config entry to inspect.
The wrapper, or when the entry was not registered.
Controls the amount of diagnostic information written by ConditionalConfigSync.
Lifecycle, registration, initial sync, and important queue activity.
Adds package preparation, compression, policy application, and value-flow details.
Adds per-value and per-fragment tracing. Intended for short diagnostic sessions.
Enables runtime debug logging programmatically for the shared standalone plugin.
Selects the runtime debug verbosity used when is enabled.
Optional case-insensitive filter matched against a synchronization name or display name. Empty means all mods.
Requests a complete synchronization package from the currently connected server.
when the request was dispatched; otherwise when no remote server
is connected.
ConditionalConfigSync invokes this automatically when a config or custom value is registered after the initial
client synchronization. Mods may also call it after rebuilding a dynamic registration set. The request is ignored
on the server and in local worlds. Resynchronization does not repeat the completed peer admission or mod version
check, so mods that require connection rejection must create their ConfigSync before connecting.
Releases process-wide watchers, Harmony patches, queued work, and network-session state.
Called by the standalone BepInEx bootstrap during plugin destruction. Dependent mods normally never call this.
Compatibility name for code originally written against ServerSync's ConfigSync class.
It has the same behavior as . New code may use either name; keeping this alias
allows existing declarations to migrate by changing only the namespace import.
Creates a compatibility synchronization instance for one mod.
Stable unique identifier, normally the mod's BepInEx GUID.
Defines how ownership and synchronization of a registered configuration entry are determined.
Choose a fixed mode when a setting must always belong to the server or the local client. Use
only when server policy may safely change the effective owner at runtime.
The server always owns and synchronizes this setting. SyncPolicy entries are ignored.
Use this mode for settings that control shared mod mechanics or synchronized state whose behavior must remain
consistent on the server and every client. Examples include gameplay rules, world-state generation, shared event
behavior, network-visible calculations, and feature switches that would malfunction when peers disagree.
SyncPolicy may override the mod-defined default ownership.
Each client always owns this setting. SyncPolicy entries are ignored.
Describes an effective ownership override applied to a setting.
This value reports only overrides that change the mod-defined default ownership. A matching policy rule that keeps
the same ownership is represented by because it has no effect on runtime behavior.
The effective ownership matches the mod-defined default.
The setting is server-controlled despite being client-controlled by default.
The setting is client-controlled despite being server-controlled by default.
Describes whether and why the current process can change a Conditional setting's server ownership policy.
The setting has a fixed ownership mode and cannot be changed by server policy.
The current process may request or apply a policy change.
A compatible active server session is required before policy can be changed.
The server session is active, but the current player lacks administrator access.
Non-generic base for runtime values synchronized independently from BepInEx config files.
Use for state and for event-like
messages where repeated equal assignments must be preserved.
Raised after the active value is applied or explicitly re-notified.
ConditionalConfigSync also listens to this event to publish changes. Avoid assigning the same value recursively
from the handler. Use after mutating a reference-type value in place.
Compatibility alias for . Re-publishes and re-processes the current active value.
Explicitly notifies subscribers that the current value must be processed again.
This is useful after mutating an object in place, because assigning the same object reference can be suppressed
by the equality comparer. Call it only from a side that is allowed to publish the current value.
syncedList.Value.Add(newItem);
syncedList.NotifyChanged();
The local fallback retained by a client while a server value is active.
Prefer the typed assignment methods instead of modifying this field directly.
Unique identifier of this custom value within its owning synchronization instance.
Runtime type used for package serialization and validation.
Gets or sets the active value through the non-generic API.
Prefer Value and the typed AssignLocalValue... methods. Direct assignment here does not provide
the local-fallback semantics that a connected client usually needs. Equal assignments are suppressed for a
normal custom value and preserved for a sequenced custom value.
Assigns a boxed active value and reports whether an event was raised.
The candidate active value.
When true, notify even if the configured comparer reports equality.
True when the value was accepted and was raised.
Intended for custom derived value types. Most mods should use the typed public assignment methods.
True when the local side currently owns and may publish this value.
Ordering priority used when several custom values are batched or flushed together. Higher values come first.
Values with the same priority keep their registration order. Priorities are useful when one value must be
processed before another, for example loading environment definitions before selecting the current environment.
They do not turn a state value into an event queue; use for that.
Initializes a custom synchronized value base.
The synchronization instance that owns the value.
Unique stable identifier within the synchronization instance.
Runtime serialization type.
Batch ordering priority. Higher values come first.
Synchronizes a runtime state value and suppresses assignments considered equal by its comparer.
The synchronized value type.
Use this type for current state such as JSON text, selected modes, generated settings, or cached metadata. If the
same state is assigned again, subscribers and the network are not notified unless an explicit notify method is used.
Handlers attached after construction do not receive the constructor's initial assignment. After subscribing, use
when derived runtime data must be built at least once.
Custom values use Valheim package serialization. Complex domain types can implement ISerializableParameter
when the built-in primitive, enum, collection, and value-type paths are not sufficient.
var mapData = new CustomSyncedValue<string>(configSync, "Map data", "");
mapData.ValueChanged += () => ApplyMapData(mapData.Value);
mapData.AssignLocalValueIfChanged(ReadMapData());
Gets or sets the currently active synchronized value.
For a normal custom value, assigning an equal value is ignored. Prefer the AssignLocalValue... methods
when code can run on a connected client, because they preserve the client's local fallback.
Creates a state-like custom synchronized value.
The synchronization instance that owns this value.
A unique stable name within .
Initial local value.
Batch ordering priority. Higher values are processed before lower values.
Optional equality comparer. It controls duplicate suppression for local assignments and received values. Supply a
content comparer for arrays, lists, dictionaries, or domain objects when reference equality is not sufficient.
var settings = new CustomSyncedValue<Dictionary<int, string>>(
configSync, "Season settings", new Dictionary<int, string>(),
priority: 100, valueComparer: DictionaryContentComparer.Instance);
Assigns the local value using the default semantics of this custom-value type.
The new local value.
For , equal values are suppressed. For
, every assignment is preserved, including repeated equal values.
On a client that is not the source of truth, this changes only the local fallback and does not notify handlers.
Assigns the local value only when the configured comparer reports a real change.
The candidate local value.
This method suppresses equal values for both normal and sequenced custom values. Use it for polling, file
watchers, or repeated recalculation where only changed state should trigger handlers and network traffic.
settingsJson.AssignLocalValueIfChanged(File.ReadAllText(path));
Assigns the local value and forces one notification even when the value compares equal.
The value to assign and process.
Use this for initial processing, explicit reload commands, or rebuilding derived data when handlers must run at
least once. On a client that is not the source of truth, only the local fallback is updated; the active server
value is not re-notified.
// Initial load must build runtime objects even if the text equals the default value.
settingsJson.AssignLocalValueAndNotify(ReadSettings());
// Later reloads should run only after a real change.
settingsJson.AssignLocalValueIfChanged(ReadSettings());
Synchronizes an event-like sequence where every assignment must be delivered in order, including equal values.
The event payload type.
A normal represents the latest state and may coalesce pending updates. A sequenced
value snapshots every deferred assignment into its own package. Use it for commands, pulses, combat events, or any
message where A, A means two events rather than one state. Do not use it merely to force initial processing;
use for that.
var playEffect = new SequencedCustomSyncedValue<int>(configSync, "Play effect");
playEffect.ValueChanged += () => SpawnEffect(playEffect.Value);
playEffect.AssignLocalValue(7);
playEffect.AssignLocalValue(7); // delivered as a second event
// This explicit method still suppresses a duplicate when that is desired.
playEffect.AssignLocalValueIfChanged(7);
Creates an event-like custom synchronized value that preserves every assignment.
The synchronization instance that owns this value.
A unique stable name within .
Initial local payload value.
Batch ordering priority. Higher values are processed before lower values.
Optional comparer used only by explicit change-checking operations such as
. Normal sequenced assignment does not suppress equality.
Cached reflection bridge for Valheim runtime APIs. The development references may be publicized,
while the actual game assembly can keep the same members non-public. All game member invocation
is centralized here so CLR accessibility changes do not surface as MethodAccessException in callers.
Forces eager validation of all cached Valheim reflection bindings.
Shared package metadata used by the BepInEx bootstrap, both assemblies, and the publishing pipeline.
Change here when preparing a new release.
BepInEx plugin identifier and Harmony owner ID.
Human-readable plugin name shown by BepInEx and package managers.
Canonical source repository and release page.
Package and assembly version. Update this single value for a new release.
The Thunderstore manifest reads the compiled plugin assembly version during packaging.
Current ConditionalConfigSync wire protocol version.
Increase this value only when the network format becomes incompatible.
Shared package metadata used by the BepInEx bootstrap, both assemblies, and the publishing pipeline.
Change here when preparing a new release.
BepInEx plugin identifier and Harmony owner ID.
Human-readable plugin name shown by BepInEx and package managers.
Canonical source repository and release page.
Package and assembly version. Update this single value for a new release.
The Thunderstore manifest reads the compiled plugin assembly version during packaging.
Current ConditionalConfigSync wire protocol version.
Increase this value only when the network format becomes incompatible.
Common metadata attached to every BepInEx config entry registered with ConditionalConfigSync.
Most mods use the typed returned by
instead of working with this base class directly.
The client's original local value while a server-controlled value is active.
This field is public for compatibility with ServerSync integrations. New code should normally use
AssignLocalValue on the typed wrapper instead of modifying this field directly.
Gets whether this setting is currently controlled and synchronized by the server.
For settings this value reflects the effective server policy after it
has been initialized. Before that point it returns the normalized mod-defined default, including compatibility
code that assigns after registration.
Gets whether effective server policy currently hides this setting from compatible config UIs.
Gets whether the effective policy state has been initialized for the current server session.
This is normally true on a running server after policy loading and on a connected client after receiving config
state from the server. It returns to false when the server connection is reset and local defaults are restored.
Gets the underlying BepInEx config entry.
Defines how policy is allowed to control this setting. The default is .
Prefer passing the mode directly to an AddConfigEntry overload so the wrapper is fully configured before
registration. This public field remains available for source compatibility with existing integration helpers.
Defines the default ownership used when is .
means server-controlled by default; means client-controlled by
default. Prefer the AddConfigEntry overloads instead of assigning this field after registration.
Gets the normalized ownership defined by the mod before server policy is applied.
Fixed modes always return their fixed ownership. Conditional mode returns .
Gets whether effective policy changes the ownership defined by the mod.
Only settings can be overridden. A policy rule that resolves to the same
ownership as the mod default is not reported as an override because it does not change runtime behavior.
Gets the effective policy override that changes this setting's ownership.
Gets the current availability state for changing this setting's server policy.
The state distinguishes fixed settings, unavailable server sessions, missing administrator access, and an
available policy control operation.
Gets whether the current process may change this Conditional setting's server policy.
This is a convenience projection of . It returns
only when the state is .
Requests the opposite effective ownership policy for this Conditional setting.
when the change was applied locally or dispatched to the server.
The server persists the resulting exact-setting rule in ConditionalConfigSync.SyncPolicy.cfg. When the
requested ownership is already provided by the mod default or a section rule, an unnecessary exact rule is removed.
Typed synchronization wrapper for a regular BepInEx .
The config value type.
The wrapper keeps the client's local value separate while a server value is active. When the client disconnects,
or when policy changes the entry back to client-controlled, the local value is restored.
Creates a synchronization wrapper for the supplied BepInEx config entry.
The BepInEx config entry being registered.
The original typed BepInEx config entry.
Gets or sets the currently active value of the underlying config entry.
On a connected client this may be the server value rather than the value stored in the client's cfg file.
Use when changing the client's own fallback value.
Assigns the value owned by the local side without overwriting an active server value on a client.
The new local value.
On the server or in a local world this updates the active config entry. On a connected client controlled by
the server it updates only the saved local fallback, which is restored later. BepInEx itself suppresses
SettingChanged when the typed value is equal.
Describes one effective policy-state transition for a registered config entry.
This event data is raised on the Unity main thread. It is useful when a mod must rebuild runtime state after an
administrator changes SyncPolicy or HiddenConfigs while the server is running, or when a client receives a new
effective state from the server.
The config entry whose effective policy state changed.
The previous effective server-controlled state.
The new effective server-controlled state.
The previous effective hidden state.
The new effective hidden state.
Human-readable origin such as a policy reload or an incoming server package.
Describes a synchronization operation that was deliberately rejected before it could be applied or sent.
Typical reasons include permission checks, malformed fragments, queue overflow, payloads larger than the configured
safety limit, or a package-level exception. This event is diagnostic; handlers should not retry automatically
without understanding the reason, because doing so can create a retry loop.
Human-readable rejection reason suitable for logs and diagnostics.
Remote sender UID for an incoming package, or for a local outgoing rejection.
for an incoming package; for a local outgoing operation.
The originating exception when rejection followed an exception, otherwise .
Performs peer version compatibility checks for a mod.
A instance creates and maintains its own version check automatically. Construct
this class directly only for a mod that needs version validation without registering synchronized values.
Stable mod identifier used by the version-check RPC.
Human-readable mod name used in connection errors and logs.
Current local mod version.
Oldest compatible version accepted from the remote peer.
Gets or sets whether the checked mod must be installed and compatible on the remote peer.
When enabled on a client, the server must have a compatible copy of the mod. When enabled on a server, every
connecting client must have a compatible copy. A standalone defaults to
. A version check created for mirrors that instance's
value. Configure it before the connection handshake.
Protocol version reported by the connected server. Zero means that the version handshake has not completed or
that the server did not provide protocol metadata.
Whether protocol metadata has already been received from the connected server.
Creates a standalone version check not backed by a synchronization instance.
Stable unique mod identifier.
Creates a version check backed by a instance.
The synchronization instance whose version fields should be used.
Clears received peer-version state and refreshes fields from the backing synchronization instance.
ConditionalConfigSync calls this as part of its connection lifecycle; most mods do not call it directly.