Valheim
Install with App

Details

Latest version
0.9.2
Last Updated
First Uploaded
Downloads
298
Likes
0
Size
1.1MB
Dependants
ADDatHost Valheim hosting
30% off

LOJU Tunnelheim Companion 0.9.2

An independent companion for Tunnelheim 1.0.0, shared for community testing and feedback. Adds a per-player excavation toggle, a centerline Canal planner with blended banks, and the explicitly confirmed Ultra Lazy excavation queue. Includes a next-work marker and Continue / Retry when a queue pauses. Version 0.9.0 adds independently sized Ultra Lazy cuts, conservative natural scenery clearance, adjustable rounded corners, endpoint continuation and the /thcompanion chat command. Version 0.9.2 expands audited bush/log clearance and improves blocker details, changes optional menu interaction to press-on/press-off, and adds continuous point placement. The custom panel, title, button and slider artwork is retained. Live labels and values remain readable and interactive; the body scrolls at smaller resolutions. The approved package icon is unchanged.

Experimental: tested in a private single-player setup; authenticated multiplayer is unverified. Back up your worlds, characters and profile first. Try a separate mod profile and disposable world before using important saves. This is an experimental community candidate. See VALIDATION.md for focused checks and the distinction between current and earlier gameplay evidence. The older broad ore/hoe/building/water matrix was not repeated.

Requirements and installation

Tested dependency baseline:

The tested game baseline was Valheim Steam build 25909357 / Unity 6000.0.75f1. Other game/dependency versions are not guaranteed compatible. The companion checks required Tunnelheim version/API compatibility; an unsupported API disables companion patches with a log warning/error, not Tunnelheim itself.

Install through your Thunderstore-compatible mod manager once the package is listed, with its dependencies. For local ZIP import in r2modman: Settings > Profile > Import local mod > Select file, then select the ZIP without extracting it. Verify package name TunnelheimCompanion, package version 0.9.2. Local import does not fetch dependencies, so install those first. Keep exactly one companion DLL.

For manual installation, with the game/server stopped and the dependencies installed, place plugins/TunnelheimBuildingFix.dll under BepInEx/plugins/LOJU-TunnelheimCompanion/.

For multiplayer experiments, use the same companion version on every client and the server, with matching Tunnelheim/dependency versions. Clients need it for input; any peer that owns affected terrain needs the matching adapter. Mixed companion versions are unsupported. This requirement is not a claim that multiplayer has passed testing.

F4: excavation OFF / ON

Every new local player/world session starts OFF, including restart, rejoin, character change and respawn. Press F4 to opt in. OFF does not unload Tunnelheim or delete existing tunnels.

  • ON: retains Tunnelheim digging and hoe shaping. An attack that reaches both ore and ground can excavate both.
  • OFF: keeps native ore damage/drops and exterior terrain mining. Native swings may still hit ore and ordinary ground together. Accepted exterior height/paint edits are reconciled at tunnel boundaries.
  • OFF hoe raising, surface leveling/smoothing, path and paving use native limits and resource requirements. Add Earth maps to native Raise Ground; Smooth Surface maps to native surface leveling. Interior shaping and tools with no native exterior equivalent, such as wall/ceiling/stairs, require ON and provide refusal feedback while OFF.
  • The exterior/interior classifier uses the highest loaded voxel surface; a target more than 0.75 m below it is considered interior. Cliffs, overhangs and thin roofs remain limitations. Very shallow cavities are not universally protected.
  • Embedded ore is mineable if the attack reaches its collider. OFF does not remove enclosing interior terrain to expose it.

Configuration is saved in BepInEx/config/local.tunnelheim.buildingfix.cfg. ToggleKey = F4 is configurable. Legacy EnabledOnStart is ignored; startup is always OFF. Config reload preserves the active session's choice. Check other mods/overlays for key conflicts, and never use Alt+F4 as a toggle.

