ValheimKillStats

A client-server synchronized BepInEx plugin for Valheim that tracks comprehensive player statistics and exports them to JSON for external dashboards and analytics.

Architecture

This plugin uses a client-server model where:

• Clients capture game events (kills, damage, crafting, etc.) using Harmony patches
• Server receives stats via RPC and persists them to JSON
• Mod Enforcement ensures all connecting players have the mod installed (players without it are kicked after 10 seconds)

This design is necessary because Valheim's combat and many other events only fire on the client side.

Features

Combat & Deaths

• Kill Tracking - Records every creature kill by type per player
• Boss Kills - Tracks all 7 boss defeats separately
• Death Tracking - Records deaths with cause (creature name, PvP, or environmental)
• Damage Dealt - Total damage dealt by each player

Gathering & Crafting

• Resource Gathering - Tracks 21 resource types (wood, ores, hides, etc.)
• Foraging - Berries, mushrooms, thistle, and other pickables
• Farming - Seeds planted and crops harvested
• Crafting - Records every item crafted with quantities
• Processing - Ore smelted, coal produced, flour milled, etc.
• Cooking - Meat roasted on cooking stations
• Brewing - Meads fermented in fermenters
• Building - Every structure placed and deconstructed tracked by type

Player Progress

• Skills - Snapshots of all 18 skill levels
• Inventory - Current inventory contents with item quality

Activity

• Time Played - Total session time per player
• Distance Traveled - Cumulative distance moved
• Last Seen - Timestamp of last activity

Timeline & Progression (v0.6.0+)

• Event History - Complete timeline of all game events with Valheim's in-game day
• Kill Events - Every creature and boss kill with game day
• Death Events - Player deaths with cause and game day
• Crafting Events - Items crafted, cooked, brewed, processed
• Gathering Events - Resources collected, items foraged
• Building Events - Structures placed and deconstructed, seeds planted
• Session Tracking - Player join/leave events with timestamps
• Day-End Snapshots - Skills and distance captured at end of each game day for progression tracking

Installation

Server

1. Download ValheimKillStats.dll from the Releases page
2. Copy to your server's BepInEx/plugins/ folder
3. Restart the server

Stats are written to BepInEx/plugins/stats.json every 2 seconds. Timeline events are written to BepInEx/plugins/timeline.json every 2 seconds.

Client (Required)

All players must install the mod to play on the server. Players without the mod will be kicked after 10 seconds.

1. Install BepInEx if not already installed
2. Download ValheimKillStats.dll from the Releases page
3. Copy to your client's BepInEx/plugins/ folder
4. Launch Valheim

The client version must match the server version.

JSON Output Format

{
  "lastUpdated": "2025-12-14T10:30:00Z",
  "players": {
    "Viking": {
      "totalKills": 150,
      "killsByCreature": {
        "Greydwarf": 45,
        "Greydwarf_Elite": 8,
        "Troll": 3,
        "Skeleton": 22
      },
      "bossKills": {
        "Eikthyr": 1,
        "gd_king": 1
      },
      "deaths": 5,
      "deathsByCause": {
        "Greydwarf": 2,
        "Troll": 1,
        "Fall": 1,
        "PvP": 1
      },
      "damageDealt": 125430.0,
      "resourcesGathered": {
        "Wood": 2500,
        "Stone": 800,
        "Copper Ore": 150,
        "Fine Wood": 320
      },
      "itemsCrafted": {
        "item_sword_iron": 2,
        "item_bow_huntsman": 1,
        "item_shield_wood": 3
      },
      "itemsGathered": {
        "Raspberry": 45,
        "Blueberry": 32,
        "Mushroom": 28,
        "Thistle": 15
      },
      "seedsPlanted": {
        "Carrot": 50,
        "Turnip": 30,
        "Barley": 100
      },
      "itemsProcessed": {
        "CopperOre (Smelter)": 80,
        "TinOre (Smelter)": 40,
        "Wood (Charcoal Kiln)": 200,
        "Barley (Windmill)": 50
      },
      "foodCooked": {
        "Cooked Meat": 45,
        "Grilled Neck Tail": 12,
        "Cooked Fish": 8
      },
      "meadsBrewed": {
        "MeadBaseTasty": 10,
        "MeadBaseHealthMinor": 5,
        "MeadBaseStaminaMinor": 8
      },
      "structuresBuilt": {
        "piece_wall_wood": 150,
        "piece_floor_wood": 80,
        "piece_roof_wood": 45,
        "piece_workbench": 3,
        "piece_chest_wood": 12
      },
      "skills": {
        "Swords": 45.5,
        "Axes": 38.2,
        "Wood Cutting": 52.0,
        "Run": 28.3
      },
      "currentInventory": [
        {"name": "item_sword_iron", "amount": 1, "quality": 3},
        {"name": "Wood", "amount": 50, "quality": 0},
        {"name": "Coins", "amount": 234, "quality": 0}
      ],
      "timePlayedSeconds": 36000,
      "distanceTraveled": 45230.5,
      "lastSeen": "2025-12-14T10:25:00Z"
    }
  },
  "serverTotals": {
    "totalKills": 523,
    "totalDeaths": 28,
    "totalDamageDealt": 482000.0,
    "totalItemsCrafted": 156,
    "totalItemsGathered": 892,
    "totalSeedsPlanted": 340,
    "totalItemsProcessed": 1250,
    "totalFoodCooked": 245,
    "totalMeadsBrewed": 89,
    "totalStructuresBuilt": 1547,
    "bossesDefeated": ["Eikthyr", "gd_king", "Bonemass"]
  }
}

