CaptainValheim

Turns shields into active weapons. All you need is one shield. Shield strikes, throws, charges, projectile reflection, and block charges all follow real shield stats and blocking skill.

Shield Primary Attack
CaptainValheim lets a shield act as a real close-range weapon instead of only a defensive item. A primary shield strike uses the equipped shield's own block power, deflection force, stamina profile, and durability cost as the base, then applies the values from CaptainValheim.yml. That means a buckler, tower shield, and round shield can all feel different without needing separate hardcoded behavior.

Shield Throw
Throw your shield forward as a returning weapon. The throw can hit multiple targets, lose power through damage decay, search for nearby targets, and return after its lifetime expires. Damage, push force, target count, damage decay, ricochet search radius, flight lifetime, stamina cost, and durability cost can all be tuned, while the final result still scales from the shield you actually equipped.

Shield Charge
Shield Charge turns your block into a forward burst that drives into enemies with shield-based damage and push force. It is useful for closing distance, interrupting enemies, or opening space in a crowd. Charge distance, speed, hit radius, cooldown, stamina cost, durability cost, damage factor, and push factor are configurable, and WarfareTweaks can read the shield-hit context when both mods are installed.

Block Charge
Valheim already contains a block-charge style counterattack, but it is effectively locked away for normal shield gameplay. CaptainValheim exposes and tunes that vanilla behavior so shields can use it intentionally. The mod can also provide fallback charge visuals for shields that do not have their own charge setup, making the feature usable across a wider range of shield prefabs.

Projectile Reflection
Projectile Reflection rewards accurate blocking by letting guarded projectile hits bounce back instead of simply being absorbed. Reflection behavior scales with shield deflection and can be tuned separately from attacks, throws, and charges, so servers can decide how strong defensive projectile play should be without changing the rest of the shield kit.

Highlights

• Gives every shield a configurable active combat kit through one synced YAML file.
• Scales damage, push, stamina, and durability from the shield's actual stats instead of using one flat value for every shield.
• Provides a global fallback so unlisted shields work immediately, while individual prefab overrides can tune special cases.
• Syncs config through ServerSync for dedicated servers.
• Adds a WarfareTweaks bridge so Warfare effects can recognize CaptainValheim shield hit contexts.
• Keeps the mod focused on shields only, with no ranged, melee, or Blood Magic preset schema mixed in.

Shield Features

• primaryAttack: turns shield use into a direct shield strike with configurable damage, push, stamina, and durability factors.
• throw: throws the shield, supports multiple targets, damage decay, search radius, lifetime scaling, and return behavior.
• charge: sends the player forward with shield-based damage, push, hit radius, distance, speed, cooldown, and stamina tuning.
• reflect: lets guarded projectile reflection scale from shield deflection.
• blockCharge: enables and tunes Valheim's vanilla block-charge counterattack behavior, including support for shields missing charge visuals.

Configuration

CaptainValheim creates:

• BepInEx/config/sighsorry.CaptainValheim.cfg
• BepInEx/config/CaptainValheim.yml

Show Shield Tooltip in the BepInEx config controls the extra CaptainValheim guidance appended to shield item tooltips. It defaults to On and is a client-only display setting that is not synchronized with the server.

The root Global block defines fallback behavior for all shields. Any shield prefab listed below Global inherits those defaults and only overrides the fields you write.

Example:

Global:
  throw:
    enabled: true
    damageFactor: 0.80
    targets: 3
  charge:
    enabled: true
    cooldown: 10.0
    distance: 4.0

ShieldCarapaceBuckler:
  throw:
    damageFactor: 1.00
    targets: 2
  charge:
    cooldown: 8.0

Set a mode block's enabled: false to disable that feature after inheritance.

Localization

The package includes CaptainValheim.English.yml as a translation template. Copy it beside CaptainValheim.dll, translate only the values while keeping every key unchanged, and rename it to CaptainValheim.<Valheim language>.yml. For example, a Turkish translation must be named CaptainValheim.Turkish.yml.

Save translation files as UTF-8, then restart Valheim or reselect the language after changing a file. Localization is client-local, so each player can use a different language file; missing files or values fall back to the built-in English text.

Compatibility

• Works on dedicated servers through synced config.
• Can pass shield hit context to WarfareTweaks so configured Warfare effects apply cleanly to shield attacks and shield charges.
• Designed to coexist with SecondaryAttacks, which handles non-shield ranged, melee, bomb, staff, and Blood Magic behaviors.

Building

Build against a local Valheim installation with BepInEx and the publicized game assemblies configured in environment.props.

For normal development, build Debug and automatically copy the final merged plugin DLL into the configured Valheim plugins folder:

dotnet build CaptainValheim.csproj -c Debug -p:DeployToGame=true

Use -p:DeployToGame=false to skip the game DLL copies. The legacy SkipDeployment=true option is still supported when DeployToGame is not specified. Debug builds do not update the release manifest or generate packages. Use Release only for an explicitly requested release; SkipPackaging=true skips its manifest update and Thunderstore/Nexus packages.

Github

https://github.com/sighsorry1029/CaptainValheim

Changelog

