Universal Wand

One wand. Every staff.

• Switch between Valheim's eight current magic weapons 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.
• Original staffs remain unchanged and fully usable.

Important release status

Version 0.1.2 is a compiled and statically validated release candidate. It was compiled against the available publicized Valheim 0.221.4 API plus BepInEx 5.4.23.3 and Jotunn 2.29.2. The intended stable game snapshot is 0.221.12, but no Valheim runtime was available here, so in-game, multiplayer, visual-alignment, and balance-equivalence tests remain required before public release.

Valheim 1.0 / Deep North requires a full rebuild, runtime retest, and magic-roster audit. Future default changes will never overwrite existing custom bindings.

Controls

Every shortcut is a local BepInEx KeyboardShortcut and can be changed live through the config file or a compatible configuration manager. Set a shortcut to None to unbind it. If shortcuts conflict, the lowest slot number wins and one warning is logged.

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.

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.

Unlock progression

A mode permanently unlocks for that character after any of these events:

1. the corresponding source magic weapon is present in the character's inventory,
2. the character crafts or upgrades that weapon, or
3. the original weapon reaches its successful attack trigger.

Inventory ownership is checked every 0.75 seconds, so an already-owned or newly picked-up staff is recognized without requiring another craft. A failed/no-Eitr attempt does not count as a successful cast, but possession still counts. 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.

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. During the exact native attack methods, the physical wand temporarily reports that spell's recorded source-staff quality; it is restored immediately afterward. This carries the source level through immediate attacks and delayed projectile bursts without replacing the wand's own item quality or durability. 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.

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:

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 place UniversalWand.dll in BepInEx/plugins/UniversalWand/. Jotunn and BepInEx are required.

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.

See TEST_REPORT.md for completed and outstanding verification.

Changelog

0.7.2 - 2026-10-01

• Cancel a queued native spell selection if the player changes to another wand. Previously, a selection requested during an attack could overwrite the newly equipped wand's spell.
• Add a regression covering replacement during an attack and immediately before it ends; all 63 integration scenarios pass.
• Review Jotunn registration and multiplayer requirements against its 2.30.2 GitHub source; clarify controls, installation and testing scope.

0.7.1 - 2026-09-30

• Defer missing-source warnings until gameplay item registration has completed and its callbacks have settled. The incomplete menu database no longer reports all twelve vanilla staffs as disabled.
• Recheck sources registered through the API after gameplay starts. A genuinely absent source still produces a warning; a later available source recovers normally.
• Let optional Staffs of Fracturing sources finish registration before reporting an absent variant.
• Restore the clean SDK project and build against Valheim 1.0.16, Jotunn 2.30.2 and BepInExPack 5.4.2351. Add four registration lifecycle regressions; all existing suites pass.

0.7.0 - 2026-09-13

• Reduced the base recipe to 10 core wood, 5 fine wood, 2 silver and 1 black core. Upgrades now use core wood, fine wood and silver with native quality scaling.
• Added one historical base-recipe reimbursement per eligible character when their old wand is in their inventory. Return 20 Yggdrasil wood, 30 refined eitr, 5 black cores and 2 red gemstones; keep the wand, fill available inventory space and drop the remainder at the player's feet. Notify that player through local chat.
• Require the wand's recorded crafter/upgrader to match the local character. Exclude new-recipe wands, known cheated items and existing claims. Historical upgrade costs and other mods' price changes cannot be reconstructed from old saves.
• Reserve a durable receipt before delivery and preserve character/item markers. Empty, interrupted or corrupt receipts block repeat awards; ambiguous inventory/drop failures stop without automatically retrying. Preserve the refund receipt folder across mod/profile updates.
• Mark native newly created and upgraded wands before inventory insertion, including positioned upgrades, without patching global attack or crafting UI methods.
• Added 101 refund scenarios covering 1,120 assertions, including real-file concurrent claims, interrupted delivery, rollback, replay and crafting-scope cleanup.
• Added default SilverCore appearance: wood body, shiny silver base and a faintly emissive dark-purple core tip. Preserve the same mesh, size and grip. Choose ClassicWood in the local visual config to restore the previous appearance immediately.
• Update modded clients and servers together to 0.7.x. Native API checks and deterministic builds passed; live Valheim refund delivery, crafting compatibility, appearance and multiplayer validation remain required before public release.

