diff --git a/CLAUDE.md b/CLAUDE.md index d9f07e5..c1d259e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -116,7 +116,7 @@ text and the player docs follows these rules. in the README changelog and the GitHub release notes. Upgrade steps players need are the only exception. - The played and not-played status matches the README exactly: the 1.0 code (released as 1.0.0) ran 16 passes in a live game, including one hosted co-op session; 1.1.0's changes and anything since are covered by automated tests but - not played; no live two-player session on 1.1.x; frame time, Iron Teeth, non-Windows and Timber Together live play untested. + not played; no live two-player session on 1.1.x or 1.2.x; frame time, Iron Teeth, non-Windows and Timber Together live play untested. Replay numbers always say "straight-line stand-in". Never invent numbers, reviews or screenshots. - Keep the credits: MIT, maintained by Timbermods; Housing Optimize and Commute Balancer are Bobingabout's. Keep the "unofficial, not affiliated with or endorsed by Mechanistry" line in every footer. @@ -139,7 +139,7 @@ When asked to "update the website for the latest release, consistent with the de `"sha256"` (install `#checksum`; take the hash from the release's SHA256SUMS asset). - `data-release-pinned`: index `.status-note` and `#status` head, FAQ `#does-it-have-settings` and `#is-it-stable`; bump after re-checking the text. - - Status: index `.status-note`, `#status` Tested / Not yet lists (incl. "41 automated checks: 40 run on every + - Status: index `.status-note`, `#status` Tested / Not yet lists (incl. "46 automated checks: 45 run on every change": match the test output), install `#multiplayer`, FAQ `#does-it-work-in-multiplayer` and `#is-it-stable`, troubleshooting `#multiplayer`. - Requirements and game version (built against 1.1.2.4, minimum 1.1.0.0): install `#requirements`, FAQ diff --git a/PRODUCT.md b/PRODUCT.md index 875e2c0..8704cab 100644 --- a/PRODUCT.md +++ b/PRODUCT.md @@ -22,10 +22,11 @@ The website for **Optimized Local Housing** (https://github.com/timbermods/Optim that, once a day, moves adult beavers into the homes that give the colony the **shortest total commute** between home and assigned workplace. Beds are limited, so not everyone can live next to work; the mod solves that exactly (an optimal assignment, the Hungarian algorithm, one district at a time) instead of nudging beavers one swap at a time. -Every home keeps the same number of adults and children never move, so breeding is untouched. +Adults can move into empty beds, but only adult beds, and never in a way that leaves fewer homes able to have a kit. +Children never move. Success, in order: -1. **Understand it:** the visitor grasps that it rearranges the adults already housed (it doesn't fill empty beds or +1. **Understand it:** the visitor grasps that it rearranges the adults already housed, into empty beds too (it doesn't build anything), that it minimizes the colony's total, not each beaver's walk, and that breeding and children are safe. They download the right file. 2. **Install it right:** the `OptimizedLocalHousing-vX.Y.Z.zip` under Assets (not "Source code"), game closed, @@ -40,11 +41,12 @@ Success, in order: - **Versus the base game:** by the look of the game's code, the built-in assigner hands out beds without asking where a beaver works. This mod rearranges the adults already housed so the colony's total home-to-work route cost is as - small as the rules allow. It works alongside the game's assigner, which still fills vacant beds. + small as the rules allow, moving adults into empty adult beds too. It works alongside the game's assigner, which + still houses newcomers and kits. - **Versus Bobingabout's Housing Optimize and Commute Balancer** (as their Workshop pages describe them): Housing Optimize unassigns everyone once a day and refills first-come-first-served, nearest first; Commute Balancer works - gradually over days. This mod solves each district exactly, once a day, keeps every home's adult count, and spreads - the work over ticks. Say it truthfully: in one replay a first-come-first-served model averaged 25.6 against 24.1 for + gradually over days. This mod solves each district exactly, once a day, never leaves fewer homes able to breed, and + spreads the work over ticks. Say it truthfully: in one replay a first-come-first-served model averaged 25.6 against 24.1 for this mod, but that was a model with a straight-line stand-in, not a benchmark of either mod. Those mods have thousands of subscribers and far more real-world mileage; this one is newer. Never claim "the best housing mod". They must not run together: this mod turns itself off if either is enabled. @@ -52,11 +54,11 @@ Success, in order: ## Operating Context -- **Current release: v1.1.1** (published 2026-09-22), a **stable** release marked Latest on GitHub. A maintenance - release: the conflict check covers only Housing Optimize and Commute Balancer; passes and saved data are unchanged - from 1.1.0. Release assets: `OptimizedLocalHousing-v1.1.1.zip` and `OptimizedLocalHousing-v1.1.1-SHA256SUMS.txt` - (ZIP SHA-256 `cc6b905d0021c3119f15a85186d6a7197e7955bed890d0134d0c6a2f2f654059`). Earlier: v1.1.0, v1.0.1, v1.0.0, - and the v0.1.0 preview (pre-release). +- **Current release: v1.2.0** (published 2026-09-27), marked Latest on GitHub. Adults can move into empty adult beds; + a move that would leave fewer homes able to breed is turned down; children never move. Release assets: + `OptimizedLocalHousing-v1.2.0.zip` and `OptimizedLocalHousing-v1.2.0-SHA256SUMS.txt` (ZIP SHA-256 + `1bae3d47dad8801712d4b73656e312036ec84f5527f72203a5907b8b33a21a3b`). Earlier: v1.1.1, v1.1.0, v1.0.1, v1.0.0, and + the v0.1.0 preview (pre-release). - **Game:** Timberborn 1.1, built against **1.1.2.4**, manifest minimum **1.1.0.0**. A future game update could break it. Checked on Windows only. - **Requirements:** none. Mod name in the Mods menu: **Optimized Local Housing**; mod ID `Kyler.OptimizedLocalHousing`. @@ -69,7 +71,7 @@ Success, in order: BeaverBuddies warns at join time when mod versions differ. - **In-game settings players meet:** none. No menu, no UI, no options. The tuning constants (`NearHomes`, `QueriesPerTick` in `PassEngine.cs`; `StayBonus` in `Assignment.cs`) are in the source for people who rebuild. -- **What players see:** beavers change homes; one log line at startup (`[OptimizedLocalHousing] 1.1.1 loaded.`) and +- **What players see:** beavers change homes; one log line at startup (`[OptimizedLocalHousing] 1.2.0 loaded.`) and one per pass. A pass starts as soon as the game ticks on a save the mod hasn't seen, then at the start of every in-game day; it takes roughly 150 to 200 ticks on a colony of a few hundred beavers (about 90 seconds to two minutes at normal speed). Other log messages: `Disabled because another housing assignment mod is enabled`, `Saved state @@ -101,10 +103,10 @@ Success, in order: and `data-asset="^OptimizedLocalHousing-v[\d.]+\.zip$"`. - Hand-written fallbacks must stay working: the download links (`data-release-href="download"`) point at `/releases/latest`, the footer's Latest release link carries `data-release-href="notes"`, and every - `data-release` span (`version`, `tag`, `asset-name`, `sha256`) holds the current value written by hand (1.1.1, the + `data-release` span (`version`, `tag`, `asset-name`, `sha256`) holds the current value written by hand (1.2.0, the ZIP name, the hash above). Update them at each release, since `release.js` only replaces them when the lookup works. - - `data-release-pinned="1.1.1"` marks text written for one version (the home status notice and section, FAQ + - `data-release-pinned="1.2.0"` marks text written for one version (the home status notice and section, FAQ settings and stability answers); bump it when the text is re-checked for a new release, or `release.js` appends a "written for" note. - `404.html` loads its stylesheet, favicon and links by absolute `/OptimizedLocalHousing/` paths. @@ -122,8 +124,9 @@ Success, in order: maintainer's colony (about 350 adults, 104 homes, 167 workplaces) with no errors, warnings or rollbacks, including one hosted co-op session with a second player (about 11,000 ticks, 15 passes, no desync in the host's log). - **Not played in game:** 1.1.0's changes (same-district pricing, remembered route costs, per-district solve, - larger budgets for large colonies) and 1.1.1. They are covered by automated tests only. No live two-player session - has been played on 1.1.0 or 1.1.1; the client's side, joining and rehosting are untested. + larger budgets for large colonies), 1.1.1, and 1.2.0's moves into empty beds. They are covered by automated tests + only. No live two-player session has been played on 1.1.x or 1.2.0; the client's side, joining and rehosting are + untested. - Never measured: frame-time impact (the per-tick work is bounded, but a real path query hasn't been timed, nor the larger budgets of very large colonies). Iron Teeth untested (developed on Folktails). Only Windows. BeaverBuddies Timber Together was audited against the mod's code, not played with it. @@ -133,8 +136,10 @@ Success, in order: - Present it as "stable means this evidence plus the automated tests, not that every situation has been tried", without scaring people off. - **How the shipped site states these facts (keep it this way):** - - The home page's Tested list says "41 automated checks: 40 run on every change, and one runs against the installed - game" (CI runs 40; the compiled-adapter check runs only locally with the game). + - The home page's Tested list says "46 automated checks: 45 run on every change, and one runs against the installed + game" (CI runs 45; the compiled-adapter check runs only locally with the game). + - The replay results were made with every home keeping its number of adults (before moves into empty beds), and + the site says so. - The home status, `install.html` (Multiplayer), the FAQ multiplayer and "Is it stable?" answers and the troubleshooting multiplayer entry say the live session ran the code the stable release started from, and that this release hasn't been played live by two players. None of them walks through version history. @@ -165,23 +170,24 @@ Success, in order: screenshots. - **Real data:** the replay results above (the bar chart and its table); the live log figures (16 passes, about 183 ticks and 5,350 route queries each, 0 to 4 cycles); two real `Pass` lines from the maintainer's log (Pass 26 and - Pass 34; Pass 26 is quoted on the home and install pages, Pass 34 on the troubleshooting page); the FAQ's measured "let adult counts change" experiment - (average 24.0 to 23.1, about 4%, while homes able to have a baby fell from 11 to 1; one colony, straight-line - stand-in); the tick and memory figures in the README (47 vs 157 solve ticks; 480 vs 1,118 ticks for 1,600 adults). + Pass 34; Pass 26 is quoted on the home and install pages, Pass 34 on the troubleshooting page); a measured "let adult counts change" experiment with no + breeding rule (average 24.0 to 23.1, about 4%, while homes able to have a baby fell from 11 to 1; one colony, + straight-line stand-in; no longer quoted on the site); the tick and memory figures in the README (47 vs 157 solve ticks; 480 vs 1,118 ticks for 1,600 adults). - **Does not exist, and must not be faked:** in-game screenshots or clips of the mod at work (there is no UI to capture; a before/after of a real colony would need the maintainer's own shots, so leave a marked slot), download counts, player numbers, testimonials, reviews, press, benchmarks against the other housing mods, frame-time numbers, - Iron Teeth or non-Windows results, and any 1.1.x live-play results. + Iron Teeth or non-Windows results, and any 1.1.x or 1.2.x live-play results. ## Product Principles 1. **Show the mechanism, then the proof.** One total, limited beds, an exact solve: the diagrams explain it, the replay numbers back it, and every number carries its caveat. -2. **Breeding and families first.** Adult counts per home never change and children never move; say it early, because +2. **Breeding and families first.** No move leaves fewer homes able to have a kit, adults never take a kit's bed, and + children never move; say it early, because it's the first worry of anyone who has used a housing mod. 3. **Nothing to set, so the log is the interface.** Install right, let the game run, read the `Pass` line; the troubleshooting page is built around those messages. 4. **Fair to the neighbours.** Compare with Housing Optimize and Commute Balancer by what they say they do, admit their mileage, never claim to be the best. -5. **Honest about what's been played.** The 1.0 code ran live, 1.1.x is tested but not played, and frame time is +5. **Honest about what's been played.** The 1.0 code ran live, 1.1.x and 1.2.x are tested but not played, and frame time is unmeasured; said plainly, as the mod is now, with the version history left to the changelog. diff --git a/README.md b/README.md index 10af335..b9ac774 100644 --- a/README.md +++ b/README.md @@ -34,8 +34,8 @@ Search for `[OptimizedLocalHousing]`: there is one line at startup and one after - **The whole colony, not each beaver.** One beaver may walk a little farther so everyone together walks less. Each district is solved exactly, with the game's own route costs, so stairs, platforms and ziplines count. -- **Every home keeps the same number of adults.** Homes never overfill and breeding is untouched. Empty beds are - left for the game to fill. +- **Breeding is protected.** Adults can move into empty beds near work, but they take only adult beds, and never + in a way that leaves fewer homes able to have a kit. Homes never overfill. - **Children never move.** Neither do beavers in paused, blocked or automation-off homes, and nobody moves into one. - **Nobody crosses districts, and nobody is made homeless.** - **Commutes stay possible.** A beaver who can reach work is never moved to a home that can't. One who can't is @@ -49,8 +49,8 @@ Search for `[OptimizedLocalHousing]`: there is one line at startup and one after ## Results -A real 266-beaver colony (222 employed adults, 89 homes), replayed through the pass engine with straight-line -distance standing in for route cost: +A real 266-beaver colony (222 employed adults, 89 homes), replayed through the pass engine with every home +keeping its number of adults and straight-line distance standing in for route cost: | | Average commute | |---|---| @@ -67,8 +67,8 @@ That pass took 147 ticks and rehomed 182 beavers in 20 cycles. A second pass cha - **Played:** the 1.0 code ran 16 passes in a row on the maintainer's colony (about 350 adults, 104 homes, 167 workplaces), with no errors, warnings or rollbacks. That included one hosted co-op session with a second player: about 11,000 ticks, 15 passes and no desync in the host's log. -- **Tested, not played:** the 1.1 code. 41 automated checks cover it; 40 run on every change. -- **Not tried yet:** a live two-player session on 1.1, the second player's side of a co-op session, frame-time +- **Tested, not played:** the 1.1 and 1.2 code. 46 automated checks cover it; 45 run on every change. +- **Not tried yet:** a live two-player session on 1.1 or 1.2, the second player's side of a co-op session, frame-time impact, the Iron Teeth faction, systems other than Windows, and Timber Together in a live session (its code was checked against this mod's, not played with it). diff --git a/docs/faq.html b/docs/faq.html index 3c6d01f..50b6ff0 100644 --- a/docs/faq.html +++ b/docs/faq.html @@ -63,7 +63,7 @@
No. There is no menu and nothing to set. The tuning constants are in the source for people who rebuild the mod; see DEVELOPING.md.
No. There is no menu and nothing to set. The tuning constants are in the source for people who rebuild the mod; see DEVELOPING.md.
We tested it, and it isn't worth it. On the real 266-beaver colony we replayed, letting homes change their number of adults shortened the average commute by only about 4% (24.0 to 23.1). But homes able to have a baby fell from 11 to 1, and keeping those baby beds free erased the gain.
-So every home keeps its adult count, and empty beds are left for the game and for babies. That was one colony with a straight-line stand-in for route cost, so others will differ.
+Yes. An adult moves into an empty bed when that shortens the colony's total walk, so a home's number of adults can change.
+It takes only adult beds: the game keeps a third of each home's beds for kits. A move is turned down if it would leave fewer homes able to have a kit.
It's built not to. Every home keeps the same number of adults and children never move, so each home keeps the same free beds and the same chance of a birth. Only which adults live there changes.
+It's built to protect it. Children never move, and adults never take a kit's bed. A move is turned down if it would leave fewer homes able to have a kit: the game needs two adults, a free bed and room for another child.
Both have thousands of subscribers and far more real-world mileage; this one is newer. The comparison on the home page has one replay's numbers.
@@ -188,7 +188,7 @@Yes. The code the stable release started from ran 16 passes in a row in a live game, including a hosted co-op session, with no errors, warnings or rollbacks. This release's newer changes are covered by automated tests but haven't been played in a live game yet. See what is tested and what isn't.
Yes. The code the stable release started from ran 16 passes in a row in a live game, including a hosted co-op session, with no errors, warnings or rollbacks. This release's newer changes are covered by automated tests but haven't been played in a live game yet. See what is tested and what isn't.
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.
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
+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
Each district is solved exactly with the Hungarian algorithm. The colony's total commute is the smallest the rules allow.
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.
Every home keeps exactly the same number of adults, and children never move. Beds for babies stay where they are.
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.
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.
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.
Every player's game should make the same moves, even across a save, a reload or a mid-pass join. What has been played
Every housed adult beaver, its home and its assigned workplace, in one quick snapshot.
Every housed adult beaver, its home and its assigned workplace, and every empty bed, in one quick snapshot.
Real route costs from each workplace to its 32 nearest homes in its district. Farther homes are estimated.
The best way to reassign the adults to the beds adults use today, one district at a time.
Every proposed move is priced again with fresh routes. A cycle of moves is dropped if it would cut a beaver off from work, or if it saves too little.
Whole cycles of moves are applied in a single tick, and rolled back if the game refuses any of them.
The best way to reassign the adults to the district's beds, empty ones included, one district at a time.
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.
Each cycle or chain of moves is applied in a single tick, and rolled back if the game refuses any of them.
A real 266-beaver save (222 employed adults, 89 homes) replayed through the actual pass engine, with straight-line distance standing in for route cost. Then the live game's own log.
+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.
Stable means the evidence below, not that every situation has been tried.
In PowerShell, from the folder you downloaded to:
Get-FileHash .\OptimizedLocalHousing-v1.2.0.zip -Algorithm SHA256
The hash should be:
-cc6b905d0021c3119f15a85186d6a7197e7955bed890d0134d0c6a2f2f654059
+1bae3d47dad8801712d4b73656e312036ec84f5527f72203a5907b8b33a21a3b
The same hash is in the SHA256SUMS file attached to the release.
That's expected on the first pass of a badly housed colony. Children never move, so a child may end up living with different adults; breeding is untouched. Later passes move only a few beavers.
+That's expected on the first pass of a badly housed colony. Children never move, so a child may end up living with different adults. No move leaves fewer homes able to have a kit. Later passes move only a few beavers.
If you dislike the result, load your backup and remove the mod.