Plan a Canal

  1. Type /thcompanion in in-game chat to open the planner, including while excavation is OFF. The command selects Canal but never enables excavation, starts digging or resumes a job. Alternatively use F4 ON and Tunnelheim's shape key, normally F7, to cycle Round -> Square -> Canal. F7 cycling remains unchanged; leaving Canal hides its guide.
  2. Click Add, release that click, then aim and left-click terrain within 32 m for each centerline point (at least two points, at least 2 m apart). Right-click or Escape returns to the planner. Use the point list and Move, Insert after or Remove controls to edit the draft.
  3. Adjust Bottom width, Water depth, Bank blend per side and Corner radius. Previewing changes no terrain. Confirm guide saves the target and closes the panel.
  4. Equip a pickaxe and excavate toward the green target. Cut direction follows the guide, not which way you face. Cycle away from Canal and back to reopen the planner.
  5. Close retains a draft. Cancel draft restores the confirmed guide. Clear draft affects only draft points. Delete saved plan... > Yes, delete plan removes the current world/character's guide, draft and preview, never excavated terrain.
  6. Continue from last point... starts a fresh bounded draft from the confirmed endpoint. A locked 2.5 m starter preserves its outgoing direction; dimensions and corner radius are copied. Add the next endpoint, preview and confirm. The old guide can be unfinished: this does not finish or resume its queue. Cancel draft restores the old confirmed guide. New confirmation replaces the one active local guide, without restoring or undoing old terrain. The two starter points count toward the normal limit.
  7. After restarting, select Canal and use Load guide for that world/character. Guides are local; other players do not automatically share your planning markers.

Bottom width: 2-32 m. Depth: 0.5-10 m below sea level. Bank blend: 2-24 m per side. Defaults 14 / 3 / 8 are provisional, not proven minimum Drakkar clearances. Routes are limited to 16 points, 96 m and 80,000 loaded surface samples. Crossings and near-reversals are rejected. Corner radius 0–24 m, default 6 m on new plans, rounds inside the placed corner points; short segments reduce the requested radius. Zero keeps sharp corners. These are bounded circular fillets, not a freeform spline that passes through every corner. The preview shows the actual compiled route. Existing saved guides retain their old geometry until adjustable corners are explicitly enabled.

Banks are rounded/sloped within the native voxel grid, not perfectly smooth. Narrow banks on high ground can be steep; widen the blend for gentler banks. Existing lower terrain is not filled. Water is not created above sea level. Ship entrances, turning, draft, waves and clearance need their own disposable-boat test.

Deleted guide metadata is retained under BepInEx/config/TunnelheimCompanionGuides/Deleted for manual recovery while the game is closed; it is never automatically loaded. Guide deletion is not terrain undo.

Cut size and moving with the panel

Fine / Original / Bulk and the cut-size slider select a maximum radius of 0.25-3 m, default 0.75 m. Actual cuts shrink at banks, the bed and guide edges. Manual swings retain ordinary stamina/durability costs and per-dig stone-drop chance; costs/drops are not multiplied by excavated volume. Fine settings may barely affect the 0.5 m voxel grid. A long canal still takes many cuts.

The panel defaults to modal editing. Optionally click Enable Right Alt menu toggle: press Right Alt once for menu interaction, press it again to walk/look with the panel visible. Releasing the key does not change the state. The status line shows MENU ON or MENU OFF. Attacks remain blocked while the planner is open. Close it and release held mouse buttons before digging. Use modal editing instead restores modal behavior.

[Canal] MenuInteractKey supports RightAlt, RightControl, LeftAlt or None (modal). Existing optional-key settings now use toggle semantics. Right Alt may act as AltGr or conflict with overlays. Close/reopen, focus loss, chat/text input, other native menus, death and session changes reset the interaction latch; release and press the key again to interact. This is separate from F4 and never enables excavation or starts/resumes Ultra Lazy.

Continuous Add

Click Add to enter temporary point placement. The panel gives way to a compact placement hint and center-screen terrain target. Release the Add click first, then walk/look and left-click once for each point. Right-click or Escape returns to the planner with the draft retained. No hammer or inventory item is created, equipment is unchanged, and planning never digs. Attacks are blocked during placement.

