TrollCompanion 0.2.9

Summon friendly trolls with the Trollstaff, keep their progress, and give them combat orders. Your companions always carry a club. Wild trolls remain unchanged.

Development release: version 0.2.9 fixes custom companion names being lost on recall. Names are now saved with the companion and restored after resummoning, variant changes, death, restarts, and temporary slot restrictions. Combat balance and failure refunds remain unchanged from 0.2.8. The release build, API checks, and 82 regression tests passed. In-game validation of name persistence and full multiplayer testing are still pending.

Features

• Ashlands trolls by default, with forest trolls available as an alternative.
• Native Trollstaff arrival and impact effects, without impact damage or terrain damage.
• A persistent roster for each character and world, including custom names, kill progress, and current health.
• Attack-move, focus attack, hold position, follow, and recall commands.
• Configurable limits, progression, costs, combat stats, cooldowns, and protection settings.
• Early placement checks with a search for a suitable spot within 3 meters of the target.
• Optional, server-controlled refunds for confirmed technical spawn failures.
• Configurable resistance compensation against ordinary hostile creatures, with separate boss scaling.

Installation

Install the same TrollCompanion version on the server/host and every client. Client-only installation is not sufficient for multiplayer.

Dependencies:

• BepInExPack Valheim 5.4.2351 or newer.
• Jotunn 2.30.2 or newer.

1. Stop Valheim and the server before replacing mod files.
2. Install through Thunderstore Mod Manager, or use Settings > Profile > Import local mod to import the ZIP into a test profile.
3. For a manual server installation, extract plugins/TrollCompanion.dll into the server's BepInEx/plugins/TrollCompanion folder. Keep only one copy of the plugin. When switching from a manual installation to the manager, remove the old manually copied DLL and its PDB first.
4. Start the server, then launch the client with mods enabled. Check both startup logs for Loading [TrollCompanion 0.2.9].

Keep your existing configuration and companion data when updating. The startup log still uses the message TrollCompanion geladen.

The local import package is TrollCompanion-0.2.9.zip.

Controls

Equip the Trollstaff to use these commands. Menus and text input block command hotkeys.

Orders affect all your active companions. A new J command replaces the previous order. During attack-move, focus attack, and holding position, companions do not automatically catch up to you. H restores following and catch-up behavior.

Key bindings are configurable on each client. G remains available for Valheim's radial menu.

Companion names

The owner can rename a companion through the game's normal name dialog, using its native 10-character limit. Clear the field to restore the native default name. No new key binding or configuration option is needed.

With text messages enabled, Begleitername gespeichert. (companion name saved) or Standardname gespeichert. (default name saved) confirms that the server has saved the change durably.

The name stays with that companion through recall, resummoning, variant changes, death, restarts, and temporary slot restrictions. Companions keep separate names. Extra star indicators above two stars remain visible with custom names and are kept separate from the stored name. Native name filtering and content-author information are preserved.

Names already lost by older versions cannot be recovered. Rename those companions once after updating.

Default settings

Both troll variants use the forest troll's base combat stats. Eligible kills belong to the companion that lands the final blow. Players, tamed animals, and other companions do not grant kill progress.

The inspected forest troll has 600 base HP. The default health multiplier of 10 and health-per-star value of 1 produce the maximum-health values above. Damage uses the verified forest troll club profiles, with a base multiplier of 6 and an additional 50% of that base per star. Existing configurations retain their saved health and damage multipliers.

Resistance compensation restores 75% of the damage that resistance would remove on ordinary body hits: a native damage coefficient of 0.5 becomes 0.875, and 0.25 becomes 0.8125. Weaknesses, immunity, ignored damage types, and special weak-spot mechanics retain their native behavior. Explicit weak-spot hits receive no resistance compensation. Creatures identified by the game as bosses also receive no compensation; their combat damage types use the additional 0.5 multiplier and their normal resistances still apply. Generic damage, chopping damage, and pickaxe damage are excluded from both target-specific rules.

