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.

0.4.4

• Support TidyChests 1.4/1.5 quick-deposit signatures while retaining the earlier adapter, and observe its restock path without nested duplicates.
• Add BestAutoSort 0.6 server-authority deposit/withdrawal observation after persisted commits, with actual quantities, sender attribution and optional Epic Loot metadata.
• Keep legacy chest-owner observation; reject remote claims against server-owned chests. Cached responses, rejected/uncertain transfers and unresolved actors are not recorded as successful player transfers.
• Exclude BestAutoSort feeder transactions from player-inventory attribution. Integrations remain optional and never modify inventories, ownership or transaction outcomes.

0.4.3

• Observe creature drops and successful world pickups with optional Epic Loot metadata and exact-ID origin links.
• Add item-transfer evidence, including Tidy Chests quick deposit, committed BestAutoSort chest transactions and observed local consumption.
• Distinguish player-origin pickups, recipe and planting consumption, and automatic FeedLikeGrandma chest removals.
• Add searchable item/chest summaries, bounded origin caches and separate routine detail routing.
• Preserve missing-origin and incomplete-transfer evidence rather than inferring where items came from or went.

0.4.2

• Add Today / Last 7 days / All time leaderboard filters, compact daily-to-monthly history and automatic retained-raw-log period import.
• Save bounded boss encounter summaries with player damage shares and exact-boss death links.
• Attribute observed poison/burning effects conservatively; mixed-source pools remain unassigned. Preserve the source of lethal ticks through deferred death processing.
• Add a configurable F8 leaderboard with shared ranks, bounded replies and honest missing-data handling.
• Detect optional Epic Loot and report changes to equipped rarity/enchantments; show latest gear in F8.
• Exclude proven maximum-health clamps from combat damage and avoid per-tick food-decay log noise.
• Add age/size retention, verified compressed archives and a compact lifetime ledger; archive storage is bounded too.
• Reduce routine snapshots during detected AFK and suppress initial None-biome transitions.
• Read compressed archives on demand, use common creature names, and prune stale generated exports.
• Remove repeated read-only/admin UI notices; keep one concise description statement.

0.4.1 - Previous version data import support

• Keep the F8 window opaque when focused or clicked.
• End the GUI event cleanly when switching tabs, filtering counters or closing. Restore shared GUI colors after drawing.
• Automatically backfill retained 0.1 kills/deaths once per world, preserving newer progress and saving an import marker with the totals. Identify imported portions in F8.
• Simplify repetitive README text.

0.4.0

• Group building, mining, woodcutting, crafting, gathering and fishing into ten-minute per-player work summaries with separate action-time sites, evidence-based main activity and partial disconnect/restart recovery.
• Keep kills, deaths and revenge immediate. Link recent work with explicit time/proximity limits and confidence wording.
• Separate readable story events from routine detail evidence, retaining searchable provenance and avoiding duplicated totals.
• Add latest work summaries to F8 Adventure and the HTML overview. Negotiate protocol 4 with compatibility fallbacks to earlier collectors.
• Preserve existing gameplay settings, optional reporting and read-only statistics. No automatic messages or admin powers.

Changelog

0.3.0

• Add a configurable F8 in-game stats window with Combat, Adventure, and Skills & Condition tabs. It reads the authenticated player's own server record, refreshes while open, and restores normal input when closed.
• Observe changes across Valheim's 205 native stat categories, plus named pickup, crafting, harvest, food, building and enemy-credit counters. Keep overlapping native counters separate from directly observed deaths and damage.
• Add periodic snapshots of health, stamina, eitr, armor, carry weight, comfort, equipped weapon, food and skills. Compare nearby same-connection skill samples without counting imported character history as earned progress.
• Sample client biomes every two seconds; add reporting-session start/end events. Snapshots normally refresh every 30 seconds and on observed biome changes.
• Preserve pending native-stat changes across respawn; reset on character-profile or connection changes. Expire invalid entries individually so one stale metric does not invalidate a fresh batch.
• Explicitly distinguish long unobserved client stalls from active and AFK time. Flag gaps and out-of-order observations in damage breakdowns.
• Add a searchable HTML overview, SQLite index/query tool, player/day exports, stable event links and a field schema. Avoid double-counting matching client/server biome observations.
• Keep detailed damage ledgers out of compact correlation saves; cache native reflection fields and bound queues, metrics, snapshots and own-stat replies.
• Include source, optional report tools, field documentation and validation notes. No admin commands, automatic announcements or external analytics.

0.2.0

• Add actual HP loss and per-source percentages, assists, persistent player statistics, AFK estimates, emotes, building placements and boat/structure removals.
• Negotiate enhanced reporting while retaining death-only compatibility with version 0.1.
• Add a read-only report tool.

0.1.0

• Initial experimental owner-reported deaths, killing blows and exact-creature revenge correlation.