Hearthfolk

Unofficial mod. Hearthfolk is a fan-created Valheim modification and is not affiliated with or endorsed by Iron Gate Studio or Coffee Stain Publishing. Use it at your own risk. See LICENSE.md and NOTICE.md included with this distribution.

Hearthfolk is a Valheim settlement mod built around visible, persistent residents, daily routines and physical work around the player's settlement.

1.1.1

What ships today:

• a buildable Exiles' Hearth (hammer, Misc) with a wide two-tab settlement panel (Use): select residents from a compact list, inspect their status and happiness, recruit new caretakers, and tune settlement settings;
• persistent, networked human settlers cloned from the vanilla player rig;
• each resident has a persistent, multiplayer-synchronised appearance. The hearth panel can cycle body type, every native hair and beard style, hair colour and skin tone or generate a new combination, with a live 3D portrait of the actual resident. Residents can also be renamed; their name and claimed-bed label update together. New residents roll a random 50/50 body type; appearance and names survive death and respawn. The server can provide a custom recruitment name pool through Recruitment.NamePool;
• settler inventory opened with Use on the settler, sharing the body's real equipment (items are worn, wielded, consume durability, and can break);
• newly recruited settlers are Caretakers; Idle, Lumberjack, Miner, Farmer, Guard, Caretaker, Cook and Follower assignments are managed directly from the hearth;
• Lumberjacks physically search for allowed trees, logs and wood drops inside the work area, use their equipped axe and deposit gathered resources;
• Cooks work the settlement's cooking stations, including the stone oven: they fetch raw food from the settlement chests, put it on a lit fire, refuel the stations that burn fuel, and above all take every dish off the moment it is done, so nothing is left to overcook into coal. Finished food is picked up off the ground and returned to storage;
• Miners physically search for allowed rocks and ore deposits, use their equipped pickaxe without deforming terrain and deposit gathered resources;
• buildable Farm Markers define circular crop fields around their centre (8 metres by default, configurable from 3 to 20). Looking at or using a marker temporarily draws its real terrain-following perimeter on the ground. Use a marker to select any Cultivator crop whose planting material the player has discovered, or the explicit combined food-and-seed option for a reciprocal crop pair. Combined fields alternate their preferred planting type so both members remain present. Farmers equipped with a real Cultivator harvest ripe vanilla crops, collect their drops, fetch every available unit of a planting resource above the configured reserve in one chest visit, finish that carried batch only in markers configured for the matching crop, validate cultivated ground, biome, sunlight and spacing before planting, consume tool durability and return the harvest to storage. For crops such as carrots, turnips and onions, they automatically replant enough harvested produce to regenerate seeds and keep the farming cycle self-sustaining. Each Farmer has a persistent Allowed crops filter in the settlement panel; one toggle controls both the food crop and its reciprocal seed crop, including compatible Cultivator crops added by other mods. Farmers can also be assigned exact Farm Markers, switched between full-cycle, plant-only and harvest-only work, and given optional per-crop stock targets. Stored harvest and projected yields from crops already growing count toward each target;
• residents open ordinary doors and gates encountered on civil routes to beds, work targets and patrols, then close only the doors they opened after crossing. When a perimeter wall blocks the direct route, they deliberately detour through a loaded door or gate before resuming the original destination. The hearth map can explicitly mark one or more preferred perimeter entrances without hiding the interior doors needed to reach houses, beds or indoor storage. Stuck recovery samples the real colliders of player-built walls and follows local physical waypoints instead of trusting the terrain navmesh alone. Closure waits while another character is still in the doorway;
• distinct buildable Lumberjack and Miner Banners extend only their matching role's physical work area. Both use the classic freestanding Valheim silhouette: a patterned pointed cloth hanging from a single grounded post;
• the hearth can raise a settlement-wide alert, temporarily turning every resident into a guard and restoring their previous role when the alert ends;
• vanilla raids trigger the same response automatically: every resident interrupts meals, sleep and work, equips an available weapon, runs to defend the hearth and proactively engages nearby enemies until the event ends;
• residents ignore nearby creatures that are not actively causing trouble. Outside a raid, the automatic response starts only when a resident is actually attacked or a hostile actor damages a player-built structure inside the hearth's work radius; the alert lingers briefly after the last hit and then routines resume;
• buildable Patrol Points form a clockwise route around their nearest hearth. Every Guard has an interactive local-map editor in their resident card, where points can be selected in an individual exact visit order with numbered markers, directional links, pan and zoom. Off-duty guards sit during the day and sleep at night;
• Followers accompany any player who commands them with Crouch+Use, keep stable formation positions when travelling as a group, may be told to wait, and return to the hearth when their player disconnects without forgetting the assignment; following resumes automatically when that player reconnects. Their hearth panel offers Defensive, Aggressive and deliberately non-combat Passive stances. They retain meals and happiness but do not require beds or sleep, and eat only food carried in their own inventory. A follower travels at its player's own pace — walking, jogging or running with them, and always running to escort a mounted rider — and boards the ship its player sails on, taking a free seat when the ship has one and riding the deck when it does not;
• residents use Valheim's true walking pace for civil movement. Lumberjacks and Miners run while performing their field work; every resident immediately runs when an alert, hostile target or attack creates a threat;
• caretakers use the settlement intake chest to refuel player-built fires, torches and production machines, load compatible inputs, collect finished material drops and return them to storage; supplied with a usable hammer, they also repair damaged player-built structures under vanilla station and ward rules. Each of these task categories can be enabled or disabled per Caretaker from the hearth;
• idle Caretaker statuses identify the exact missing material and target machine whenever a pending refuelling or production task cannot be completed;
• assign one or more exact settlement intake chests with Ctrl+Use on each physical chest. Each chest can serve Lumberjacks, Miners, Farmers or any combination of those roles. Caretakers process every intake chest in the settlement, physically sorting resources, food, fish and trophies into specialised settlement chests and retrieving production supplies from them; the same chest panel configures accepted sorting items, while unconfigured destination chests infer them from their existing contents. When KGvalheim ItemDrawers or Firehunter1980's unofficial QuickFix is installed, compatible player-seeded drawers inside the work area are preferred automatically as sorting destinations;
• residents sleep in ordinary player-built beds. Hearthfolk ships no sleeping structures of its own: raise whatever house you like out of Valheim's own pieces, put beds in it, and each resident claims a free roofed bed near the hearth. A bed a player has ever slept in is never taken — claiming one is how you keep it for yourself — and beds on ships and carts are ignored. At night workers lie down until morning while guards keep watch;
• residents can be moved to another hearth from their resident card. Every hearth in the world is a valid destination, not just the ones nearby, so a settlement on the far side of the map can be staffed from an established one. The resident keeps its name, appearance, role and inventory, and leaves its bed, assigned chest, patrol route and fields to the settlement it left;
• settlers can be safely dismissed from the hearth panel once their inventory is empty; dismissal releases their bed;
• residents heal. Their health is shown in the settlement panel, they recover Settler.HealthRegen health per minute (3 by default, 0 disables it) whenever they are out of danger, they wake at full health after a night's sleep, and Followers eat food from their own inventory when they drop below two thirds. Recovery pauses during an alert, while a resident is fighting and for a few seconds after any hit;
• dead settlers automatically return at their hearth after a configurable delay. Weapons, tools, armour and accessories keep their exact durability, while gathered materials, food, ammunition and other cargo are lost on death. The hearth panel keeps them listed as dead with a live countdown, which persists across world reloads;
• residents eat a real dinner before bed and a real breakfast before work, physically fetching nutritious food from accessible settlement chests. They reserve a nearby chair or bench when one is free and otherwise eat standing;
• residents whose role has temporarily exhausted its work, materials or valid targets enter the same idle routine instead of repeatedly stopping in place. Idle residents sometimes form conversation groups of two or three, using free seats when available or chatting while standing. They face one another, exchange synchronized speech bubbles and small gestures, and earn a configurable daily happiness bonus after completing their social break;
• meals take a configurable amount of world time and follow Valheim's accelerated night when players sleep. A completed night's rest fully restores health;
• persistent happiness reflects sleep, meals, seating, company, safety, shelter, a lit fire and suitable work equipment. The panel explains every recent cause;
• residents who remain miserable for a configurable number of simulated days leave after warnings, releasing their assignments and leaving a recoverable inventory container at the hearth. Unloaded days never reduce happiness;
• guards always respect meals; their configured hearth shift determines whether they patrol or sleep at night. An armed resident holds the best weapon it owns and only wears a shield with a one-handed one. A bow counts as a weapon only once the resident actually carries arrows, which it restocks from a settlement chest up to Guards.ArrowSupply; melee weapons win over a bow unless Guards.PreferRangedWeapons is enabled;
• the Hearthfolk panels scale with Interface.UiScale, a per-client setting for high resolution screens. Valheim's own UI scale cannot affect them because these panels are not part of the game's interface canvas.