0.6.3 - 2026-09-12

• Removed Spirit Orb from active custom spells, including casting, sound and local/remote effects. Custom Lightning Strike remains disabled.
• Numpad + now cycles Lumos → Telekinesis. Their controls, the default-Off/server-controlled custom setting and native staff alternate casting are retained.
• Updated the description and config help; kept inactive spell code and stable identifiers for future work.

0.6.2 - 2026-09-12

• Temporarily disabled custom Lightning Strike, including selection, casting and remote visual playback/relay. Retained its implementation for a future return.
• Numpad + now cycles Spirit Orb → Lumos → Telekinesis. Their existing controls and Protection alternate remain.
• Updated the description and config help. Native staff spells, including the separate Deep North Lightning Strike, are unchanged.

0.6.1 - 2026-09-12

• Restored the earlier lightning style, removing 0.6.0's added HDR material boost, glow shells and thin tributaries/forks.
• Raised the blue strike origin to 300 m above its target and moved the purple gathering to 280–320 m overhead. Preserved the orbital circle, fast purple → blue → red timing and single impact at 1.15 seconds.
• Kept materials local to each strike, the eight-visual limit and cleanup. No global lightning, camera, fog or bloom setting is changed. The reported interaction with other lightning could not be reproduced here.
• Retained 0.6.0 telekinesis following, held raising, pulling and momentum release.
• Shortened the description with a quick overview, clear controls and telekinesis instructions. Kept Gaakrin's MagicTweaks credit; moved the full reference to the source ZIP.

0.6.0 - 2026-09-12

• Added emissive lightning cores, wider soft glow and attached thin tributaries/forks. Kept the purple → blue → red sequence and single damage impact at 1.15 seconds.
• Capped lightning presentation at eight simultaneous instances, with bounded geometry and material/texture cleanup; damage remains independent of visual eviction.
• Telekinesis now follows player movement and camera aim at a retained distance. Held secondary raises it; held Block brings it closer.
• Acquisition remains held when its button is released. A later short secondary tap releases existing swing momentum; holding instead raises and keeps the target. Primary keeps the 32 m/s powered expulsion.
• Added collision-aware follow targets, responsive velocity tracking, stale/blocked hold cleanup, and velocity-preserving fling impact monitoring. Menu/policy/death cleanup cannot trigger a fling.
• Preserved Lumos, Spirit Orb, native Protection and all staff progression/network behavior. Custom spells remain Off by default and server-controlled.
• Isolated custom test build directories so linked test programs cannot share stale apphost/incremental outputs. Added follow/gesture/control regressions; actual gameplay and visuals still require in-game checks.

0.5.0 - 2026-09-12

• Condensed Plus cycling to Spirit Orb → Lumos → Lightning Strike → Telekinesis.
• Telekinesis now uses secondary attack to lift/release, held Block to pull closer and primary attack to throw. Increased throw speed 24 → 32 m/s while retaining damage caps, ownership, costs and cleanup.
• Disabled the blue custom forward shield and its damage hook. Spirit Orb/Lightning secondary now uses the full native Protection spell with its own unlock, recorded level, costs and effects. Custom selection remains intact; saved Dead Raiser cannot redirect it to Trollstav.
• Retained the lightning targeting circle; added high purple sky buildup, a bright blue downward strike impacting at 1.15 seconds, then red lightning rising from the ground. Damage occurs once at the blue impact.
• Renamed Magical Light to Lumos; its wisp appearance, passive behavior and 30-second detached lights are preserved.
• Added a quiet short casting sound to Spirit Orb, with native audio lookup and a soft synthesized fallback. Remote launches sound once; failed/duplicate casts do not.
• Preserved Off-default/server-controlled custom policy, native spell progression, client-only vanilla support, artwork and held model. Update installed clients/server together to 0.5.x.
• Added focused controls, native Protection and lightning timeline regressions. In-game appearance, audio, physics and networking still require testing.

