⚒️ Balrond Second Chance

---

Overview

Balrond Second Chance adds a configurable Downed state to Valheim.

Instead of dying immediately, players can enter a Downed state where they may:

• Be revived by another player (instantly or through an optional hold-to-revive interaction)
• Revive themselves, either for free or by consuming a configured item
• Release their soul manually and die normally
• Wait for the Downed timer to expire

Gameplay settings, including the Downed animation and friend-revive hold duration, are synchronized through ServerSync. Debug Logging is a local-only setting. Server administrators can enforce synchronized settings using Lock Configuration.

Version note: This README describes the 1.0.17 source patch. The changes require a matching mod build on the server and clients. The patch has undergone source-level checks but has not yet been validated through a full Valheim multiplayer runtime test.

If you encounter a problem, please send feedback on Discord together with your logOutput.txt.

---

🧭 What Happens When You Die?

1. You enter the Downed state instead of dying immediately, when the feature is available.
2. A popup presents the available actions:
   • Wait for another player to revive you
   • Resurrect (self revive), if enabled
   • Release Soul
3. The Downed timer counts down.
4. If the timer reaches zero, you die automatically when Auto Release When Timer Ends is enabled.

---

🤝 Reviving Other Players

To revive a Downed player:

1. Approach within the configured Revive Distance (default: 3).
2. If Require Item For Friend Revive is enabled, carry at least Resurrection Item Amount of one allowed item in your inventory. The mod checks availability before beginning the interaction.
3. Use the interaction appropriate to the configuration:
   • Default / instant: press your Use key (normally E) once.
   • Timed: hold Use for the configured duration while keeping the same Downed player targeted and remaining in range.
4. When the Downed player's network owner confirms that revival succeeded, the reviver's game removes the configured number of items, if required. The revived player receives the configured health and cooldown.

If Require Item For Friend Revive is disabled, reviving another player is free. If Allow Friend Revive is disabled, other players cannot revive the target.

Optional Hold to Revive (new)

The feature is disabled by default to preserve the original instant-revive behavior.

Enable Timed Friend Revive	Friend Revive Hold Seconds	Behavior
false	Any value	One press of Use revives instantly.
true	0	One press of Use revives instantly.
true	Greater than 0	Hold Use for the selected number of seconds (up to 60).

When timed revival is active, the hover hint changes from USE to HOLD and displays elapsed/required time. The interaction follows the remappable Use binding; controller JoyUse is also recognized.

Releasing the key, looking away or changing the target, leaving revive range, losing eligibility, or reaching the Downed player's death/release state cancels the attempt. A new attempt starts from zero. The Downed timer does not pause while someone is holding the revive key. Using an item directly on the Downed player cannot bypass an enabled hold requirement.

The duration affects reviving another player only. It does not delay the self-revive button.

When Are Resurrection Items Consumed? (changed in 1.0.17)

Items are not removed at the beginning of a hold, on cancellation, or when a normal revive request is rejected. The reviver's inventory is charged after receiving a verified success response from the Downed player's owner.

• Only the configured Resurrection Item Amount is deducted, not the entire stack.
• Multiple stacks of the same permitted item type may be combined to meet the requirement.
• Different permitted item types are alternatives; their quantities cannot be combined to pay for one revive.
• Repeated success confirmations are tracked to prevent charging the same completed revive twice under normal operation.

Examples: With an amount of 2, a stack of 10 becomes 8; two stacks containing 1 of the same item each are consumed; one MeadHealthMinor plus one MeadHealthMedium is not sufficient if the amount is 2.

Multiplayer limitation: Player inventories and revival state are controlled by different network owners. This is not a guaranteed atomic payment. A disconnect after the target is revived but before the payer receives the result can leave a revival unpaid; moving/using items during confirmation can leave payment pending. The mod retries confirmations while the relevant session remains available, but it has no durable cross-session payment ledger. See Multiplayer Notes & Known Limitations below.

---

🧍 Self Revive

Self revive can be enabled or disabled using Allow Self Revive.

Free Self Revive

When Require Item For Self Revive is disabled:

• Press Resurrect while Downed.
• No item is consumed.

Item-Based Self Revive

When Require Item For Self Revive is enabled:

• Carry the configured amount of one allowed resurrection item.
• Press Resurrect while Downed.
• The local owner performs the revive and checks its result before deducting the required amount from the inventory.

Self revive does not use Hold to Revive. Both self revive and friend revive obey applicable cooldown rules.

---

💀 Release Soul

While Downed, you can select Release Soul at any time. This ends the Second Chance state and continues normal Valheim death behavior.

---

⚙️ Features

