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.
• Use vanilla spells with the mod installed only on your client; installing it on the server is optional.
• 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.
• Built-in, configurable right-click Protection/Trollstav casting; no MagicTweaks installation needed.
• Four optional custom spell modes on Numpad +, including wisp lights, lightning, telekinesis and native Protection.
• Original staffs remain unchanged and fully usable.

Important release status

Version 0.6.0 targets Valheim 1.0.12 and requires Jotunn 2.30.0 or later on installations using the mod. Custom spells are Off by default and require server permission in multiplayer. Built-in native alternate casting, client-only vanilla spells, recorded levels, bindings, transparent inventory icon and held model are retained.

This is a release candidate for Valheim 1.0.12, BepInEx 5.4.23.5 and Jotunn 2.30.0. Automated checks cover service behavior and binary API compatibility; they do not launch Valheim. The new custom effects, collision physics, shield absorption, resource use and real multiplayer still require in-game testing. Earlier Protection/summon runtime checks also remain outstanding. See TEST_REPORT.md and the source archive's docs/RUNTIME_TEST_MATRIX.md.

Existing native selections, unlocks, recorded staff levels and configured keys are preserved. Update participating Universal Wand installations to 0.6.x; unmodded installations may remain unmodded for vanilla spells.

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 +	Cycle enabled custom spells in the order below

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, followed by Enter, then Plus; 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 resolved, network-supported native staff 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. It cannot bypass the custom-spell master setting or enable Fracturing variants on a server without their mod.

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.

Custom Added Spells

In BepInEx/config/com.universalwand.valheim.cfg, set:

[Custom Spells]
Custom Added Spells = On

The default is Off. In a local world, you choose. On a server running Universal Wand, the server's setting governs every modded client. On a server without Universal Wand, custom spells are always locked Off, regardless of a client's saved preference. An unconfirmed or lost server permission also means Off. The testing unlock switch does not override this rule.

All four modes become available together when enabled; there are no new staff items or staff-level unlocks for these custom spells. Numpad + (Custom Spells Key) cycles in this exact order, then returns to Spirit Orb:

Order	Mode	Primary attack	Secondary attack	Hold Block
1	Spirit Orb	Fire a fast Spirit/Lightning projectile; hold to repeat	Native Staff of Protection	Normal blocking
2	Lumos	Throw a wisp-like light forward	Place light at the tip's position when clicked	Normal blocking
3	Lightning Strike	Call lightning at the aimed location	Native Staff of Protection	Normal blocking
4	Telekinesis	Violently throw the held or aimed target	Acquire; hold to raise; quick tap while held to release	Pull the held target toward you

These use Valheim's configured Primary Attack, Secondary Attack and Block actions, including controller bindings. Primary is normally left-click; secondary and block are separate actions. There are no separate Levitate/In-Out/Expulsion cycle entries. Select an unlocked native staff with its normal number/Enter key to leave custom casting. Pressing a locked native key retains the custom mode. Custom selection is remembered per wand for the current session; native selection/progression remains saved normally. The custom Lightning Strike is separate from the vanilla Deep North staff selected through Enter. Fallen Valkyrie Fire is not included.

Lumos: a free wisp-like light follows the tip while the mode is equipped. Each thrown/placed light lasts exactly 30 seconds and remains after switching spells or putting the wand away. The passive tip light disappears on switch/unequip. Thrown lights slow to a hover and stop on collision. These lights illuminate; they do not clear Mistlands mist. Up to 12 detached lights per caster and 64 total are kept; the oldest is replaced if necessary.

Lightning Strike: thick, bright emissive cores have soft colored glow and thin branching bolts attached along their paths. The glow is rendered directly; enabled bloom can enhance it. The orbital targeting circle starts immediately. At 0.50 seconds, purple lightning gathers high overhead toward the strike axis, styled after Mistlands lightning. A bright blue bolt travels downward from 1.05 seconds and hits at 1.15 seconds. Red lightning then rises from the ground at 1.20 seconds; the effect fades by 2.05 seconds. Damage is applied once, at the blue impact. Aim range remains 80 m and damage radius 6 m.

Telekinesis: secondary attack acquires a target. It follows your movement and aim at a retained distance, with normal physical smoothing and collisions. Looking around, up or down steers it; moving your body carries the target along. Hold secondary to raise it, and release that button to keep it hovering/following. Holding Block pulls it closer at 6 m/s, down to 2.5 m. Raising moves at 3 m/s along the retained radius, up to 25° above your aim to keep it in view; looking up/down moves it further with your gaze. While already holding a target, a secondary tap shorter than 0.20 seconds releases it with its current motion, letting a swing become a natural fling. Primary attack remains the stronger immediate 32 m/s expulsion.

Switching modes or putting the wand away releases the hold. Ordinary hostile creatures, dropped items and dynamic logs remain eligible; players, bosses, tamed allies, buildings, ships and carts are excluded. Objects cannot be teleported through obstacles. Excessive separation or an obstructed/invalid hold is released. Physical flings and powered throws can damage both health-bearing targets and struck trees through the native impact path; a dropped inventory item has no artificial health. Existing damage caps, native ownership, access checks and cleanup remain.

Native Protection: replaces the disabled blue forward shield for Spirit Orb/Lightning secondary attack. It requires Protection's own unlock and uses its highest recorded source-staff level, complete native data, costs, Blood Magic scaling, status effect and networking. It preserves your custom selection and does not depend on the native alternate-casting toggle. Locked or unavailable Protection cancels the attempt without firing the last selected staff. No additional shield is manually applied.