Point placement retains the 16-point/96 m guide bounds, minimum point spacing, rounded-route checks and 32 m terrain-target reach. An invalid placement click ends placement with a reason so you can adjust the draft. Reaching limits, focus loss, other menus, death, mode or session changes end placement; it does not automatically resume. Preview and confirm the draft before using it for excavation. Move/Insert remain individual editing actions.

Ultra Lazy

With Canal selected and a confirmed guide, reopen the planner, click Ultra Lazy, review the planned operation, then click Confirm Ultra Lazy excavation. Preparation is non-destructive. There is no separate global hotkey.

This deliberately confirmed operation is free: no stamina, durability or material drops. Normal manual mining is unchanged. It can remove audited natural scenery without loot: loose branches/stones, selected ordinary rocks, trees, stumps and logs. Planted trees are included. Whole renderer/collider footprints must fit inside the confirmed guide, and the anchor or a solid collider must intersect the actual cut. Bounds merely touching a guide are insufficient. Whole-object removal is destructive: inspect your plan before confirming. Large canopies or objects partly outside the plan may require manual clearing.

The initial whitelist is deliberately narrow: Pickable_Branch, Pickable_Stone, Rock_3, Rock_4, Beech1, Beech_small1/2, Birch1/2, Oak1, PineTree, FirTree, Beech_Stub, Birch_log, FirTree_log and PineTree_log. Unexpected components refuse removal. Other rock/tree variants are not implicitly allowed. Buildings, ships, wards, ore, creatures, unknown objects and foreign-owned records remain protected. No ownership is claimed. Nearby creatures or structures can block otherwise eligible scenery.

Ultra Lazy has its own maximum auto-cut radius slider: 0.75–6 m, default 6 m ([Ultra Lazy] MaxAutoCutRadius). The manual 0.25–3 m slider is unchanged. Center-first scheduling opens the canal core sooner; banks/bed still shrink cuts to fit the saved target. Work is scheduled in bounded 4 m sections, with at most one cut or scenery removal per 0.25 seconds and saved-record/mesh checks between operations. A physical cut can cross a section boundary while remaining inside the confirmed guide. Fine bank finishing can still take many cuts; no whole-route speedup or few-hit completion guarantee is made. The progress percentage counts surveyed guide samples, not excavated volume. Voxel-scale no-progress samples are reported for manual surface review. Limits are 20,000 accepted cuts per run, 256 per sample and 256 scenery removals per run. Removal receipts prove local record deletion; authenticated remote-peer behavior remains unverified.

Paused? Follow the magenta work marker

The magenta cross and tall marker show the next cut, with section, distance, camera-relative direction and X/Z coordinates. It is not a safe standing spot.

  • Too far: move within 32 m of the marker.
  • Too close: move outside the displayed clearance while staying within 32 m.
  • Press the optional interaction key to switch between walking and menu interaction.
  • After resolving the condition, click Continue / Retry (recheck next work). Moving closer never automatically resumes excavation.
  • Loading/rebuild messages: allow normal loading/synchronization, then Retry. Foreign ownership, protected areas and obstacles are separate refusals; moving is not a universal fix. No ownership claims or protection bypasses are made.

Retry retains the cursor, saved-cut counts and operation budget, then checks current terrain and context again. An uncertain/unverified cut or exhausted hard budget cannot be resumed through Retry.

Stop excavation remains visible above scrolling controls. Stop, closing/Escape, F4 OFF, shape/guide/session changes, death, focus loss or lost authority ends the job. Completed edits remain. Stopped/stale jobs cannot be resurrected by Retry. There is no saved background job, automatic resume or whole-route undo. Tunnelheim's limited per-cut undo history cannot restore an entire canal.

Known limits and testing