0.4.0 - 2026-09-12

• Added wand-only custom casting, default Off under [Custom Spells] Custom Added Spells = On/Off. Local worlds use the local choice; a modded server controls clients. An unmodded/unconfirmed server always means Off.
• Added configurable Numpad + cycling: Spirit Orb, Magical Light, Lightning Strike, Levitate, In / Out, Expulsion. Existing numbered keys and Enter retain native staff selection. No Fallen Valkyrie spell is included.
• Spirit Orb fires rapid Spirit/Lightning projectiles. Lightning calls an aimed area strike with blue/violet effects, optional available native red-lightning color, thunder and one hit per target.
• Wisp-like light follows the tip while equipped. Left-click throws a light; right-click places it at the tip's current position. Detached lights last 30 seconds and survive ordinary spell switches/unequip.
• Spirit Orb and Lightning right-click create a blue forward barrier with directional caster-only damage absorption, finite capacity and duration.
• Levitate holds eligible mobs/objects; hold left/right in In / Out to pull/push. Expulsion throws them and applies native impact damage to both health-bearing objects, including chop damage to struck trees. Delayed impacts retain launch skill/world data.
• Added confirmed-peer visual relay and server permission renewal. Policy/world/death/ownership cleanup removes ongoing custom gameplay. New effects require explicit server support; no custom network-prefab registration is needed.
• Kept custom input blocked after permission loss until explicit native selection, preventing accidental stale staff casts. New queued custom/native choices cancel older choices from the other selector.
• Preserved native complete-spell alternates, highest recorded staff levels, carrier networking, inventory transparency and small held model. MagicTweaks notice and Gaakrin inspiration credit remain.
• Added focused custom controller, policy, shield, light motion and telekinesis snapshot checks. Real Unity rendering, damage/physics and multiplayer testing remain required.

0.3.2 - 2026-09-12

• Made alternate casting a built-in wand feature, enabled by default under [Casting] Enable Alternate Casting. Disabling it restores the selected source's native secondary behavior.
• Right-click casts unlocked Trollstav with Dead Raiser selected, otherwise unlocked Protection. Left-click and the saved primary selection are preserved.
• Retained full native alternate spell data and its separately recorded level, costs, skills, restrictions and delayed-effect snapshots. No manual shield or extra summon is applied.
• Prevented repeated/opposite clicks during an active cast from replacing its target data or level before the trigger frame.
• Removed the MagicTweaks casting integration and soft dependency. Detection now logs a compatibility notice after plugin initialization; remove incompatible MagicTweaks 1.0.0 and restart. This release does not disable that separate DLL's global attack patches.
• Built-in alternate casting inspired by MagicTweaks by Gaakrin. No MagicTweaks code or assets are bundled.
• Preserved optional server installation, vanilla-spell networking, visuals and saved progression. Added regressions with MagicTweaks absent; actual shield absorption, summons and multiplayer still require in-game verification.

0.3.1 - 2026-09-11

• Fixed the MagicTweaks right-click adapter carrying Embers item data with a copied Protection animation, leaving out the target spell's status-effect and skill data.
• Run the complete native Protection source through the secondary slot at the character's recorded Protection level. Dead Raiser uses the complete Trollstav source at its recorded level.
• Keep the wand's own identity and selected primary spell during alternate casts; no manual shield lookup or MagicTweaks secondary initialization is required.
• Added three regressions covering shield data through the trigger frame, missing MagicTweaks initialization, and correct alternate data for every primary mode.
• Retained the 0.3.0 network protocol, controls, unlocks, icon and model. In-game shield and multiplayer verification remain outstanding.

0.3.0 - 2026-09-11

