Viking Storyteller

Experimental 0.2.0 for Valheim 1.0.15. Records gameplay facts for per-player recaps: deaths, killing blows, damage contributions, assists, AFK estimates, emotes, building placements, and boat/structure removals. Exact-creature revenge links are retained.

The mod does not generate prose or post automatic chat messages. It provides local files for a server operator or reporting tools. It grants no admin powers and does not change combat, inventory, loot, building or multiplayer ownership.

Install and update

Install on the server and all participating players' Thunderstore profiles, then restart the server and games. Dependencies: BepInExPack Valheim 5.4.2350 and JsonDotNET 13.0.4.

Clients without this mod can still join. Version 0.1 clients still supply deaths to a 0.2 collector, but cannot supply new observations. A 0.2 client falls back to death-only reporting with a 0.1 collector. A server without the mod receives at most three negotiation attempts; continuous reporting requires acceptance.

Damage contributions and statistics

The owner of each character observes resulting health changes. Actual HP lost is measured after armor, resistance and other changes handled before the final health write. A finishing hit receives credit only for HP actually removed, not its overkill attack value. A fully blocked hit with no HP loss contributes zero.

Both player and creature deaths receive an encounter breakdown. Each source includes an entity identity when available, HP removed, hit count and percentage. The killing blow remains separate. Unknown attackers are never assigned to a guessed player or creature. Falls and other unattributed causes retain separate buckets. Damage-over-time effects are attributed only when the game's hit data identifies their attacker.

An encounter resets at observed full recovery or after 120 seconds without recorded health loss. It can continue throughout a long boss fight while damage continues. Partial healing remains in the encounter, so total HP lost can exceed maximum HP. Percentages divide each source's observed HP loss by total observed HP loss, including unknown sources. They describe recorded damage, not guaranteed complete coverage or a causal percentage of blame. Starting health and coverage notes accompany the breakdown.

Accepted observations accumulate on the collector across ownership changes. A report can still be rejected if its ownership evidence has vanished. Missing reporters, restarts, queue overflow, unknown prefabs and mods bypassing observed methods can leave gaps. In-progress encounters do not survive a collector restart. A death with no damage observations says unavailable rather than inventing a breakdown.

Per-player totals include creature killing blows, player killing blows, creature assists, deaths, HP damage dealt to creatures/players, HP lost, observed health gains, active/AFK seconds, emotes and pieces placed. An assist means positive recorded damage in that creature's final recorded encounter without its killing blow. Each account gets at most one assist per creature, including across respawns. Historical deaths are not retroactively converted into damage or assist statistics. Health gains can include food or other HP changes, not just healing abilities.

AFK, emotes and building

AFK defaults to five minutes without observed in-game input. The grace period counts as active; only time after it counts AFK. Activity reports are sent about every 15 seconds, giving transition timestamps that resolution. Unreported time, disconnects and long stalls are not silently counted as either active or AFK.

The client reads Valheim's input activity timestamp and controller stick activity while focused. It sends durations and an AFK flag, never key contents, chat text or device identifiers. Successful emotes also count as activity. Boat movement and incoming damage do not. This is a heuristic, not proof of physical presence; scripts, held inputs and controller drift can affect it. There are no AFK kicks or announcements.

Successful local-player emotes record name, player, time and position. Completed Player.PlacePiece calls record the prefab and placement position. This includes mods using that method; it is not an inventory or crafting log. Failed or skipped methods are not reported.

The server separately records confirmed permanent network-object removals for recognized boats and built structure prefabs. boat_removed and structure_removed include prefab, object identity, time and position. Removal does not distinguish destruction, dismantling or admin deletion and does not identify who caused it. Ordinary client unloading is not permanent network-object removal. Custom boats without the game's Ship component and unrecognized prefabs may not be classified.

Biome/travel observation, item collection, crafting, equipment changes and chat transcription are not provided by this release. External server observers can supplement these files.

Files and reporting

Under BepInEx/config/VikingStoryteller/:

• <world-id>-events.jsonl: deaths, revenge links, health changes, activity, emotes, placements and removals.
• <world-id>-state.json: death deduplication and correlation.
• <world-id>-stats.json: cumulative per-player statistics since enhanced collection began, keyed by account rather than display name.
• status.json: collector health, protocol coverage and accepted/rejected/dropped counts.

The event file rotates near 20 MiB and retains ten archives per world. Logs flush every two seconds; state saves every 15 seconds and on normal unload. Crashes can lose buffered records. Event IDs support deduplication. Reports can be incomplete if older logs have rotated away.

The optional read-only Python 3 tool tools/report.py produces per-player JSON and a timeline for a time range. It omits account IDs from its output. Example:

python report.py --directory /path/to/BepInEx/config/VikingStoryteller --world YOUR_NUMERIC_WORLD_ID --since 2026-09-20T12:00:00-05:00

No extra port, API key or external analytics service is used. This package includes the DLL, documentation, license, source and report tool; no player logs, admin helper or test plugin. Local server records contain account identifiers, in-game names, positions and gameplay events. Tell players what is collected and avoid publishing raw files.

Configuration: JacobsValheim.VikingStoryteller.cfg. Existing Send gameplay death reports and Collect gameplay death reports switches now cover all reporting, preserving prior opt-outs. AFK after seconds without input defaults to 300 and accepts 60 through 3600. Restart after changing configuration.

Validation and limitations

52 pure-model checks cover damage math, identity, deduplication, attribution, AFK and action validation. An isolated Valheim test covers real HP changes/death, capped overkill, healing, boat/structure removal and actual ZRpc negotiation/serialization. Protocol tests reject wrong owners, invalid tokens, replayed sequences, oversized batches and another player's activity claims. Normal multi-PC testing of client input, emotes and placement remains necessary.

The collector validates peer identity, session token, world, timestamp, numeric/payload bounds and victim ownership. Client observations are not anti-cheat proof. No reporting RPC executes commands. Bounded queues, rate limits, source limits and log rotation favor gameplay over retaining every observation under overload.

Correlation retains 2,000 deaths and at most 8,192 victim IDs. Up to 2,048 encounters and 64 source buckets per encounter are retained; excess sources enter a labeled bucket. World rollback can reuse IDs: archive/reset matching story state after deliberately restoring a world if a fresh history is desired.

MIT-licensed source is included. Build against Valheim managed assemblies, BepInEx, Harmony and JsonDotNET. Do not redistribute game assemblies.

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.