Village Companion

By Jay_Walk_King — experimental release 0.18.2

Recruit Viking NPCs and build a working settlement: defenders, haulers, harvesters, miners and animal keepers. Equip villagers, share them with your tribe, assign work areas and give them passive gathering buildings.

These villagers are NPCs, not fake multiplayer connections. Other mods that specifically require real player connections may not recognize them.

Guide contents

• Install and start
• Your first villager
• Controls and orders
• Equipment and classes
• Chest filters
• Jobs
• Night routines and anchor rebuilding
• Tribes and saving
• Knockout taming
• Console and developer tools
• Suggested test session
• Troubleshooting and reporting bugs
• Configuration and release status

Install and start

1. In Thunderstore Mod Manager or r2modman, select Valheim, the correct store and your testing profile.
2. Install VillageCompanion by Jay_Walk_King with dependencies. It requires denikson-BepInExPack_Valheim 5.4.2351.
3. Launch with Modded / Start modded. Starting normally through Steam does not select your manager profile.
4. Begin with a disposable world and character. Back up existing saves before testing this experimental release.

Every participating multiplayer client and the host/server need the same mod version. Multiplayer and dedicated-server behavior still need live verification; do not assume solo results establish multiplayer compatibility.

Remove older manual copies of VillageCompanion.dll before using the managed version. Keep only one copy in the active profile. The manager may put its own loader files in Valheim's game folder; the plugin and its configuration belong in the profile.

Your first villager

1. Obtain wood and stone, equip a normal building hammer and find Summon Anchor in Misc.
2. Build it for 5 wood + 2 stone, with clear dry ground around it. No crafting station is required. It looks like a portal but does not teleport.
3. Press E on the anchor and summon a villager. Default recharge: 60 seconds per anchor after a successful summon.
4. Press E on the villager to claim them and open their inventory. You must already have an anchor accessible to your ownership/tribe.
5. Equip gear and choose a class in their inventory, then give orders with the . command menu.

Villagers can also appear near surviving abandoned huts/town ruins in the Meadows. Defaults: one attempt every 120 seconds, 30% chance, with a nearby limit of 2 loaded villagers within 100 metres of a ruin. These are attempts, not guaranteed spawn times. Summoning is easier for repeatable tests.

Controls and orders

• E on villager: claim/open inventory outside command selection.
• . / > key: open or close the command menu. This is the Period key, not a requirement to hold Shift.
• Left click while aiming at a villager: select/deselect. Selected villagers are highlighted. Selection range is 30 metres.
• E after selecting: confirm the group.
• Esc or .: cancel/close an order.

For a job: Class orders → click villagers → E → choose the job → choose its destination/area. A group must have the same class. Mixed classes trigger a request to reselect; assigning a job does not automatically change their class.

The main menu also provides Follow, Carry, Place, Unload and Inspect. Carry/Place help relocate villagers. Unload drops removable inventory contents near you; equipped and protected starter items are kept. Inspect records individual details in the game log.

Defense placement: aim at clear ground, click and release to set a stationary guard point. Hold left click and move your aim to draw a patrol; release over valid ground to confirm. Routes support up to 64 points / 100 metres total. Aim within 60 metres.

Hauling, farming and husbandry areas: left click/drag paints 2-metre grid cells; right click erases; E confirms. Nearby wooden/stone floor snap points help align the grid. Only painted cells count; gaps remain outside the job. Up to 4,096 cells can be selected. Earlier painted areas are converted when loaded. Use modest areas for your first test.

Equipment and classes

Open inventory with E. Add equipment, then right click it in the villager inventory to equip it. Adding a replacement alone does not unlock starter gear: equip the replacement first. Starting gear is a club, rag chest and rag legs.

Class controls in the inventory select Defender, Hauler, Harvester, Miner or Animal Keeper. Icons above villagers show their class; the defender icon combines a shield and spear. Class changes and new orders can interrupt existing assignments.

Default starting health is 200. Equipped armor contributes protection. Villager gear does not lose durability, and arrows are not consumed. Supply the arrow type you want them to use; knockout arrows change the purpose of their shots.

