TerrainForge

A free-form terrain brush for Valheim.

Flatten, raise, lower, smooth, ramp (two-point, fixed-angle and path), shore, paint and restore terrain of any size, beyond the vanilla +/-8 m limit, with undo/redo, five brush shapes, a radial menu, named presets and EN/ES localization.

The mod ships its own TerrainForge Rod (a clone of the Hammer) as the brush tool, hands it to you automatically and documents everything in an in-game help tab (press the rebind key, default F5).

Why client AND server

Terrain edits are written into the game's TerrainComp delta arrays and persisted to the owning ZDO, so the server stores and replicates them to every client.

Because the vanilla TerrainComp.ApplyToHeightmap clamps every vertex to baseHeight +/- 8 m, TerrainForge must also be installed on the server (otherwise the server regenerates a clamped terrain while modded clients show the full edit, causing desync). Install it on the server and on every client.

Requirements

• BepInEx 5 (x64, Mono) on client and server. Thunderstore Mod Manager users already have it.
• Jotunn (ValheimModding-Jotunn) — used to register the custom tool item. Listed as a dependency in manifest.json; Thunderstore installs it automatically.

Installation

1. Build (see below) or copy TerrainForge.dll.
2. Drop it in:
   • Client: ...\BepInEx\plugins\TerrainForge\TerrainForge.dll
   • Server: <server>\BepInEx\plugins\TerrainForge\TerrainForge.dll
3. Restart the game / server.

Usage

Equip the TerrainForge Rod (given automatically on entering a world; get it again with the give tool key, default F8), aim at the ground and hold the apply key (default right mouse button) to edit terrain under the crosshair.

While aiming, a solid ring marks the real generated area, with thin, faint guides in the operation colour around it (full-strength zone, maximum brush radius and maximum aim distance). In the Ramp operation the real A-B corridor is drawn while marking. The status HUD (bottom-right, default IMGUI typeface) shows the current operation, radius, shape and paint, plus undo/redo counts; a second line shows the aimed height, the current target and the local slope in degrees. Guides can be turned off with Preview > ShowGuides.

Operations cycle through: Flatten, Raise, Lower, Smooth, Ramp, Paint, Restore, Shore (flattens toward water level + offset, for beaches) and Snow (paints snow like Paint but snow-only; hold Shift to remove it and restore the original ground).

Everything is editable live in the in-game menu (F5 → AJUSTES tab): operation / shape / paint / ramp-mode / smooth-mode, all sizes via sliders, every toggle, menu/HUD language (Español/English) and named brush presets. Saved when the menu closes.

Terrain snapshots (backups) live in the same tab: name a snapshot to save every edited tile to BepInEx/config/TerrainForge/snapshots/<name>.dat, then load it back later (even in another session). Importing restores the arrays with ownership and is itself undoable; tiles that are not loaded report cleanly, so import near the place.

Shapes cycle through: Circle, Square, Line, Rect, Poly (. key). Line/Rect are marked with two Apply presses (A then B; line half-width = brush radius, rect corners define the area with soft edges). Poly adds one vertex per press and closes on a double-press with 3+ vertices. All area operations apply over these footprints with undo support.

• Flatten follows the ground under the crosshair by default, so it conforms to whatever you aim at (e.g. a ramp). Hold the modifier (Left Shift) to level to your own feet instead.
• Smooth averages each point with its neighbours (a real blur), smoothing bumps, steps and noise. Hold it down to smooth progressively.
• Ramp has three modes (H): two-point (mark A then B, a straight slope joins both heights), fixed-angle (B sets direction/length, height follows SlopeAngle, adjustable with Alt + radius keys), and path (mark a curve A→B→C…, double-press to close). The brush radius sets the ramp width and softness softens only the side edges.

In-game help

Press F5 (configurable) — or the TerrainForge button in the ESC pause menu — and open the AYUDA tab for an in-game description of the tool and every operation. The TECLAS tab rebinds keys: click a binding, press the new key or mouse button, and it is saved to the config immediately. Esc cancels a capture.

