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.

Alpha 0.19.2

Current vertical slice:

• 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 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;
• Miners physically search for allowed rocks and ore deposits, use their equipped pickaxe without deforming terrain and deposit gathered resources;
• buildable Farm Markers define invisible circular crop fields around their centre (8 metres by default, configurable from 3 to 20). 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;
• 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;
• buildable Settler Tents are decorated A-frame canvas camps reserved for one resident. Woven canvas and layered-fur textures are purpose-built for the model, with a consistent natural white finish across every placed tent. Each has timber supports, tied entrance flaps, ropes, stakes, pennants, an enterable interior and a furnished side awning with table, chairs and travelling clutter. Two always-lit particle torches provide warm light and the vanilla Fire status. Their fixed open entrance gives physical navigation a reliable target, and waking residents use a dedicated two-stage exit before resuming work. Existing vanilla-bed claims remain valid until a free tent is built, then migrate automatically. At night workers lie down until morning while guards keep watch;
• settlers can be safely dismissed from the hearth panel once their inventory is empty; dismissal releases their bed;
• 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.

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

Changelog

1.1.1

• Fixed the Cook assignment selecting Farmer instead, which made the new role impossible to use at all. The role network call clamped the requested value to the highest role that existed when it was written, so the Cook — one past that ceiling — silently became the role below it. An unknown role is now refused outright rather than quietly turned into a neighbouring job.

• Residents can be moved from one hearth to another, from their resident card. The destination list is read from the world's hearths rather than from the ones currently loaded, so a settlement on the far side of the map is a valid choice. The resident keeps its name, appearance, role and inventory, and leaves behind everything that belonged to the settlement it left: its bed, its assigned chest, its patrol route and its assigned fields, all of which name objects that stay where they are. The destination is resolved from the world on the peer that owns the resident, never from a position supplied by the client asking for the move.

1.1.0

• Residents recover health out of danger, and the settlement panel shows how much each of them has left. Until now the only ways back to full health were a night's sleep and, for Followers, eating their own food: a resident hurt during the day, or one with nowhere to sleep, stayed wounded with nothing the player could do about it — and no way to even see it. Recovery runs at Settler.HealthRegen (3 health per minute by default, 0 disables it) and stops during an alert, while a resident holds a hostile target, and for a few seconds after any hit, so nobody heals mid-fight.

• New Cook assignment. A Cook works every cooking station in the settlement, the stone oven included: it fetches raw food from the settlement chests, puts it on a lit fire, refuels the stations that burn fuel, and takes each dish off the moment it is done — which is the point, because Valheim turns an unattended dish into coal. Finished food is collected off the ground and returned to storage. A station is only loaded when its fire is actually lit, one Cook works one station at a time, and every change goes through the same authoritative calls a player triggers, from a Cook standing at the fire.

• Residents walk to a spot they can actually use a chest from, instead of to the nearest point of its collider. That point was measured from wherever the resident stood when the trip began, so for a chest against a wall — or in a storeroom entered through a door — it was the outside face of the wall: the resident walked up to it, decided it had arrived, then failed the reach test for as long as the job lasted. This is why settlers queued on the far side of a wall from the crates they were assigned. Each trip now picks a standing post around the chest that passes the real reach test first, which also gives the gateway detour a reason to open the door in between. The search is nearest-post first and stops at the first usable one, so a chest the resident is already standing in front of costs a single ground probe.

• A rebuilt Exiles' Hearth now adopts the residents of the one it replaces. Membership was purely positional — a resident belongs to the hearth standing on its home point — so a player who tore the hearth down to move it a few metres lost the entire roster: the new hearth listed nobody, the old residents went on serving bare ground, and putting the hearth back where it stood was the only way to see them again. A resident whose hearth is gone now joins the first one raised within Settlement.RehomeRadius (24 metres by default, 0 disables it) of where it used to live. A hearth that is still standing keeps its residents, so a second hearth next to a live one never poaches them, and residents who died during the move are adopted with the living instead of never coming back.

