Guide

Install guide

About five minutes. You need Timberborn 1.1 and nothing else: no other mods are required.

Back up first. As with any mod, keep a copy of your save so you can undo the moves the mod makes.

Requirements

Timberborn 1.1. The mod is built against 1.1.2.4 and asks for 1.1.0.0 or newer. A future game update could break it.
Windows. That is the only system it has been checked on. It is an ordinary game mod, so other systems may work, but the Mods folder is in a different place there.
No other mods. No Harmony, no Mod Settings.
Do not run it alongside Incremental Housing, Bobingabout's Housing Optimize or Commute Balancer. It disables itself if it sees one of them enabled. See the FAQ.

Step by step

Back up your save
Copy the save you want to use from Documents\Timberborn\Saves so you can go back if you don't like the result.
Download the mod
Get OptimizedLocalHousing-v1.0.0.zip from the release page. It is distributed from GitHub, not the Steam Workshop.
Close Timberborn
Make sure the game is fully closed before you copy files into its Mods folder.
Extract into your Mods folder
Extract the ZIP into Documents\Timberborn\Mods. It contains one folder, OptimizedLocalHousing, and you should end up with the layout shown below. If you extracted into a new folder, you may have a doubled OptimizedLocalHousing\OptimizedLocalHousing. Move the inner one up.
Enable it and restart
Start Timberborn, open Mods from the main menu, tick Optimized Local Housing, and restart the game when it asks. Menu wording can differ a little between game versions.
Load your save and let the game run
On a save the mod hasn't seen before, the first pass starts as soon as the game is ticking (not while paused). After that it runs at the start of every in-game day. Check that it ran.

Folder layout

This is what a correct install looks like. The game reads the manifest and the DLL from the version-1.1 folder.

Documents\Timberborn\Mods\
└── OptimizedLocalHousing\
    ├── LICENSE
    ├── README.md
    └── version-1.1\
        ├── manifest.json
        └── Scripts\
            └── OptimizedLocalHousing.dll

Check that it works

The mod has no menu and no settings. It writes one line to the game log at startup and one line after every pass.

Quit the game, then open %USERPROFILE%\AppData\LocalLow\Mechanistry\Timberborn\Player.log. If you have already restarted, the previous session is in Player-prev.log.
Search for [OptimizedLocalHousing]. You should see this at startup:
```
[OptimizedLocalHousing] 1.0.0 loaded.
```
After a pass finishes you should see a summary line (roughly 90 seconds to two minutes at normal game speed on a colony of a few hundred beavers, faster at higher speeds). This is a real line from a live game, and your numbers will differ:
```
[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.
```

No line, or an error line? Head to Troubleshooting.

Multiplayer

Every player must have the exact same version installed, because the mod changes which beaver lives where and all players' games have to agree. The pass is designed to give the same result on every machine and to resume correctly after a save, a reload or a join. It has been used in a live hosted co-op session (about 11,000 ticks and 15 passes) with no desync reported by the host. That is one session, so if you try it please tell us how it went.

Updating

Close the game and delete the old Mods\OptimizedLocalHousing folder.
Extract the new ZIP into Mods as above.
Start the game. Your saves keep working, including saves from v0.1.0: the mod's saved data is compatible, and it ignores saved state it doesn't understand and starts fresh.
In multiplayer, every player must update to the same version together.

Uninstalling

Untick it in the Mods menu and restart, or delete the OptimizedLocalHousing folder. Nothing else is needed. Beavers keep the homes they have, and any leftover mod data in your save is ignored. To undo the moves already made, go back to a save from before you installed it.

Verify the download (optional)

In PowerShell, from the folder you downloaded to:

Get-FileHash .\OptimizedLocalHousing-v1.0.0.zip -Algorithm SHA256

The hash should be:

f4de3a7eac21365bf692364e7d9cc9d6a41a81823bba23d916b15c8b07e9967d

The same hash is in the SHA256SUMS file attached to the release.