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.
• Six optional custom spell modes on Numpad +, including wisp lights, lightning, telekinesis and a forward shield.
• Original staffs remain unchanged and fully usable.

Important release status

Version 0.4.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.4.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 six 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	Left-click	Right-click
1	Spirit Orb	Fire a fast Spirit/Lightning projectile; hold to repeat	Forward Shield
2	Magical Light	Throw a wisp-like light forward	Place a light at the wand tip's position when clicked
3	Lightning Strike	Call a powerful lightning strike at the aimed location	Forward Shield
4	Levitate	Lift/hold a target; click again to release	Release
5	In / Out	Hold to bring the held target toward you	Hold to move it away
6	Expulsion	Launch the held or aimed target	Release

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.

Magical Light: 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: blue and violet branches accompany the aimed strike. Red branches are included when a known red-lightning effect exists in the running game's prefab registry. It uses one damage application per target, with a short telegraph and thunder. Aim range is 80 m; damage radius is 6 m. Terrain/structures can be damaged under normal access checks.

Telekinesis: a held target stays held while cycling Levitate → In / Out → Expulsion. Switching to other modes or putting the wand away releases it. Ordinary hostile creatures, dropped items and dynamic logs can be moved. Players, bosses, tamed allies, buildings, ships and carts are excluded. Expulsion uses physical collisions and damages both the thrown target and the impact target where native health exists; trees can receive impact/chop damage. Standing trees are not uprooted. Dropped inventory items have no native health and are not artificially destroyed. Native ownership must be obtained before manipulation.

Forward Shield: a blue translucent barrier follows the player and absorbs hits whose path crosses its front face. It protects the caster, with remaining damage passing through if its capacity is exhausted. Rear/side hits, existing damage-over-time and environmental damage are not covered. This is not an allied/structure wall or a Protection bubble. It stops on unequip, leaving eligible custom modes, death or permission loss. Its controls do not depend on the native alternate-casting toggle.

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; 0.3 s delay; 650 base Lightning before native Elemental Magic skill factor
Acquire levitation	10	2 Eitr/s upkeep; 2.5–28 m holding distance
In / Out	Upkeep only	6 m/s movement of the holding distance
Expulsion	15	24 m/s launch; speed-based collision damage
Forward Shield	25	8 s or until depleted; 200–500 absorption with Blood Magic skill

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.4.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 installed 0.2.x/0.3.x clients and servers to 0.4.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.