Runic World Engine 1.2.2

A Valheim world is constantly synchronizing objects, changing state, communicating with peers, and saving to disk. When those systems collide with an expensive frame or overlapping save work, everyone can feel the hitch even though nobody did anything wrong.

Runic World Engine watches that infrastructure, offers a coordinated player-cap override, and smooths asynchronous saves. See which connections are struggling, spot growing queues, and receive early warnings without changing world ownership or synchronization behavior.

Version 1.2.2 is verified with Valheim 1.0.15 and requires BepInExPack Valheim 5.4.2350, including support for the chunked-world save and load pipeline.

Major features

• Observe aggregate ZDO population, peer counts, traffic, and lifecycle rates.
• Optionally configure a 2–64 player cap with coordinated admission, Steam, and PlayFab limits.
• View each connected peer's RTT, send/receive rate, queued traffic, and heartbeat age.
• Observe ownership assignments, releases, transfers, and rapid repeated transfers.
• Identify possible synchronization starvation and sustained unhealthy server conditions.
• Measure save and load call duration without scanning world contents.
• Coalesce overlapping asynchronous periodic save requests.
• Briefly defer save preparation after an already-expensive frame.
• Offer optional, rate-limited diagnostic summaries.

How it feels in-game

There is no new gameplay interface demanding attention. The world continues to save normally, but avoidable overlapping work and poorly timed preparation are reduced so persistence announces itself less dramatically.

Quick setup

Install on the dedicated server or the player hosting the world for server-wide monitoring and the player-cap override. Connecting clients do not need World Engine for those features. An optional client installation reports that client's local connection only; it does not fetch the server's telemetry.

Start once to generate BepInEx/config/chazman.RunicWorldEngine.cfg. To host up to 20 players, configure the host and restart it:

[Player Capacity]
Enabled = true
MaximumPlayers = 20

The override is off by default. The configured cap is frozen at startup. A dedicated PlayFab host gets a separate reserved transport slot; that slot does not reduce the human player cap. Raising the cap does not add CPU or bandwidth capacity.

In the local F5 console, enter runicworld_status for the most recent read-only report. No devcommands or administrator grant is needed to inspect your own process. On a headless server, enable log summaries instead:

[Diagnostics]
LogPeriodicSummary = true
SummaryIntervalSeconds = 30
LogPeerDetails = true

Read the server's BepInEx log for its complete report. Peer details include player names and peer IDs, but no IP addresses, passwords, or authentication tokens. Warnings are enabled by default even when periodic summaries are off.

Player-cap validation

World Engine audits the Valheim 1.0.12 / 1.0.14 method bodies and every identified literal hosting-limit site before installing the override: five sites on a listen host, six on a dedicated server. The dedicated set includes Steam's initial maximum-player setting. It preserves the old remote-server browser fallback rather than changing the displayed capacity of other servers.

The override requires the complete audited set. Unknown method bodies, missing sites, additional detected limit sites, or competing transpilers reject the override and block hosting until corrected and restarted. Integrity is checked again before hosting and admission. If the patch set changes afterward, new admissions are blocked and a restart-required error is logged; existing players are not kicked and the cap is not silently reduced. A rejected connection may receive Valheim's server-full message; the host log gives the actual integrity error.

This validates the audited game-side limit patches, not arbitrary behavior added by other plugins or external platform-service limits. Authentication and character-vault checks remain in effect. Do not combine this override with another player-limit mod. A new game version alone does not disable the override. If the audited capacity method bodies change, the override requires a fresh code audit before it can run.

Reading health reports

• RTT: Steam's native ping or PlayFab Party's per-endpoint round-trip latency. n/a means unavailable or not yet measured, not zero.
• Send/receive: bytes per second. Steam reports native transport rates; PlayFab reports socket payload rates, not compressed wire bandwidth. These are not directly interchangeable.
• Queues: native queued bytes and unacknowledged/in-flight bytes are shown separately from application queued messages. PlayFab in-flight bytes are an outstanding payload indicator, not an exact wire backlog; layers can overlap and should not be added as a bandwidth measurement.
• Priority/invalid ZDOs: pending priority synchronization work and invalidation notices, not every unsent world object. An idle connection with no pending work is not starvation.
• Send-window pressure: queued application sends or traffic approaching Valheim 1.0.12's ZDO send-budget boundary. The PlayFab reading uses the game's discounted queue estimate; it is not an exact wire measurement.
• Possible starvation: pending priority/invalidation work or send-window pressure with no successful ZDO send for the configured interval. It is an indicator, not proof that a specific object is stuck.
• Ownership: read-only transition counters. Rapid-transfer detection tracks up to 1,024 object IDs over a ten-second window; assignments and releases are counted separately.

