Optimized Local HousingOptimal, not first-come-first-served
The whole colony is solved at once with the Hungarian algorithm, so the total commute is the smallest the rules allow. It isn't whatever a greedy pass happens to leave over.
Timberborn 1.1 mod · Version 1.0.0 · Stable
Every beaver, as close to work as the beds allow.
Optimized Local Housing re-houses your adult beavers once a day so the whole colony's walk between home and workplace is as short as it can possibly be, without touching your breeding.
- Free & open source (MIT)
- No other mods required
- Built against Timberborn 1.1.2.4
Stable release. It has run 16 passes in a row in a live game, including a hosted co-op session, with no errors. See exactly what is and isn't tested.
Homes shouldn't be a lottery.
By the look of the game's code, the built-in home assigner hands out beds in rotation and never asks where a beaver works. Over time a colony ends up with beavers walking across the whole map every day, past homes that are empty-handed and right beside their job.
Not everyone can live next door to work, because beds are limited. So the real question is which arrangement of beavers into beds makes the total walking smallest. That is a classic assignment problem, and this mod solves it exactly, once a day, instead of nudging beavers around a swap at a time.
Features
What it does for your colony
Real routes, not straight lines
Homes are priced with the game's own route cost, so stairs, platforms and ziplines count. The 32 closest homes to each workplace get a real route query.
Families and breeding stay safe
Every home keeps exactly the same number of adults, and children never move. Beds set aside for babies stay exactly where they are.
No pointless shuffling
A beaver only moves if it saves at least one route-cost unit. Once a colony is optimized, another pass changes nothing.
Smooth by design
The work is spread across ticks with fixed budgets: at most 32 route queries per tick. A pass on a 266-beaver colony takes about 147 ticks.
Built with co-op in mind
Whole-number maths, sorted IDs and a fully saved pass state are meant to give every player the same result, even across a save, a reload or a mid-pass join. It has run through a live co-op session without a desync. Details
How it works
One pass, five steps
A pass runs as soon as the game is ticking the first time the mod sees a save, then at the start of every day. The steps are spread over many ticks, so there is no long freeze.
- Capture
Every housed adult beaver, its home and its assigned workplace, in one quick snapshot.
- Price
Real route costs from each workplace's 32 nearest homes. Anything farther is only estimated, and is re-checked before it is ever used.
- Solve
The best possible way to reassign the adults to the beds that adults occupy today.
- Verify
Every proposed move is priced again with fresh routes. Moves that would strand a beaver, or that don't save enough, are thrown away.
- Apply
Whole cycles of moves are applied in a single tick, and rolled back if the game refuses any of them.
Safe by construction
What it always does
- Keeps every home's number of adults exactly the same.
- Leaves unemployed adults free to give up good beds to beavers who commute.
- Repairs a broken commute by moving a beaver to a home that can reach its workplace.
- Skips a move if the beaver, its job or its home changed while the pass was running, and retries next day.
- Disables itself if another housing-assignment mod is enabled.
Hard limits
What it never does
- Move children.
- Move anyone into a paused, blocked or automation-off home, or out of one.
- Move a beaver to a home it can't reach from work.
- Move a beaver into another district.
- Leave a beaver homeless.
Results
What one pass does to a real colony
We replayed a real 266-beaver save (222 employed adults, 89 homes) through the actual pass engine.
Average commute
Route-cost units per employed adult, lower is better
Before
53.1
After one pass
24.1
True optimum
24.0
View chart data as a table
| Case | Average commute |
|---|---|
| Before | 53.1 |
| After one pass | 24.1 |
| True optimum | 24.0 |
55%
shorter average commute after one pass
147 ticks
for the whole pass
roughly a fifth of a game day
≤ 32
route queries in any one tick
182 beavers
rehomed, in 20 move cycles
a second pass changed nothing
Distance in this replay is a straight-line stand-in for route cost, so real numbers in your game will differ, and real path queries cost more than the stand-in. The first pass on a badly housed colony moves most adults at once; later passes move only a few.
In the live game: the game logs of a real colony (about 350 adults, 104 homes, 167 workplaces) show 16 consecutive passes, each taking about 183 ticks and about 5,350 route queries, and applying between 0 and 4 move cycles. No errors, warnings or rollbacks were logged.
Status
What is tested, and what isn't
Stable means the evidence below, not that every situation has been tried. Here is the honest picture.
Verified
- 16 passes in a row in a live game (about 350 adults, 104 homes, 167 workplaces) with no errors, warnings or rollbacks.
- A hosted co-op session with a second player on the same version: about 11,000 ticks, 15 passes, and no desync reported by the host.
- 25 automated checks pass, including a comparison of the solver against brute force.
- Two simulated peers stay identical at every tick of a pass.
- Saving and reloading at any tick of a pass gives exactly the uninterrupted result.
- Route queries stay within their per-tick budget.
- The compiled mod passes a check against the game's own component rules.
- The replay on a real colony described above.
Not yet verified
- Frame-time impact: the per-tick work is bounded, but the cost of a real path query hasn't been timed.
- Multiplayer beyond that one hosted session: joining, rehosting, and the client's side.
- The Iron Teeth faction (developed and replayed on a Folktails colony).
- Operating systems other than Windows.