Chest filters

Open a chest normally. Three filter slots appear to the right of its inventory:

1. Drag an item onto a filter slot. This records its icon/type; it does not consume or transfer the sample.
2. Right click a filter to clear it.
3. Toggle All to accept other items as well. Explicit item filters are preferred over All storage.

Filters control where workers put items and which supply chests they use. A filter does not create supplies: put actual seeds/animal food in the chest. Chests must have space, be accessible through wards and belong to the current local network owner. Workers skip chests while someone is using them.

Default delivery/supply search range is 60 metres from the work area, not necessarily from the worker. For initial tests, place chests beside the painted area with an unobstructed route.

Jobs

Defenders

Choose Defender class, equip a weapon and assign a guard spot or patrol. Melee defenders normally acquire enemies within 10 metres and pursue up to 20 metres from their defense origin. Being attacked or a nearby related villager being hit can trigger a defense response beyond normal acquisition range.

Archers use enemy-style projectile firing and native turret target selection. Their default bow range is 30 metres, with initial acquisition at half that range (15 metres). Existing targets/retaliation can use the larger bow range. Both target acquisition and releasing shots require line of sight. Solid walls and other obstructions block shots. These bow ranges are separate from melee pursuit limits.

If displaced from their position, archers try to return. If the route is unavailable, they can reposition in a small area around their landing spot to regain a shot. Supply a walkable route back to elevated platforms when possible.

Damage multipliers are 70% for ranged and 85% for melee relative to the unmodified villager attack. These are not promises of matching player DPS: weapon, armor and encounter conditions still matter. Defenders work at night. Tamed animals and animals under knockout protection are excluded from their attacks.

Haulers

Choose Hauler class, mark destination chests and paint an area. Haulers collect loose items, mine output whose entrance is in their area, and supported wild pickable resources. Supported wild item types include stones, flint, branches/wood, dandelions, thistle, red/yellow/blue mushrooms, Jotun puffs, Magecaps, raspberries, blueberries and cloudberries.

Player-planted/player-created resources are excluded, including marked grown crops. This is gathering existing pickables, not chopping trees or mining deposits. No matching usable chest means the worker waits rather than collecting endlessly. Leave inventory space for cargo.

Harvesters

Choose Harvester class, give them a cultivator, paint a planted field and set up marked chests for both planting supplies and harvest output. A cultivator must be in the villager's inventory. Equip it for a clear test setup.

Farmers harvest mature supported crops and replant the same crop using actual planting materials. Support is derived from cultivator plant recipes with one material requirement and a harvestable grown form. Perennial pickables that regrow in place are excluded from replanting to prevent duplicates. They do not cultivate new terrain, plan a new field or plant arbitrary new crops across empty cells.

For a simple test, plant carrots on cultivated ground, supply carrot seeds in a seed-filtered chest and mark another chest for carrots. Crop ownership/tribe and ward access must allow the worker to use the field. If a replant is pending, keep its location inside the assigned area and provide the required materials.

Animal keepers

Choose Animal Keeper class and paint a pen containing tame animals. Supported species are boars, wolves, lox and hens. Supply their normal food in marked chests and mark output storage for their drops.

The class orders panel lets you set how many adults of each species to retain, from 2 to 50, default 2. Babies, founding adults and pregnant animals are preserved. Only eligible grown offspring above the chosen adult count are harvested. An old adult is not automatically eligible merely because it is above the count.

Native breeding requirements still apply: food, partner proximity, population limits and safe conditions. The keeper's inventory report flags hunger, nearby damaging fire, frightened animals, missing partners, overcrowding and missing output storage. It is a report of detected conditions, not a guarantee every torch or campfire prevents breeding.

Village Mine and miners

Obtain copper ore yourself before using a mine. Build Village Mine with the hammer for 20 wood + 10 stone + 1 copper ore. It has a brown dungeon-entrance appearance and copper-ore build icon.