1.0.12

• Reduced shield key-hint UI work by preventing the game's combat hints and CaptainValheim's hints from repeatedly toggling each other every frame. Preserved normal weapon hints when using a shield with a melee weapon and cleaned up owned hints when the HUD is destroyed.
• Improved automatic re-equipping after direct shield returns and marked ground pickups. Re-equipping now waits for temporary attack, dodge, or swimming restrictions to end instead of expiring after one second.
• A new hand equipment choice cancels pending re-equipping. Other mods' equipment restrictions remain authoritative; a rejected equip leaves the shield in the inventory without repeated attempts or extra item drops.
• Added thrower identity metadata to dropped thrown shields for optional FearNoSpear integration. Compatible FearNoSpear versions can restrict automatic pickup to the thrower while retaining manual pickup; metadata failures after a successful drop do not trigger a duplicate drop.

1.0.11

• Added server-synchronized options for using shield charge, block-charge counterattacks, and projectile reflection with a one-handed melee weapon. Charge defaults to Off; block charge and reflection default to On.
• When enabled, Block + Secondary Attack uses shield charge while ordinary weapon attacks remain available. A failed or held charge input cannot fall back to a weapon attack.
• Block-charge accumulation and counterattacks now respect the equipment policy and YAML enable setting without changing other players' shields; entering disallowed equipment clears stored charges.
• Prevented direct shield charge from starting during attacks, dodges, knockback, stagger, or other restricted actions.
• Updated shield hints, tooltips, and the Compendium to explain weapon compatibility while retaining normal weapon hints.
• Updated the required BepInExPack version to 5.4.2351.

1.0.10

• Updated CaptainValheim for Valheim 1.0.7, including the new shield tooltip signature and original game assembly access boundaries.
• Updated the bundled ServerSync compatibility build for Valheim 1.0.7, fixing configuration initialization and preserving connection-time player, history, administrator, and network-time messages.
• Preserved Valheim 1.0 damage channels, attack resource effects, and status-effect variants through shield hits and the versioned projectile reflection protocol.
• Prevented new mid-flight projectile template behavior from bypassing shield throw hit ownership and duplicate-hit handling.
• Updated the required BepInExPack version to 5.4.2350.

1.0.9

• Reorganized shield throw and charge state alongside their runtime code and removed redundant attack setup forwarding without changing combat rules.
• Removed an unnecessary ObjectDB snapshot pass while retaining capture-before-write and conditional restoration of modified shield data.
• Avoided allocating reflection block contexts for characters and shields that do not use projectile reflection.
• Added DeployToGame support for automatic local DLL updates after Debug builds, plus options to skip game copies or release packaging during validation.

1.0.8

• Added the client-only Show Shield Tooltip setting, enabled by default, so each player can hide CaptainValheim guidance from shield item tooltips without changing server behavior.
• Removed the shield reflection debug logging option and its diagnostic-only logging and data plumbing.

1.0.7

• Added localized shield key hints, contextual shield tooltip guidance, and a new Compendium page explaining Shield Strike, Throw, Charge, Projectile Reflection, and Block Charge.
• Added built-in English and Korean text plus client-side CaptainValheim.<Language>.yml overrides; Thunderstore packages now include CaptainValheim.English.yml as a translation template.
• Simplified the shield-only configuration and runtime structure by removing unused inherited SecondaryAttacks paths and consolidating code that changes together.
• Hardened live configuration reload and synchronization, ObjectDB restoration and reapplication, runtime cleanup, and shield state handling while preserving existing combat behavior.

1.0.6

• Rebuilt dedicated-server projectile reflection around owner-authoritative HitData and projectile snapshots with exact, one-shot target correlation, allowing multiple shield players in the same loaded zone to reflect independently.
• Removed pending queues, TTL pruning, fuzzy matching, and string payload workarounds while preserving the original sender, validating ownership, and marking reflected projectiles across ownership transfers.

1.0.5

• Reduced inherited SecondaryAttacks infrastructure to CaptainValheim's shield-only configuration, definition, and runtime pipeline, removing duplicate version RPC and unused generic paths.
• Hardened shield primary, throw, charge, and reflection context cleanup with scoped Harmony finalizers and simplified projectile visual and return handling.

1.0.4

• Fixed dedicated-server shield reflection for multiple players in the same loaded zone by correlating remote projectile and block contexts through player ZDOIDs.
• Added bounded ordered fallback matching and now creates reflected projectiles from their registered source prefabs.

1.0.3

• Improved dedicated-server shield reflect reliability by keeping successful blocks briefly pending so late projectile ownership/context RPCs can still trigger reflection.

1.0.2

• Improved multiplayer shield reflect reliability on dedicated servers by sending projectile fallback payloads for remote block contexts.
• Relaxed remote shield reflect context matching so valid blocks can reflect even when projectile hit context timing or hit points differ between clients.

1.0.1

• Added multiplayer shield reflect ownership handoff so remote projectile hits can be reflected by the blocking player on dedicated servers.
• Added optional shield reflect diagnostics.
• Fixed generated key hint separator font/style copying.

1.0.0

• Initial Release.