Spirit Orb sound: each accepted cast plays one short, quiet positional magic pulse. It uses a suitable native Frost firing clip when available, otherwise a soft synthesized airy sound. Projectile damage, speed and casting cost are unchanged.

Initial balance values:

Action	Eitr	Timing / strength
Spirit Orb	6	0.2 s cadence; 45 m/s; 80 Spirit + 20 Lightning before skill scaling
Throw/place light	2	30 s lifetime; 0.35 s cadence
Lightning Strike	80	5 s cooldown; impact at 1.15 s; 650 base Lightning before native Elemental Magic skill factor
Acquire levitation	10	2 Eitr/s upkeep; 2.5–28 m holding distance
Pull with Block	Upkeep only	6 m/s inward movement
Expulsion	15	32 m/s launch; speed-based collision damage
Protection alternate	Native cost	Native Protection timing/strength at its recorded level

Custom attack damage uses native damage/resistance processing. Spirit damage can be resisted by living enemies, so Spirit Orb's effect varies by target. Values are initial tuning, not measured in-game balance. Costs and cooldowns are currently fixed; the config provides the master toggle and cycle key. Vanilla staff spells continue using their separately recorded source levels.

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.

On a remote server, the three custom variants are available only when Jotunn confirms Staffs of Fracturing is installed on that server. Otherwise they are skipped, including with the testing override enabled. Their saved unlocks and levels remain intact. Vanilla Fracturing still works client-side. Universal Wand does not change the other mod's own connection requirements.

Built-in alternate casting

Built-in alternate casting inspired by MagicTweaks by Gaakrin.

The feature is enabled by default through [Casting] Enable Alternate Casting = true. It works with MagicTweaks absent and affects only the Universal Wand's native staff modes. Custom modes use their own controls above.

Selected spell	Left-click	Right-click with alternate casting enabled
Dead Raiser	Dead Raiser: skeletons	Trollstav
Any other native staff mode	The selected spell	Staff of Protection

The alternate source must already be unlocked by that character and available under the normal network policy. Its own highest recorded source-staff level is used, independently of the selected spell and physical wand quality. A locked alternate displays only Not yet unlocked., consumes no resources, and leaves the selected spell unchanged. Set [Casting] Enable Alternate Casting = false to use the selected source spell's normal native secondary attack instead. Left-click always retains the selected spell.

Right-click uses the alternate staff's complete native item data and runs its primary attack through the wand's secondary slot. Protection retains its shield effect, Blood Magic skill scaling and native costs; Trollstav retains its native summon data, health/Eitr costs and restrictions. The existing cast-quality lease and delayed-effect snapshots preserve the alternate's recorded level through completion. Universal Wand does not manually apply a second shield or spawn an extra summon.

Remove broken MagicTweaks installations

For the intended setup, remove MagicTweaks 1.0.0 from each affected client/server mod profile and restart those game/server processes. Universal Wand does not require or bundle it. Its former casting integration and soft dependency have been removed; plugin detection now provides a compatibility notice only.

Making the wand independent cannot stop a separately installed MagicTweaks DLL's global attack patch from throwing errors. If Universal Wand detects it, the startup log explains this conflict and the removal/restart step. Universal Wand does not disable or patch that separate DLL.

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 native staff 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 built-in alternate cast, a fresh temporary wand-owned view keeps the complete target spell 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 server does not need Universal Wand for the twelve vanilla spells. The client sends the selected vanilla staff's equipment identity and uses native projectile, damage, status and summon networking. Custom spells require Universal Wand 0.6.x on the caster and server, with the server master setting On. Modded peers receive their visual effects; unmodded observers can receive native damage/physics results but cannot render the custom artwork. New observers do not receive snapshots of custom effects already in flight.

Installation	What happens
Only the wand user's client has Universal Wand	The user sees the wand and can select unlocked vanilla spells. Other clients see the selected vanilla staff.
Other clients also have Universal Wand	They see the wand through its visual marker, even if the server lacks Universal Wand.
Server also has Universal Wand	The same format works; clients without Universal Wand can still connect.

Installing the mod only on the server cannot give unmodded clients its custom model or controls. Each viewer needs Universal Wand to render the wand. Other installed mods may have their own connection requirements.

Universal Wand declares Jotunn VersionCheckOnly with Minor version strictness: absence is allowed, while installations on both ends must have compatible versions. Update participating modded clients and servers to 0.6.x together.

Saved and dropped items

The persistent item uses the vanilla Staff of Embers prefab plus an ordinary custom-data marker. Modded clients restore the wand's name, icon, stats and selection when loading inventories or drops. Unmodded clients see a Staff of Embers in storage, drops and trades; ordinary item stands also use that vanilla appearance. While a modded player holds the wand, equipment updates show unmodded viewers the selected staff instead. The marker itself never grants an Embers unlock.

Removing Universal Wand leaves a usable vanilla Staff of Embers in place of the wand. Reinstalling restores it if its custom data was preserved. Character spell unlocks remain separate and are not transferred with the item.

Old custom-prefab wands must be loaded and saved once with 0.3.0 before removing the mod from an existing world. Load old containers and dropped wands as well as the character inventory; an unmodded game cannot migrate old records that still require the former custom prefab.

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.

MagicTweaks detection uses plugin GUID gaakrin.magictweaks only to issue a compatibility notice. The published MagicTweaks 1.0.0 DLL contains a global attack helper that calls a status-effect API signature absent from the inspected Valheim 1.0.12 API. Remove that separate mod and restart; its errors are not fixed by Universal Wand's independent alternate casting. No MagicTweaks assembly reference, dependency, code or assets are bundled.

Staffs of Fracturing remains an optional integration; its own Valheim 1.0 runtime compatibility was not verified here. Use a version that works 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.