Valheim Kukolony0.5.2

You are viewing a potentially older version of this package. View Latest Version

Install with App

Date Uploaded

last month

Downloads

1.3K

Size

592KB

Download

Details Required (2)Versions

Kukolony

A villager colony system for Valheim. Place a hearth, hire villagers, register your chests and stations, hand out jobs — and they haul, chop, mine, forage, farm, cook, craft, mend and defend while you get on with the game. Take them adventuring, sail with them, and meet the villages that already live out in the world.

☕ Support the mod: https://buymeacoffee.com/kukukodes

I build Kukolony in between looking for work. If it is worth a coffee to you, that directly keeps me going. Thank you. 🙏

🛠️ The mod keeps growing on Patreon: https://patreon.com/KuchukboromDebbarma286

About this release

0.5.2 is the whole mod, with nothing held back. Earlier free versions shipped the colony half and kept the party, combat, boats, work flags, multiple colonies and the living villages switched off. This one turns everything on.

This is the current state of Kukolony, and it is the last free release. It will not receive further updates here. All work from now on — new features, balance, fixes — goes into the Patreon version. If you want to see where the mod goes next, or you want a say in it, that is where it happens: https://patreon.com/KuchukboromDebbarma286

What you have here is complete and playable as it stands. Everything below is in the box.

Requirements and install
Quick start
Keys
The Kolony
Villagers
Structures and their settings
Item categories
Jobs
Queues, presets and turns
Work flags and fields
The party
Combat and defence
Boats
Living villages
The map
Off-screen simulation
Multiplayer
Settings
Console commands
Good to know

Requirements and install

BepInEx (denikson-BepInExPack_Valheim) and Jötunn — both are listed as dependencies, so a mod manager fetches them for you.
Every player needs the mod, and so does a dedicated server. Villagers are simulated by whoever is nearest, and a machine without the mod cannot run them.
Optional: PlanBuild. If it is installed, villagers can build your blueprints (see Plan Totems). Nothing is needed if it is not.

Manual install: drop the Kukolony folder into BepInEx/plugins/. The config is written to BepInEx/config/com.kuku.kukolony.cfg on first launch, and every setting in it can also be changed in game (see Settings).

Quick start

