Viking Storyteller

Experimental 0.1.0 for Valheim 1.0.15. Read-only death reporting and exact-creature revenge links for server operators who want to write gameplay recaps. No automatic roasts, chat messages, admin commands, or gameplay changes.

Install

Install Viking Storyteller on the server and every participating player's Thunderstore profile, then restart the server and game. Players without the mod can still join, but missing reporters leave gaps. A client waits for the server collector's handshake before sending death reports. A server without the collector receives at most three harmless handshake attempts per connection; reporting stays inactive.

Dependencies: BepInExPack Valheim 5.4.2350 and JsonDotNET 13.0.4. This package contains only VikingStoryteller.dll, documentation, license and source. It does not include a private admin helper, credentials, player data, or a test plugin. It does not upload reports to Thunderstore or any analytics service.

What it records

When the computer owning a player or creature runs the game's death method, the reporter captures the game's last-hit attacker, victim entity ID, cause type, world/time, and location. The collector resolves creature prefab names and player identities from its own network state. Creature identity is world ID plus network entity ID, not its name or species.

If a creature kills a player and that exact creature is subsequently killed by the same player's new or existing character, the collector emits revenge. If another identified player kills it, it emits avenged_by_teammate. Reports arriving in either order can link, using game time and both source event IDs. Killing a different boar does not count. An unknown attacker stays unknown.

Reports are observations from clients, not anti-cheat proof. The collector checks the connected sender, connection token, world, timestamp, payload limits and current/recent victim ownership. Clients cannot send admin commands, spawn items, teleport people, or edit server settings through this protocol.

Limits

• This initial release has isolated model/protocol checks and a disposable-server native death test. Real multiplayer client-to-server coverage has not yet been verified. Keep normal world and character backups when trying a new mod.
• All participating clients need the reporter to observe combat owned by those clients. Missing reporters, lag, unavailable prefabs, unresolved attackers or other mods replacing death handling can leave gaps.
• Attacker means the game's last-hit attribution. Damage-over-time effects and other mods can make that differ from a simple final weapon hit. Environmental or unknown deaths are not assigned to a guessed creature.
• No continuous damage/DPS, inventory, crafting, chat, biome tracking or automatic narrative generation is provided by this package. It supplies structured death stories for manual review or separate tooling.
• Creature ownership can migrate; a report can be rejected if ownership evidence is no longer available. Removed-entity evidence is retained for 30 seconds. Events older than 120 seconds are rejected.
• Correlation keeps 2,000 death events. Dedup keeps up to 8,192 victim IDs. A world rollback can reuse prior IDs; archive/reset this mod's matching world state after deliberately restoring a world backup if you want a fresh story history.
• Client queues are bounded at 256 events; server queues at 2,048 log lines. The collector accepts at most 256 reports per connection per ten seconds. Overload and sudden shutdown can drop telemetry without affecting gameplay.

Server files

BepInEx/config/VikingStoryteller/ contains:

• <world-id>-events.jsonl: death observations and revenge links, one JSON object per line.
• <world-id>-state.json: persistent dedup/correlation history.
• status.json: collector health, accepted/rejected/dropped counts and reporting connections.

The current event file rotates at approximately 20 MiB. Ten archives are retained per world. State is saved every 15 seconds and on normal unload; pending event lines flush every two seconds. A crash can lose recent buffered records. Event IDs allow consumers to deduplicate a repeated line after an interrupted write.

These files contain in-game names, platform account identifiers, positions and gameplay events. They remain on the server computer. Server operators should tell their players what they collect and avoid publishing raw files containing account identifiers.

Configuration file: BepInEx/config/JacobsValheim.VikingStoryteller.cfg. Players can turn Send gameplay death reports off; operators can turn Collect gameplay death reports off. Configuration changes take effect on restart. No public service, API key or extra network port is needed.

Source and support

Source is included under source/ with an MIT license. Build against the installed Valheim 1.0.15 managed assemblies, BepInEx and Harmony, plus Newtonsoft.Json from JsonDotNET. Do not redistribute the game's DLLs. This is an experimental small-server tool, not an anti-cheat or moderation system.