• Fixed a resident going on wearing armour the player had taken back. Equipment is driven from the resident's shared inventory, but nothing ever undid it: Valheim only takes gear off automatically for a Player, and a settler is a plain Humanoid, so the body kept displaying a helmet or a cuirass that was already in the player's own inventory — with the resident's inventory visibly empty. The resident now takes off anything it no longer owns.

• Followers now travel at the pace of the player they escort instead of always walking. The civil movement policy that makes residents stroll around their own village was applied to escorts too, and it silently cancelled the follower's own request to run: a companion physically could not exceed walking speed unless it was fighting, so it fell behind on every journey and only ever caught up by teleporting after sixty-five metres. A follower now walks when its player walks, jogs when it jogs and runs when it runs, and still sprints on its own to close a gap.

• Followers now sail with their player. A companion left standing on the pier while the boat pulled away was the whole of the previous behaviour, and one that tried to reach a hull under way could only swim after it: a deck at sea is on no navmesh. A follower now boards the ship its player is travelling on, takes a free seat if the ship has one, and otherwise rides the deck without walking, since every step on a moving boat is a step towards the rail. It steps off with the player and resumes the normal formation ashore. Escorting a mounted player also counts as a run: a rider reports neither walking nor running, so followers used to stroll after a galloping lox.

• Followers no longer shove the player around. Two causes. A player turning on the spot swings every formation point with them, and the follower chased the swing straight through the player — the reason companions pushed players off jetties and into deep water. Followers now settle further out and absorb a turn instead of tracking it. Separately, no resident ever gave way to a player: Valheim characters push each other physically, so one holding its course against a standing player slid that player backwards. Every resident now brakes for a player in its path, and presses on after two seconds so a player standing in a doorway can never freeze a job loop.

• The Hearthfolk panels can be resized with Interface.UiScale. They are drawn with Unity's immediate-mode GUI, which Valheim's own UI scale setting cannot reach — that setting drives the game's interface canvas, not ours — so on a high resolution screen the text stayed at its fixed pixel size with nothing the player could do about it. The new value scales the panels whole: text, boxes, item icons and the patrol map together. It is local to each client and never synchronised, because the right value depends on the screen sitting in front of the player and not on the server they joined.

• Fixed residents being unable to use chests stacked on top of each other. The reach test measured a straight line from the resident's eyes while the walk towards the chest measured ground distance only, so the height of the stack ate into the horizontal budget until no standing position could satisfy both: the resident walked under the stack, reported the storage as unreachable and waited there. Horizontal and vertical reach are now separate budgets, a chest standing in front of another chest is no longer treated as a wall blocking the line of sight, and both are exposed as Work.StorageReach and Work.StorageVerticalReach. Horizontal reach also grew from 2.8 to 3.2 metres, still well under the 5 metres the player enjoys.

• Fixed armed residents standing still instead of fighting. Two separate causes. A weapon was picked by taking the first matching item in the inventory, so a bow that happened to sit in an earlier slot than a sword disarmed the guard in practice: Valheim refuses to start a bow attack without ammunition, and the resident simply stood in front of its target. Weapons are now ranked, an empty bow does not count as a weapon at all, and the resident reports that it needs arrows instead of claiming to be armed. Separately, equipment was re-synchronised every two seconds and equipped a shield on top of a two-handed weapon or a bow; each of the two unequipped the other, so the pair flip-flopped forever and every swap restarted the equip animation. A shield is now only worn with a one-handed weapon, and during a fight the vanilla AI's own weapon choice is left alone.

• Residents carrying a bow restock arrows from a settlement chest, up to Guards.ArrowSupply (30 by default, 0 disables it), and never during an alert. Melee weapons still win over a bow when a resident owns both, because the vanilla creature AI handles a blade far more reliably than a player bow; a settlement that wants archers sets Guards.PreferRangedWeapons.