Scenery clearing uses an exact native prefab/component allowlist, not every rock or bush from every biome/mod. Supported additions include Bush01, Bush02_en, raspberry/blueberry/cloudberry bushes and native fallen/half logs. Whole renderer/collider bounds must fit the confirmed corridor, actual cut intersection must be established, and the anchor must be above the retained bank/bed. Buildings, wards, ships, ores, unknown objects and foreign-owned/unready records remain blockers. An invisible collider is not presumed safe. Refusals now identify unsupported collider paths, position/layer/trigger details or prefab coordinates; include that text in bug reports. The exact original phantom-bush scene has not been identified from logs.

See VALIDATION.md for exact current verification. Physical keyboard/mouse interaction and authenticated multiplayer are not verified for this patch. Older broad ore/hoe/building/water and Drakkar suites were intentionally not rerun.

  • The narrow building correction addresses a reproduced dry-tunnel aiming ray hitting the sea-level water collider. Genuine underwater, collision, slope and other native placement restrictions remain. It does not establish the cause of every underground building rejection.
  • Known but unavailable/unreadable/pending tunnel data may block edits. Native terrain and voxel reconciliation are not atomic; on an unexpected reconciliation/save failure, stop and preserve evidence and backups. Retry is not a repair guarantee.
  • Thin roofs, shallow cavities, cliff classification and fully occluded ore remain important edge cases.
  • Earlier single-player parked-ship reload damage remains unresolved. Persistent dedicated servers still have client/zone loading; uptime does not eliminate that risk.
  • Multiplayer ownership migration, late joins, simultaneous edits, remote costs/refunds and restart persistence need testing with consenting peers on a disposable server/world. Matching versions alone do not establish correctness.
  • There is no guarantee of compatibility with other terrain/building mods or future game/Tunnelheim updates.

Update, rollback and saves

Close the game/server and back up the profile/config plus worlds/characters before changing versions. Keep one companion DLL and coordinate client/server versions. Local/manual mods can be omitted by shared-profile imports or removed by Update existing profile; reimport the ZIP when needed.

New adjustable-corner guide files use local format 2. Older Companion releases cannot load them; existing legacy format 1 guides preserve exact geometry, and the first migration keeps a .v1-before-rounded backup. Back up the whole guide folder before upgrading. Reverting the DLL does not revert saved terrain or automatically restore older guides. Native Tunnelheim operation serialization is unchanged.

To remove only this companion, disable/remove its plugin while the game is closed. This does not restore completed terrain edits. Keep Tunnelheim installed when loading tunneled worlds: its author warns that loading affected areas without it deletes tunnel objects and restores terrain. Use backups for rollback experiments; do not test removal on an important world. Do not downgrade to companion 0.3.0.

Reporting an issue

Please include:

  • Valheim build, companion version, Tunnelheim/BepInEx/Jotunn versions, other relevant mods and changed configuration.
  • Single-player or dedicated/listen server; client/server versions and which player performed the edit.
  • Numbered reproduction steps, expected result and actual result; whether it repeats in a disposable test profile/world.
  • F4 ON/OFF, shape/mode, guide dimensions, corner radius and manual/automatic cut sizes; Ultra Lazy section/status and the exact refusal/error text.
  • Relevant BepInEx/LogOutput.log excerpts, screenshots or a short video, and whether the result persists after save/reload. Remove credentials, IP addresses and private paths before sharing logs.

Use the Discord community link below for feedback and bug reports. Preserve a backup if terrain differs between peers or an operation reports an uncertain save; avoid repeating destructive actions merely to gather a report.

This archive contains only the independent companion DLL with embedded original approved UI artwork, the approved icon and documentation. Tunnelheim and other dependencies are installed separately; no upstream binaries/assets, diagnostic harness, game assemblies or test saves are bundled.

Feedback & Bug Reports

Join the SmeagsMods Discord community to share feedback and report issues. Please include the versions, reproduction steps, toggle/mode, relevant logs and screenshots described in the bug-report checklist above.

Thunderstore development is made possible with ads. Please consider making an exception to your adblock.