Give Miner-class villagers pickaxes. Choose Class orders, select/confirm them, choose Mine, then left click the mine. Capacity: 3 miners. Press E on the mine to choose ore or open its output. You must have personally discovered each selected ore; unsupported ores are not available.

Default production per miner, measured in active working time:

• Copper or tin: 1 per 10 minutes.
• Iron scrap: 1 per 20 minutes.
• Silver: 1 per 30 minutes.
• Flametal: 1 per 45 minutes.

Miners walk to the entrance, disappear inside and rest outside after 4 minutes, for 1 minute. Rest and night sleep reduce wall-clock production. Multiple active miners contribute to shared production progress. There is no offline catch-up. Output has 8 inventory slots and production requires room.

To automate delivery, paint a separate hauler area over the mine entrance and use a nearby chest filtered to its ore. Demolishing/destroying the mine immediately releases occupants; distance unloading is not treated as demolition.

Gatherer's Hut

Build with a normal hammer for 4 red mushrooms + 10 wood. Press E, select one or two owned Haulers within 60 metres, then Assign. Workers assigned here gather passively instead of performing their painted hauling job.

Choose Biome gathering, or choose a resource with the arrows and press Give 1 sample. Sample mode consumes one item when changing to that resource; it does not consume a sample every day. Supported samples: red/yellow/blue mushrooms, raspberries, blueberries, cloudberries, dandelions and thistle.

Biome output:

• Meadows: red mushrooms, raspberries, dandelions.
• Black Forest: red mushrooms, blueberries, thistle.
• Swamp: thistle.
• Plains: cloudberries.
• Mistlands: Jotun puffs and Magecaps.
• Other biomes: no configured mix; use a supported sample.

Items are distributed through the chosen pool; the daily number is total items, not that many of every resource.

With two eligible haulers, morning yield is 6 / 8 / 10 / 12 for tribes of 1 / 2 / 3 / 4+ members. One hauler gives 3 / 4 / 5 / 6; zero gives zero. Member scaling uses total tribe membership, not the number currently online. Storage caps are 18 / 24 / 30 / 36 items respectively, including items already stored there.

Production pays on the observed night-to-morning transition. Sleep preserves yield. Keep the hut loaded across that transition; loading it after dawn does not pay missed mornings. Missing/destroyed anchors or reassigned/dead workers affect eligibility. Each morning can pay only once; full storage does not create a later backlog. Use Open output in the hut menu to collect.

Night routines and anchor rebuilding

Claimed non-defenders pause their jobs at night, gather around their settlement's anchor, sleep and resume after dawn. Miners emerge while retaining their assignments. Defenders stay active. This routine is based on the game's night state, not your computer clock.

If the anchor is destroyed, workers suspend their normal jobs and try to rebuild it at its old site. They pool real supplies and search nearby drops/wild branches and stones within 40 metres. Rebuilding costs 5 wood + 2 stone. They do not create free materials or raid arbitrary storage chests for this routine.

Keep the old site accessible and supply nearby wood/stone. Rebuilding occurs during daytime. Workers may wait if materials, paths, inventory room or ward access prevent repair. You can also rebuild an anchor near the original site yourself.

Tribes and saving

Open . → Tribe to create a tribe, invite online players and accept invitations. Names use 2–32 characters: letters, numbers, spaces, hyphens or underscores. Tribe members share access to claimed villagers. Ownership is still associated with the claiming character; changing membership changes who has shared access.

Villager gear, claims, classes, job areas and orders are persisted. Claimed villagers are not removed merely because you move far away. Persistence does not mean distant NPCs keep simulating: jobs depend on loaded objects and network ownership.

Villager/building state lives in the world save. Tribe membership is stored separately under the host/server profile's BepInEx/config/VillageCompanionTribes folder. Back up that folder along with worlds and characters, especially when moving profiles or hosts.

Knockout taming

Craft 20 Knockout Arrows for 8 wood + 2 resin + 1 red mushroom. One hit puts a wild creature with supported tameable behavior to sleep without damage; other creatures are not valid knockout targets.