The balance target still needs combat measurements. Attack reach, terrain, hit locations, time spent attacking, and flying targets can limit effectiveness.

Recall is free and preserves identity, progress, and current health. Recalled companions do not heal in storage. After a companion dies, its identity and progress remain; once the death cooldown expires, it can return at full health. Recall produces no loot, and actual death loot is disabled by default.

Companion attacks protect players, tamed animals, player structures, trees, and rocks by default. Protection settings are configurable. An axe is not included yet.

Configuration

Configuration file:

BepInEx/config/de.steve.valheim.trollcompanion.cfg

In multiplayer, gameplay settings come from the server/host. Change troll type, limits, progression, costs, stats, cooldowns, and protection there. Key bindings, messages, markers, and the optional combat log remain local.

Configuration keys currently use German names. Useful entries include:

Existing configuration values are preserved during updates. Change Trolltyp or key bindings explicitly if an older configuration still uses Forest or G. Variant changes apply on the next summon.

To adopt the new defaults on an existing server, explicitly set GrundLebenMultiplikator = 10 and GrundSchadenMultiplikator = 6 in its [Kampf] section. The new resistance and boss settings are also controlled by the server. Combat values are captured on summon and stored on the companion's network object, so changing its network owner does not change its balance. Updated settings apply on the next summon. Stored absolute health is retained, up to the new maximum; increasing maximum health does not grant free healing.

Enable [Diagnose] Kampfprotokoll = true locally when collecting combat measurements. It records actual HP changes for companion hits that reach native damage application; weapon diagnostics also identify native club profiles and damage types. Hits rejected earlier produce no entry, so a missing entry does not establish resistance. For multiplayer measurements, collect logs from the peer processing the damage.

Placement and failed casts

The same strict ground and clearance checks run before casting and before the companion appears. If the direct target is obstructed, the mod searches for a suitable nearby spot within 3 meters. The selected spot stays fixed through the casting animation, even if you move the camera. Rejected ground, water, steep slopes, and blocked space produce a specific message.

With [Kosten] ErstattungBeiFehler = true, a confirmed technical spawn failure refunds the Eitr and health actually deducted locally for that cast, once. A known local failure before sending the summon request can be refunded directly; after a request was sent, the server must confirm the failure. Early rejection before casting costs nothing. Death, recall, portal use, disconnecting, and leaving range do not qualify for refunds. A timeout alone is not confirmation of failure and does not trigger a refund. Native resource caps still apply, and a refund does not revive a dead player. Set the option to false to keep paid costs after technical failures as well.

Save data

The server/host stores companion data separately for each character and world:

BepInEx/config/TrollCompanion/worlds

Include this directory in server backups. Keep it when updating the mod.

The server validates ownership, summon generation, network-object identity, and request order before accepting a name. It atomically saves the name and native content-author information before applying the change to the live companion. A failed save does not approve the rename.

Existing schema-1 files are read and upgraded to schema 2 on the first successful save. Companion IDs, kills, and HP are retained; no reset is needed.

Multiplayer troubleshooting

Since version 0.2.6, ZIP entries have a deterministic timestamp that changes with the plugin version. This addresses BepInEx reusing old cached plugin metadata after an update. Update the server/host and every client to 0.2.9, then restart them. Keep existing configuration and companion data; no reset is required.

Version 0.2.5 fixes a player-identity lookup that could leave clients at Begleiterbestand wird synchronisiert (companion roster synchronizing). Update the server and all clients together.

After connecting, check BepInEx/LogOutput.log for:

• Server: TrollCompanion-Handshake bestaetigt
• Client: erste Bestandsantwort vom Server empfangen

The first response may still report that the player's network object is arriving. If the wait persists, check the server log for TrollCompanion-Handshake wartet and its reason.

Earlier local logs show summons and a server roster response. These observations do not establish full multiplayer compatibility or validate the new name-persistence flow. In-game validation remains pending.