• Added client-only operation for all twelve vanilla spells; Universal Wand is now optional on the server and other clients.
• Publish the selected vanilla staff's equipment identity while restoring the custom wand model locally for viewers with Universal Wand.
• Store and drop wands through a vanilla Staff of Embers carrier with a versioned item marker, retaining selection and physical quality through standard item serialization.
• Migrate older custom-prefab inventory records before Valheim replaces their custom data; normalize legacy dropped items when loaded with the mod.
• Prevent the carrier from granting an unearned Embers unlock and clear visual markers when another weapon is equipped.
• Preserve hidden-item visuals, highest source levels, delayed casting snapshots, bindings, transparent icon and existing hand-aligned geometry.
• Require confirmed server support for the optional custom Staffs of Fracturing projectiles; absent-server variants are skipped without deleting progression.
• Added client compatibility regressions and checked every new Harmony target and argument against the supplied Valheim 1.0.12 assembly. Live multiplayer testing remains required.

0.2.0 - 2026-09-11

• Rebuilt against the supplied Valheim 1.0.12 game and Unity assemblies; requires BepInExPack Valheim 5.4.2350 and Jotunn 2.30.0 or later.
• Replaced private equipment-member access with public Valheim 1.0 APIs; no publicized game reference is required.
• Added Echo Spike, Spirit Caller, Northern Vengeance and Lightning Strike with independent unlocks and highest-level progression.
• Added configurable Numpad Enter cycling for unlocked Deep North staffs, preserving all existing keys and saved progress.
• Captured wand-only casting snapshots for delayed projectiles, area effects and summons so later switches cannot change their level or source data.
• Protected physical wand quality during item saving and inventory cloning, including saves/drops during a cast.
• Preserved native combat/crafting paths, optional integrations, transparent inventory icon and held model.

0.1.6 - 2026-09-11

• Replaced direct publicized-only gameplay-input access with a cached runtime method binding, preserving Valheim's own menu and typing guards.
• Restored active-backend keyboard support through BepInEx UnityInput.Current, while retaining tolerance for unrelated held gameplay keys.
• Enabled compiler support for access to game members through publicized references.
• Aligned the plugin's .NET Standard 2.1 target with its Unity 6000 reference assemblies.
• Isolated update stages and added deduplicated error reporting so a maintenance failure cannot silently disable selection.
• Made selection and queued switching use the same current-weapon lookup as casting.
• Process explicit selection requests before refreshing the prior mode, and only commit fallback state after its source view is prepared successfully.
• Added 17 executable integration scenarios covering all eight vanilla selections, unlocks, highest staff levels, queued switching and unequipping, MagicTweaks alternates, input backends and exception recovery.
• Corrected the build script to execute its regression runners.

0.1.5 - 2026-09-01

• Fixed a gameplay input bug where BepInEx's exact KeyboardShortcut.IsDown() modifier test could reject Numpad selection whenever movement, sprint, or another unrelated keyboard key was held.
• Replaced exact-shortcut polling with main-key polling that requires configured modifiers but ignores unrelated gameplay keys.
• Added [Testing] Unlock All Spells, a live non-persistent override that exposes every resolved spell at level 1 while preserving legitimately recorded higher levels.
• Added explicit selection diagnostics: detected locked requests, successful spell/level selections, and resolved-source application failures now produce distinct feedback/log entries.
• Renamed keybind config entries from Slot 0–Slot 9 to the corresponding staff names.
• Added automatic one-time migration of existing slot-key values and removal of the obsolete slot entries.
• Strengthened immediate progression recognition by checking both the current weapon and right-hand item when they differ.
• Preserved the confirmed 0.1.4 MagicTweaks shield path, native combat isolation, crafting isolation, icon, and held model.
• Expanded pure core coverage from 20 to 23 checks.

0.1.4 - 2026-09-01