Default sleep lasts 600 world seconds. Aim at the sleeping animal:

• E: attach/release the drag rope. Dragging supports obstacles and stairs.
• Shift+E: feed one suitable item from your inventory, with a default 10-second cooldown.
• Alt+E: cancel taming protection and wake it.

Feed its normal diet. Current feed counts: 3 for boars/other supported animals, 5 for wolves, 8 for lox; the hover text shows progress. Feeding requires it to be asleep. The final feed tames and wakes it. Protected animals are spared by villagers. Giving knockout arrows to an archer makes it useful for capture rather than lethal defense against tameable wildlife.

Console and developer tools

For console tests, add -console to the launch arguments used for the modded launch and open F5. devcommands and vanilla spawn commands are for a local test world; permissions and multiplayer availability differ. Custom villager commands target the nearest villager within 30 metres, not the one under your crosshair, and require a controllable locally owned NPC.

• villager help: list commands.
• villager spawn Ulf: create a villager in front of you; optional name. Build an anchor before claiming/ordering them.
• villager follow: follow you.
• villager guard: switch to guard mode.
• villager carry / villager place: carry/place the nearest villager.
• villager collect on / villager collect off: legacy simple collection toggle; use Hauler Class orders for filtered area delivery.
• villager give PickaxeAntler: spawn one item into their inventory. This is a test shortcut; use inventory right click to verify equipped gear.
• villager unload: drop removable contents near you.
• villager status: print state, health, ownership, job and cargo information.
• villager remove: permanently remove the nearest villager; unload cargo first.

Useful local vanilla test commands after devcommands: spawn Hammer 1, spawn Cultivator 1, tod 0.5 for daylight and tod -1 to restore the normal clock. Frozen time can prevent night/morning transitions, so restore it for routine and hut tests.

spawn VC_DevBuilder 1 gives the Developer Builder. It has no crafting recipe, infinite durability and free building. Its catalog includes normal building/cultivator pieces, plants and decorative world structures; F8 while holding it opens its catalog. Decorative dungeon pieces do not generate functional dungeon interiors. Use ordinary equipment and survival materials when testing progression gates.

Developer integration commands/configuration are not a general player test suite: some create or destroy objects and are restricted to specifically named test worlds. Leave them off in normal play.

Suggested test session

Start with one worker per job and a small, flat area. Check the inventory status/console log at each step.

1. Recruitment: build an anchor, summon, claim and open inventory. Equip a replacement club/weapon and confirm the starter weapon becomes removable only after replacement is equipped.
2. Controls: order Follow, then Class orders. Select two same-class villagers and confirm their highlights; try mixed classes and verify the reselect message.
3. Storage/hauling: set a wood filter on a chest, drop wood inside the painted area and stone outside it. Confirm only eligible items are collected, the filter sample is retained and wood arrives in the chest. Test a full chest and an empty matching chest.
4. Farming: plant a few carrots, mark seed/output chests and assign a cultivator-carrying harvester. Wait for mature crops. Verify harvest arrives and replanting uses real seeds; remove seeds to check the waiting state. Check that a hauler leaves planted crops alone.
5. Mining: obtain copper, assign a pickaxe-carrying miner and set copper output. Wait through work/rest cycles. Add a separate hauler covering the entrance. Verify ore moves to its filtered chest. In the disposable test, demolish the mine with an occupant inside and check their release.
6. Hut/routines: assign one hauler across a natural night-to-morning transition and check solo yield of 3. Repeat with two for 6. Check sleep/resume and a full output inventory. Test anchor destruction with real wood/stone nearby.
7. Animals/combat: set up a tame pair, suitable food and marked drop chests; choose retention and wait for breeding/growth. Test an archer with clear sight and behind a solid wall, using small enemies before trolls. Check armor is equipped rather than merely present.
8. Persistence: save, quit and reload. Verify name, claim, class, inventory, painted area and building assignments; walk away and return. Separately test tribe invitations/access with a second player before trusting a shared long-term world.

A failed step is useful evidence. Record its setup and expected result before changing several settings at once. Do not use time skips as proof of normal production rates or offline catch-up.

