Frequently asked questions

Once a day it works out the arrangement of adult beavers into their existing beds that makes the colony's total home-to-workplace travel as short as possible, and moves the beavers that need moving.

A pass starts the first time the mod sees a save, then at the start of every in-game day. A pass took 147 ticks on a 266-beaver colony in the replay, and about 183 ticks on a live colony of about 350 adults, roughly 90 seconds to two minutes at normal speed. The work is spread across those ticks, with at most 32 route queries per tick.

Moves are applied when a pass finishes, which can be at any time of day. Beavers simply walk to their new home the next time they go home.

No. Version 1.0.0 has no menu and no options. The tuning values (NearHomes, QueriesPerTick, StayBonus) are constants in the source if you're willing to rebuild it. A relaxed "let adult counts change" option was considered and dropped, and the reason is below.

A group of beavers that each take the next beaver's bed, and the last takes the first's, like A→B→C→A. Every home in the cycle ends up with as many adults as it started with. Cycles are applied all at once, or not at all if anything about them has changed. A simple two-beaver swap is the smallest cycle.

It uses the game's own route cost between a home and the beaver's assigned workplace, so stairs, platforms and ziplines count. It isn't straight-line distance. To keep the work small, each workplace prices its 32 nearest homes by block distance; anything farther is only estimated, and every move is re-priced with fresh routes before it happens.

• It is already in the best place the total allows. Someone else needed that bed more.
• Moving would save less than one route-cost unit. A beaver stays put unless the move is worth it, so the colony doesn't churn.
• Its workplace is disabled or in another district, or it has no job, so its commute isn't measured.
• Its home is paused, blocked, or switched off by automation. Those homes are skipped.
• It was skipped this time because something changed mid-pass, and it will be reconsidered tomorrow.

They don't care where they live, so they are treated as free to take whatever bed is left. That means an unemployed beaver may give up a home next to a workplace so a working beaver can have it.

We tested exactly that, and it isn't worth it. On the real 266-beaver colony we replayed, letting the solver change how many adults each home holds shortened the average commute by only about 4% (24.0 to 23.1). But it used up the beds where babies could be born: homes able to have a baby fell from 11 to 1. Keeping those baby beds empty brought the gain back to nothing.

So every home keeps its adult count. This was measured on one colony, with a straight-line stand-in for route cost and child-bed limits inferred from household sizes, so other colonies will differ, but a 4% gain wasn't worth risking population growth.

It's built not to. In the game's code a baby needs a home with a free bed, at least two adults, and fewer children than half its adults. Optimized Local Housing keeps every home's number of adults exactly the same and never moves children, so each home keeps the same free beds and the same number of pairs. The chance of a birth in each home is untouched.

What changes is which adults live in a home. By construction, breeding capacity is identical before and after a pass.

Children never move, but the adults in their home may change, especially on the first pass. We haven't found any game mechanic that ties a child to specific adults, but we can't rule one out. If it matters to you, try it on a copy first.

No, by design. Every move is applied as a whole cycle in one tick and rolled back if the game refuses any part of it. Every destination's route to the beaver's workplace is checked with a fresh query first, and a move that would leave a beaver unable to reach work is thrown away.

The mod stores a small amount of data in your save: a few hundred bytes when idle and a few tens of kilobytes during a pass. If you remove the mod, the data is ignored and beavers keep their current homes. As with any mod, keep a backup of important saves.

No. Two housing mods would keep reassigning each other's work. Optimized Local Housing checks for these mods at startup and turns itself off, with a warning in the log, if one is enabled. Pick one. See Troubleshooting.

As described on their Workshop pages:

• Housing Optimize reassigns beavers once at the start of each day: it unassigns everyone and refills homes first-come-first-served, nearest first, all at once. Its author notes the result isn't guaranteed to be the best.
• Commute Balancer works gradually over days, moving a beaver to a closer empty home or swapping when the benefit outweighs the other beaver's inconvenience.
• Optimized Local Housing solves the whole colony at once for the smallest total commute, keeps every home's number of adults, and spreads the work across ticks with fixed budgets.

In a replay on one real colony, a first-come-first-served strategy like the one Housing Optimize describes averaged 25.6 (between 23.5 and 29.0 depending on the order workplaces were handled), against 24.1 for this mod, even though that model was given looser bed rules. That was a model with a straight-line stand-in, not a benchmark of either mod. Both of those mods have thousands of subscribers and much more real-world mileage. This one is newer.

We don't claim that. Because it solves the assignment exactly, it should reach the shortest total commute among the approaches above, and the tests support that. It has now run in live single-player and co-op play, but with far less mileage than long-established mods, and commute isn't the only thing that matters: stability, disruption and real-world track record count too.

The fair test is to run each mod on a copy of the same save for a few in-game days and compare the average commute afterward. If you do, we'd like to hear the result.

It is designed for it. It uses whole-number maths and sorted IDs, and the entire pass state is saved with the game, so every player should reach the same result even across a reload or a mid-pass join. All players must run the same version. It has been used in a live hosted co-op session (about 11,000 ticks and 15 passes) with a second player on the same version, and the host's log shows no desync. That is one session, so treat it as encouraging rather than conclusive.

It hasn't been tested. It was developed and replayed on a Folktails colony, and it only handles beaver dwellers.

• Timberborn 1.1 (built against 1.1.2.4, minimum 1.1.0.0). A future update could break it.
• Checked on Windows only.
• No other mods are required. It doesn't need Harmony or Mod Settings.

Yes, under the MIT license. The source, the test suite and the build script are on GitHub.

Version 1.0.0 is the first official release. It is the same code as the earlier v0.1.0 preview, promoted after 16 consecutive passes in a live game, including a hosted co-op session, ran with no errors, warnings or rollbacks. “Stable” means that evidence plus the automated tests, not that every situation has been tried. See what is tested and what isn't.

Open an issue on GitHub. The troubleshooting page lists what to include.