Changelog

See the Changelog tab on Thunderstore or CHANGELOG.md in the package for version history.

Changelog

This development history includes builds that were not published on Thunderstore.

TrollCompanion is a gameplay preview. Full single-player, co-op, and dedicated-server testing is still pending.

0.2.10

• Added an F6 companion panel that works without the Trollstaff. View each companion's name, status, health, stars, kills, next star threshold, death cooldown and club attack values; recall one active companion from its row.
• Translated current mod messages, controls, configuration labels and descriptions, diagnostics and documentation into English. Native game text still follows the game's language.
• Added automatic migration from the previous German configuration keys. Existing files receive a separate backup; other saved settings are preserved. The health and damage base multipliers are each set to 2 once during this migration. Later edits are retained.
• Added live configuration reload after a file has remained unchanged for about one second. The host validates and synchronizes a complete rules snapshot; invalid edits leave the last accepted rules in use.
• Changed the default health and damage base multipliers to 2. Default maximum HP is 1200/2400/3600 and club damage scales by 2/3/4 at 0/1/2 stars. Live balance changes preserve the health percentage; star gains still preserve absolute HP.
• Added schema-3 storage for health together with its maximum, applied balance, star count and state revision. Existing schema-1/2 records keep their names, identities and progress. If the former maximum cannot be established, migration preserves absolute HP instead of guessing a percentage.
• Added optional shared kill progress, enabled by default within 25 metres of the defeated enemy. Only the same owner's nearby living active companions share a kill; the killer always receives its own kill. Each kill awards Blood Magic XP once, regardless of recipient count.
• Added validation for stale individual-recall requests, paired health updates, shared-kill eligibility and event deduplication. Update the server/host and every client together to 0.2.10.

Local automated checks cover these rules and migrations. Full in-game validation, including the panel, live reload and shared progress on a dedicated server with two clients, remains pending. See the project build report for the final build and package results.

0.2.9

• Fixed custom troll names being lost after recall. Names and native content-author information are now stored with the persistent companion record and restored after resummoning, variant changes, death, restarts, and temporary slot restrictions.
• Added server validation of the name request's owner, summon generation, network object, and sequence. An accepted name is saved atomically before it is applied to the live companion.
• Kept the normal naming dialog and its 10-character limit. Clearing a name restores the native default; extra star indicators above two stars remain visible without becoming part of the stored name. No new controls or settings are required.
• Added schema-2 name storage while retaining support for schema-1 saves. Existing data is upgraded on the first successful save without changing companion IDs, kills, or HP.
• Kept combat balance and technical-failure refunds unchanged from 0.2.8. Update the server/host and every client to 0.2.9.

Names already lost by older versions cannot be reconstructed; rename those companions once. The release build, API checks, and 82 regression tests passed. In-game name-persistence tests remain pending.

0.2.8

• Raised the default health multiplier to 10 and club damage multiplier to 6. At 0/1/2 stars, default scaling gives 6000/12000/18000 maximum HP and ×6/×9/×12 club damage.
• Added server-synchronized [Kampf] ResistenzDurchdringung, default 0.75. On ordinary body hits against hostile non-boss creatures, it restores 75% of the damage lost to resistance. Weaknesses, immunity, ignored damage types, and special weak-spot mechanics retain their native behavior.
• Added [Kampf] SchadenGegenBosseMultiplikator, default 0.5. Game-identified bosses retain their resistances and receive this additional multiplier on combat damage types; resistance compensation does not apply to them. Generic, chopping, and pickaxe damage are excluded from both target-specific rules.
• Saved combat settings on the summoned companion's network object so they remain consistent when network ownership changes. New settings apply on the next summon; stored absolute health is retained without free healing.
• Added optional local [Diagnose] Kampfprotokoll, disabled by default, for actual HP changes from companion hits, plus weapon-profile and damage-type diagnostics.
• Kept the placement checks and technical-failure refunds from 0.2.7. Existing configuration values remain unchanged: existing servers must explicitly set the health and damage multipliers to 10 and 6 to adopt the new defaults.