Note: F5 is also Valheim's developer console key, but only when the game is launched with -console. If your console is enabled, rebind this to e.g. F7/F9.

All hotkeys are also editable directly in BepInEx/config/com.terrainforge.valheim.cfg.

Configuration

Config file: BepInEx/config/com.terrainforge.valheim.cfg

• General: Enabled, PlayEffects (dust + thud on apply), Language (Español / English).
• Brush: Radius, RadiusMin/Max, RadiusStep, Softness, FalloffPower, RaiseLowerMeters, PaintStrength, DefaultOperation, Shape, Paint, RampMode (TwoPoint / FixedAngle / Path), SlopeAngle (5-60°), SmoothMode (Full / Bumps / Dips), ShoreOffset, UseFixedHeight / FixedHeight (eyedropper state).
• Input: all hotkeys (ApplyKey, radius, cycles, AimHeightModifierKey, UndoKey/RedoKey, EyedropKey, RampModeKey, RadialKey, GiveToolKey, RebindMenuKey), plus RequiredTool (Any, Pickaxe, or the mod's TerrainForgeTool — default) and AutoGiveTool (hand out the rod on entering a world, default true).
• Limits: UnlockDeltaLimit (default true), MaxUpDelta, MaxDownDelta. Raising these allows terrain edits past the vanilla +/-8 m; keep them equal on server and clients.
• VanillaTools (best effort / optional):
  • ScaleVanillaToolRadius – enlarge the vanilla hoe / cultivator radius. This only affects the client that applies the op and may not stay consistent across clients, so it is off by default.
  • NoBuildCost – remove material / workstation requirements.
  • AllowInProtectedZones – ignore no-build and ward zones (bypasses protection).
• Preview: ShowPreview, ShowGuides (reach guides, slope tint, level ring).
• History: UndoDepth (0-500, default 50; 0 disables undo history).
• Presets: Slots (named brush setups, managed in-game).
• Performance: ChunkCompsPerFrame (1-32, default 4 tiles per frame).
• Server (authoritative when the server runs the mod — its values win through config sync): AllowTerrainEdits (default true; when false, clients cannot apply, undo or redo) and AdminOnlyEdits (default false; only admins / host may edit). RespectWards (default true) blocks edits inside foreign wards. RadiusCap / DeltaCap (0 = off) clamp brush radius and delta, visibly in HUD and preview. Servers without the mod ignore this section, so the client tool keeps working there for testing.

Building

Requires the .NET SDK and the reference DLLs (Valheim Managed folder + BepInEx core folder). Defaults point at the Thunderstore profile; override with:

dotnet build -c Release -p:ValheimDir="D:\Steam\...\Valheim"

Deploy straight into the profile plugins folder:

dotnet build -c Release -p:Deploy=true

Notes / limitations

• Design principle: keep external dependencies to a minimum. Prefer vanilla game APIs + Harmony over third-party mod frameworks when a feature can be done either way. (The custom tool item currently uses Jotunn; the goal is to eventually register the prefab ourselves via a Harmony patch so Jotunn is not required.)
• Larger vanilla-tool radius is best-effort and may desync other clients; the custom brush is the reliable path for big edits.
• Keep MaxUpDelta / MaxDownDelta consistent between server and clients.

Changelog

See CHANGELOG.md.

Changelog

[0.3.8] - Hotfix for 0.3.7

Context

• The 0.3.7 log supplied for review showed repeated network prefab registration failures because the stable hash 506871212 was already present, plus invalid null item entries during ObjectDB registration. The log also showed the tool being registered, so the precise runtime failure still needs confirmation in game.

Fixed

• Network prefab registration now reuses an existing entry when it matches TerrainForgeTool, instead of attempting to add the duplicate key again; hash collisions with another prefab are reported and left untouched.
• Invalid null item entries are removed before rebuilding ObjectDB indexes, and the tool clone is cleaned up if registration fails.
• Terrain editing and the brush HUD stop when the required tool is unequipped, including while free camera remains active; equipped inventory data is checked for cases where free camera hides hand slots.

Verification

• The supplied log identifies the duplicate-key and ObjectDB symptoms, but does not confirm that the game hands out the rod or that terrain editing works after these changes. Test in Valheim before publishing this hotfix.

[0.3.6] - 2026-10-21

Fixed

• Reworked the F5 panel layout: tabs are split into two rows, window sizing follows screen dimensions, and each operation only shows the controls it uses.
• Ramp now has a dedicated panel that keeps Two-Point, Fixed-Angle, and Connected Path visible, with width, softness, and fixed-angle controls grouped together.
• Circle and Square are hidden while Ramp is selected because ramp placement uses its own line/path geometry; both shapes remain available for brush and Copy/Paste selection.
• Renamed the Path ramp option to Connected in English and Spanish and clarified that 3+ marked points create one continuous ramp.

Planned

• Added Circular ramps to the 0.4.0 roadmap: prototype both a level ring/annular terrace and a connected spiral that rises or descends around a center.

UI

• Opening the F5 panel now freezes local player input and camera look, dims the game behind the panel, and opens at a larger resolution-aware size.
• Added a dedicated Copy / Paste brush mode to the Q wheel; Apply selects the area according to the active shape, while the configured paste shortcut opens or confirms the placement preview. Its HUD identifies the mode separately from Paint.
• Copy mode now honors the selected shape: mark two corners for Rectangle, endpoints for Line, or vertices for Polygon; Circle/Square copy the aimed brush footprint. The HUD shows the next selection step.
• Folded Snow into Paint as the DeepSnow paint type; the existing height modifier still removes snow. Existing configs that selected Snow migrate to Paint + DeepSnow.
• Added a dedicated Copy/Paste tab with visible terrain copy, paste-preview/confirm, clipboard history, and saved-stamp controls; copy/paste buttons close the menu so the requested world action can run immediately.
• Reused the F5 operation glyphs in the Q radial wheel, selected-operation hub, and an in-world aim badge.
• Replaced the long, crowded status text with a compact TerrainForge card showing operation, radius, shape, target height, undo/redo, and only relevant contextual status.
• Kept permission and server warnings visible with a distinct alert color.
• Free camera now clamps its height above sampled terrain, preventing downward flight through the world while preserving aim toward lower terrain.

Changed

• TerrainForge now registers its own TerrainForge Rod prefab with Harmony. Jotunn is no longer required.
• Removed Jotunn from the Thunderstore dependencies; BepInEx is the only required mod dependency.
• Plugin metadata was aligned at version 0.3.6.
• Re-register the rod for each ObjectDB instance and retry network-prefab registration after ObjectDB is populated, covering startup-order and world reloads.
• Verify ObjectDB indexing and network-prefab insertion; report failures instead of silently claiming registration succeeded.
• Revalidate the rod against the live ObjectDB during gameplay so later database rebuilds by other mods cannot leave auto-give using a stale registration state.

[0.3.5] - 2026-10-17

Added

• Terrain stamps — dedicated shape selection: select Circle, Square, Line, Rectangle, or Polygon in the Q-wheel Copy/Paste mode; the HUD guides the selection. Paste uses a movable preview and explicit confirmation.
• Free camera (F) reworked: while flying, right-click no longer triggers lock-on, brush drift or a screenshot; Ctrl+wheel adjusts the brush radius; brush adjustments keep priority over free-fly input; on-screen banner shows the fly distance.

Changed

• Saved stamps now use version 2 (adds the selection mask); version 1 stamps still load.
• Documentation: README and CHANGELOG are now in English, with a complete wiki manual available in 14 languages. Internal roadmap added.

Fixed

• Free-fly camera vs. brush input: suppressed vanilla SecondaryAttack / Block / Attack handling and the scroll-wheel conflict while flying, so aiming, radius and adjustments work from the free camera.
• Preview of a region-cropped stamp now skips cells outside the copied rectangle.

[0.3.4] - 2026-10-15

Added

• Persistent HUD: position coordinates, current biome and nearby resources (with counts) always visible next to the tool status.
• "Reset keybinds" button: in the keys tab, resets every keybind to its default value in one click.
• Valheim-native UI: full UI redesign using the Averia typeface and Valheim's palette (gold, dark greys), with native-styled buttons, panels, tabs and scrollbars.
• Native radial menu (Q): working mouse wheel via ZInput.GetMouseScrollWheel(), fixed button hover (radius 34–130 px), identical to vanilla radial menus.
• Forced visible cursor: in the F5 menu and the ESC button, the cursor is forced visible and unlocked every frame via OnGUI().
• Slope heatmap (H): slope overlay: 🟢 0–15° → 🟡 15–30° → 🟠 30–45° → 🔴 45°+.
• Height heatmap (J): height overlay: 🔵 low → 🟢 mid → 🟡 high → 🔴 peak.
• Stamp Preview Pro: contour lines in the stamp preview — draws a 1 m curve over the stamp area in Valheim gold.
• Improved Shore operation: a dedicated falloff mode for Shore (ShoreFalloffMode: Linear, Smooth, Flat, Pointy), defaulting to Linear for more natural beaches; a linear falloff is used by default to reach the water level more reliably; configurable in SETTINGS → "Shore falloff".
• Visible ramp-mode selector: the ramp mode (two-point / fixed-angle / path) is now shown as three selectable buttons instead of a single cycling button.
• "Quick actions" section in the keys tab: buttons for Undo, Redo, Fix height, Copy/Paste stamp, Previous stamp, Clear marks and the heatmaps — no need to rely only on the hotkey.
• Vanilla tool blocking (BlockVanillaTerrainTools): while the TerrainForge tool is equipped, vanilla hoe/cultivator terrain edits are ignored.
• Material diagnostic (log): a button that dumps the terrain shader and texture slots to the log, to assess the feasibility of non-biome textures.
• Tool color (ToolTint / ToolTintColor): tints the model and icon of the TerrainForge Rod (a Hammer clone) to tell it apart from the vanilla Hammer at a glance. Only affects this mod's tool.

Changed

• F5 panel reorganized: the SETTINGS tab now groups options into labeled sections (Tool, View, Vanilla, Server, General) instead of a single block of toggles; the tool tint (ToolTint / ToolTintColor) is editable directly in the UI.

Fixed

• Preview: circles/square hidden on Line/Rect/Poly while marking point A.
• Cursor visible in the F5 menu and the ESC button (OnGUI forces it visible).
• Radial menu (Q): the mouse wheel now keeps the selection. Previously, with a centered cursor, the pick was wiped instantly and the wheel looked unresponsive; now only the pointer over an option changes the selection.
• Alt+Wheel (fixed height): more reliable wheel reading.
• Menu window: initial size 680×720, min scroll 460 px, wider keybind rows.

[0.3.3] - 2026-10-15

Added

• Professional bilingual documentation (ES/EN): README, CHANGELOG and WIKI fully rewritten in both languages with professional formatting, tables and complete coverage of every feature.

Fixed

• Radial menu (Q): working mouse wheel (uses native ZInput.GetMouseScrollWheel), fixed button hover.
• Preview: circles/square hidden on Line/Rect/Poly while marking point A.
• Cursor visible in the F5 menu and the ESC button (OnGUI forces it visible).
• Mouse wheel in the radial menu (Q) using Valheim's native API.
• Menu window: initial size 560×600, min scroll 400 px.

[0.3.2] - 2026-10-14

Added

• 14 languages + auto-detect: automatic detection via reflection (Localization.instance.GetSelectedLanguage()). Languages: English, Español, Français, Deutsch, Русский, 中文, 繁體中文, 日本語, 한국어, Polski, Português, Türkçe, Українська, Italiano. Default Auto; falls back to English.

Fixed

• Preview: circles/square hidden on Line/Rect/Poly while marking point A.
• Cursor visible in the F5 menu and the ESC button (OnGUI forces it visible).
• Mouse wheel in the radial menu (Q) using native ZInput.GetMouseScrollWheel().
• Menu window: scroll view min height 400 px, initial window 560×600 px.

[0.3.1] - 2026-10-14

• Version fix to resolve a Thunderstore conflict.

[0.3.0] - 2026-10-13

Added

• Undo / Redo (Ctrl+Z/Ctrl+Y): every application stores exactly the vertices it touches. Configurable depth (0–500) with a slider + textbox in the KEYS tab. Live counters in the HUD. History is cleared when leaving the world.
• Live HUD data: a second line with the aimed height, current target and local slope in degrees.
• Eyedropper (G): fixes the Flatten height at the aimed point (takes priority over Shift). The HUD shows fixed.
• Fixed-angle ramps (H): a FixedAngle mode where B gives direction/length and the height follows SlopeAngle. Adjust in-game with Alt + radius/wheel.
• New shapes: Line (two-click capsule), Rectangle (two corners), Polygon (click per vertex, double-click closes). All with undo and preview.
• In-game SETTINGS tab (F5): everything editable live — cyclers, sliders, toggles. Saved on close.
• Smooth modes: Full / Ridges only / Dips only (cycle in SETTINGS). Line + Smooth = smooth along a path.
• Shore operation: flattens toward the water level + margin (beaches). Softness blends like Flatten.
• Preview improvements: the footprint edge tints red on slopes; Flatten/Shore show a target-level ring.
• Feedback effects: native dust + hit effect on every application (throttled while holding). Toggle General > PlayEffects.
• EN/ES localization: General > Language switches the menu, HUD, messages and help. Key labels are rebuilt when the menu opens.
• Radial menu (Q): choose the operation with the mouse; release confirms, Esc cancels. Suppresses the brush while open.
• Named profiles: save/load/delete up to 12 full setups (SETTINGS → Profiles).
• Live measurements: the HUD shows line/ramp length, rise and angle, rectangle W×D+area, polygon perimeter+area.
• Path ramps (Path): a curve A→B→C… (double-press closes) → smooth Catmull-Rom. Preview corridor + trail, live length, undo.
• Target height by text: UseFixedHeight/FixedHeight in config + a Fix/Release textbox in SETTINGS. G captures in the same state.
• Terrain snapshots: saves edited tiles in a versioned binary (.dat in snapshots/, max 12). Import restores arrays with ownership and is undoable; missing tiles warn.
• Wards + server caps: RespectWards blocks foreign wards; RadiusCap/DeltaCap are server-enforced caps visible in the HUD/preview.
• Chunked application: configurable tiles/frame (TilesPerFrame, 1–32). Terrain appears progressively, one undo per stroke, auto-continues if you release the key.
• Server authority: Server section (AllowTerrainEdits, AdminOnlyEdits). Server values win via config sync; clients cannot apply/undo/redo against them (HUD SERVER: BLOCKED). Servers without the mod ignore the section.

[0.1.0] - 2026-10-12

Added

• Free brush: Flatten, Raise, Lower, Smooth, Ramp, Paint, Restore under the crosshair. Flatten follows the aimed height (Shift = level at your feet); Smooth averages neighbours.
• TerrainForge Rod (Hammer clone): auto-given/equipped on join, give key F8.
• Two-point ramp: click A, click B → a straight slope joins both heights (radius = ramp width). A wide, flat corridor with a soft edge (softness = lateral blend).
• Configurable brush radius (60 m), shape (circle/square), paint cyclable in-game.
• Live preview: a solid ring = the real area; faint guides in the operation color = full-strength zone, max radius, max aim distance. For Ramp: the real A–B corridor (both edges). Guides toggleable via Preview > ShowGuides. Top-left HUD (op, radius, shape, paint).
• In-game keybind menu (F5, configurable) with its own skin + an in-game help tab.
• Removal of the vanilla ±8 m clamp (UnlockDeltaLimit). Must also be on the server.
• Optional vanilla tweaks: scaled hoe/cultivator radius, no build cost, edits in protected zones.
• The crosshair works over water (heightmap raymarch without a collider).
• Configurable required tool (Any, Pickaxe, TerrainForgeTool).

Notes

• Edits persist via the TerrainComp ZDO and replicate through the server → required on both client and server.