Troubleshooting

• Wrong folder depth. The game needs Mods\OptimizedLocalHousing\version-1.1\manifest.json. A doubled OptimizedLocalHousing\OptimizedLocalHousing folder is the usual mistake. See the folder layout.
• Wrong Mods folder. It must be the folder your other mods are in, normally Documents\Timberborn\Mods.
• Old game. The mod needs Timberborn 1.1 or newer. Older versions won't load it.
• Fully quit and restart the game after copying files.

• Make sure you're reading the right session. The log is overwritten each launch, and the previous one is Player-prev.log.
• Check the mod list near the top of the log. Optimized Local Housing (v1.0.0) should be listed. If it isn't, it wasn't enabled, or you didn't restart after enabling it.
• If it's listed but the loaded. line is missing, check the game didn't fail to load the mod's DLL further down the log, and report it with that log.

• The game has to run. Passes only progress while the game is ticking. Paused time doesn't count. A pass takes roughly 150 to 200 ticks on a colony of a few hundred beavers, about 90 seconds to two minutes at normal speed.
• Saves the mod has already seen start their next pass at the beginning of the next in-game day, not straight away. Only a save the mod hasn't seen before starts a pass immediately.
• You quit the game before the pass finished. Let it run a little longer, and note the line is written when the pass ends.
• Look for "Disabled because…" or "Pass abandoned…" in the log.

Optimized Local Housing turns itself off when it sees another mod that reassigns beavers' homes, because two of them would keep undoing each other. The message ends with the ID it found. It checks for these:

• Kyler.IncrementalHousing (Incremental Housing)
• BobHousingOptimize (Bobingabout's Housing Optimize)
• BobCommuteBalancer (Bobingabout's Commute Balancer)
• housingoptimize (a mod.io listing of Housing Optimize)

Disable the other mod in the Mods menu and restart. Only one housing mod should be on.

Reading the line: Pass 34: 345 adults, 104 homes, 167 workplaces; 5394 route queries over 183 ticks; 4 move cycles applied (1 rejected, 2 stale), 0 disconnected commutes repaired, route cost saved 717.

• adults / homes / workplaces: how many the pass considered.
• move cycles applied: groups of beavers that swapped beds around. Zero is the correct answer when the colony is already as good as it can be. A second pass on an optimized colony changes nothing.
• rejected: the fresh route check threw a proposed cycle away, because a beaver would end up unable to reach work, or the cycle didn't save at least half a route-cost unit.
• stale: someone in the cycle changed home or job, died, or a home couldn't take them, between the snapshot and the moment of applying. Small numbers are normal. These beavers are reconsidered in the next pass.
• route cost saved: the total drop in commute across the beavers that moved.

Persistent zeros on a colony that clearly needs help usually mean the beavers aren't eligible: they have no assigned workplace, the workplace is disabled or in another district, or their homes are paused, blocked or switched off by automation. Those beavers are left alone by design.

• Beds are limited. The mod minimizes the total. Someone has to live farther away, and it may be the beaver you're watching.
• Route cost isn't distance. The mod uses the game's route cost, so stairs and ziplines can make a home that looks close actually costly, or a far one cheap.
• Commute means home to assigned workplace. A beaver that wanders off to haul goods or a different job site isn't measured by that.
• Timing. New jobs, new homes and births show up in the next pass.
• Vacant beds aren't used. Every home keeps its number of adults, and empty beds are left for the game and for babies. See the FAQ.
• Candidate homes are limited to the 32 nearest by block distance per workplace, plus a re-check of anything farther. A home far away by straight line but close by zipline could be missed.

Expected on the first pass of a badly housed colony: the best arrangement can differ from the current one for most adults. Children never move, so a child can end up in a home with different adults than before. Every home still has the same number of adults, so babies and breeding capacity are untouched. Later passes move only a few beavers. If you dislike the first result, load a backup save and don't install the mod.

The pass is split into steps with fixed per-tick budgets (at most 32 route queries per tick), but two moments do their work in a single tick: taking the snapshot when a pass starts, and applying the moves when it ends. On a large colony either could cause a brief blip. Frame-time impact hasn't been measured; for scale, a pass on a live colony of about 350 adults, 104 homes and 167 workplaces used about 5,350 route queries over about 183 ticks, with no problems reported.

If you see a real stutter, please report it with your colony size and the pass line from the log. Until it's fixed you can disable the mod.

An unexpected error stopped the pass. It is contained: no beavers are left half-moved, the game keeps running, and the mod tries again the next day. Copy the full message, which includes the error and where it happened, and report it. That is a bug we want to hear about.

The game refused one of the assignments in a cycle. The mod put every beaver in that cycle back in its original home, so nothing is lost. If it happens repeatedly, report it with the message.

The mod couldn't read its own data from the save (for example, data written by a different version). It starts fresh, at no cost to your colony. If you see it after a normal update, you can ignore it.

• Everyone needs the identical version. If only some players have the mod, or the versions differ, the games will disagree about where beavers live.
• Restart the session from the host's save with everyone on the same version.
• It has been used in one live hosted co-op session (about 11,000 ticks and 15 passes) with no desync reported by the host, so a desync would be a new finding. If it happens, please report it: include every player's Player.log from the session and say when it happened relative to a Pass line.

The mod is built against Timberborn 1.1.2.4. A game update can change the parts it relies on. Look in the log for an error mentioning OptimizedLocalHousing, disable the mod until a matching release is available, and check the releases page.

Disabling or deleting the mod stops further changes but doesn't move anyone back. To undo the moves already made, load a save from before you installed it. That is why you should try it on a copy first.