Timeline Output Format (v0.6.0+)

{
  "version": "1.0",
  "lastUpdated": "2025-12-20T10:30:00Z",
  "currentGameDay": 45,
  "eventCount": 1523,
  "events": [
    {
      "id": "a1b2c3...",
      "eventType": "Kill",
      "player": "Viking",
      "gameDay": 5,
      "realTimestamp": "2025-12-20T08:15:00Z",
      "target": "Greydwarf"
    },
    {
      "id": "b2c3d4...",
      "eventType": "BossKill",
      "player": "Viking",
      "gameDay": 45,
      "realTimestamp": "2025-12-20T12:30:00Z",
      "target": "Eikthyr",
      "isBoss": true
    },
    {
      "id": "c3d4e5...",
      "eventType": "DayEnd",
      "player": "Viking",
      "gameDay": 45,
      "realTimestamp": "2025-12-20T22:00:00Z",
      "skills": { "Swords": 52.3, "Axes": 28.1, "Run": 45.0 },
      "distance": 12500.0
    }
  ]
}

See TIMELINE_SCHEMA.md for complete documentation.

Tracked Data Reference

Resources (55+ types)

Category	Resources
Wood	Wood, Fine Wood, Core Wood, Ancient Bark, Yggdrasil Wood, Ashwood
Stone	Stone, Flint, Obsidian, Grausten, Black Marble
Ores	Copper Ore, Tin Ore, Iron Scrap, Silver Ore, Black Metal, Flametal Ore
Gemstones	Bloodstone, Iolite, Jade
Hides	Leather Scraps, Deer Hide, Troll Hide, Wolf Pelt, Lox Pelt, Scale Hide, Asksvin Hide
Mistlands	Sap, Carapace, Mandible, Bilebag, Blood Clot, Soft Tissue, Seeker Meat, Blue Jute
Ashlands	Sulfur, Charcoal Resin, Proustite Powder, Molten Core, Celestial Feather
Ashlands Drops	Asksvin Bladder/Neck, Morgen Heart/Sinew, Bonemaw Meat, Vulture Meat
Other	Coal, Resin, Guck, Chitin, Black Core, Feathers, Tar

Skills (18 types)

Category	Skills
Combat	Swords, Knives, Clubs, Polearms, Spears, Axes, Unarmed, Bows, Crossbows, Blocking
Gathering	Pickaxes, Wood Cutting
Movement	Run, Jump, Sneak, Swim
Other	Fishing, Ride

Bosses (12)

Prefab Name	Boss	Type
Eikthyr	Eikthyr	Main
gd_king	The Elder	Main
Bonemass	Bonemass	Main
Dragon	Moder	Main
GoblinKing	Yagluth	Main
SeekerQueen	The Queen	Main
Fader	Fader	Main
Brenna	Brenna	Mini
Geirrhafa	Geirrhafa	Mini
Zil	Zil	Mini
Thungr	Thungr	Mini
LordReto	Lord Reto	Mini

Gatherables (Foraging)

Category	Items
Berries	Raspberry, Blueberry, Cloudberry
Mushrooms	Mushroom, Blue Mushroom, Yellow Mushroom, Jotunpuffs, Magecap
Plants	Thistle, Dandelion, Carrot, Turnip, Onion, Barley, Flax
Other	Honey, Surtling Core, Greydwarf Eye, Freeze Gland, Royal Jelly, Dragon Egg
Ashlands	Smoke Puff, Fiddlehead, Vineberry Cluster
Eggs	Egg, Chicken Egg

Seeds & Planting

Category	Items
Vegetables	Carrot, Turnip, Onion
Crops	Barley, Flax
Trees	Beech, Birch, Oak, Pine, Fir

Processors

Processor	Function
Smelter	Ore → Metal bars
Blast Furnace	Advanced ore → Metal
Charcoal Kiln	Wood → Coal
Windmill	Barley → Flour
Spinning Wheel	Flax → Linen
Eitr Refinery	Sap + Soft Tissue → Eitr

Cooking Station Foods (16)

Prefab	Display Name	Station
CookedMeat	Cooked Meat	Standard
NeckTailGrilled	Grilled Neck Tail	Standard
CookedFish	Cooked Fish	Standard
CookedLoxMeat	Cooked Lox Meat	Standard
CookedHareMeat	Cooked Hare Meat	Standard
CookedChickenMeat	Cooked Chicken Meat	Standard
CookedDeerMeat	Cooked Deer Meat	Standard
CookedWolfMeat	Cooked Wolf Meat	Standard
CookedBugMeat	Cooked Bug Meat	Standard
SerpentMeatCooked	Cooked Serpent Meat	Standard
CookedBoarMeat	Cooked Boar Meat	Standard
CookedSeekerMeat	Cooked Seeker Meat	Iron
CookedBonemawMeat	Cooked Bonemaw Meat	Iron
CookedAsksvintail	Cooked Asksvin Tail	Iron
CookedVultureMeat	Cooked Vulture Meat	Iron
Bread	Bread	Oven