Warnings cover sustained high RTT, queue growth, overdue heartbeats, slow mean frames, rapid ownership churn, and possible starvation. Network warnings allow a 15-second peer warm-up. Conditions must persist for five seconds by default; repeated warnings are limited to once per minute per category, with a recovery message after sustained improvement. High player occupancy is reported when the validated override is active. Thresholds are configurable under [Server Health].

Safety and compatibility

Valheim remains responsible for snapshot preparation and disk writing. Synchronous shutdown saves are never deferred, and periodic deferral has a hard maximum. World Engine never deletes, rewrites, compacts, reprioritizes, or force-sends world data; unknown mod data is preserved. It has no client UI or custom protocol and runs on dedicated servers with the same small footprint.

Authority and performance bounds

World-data handling remains conservative:

• it never deletes, rewrites, compacts, quarantines, reprioritizes, or force-sends a ZDO;
• unknown third-party data is always preserved;
• it creates no persistent world keys of its own;
• it publishes no registry, capability, protocol, ownership declaration, or cross-mod service;
• it has no client UI or asset load, so dedicated servers use the same small runtime;
• optional summaries are off by default and rate-limited to 5–600 seconds.

The world observatory uses constant-time collection counts and event counters. Network health samples at most 128 peers per second and keeps a bounded ownership history. It does not perform a base scan, sector walk, prefab enumeration, heat-map build, or save clone on the game thread. Save/load completion cannot force an extra sample through the one-second ceiling. A failed sample is discarded without changing world state or blocking any gameplay mod.

Save smoothing

Asynchronous periodic saves are coalesced while an earlier save is still active and their main-thread preparation is deferred briefly when the previous frame exceeded the configured frame budget. The deferral is bounded (five seconds by default), so a persistently busy server still saves. Synchronous shutdown saves are never deferred. The smoother never touches Unity objects from a worker thread; Valheim retains ownership of both snapshot preparation and its normal disk writer. This reduces avoidable save-time spikes, but no mod can promise a literally zero-frame hitch for every world size and storage device.

Configuration

World heat maps, compaction, and synchronization rescheduling are not enabled by this mod.

Compatibility: startup validates required game APIs rather than rejecting an unfamiliar game version. Actual API incompatibilities still disable safely.

Changelog

1.2.2 - 2026-09-18

• Replaced the exact game-version allowlist with startup API validation. Compatible future patches no longer require a version-only update.
• Incompatible APIs still fail closed; World Engine retains its exact method-body audit.

1.2.1 - 2026-09-17

• Fixed the optional player-cap override rejecting Valheim 1.0.14 and blocking hosting or new admissions.
• Retained Valheim 1.0.12 support and all method-body, loaded-IL, conflict, and admission-integrity checks. Unknown builds remain rejected.

1.2.0 - 2026-09-12

• Added an optional, configurable 2–64 player cap with coordinated Steam, PlayFab, and admission limits, including the dedicated host's transport slot.
• Added startup validation and admission integrity checks for the audited Valheim 1.0.12 hosting-limit patches.
• Added runicworld_status, peer counts, Steam/PlayFab RTT and traffic rates, queue diagnostics, ownership-transfer counters, and possible synchronization-starvation indicators.
• Added configurable, sustained server-health warnings with recovery messages and rate limiting.
• Preserved existing save smoothing and read-only world diagnostics.

1.1.2 - 2026-09-09

• Migrated save timing to Valheim 1.0.7's exact ZDOMan.SaveChunks and LoadChunks contracts while retaining a separate legacy-world load observation seam.
• Added the required assembly_utils reference for the new file-source parameter and verified all observatory targets against both installed client and dedicated-server assemblies.
• Updated the release dependency floor to BepInExPack Valheim 5.4.2350.

1.1.1 - 2026-09-05

• Reworked the Thunderstore description and README opening to lead with the player problem, the mod's core benefit, major features, in-game feel, and then safety and compatibility details.
• Description-only package update. The plugin DLL and gameplay behavior are byte-for-byte unchanged from 1.1.0.

1.1.0 - 2026-08-31

• Added bounded main-thread save preparation smoothing for asynchronous periodic saves.
• Coalesces overlapping requests, never defers synchronous shutdown saves, and never accesses Unity objects from a background worker.

1.0.0

• Kept constant-time aggregate ZDO observability and interval event counters.
• Kept installed-Valheim-verified save/load timing hooks with exception-preserving finalizers.
• Made Enabled = false startup-inert and deferred Harmony construction until after the setting gate.
• Verified exact installed field shapes and kept load completion within the one-second sample ceiling.
• Removed the Core registry, capability, protocol, service, and world-data ownership declaration architecture; BepInExPack Valheim is the only runtime dependency.
• Preserved all unknown data and retained no deletion, compaction, or sync-scheduling path.