LOJU Tunnelheim Companion 0.8.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. Version 0.8.1 adds a next-work marker and Continue / Retry when a queue pauses.

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 package contains the unchanged, previously tested 0.8.1 DLL; packaging did not add new features or perform new game tests.

Requirements and installation

Tested dependency baseline:

• Tunnelheim 1.0.0: Tunnelheim-Tunnelheim-1.0.0
• BepInExPack Valheim 5.4.2351: denikson-BepInExPack_Valheim-5.4.2351
• Jotunn 2.30.2: ValheimModding-Jotunn-2.30.2

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.8.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. Turn excavation ON with F4. Use Tunnelheim's shape key, normally F7, to cycle Round -> Square -> Canal.
2. Click visible terrain within 32 m to place at least two centerline points, at least 2 m apart. Use the point list and Move, Insert after or Remove controls to edit the draft.
3. Adjust Bottom width, Water depth and Bank blend per side. 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. 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.

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 hold Right Alt to interact: release Right Alt to move/look, hold it to operate the panel or place points. 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). Right Alt may act as AltGr or conflict with overlays. Focus loss, chat, inventory and native menus suspend interaction; release and press the modifier again afterward. Physical keyboard/mouse combinations are not exhaustively verified.

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 excavates terrain only: 0.8.1 does not automatically remove trees, twigs, rocks, ore, buildings or other obstacles. Clear obstacles normally first.

Ultra Lazy uses the current Canal cut size and bounded 4 m sections, at most one cut per 0.25 seconds, with saved-record and terrain-rebuild checks between cuts. It can be slow, especially when banks require small cuts; Bulk is not a promise of rapid whole-route excavation. 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 and 256 per sample.

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.
• Release the optional interaction modifier to walk; hold it again to click.
• 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 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

See VALIDATION.md for detailed 0.8.1 evidence. Focused offline checks, private instrumented single-player recovery tests, saved terrain/process restart and production-only startup passed. Physical UI input and authenticated multiplayer were not comprehensively tested. Older broad ore/hoe/building/water and Drakkar suites were not rerun for 0.8.1.

• 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.

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 and cut size; 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, its original 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.