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.