Villagers-Ymiron

Work in progress. Villagers for Valheim: vikings who live in your settlement, each with a name, a look, a home, a job and the courage to defend it.

What works now (0.23.0)

Villagers

• They use the player body: random gender, hair, beard, skin and hair color, simple clothes.
• Each one has a Norse name, shown when you look at them together with what they are doing.
• Talent: each villager was born for one trade, at a level: Novice, Skilled or Master Woodsman, Stonemason, Green Thumb (farmer), Smelter (stoker) or Handyman (caretaker). At that trade it works AptitudeBonus (25%) faster per level; farmers, stokers and caretakers also walk faster on their errands (at most +50%). At any other trade it works as anybody else. Villagers made before talents existed get one the first time they are loaded.
• Jobs are yours to give: villagers never take a job by themselves. Give each one its job from its panel or from the Village Hall; without one it rests in the village.
• Players cannot hurt them (unless PvP is on). They are saved with the world and look the same for everyone.

Homes and daily life

• A villager without a bed takes the closest free vanilla bed near its home. That bed becomes its home and shows "Astrid's bed (villager)". Beds claimed by a player (spawn point) are never taken; if a player claims a villager's bed, the villager gives it up and looks for another one.
• Free time: with nothing to do they look for a free chair, bench or throne in the village (40 m around home) and sit there for a while; without a free seat they walk along the paths drawn with the hoe (or visit fires, workbenches and furniture) or stroll a little. To reach a seat they open doors on the way; walks only go where no door must be opened, so they stay inside the walls. Workers whose job has nothing for them (no trees or rocks, nothing to sow or pick, no tool) spend the wait the same way, and get up as soon as there is work again.
• Map: villagers appear on the map and minimap with their name. When one dies, a death pin marks the place (kept until you remove it) so you can pick up what it carried.
• During the day they work or enjoy their free time; around sunset they walk to their bed and sleep until dawn. Without a bed they sit by a burning fire nearby (on a free chair or bench within its heat, else on the floor around it, never on a table), or wait at home if there is none.
• Doors and gates: villagers have their own walking map, where the doors they can open are not walls. Their way goes through the house door and out of the gate like yours: at each closed door on the way they stop, open it, walk through and close it behind themselves (unless a player or villager is in the doorway). Locked doors and doors that cannot be closed again are walls. When fighting or fleeing they never open a door or gate.
• Drawbridges: lowered, villagers walk over them; raised, they are a wall. A villager whose way is cut by a raised drawbridge walks to it on its own bank, lowers it, waits for it to come down, crosses and raises it behind itself (unless someone is on it). It never walks into the moat to reach it.
• Villager Path Marker (hammer, next to the woodcutting zone, 1 wood): a small flat disc on the floor. Where villagers cannot find the way by themselves (big houses, sunken floors, odd stairs), mark the way with markers and link them: use a marker, then the next one (using a linked pair again removes the link); markers placed one after the other are linked automatically. The markers are walk-through (nobody trips on them). When a villager walks near a linked network (markers within 25 m of it or of its destination) the network is its preferred way: it walks the links in straight lines, opening the doors on them, and leaves the last marker on its own. With the hammer in hand the links are drawn: green clear, yellow a step too high or a drop on the way, red something solid in the way (villagers skip red links), with a post on the exact spot and its name when linking.
• Getting unstuck: a villager held back by something (a post, a step, a door leaf) asks for a new path, steps aside and jumps; after several tries it picks another target. One that cannot get any closer to its bed for a minute gets into it anyway, instead of standing against a wall all night. A villager that finds no way at all for 30 s (walled in by something the game's pathfinding cannot handle) appears where it has to go (UnstuckTeleport). Villagers hop over low sills and steps (up to 60 cm). A villager held back without progress for 30 s appears at its destination too.

Woodcutter

• Woodcutter's Lodge (hammer, Village): a small woodcutters' camp (lean-to, chest, log pile, chopping block). A villager you give this job works there. Put an axe inside: the best one is used.
• The woodcutter is a craftsman inside the base: at the chopping block it makes the wood you choose, blow after blow (with the axe's swing and sound), one piece at a time, out of nothing. The woods (WoodProducts): wood, core wood, fine wood, ancient bark, Yggdrasil wood, Ashlands wood, Deep North wood. Each needs the axe the game asks to cut the trees that give it.
• Shift + E on the lodge opens the work panel: every wood on its own row (icon, time per piece, how much is inside, the axe it needs) with a Choose button, and the piece being made with its progress bar.
• It is not instant: by default one piece every 30 s of work for wood, 60 s core wood, 90 s fine wood, 120 s ancient bark, 180 s Yggdrasil wood, 240 s Ashlands wood, 300 s Deep North wood. Each piece wears the axe as ToolWearPerItem (3) blows. Hunger, cold, unhappiness and traits slow it down.
• With the axe too weak for the chosen wood, no room, or no axe, the woodcutter rests in the village and goes back to work as soon as it can.
• While nobody is around the game does not simulate villagers: when you come back, the work of that time is done at once, limited by the free space and the axe's durability.
• Village Storehouse (hammer, Village): the collection point of the village, an open storehouse with a plank floor and a gabled roof, with a storage of 8x4 (look at it and press E). It starts bare: as it fills up, log stacks, stone, flint and coal piles, crates, barrels and sacks appear on the platform, according to what it holds.
• In the evening the woodcutter brings what it made to the storehouse; what does not fit is left next to it. Without a storehouse it is left on the ground next to its bed.
• The old Woodcutting Zone banners are no longer used and no longer in the hammer: those already built stay as decoration (remove them with the hammer to get the materials back).

Stonecutter

• Stonecutter's Quarry (hammer, Village): an open stone yard: a tripod crane lifting a cut block, a mason's bench with a slab, mallet and chisel, a raw boulder with a pickaxe stuck in it, a stack of cut blocks (look at it and press E to open its storage). A villager you give this job works there. Put a pickaxe inside.
• The stonecutter makes the stone you choose at the boulder, as the woodcutter (StoneProducts, Shift + E to choose): stone (30 s), flint (45 s), obsidian (120 s), black marble (180 s), grausten (240 s), ice (300 s), each with the pickaxe the game asks to break the rocks that give it. Ores are still yours to find and mine. In the evening what it made goes to the storehouse.
• The old Quarry Zone cairns are no longer used, as the woodcutting zones.

Needs

• Each villager has food, warmth and morale (0-100%), shown when you look at it.
• Village Pantry (hammer, next to the storehouse): a larder with shelves, barrels and hanging food. Put any food players can eat inside: hungry villagers come to eat between two tasks (at once when starving), the humblest food first. They never touch your own chests. Shift + E on the pantry lists the foods inside: click one to forbid it (it stays there for you) or allow it again.
• Warmth comes from a burning fire (the same heat that warms you): at night without one they cool down, slowly under a roof, fast in the open; by day only cold or freezing weather in the open chills them.
• Morale drifts toward how their life is: fed, warm, a bed and how comfortable its place is (the game's comfort level), some rest on a seat; a villager who died nearby saddens the others for a day.
• Hungry, cold or unhappy villagers work slower and hit weaker; in despair (morale below 10%) they stop working until things get better. Nobody dies of hunger.

Farmer

• Village Farm (hammer, Village): a thatched shed with a potting bench; look at it and press E to open its storage. A villager you give this job works here as a farmer.
• Till the ground yourself with the cultivator: the farmer never changes the terrain. In its fields it picks what is ripe and sows the same crop again on the same spot, with what it just picked (barley, flax) or with the seeds in the farm.
• The empty tilled ground is sown in tidy rows with what you put in the farm (carrot seeds, turnip seeds, barley, flax, a carrot to grow carrot seeds...), the crop of the neighbouring rows first.
• Crop priorities: Shift + E on the farm opens its panel, one card per crop with - and + to give it a priority from 1 to 5 (3 by default). The free ground is shared among the crops with seeds in the farm in proportion to their priority (carrots 5, onions 4, turnips 2: about 5:4:2), the one furthest behind its share first. A harvested spot is sown again with the same crop only while that crop is within its share, so changing the priorities reshapes a full field little by little.
• Harvesting needs nothing; sowing needs a cultivator in the farm (it wears out as for a player).
• The harvest goes back to the farm; in the evening the farmer carries it to the Village Storehouse, with the wood and the stone. Of the finished goods (carrots, turnips, onions, barley, flax...) it keeps KeepForSowing (10%) in the farm to sow again; of the seeds it keeps SeedReserve. Fill the pantry yourself with what the villagers should eat.
• Field Scarecrow: marks a field of the closest farm. It is built on tilled ground and covers the tilled patch it stands on, up to the paths, grass or untilled strips around it (at most FieldRadius away): two fields side by side with a path between them stay apart. Ground you till next to the field joins it within a few seconds. A farm without scarecrows tends the tilled ground around itself.
• What a field grows: Shift + E on the scarecrow opens its panel. Click one or more crops (click again to take one away): carrot seeds, carrots, or both, and so on. Any crop clears the choice and lets the farm's priorities decide. In a field with several crops they take turns, weighted by their priority. The panel and the scarecrow tell which seeds the farm is missing for that field, and when the farmer could not walk there lately (with where its way stops).
• E on a scarecrow still moves the field to another farm in range.

Stoker

• Stoker's Shed (hammer, Village): a lean-to against a low stone wall, with a coal bin, crates of ore, a log stack and a wheelbarrow (look at it and press E to open its storage). A villager you give this job works there as a stoker.
• It tends the smelters, blast furnaces, charcoal kilns and eitr refineries within StokerRadius (20 m) of the shed: it collects what they made and brings it to the shed, keeps their fuel up and fills them with what they work on, taking ore, coal, wood, soft tissue... from the shed. One errand at a time, the most urgent first: finished pieces waiting, a machine about to run out of fuel, a machine with room for more. It uses the machines as a player does, so they run as usual; the coal of the kilns goes back into the shed and fires the smelters.
• Shift + E on the shed opens its panel: one card per machine around it (the 16 closest), with its fuel, its load, the pieces ready and its distance. Click a machine to switch it between TENDED and IGNORED: the stoker leaves ignored machines alone, so you can keep some for yourself.
• In the evening the finished pieces (bars, eitr...) go to the storehouse; ore, coal and the rest stay in the shed.
• With nothing to do it rests in the village. The machines keep working by themselves while nobody is around.

Caretaker

• Caretaker's Workshop (hammer, Village): a lean-to with a carpenter's bench, a tool rack, an anvil on a stump, logs and a bucket of resin (look at it and press E to open its storage). A villager you give this job works there as a caretaker. It looks after the base within CaretakerRadius (30 m) of the workshop, one errand at a time, in this order: worn tools (and gear in the workshop), fires and torches, damaged pieces, things lying around. Worn tools waiting make it leave the repairs of the base at once:
  • Fires and torches built by the players (campfires, hearths, braziers, sconces, torches): a fire about to go out first, then any at or below FuelBelow (50%). The fuel comes from the workshop: put inside wood, resin, guck, greydwarf eyes, coal... whatever your fires burn. It brings enough for every fire of that kind and feeds them in a row. Fires turned off by a player stay off.
  • Worn tools: axes, pickaxes and cultivators below ToolRepairBelow (25%) in the other workplaces of the village (within ToolRadius, 100 m, and any worn piece in the armory) are taken to the workshop, repaired at the anvil and brought back where they were. The worker rests meanwhile.
  • Damaged pieces below RepairBelow (80%): repaired on the spot with the hammer, as a player does; the pieces within reach are done one after the other.
  • Gear put in the workshop (yours too) is repaired there.
  • Things lying on the ground for at least CollectDelay (2 min) are brought to the storehouse. Never weapons or armor, food near tamed animals, what lies next to a storehouse, or what a stoker's machine just made; list more in CollectIgnore (e.g. ChickenEgg, so the eggs stay on the floor and hatch), or turn it off with CollectItems. Without a storehouse nothing is picked up.
• Repairs cost nothing and need no workbench or forge. With nothing to do it rests in the village.
• Drawers (with ItemDrawers-Ymiron installed, SortIntoDrawers): in the evening, once the others have brought the day's work to the storehouse (it waits for them a little), the caretaker carries what the storehouse holds into the drawers within DrawerRadius (40 m) of it, trip after trip, a whole wall of drawers at a time. Only into compartments already set to that item: you decide what goes where, and what has no compartment stays in the storehouse. Then it goes to bed.

Recruitment

• Village Horn (hammer, Village): blow it (E) and three newcomers answer. A panel shows them side by side: a live portrait, their name, their talent, their good and bad traits and the coins they ask (good traits and a higher talent cost more, bad traits less).
• Hire one: the coins are taken from your inventory, and a while later (WandererArrivalSeconds) the newcomer appears right by the horn, already one of the villagers (takes a free bed and waits for you to give it a job). The same candidates are shown to every player; new ones come each day. After a hire the horn rests for HornCooldownDays.
• A newcomer comes only if there is a free bed near the horn and, with needs on, food in a pantry.
• Traits: Strong / Weak, Tireless / Lazy, Frugal / Glutton, Hardy / Chilly, Cheerful / Grumpy, Brave / Coward. They change work speed and strength, hunger, how much the cold bites, morale and courage. A newcomer has one or two good traits and usually one bad. Villagers made before traits existed get theirs the first time they are loaded.

Villager panel

• Press E on a villager: a panel in the game's own style opens. Left, a live portrait of the villager, its health and its gear; middle, its needs (food, warmth, morale) with the strength it works at, and its home (bed, comfort); right, its work (workplace, tool, zones). From there you can send it to a free workplace (the ones of its talent first) or dismiss it. E, Esc or the X close it.

Village Hall

• Village Hall (hammer, Village): a roofed notice board with notes pinned on it, a lantern and a lectern with the ledger. Press E on it to run the village:
  • Villagers (left): every villager within HallRadius (100 m), a row each: name, talent, job (with the talent's bonus when it is its trade), what it is doing, health, food, warmth and morale. Those without a job come first. Job on a row lists the workplaces for it (its talent's first): free ones, or taken ones (the worker there is left without a job), or Leave its job. Call brings a villager stuck somewhere next to the Village Horn closest to the hall at once (whatever it was doing is dropped).
  • The village (right): villagers and beds, the average needs, the pantry, the storehouse (slots and what it holds most), the workplaces (without a worker, missing tool, no machines) and the upkeep (fires low, damaged pieces, worn tools).

Defense

• Village Armory (hammer, next to the lodge): a weapon rack with spears and shields; look at it and press E to open its storage. Put melee weapons, shields and armor inside: during the day each villager comes to take the best pieces it can use and brings back what they replace.
• Villagers fight monsters that come for them or close to them: with their weapon, else the tool in their hand, else their fists. Their blows only hit the monster, never the base.
• Below 30% health, or against much stronger enemies (trolls, bosses), they run home instead.
• What a villager carries (weapons, armor, wood) is saved with it and dropped where it dies.

Test commands

Enable devcommands in the console (F5), then:

Command	What it does
villager [count]	Spawns villagers in front of you (max 20).
villager_clear [radius]	Removes the villagers around you (default 30 m).
villager_info [radius]	Shows what the villagers around you are doing.
villager_path	Can the closest villager walk to where you stand?
villager_map [radius]	Shows for a minute where the closest villager can walk: green reachable, red cut off.

Configuration

Server settings: on a server with the mod, the server's config is used by everybody (sent when you join and whenever the server's file changes; your own file is not touched, and is used again when you leave). Personal settings stay yours: MarkerToggleKey, MarkersVisible, ShowOnMap, DeathPins, VerboseLog. A server without the mod: everyone uses their own file.

File BepInEx\config\ymiron.valheim.villagers.cfg (reloaded automatically when saved):

Section	Key	Default	What it does
1 - Villagers	Health	100	Maximum health of new villagers.
1 - Villagers	Outfits	rags/leather sets	Starting clothes picked at random: outfits split by ,, items by +.
1 - Villagers	AptitudeBonus	25	Percent faster per talent level at the villager's own trade.
2 - Behaviour	WanderRadius	8	How far they stroll around home (m).
2 - Behaviour	VillageRadius	40	Free time happens within this distance of home (m).
2 - Behaviour	ShowOnMap	true	Villagers on the map and minimap.
2 - Behaviour	DeathPins	true	Death pin on the map where a villager dies.
2 - Behaviour	MarkerRequirements	Wood:1	Cost of the path marker.
2 - Behaviour	MarkerToggleKey	F8	Hides/shows the path marker discs (they keep guiding the villagers; the hammer still shows the links).
2 - Behaviour	MarkersVisible	true	Whether the discs are shown (set by the key).
2 - Behaviour	MarkerLinkDistance	15	Longest link between two markers (m).
2 - Behaviour	UnstuckTeleport	true	A villager with no way to its destination for a while appears there.
2 - Behaviour	UnstuckTeleportDelay	30	Seconds without a way before that.
2 - Behaviour	VerboseLog	false	Writes what every villager does (states, errands, paths, meals) to the log and console; off, only warnings and the main events.
2 - Behaviour	WanderInterval	8	Seconds between two strolls.
3 - Safety	ThreatRadius	12	They react to visible hostile creatures closer than this (m).
3 - Safety	FleeDistance	20	How far they run each time they flee (m).
4 - Home	BedSearchRadius	30	A villager without a bed takes a free bed within this distance of its home (m).
4 - Home	FireSearchRadius	25	Without a bed, at night they sit by a fire within this distance of home (m).
5 - Woodcutter	LodgeRequirements	Wood:20,Stone:6	Cost of the lodge.
5 - Woodcutter	LodgeWidth / LodgeHeight	6 / 3	Size of the lodge storage.
5 - Woodcutter	JobSearchRadius	100	A jobless villager takes a free lodge (and uses an armory) within this distance of its home (m).
5 - Woodcutter	SwingInterval	1.8	Seconds between two axe swings.
5 - Woodcutter	WoodProducts	Wood:30, RoundLog:60, FineWood:90, ...	What the woodcutter can make, as Item:Seconds per piece (optional @Tier).
5 - Woodcutter	ToolWearPerItem	3	Each piece made wears the tool as this many blows.
5 - Woodcutter	OfflineMaxDays	1	At most this many in-game days are caught up.
5 - Woodcutter	StorehouseRequirements	Wood:30,Stone:10	Cost of the storehouse.
5 - Woodcutter	StorehouseWidth / StorehouseHeight	8 / 4	Size of the storehouse storage.
7 - Stonecutter	QuarryRequirements	Wood:15,Stone:15	Cost of the quarry.
7 - Stonecutter	StoneProducts	Stone:30, Flint:45, Obsidian:120, ...	What the stonecutter can make (as WoodProducts).
9 - Recruitment	HornRequirements	FineWood:10,DeerHide:2	Cost of the horn.
9 - Recruitment	HornCooldownDays	1	Days before the horn can be blown again.
9 - Recruitment	WandererArrivalSeconds	40	Seconds before the wanderer shows up.
9 - Recruitment	WandererWaitDays	1	Days a wanderer waits to be welcomed.
9 - Recruitment	RecruitRadius	40	Free bed and food must be within this distance of the horn.
9 - Recruitment	RecruitBaseCost	60	Coins a newcomer asks before its traits are counted.
9 - Recruitment	RecruitCostPerGood	30	Coins added for each good trait.
9 - Recruitment	RecruitCostPerBad	20	Coins taken off for each bad trait.
9 - Recruitment	RecruitMinCost	10	The lowest price.
9 - Recruitment	RecruitCostPerTalentLevel	15	Coins added for each level of the newcomer's talent.
13 - Village Hall	HallRequirements	Wood:20,FineWood:6,Resin:4	Cost of the Village Hall.
13 - Village Hall	HallRadius	100	Villagers and workplaces within this distance are listed (m).
10 - Farmer	FarmRequirements	Wood:20,Stone:4	Cost of the Village Farm.
10 - Farmer	FieldRequirements	Wood:4	Cost of the Field Scarecrow.
10 - Farmer	FieldRadius	10	How far a field reaches from its scarecrow at most (or the ground tended around a farm without scarecrows).
10 - Farmer	SeedReserve	30	Seeds of each kind (carrot, turnip, onion seeds...) kept in the farm; the rest goes to the storehouse.
10 - Farmer	KeepForSowing	10	Percent of the finished goods kept in the farm to sow again; the rest goes to the storehouse.
10 - Farmer	HarvestCarry	30	The farmer brings the harvest home once it carries this many items.
11 - Stoker	ShedRequirements	Wood:20,Stone:10	Cost of the Stoker's Shed.
11 - Stoker	StokerRadius	20	The stoker tends the machines within this distance of its shed (m).
11 - Stoker	StokerStations	smelter, blastfurnace, charcoal_kiln, eitrrefinery	The machines it tends (piece prefab names).
12 - Caretaker	WorkshopRequirements	Wood:20,Stone:10,Resin:5	Cost of the Caretaker's Workshop.
12 - Caretaker	CaretakerRadius	30	The caretaker looks after the base within this distance of its workshop (m).
12 - Caretaker	FuelBelow	50	A fire or torch is fed at or below this percent of fuel.
12 - Caretaker	RepairBelow	80	A piece is repaired below this percent of health.
12 - Caretaker	ToolRepairBelow	25	A tool (or armory piece) is taken to be repaired below this percent of durability.
12 - Caretaker	ToolRadius	100	Worn tools are fetched from the workplaces and armories within this distance (m).
12 - Caretaker	SortIntoDrawers	true	With ItemDrawers-Ymiron: sorts the storehouse into the drawers in the evening.
12 - Caretaker	DrawerRadius	40	The drawers within this distance of the storehouse are filled (m).
12 - Caretaker	CollectItems	true	Brings the things lying on the ground to the storehouse.
12 - Caretaker	CollectDelay	120	Seconds a thing must lie there before it is picked up.
12 - Caretaker	CollectIgnore	(empty)	Items never picked up (prefab names, comma separated).
8 - Needs	NeedsEnabled	true	Needs on/off (off: always full speed).
8 - Needs	PantryRequirements	Wood:20,FineWood:4	Cost of the pantry.
8 - Needs	HungerPerDay	30	Food bar used up per in-game day.
8 - Needs	EatBelow	45	They go to eat below this.
8 - Needs	FoodValue	0.35	Food bar per point of health+stamina+eitr of the food eaten.
6 - Defense	ArmoryRequirements	Wood:20,Stone:6	Cost of the armory.
6 - Defense	CombatDamage	1	Multiplier of the weapon's damage when a villager hits a monster.
6 - Defense	AttackInterval	1.4	Seconds between two blows.
6 - Defense	RetreatHealth	0.3	Below this share of health a villager runs home.
6 - Defense	TooStrongFactor	4	Enemies with more than this many times a villager's health are avoided.

Installation

Needed on every player's game, same version for everyone: villagers are world objects, and a player without the mod cannot see them (villagers near them stay still until a player with the mod comes close and takes them over).

On a dedicated server the mod is optional but recommended (copy the same Villagers.dll into the server's BepInEx\plugins, with BepInEx installed there):

• with it, the server's config file is everybody's (costs, radii, timings), sent when a player joins and whenever the file changes;
• without it, villagers and pieces are saved as usual and nothing breaks, but each player uses their own config file: keep them the same.

Each villager is run by one player at a time (the one the game gives it to, as for monsters). Orders (a job, a call from the Village Hall, a welcome) and hires at the horn go to that player; when it is someone who cannot carry them out (no mod, an older version, a server without the mod), the player giving the order takes the villager or the horn over first, so nothing is lost.

• Mod manager (r2modman / Thunderstore Mod Manager): Settings > Import local mod and pick the zip.
• Manual: copy Villagers.dll into BepInEx\plugins.

Requires BepInExPack_Valheim.