• Hardened source-staff recognition after runtime testing showed that Frost worked but other acquired/used staffs could remain locked.
• Added stable source-name and attack/projectile identity fallbacks for cloned or rewritten inventory item instances.
• Added an immediate, read-only progression check when a non-wand source staff begins an attack; normal weapons still return directly to Valheim and cannot be cancelled by this check.
• Contained progression-scan exceptions so a bad inventory item cannot stop Numpad selection or wand updates; failed scans retry automatically.
• Explicitly excludes the Universal Wand itself from progression recognition so its temporary casting view or physical quality can never grant/upgrade a source spell.
• Added optional soft-dependency compatibility with MagicTweaks 1.0.0.
• With MagicTweaks installed, wand right-click casts unlocked Protection normally or unlocked Trollstav while Dead Raiser is selected.
• Alternate casts use the target spell's highest recorded source-staff level and a fresh live MagicTweaks secondary-attack view.
• Prevented normal selection refresh from replacing a MagicTweaks compatibility view during an active attack.
• Expanded pure core coverage from 17 to 20 checks.

0.1.3 - 2026-08-31

• Removed the InventoryGui.DoCrafting Harmony patch that could stall AzuCraftyBoxes and normal crafting. Inventory scanning now observes completed crafts/upgrades without touching the crafting pipeline.
• Removed every Attack.OnAttackTrigger and Attack.FireProjectileBurst patch after runtime testing showed that they could suppress damage and spell projectiles for unrelated weapons.
• Kept only one fail-open Humanoid.StartAttack boundary. It exits immediately for non-wands, so swords and original staffs stay entirely on Valheim's native path.
• Changed source-level handling to a wand-only cast lease: the recorded staff quality remains active for the wand's complete attack and is restored as soon as that attack finishes or fails.
• Added exception containment so a Universal Wand preparation failure logs an error but cannot cancel a normal weapon attack.
• Added live-SharedData fallback recognition for source staffs whose inventory prefab name is unavailable or altered by another mod.
• Preserved the 0.1.2 transparent inventory icon and corrected half-size hand-aligned model unchanged.

0.1.2 - 2026-08-31

• Removed personal-name branding from the plugin GUID, assembly metadata, license, save keys, source, and packaged files.
• Separated the artwork outputs: Thunderstore keeps the neutral gray presentation, while the embedded in-game icon uses a genuinely transparent background.
• Reworked progression so carrying a source staff, crafting/upgrading it, or successfully casting it unlocks the matching spell reliably.
• Added versioned per-character source-quality progression. The highest source-staff level ever acquired or used is retained for each spell and never downgraded.
• Applied that stored source quality during the complete native cast path, including delayed projectile bursts, while preserving the Universal Wand's own quality and durability outside each cast.
• Migrated older Boolean unlocks as level 1 without retaining the former identifying save-key prefix.
• Reduced the held model to half its previous dimensions, made it completely straight, removed the permanent tip object, and placed its wooden base at the hand attachment point.
• Expanded pure core coverage from 15 to 17 checks.

0.1.1 - 2026-08-31

• Added optional soft-dependency compatibility with Staffs of Fracturing 1.0.0.
• Added Iolite, Jade, and Bloodstone to the Fracturing family without taking additional direct-selection keys.
• Repeated Fracturing-key presses now cycle through installed and individually unlocked family entries in a stable order.
• Added per-character craft-or-successful-cast unlock handling for each Fracturing variant.
• Kept clean fallback behavior when the optional mod or a previously selected variant is absent.
• Replaced the runtime model with an actual three-sided wooden stick with flat triangular caps.
• Enlarged the cyan tip orb and centered its core directly on the wand endpoint in both the runtime model and icon.
• Expanded pure core coverage from 10 to 15 checks and added supplied-DLL identifier verification.

0.1.0 - 2026-08-29

• Added the quality 1–4 Universal Wand with a lightweight faceted, subtly irregular continuous-taper wood model and matching low-poly original icon.
• Added eight data-driven adapters for the current vanilla magic roster.
• Added exact default Numpad 0–9 mapping with slots 6 and 7 reserved.
• Added per-character craft-or-successful-cast unlock progression and spoiler-safe locked feedback.
• Added per-item selected-mode persistence and safe queued switching during attacks.
• Added configurable live BepInEx shortcuts, deterministic duplicate handling, HUD notices, and pooled switch flash.
• Added EveryoneMustHaveMod/Minor network enforcement and dedicated-server visual guards.
• Added tests, deterministic-build checks, package validation, source archive, architecture notes, and the Valheim 1.0 maintenance plan.