Hearthfolk

Hearthfolk is a server-authoritative, ASKA-inspired village system for Valheim 1.0.7. It adds shared Stone Tablet settlements, persistent two-candidate recruitment, procedural villagers, survival needs, skill growth, and physical woodcutting, planting, fishing, and guard jobs.

Requirements

• Valheim 1.0.7
• BepInExPack Valheim 5.4.2350
• Jötunn 2.30.0

Every multiplayer client and the server must install matching Hearthfolk versions.

Build

Run scripts\build.ps1. The script downloads compile-only dependencies to the ignored .deps directory, builds the plugin and dependency-free core test runner, executes the tests, and packages dist\Hearthfolk-0.1.0.zip.

A Debug build produces dist\Hearthfolk-0.1.0-debug.zip and hard-disables recruitment and candidate-reroll costs. Release builds always use the synchronized configured costs.

Override the game directory when needed:

.\scripts\build.ps1 -GameDir "D:\SteamLibrary\steamapps\common\Valheim"

Playing

1. Craft the Hearthfolk Hammer at a workbench from 5 Wood and 2 Stone.
2. Use it to place a Stone Tablet. Tablets default to an 80 m radius and require 160 m separation.
3. Open the tablet and recruit one of its two persistent candidates. Recruitment begins at one Surtling Core and increases linearly.
4. Place a Village Pantry and load it with ordinary Valheim food.
5. Place workstations, link nearby input/output containers, and assign villagers through each station panel.

Woodcutters require axes. Planters consume Beech Seeds, Fir Cones, or Pine Cones. Fishers require a fishing rod and bait. Guards require a weapon. Villagers eat real food, accumulate fatigue, sleep at nearby beds, gain job skills, and can die from combat or prolonged starvation.

Multiplayer and persistence

Recruitment requests are validated by the authoritative ZNetView owner before resources are consumed. Village, candidate, villager, needs, skill, and workstation state are stored in ZDO fields and therefore travel with the world save. Physical work pauses when its zone is unloaded; need decay uses a bounded real-time catch-up window.

The tablet founder, local host/admin, and players permitted by a covering ward can manage a settlement. Everyone may inspect it.

Current Valheim 1.0.7 note

Jötunn 2.30.0 registers custom pieces on Valheim 1.0.7, but custom piece-table categories are temporarily incomplete upstream. Hearthfolk consequently uses a dedicated uncategorized build table so all pieces remain accessible. The Village/Gathering/Defence category labels are retained in definitions for automatic restoration when Jötunn supports them again.

Administration

Enable console cheats and use:

• hearthfolk list
• hearthfolk inspect <villager name>
• hearthfolk repair

Server-synchronized BepInEx settings control resource costs, population, village/job radii, hunger/fatigue rates, starvation grace, catch-up limits, debug overlay, and forced disband policy.

Known vertical-slice limitations

• Portraits are deterministic generated avatars; a later asset pass can replace them with rendered 3D headshots without changing candidate saves.
• Villagers claim the nearest available bed operationally but do not overwrite a player's vanilla bed ownership.
• Fishing performs a visible station-based production cycle near water rather than manipulating individual swimming fish entities.
• Station management UI currently requires the local player to have tablet management rights; the owning peer remains responsible for persistent simulation.

Removal warning

Back up worlds before uninstalling any content mod. Loading a world without Hearthfolk can discard its custom prefabs and their ZDO-backed state.