Blood Magic Companion

Five configurable Blood Magic changes in one Valheim mod:

• Stamina-powered casting: replace eitr with fixed stamina costs, scaled by Blood Magic skill, while preserving the original health cost.

• Caster shield XP: credit Staff of Protection shield-break XP to the caster when the computer processing the break and the caster support the feature.

• Optional skeleton training: summoned melee and archer skeletons can target T.W.I.G.; disabled by default.

• Optional skeleton lava immunity: protect summoned melee and archer skeletons from lava damage and lava-applied burning; disabled by default.

• Optional Trollstav XP: summoned troll damage to enemies can award Blood Magic XP to the original caster; disabled by default.

All features can be switched off independently. One DLL, one configuration file.

Status: experimental release 1.4.1. Compiled against Valheim 1.0.17 and BepInExPack 5.4.2350. All 349 executable assertions, 144 static assertions and six installed-prefab comparisons pass; see docs/VALIDATION.md. Actual casting and multiplayer remain unverified. The default conversion rate is a starting point for balancing, not a claim of equivalence to vanilla eitr.

Install and upgrade

Use r2modman or Thunderstore Mod Manager with BepInExPack_Valheim 5.4.2350 or newer. The 1.4.1 installable ZIPs are built and checked. After the public package is published, update the existing qwertyzxcv-BloodMagicCompanion package, then launch with Start modded. For a local ZIP, use Settings → Profile → Import local mod and select LocalMods-BloodMagicCompanion-1.4.1.zip. Avoid enabling both a local import and the public package at once.

For manual installation, replace BloodMagicCompanion.dll inside BepInEx/plugins with the new DLL. Keep only one copy. Close Valheim before updating.

Remove or disable both standalone predecessors: BloodMagicCasterXP and BloodMagicHealthCost. The combined plugin declares those IDs incompatible to avoid double patches.

After the first launch, edit BepInEx/config/local.valheim.bloodmagiccompanion.cfg through the mod manager's Config editor. Restart to apply settings.

Upgrading from 1.0.0 changes casting balance: the extra health payment is replaced by stamina. The original health cost is restored. If the old HealthCosts/Enabled setting was false, it seeds StaminaCosts/Enabled=false when the new setting is first created. An existing StaminaCosts/Enabled always takes precedence. Other old HealthCosts settings are ignored; configure the new StaminaCosts section instead. Old per-staff health multipliers are not copied because the units and meaning changed. CasterXP and Logging settings are retained.

Stamina and health costs

At the defaults, each point of base eitr becomes 1 stamina, discounted once by Blood Magic skill: 0% at skill 0, 16.5% at skill 50, and 33% at skill 100.

converted stamina = base eitr × StaminaPerEitr × item multiplier
                    × (1 − CostReductionAtSkill100 × skill level / 100)
total stamina = max(0, native stamina cost) + converted stamina

Skill is clamped to levels 0–100. Primary and secondary attacks use their own base eitr fields. Any original stamina cost retains its native modifiers and is added separately. Equipment and status-effect stamina discounts do not reduce the converted surcharge. A negative native stamina refund cannot cancel the surcharge.

These are conversion examples; each attack uses its actual configured base eitr cost.

Health remains vanilla. Original flat health plus the percentage of current health, its native skill discount, eligibility checks, and payment cap are unchanged. There is no extra health payment and no new health threshold. The conversion does not scale with current or maximum health.

