VikingLib

VikingLib is a modular combat mechanics, character statistic, and damage calculation framework for Valheim. It decouples Valheim's combat and stat systems from monolithic vanilla methods, providing a deterministic foundation for custom combat overhauls, RPG progression, weapon packs, and perk mods.

⚠️ Work in Progress (Pre-Release v0.2.1): This framework is in active development and has not been tested extensively across all game configurations. Features, internal APIs, and mechanics may change, and unintended edge cases may occur. Backup your character and world saves before testing.

How It Works

VikingLib intercepts and standardizes all combat math, stat mutations, and stamina drains through deterministic pipelines:

• 6-Phase Prioritized Damage Pipeline: Every melee hit, projectile, and environmental impact executes sequentially across 6 distinct phases (PreCheck, AttackerModifiers, TargetDefenses, Mitigation, Execution, PostHitProcs), with full support for multi-target cleave decay, armor penetration, and continuous resistances.
• Dual-Space 3-Tier Mathematical Engine: Evaluates character stats across 90+ tokens using strict mathematical tiers: Tier 1 (Flat base values), Tier 2 (Additive percentages), and Tier 3 (Compounding multipliers).
• Asymptotic Action Efficiency: Stamina, eitr, and health costs scale smoothly in the denominator, ensuring efficiency buffs never reduce action drains to zero or exploit negative numbers (+100% efficiency halves action costs; +200% divides costs by three).
• Combat Dossier & Hugin's Compendium: Inspect full weapon combo chains, cleave ratings, and live stamina costs by holding [Shift] over weapon tooltips, and view active character statistics cleanly categorized inside Hugin's Compendium (TextsDialog).

[BepInPlugin("com.author.mymod", "MyCombatMod", "1.0.0")]
[BepInDependency("com.digitalvikings.vikinglib", BepInDependency.DependencyFlags.HardDependency)]
public class MyModPlugin : BaseUnityPlugin
{
    private void Awake()
    {
        // Add declarative character stat modifier (+20% sword damage)
        CharacterStats.DamageSwords.AddIncreased(Player.m_localPlayer, 0.20f, "Swordmaster");

        // Add type-safe resistance modifier (Tier 3 Multiplier ONLY, -20% fire damage taken)
        CharacterStats.ResistanceFire.AddMultiplier(Player.m_localPlayer, 0.80f, "Fire Ward");

        // Add asymptotic efficiency modifier (+25% melee stamina efficiency)
        CharacterStats.MeleeStaminaEfficiency.AddIncreased(Player.m_localPlayer, 0.25f, "Iron Stamina");
    }
}

Changelog

All notable changes to VikingLib will be documented in this file.

[0.3.0] - 2026-11-03

Added

• Dynamic Poise Scaling: Enemy stagger thresholds now scale dynamically via a square-root health formula with customizable coefficient and outlier offsets.
• Multi-Secondary Attack Support: Weapon attack discovery now recognizes chained secondary attacks, rendering individual attack profiles in item dossiers.
• Elemental Armor Absorption: Configurable armor absorption for elemental and magic damage sources alongside physical damage mitigation.
• Decoupled Bare-Hand Combat: Unarmed strikes and crafted fist/claw weapons now maintain distinct secondary attack profiles and progression.

Changed

• Bleed Damage Model: Bleeding afflictions now support severity-gated refresh models and dual absolute/relative health caps.
• Combat Balance Defaults: Retuned baseline stagger coefficient, poise linger duration, pierce precision, and shield poise retaliation.

Fixed

• Unspawned Creature Dossiers: Resolved null reference exceptions when inspecting uninstantiated creature prefabs in the bestiary compendium.

[0.2.3] - 2026-10-29

Added

• Creature Cleave System: Introduced multi-target cleave scaling on creatures, granting full cleave capability to bosses and giants.
• Status Effect Persistence: Active Forsaken powers, meads, and potions are now preserved across logout and reconnection.
• Combat Wounded State: Taking direct physical damage temporarily reduces health regeneration to 33% for 8 seconds with custom HUD indicators.
• Project Auga UI Integration: Real-time combat and survival stats injected natively into Auga's Player panel with custom scroll drawer and quick-jump link.
• Creature & Lore Dossiers: Unlocked creature combat dossiers and martial treatises integrated into Hugin's Compendium and Auga's Bestiary.

Changed

• Modularized Phase Handlers: Decoupled default combat phase implementations into dedicated handler structures for improved maintainability.
• Skill Lifecycle Architecture: Reorganized native skill interception patches into dedicated domain modules.

Fixed

• Eikthyr Stamina Scaling: Corrected Forsaken power stamina cost calculation to grant the full intended 60% discount.

[0.2.2] - 2026-10-27

Changed

• Calibrated Stagger Durations: Refined stagger recovery windows across creature tiers (Minor foes ~2.0s, Standard mobs ~2.75s, Heavy elites ~4.0s, Bosses full 5.0s, and Player 2.0s baseline).
• Combat Dossier Formatting: Streamlined weapon tooltip layout, attack profile headers, and keybinding prompt clarity.

[0.2.1] - 2026-10-25

Fixed

• Fixed critical game startup error triggered by cooking station drop yield telemetry registration.

[0.2.0] - 2026-10-25

Added

• Universal Poise & Boss Stagger Engine: Continuous poise accumulation, uniform stagger duration, and overhead stagger meters, enabling full stagger stuns against all world bosses and giants.
• Economic Yield Engine: Configurable gathering, mining, woodcutting, cooking, and crafting bonus yield mechanics with detailed logging receipts.
• Physical Triad Calibration: Scaled Slash Bleed to 35% of post-mitigation damage, Melee Pierce Precision to +25%, and decoupled enemy physical attack stagger buildup.

Changed

• Default cleave mode changed from Continuous to Geometric.

[0.1.0] - 2026-10-25

Added

• 6-Phase Combat Pipeline: Modular damage processing framework (PreCheck, AttackerModifiers, TargetDefenses, Mitigation, Execution, PostHitProcs) supporting multi-target cleave, armor penetration, and continuous resistances.
• Universal Poise & Boss Stagger Engine: Continuous poise accumulation, uniform stagger duration, and overhead stagger meters, enabling full stagger stuns against all world bosses and giants.
• Dual-Space 3-Tier Stat Architecture: Standardized mathematical engine evaluating character stats across 90+ tokens using flat bases, additive percentages, and compounding multipliers with asymptotic stamina efficiencies.
• Multi-Slice Status Effect System: Dynamic status effect architecture supporting severity-gated bleed refresh, DPS rate bounds, duration-first absorption shields, and automated stat scaling.
• Economic Yield & Environmental Engine: Configurable gathering, mining, and woodcutting drop scaling, plus detection utilities for felled logs.
• Network Serialization Protocol: Robust binary protocol maintaining byte symmetry and save-file safety for custom combat data over RPCs.