Universal Wand

One wand. Every staff.

• Switch between twelve vanilla magic weapons, including the four Deep North staffs, with configurable Numpad hotkeys.
• Keep one Universal Wand equipped while changing spells instantly.
• Unlock each spell by acquiring, crafting, upgrading, or successfully casting its original staff.
• Preserve the highest source-staff level reached for every spell.
• Optionally cycle through all three Staffs of Fracturing variants.
• Optionally inherit MagicTweaks right-click Protection/Trollstav casting.
• Original staffs remain unchanged and fully usable.

Important release status

Version 0.2.0 targets Valheim 1.0.12 and requires Jotunn 2.30.0 or later. It preserves the 0.1.6 selection fixes, adds the four Deep North staffs, and uses public game APIs for equipment access. It also preserves spell level and casting data for delayed projectiles/summons, and protects the physical wand level during saves and inventory cloning.

This remains a release candidate, compiled against the supplied, unmodified Valheim 1.0.12 game/Unity assemblies, BepInEx core and Jotunn 2.30.0. Automated checks cover service behavior and binary API compatibility; they do not launch Valheim. In-game spell, crafting, multiplayer and optional-mod retests remain required.

Existing selections, unlocks, recorded staff levels and configured keys are preserved. The new shortcut is additive. Do not mix the 0.1.x and 0.2.x releases across a server and its clients.

Controls

Key	Spell
Numpad 0	Staff of Protection
Numpad 1	Staff of Frost
Numpad 2	Staff of Embers
Numpad 3	Fracturing family; press repeatedly to cycle
Numpad 4	Dundr
Numpad 5	Staff of the Wild
Numpad 6	Unassigned/reserved
Numpad 7	Unassigned/reserved
Numpad 8	Dead Raiser
Numpad 9	Trollstav
Numpad Enter	Cycle unlocked Deep North staffs

Numpad Enter cycles Echo Spike, Spirit Caller, Northern Vengeance, and Lightning Strike in that order. Locked or unavailable entries are skipped. If none are unlocked, it only displays Not yet unlocked.. Each source staff records its own highest level using the same progression rules as the original eight. The configurable setting is Extra Spells Key; reserved slots 6 and 7 remain available for future use.

Every shortcut is a configurable BepInEx KeyboardShortcut, but gameplay polling uses UnityInput.Current and checks only its main key and intentionally configured modifiers. Both supported Unity input backends are handled. Holding movement, sprint, dodge, or another unrelated gameplay key does not block a spell switch. Set a shortcut to None to unbind it. If shortcuts conflict, the lowest mapped number wins; direct slots take precedence over the extra-spell shortcut, and a warning is logged.

Config entries use staff names such as Staff of Embers Key instead of Slot 2. Existing Slot 0–Slot 9 values migrate automatically and the old entries are removed.

Input is accepted only while the local player has the wand equipped and Valheim allows gameplay input. Typing, menus, inventory/crafting, console, and compatible configuration UI block selection.

Temporary testing option

Set [Testing] Unlock All Spells = true to make every currently resolved wand mode available at level 1. A legitimately recorded higher source level remains higher. This override is live, does not write fake character progression, and can be disabled without changing real unlocks.

Use it to isolate failures:

• If every Numpad key selects and casts a different spell while enabled, input/casting works and remaining trouble is in progression detection.
• If a named selection message appears but the spell cannot be applied, the HUD says Spell source unavailable. and the log identifies that exact source.
• If no message appears, check BepInEx/LogOutput.log for Universal Wand spell selection failed. A runtime input failure is distinct from a key not being detected or Valheim blocking input while a menu is open.

Optional Staffs of Fracturing support

When L4zerShark_Team-StaffsOfFracturing-1.0.0 is installed, repeated presses of the Fracturing shortcut cycle in this stable order:

1. Staff of Fracturing
2. Iolite Staff of Fracturing
3. Jade Staff of Fracturing
4. Bloodstone Staff of Fracturing

Unavailable or locked variants are skipped. Each variant unlocks separately when that character acquires, crafts, upgrades, or successfully casts its corresponding original staff. A locked selection still displays only Not yet unlocked.

Staffs of Fracturing is an optional integration, not a hard dependency. If it is absent, Numpad 3 selects normal vanilla Fracturing and every other wand mode continues working. If it is installed, install the same compatible Staffs of Fracturing version on the server and every client as required by that mod.

Optional MagicTweaks support

When Gaakrin-MagicTweaks-1.0.0 is installed, right-clicking the Universal Wand follows MagicTweaks' alternate-cast layout:

• Dead Raiser selected: cast Trollstav.
• Any other selected mode: cast Staff of Protection.

The alternate source must already be unlocked by that character. Its highest recorded source-staff level is used for the complete alternate cast. A locked alternate displays only Not yet unlocked. and does not cast. MagicTweaks remains optional and is not listed as a required Thunderstore dependency; if installed, use it on the same clients/server where its normal behavior is expected.

Unlock progression

