Units & Companions

Units are the characters in the world — your colonists, enemies, and neutral NPCs. In Overseer Mode, you select and command units to build, demolish, and explore.

Factions

Each unit has a race and a faction. Race determines base stats (speed, view radius, sprite) via data-driven assets/races.ron. Faction determines behavior class. Any race can belong to any faction.

Races

Race	HP	EP	Notes
Dwarf	120	80	Colony default. Generated dwarven names.
Goblin	60	40	Hostile default. Goblin name culture.
Skeleton	40	0	Hostile default. Uses goblin name culture.
Human	100	60	Neutral default. Human name culture.
Deer	80	50	Wild. No generated names.
Wolf	—	—	Wild. No generated names.

Factions

Faction	Behavior
Colony	Selectable, commandable, possessable by the player
Hostile	Attacks on sight
Neutral	Non-hostile — future trading
Wild	Passive fauna

Unit Stats

Each unit has three core stats displayed in the HUD and unit panels:

Stat	Description
Health (HP)	Hit points. Unit dies at 0. Base value depends on race.
Energy (EP)	Energy pool for actions and sprint. Base value depends on race.
Level	Experience level, shown as a badge in the HUD and unit cards.

Unit Commands

Units execute commands from a queue. Available commands:

Command	Description
MoveTo	Pathfind to a target tile
Build	Place a block at a tile using an item
Demolish	Remove a block at a tile
Pickup	Pick up an entity (dropped item)

Commands are queued sequentially. Hold Shift + right-click in Overseer Mode to append to the queue instead of replacing it.

Pathfinding

Units use A* pathfinding to navigate to their target. The pathfinder respects:

Block movement rules (blocks_movement property)
Surface transitions (step up/down, walk, fall)
Z-level navigation via stairs

Multi-Waypoint Plans

Using kinswardctl, you can assign multi-waypoint routes:

kinswardctl unit-plan <entity_id> 5,0,1 5,5,1 0,5,1

Task System

The global TaskQueue holds pending tasks. When a unit becomes idle, it automatically picks the nearest pending task from the queue and pathfinds to execute it.

Task types: Build, Demolish, Pickup.

Tasks can be created by:

Right-clicking in Overseer Mode
Zone operations (bulk build/demolish)
kinswardctl commands (task-add, zone-build, zone-demolish)

Companions

Companions are Colony units that follow behavioral patterns:

Behavior	Description
Follow	Follow a specific entity (typically the player)
Station	Stay in place

Managing Companions

Use kinswardctl companion commands or the in-game companion system:

# List all companions
kinswardctl companion-list

# Set a companion to follow
kinswardctl companion-behavior <entity_id> follow

# Call all companions to follow
kinswardctl companion-call-all

# Dismiss all (station in place)
kinswardctl companion-dismiss-all

Traits

Units of sentient races (those with name cultures — Dwarf, Goblin, Skeleton, Human) receive 0–3 random traits at spawn. Traits are descriptive for now — stat modifiers will come with the attribute system.

Trait	Category	Rarity	Effect
Hardy	physical	0.15	Tough constitution, resistant to cold and disease
Quick Learner	mental	0.12	Picks up skills faster
Night Owl	lifestyle	0.12	More productive at night
Clumsy	physical	0.10	Prone to accidents, slower at tasks
Strong Back	physical	0.10	Can carry heavier loads
Keen	physical	0.08	Sharp senses, extended field of view
Frail	physical	0.08	Weak constitution, takes more damage
Firstborn	birthright	special	Starting player character only — not randomly assigned

Manage traits via kinswardctl:

kinswardctl traits                          # list all traits
kinswardctl unit-add-trait <ID> hardy       # add trait
kinswardctl unit-remove-trait <ID> clumsy   # remove trait

Names

Sentient units receive generated names from racial syllable tables (defined in assets/names.ron). Dwarves get names like “Thorin Ironforge”, goblins like “Snagnak Rotfang”. Animals get descriptive names (“Deer #1”).

The world itself also receives a generated name (e.g. “Stormreach”) from the World culture table, visible via kinswardctl game-info.

Spawning Units

In debug mode, new units can be spawned via kinswardctl:

# Spawn a dwarf colony unit at (10, 5, 1) — name auto-generated
kinswardctl spawn dwarf 10 5 1

# Spawn with explicit name and faction
kinswardctl spawn goblin 5 5 1 --faction hostile --name "Grikash"

# Spawn and possess (take direct control)
kinswardctl spawn dwarf 0 0 1 --controlled

Races: dwarf, goblin, skeleton, human, deer, wolf. Factions: colony (default), hostile, neutral, wild.

Possession

You can possess a Colony unit to take direct control in Adventure Mode. While possessing a unit, WASD moves that unit instead of the default player character.

kinswardctl possess <entity_id>   # take control
kinswardctl possess               # release