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.

[!WARNING] Work in Progress (Pre-Release v0.1.0): 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.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 independent slices, duration-first absorption shields, and automated stat scaling.
• Economic Yield Engine: Configurable gathering, mining, woodcutting, cooking, and crafting bonus yield mechanics with detailed logging receipts.
• Network Serialization Protocol: Robust binary protocol maintaining byte symmetry and save-file safety for custom combat data over RPCs.