A mode permanently unlocks for that character once the corresponding source magic weapon is observed in that character's inventory. This covers:

1. already-owned or newly picked-up staffs,
2. completed crafts and upgrades, and
3. staffs equipped and used normally.

Inventory ownership is checked every 0.75 seconds without patching Valheim's crafting methods. Prefab identity is used first, followed by stable live source name/attack identity for cloned or rewritten item instances. The existing fail-open Humanoid.StartAttack boundary also records an equipped original staff immediately before returning it untouched to Valheim. Progression lives in versioned character custom data, not on the wand, so trading a wand never transfers it.

The recorded value for each spell is the highest source-staff quality that character has ever possessed, crafted, upgraded, or successfully used. Acquiring level 3 after level 1 upgrades the wand's matching spell to level 3; later seeing a lower-level copy never downgrades it. Older Boolean unlock records migrate safely as level 1. Pressing a locked key leaves the current mode unchanged and displays only Not yet unlocked. to avoid automatic spoilers.

The attack boundary records Valheim's current weapon immediately; the periodic inventory scan also covers owned items that are not currently selected. These use the public Valheim 1.0 APIs without reaching into private equipment fields.

How casting works

The mod does not swap inventory items and does not reimplement vanilla or Staffs of Fracturing spell logic. Each mode creates a wand-owned shallow casting view from the live registered source weapon. Only when the Universal Wand starts an attack, it temporarily reports that spell's recorded source-staff quality for the complete cast—including delayed projectile bursts—and restores its own quality when the attack finishes or fails. Swords, original staffs, crafting, and every non-wand item bypass this state completely. Valheim's native attack pipeline supplies:

• Eitr or Blood Magic health costs
• attacks, reload/channel timing, skill selection and gain
• quality-scaled damage and item level, projectiles, status effects, targeting, ownership and friendliness
• shields, summons, summon caps, location restrictions and cooldowns

No source SharedData, attack, prefab, model, or recipe is modified. A switch requested during an active attack is queued until the attack ends. During a MagicTweaks alternate cast, a fresh temporary wand-owned view keeps the other mod's live secondary attack intact until Valheim finishes that attack.

Projectiles, area effects and delayed summon abilities receive a snapshot of the wand's casting data and spell level. Finishing the animation or selecting another mode cannot change that snapshot. Saving or dropping a wand during a cast retains the physical wand's own level. Original staffs and ordinary item saves/clones pass through unchanged.

Item and recipe

The wand has qualities 1–4, 200 base durability, and +50 durability per quality. Its held model is a very small, straight, three-sided wooden stick: half the previous dimensions, with the wooden base at the hand attachment point and no permanent orb or strange tip geometry. A brief simple cyan switch flash may appear at the otherwise plain end. It intentionally retains the two-handed staff animation/restriction family and no-shield balance.

Craft at a Galdr table:

Material	Quality 1	Per upgrade level
Yggdrasil wood	20	5
Refined eitr	30	10
Black core	5	2
Red gemstone	2	1

The station requirement starts at level 1 and rises with item quality, making quality 4 require a level-4 Galdr table.

Multiplayer and installation

Install the release ZIP with a Thunderstore-compatible mod manager, or replace UniversalWand.dll in BepInEx/plugins/UniversalWand/. BepInExPack Valheim 5.4.2350 and Jotunn 2.30.0 or later are required. Keep only one installed Universal Wand DLL.

The mod declares Jotunn EveryoneMustHaveMod compatibility with Minor version strictness. Install the same compatible version on the dedicated/listen server and every player client. Mixed modded/unmodded play is rejected instead of allowing unknown custom items or half-working casts. Unmodded console/crossplay clients are therefore unsupported on a server running this mod.

Selection/HUD/VFX are local. Actual casts use vanilla projectile, damage, status and summon networking paths. This is consistent with Valheim's normal trusted mod environment; it is not advertised as an anti-cheat system.

Compatibility notes

Source weapons are resolved after vanilla and normal mod item registration. Rebalances already present at that point are inherited. A mod that mutates source attacks later at runtime may need an explicit adapter. Missing/renamed prefabs disable only the affected mode and log once.

The optional Staffs of Fracturing 1.0.0 adapter was verified against plugin GUID com.l4zershark.staffsoffracturing and the three registered item prefabs in the supplied release DLL. Compatibility uses only stable IDs and live source data; Universal Wand does not compile against, bundle, or modify the other mod's assembly.

The optional MagicTweaks 1.0.0 adapter was verified against plugin GUID gaakrin.magictweaks and its published implementation. Universal Wand reads the secondary attacks that MagicTweaks has already attached to the live vanilla source data; it does not reference, bundle, modify, or reproduce MagicTweaks code.

Those optional integrations remain available, but their own Valheim 1.0 runtime compatibility was not verified here. Use versions of those mods that work on your current game.

The Deep North staff identifiers were checked against Jotunn's generated prefab list. Source attacks and effects are obtained from the installed game at runtime.

See TEST_REPORT.md for completed and outstanding verification.