The mod must be installed on the server and on every client. Minor versions must match.

KGvalheim ItemDrawers 1.2.0 is an optional compatibility mod and is not bundled with Hearthfolk. If used in multiplayer, install it according to ItemDrawers' own client/server requirements. Empty drawers must first be seeded by the player to define the item and quality they accept.

Build

dotnet build .\Hearthfolk.csproj -c Debug

Default local paths are configured in Hearthfolk.csproj. Override them without editing the project when needed:

dotnet build .\Hearthfolk.csproj -p:ValheimDir="D:\Games\Valheim" -p:ProfileDir="D:\Profiles\Valheim"

Use -p:SkipProfileCopy=true to compile without copying the DLL into the active Thunderstore profile. The configured default profile is Default.

Known limitations

• Physical resident behaviour requires loaded zones; there is no offline resource production while the zone or game is unloaded.
• A settler's bed can be reclaimed safely by dismissing that settler. There is no separate "release bed" button yet.
• Target scans still sweep loaded objects (throttled); a spatial registry is planned if profiling demands it.
• Chest sorting covers materials, consumables, fish and trophies. Equipment, ammunition and quest items are left untouched. Empty chests work once explicit filters are configured.
• The hearth uses its own communal-fire model and embedded crafting icon.
• Food preference currently favours variety and lower-value meals from explicitly configured food chests; individual favourite foods are not implemented yet.

Next milestone

Forager role, followed by additional resident preferences and settlement polish.