The release build, API checks, and 66 regression tests passed. The balance target is strong performance against ordinary Ashlands and Deep North enemies while preserving sustained boss fights. No 0.2.8 in-game combat results are available yet; flying targets, hit detection, terrain, and attack uptime require testing.

0.2.7

• Raised the default base health multiplier to 3. With the inspected 600-HP forest troll base and default star scaling, maximum health is 1800/3600/5400 at 0/1/2 stars.
• Preserved existing configuration values. Existing servers must explicitly set [Kampf] GrundLebenMultiplikator = 3 to adopt the new default. It applies on the next summon and retains stored absolute health, up to the new maximum, without free healing.
• Added shared strict placement checks before casting and spawning, with a search for a suitable spot within 3 meters. The selected point remains fixed during the casting animation, and placement failures report their cause.
• Added the server-synchronized [Kosten] ErstattungBeiFehler option, enabled by default. A confirmed technical spawn failure can refund the Eitr and health actually paid locally for that cast, once, subject to native resource caps.
• A known local failure before sending the summon request can be refunded directly. After a request was sent, the server must confirm the failure.
• Excluded death, recall, portal use, disconnection, and leaving range from refunds. A timeout without confirmed server failure does not trigger a refund.

Build/API checks and 56 local regression tests passed. No 0.2.7 in-game test has been completed. The latest local 0.2.6 log confirms several summons and the first server roster response, but full multiplayer acceptance remains pending.

0.2.6

• Fixed package timestamps that caused BepInEx to reuse cached 0.2.4 plugin metadata even when the correct 0.2.5 DLL was installed. ZIP entries now use a deterministic timestamp that changes with the plugin version.
• Gameplay and saved companion data are unchanged. Keep your configuration and companion saves; no data reset is required.
• Update the server/host and all clients together to 0.2.6.

An in-game retest of the update and dedicated-server synchronization is still pending.

0.2.5

• Fixed player-to-companion roster lookup for dedicated servers and co-op hosts, addressing the persistent "Begleiterbestand wird synchronisiert" message.
• Added connection checks for respawning, reconnecting, and duplicate character sessions, plus clearer synchronization diagnostics.
• Existing companion data is retained; no data reset is required. Update the server and all clients together.
• Added English package details and a packaged changelog.

The multiplayer fix has passed local code checks; an in-game retest is still pending.

0.2.4

• Updated the package and plugin version for Thunderstore distribution. Gameplay is unchanged from 0.2.3.

0.2.3

• Fixed summoning being blocked by the native arrival effect's GlobalWind component.
• Improved diagnostics and messages to distinguish arrival-effect failures from unavailable troll variants.

0.2.2

• Made the Ashlands troll the default companion variant; Forest remains configurable.
• Changed the default target-command key to J to avoid the game's radial-menu binding. H still restores following.
• Added the Trollstaff's native arrival effects, timing, impact sounds, and wake-up animation, using separate effect copies with impact damage disabled.
• Reserved companion slots during arrival and added cancellation for interrupted summons.

Existing configuration files keep their saved variant and key settings.

0.2.1

• Fixed club validation rejecting the troll's two native club attacks as ambiguous equipment.
• Preserved both club attack animations and equipped a club before the companion's first fight.

0.2.0

• Added the initial gameplay preview: friendly club-wielding trolls, summon and recall commands, following, attack-move, focus attacks, and position holding.
• Added persistent companion slots, kill progression, stars, death cooldowns, and configurable gameplay and damage-protection settings.
• Added host-managed companion storage and multiplayer messaging for testing across single-player, co-op, and dedicated servers.

0.1.0

• Added the minimal BepInEx plugin with the startup message TrollCompanion geladen.
• Added the initial build and deployment setup. This version did not change troll behavior.