Optimized Local HousingOptimized Local Housing
The shortest total walk the beds allow.
A Timberborn 1.1 mod. Once a day, it moves adult beavers into the homes that make the colony's total walk to work as short as it can be. Beds are limited, so not everyone lives next door to work. Together, they walk the least.
- The whole colony, not each beaver. One beaver may walk a little farther so that everyone together walks less.
- Breeding is protected, and children never move. Adults can move into empty beds near work, but never in a way that leaves fewer homes able to have a kit.
- Once a day, spread over many ticks. Nothing to set, no menu. It needs no other mods.
Stable. It ran 16 passes in a row in a live game, including a hosted co-op session, with no errors. This release's newer changes are covered by automated tests but haven't been played yet. What is tested, and what isn't
Homes shouldn't be a lottery.
By the look of its code, the game hands out beds without asking where a beaver works. Beavers end up walking across the map every day, past homes right beside their job.
The real question is which arrangement of beavers into beds makes the total walk smallest. That is a classic assignment problem. This mod solves it exactly, once a day, instead of nudging beavers one swap at a time. It only rearranges the adults already housed.
How the plan is drawn up
Six rules the mod keeps every time it arranges your colony.
Optimal, not first-come-first-served
Each district is solved exactly with the Hungarian algorithm. The colony's total commute is the smallest the rules allow.
Real routes, not straight lines
Homes are priced with the game's own route cost, so stairs, platforms and ziplines count. Each workplace checks real routes to the 32 nearest homes in its district.
Families and breeding stay safe
Children never move. Adults take only adult beds, and a move is turned down if it would leave fewer homes able to have a kit.
No pointless shuffling
Beavers move only when the rearrangement saves at least one route-cost unit for each beaver moved. Once a colony is arranged, another pass changes nothing.
Smooth by design
The work is spread over many ticks, a little at a time, so there is no long freeze. A large colony does more per tick to finish within the daytime; only the very largest take longer.
Built with co-op in mind
Every player's game should make the same moves, even across a save, a reload or a mid-pass join. What has been played
One pass, five steps
The first pass starts as soon as the game runs on a save the mod hasn't seen. After that, a pass runs at the start of every day.
- Capture
Every housed adult beaver, its home and its assigned workplace, and every empty bed, in one quick snapshot.
- Price
Real route costs from each workplace to its 32 nearest homes in its district. Farther homes are estimated.
- Solve
The best way to reassign the adults to the district's beds, empty ones included, one district at a time.
- Verify
Every proposed move is priced again with fresh routes. Moves are dropped if they would cut a beaver off from work, save too little, or leave fewer homes able to have a kit.
- Apply
Each cycle or chain of moves is applied in a single tick, and rolled back if the game refuses any of them.
What it always does
- 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, when a bed can be arranged.
- Skips a move if the beaver, its job or its home changed while the pass was running, and tries again the next day.
What it never does
- Move anyone into a paused, blocked or automation-off home, or out of one.
- Move a beaver who can reach work into a home that can't.
- Move a beaver into another district.
- Leave a beaver homeless.
Next to Housing Optimize and Commute Balancer
Bobingabout's two mods are the ones most players know. Here is how they differ, going by what their Workshop pages describe.
| Question | Housing Optimize | Commute Balancer | Optimized Local Housing |
|---|---|---|---|
| When | Once at the start of each day, all at once | Gradually, over days | Once a day, spread over ticks |
| How it decides | Unassigns everyone and refills first-come-first-served, nearest first; its author notes the result isn't guaranteed to be the best | Moves a beaver to a closer empty home, or swaps when the benefit outweighs the other beaver's inconvenience | Solves each district exactly for the smallest total commute |
| Adults per home | Refilled | Can change with moves to empty homes | Can change with moves to empty beds, never leaving fewer homes able to breed; children never move |
| Track record | Thousands of subscribers | Thousands of subscribers | Newer, with far less real-world mileage |
In a replay of one real colony, a first-come-first-served model like the one Housing Optimize describes averaged 25.6 (23.5 to 29.0, depending on the order workplaces were handled) against 24.1 for this mod. That was a model with looser bed rules and straight-line distances, not a benchmark of either mod. More in the FAQ
Don't run them together: Optimized Local Housing turns itself off if Housing Optimize or Commute Balancer is enabled.
What one pass does to a real colony
A real 266-beaver save (222 employed adults, 89 homes) replayed through the actual pass engine, with every home keeping its number of adults and straight-line distance standing in for route cost. Then the live game's own log.
Average commute
Route-cost units per employed adult, straight-line stand-in. Lower is better.
View chart data as a table
| Case | Average commute |
|---|---|
| Before | 53.1 |
| After one pass | 24.1 |
| True optimum | 24.0 |
- 55% shorter
- the average commute after one pass
- 147 ticks
- for the whole pass, about a fifth of a game day
- 182 beavers in 20 cycles
- rehomed by that pass
- 0 changes
- from a second pass
Real route costs 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 log of a real colony of about 350 adults, 104 homes and 167 workplaces. 16 passes in a row, each about 183 ticks, applied 0 to 4 move cycles with no errors, warnings or rollbacks.
[OptimizedLocalHousing] Pass 26: 356 adults, 104 homes, 167 workplaces; 5354 route queries over 182 ticks; 2 move cycles applied (0 rejected, 0 stale), 0 disconnected commutes repaired, route cost saved 177.
- 356 adults, 104 homes
- who was in the plan
- 5354 queries, 182 ticks
- the work, spread out
- 2 move cycles applied
- groups of beavers who swapped beds
- 0 rejected, 0 stale
- moves thrown out at the check, or because something changed
- route cost saved 177
- how much shorter the colony's walk got
What is tested, and what isn't
Stable means the evidence below, not that every situation has been tried.
Tested
- 16 passes in a row in a live game (about 350 adults, 104 homes, 167 workplaces) with no errors, warnings or rollbacks, on the code the stable release started from.
- A hosted co-op session with a second player on the same version: about 11,000 ticks, 15 passes, and no desync in the host's log.
- 46 automated checks: 45 run on every change, and one runs against the installed game. They cover the solver against brute force, several districts, large colonies, and two players staying in step through saves and reloads.
- The replay of a real colony above.
Not yet
- This release's newer changes in a live game: moving adults into empty beds, pricing homes by district, remembered route costs, solving each district on its own, and bigger budgets for large colonies. Automated tests cover them.
- Frame-time impact: the per-tick work is bounded, but a real path query hasn't been timed, nor the bigger budgets a very large colony gets.
- Multiplayer beyond that one hosted session: joining, rehosting, the second player's side, and a live two-player session on this release.
- The Iron Teeth faction (developed and replayed on a Folktails colony).
- Operating systems other than Windows.
- Timber Together: its code was read against this mod's, but not played together.
Five minutes to install
- The ZIP under Assets on the release page, not Source code.
- Close the game and extract it into
Documents\Timberborn\Mods: oneOptimizedLocalHousingfolder. - Enable it and restart. Not alongside Housing Optimize or Commute Balancer.