Install with Gale
HearthBelow
Dig caves. Build underground. Bring the hearth below.
HearthBelow transforms Valheim’s terrain wherever you dig, allowing you to carve real tunnels, hollow out mountains, and build permanent underground homes.
Digging remains grounded in Valheim’s progression: pickaxes carve terrain gradually, stronger tools reach greater depths, creatures can follow you underground, and anything built without proper support can still collapse. Existing worlds are supported, untouched terrain remains unchanged, and all cave edits persist through Valheim’s normal world-saving and multiplayer systems.
⚠️ BACK UP YOUR WORLD ⚠️
It does not modify vanilla save data or worldgen, but it changes how terrain looks and behaves in modified zones, and underground builds only make sense while the mod is installed (see Removing the mod below). Make backups before using it.
What it does
- A bigger bite costs more. Widening your dig scales the swing's stamina and tool wear by how much more rock it removes, so a wide blast costs several times a narrow scoop and a small dig costs less than vanilla. It works by scaling vanilla's own numbers, so the pre-swing stamina gate, the skill discount, food and equipment modifiers all still apply - run out and the swing is refused with the usual bar flash. A swing that does not dig - blocked by a ward, inside a protected location, or already at your pickaxe's depth limit - costs nothing extra. Admins can retune or disable it.
- Pickaxe digs caves. Any pickaxe carves material out of the terrain instead of lowering it - dig sideways into a hillside, sink a shaft, hollow out a mountain. Digging is gradual like vanilla (each swing bites in the direction you're swinging) and drops stone like vanilla. Better pickaxes dig deeper: depth is capped by tool tier (antler/stone 8m, bronze 16m, iron 48m, blackmetal 128m by default), so modded pickaxes fit in automatically. Digging at a tool's cap leaves a flat, even floor - handy for lining up builds. How wide a hole a tier digs can be capped the same way (off by default), and a tier in neither list follows the step the listed ones climb by, so a modded flametal pick lands above blackmetal instead of digging uncapped.
- See it before you swing. Hold a pickaxe and the ground is painted where your next hit will land, with a ring
around the real edge and a mark on the exact point the head will connect. It is a prediction, not a decoration: it
runs vanilla's own melee sweep early and tests the result against the live voxel field, so it accounts for your swing
angle, the shape and mode you are on, space that is already hollow, and your pickaxe's depth limit. A readout shows
the tool, shape, mode, size and how many cubic meters the swing would actually remove. Hold the dig modifier (default
Left Alt) and the mode bar fades in: the mouse wheel resizes the dig a notch at a time,Zswitches shape,Vswitches gradual/blast. The size bar reads across, from zero to the admin cap, with the stretch your pickaxe cannot reach shaded out, so your own ceiling and the server's are both on screen. No config file, no relog, and the wheel is taken off the camera only while the bar is open. Admins can cap the radius players may pick, or lock the whole thing off. - Faithful terrain conversion. The first carve in a 64×64m zone converts that zone's heightmap (including existing terrain edits) into a voxel volume and swaps rendering + collision over seamlessly. Untouched zones are unaffected, and vanilla terrain tools keep working on voxelized zones.
- Live underground. The voxel surface behaves like normal terrain: building, ground support, grass, biome detection, footsteps, and fires all work. The hoe works underground too and feels like the surface hoe: raise ground grows the floor in the same small vanilla-sized steps, level/smooth shape the cave floor (without eating low ceilings), paths/paving paint it. Deep enough down, a dungeon-style ambience fades in (configurable per player, or off). Log out in a cave and you log back in there; tombstones, drops, and loot stay down instead of popping topside.
- Weather stays outside. Rock overhead counts as shelter: rain, snow and ash stop falling on you underground, the
ground stops looking wet, and you get vanilla's Sheltered buff, muffled indoor sound and calm air - the same as
standing in a roofed house. Weather still reaches in near a cave mouth, and
hearthbelow weatherexplains why any given spot does or doesn't count. - Creatures follow you in. The navmesh is built from the voxel terrain, so monsters path into your tunnels. Sealing the entrance with raised ground still works as a defense.
- Multiplayer + persistence. Works on existing worlds. Carves are tiny operations stored on the same networked object vanilla uses for terrain edits (the zone's TerrainComp ZDO), so they save with the world and sync through vanilla's own machinery. No custom save format, no extra files.
Installation - required on server AND all clients
This is a terrain-consistency mod. Everyone in the world must have it, same version:
- Dedicated server: required. Enforces the version handshake (mismatched clients are kicked) and is the config authority via ServerSync.
- All clients: required. A player without the mod would see no caves and walk on phantom terrain above your tunnels.
- Crossplay: console players cannot install mods - run your server without crossplay.
Singleplayer / local hosting works out of the box.
Console commands
The terrain-editing ones (carve, fill, raise, flatten, smooth, restore) are admin only on a server. They act
on the terrain under your crosshair, up to 100m away, with an optional radius argument between 0.25m and 6m (default:
your Carve Radius config).
hearthbelow carve [radius]- carve at the crosshair (always full radius, no gradual bite).hearthbelow fill [radius]- fill material back in at the crosshair.hearthbelow raise [radius]- raise the ground at the crosshair, like the hoe.hearthbelow flatten [radius]- level the floor at the crosshair and carve headroom above it.hearthbelow smooth [radius]- blend the floor toward the crosshair height with falloff.hearthbelow restore- remove all voxel edits in the zone you are standing in (including digs crossing in over its borders) and restore the vanilla heightmap. Careful: entombs anything built in that zone's caves.hearthbelow restore [radius]- fill in only the digs centred within that radius, plus any dig the spot itself is inside. Carves are all-or-nothing, so a dig is filled whole or left alone.hearthbelow info- voxelization info for your current zone (this is the default with no argument).hearthbelow weather- why the spot you're standing in does or doesn't count as sheltered.hearthbelow compat- which mods (including this one) are patching the terrain pipeline, read straight from Harmony, plus whether the zone you're in is voxelized. Paste this when reporting a conflict with another terrain mod.
Diagnostics, mostly useful when reporting a bug (output also goes to the log):
hearthbelow show [all|voxel|vanilla|lod]- draw only one of the three terrain meshes within 300m, to see which one an artifact belongs to.allrestores normal rendering.hearthbelow holes [tolerance]- look for unclosed mesh edges between neighbouring zones within 24m.hearthbelow remesh- rebuild every chunk mesh in your current zone.hearthbelow meshinfo- mesh, renderer and material details for the ground you're on.
Config (synced from server, except where noted)
| Setting | Default | Description |
|---|---|---|
| Lock Configuration | On | Only server admins can change the synced settings |
| Voxel Digging | On | Pickaxe carves caves instead of lowering terrain (master switch, also gates cave shelter) |
| Dig Mode | Gradual | Gradual = shallow vanilla-like bites per hit, Blast = full radius at once |
| Dig Depth Per Hit | 0.75 | How deep each hit bites into the surface (Gradual mode) |
| Carve Radius | 1.6 | Radius of the dig per pickaxe hit, so the hole comes out twice this across (minimum 1m) |
| Dig Shape | Cube | Cube = flat floors/walls/ceilings, Sphere = round organic caves |
| Max Cave Depth | 128 | How far below the original surface you can dig, no matter the tool. Higher = more memory per dug zone |
| Tool Depth Limits | On | Cap dig depth by pickaxe tool tier (digging at a cap leaves a flat, even floor) |
| Tool Tier Depth Limits | 0:8,1:16,2:48,3:128 | Tier:meters pairs (antler 0 … blackmetal 3); unlisted tiers follow Extend Tool Tier Limits |
| Tool Tier Size Limits | (empty) | Tier:meters pairs capping how wide that tier digs, measured across; empty = no size limit |
| Extend Tool Tier Limits | On | A tier missing from those lists inherits the step they climb by (tier 4 depth = 208m); off = unlisted tiers are uncapped |
| Max Carves Per Zone | 5000 | Safety cap on stored operations per 64×64m zone |
| Allow Dig Customization | On | Let players change radius/shape/mode on the fly; off = everyone digs with the settings above |
| Max Player Carve Radius | 3 | Admin cap on the radius a player may pick (max 8, so 16m across), re-enforced on the zone owner |
| Radius Cost Scaling | 2 | Scales stamina and tool wear by how much more rock a swing takes than a default one (3 = tracks volume exactly, 0 = off, 100x ceiling) |
| Dig Yield Scaling | 3 | Scales the stone a swing drops the same way (3 = same per cubic meter at any size, 0 = vanilla drop, 100x ceiling) |
| Underground Environment | Darklands_dark | Cave ambience (also: Crypt, SunkenCrypt, Caves, InfectedMine; empty = outside weather). Per player, not synced |
| Underground Environment Depth | 16 | Meters below the surface before the ambience fades in (default = bronze's dig limit). Per player, not synced |
| Underground Painting | On | Hoe paths/paving paint cave floors (also shows on the surface above - see limitations) |
| Cave Weather Shelter Cover | 0.6 | How enclosed a spot must be before weather stops reaching it (vanilla asks 0.8 for a house). Per player |
| Cave Weather Particles | rain,snow,sleet,hail,ash | Which particle effects rock overhead switches off, matched by name. Per player, not synced |
Dig controls (client-side, never synced)
| Setting | Default | Description |
|---|---|---|
| Dig Preview | On | Show the overlay while a pickaxe is out |
| Toggle Dig Preview | Alt + B | Turn the overlay off/on in game; remembered between sessions |
| Dig Readout Timeout | 4 | Seconds the text under the overlay stays up after a change (0 = always) |
| Dig Readout Tool Name | Off | Include the pickaxe's name in that text |
| Dig Preview Fill | On | Wash the ground inside the ring |
| Dig Preview Outline | On | The ring itself |
| Dig Preview Impact Marker | On | Mark the exact point the head connects, worked out before the swing |
| Dig Preview Impact Marker Size | 0.14 | Radius of that mark, in meters |
| Dig Preview Color | pale blue | Fill colour |
| Dig Preview Outline Color | blue | Ring and impact mark colour - keep it brighter than the fill |
| Dig Preview Fill Center Alpha | 0.1 | Wash opacity at the middle of the dig |
| Dig Preview Fill Edge Alpha | 0.42 | Wash opacity at the rim; higher than the centre fades inward like vanilla's |
| Dig Preview Line Width | 0.06 | Ring thickness in meters |
| Dig Controls Modifier | Left Alt | Hold to open the mode bar and take the mouse wheel |
| Cycle Dig Shape | Z | Sphere ↔ cube; only fires while the modifier is held |
| Cycle Dig Mode | V | Gradual ↔ blast; only fires while the modifier is held |
| Dig Size Step | 0.2 | Meters across per notch of the mouse wheel, same measure as the readout |
Keyboard and mouse only - gamepad bindings are not wired up yet.
Avoid changing Max Cave Depth on a world that already has deep caves - existing carves below the new limit will be
clamped away.
Terrain ops: what HearthBelow intercepts, and how vanilla is mirrored
If your mod also touches terrain, this is the contract. HearthBelow does not replace Valheim's terrain pipeline - it shadows it, per zone, and only in zones that have been dug.
Three patches, all prefixes:
| Patch | What it does |
|---|---|
Attack.SpawnOnHitTerrain (prefix) |
Records that a swing is landing, who swung, the approach direction, and the tool's depth cap. Sets no state of its own beyond that. |
TerrainOp.Awake (prefix) |
The one that matters. Decides whether this op becomes a voxel op, and clears the vanilla flags it has taken over. |
TerrainComp.InternalDoOperation (prefix) |
Belt and braces for ops that reach the compiler another way; clears the same flags on carved ground. |
In TerrainOp.Awake, exactly one of two things happens:
- A pickaxe hit (
InTerrainAttackis set by the attack prefix). I carve, then clearm_level,m_raiseandm_smoothon that op's settings so vanilla does not also lower the heightmap underneath us.m_paintClearedis deliberately left alone - the dig marks around the hole should still appear. - Anything else on carved ground (
VoxelWorld.IsCarvedGroundAt). The op's settings are read and replayed as voxel ops, in vanilla's own order - level, then raise, then smooth - and the same three flags are cleared. On terrain that has never been dug I do nothing at all and the op runs entirely vanilla.
The vanilla maths HearthBelow mirrors, taken from TerrainComp:
| Vanilla | HearthBelow | Notes |
|---|---|---|
LevelTerrain(pos, m_levelRadius, m_square) |
VoxelWorld.FlattenAt |
Hard set to the plane across the radius, no falloff, square or circle per m_square. HearthBelow also carves headroom above the plane, but never into a ceiling more than 1m over the old floor. |
RaiseTerrain(pos, m_raiseRadius, m_raiseDelta, m_square, m_raisePower) |
VoxelWorld.RaiseAt |
Per column: target = pos.y + delta·falloff, falloff = (1 - dist/radius)^power (1 when square or power ≤ 0), clamped to min(target, floor + delta·falloff), skipped when the target sits below the existing floor. Same as vanilla's num5 handling including its else continue. |
SmoothTerrain(pos, m_smoothRadius, m_smoothPower) |
VoxelWorld.SmoothAt |
Lerp(floor, pos.y, 1 - (dist/radius)^power), delta clamped to ±1. Circle only, as in vanilla. |
All three use m_levelOffset the same way vanilla does. Radii are passed through untouched - an earlier build
padded level to a 1.5m and smooth to a 2m minimum, which made every hoe stroke wider than vanilla on carved ground; that
padding is gone, and m_smoothPower is honoured instead of assuming vanilla's default of 3.
The pickaxe is the one place HearthBelow is deliberately not vanilla, because vanilla cannot dig caves. A hit
becomes a
CarveOp built by VoxelWorld.BuildCarveOp:
- Blast - a sphere or axis-aligned box of
Carve Radius, Chebyshev distance for cube and Euclidean for sphere. - Gradual (default) - an oriented scoop:
Carve Radiuswide across the swing,Dig Depth Per Hitdeep along it, where the direction ishitPoint - attacker eyeexactly asSpawnOnHitTerraincomputes it. This is what makes repeated hits bite in predictably instead of blowing a full sphere out of the first swing. - Both are clamped to the tool's tier depth cap, which is what leaves a flat floor at the limit.
Aim prediction (VoxelMagic/MeleeAim.cs) is a straight port of Attack.DoMeleeAttack's terrain sweep so the
preview can run before the swing: same origin (GetAttackOrigin() + up·m_attackHeight + right·m_attackOffset), same
attackDir from
GetMeleeAttackDir (note m_maxYAngle is 0 on pickaxes, so the swing follows the character's flat forward, not the
camera), the same m_attackAngle arc in 4° steps, the same
m_attackRayWidth sphere cast over m_attackRange - m_attackRayWidth, the same behind-the-swing rejection and the same
m_hitPointtype aggregation.
If you are writing a mod that edits terrain:
- Ops on undug zones are untouched - if your mod never runs where someone has dug, nothing changes for you.
- Ask
VoxelWorld.IsCarvedZoneAt(pos)/IsCarvedGroundAt(pos)before assuming a heightmap tells the truth. On a voxelized zoneHeightmap.GetHeightstill returns the surface, and knows nothing about the cave under it. - Custom
TerrainOp.Settingsare honoured through the same three-op path above, so a modded hoe piece works underground without changes as long as it goes throughTerrainOp. - Writing to
Heightmap.m_heightsdirectly will be overwritten on the next remesh of a dug zone. Go throughTerrainOp/TerrainComp, or callVoxelWorld.FlattenAt/RaiseAt/SmoothAt/CarveAt/FillAtdirectly. - Carves live on the zone's
TerrainCompZDO under theHearthBelow_VoxelOpskey. Wiping aTerrainComp's ZDO data wipes the caves in that zone. - Resetting a
TerrainCompback to un-edited will not remove a cave on its own, because a dug zone is not drawn from that heightmap anymore - clear the ops too, viaVoxelWorld.RequestClear(hmap). A "remove terrain modifications" op - one with level, raise, smooth and paint all switched off, which is how Searica's AdvancedTerrainModifiers marks its piece - is recognised and fills in the digs centred in that spot, plus any dig the spot is inside, instead. Carves are all-or-nothing, so a carve is removed whole or not at all. - Found a case where HearthBelow diverges from vanilla on undug ground? That is a bug - report it, since matching vanilla exactly is the goal everywhere except the pickaxe.
Removing the mod
Your world stays fully loadable - terrain reverts to the untouched heightmap and caves disappear until the mod is reinstalled (the data survives). However: anything built inside a cave ends up buried under the restored terrain and will likely collapse. Don't uninstall casually on a world with underground builds.
Good to know
- Undermining is real. Dig the ground out from under a building and it collapses, exactly like vanilla. Ore deposits and boulders are static props though - digging under one leaves it hanging in place.
- No cave-ins. Terrain has no gravity or structural simulation - overhangs and undercuts stay put.
- Protected locations stay protected. Digging is blocked inside no-build locations (boss altars, the trader, and so on). Vanilla dungeon interiors live far outside the terrain, so a tunnel can never break into one.
- Smoke is honest. A cave fire behaves like a fire in a sealed house - give the smoke somewhere to go or it will smother the fire, and then you.
- Dug your own grave? The hoe's raise ground builds a ramp back out. Worst case, the vanilla
dieconsole command works without devcommands.
How it works (for the curious)
Vanilla terrain is a heightmap: one height value per (x,z), and the ground mesh is that grid stitched into a surface. A tunnel would need two surfaces at the same (x,z), which the data structure simply cannot express - that's why vanilla has no caves.
HearthBelow replaces that, per zone and only when needed, with a density grid: a 3D array sampled every 1m where positive = solid rock and negative = air. The terrain surface isn't stored anywhere - it's wherever density crosses zero. A cave is just a pocket of negative values with positive values above and below it, so overhangs and tunnels come for free.
- Lazy conversion. Nothing is voxel until you dig. The first carve in a 64×64m zone samples its heightmap (including all existing terrain edits) into the density grid, meshes it, and swaps the meshes in for the vanilla renderer + collider in one go. The meshing is budgeted at a few ms per frame, so there's no hitch, and the result is shape-identical to the original terrain.
- Surface nets meshing. The mesh is generated by surface nets (a marching-cubes cousin): every grid cell where density flips sign gets one vertex, placed from that cell's edge crossings, and neighboring cells' vertices are stitched into quads. The result lands on the same layer with the same material as vanilla terrain, so building, grass, biome detection, navmesh, and footsteps don't notice the difference.
- Digging is subtraction. A pickaxe hit subtracts a sphere/cube of density; the hoe adds it back. Zones are meshed in 16×16×16 chunks and only the chunks that changed are remeshed, which is what keeps digging cheap.
- The distant terrain follows along. Valheim draws far-away ground as a coarse heightmap sheet that knows nothing about caves, which would otherwise show up as a wall, a sunken step, or a flat sheet hanging inside your tunnel. That sheet is cut away around dug zones near you and restored once you leave, so caves look right from inside without punching holes in the scenery at a distance.
- Persistence is replay. The grid itself is never saved - that would be megabytes. Instead, each dig is stored as a tiny operation on the zone's TerrainComp ZDO (the same networked object vanilla uses for terrain edits), and the grid is rebuilt from heightmap + replayed ops on load. That's also the whole multiplayer story: a carve is a few dozen bytes, the per-zone list is compressed on top, and it all syncs through vanilla's own machinery.
The cost scales with what you dig: an untouched zone costs nothing, a dug zone holds its density grid in memory (a few
MB at the default 128m depth) plus its chunk meshes. Loading a dug zone replays its stored ops over the freshly sampled
heightmap (a one-off few milliseconds) and then meshes on a ~5ms-per-frame budget until the zone swaps over. The vanilla
terrain stays active until everything is ready, so there's no pop-in and no hitch. Dedicated servers do the same work
(creatures need the collision), with the same per-frame budget. Want real numbers from your own setup? Enable Debug in
BepInEx's log config and every zone conversion prints its build, replay, and meshing times to the log.
Known limitations
- Digging below the water level (y≈30) does not flood or block water - avoid digging under shorelines unless you enjoy weirdness.
- Tar pits use the game's liquid system, which this mod does not touch yet. Digging under or right next to one is untested - dig elsewhere for now.
- Creatures need a few seconds to "learn" freshly dug tunnels (the navmesh rebuilds on vanilla's own cycle).
- Terrain paint is a flat 2D layer shared between a cave floor and the surface above it, so painting one paints the
other. Turn off
Underground Paintingif clean surfaces matter more to you than paintable cave floors. - Where a voxelized zone borders untouched terrain, a faint lip can show on extreme slopes; it disappears once the neighboring zone is dug into.
- Two players editing the exact same spot simultaneously can briefly see slightly different results; it reconciles when the area reloads.
- Digging near a zone border voxelizes the neighboring zone too (needed for seamless tunnels across borders).
For questions or comments, find me in the Hexium, Odin Plus Team Discord or in my own:
|
|
|