ValheimWeaponClasses - Developer README

1. Overview

ValheimWeaponClasses is a Valheim mod (BepInEx plugin, built on the Jotunn modding library) that adds a craftable "Class Obelisk" piece. A player interacts with the Obelisk to choose one of 8 combat classes:

SwordMaster, Archer, Crusher, Assassin, Brawler, Wizard, Lancer, Bulwark

Each class deals bonus damage with its associated weapon type and gains XP from combat. Classes level from 1 to 50, unlocking a passive perk every 10 levels (10 / 20 / 30 / 40 / 50).

Plugin identity (BepInEx):

2. Requirements / Dependencies

• .NET Framework 4.7.2
• BepInEx + 0Harmony (referenced from the local Steam Valheim install)
• Jotunn (declared as a hard dependency via [BepInDependency(Jotunn.Main.ModGuid)]) — used for prefab cloning, the piece/build system, and all custom GUI (the class-selection window)

The .csproj references game/BepInEx/Jotunn DLLs via HintPaths pointing at a local Steam install (Program Files (x86)\Steam\steamapps\common\Valheim\...). If you're setting this up on a new machine, update those HintPaths (or your Steam install path) if the build fails to find references.

3. Project Layout

ClassObeliskMod.cs          Plugin entry point (BaseUnityPlugin). Creates the
                             Obelisk piece and contains the entire class-
                             selection GUI (built with Jotunn's GUIManager).

Utilities/
    PlayerClass.cs             The PlayerClass enum + PlayerClassHelper
                                (display names, internal names, weapon-type
                                lookups).
    PlayerClassManager.cs      Per-player class data (PlayerClassData) and
                                the static registry (PlayerClassManager).
                                Also contains the Save/Load Harmony patches.
    ClassCombatManager.cs      Weapon-type detection (is this a sword? a
                                bow? etc.) and class damage multipliers.
    ClassDamageBonusSystem.cs  Generic per-level damage bonus (separate
                                from ClassCombatManager - see section 5).
    XPSystemManager.cs         XP awarding, leveling curve, and the Harmony
                                patches that hook combat events for XP.
    AnimationSpeedManager.cs   Reusable stacking multiplier utility for
                                attack/animation speed (used by some perks).
    SEUtils.cs                 Helpers for inspecting vanilla StatusEffects
                                (poison/burning/frost stacks, timers, etc.)

PerkManagers/                One file per class, each implementing that
                             class's level 10/20/30/40/50 passive perks
                             (SwordMasterPerkManager.cs, ArcherPerkManager.cs,
                             CrusherPerkManager.cs, AssassinPerkManager.cs,
                             BrawlerPerkManager.cs, WizardPerkManager.cs,
                             LancerPerkManager.cs, BulwarkPerkManager.cs).
                             This is where you go to add or tune a specific
                             class's abilities.

TestingResources/            Debug-only console commands (API discovery,
                             bow testing, general debug utilities). Not part
                             of the intended production feature set.

Resources/Icons/             Embedded .rgba icon assets used by some perk
                             status effects.

4. How Class Selection Works

1. The player crafts the Class Obelisk with a Hammer. It's built by cloning the vanilla piece_workbench prefab and stripping its CraftingStation component, so it's purely an interactable piece, not a crafting station (see ClassObeliskMod.AddClassObelisk / CreateClassObeliskPrefab).

2. Interacting with it (E) calls ClassObeliskInteract.Interact, which opens a class-selection window built entirely with Jotunn's GUIManager (no Unity prefab/asset UI) - a grid of class buttons, a description panel populated from the hardcoded ClassDescriptions dictionary in ClassObeliskMod.cs, and a "Select Class" button.

3. Clicking "Select Class" calls:

   PlayerClassManager.SetPlayerActiveClass(player, className)
   

   which resolves the class and calls PlayerClassData.SetActiveClass, replacing any currently active class - by default only one class can be active at a time.

Note: PlayerClassData.CanSelectSecondClass() returns true once any class reaches level 50, implying a second, simultaneously-active class is intended at that point. The selection GUI currently always calls the single-class "replace" path rather than an "add second class" path, so dual-classing appears to be a planned but not fully wired-up feature.

5. Where Class Settings Live

There is no external data file (no JSON/YAML) for class definitions - everything is hardcoded in C#:

• Utilities/PlayerClass.cs — the PlayerClass enum (the 8 classes) plus PlayerClassHelper, which maps each class to a display name, an internal/save name, and a weapon-type description.
• ClassObeliskMod.cs (ClassDescriptions dictionary) — flavor-text descriptions of each class's perks, shown in the selection GUI. This is display text only, not mechanics.
• Utilities/ClassCombatManager.cs — weapon-type detection (IsSwordWeapon, IsBowWeapon, IsBluntWeapon, IsKnifeWeapon, IsSpearWeapon, IsUnarmedAttack, IsMagicWeapon - mostly string-matching on weapon names) plus GetClassDamageMultiplier. Used both to gate XP eligibility and to apply combat damage bonuses.
• Utilities/ClassDamageBonusSystem.cs — a generic, class-agnostic damage bonus that scales with level (0.5% per level, capped at 25% at level 50), applied when the equipped weapon matches the active class's weapon type.

  Note: this appears to overlap with the multiplier logic in ClassCombatManager - both patch Character.Damage. Worth reconciling if you're touching damage math, so bonuses don't double up unexpectedly.

• PerkManagers/*.cs — the actual mechanical implementation of each class's Lv10/20/30/40/50 perks (buffs, status effects, stamina discounts, stagger, etc). This is the primary place to add new perks or rebalance existing ones.
• Config — only one BepInEx config value exists: EnableMod (bool, default true), bound in ClassObeliskMod.Awake(). All other balance numbers (damage bonus per level, XP rates, perk thresholds/durations) are plain C# constants scattered across ClassDamageBonusSystem.cs, XPSystemManager.cs, and the individual PerkManagers - there's no config file for tuning them outside of code changes (aside from a couple of values adjustable at runtime via the xprates debug command, which are not persisted).

6. Player Data & Persistence

• PlayerClassData (Utilities/PlayerClassManager.cs) is the per-player state container: class levels, XP per class, currently active class(es), and per-class "unlocked" flags.

  Note: classUnlocked currently initializes every class as unlocked ("All unlocked for testing") - unlock-gating isn't actually enforced yet.

• PlayerClassManager holds a static in-memory dictionary, Dictionary<long, PlayerClassData>, keyed by the player's ID. This is populated lazily via PlayerClassManager.GetPlayerData(player).

• Persistence rides on the vanilla character save, not a separate file or the world save:

  • Player_Save_Patch (postfix on Player.Save) serializes PlayerClassData with Unity's JsonUtility and appends it to the character's ZPackage.
  • Player_Load_Patch (postfix on Player.Load) reads that trailing data back out (and safely no-ops for older/pre-mod character files).

  Practical effect: class progress travels with the player's character file, and is unaffected by which world/server they join.

Multiplayer caveat: there is no custom RPC/ZDO sync code anywhere in the mod. Class/level/XP state lives only in local memory on whichever machine computes it (client or dedicated server) and is not broadcast between peers. On a dedicated server with multiple simultaneous players this is a likely gap worth testing/hardening before relying on it in real multiplayer sessions.

7. Experience & Leveling

Core logic: Utilities/XPSystemManager.cs (ClassXPManager)

• Kill bonus XP — the sole XP source. Damage dealt to a creature by (possibly multiple) classes is tracked (no XP awarded for the damage itself); on the creature's death, a bonus XP pool (creature max health x KillBonusMultiplier) is split across the classes that contributed damage.
• These are hooked via Harmony on Character.Damage (post, for tracking only) and Character.OnDeath (XPTrackingPatches).
• Leveling curve — XPRequirements is a hardcoded cumulative XP table for levels 1-50 (a comment notes it was originally derived from an XP_To_Level.json reference file that is no longer present in the repo - the values are now inlined directly in code). XPCurveHelper exposes lookups for XP-required-per-level, cumulative XP, current level from XP, and progress (for UI bars).
• Max level is 50. Every 10 levels (10/20/30/40/50) unlocks a passive perk (implemented in the matching PerkManagers/*.cs file). Reaching level 50 on any class also unlocks a second active class slot (see section 4).

8. Harmony Patches at a Glance

All patches are discovered and applied with a single call in ClassObeliskMod.Awake(): new Harmony(PluginGUID).PatchAll().

9. Debug / Testing Commands

All of these are registered via Terminal.ConsoleCommand in Harmony postfixes on Terminal.InitTerminal, so they're available in the in-game console (backtick / F5, depending on your Valheim console keybind) any time the mod is loaded - there's no separate "debug build" flag. They exist purely for development and are not intended as production features.

9.1 Class progress & XP (Utilities/PlayerClassManager.cs, Utilities/XPSystemManager.cs)

9.2 Combat & damage bonuses (Utilities/ClassCombatManager.cs, Utilities/ClassDamageBonusSystem.cs)

Heads up: testdamage is registered twice - once in CombatDebugCommands (ClassCombatManager.cs) and once in DamageBonusCommands (ClassDamageBonusSystem.cs), with slightly different output. Because both patch classes run their InitTerminal postfix, only one registration will actually win at runtime (whichever Terminal.ConsoleCommand was added last for that name). If you're debugging damage math and the output looks wrong/stale, this collision is likely why - worth renaming one before relying on it.

9.3 Bow draw-duration testing (TestingResources/BowTestingCommands.cs)

There's a near-duplicate, simpler version of the multiplier command - test_draw_duration <multiplier> - in ApiDiscoveryCommands.cs (section 9.4); the two don't share state, so don't mix them in the same test session.

9.4 API / reflection discovery (TestingResources/ApiDiscoveryCommands.cs)

These exist to explore Valheim's internals (find the right field/method to Harmony-patch) without decompiling by hand. Run api_help in-game for a live summary.

9.5 General reflection dumps to file (TestingResources/ValheimDebugUtility.cs)

Unlike the commands above (which print to the in-game console), these write their results to text files so you can review large dumps outside the game - look under BepInEx's log/debug output path printed by debugpath.

9.6 Misc / sanity checks (ClassObeliskMod.cs)

10. Getting Started (Building the Mod)

1. Open ValheimWeaponClasses.sln in Visual Studio (or your preferred .NET Framework-capable IDE).
2. Confirm the HintPaths in ValheimWeaponClasses.csproj match your local Steam Valheim install (BepInEx core, Jotunn plugin folder, and the game's managed assemblies). Update them if your install path differs.
3. Ensure Jotunn is installed in your local Valheim BepInEx/plugins folder - it's a runtime dependency, not just a compile-time reference.
4. Build (Debug or Release).
5. Copy the resulting ValheimWeaponClasses.dll into your Valheim BepInEx/plugins folder to test in-game.