Build a Kolony Hearth (in the hammer's build menu — 10 wood, 10 stone). It is the colony's record: its name, its people, its structures, its jobs. It starts with a random name; rename it on its screen.
Press [ (the Kolony key) to open the Kolony screen on the nearest hearth.
Hire a villager — Villagers → New villager. It costs coins (50 by default), arrives with a name and nothing else, and feeds and dresses itself from your chests.
Register a chest. Look at a chest inside the hearth's reach and open the screen, or use Structures → Register something nearby. Set what it holds: Food, Wood, anything.
Put food in a registered chest. Villagers eat from registered storage and starve without it. Put a bed in reach, register it, and give it a sleeper.
Add a job — Jobs → Add a job → Haul. It is ready as it is: loose items go to the chests that take them.
Give the job to the villager — on the job, Who runs this, tick the villager. Or make a preset (Presets → New) of several jobs in order and give that to everyone.
Watch it work. Hover a villager to see what it is doing; press Watch on its screen to follow it with the camera.
Grow from there: register a kiln and a smelter and add Tend; a cooking station and add Cook; an axe in a chest and Chop; a pickaxe and Mine; a Kolony Field and Farm.
Take someone along. Walk up to a villager and press Use: it follows you.

Keys

Every key below is configurable. The four mod keys are ignored while you are typing in chat, the console or a text box.

Key	What it does
`[`	Open the Kolony screen on the nearest Kolony. Press again to close.
`]`	Open the Kolony screen straight onto your party.
`\`	While looking at a registered structure: open its settings.
`Shift` + `\`	Toggle floating marks over every registered structure.
`Esc`	Back one screen; closes from the top screen.
Use on a villager	Follow me / stop following.
Crouch + Use on a villager (Ctrl + E by default)	Trade: give and take items.
Alt place + Use on a villager (Shift + E by default)	Open its management screen.
Use on a hearth	Says which key manages it.
Use on a Kolony Flag or Field	Opens its screen.
In watch mode: `Tab` / `Shift`+`Tab`	Next / previous villager.
In watch mode: `E`	Open the watched villager's screen.
In watch mode: `Esc`	Stop watching.

Hovering a villager shows only the keys that will actually work on it — a villager of another village says "Answers to X, not to you" instead.

The Kolony

A Kolony Hearth is a settlement. It owns:

a name (random at first, editable on the screen — it colours every pin the settlement owns on the map);
a reach: a circle (48 m by default, settable up to a ceiling) in which structures can be registered and work happens;
its villagers, its registered structures, its jobs and presets.

More than one Kolony per world is allowed in this release. SingleColony in the config restores the one-colony rule if you prefer it; while it is on, placing a second hearth says so.

Losing a hearth starts a cooldown (one real minute by default) before another can be raised, so a hearth cannot be hopped around the map to grab ground. By default any loss counts, including an enemy levelling your base; CooldownOnAnyLoss off counts only your own removal.

The Kolony screen is the front door to everything: villagers, party, reach, item categories, structures, jobs, presets, the World screen, the settings page, and two warnings that only appear when they matter — Getting nowhere (villagers with work who finish nothing) and Starving.

Hover the hearth for its name, headcount, structure count and the manage key.

Villagers

Hiring, naming, dismissing

New villager on the Villagers screen hires one. It costs NewVillagerCost coins (50; 0 makes them free).
Every villager has a name and its own appearance. Rename it on its screen.
Remove villager drops whatever it carries and wears where it stands and lets it go.
Send home returns a party member to its Kolony.

Food

Villagers eat from your registered chests. Food is worth its own burn time from the game's data, so a cooked meal keeps a villager going longer than a raw one. They eat when they run low (HungryBelowSeconds), and sit down on a nearby seat to do it when there is one.

A working villager burns food at FoodDrainRate × real time (0.5 = a meal lasts twice its own duration). Idle villagers barely eat.
Hunger only advances while the villager is loaded and ticking — a settlement you walk away from does not starve behind your back, and the step is capped after a long gap.
Starving shows red on the hover and on the Kolony screen. Whether it actually kills is StarvingKills (off by default for your colonies; villages starve for real).

Energy and rest

Every action costs energy (EnergyPerAction). Below TiredBelow a villager stops work and goes to rest; it resumes at RestedAbove. Rest is triggered by energy, never by nightfall — a settlement works in shifts.

Recovery is in in-game hours, so it scales with the day length:

Where it rests	Exhausted → rested
Its own bed (register a bed, set Sleeps here)	4 hours
At the hearth, no bed	10 hours
Where it stands	20 hours

Health, death and revival

Villagers have a real health pool (VillagerMaxHealth, 50) and heal while fed (HealFullSeconds; 0 uses the creature's own rate).
On death, everything drops where it fell — bag and gear locker both. The death is written into the Kolony's ledger and announced.
A fallen villager comes back at its bed after ReviveSeconds (one minute of world time, which only runs while the game does). A villager without a bed wakes at the hearth.

Gear

Every villager has a gear locker separate from its bag: armour slots (head, chest, legs, cape, belt) and racks for weapons, shields, torches and tools. The bag is for cargo only.

They dress themselves. New villagers arrive naked and shop your registered chests for the best piece per slot, roughly once a minute. Outclassed pieces go back to storage.
The right hands at the right time. The job's tool while working, weapon and shield in a fight, a torch at night — one owner of the hands at a time.
A villager never takes the settlement's last tool. A spare axe or pickaxe in a chest is shopped; the only one is left for you.
Each job kind carries a kit preference (what it reaches for). A kit shapes the choice and never blocks work.
Locker on the villager's screen shows it all, grouped, with Give and Take. Give gear hands over a piece from your inventory.

Getting around

Doors: a villager whose walk stalls against a closed door on its own ground opens it, and closes it behind itself a few seconds later (DoorCloseBehindSeconds) — only doors it opened, only when nobody stands in the doorway.
Jumps: a hop over a knee-high lip, and a deliberate step down when stranded above where it is going.
Stuck detection: a villager making no progress toward its destination for StuckGiveUpSeconds gives up and tries something else, and refuses that target for a while rather than walking the same impossible route again.
Small talk: villagers exchange a few words when they pass and greet a player who comes near. Rare on purpose.
Idle villagers stroll the grounds and sit on benches instead of standing like furniture.

Watching a villager

Watch on a villager's screen follows it with the camera and shows a live card: what it is doing, its job, which step of the job it is on (or which reflex has it — resting, eating, fighting), what comes next in its preset and how long the current turn has left, energy, food, health, stance, what it carries, where it is going, and its home. Tab cycles villagers, E opens the watched one's screen, Esc returns.

The hover

Look at any villager: name and Kolony, what it is doing (with a diagnosis when it is getting nowhere — "no axe in any chest"), energy and food (red when starving), how kitted it is, and the keys that will work on it.

Stance

Defensive fights back and reacts to a threat coming close; Aggressive seeks fights within AggressiveSeekDistance; Passive never fights. Set per villager, on its screen.

Structures and their settings

Only placed, networked build pieces inside a Kolony's reach (the hearth's circle or any of its flags) can be registered. Loose items and creatures cannot. A registered record stays visible if its object is destroyed or moves out of reach; it is marked and cannot be worked until you remove or repair it.

Registering:

Look at a piece and open the Kolony screen: a Register what you are looking at row appears.
Or Structures → Register something nearby: everything in reach that could be registered, searchable, each row saying what it would become.
Press \ while looking at a registered piece to jump straight to its settings.

Every structure has a name (editable), what it registered as, a status line that only speaks when something is wrong, Villagers may use this (off is a pause, not an unregistration), and then one row per capability, each opening its own screen:

Storage (chests and anything with an inventory)

Storage: anything (an overflow chest), only these, or everything except these — by single items or by whole category. Villagers file matching things here and carry mismatches elsewhere.
Villagers may use what is here. Off makes a keep-chest: villagers put things in but never take them out — these are my tools, leave them alone.
Take unclaimed items: dropped loot and spillover that no chest has claimed comes here.
At most: a cap per item, so a chest holds up to that many and no more.

Processing (fireplaces, smelters, kilns, cooking stations, fermenters, beehives, and anything a station protocol understands)

Keep fuelled with which fuel, and When: day and night or only at night (a hearth kept dark through the day saves most of a settlement's firewood).
Feed it what material.
Keep it how full (higher tops up sooner and burns stock faster).
What villagers do here: supply and clear, supply only, clear only.
What they carry to it: fuel and material, fuel only, material only.

Crafting (workbench, forge, cauldron, and other crafting stations)

Makes: a list of orders, each with How many (keep this many in stock, or make them once) and Up/Down to order them. Recipes needing a higher station level are listed with the level they need. OnlyKnownRecipes limits the list to what you have discovered.
Repair gear here: worn armour and tools may be mended at this station.

Rest (beds)

Sleeps here: which villager. A bed cuts rest from 10 hours to 4.

Fields (Kolony Field pieces)

Grows which crop, How big the circle is, May break new ground (whether it may sow outside already-cultivated soil), and whether to fill the field, keep a number growing or sow a number once. A Sown count reads back.

Plan Totems

With PlanBuild installed, a Plan Totem registers as a station this mod knows how to work: a tending villager asks it what the plan is still short of and carries exactly that, trip after trip, until the building is up. Drop a blueprint, register the totem, walk away.

Marks

Shift + \ floats a mark over every registered structure, so you can tell the Kolony's chests from everyone else's at a glance.

Item categories

Fifteen built-in categories classify every item by what it is, not by name, so modded items sort too:

Food · Potion · Ammo · Weapon · Shield · Armour · Tool · Ore · Metal · Wood · Stone · Seed · Trophy · Valuable · Material

Chests, job filters and stop when we have rules all take categories as well as single items.
Item categories on the Kolony screen lets you make your own named categories from any items, and fix a wrong guess for any item (this belongs in Food). Corrections are saved to the config, and on a server they are the server's.

Jobs

A job is named work a Kolony owns; a villager runs a queue of them. Every job has:

Name, and What it does.
Times before the next job (Repeat): how many finishes before the queue advances.
Where it works: the whole Kolony, and/or any of its flags, in the order you choose — the job works the first place with anything to do and moves on when that place is done. How far it reaches applies to the named places.
Walking past: work seen on the way is offered too; Work everywhere points the job at every place at once.
Who runs this: hands the job out to chosen villagers.

Ten kinds, chosen from Add a job:

Haul

Loose items on the ground go to the chests that take them, and chests are kept sorted. Which items and Never handles filter by item or category; Tidy containers too moves mismatched contents between registered chests; Fill the bag before delivering makes a round trip worth the walk. A villager never re-takes what it just put down.

Chop

What to chop: trees, logs, undergrowth. Which trees. Leave standing keeps that many trees of the place (do not strip this hillside). Stop when we have a stock of wood. Logs are cut up before new trees are felled so a colony finishes what it started; the wood lands on the ground for hauling. Needs an axe in a chest; a blunt axe is said, and a harder tree is fetched a better axe for.

Mine

Which ore, Also break loose rock, Stop when we have. Ore does not grow back, so the screen warns when there is no stock limit. Needs a pickaxe; a vein the pickaxe cannot bite is said and skipped.

Forage

What to gather (berries, mushrooms, flowers, anything pickable), Leave alone what does not grow back, Stop when we have.

Farm

Sows and keeps sown every registered Kolony Field, from seeds in your chests, at the crop's own spacing. Harvest is foraging's job; replanting is farming's.

Tend

Keeps stations running: fuel to fireplaces and hearths, ore to smelters, wood to kilns, mead out of fermenters, finished work off before it spoils — what each station wants is set on the structure, not the job. Never burn our last keeps a floor of fuel back for you, and How much is enough stops when the settlement has its fill. A big kitchen is loaded in one go: the villager fetches a bag for every station rather than one trip per station.

Cook

Loads every registered cooking station with raw food, waits beside them (waiting for food to cook), takes each piece off the moment it is done — never a burnt one — and leaves the cooked food on the ground for hauling to file. It stays for the whole batch and hands over when the last station is clear.

Craft

Makes the orders on your crafting stations from materials in your chests, and mends worn gear at stations that allow it (Mend below a wear percentage). Orders are reserved as they are taken up, so two crafters do not empty one chest for the same order.

Repair

Keeps the settlement standing: walks the registered pieces and hammers anything worn below Mend below. Needs a hammer in a chest. Free, like a player's repair.

Hunt

Sweeps the ground where the job works for anything hostile and closes with it — the job that actively hunts, so no stance has to. After the kill: pick up what it dropped sends the hunter to gather the drops around the kill into its bag, which hauling then files. It gives up on prey it cannot catch (a fleeing deer) after twenty seconds and leaves it alone for a while.

Getting nowhere: any job that finds nothing to do says so on the hover and the watch card — "none of the 8 foods it takes in any chest", "no pickaxe" — and after IdleWarnSeconds the Kolony screen counts it.

Queues, presets and turns

A villager's Work row is one thing: a single job, or a preset. A preset is a named list of jobs in an order — Hauler: Haul, Tend, Repair — and the unit you hand out to many villagers at once (Give it to everyone, Give it to some). Presets hold job identities, so editing a job changes it for everyone running it; applying one is a copy, so editing the preset later does not reach back.

The queue loops and runs by these rules:

A job that finishes consumes one repeat; when the repeats are spent the next job starts.
A job that fails (gave up on a target) consumes a repeat and moves on.
A job with nothing to do consumes nothing and yields to the next job at once.
Turns: one entry keeps a villager at most PresetTurnSeconds (two minutes) before the next gets its go, so a preset actually rotates even when the first job never runs out of work.
A full lap where nothing was possible pauses briefly rather than spinning.

The watch card shows the current step, what comes next, and how long the turn has left.

Work flags and fields

A Kolony Flag (5 wood) claims ground for a Kolony however far from home. Placing one opens its screen: name it, set its reach, and assign it to a Kolony. What its circle covers stays loaded, structures there can be registered, and jobs can be pointed at it — "the near copse, then the far one". Flags appear on the map named after the job that sends people there.
A Kolony Field (3 wood) marks ground to grow things in. Register it, tell it what to grow, and villagers with a Farm job keep it sown.
Both are worked by jobs the way the hearth is, and each can be given its own reach.

The party

Walk up to any of your villagers and press Use: it follows you. Press again to send it home, or use Send home / Send everyone home on the party screen (]).

Following: a party member keeps within PartyLeashDistance, closes to PartyComfortDistance, comes through doors and into dungeons with you, and — if genuinely stranded far behind — is caught up to your side with a "caught up" note rather than lost.
Party jobs are one list on the member's screen: duties that run all at once and work that runs in order.
- Collect drops — picks up what falls near you (leaving what is at your feet alone).
- Carry for you — takes your overflow (Take my overflow on the party screen).
- Keep the camp — when you stand still for CampSettleSeconds, pitches a fire, keeps it fuelled and cooks on it.
- Ferry loads home — walks a full bag home to file it and comes back (SupplyRunThreshold).
- Field work (chop, forage, mine…) within PartyWorkRadius of you.
Trade: Crouch + Use opens a two-way transfer with the villager. Give an item / Take on the party screen do the same.
Stance per member: Defensive, Aggressive, Passive.
The party screen shows each member's activity, food, energy, what it carries and who it follows, live.

Combat and defence

They fight with what they have: best weapon, then any sidearm, then fists — never standing helpless because the armoury was empty. Shields are raised with one-handed weapons. Arrows are conjured for a bow.
Stances: Defensive meets a hostile that comes within DefensiveReactDistance and finishes the fight; Aggressive seeks out of its own accord; Passive stays out of it.
Settlement defence (SettlementDefence): an attacked Kolony rings its alarm, defenders converge, resters wake. The Hunt job patrols proactively.
They give up on the uncatchable: a chase that lands no blow in twenty seconds is abandoned for a minute and a half — a creature that hits back cancels its own refusal.
Combat style (CombatStyle): Vanilla hands an engaged villager to the game's own combat AI — real spacing, real swings — and takes it back after; Direct drives the fight from the mod.
Friendly fire between villagers of one Kolony is off. Rival villagers fight each other for real.
Death drops everything; revival is one minute at the bed (see Villagers).

Boats

A crew that boards. Party members climb aboard your boat, take deck seats, and ride the voyage standing on the boards. One that cannot make the climb in ten seconds is helped aboard.
Nobody left behind. A follower stranded on the far shore blinks to your side when the boat is under way; one knocked overboard clambers back within OverboardRecoverSeconds; one that cannot swim is hauled out at once.
Deck combat: they fight from the deck when trouble sails close.
They step ashore when you do.

Living villages

With NpcColoniesEnabled on (the default), the world has villages of its own.

Where they come from

New worlds place NpcColonyCount villages (6) during generation, between NpcColonyMinDistance and NpcColonyMaxDistance from the centre. An existing save seeds the shortfall into zones you have never visited.
A village claims the ruins vanilla already scattered — abandoned houses, towers, hamlets — and visibly repairs them back to life. Its people are dressed for the biome: rags and a club in the Meadows, wolf armour and silver in the Mountains. Gear drops where they fall.
Finding one says You have found a settlement, and it appears on your map.

They are real

Villages are genuinely simulated at all times — working their own jobs, eating, sleeping, trading, fighting — whether or not anyone is nearby. Nothing is approximated. A village short of people takes in a newcomer after its dead would have revived.

Relations

Every colony keeps a ledger about every other: Hostile · Wary · Neutral · Friendly · Ally. It moves only by witnessed events — a delivered caravan, a landed blow, help that showed up. Villages are born with history between them; you always start a stranger, and every Kolony you raise counts as one identity: you.

Caravans: surplus goods leave a real chest in a real driver's bag and walk the real road to a friend. A caravan that dies on the way really loses its cargo.
Raids: a hostile village marches real raiders who plunder from an actual chest and bank the loot at home. Yours can be the target, and the victim's grudge is real.
Help calls: a besieged village calls for help; an allied village sends a fighter who really marches; if it counts you a friend, your map pings for three minutes.
Dispositions: a friendly village lets you walk its ground and trades caravans with its friends; a wary one warns you off and keeps its distance; a hostile one attacks on sight within its ground — off by default (NpcHostileVillages), a hostile roll wakes as wary while it is off. Village people are their own: you cannot manage, recruit or trade with them.
Arrival catch-up (NpcArrivalCatchup): a village you return to looks like time passed — fires lit, pantry grown — capped at NpcCatchupCapDays of absence.

The World screen

A door on the Kolony screen: a news feed of real headlines (caravans, raids, plunder, help calls, friendships turning), and every known village with its standing toward you, distance and bearing. Open one for its people, what it is rich in, its mood toward you and its politics with every other village, and Mark on map.

The map

Every settlement has a pin with its name and population; every villager has one labelled with what it is doing, updated as it moves, even when unloaded. Clicking either opens it.
Work flags a job points at are pinned, named after the job.
Icon says what a thing is; colour says whose it is: every pin a settlement owns shares one colour hashed from its name.
Pins are never written to your save.

Off-screen simulation

The colony keeps working when nobody is there. The server keeps a halo of zones loaded around every villager (KeepAliveHaloRings — 5 rings = 121 zones) and every registered structure, so distant villagers and villages keep genuinely moving, hauling and trading.

KeepAliveMaxZones caps the total (0 = no cap; reaching the cap is logged).
KeepAliveFilterObjects loads only what the Kolony needs in villager-only zones — villagers, registered structures, buildings, loose items, and trees only for colonies that gather.
KeepAliveEmptyGraceSeconds: after the last player disconnects, the world keeps running this long, then pauses until someone returns.
A travelling villager more than TravelObservedRange from any player covers ground unseen rather than walking a navmesh nobody has loaded.

Multiplayer

Every player and the server need the mod. Villagers are simulated by whoever is nearest; the server adopts any villager no live player holds.
World settings are the server's. Food, rest, claims, keep-alive, combat, the villages and the rest are sent to every client on join and locked there; only an admin may change them while connected. Keys and the log interval stay yours.
Two players near one kitchen no longer fight over it: a machine that loses a station it was loading waits a few seconds before taking it back, so the two take turns.
Dedicated servers are supported and were the deployment used during development.

Settings

Kolony screen → Mod settings shows every entry grouped by section: Yes/No for switches, nudged numbers over each entry's own range, cycling choices, typed keys and text, with Reset when a value is not the default and the description behind ?. Changes save to the config file at once. Entries marked (world) are the server's when you are on one.

Section	Setting	Default	What it does
Kolony	`ColonyScreenHotkey`	`[`	Opens the Kolony screen.
Kolony	`PartyScreenHotkey`	`]`	Opens the party screen.
Kolony	`StructureScreenHotkey`	`\`	Opens the looked-at structure's settings.
Kolony	`MarkersHotkey`	`\`	With Shift, toggles the registered marks.
Kolony	`ColonyRadius`	48	A hearth's reach in metres.
Kolony	`ColonyRadiusCeiling`	48	The most a hearth's reach may be set to.
Kolony	`FlagRadius`	48	A new flag's reach.
Kolony	`NewVillagerCost`	50	Coins to hire. 0 is free.
Kolony	`VillagersOpenDoors` / `DoorCloseBehindSeconds`	on / 4	Doors in the way, and closing them after.
Kolony	`VillagersJump`	on	Hops and step-downs when stuck.
Kolony	`VillagerSmallTalk`	on	Passing words and greetings.
Villagers	`GoHomeRadius`	8	How far a villager drifts from home before walking back.
Jobs	`ResourceScanRadius`	96	How far from a hearth or flag to look for trees and pickables.
Jobs	`StuckGiveUpSeconds`	60	No progress for this long → give up the trip.
Jobs	`ClaimsEnabled` / `ClaimTtlSeconds`	on / 30	Villagers reserve what they work on, for this long.
Jobs	`PresetTurnSeconds`	120	Longest one preset entry keeps a villager. 0 = off.
Jobs	`IdleWarnSeconds`	300	Finishing nothing for this long is reported.
Jobs	`ItemKindOverrides`	—	Your category corrections (edited in game).
Off-screen	`KeepAliveEnabled`	on	Colonies work with nobody near.
Off-screen	`KeepAliveHaloRings` / `SeaHaloRings`	5 / 5	Zones held around each villager, ashore and at sea.
Off-screen	`KeepAliveMaxZones`	0	Cap on held zones (0 = none).
Off-screen	`KeepAliveScanSeconds`	4	How often unloaded villagers are swept for.
Off-screen	`KeepAliveEmptyGraceSeconds`	600	Run-on after the last player leaves.
Off-screen	`KeepAliveFilterObjects`	on	Load only what the Kolony needs in held zones.
Off-screen	`TravelObservedRange`	96	Nearer than this, a traveller walks; farther, it covers ground unseen.
Off-screen	`NpcArrivalCatchup` / `NpcCatchupCapDays` / `NpcPantryTarget`	on / 7 / 30	A returned-to village looks lived in.
Work	`EnergyPerAction`	2	Energy per action.
Work	`TiredBelow` / `RestedAbove`	20 / 70	Rest thresholds.
Work	`BedHoursToRest` / `HearthHoursToRest` / `GroundHoursToRest`	4 / 10 / 20	In-game hours to recover, by where.
Work	`FoodDrainRate`	0.5	Food burn while working, × real time.
Work	`FedCapSeconds`	1800	Seconds of food a villager can hold.
Work	`HungryBelowSeconds`	600	Goes to eat below this.
Work	`StarvingGraceSeconds` / `StarvingKills`	1800 / off	How long with nothing before it dies, and whether it does.
Work	`ChopSwingSeconds`	2	Seconds between axe blows.
Work	`OnlyKnownRecipes`	on	Crafting orders limited to what you have discovered.
Work	`PartyLeashDistance` / `PartyComfortDistance`	12 / 4	Following distances.
Work	`PartyWorkRadius` / `GleanerStandOff`	28 / 6	Party work reach, and what is left at your feet.
Work	`CampFirePiece` / `CampSettleSeconds` / `CampStandOff`	fire_pit / 20 / 4	The camp keeper's fire.
Work	`SupplyRunThreshold` / `SupplyRetrySeconds`	0.8 / 120	When a ferry run leaves, and the retry after an empty one.
Work	`OverboardRecoverSeconds`	20	Floundering time before being hauled aboard.
Combat	`CombatStyle`	Vanilla	Vanilla AI or Direct, mod-driven fights.
Combat	`SettlementDefence`	on	Villagers fight at home.
Combat	`DefensiveReactDistance` / `AggressiveSeekDistance`	15 / 24	Stance ranges.
Combat	`VillagerMaxHealth` / `HealFullSeconds`	50 / 0	Health pool and heal time (0 = creature's own).
Combat	`ReviveSeconds`	60	World-time seconds before a fallen villager wakes.
NPC Kolonies	`NpcColoniesEnabled`	on	Villages exist.
NPC Kolonies	`NpcColonyCount` / `NpcColonyMinDistance` / `NpcColonyMaxDistance`	6 / 600 / 9000	How many, and where.
NPC Kolonies	`NpcHostileVillages`	off	Villages may attack on sight.
NPC Kolonies	`NpcStarvingKills`	on	Villages starve for real.
Release	`SingleColony`	off	One Kolony per world.
Release	`ColonyReplaceCooldownMinutes` / `CooldownOnAnyLoss`	1 / on	The hearth-loss cooldown.
Release	`WorkFlagsEnabled` / `PartyEnabled` / `CombatEnabled`	on / on / on	Master switches, if you want a quieter mod.
Logging	`ActivityLogSeconds`	30	How often a villager's activity is logged. 0 = every change.
Development	`DebugSpawnEnabled`, `VerboseTendLog`, `DebugProbeEnabled`, `DevGalleryEnabled`, `Benchmark…`	off	Developer tools. Leave off.

Console commands

Server-side, for hosts and admins:

Command	What it does
`kukolony_village [metres]`	Reserves an NPC village that far ahead of you (60); walk to it to build it.
`kukolony_npcseed [count]`	Prints where a seeding pass would put that many villages, without placing them.
`kukolony_gotovillage`	Teleports you to the nearest NPC village, reserving one if there is none. (cheat)
`kukolony_disposition [friendly\|wary\|hostile]`	Reports or sets the nearest village's disposition. (cheat)

Good to know

Villagers eat only from registered chests. No registered food is the most common reason a new colony stops.
Tools live in chests. Chop needs an axe, Mine a pickaxe, Repair a hammer — in a registered chest villagers may use. The last one is never taken.
A job says what work is; a preset says the order. Give villagers a preset unless you really want one job forever.
Reach is everything. A chest just outside the circle is not the Kolony's. Flags extend it.
Cooked food burns if nobody takes it off — give a Cook to a kitchen, not just a Tend.
Removing a registered structure's record from a client while it is not loaded there says "not found" whether it was destroyed or merely unloaded; the button is worded Remove anyway for that reason.
The log (BepInEx/LogOutput.log) carries every [report] line the mod told you and a sampled activity trace. If you report a problem on Patreon, attach it.

Credits

Built with Jötunn on BepInEx. Villagers wear the game's own player rig and gear. Blueprint building via PlanBuild when installed.

Kukolony is free. If it made your Valheim better, a coffee says so: https://buymeacoffee.com/kukukodes

Details