Cauldron Foods (19)

Prefab	Display Name	Type
SoupCarrot	Carrot Soup	Soup
SoupMushroomBlue	Blue Mushroom Soup	Soup
SoupMushroom	Mushroom Soup	Soup
SoupThistleBlood	Blood Thistle Soup	Soup
SoupFish	Fish Soup	Soup
SoupFishFancy	Fancy Fish Soup	Soup
SoupDumplings	Dumpling Soup	Soup
SoupYggdrasilFlesh	Yggdrasil Flesh Soup	Soup
StewIronbind	Ironbind Stew	Stew
StewBlood	Blood Stew	Stew
StewFishWraith	Fish Wraith Stew	Stew
StewSnowball	Snowball Stew	Stew
StewSerpent	Serpent Stew	Stew
StewCholesterol	Cholesterol Stew	Stew
SaladPreparedGreen	Green Salad	Salad
SaladPreparedCold	Cold Salad	Salad
SaladPreparedCookedVegetable	Vegetable Salad	Salad
Sausages	Sausages	Other
BlackSoup	Black Soup	Other

Stone Oven Foods (9)

Prefab	Display Name
Bread	Bread
BarleyFlour	Barley Flour
PieApple	Apple Pie
PieVegetable	Vegetable Pie
CookedCarrot	Cooked Carrot
CookedOnion	Cooked Onion
CookedTurnip	Cooked Turnip
CookedMushroom	Cooked Mushroom
CookedBeetsoup	Beet Soup

Fermenter (Meads)

Tracks when mead bases are added to fermenters:

• MeadBaseTasty, MeadBaseHealthMinor, MeadBaseHealthMedium, MeadBaseHealthMajor
• MeadBaseStaminaMinor, MeadBaseStaminaMedium, MeadBaseFrostResist
• MeadBasePoisonResist, MeadBaseEitrMinor, and more

Building Structures

All pieces placed via the hammer are tracked by piece name, including:

• Walls, floors, roofs, beams, poles, stairs
• Workbenches, forges, stonecutters, artisan stations
• Beds, chests, signs, portals, wards
• Decorations, furniture, and all other placeable structures

Technical Details

• Distance updates: Every 2 seconds (filters teleports >100 units)
• Stats save: Every 2 seconds
• Timeline save: Every 2 seconds
• Skill/inventory snapshots: Every 2 seconds
• Day-end snapshots: Emitted when in-game day changes (captures skills + distance for each player)
• Thread-safe: All stats operations are locked for concurrent access
• Persistent: Stats and timeline accumulate across server restarts
• Timeline rotation: Rotates to archive file when >10MB

How It Works

Client Side (Event Capture)

The plugin uses Harmony to patch Valheim game methods on the client:

• Character.Damage - Track damage and last attacker
• Character.OnDeath - Attribute kills and record deaths
• Inventory.AddItem - Track resource gathering
• InventoryGui.DoCrafting - Track crafting and cauldron/oven foods
• Pickable.RPC_Pick - Track foraging (berries, mushrooms, etc.)
• Player.PlacePiece - Track farming (planting seeds) and building (structures)
• Smelter.OnAddOre / Smelter.OnAddFuel - Track processing
• CookingStation.UpdateCooking - Track cooking (when food finishes cooking)
• Fermenter.AddItem - Track brewing (meads)
• Player.OnSpawned / Player.OnDestroy - Session tracking

Server Side (Persistence)

• Receives stats via ZRoutedRpc RPCs from clients
• Persists cumulative stats to stats.json
• Enforces mod installation via version handshake

RPC Messages

• KillStats_Kill - Kill event with creature name
• KillStats_BossKill - Boss defeat
• KillStats_Death - Player death with cause
• KillStats_Damage - Damage dealt
• KillStats_Resource - Resource gathered
• KillStats_Craft - Item crafted
• KillStats_Gather - Item foraged
• KillStats_Plant - Seed planted
• KillStats_Process - Item processed
• KillStats_Cook - Food cooked
• KillStats_Brew - Mead brewed
• KillStats_Build - Structure built
• KillStats_Skills - Skill snapshot
• KillStats_Inventory - Inventory snapshot
• KillStats_Distance - Distance traveled
• KillStats_Playtime - Session time
• KillStats_ModCheck - Version handshake
• KillStats_Timeline - Timeline event (v0.6.0+)

Requirements

• Valheim Dedicated Server with BepInEx 5.4.x
• All clients must have BepInEx 5.4.x and the same version of this mod

Building from Source

dotnet restore
dotnet build --configuration Release

Output: ValheimKillStats/bin/Release/net462/ValheimKillStats.dll

License

MIT License

Credits

Built for the mrberto Valheim server.