Enough stamina is required. Native attack-start checks use the total stamina cost (including the game's small 0.1 stamina start margin). Spending down to zero does not make casting free. Native per-burst checks also apply, so a burst attack stops when it cannot afford another burst. The game controls deduction timing; this mod does not reserve stamina during wind-up or add a separate payment.

The tooltip shows the additional converted stamina, including current Blood Magic skill. It is added to any native stamina cost shown elsewhere. Eitr becomes zero; normal materials, ammunition, durability, and other conditions still apply.

Applies only to the owning local player's Blood Magic attacks with positive base eitr cost. Self-killing attacks and already zero-eitr attacks are excluded. Elemental magic, melee, creature attacks, shield strength, and summon behavior are unchanged by the stamina feature.

Removing eitr also removes its food requirement. Pre-casting shields or summons and recovering stamina remains possible. This is a configurable alternative balance model, not vanilla difficulty parity.

Caster shield XP and multiplayer

XP is awarded when damage breaks a Staff of Protection shield, not on cast, every hit, or ordinary expiry. The original XP factor and vanilla skill-reward call are preserved. A refreshed shield is attributed to its latest tracked caster. Skeleton attack XP, shield strength, duration, and which targets can receive shields are unchanged.

The server and other players may remain unmodded. This does not mean all remote shields can be corrected by one modded client.

The computer simulating a creature can change; summoning it does not guarantee that your client always controls it. A modded server cannot fix a break processed by an unmodded client.

The XP protocol intentionally matches BloodMagicCasterXP 1.2.1. A friend using that standalone version can exchange XP messages with this combined mod, though this interoperability has not been tested live. Do not install both on the same client. Standalone 1.0/1.1 or unknown protocols use vanilla fallback.

Capability is advertised only while caster XP is enabled. No mandatory-mod network handshake, forced version matching, or mod-version kick is added. Targeted remote rewards require known current ownership; disconnects, respawns, ownership transitions, or missing network data may drop rewards. There is no offline queue or delivery retry. Receipts have bounded duplicate protection; this is a cooperative mod, not an anti-cheat system. Other mods replacing shield, cost, or network methods may interfere.

Summoned skeletons and T.W.I.G.

Upgrade from 1.2.0: that version incorrectly required the PlayerSpawned faction and excluded vanilla summoned skeletons. Version 1.2.1 fixes this using the actual Players faction. Your existing AttackTrainingDummy setting is retained.

To enable training, set this in the config and restart:

[Summons]
AttackTrainingDummy = true

The default is false, preserving vanilla AI. With it enabled, tamed Skeleton_Friendly summons can select the nearest visible living T.W.I.G. when vanilla finds no ordinary enemy. An existing living ordinary target also takes priority. The feature covers both melee and archer equipment.

T.W.I.G. normally skips enemy selection, and its building-layer body can block the character visibility ray. This feature provides a skeleton-only fallback target and ignores only the selected dummy's own colliders for that ray. Other buildings, terrain, mist, view range, view angle, attack range, cooldowns, pathing and the native follow/patrol leash remain in effect. It does not change attack damage or XP amounts. Enabling it can make repeated training easier.

Only the computer currently simulating the skeleton applies this behavior. That computer must run this version with the setting enabled. A client-only installation works for skeletons owned by that client; behavior returns to vanilla if ownership moves to an unmodded or disabled peer. No ownership is forced and no server installation, new network messages or mandatory-mod handshake is added. Other creatures and players retain their normal visibility behavior.

This feature has executable tests with simulated game/physics APIs and static installed-game checks, but has not been playtested in Unity or multiplayer.

Summoned skeletons and lava

Set this in the config and restart:

[Summons]
LavaDamageImmunity = true

Default false. When enabled, living tamed Skeleton_Friendly summons (both melee and archers) skip both stages of lava heat damage and the burning those stages apply. This is independent of training, casting costs and shield XP. Other creatures and players are unaffected.

Ordinary fire attacks, already-active Burning effects, boiling-ocean damage, other combat damage and the native summon lifetime remain. This does not change pathfinding, lava slowdown or terrain behavior: skeletons may still walk into lava, but the covered lava damage is skipped.

The computer currently simulating the skeleton must have this setting enabled. The server and other clients may remain unmodded, but protection stops if ownership moves to an unmodded or disabled computer. For protection across ownership transfers, enable it on every computer that may simulate the summons, including the server if it does so. The mod does not force ownership or require all peers to install it.

Offline branch and installed-game contract checks pass; actual Unity/Harmony loading and multiplayer lava survival still need playtesting.

Trollstav Blood Magic XP

Enable this and restart, then summon fresh trolls:

[TrollXP]
Enabled = true
Factor = 0.5

The toggle defaults to false and is independent of CasterXP, stamina conversion, training and lava protection. When enabled, a newly summoned Trollstav troll carries its original caster's identity. Successful health damage to enemies, including the arrival explosion when attributed to that troll, can award Blood Magic XP to that caster. Merely casting, misses, fully absorbed hits, players, tames, training dummies, the troll itself and scenery do not generate rewards. Ordinary wild trolls are excluded. Damage-over-time only qualifies if the game retains the tracked troll as attacker.

Factor is a skill-gain factor, not whole skill levels. Default 0.5 uses the same factor scale as vanilla skeleton rewards. Every qualifying damage event can award XP: hitting several enemies in one area attack or landing rapid successive hits can grant several rewards. There is no per-troll cooldown. Duplicate copies of the same network report are still rejected. The caster's Factor (0.01-10) applies; invalid values fall back to the default. The old MinimumInterval setting is ignored and may be removed from existing configuration files. Logging/Diagnostics logs tracking and successful local awards.

Multiplayer: the caster needs this enabled when summoning, and the computer processing the damaged enemy needs it enabled to report damage. This is the victim's simulation owner, which can differ from the troll's owner. XP is applied only on the actual caster's client, never on another computer's copy of that player. The server and other clients may remain unmodded, but damage processed by an unmodded or disabled peer produces no extra XP. There is no required-mod handshake. Ownership changes do not reassign the caster; missing/stale network data can drop reports. This cooperative protocol is not anti-cheat protection.

Existing trolls summoned before enabling/upgrading are untracked: summon new ones. Attribution uses the caster's current network character identity; after death, logout or a new session, resummon if that identity changes. The caster must be present and resolvable on the damage-processing computer. Troll hostility, damage, lifetime and targeting remain vanilla. This feature has not been playtested in Unity or multiplayer.

Configuration

File: local.valheim.bloodmagiccompanion.cfg. Settings apply at startup.

Example: StaminaPerEitr=0.75 changes a 60-eitr spell to 45 stamina before skill scaling. StaffShield=1.2 makes shield conversion 20% more expensive without changing its original health cost. Use decimal points. Invalid settings fall back to defaults or ignore invalid item entries with a warning.

HealthCosts/Enabled is retained only as a migration seed. To disable conversion now, use StaminaCosts/Enabled. There is no health-only mode in 1.4.1. All configuration is local; it is not enforced on friends.

Troubleshooting and removal

Check BepInEx/LogOutput.log for Blood Magic Companion 1.4.1 loaded and the feature states. If loading is rejected, remove the old standalone plugins. If patch installation fails, the mod removes its patches instead of leaving a partially enabled feature.

Report game and mod versions, relevant configuration, other combat mods, and which computer processed the shield break. Share only relevant log excerpts after removing personal information.

Disable or uninstall the mod and restart to remove it. Existing earned XP remains ordinary character progress. No coordinated server uninstall is required.

Source and validation

The source repository includes C# source, MIT licensing, build scripts, standalone tests, static validators, and an offline GitHub Actions workflow. Game assemblies and loader libraries are not redistributed. This mod was developed with AI assistance.

See docs/VALIDATION.md for the exact build and offline checks, and docs/TESTING.md for the unrun in-game acceptance plan. Offline tests do not prove Unity loading, multiplayer behavior, or balance.

Changelog

1.4.1

• Remove the Trollstav XP cooldown and MinimumInterval setting. Each qualifying damage event can award XP, including multiple enemies in one area attack and rapid successive hits.
• Keep duplicate network-report protection, caster attribution, eligibility checks and the configurable XP Factor. Existing MinimumInterval entries are ignored.
• Built and packaged against Valheim 1.0.17: 349 executable assertions, 144 static assertions and six installed-prefab comparisons pass. Unity and multiplayer verification remain pending.

1.4.0

• Add independent TrollXP/Enabled (default false), Factor (0.5) and MinimumInterval (1 second per troll).
• Track the caster at Trollstav summon time and reward actual health damage to enemies, including tracked arrival damage. Exclude players, tames, training dummies, scenery, misses and fully absorbed hits. Preserve troll combat behavior.
• Apply rewards only to the caster's local player, with capability-gated reports from the victim's current simulation owner, duplicate protection and a caster-side per-troll cooldown. Unmodded peers remain compatible but cannot report extra XP.
• Add policy regression tests and installed-game hook validation. Unity and multiplayer XP verification remain pending; resummon trolls after enabling/upgrading.

1.3.0

• Add independent Summons/LavaDamageImmunity, disabled by default. Enable and restart to protect summoned melee and archer skeletons from lava heat damage and lava-applied burning on their simulation owner.
• Preserve ordinary fire, boiling-ocean damage, summon lifetime, pathfinding and all other features. Mixed unmodded peers remain supported; protection requires the current simulation owner to enable it.
• Add 36 simulated lava eligibility and emitted-branch assertions plus installed-game contract validation. Live lava survival and multiplayer ownership-transfer testing remain pending.

1.2.1

• Fix T.W.I.G. training excluding vanilla summoned skeletons: Skeleton_Friendly uses faction Players (0), not PlayerSpawned (11).
• Keep the exact summon prefab, tame, ownership, life and dummy-only visibility restrictions.
• Extract a minimal test fixture from the installed game prefabs and add an asset-verification script. The new real-faction regression fails against 1.2.0 and passes with this correction.
• Preserve existing configuration; the fixed in-game behavior still requires live verification.

1.2.0

• Add opt-in Summons/AttackTrainingDummy for summoned melee and archer skeletons.
• Prefer ordinary enemies; allow a nearby visible T.W.I.G. as a fallback target.
• Exclude only the selected dummy's own colliders from the skeleton's visibility ray. Preserve other obstacles and native attack gates.
• Apply only on the skeleton's simulation owner, without requiring installation on other peers or changing ownership.
• Default remains off. Built against Valheim 1.0.17; live gameplay remains untested.

1.1.0

• Replace converted eitr health payments with fixed stamina costs; original health cost and its native skill scaling remain unchanged.
• Default conversion: 1 stamina per base eitr, reduced once by Blood Magic skill (33% at level 100).
• Use native stamina checks and deductions, including per-burst checks; no free casting when exhausted.
• Add StaminaCosts settings for enabling conversion, conversion rate, skill discount, per-staff multipliers, and tooltips.
• Retain an explicit old HealthCosts/Enabled=false as the initial new enable setting. Old health balance settings are ignored.
• Preserve caster shield XP behavior and protocol, optional server installation, and mixed-client fallback.

1.0.0

First combined release, incorporating BloodMagicCasterXP 1.2.0 and BloodMagicHealthCost 1.1.0 into one plugin.

• Independent health-only casting and caster-shield-XP switches in one configuration file.
• Both health percentage portions scale with current health; the entire cost scales with skill. No added low-health casting threshold.
• Preserve XP protocol 3 for compatibility with peers using BloodMagicCasterXP 1.2.0.
• Optional server and other-client installation, with explicit mixed-client reward limitations.
• Prevent loading alongside either standalone predecessor on the same computer.
• Include source, standalone regression checks, static validators, and documented build steps.

Experimental: no in-game or multiplayer playtest has been completed for this combined release.