• Downed state instead of immediate death
• Multiplayer player-to-player revival, including optional Hold to Revive
• Optional instant self revive
• Free or item-based reviving
• Multiple permitted resurrection item prefab IDs (OR alternatives)
• Exact item quantities, including payment across same-type inventory stacks
• Owner-validated revive requests with confirmation and duplicate-payment protection
• Configurable revive range, restored health, Downed duration and cooldown
• Optional automatic death when the timer expires
• 4 supported Downed animations in the current configuration
• ServerSync for gameplay settings; optional local debug logging
• Localization support
• Ultrawide Downed-popup scaling improvements

---

🔧 Configuration

Configuration section names and keys below match the mod's BepInEx config.

0 General

Setting	Default	Description
Lock Configuration	true	Allows the server to enforce synchronized gameplay settings.
Debug Logging	false	Local-only diagnostic logging for Downed/UI initialization and recovery. Not synchronized.
Downed Seconds	120	Duration of the Downed state in seconds.
Auto Release When Timer Ends	true	Automatically triggers normal death when the Downed timer expires.
Cooldown Minutes	10	Cooldown applied after a successful revive.
Revive Health Percent	0.25	Fraction of maximum health restored; 0.25 = 25%.
Revive Distance	3	Maximum distance for reviving another player.
Downed Presentation Mode	Sit	Server-synchronized Downed pose. Allowed values: Sit, Bed, Dance, Headbang.

1 Self Revive

Setting	Default	Description
Allow Self Revive	true	Enables self revive while Downed.
Require Item For Self Revive	true	Requires a configured resurrection item for self revive. Disabled effectively if the item prefab list is empty.

2 Friend Revive

Setting	Default	Description
Allow Friend Revive	true	Allows players to revive other Downed players.
Require Item For Friend Revive	true	Requires a configured resurrection item for friend revive. Disabled effectively if the item prefab list is empty.
Enable Timed Friend Revive	false	Enables hold-to-revive using the Use key. Off by default; false preserves instant revival. Server-synchronized.
Friend Revive Hold Seconds	4	Hold duration when timed revival is enabled. Range: 0–60 seconds. 0 means instant revival. Server-synchronized. Does not affect self revive.

Example: enable a four-second hold for reviving other players:

[2 Friend Revive]
Allow Friend Revive = true
Require Item For Friend Revive = true
Enable Timed Friend Revive = true
Friend Revive Hold Seconds = 4

3 Items

Setting	Default	Description
Resurrection Item Prefab	MeadHealthMinor	One or more permitted prefab IDs separated by commas or semicolons. These are alternatives (OR). Leave blank to disable the item requirement effectively.
Resurrection Item Amount	1	Number of items required and deducted for each paid revive (minimum effective amount: 1).

Example of alternative items and an exact two-item cost:

[3 Items]
Resurrection Item Prefab = MeadHealthMinor, MeadHealthMedium
Resurrection Item Amount = 2

For this example, the player needs two of either allowed item, including across multiple same-type stacks; one of each type does not satisfy the requirement.

---

🎭 Downed Animations

Downed Presentation Mode controls the Downed animation. The current mod configuration exposes four supported choices:

• Sit (default)
• Bed
• Dance
• Headbang

This setting is server-synchronized, not a separate local preference for each player. Older documentation listed additional poses, but they are not selectable through the current config.

---

🌐 Translation

Translation files are stored in the mod's translation folder inside the config directory. The default file is English.json.

If untranslated keys such as $tag_something_bal appear, check that the translation file is installed and loads correctly. Malformed translation JSON is handled more defensively in 1.0.17.

To add another language:

1. Copy English.json.
2. Rename the copy using a language name supported by Valheim.
3. Translate the values only; do not change the keys.

Note: New HOLD/progress/payment status messages in the current source still contain some literal English strings and may not yet be fully localized.

---

🌐 Multiplayer Notes & Known Limitations

• Matching versions required: the 1.0.17 RPC protocol and ServerSync version checks require a matching mod build on connected players and the server.
• Server-side checks: the Downed character's owner validates sender/player identity, distance, Downed/release status, cooldown and, when enabled, the hold session and elapsed time. The protocol does not send progress updates every frame.
• Payment is not globally atomic: normal rejected revives do not spend items, and confirmed revives trigger exact-count payment. A client disconnection or inventory change during settlement can still produce an unpaid revive or a pending payment. Client-owned inventory also cannot be treated as tamper-proof against modified clients.
• Cooldown persistence: cooldown is currently stored on the player character's ZDO; its behavior across character teardown/reconnect has not yet been verified.
• Compatibility testing: the Downed implementation patches core player update/death behavior. Large modpacks and other death/animation mods should be tested together before public deployment.

Release validation status: the 1.0.17 patch passed source-level and model checks, but compiling against the live Valheim assemblies and testing single-player, host/client, dedicated-server, controller and ultrawide scenarios are still required before treating it as production-verified.

---

💬 Community & Support

Discord: https://discord.gg/Jfp8T5N7Pv
Ko-fi: https://ko-fi.com/balrond1020

---

⚒️ Enjoy your Second Chance!