• Hearthfolk no longer ships sleeping structures. Residents now claim any ordinary player-built bed near the hearth, so the player raises whatever house they like out of Valheim's own pieces and puts beds in it. 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. The Settler Tent and Settler Lodge are retired: already placed ones load once, refund their full build cost and remove themselves, and neither appears in the hammer again. Everything that existed only to serve them is gone with them: the shelter component and its berths, the wake-from-tent routine, the procedural canvas, thatch, plank and flame surfaces, the decorative torches and the camp props. Roughly 2,900 lines removed.

• Fixed chest sorting rules being lost on the next login. A chest nobody has touched this session is ownerless, and Valheim resets ownership on every load, so the configuration RPC was broadcast with no owner to accept it: every peer ran the handler, every peer failed its owner check, and the rules were silently discarded. Configuring a chest now takes ownership first, exactly as the intake-role path already did, and the write is logged so it can be confirmed.

• Fixed the whole settlement scattering after one resident was attacked. A hit raises a twelve second alert during which every resident acquires a target; when that alert expired nothing released it again, because only Followers had a combat policy. Every other role kept its target forever, fell through to the base monster AI and chased with no leash and no job control. Working residents now hold a defensive policy of their own: they never go hunting, they fight what attacks them, and they disengage once the fight drags them away from where it started. Settlement defence radii were also cut so an alert no longer sends everyone sprinting fifty metres at a single wanderer.

• Smoothed resident movement. The steer-while-walking threshold sat at exactly 90 degrees, which is the turn a right-angle corner produces, so settlers stopped dead to rotate on some corners and not others depending on rounding; it now sits clear of the angles real routes generate. The default guard ring gained two more posts for the same reason, and a resident turning on the spot interpolates its facing per frame instead of stepping round at the think rate.

• Fixed Guards and Caretakers sitting by the fire all night showing "Resting until morning". A seated resident is pinned to its chair every frame, so the walk to the bed was silently overridden; any movement order now stands the resident up first. This also fixes a seated resident never being able to reach a food chest.

• A Guard with no configured Patrol Points now walks a watch ring around the hearth and faces outward at each post, instead of freezing wherever its last chase ended.

• Residents no longer get permanently stuck. Stall detection now measures actual body movement instead of distance to a logical target, so it also fires while a gateway or physical recovery route is active and while approaching a work target whose aim point shifts every tick. Every idle, meal, rest, sleep, seed, harvest and sorting trip that previously had no reachability check now backs off, temporarily marks the unreachable chair, chest or bed, and continues with normal behaviour instead of pushing against an obstacle forever.

• Fixed the two hard deadlocks that suspended a resident's entire job loop: a meal in hand in front of an unreachable seat, and the nightly bed routine looping between selecting and discarding the same access point. Residents now eat where they stand once the meal search window expires, and lie down from the validated access point.

• Fixed residents that stayed visible but completely inert when their shared inventory failed to bind on the first frame; the binding is now retried.

• Removed multi-second freezes caused by the physical path planner. Planning is capped per search and per frame, gateway searches stop once that budget is spent, path smoothing no longer scales quadratically, and the grid buffers and physics probes no longer allocate on every node.

• Reduced per-frame cost further: the settlement alert state is cached per frame instead of being recomputed up to ten times per resident, the door probe and open-door bookkeeping are throttled, structural obstruction raycasts are cached, the Farmer's crop stock sweep uses a narrow layer mask and a longer cache, and navigation logging is rate limited.

• On dedicated servers the host no longer races the responsible client for ownership of the same resident, which caused residents to freeze and rubber-band.

• Farm Markers now draw their exact circular field perimeter on the terrain while the player looks at them. Using a marker keeps the boundary visible for four seconds while cycling crops. The client-only visual follows uneven ground, reflects the live configured radius and adds no persistent objects to saves.

1.0.0

First public release, on Thunderstore and Nexus.

Everything listed in the README ships in this version: recruitable residents with persistent appearance and inventory, the Lumberjack, Miner, Farmer, Guard, Caretaker and Follower assignments, Farm Markers and crop cycles, per-role intake chests with sorting rules, daily meal and sleep routines with happiness, doors and gateway routing, and the settlement panel that drives all of it.

Earlier development history is kept in the repository's Git history rather than shipped with the package.