Troubleshooting and reporting bugs

• Mod/menu missing: check Modded launch, enabled package/dependency, one plugin DLL and startup log. Close other UI before pressing Period.
• Claim denied: build an accessible anchor; check character ownership and tribe membership. Network ownership may be pending; retry after it settles.
• Worker idle: check class, actual order, night state, missing anchor, supplies/tool, inventory room and matching chest access/space. A class alone is not a job assignment.
• Items ignored: ensure they are in painted cells and eligible for that class; wild collection excludes planted resources. Drops/pickables and chests must be loaded. Newly spawned resources can take up to half a second to enter the shared discovery scan, plus the worker's normal planning interval.
• Cannot use a chest: check ward permissions, ownership and whether another player has it open. A filter icon alone is not a seed/food supply.
• Path problems: test flat ground first, then doors, stairs and raised platforms. Keep routes wide and entrances clear; inspect the worker's status. Work areas do not automatically build routes or open blocked passages.
• No mine/hut output: check discovered ore/pickaxe or eligible assigned haulers, anchor, room in output and loaded area. Mines measure active work time; huts need an observed dawn. Neither provides offline catch-up.
• Keeper will not slaughter: check grown offspring eligibility, adult target, pregnancy, matching output storage and native breeding conditions.

For a bug report, include:

• Mod version, Valheim version, manager/profile and full installed mod list.
• Solo, player-hosted multiplayer or dedicated server; which player hosts/owns the affected NPC.
• Exact steps, expected result, actual result and whether it repeats after reload.
• Class/order, tool/equipped weapon/armor, work area, supply/output filters and whether it was night.
• Screenshot of status/area or a short clip, plus relevant log lines around the failure.

The log is BepInEx/LogOutput.log inside the active manager profile. Locate the profile folder from manager Settings. Copy the log before another launch replaces/rotates it; redact private information before sharing publicly. Console villager status and menu Inspect provide additional state. A disposable world that reproduces the issue is especially useful.

Configuration and release status

Configuration is generated after launch at BepInEx/config/local.valheim.villagecompanion.cfg in the active profile. Close Valheim before editing. Relevant defaults:

• [Villager]: Health 200; GuardRadius 5 metres for idle wandering; BowDefenseRange 30 metres. GuardRadius is not the melee detection/chase range.
• [NaturalSpawning]: Enabled true; Interval 120 seconds; Chance 30%; NearbyLimit 2.
• [SummonAnchor]: CooldownSeconds 60.
• [Hauling]: DeliveryRange 60 metres. BrushRadius is retained for legacy area compatibility; current selection uses 2-metre cells.
• [Mining]: CopperOreSeconds 600; WorkSeconds 240; RestSeconds 60.
• [Taming]: SleepSeconds 600; FeedCooldownSeconds 10.
• [Diagnostics]: state logging Interval 10 seconds; automated test switches remain false and test phases 0 for normal play. Do not enable capture/export/destructive checks on a valued world.

Damage multipliers, melee ranges, hut yields/caps and adult-count limits are currently code defaults, not configuration sliders. No claim is made that differing client configs are automatically synchronized.

0.18.2 changes: shared half-second resource discovery scans replace separate full-scene drop/plant searches per worker, including anchor repair. Eligibility/access checks still occur on live objects. The diagnostic icon setting is bound once at startup instead of every frame. Save format and production balance are unchanged.

Compilation and automated scan-lifecycle, farming rules and work-area/storage checks passed for 0.18.2. Live solo checks also passed for native shared-scan reuse, discovery of newly spawned mushrooms, wild gathering and filtered delivery, planted-resource protection, carrot harvest/delivery/replanting, exact seed consumption and updated anchor/mine descriptions. FPS improvement has not been measured. Earlier solo integration checks covered major jobs, combat, armor, routines and dawn output. Multiplayer ownership handoffs, live tribe transport, dedicated servers and compatibility with other mods remain test targets. This release does not promise bug-free saves or a measured FPS gain.