From 75592772324f405bc80eb334ed88517f2f712660 Mon Sep 17 00:00:00 2001 From: Kyler Ramsey Date: Tue, 22 Sep 2026 09:47:46 -0700 Subject: [PATCH] Release 1.1.0 Bump the mod to 1.1.0 for the features merged in #6, #8, #9 and #10, and update the docs that described 1.0.0 behavior. - csproj and manifest: version 1.1.0. The manifest description now mentions planting-tool outlines and remembered pins. - README: "New in 1.1.0" notes, the 1.1.0 zip name, and the check count (142: 77 game-free, 65 needing the game). Also says plainly that the 1.1.0 features have not been playtested in game yet. - VALIDATION.md: 1.1.0 header, the check summary, the per-building refresh caching and planting-tool behavior, and the playtest status. - Website: pins are remembered per settlement rather than reset, the new planting-tool FAQ entry, translation via one CSV, refresh and performance wording, and the update/uninstall notes for Pins.txt. Co-Authored-By: Claude Opus 5.5 --- README.md | 20 +++++++++++++------ VALIDATION.md | 12 +++++------ docs/faq.html | 12 +++++++---- docs/index.html | 14 +++++++------ docs/install.html | 4 ++-- docs/troubleshooting.html | 8 ++++---- .../version-1.1/manifest.json | 4 ++-- source/PersistentWorkAreas.csproj | 2 +- 8 files changed, 45 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 23849fc..e87b118 100644 --- a/README.md +++ b/README.md @@ -4,12 +4,20 @@ Keep a building's working-area outline visible after deselecting it, including w **Website:** has the feature overview, an install guide, troubleshooting, and an FAQ. -## New in 1.0.0 +## New in 1.1.0 -First stable release, with no behavior changes from 0.1.3. That build has now been tested in game, single-player and in a two-player BeaverBuddies Stability Fork session. The game-log line now reads its version number from the mod itself, and the release zip now uses standard `/` folder separators, so it extracts correctly on macOS and with non-Windows tools. +- **Planting tools show their planters.** Pick a crop or tree in the planting tools and the working areas of every building that can plant it appear on their own: farmhouses for crops, aquatic farmhouses for aquatic crops, and foresters for trees and bushes, including ones still under construction. They disappear when you leave the tool. **Clear pinned areas** clears only your pins. +- **Pins are remembered.** Each settlement's pins are kept on your own computer in `PersistentWorkAreas\Pins.txt`, next to your Timberborn `Saves` folder, and come back when you load that settlement. They are never written into the save, so each co-op player keeps their own. +- **Faster refreshes with many pins.** A path or terrain change now re-checks only the pinned buildings it can reach, and selecting a pinned building no longer recalculates every pin. +- **Translatable text.** All UI text now comes from `Localizations/enUS_PersistentWorkAreas.csv`, so a translation is one more CSV. The English text is unchanged. + +When updating, replace the whole `PersistentWorkAreas` folder. The new DLL reads its text from the CSV, so copying only the DLL over 1.0.0 shows raw keys. + +1.1.0 passes 142 automated checks. Its new features have not been playtested in game yet; 1.0.0's behavior has been. ### Earlier versions +- **1.0.0:** First stable release, with no behavior changes from 0.1.3, tested in game single-player and in a two-player BeaverBuddies Stability Fork session. The game-log line reads its version number from the mod itself, and the release zip uses standard `/` folder separators. - **0.1.3:** Documentation correction only. The game itself draws a Builder's Hut's range outline while it is selected; that is vanilla behavior, not something this mod adds or changes. - **0.1.2:** Builder's Huts can no longer be pinned, so they no longer show a "Working area" panel. - **0.1.1:** The pin control gained a clearly drawn checkbox, an ON/OFF badge, a bordered panel, and hover/keyboard-focus highlighting. @@ -18,7 +26,7 @@ First stable release, with no behavior changes from 0.1.3. That build has now be ## Install 1. Close Timberborn. -2. Extract `PersistentWorkAreas-v1.0.0.zip` into your Timberborn `Mods` folder (normally `Documents\Timberborn\Mods`). The result should be `Mods\PersistentWorkAreas\version-1.1\manifest.json` and `PersistentWorkAreas.dll` beside it. +2. Extract `PersistentWorkAreas-v1.1.0.zip` into your Timberborn `Mods` folder (normally `Documents\Timberborn\Mods`). The result should be `Mods\PersistentWorkAreas\version-1.1\manifest.json` and `PersistentWorkAreas.dll` beside it. 3. Start Timberborn and enable **Persistent Work Areas** in the mod manager. Restart if prompted. Requires Timberborn **1.1.2.4** or a compatible 1.1 build. Built and tested on Timberborn 1.1.2.4. Later versions may change the internal renderer API. @@ -44,7 +52,7 @@ The mod supports navigation-based working areas. It does not pin district road c Designed for compatibility with the **BeaverBuddies Stability Fork**. The mod does not patch game methods, change simulation or building data, send multiplayer events, or modify saves; the pins live in their own small local file. It uses the same navigation queries as the game's selected-building visualizer and a separate instance of its outline renderer. -The release build passes 38 automated lifecycle/API checks. The mod has been tested in game on Timberborn 1.1.2.4, both single-player and in a two-player BeaverBuddies Stability Fork session with the mod installed on both computers. See `VALIDATION.md` for what was checked and how. +The release build passes 142 automated checks. 77 of them test the pin, refresh-planning, planting-tool and pin-file logic without the game, and 65 check the mod against the installed game's assemblies and blueprints. Version 1.0.0 was tested in game on Timberborn 1.1.2.4, both single-player and in a two-player BeaverBuddies Stability Fork session with the mod installed on both computers. The features new in 1.1.0 have not been playtested in game yet. See `VALIDATION.md` for what was checked and how. ## Build from source @@ -54,9 +62,9 @@ Install the .NET 8 SDK and have Timberborn installed, then run: .\build.ps1 -GameDir 'C:\Program Files (x86)\Steam\steamapps\common\Timberborn' ``` -The script builds the mod, runs checks, and creates `dist\PersistentWorkAreas-v1.0.0.zip`. No game, Unity, Harmony, or BeaverBuddies DLLs are redistributed. The game DLLs are used only as build references. +The script builds the mod, runs checks, and creates `dist\PersistentWorkAreas-v1.1.0.zip`. No game, Unity, Harmony, or BeaverBuddies DLLs are redistributed. The game DLLs are used only as build references. -Without the game, `dotnet run --project tests/Checks.csproj -c Release` runs only the pin-logic checks and reports the rest as skipped. GitHub Actions runs them for pull requests and pushes to `main`. +Without the game, `dotnet run --project tests/Checks.csproj -c Release` runs only the checks that need no game files (pin, refresh-planning, planting-tool and pin-file logic) and reports the rest as skipped. GitHub Actions runs them for pull requests and pushes to `main`. ## License diff --git a/VALIDATION.md b/VALIDATION.md index 09adea3..745c1fa 100644 --- a/VALIDATION.md +++ b/VALIDATION.md @@ -1,23 +1,23 @@ -# Validation — Persistent Work Areas 1.0.0 +# Validation — Persistent Work Areas 1.1.0 ## In-game testing -- Tested in game on Timberborn 1.1.2.4 with the BeaverBuddies Stability Fork, both single-player and in a two-player co-op session with the mod installed on both computers. Pinning, clearing and outline display worked as expected. -- The tested build was 0.1.3. The 1.0.0 code is the same except for the version number and the startup log line, which now reads the version from the assembly. +- **1.1.0 has not been playtested in game yet.** Its new behavior (planting-tool outlines, pins remembered in a local file, per-pin refresh caching and localized text) is covered only by the automated checks below. Run the release playtest checklist, including steps 8 to 10, to confirm it. +- 1.0.0 was tested in game on Timberborn 1.1.2.4 with the BeaverBuddies Stability Fork, both single-player and in a two-player co-op session with the mod installed on both computers. Pinning, clearing and outline display worked as expected. That tested build was 0.1.3; the 1.0.0 code was the same except for the version number and the startup log line. - Running the mod on only one of the two co-op computers has not been playtested. ## Automated checks - Compiled for `netstandard2.1` against the installed Timberborn 1.1.2.4 assemblies: zero errors and zero warnings. -- 38 checks passed: reference-identity pins, duplicate pin/unpin, independent pins, replacement/deletion behavior, global clear, new-map isolation, native renderer constructors/methods/cleanup fields, delegate binding to internal renderer methods, lifecycle/navigation/event interfaces, no simulation persistence interfaces, no Harmony/BeaverBuddies dependencies, package/key-binding consistency, manifest/assembly version agreement, and presence of the Builder's Hut marker component used to exclude it from pinning. +- 142 checks passed. 77 need no game files and also run on GitHub Actions for every pull request: pin-set identity and change tracking, refresh planning against a fake navigation world that counts range queries and outline rebuilds, the planting-tool rule and shown-building bookkeeping, and the pin-file format, escaping, 100-settlement cap, restore by entity id and atomic on-disk writes. 65 need the installed game: reference-identity pins, duplicate pin/unpin, independent pins, replacement/deletion behavior, global clear, new-map isolation, native renderer constructors/methods/cleanup fields, delegate binding to internal renderer methods, lifecycle/navigation/event interfaces, no simulation persistence interfaces, no Harmony/BeaverBuddies dependencies, package/key-binding consistency, manifest/assembly version agreement, presence of the Builder's Hut marker component used to exclude it from pinning, the navigation-change bounds against the game's `BoundingBox`, the service's refresh wiring on a live instance, planting-tool events and the planter pairing against the game's own blueprints, localization CSV layout and the absence of hard-coded UI text in the DLL, and pin-file saving, restoring and retrying on a live instance with the game's settlement and entity-registry types. - Compared the display path with the installed game's `BuildingRangeDrawer`, `BoundsNavRangeDrawer`, and navigation query calls. The mod uses those same range queries and its own outline-renderer instance. - Reviewed the BeaverBuddies Stability Fork's `IO/BuildCompatibility.cs`: its handshake identifies Timberborn and the BeaverBuddies/TimberNet binaries. This mod changes none of them. - The display service only implements frame-update, input, load, and navigation-notification interfaces. Pin state is per game-scoped service instance. Each settlement's pins are also kept, by entity id, in a local text file next to the `Saves` folder (`Documents\Timberborn\PersistentWorkAreas\Pins.txt` on Windows). It is read once after the map loads, and rewritten from the frame update after the pins change, and once after a load that finds the settlement below the top of the file, to keep it among the 100 most recent. A failed write is retried every 10 seconds and again on leaving the map, which never erases the file. A file this version cannot read is kept as `Pins.txt.bak` before it is replaced. There are no Harmony patches, replay events, simulation ticks, random calls, or save writes. -- Renderer geometry refreshes on pin, selection, construction-mode, height-visibility and navigation changes, with navigation refreshes capped at five per second. Empty pin sets do no range queries or drawing. All pins share a combined mesh. Clearing releases the renderer's owned meshes and cloned materials. +- Each pinned or planting-tool building caches its own range. A navigation change re-queries only the buildings whose range it can reach (road-spill ranges are always re-queried), with those refreshes capped at five per second. Selection and visible-level changes redraw from the cache without a query; construction-mode changes re-query every building. With no pins and no planting tool open, nothing is queried or drawn. All outlines share a combined mesh, and the renderer's owned meshes and cloned materials are released once nothing is drawn. ## Not established by the automated checks -These are compiled API and logic checks, not Unity rendering tests or a co-op session; the in-game testing above covers those. Neither establishes frame-rate impact in a very large colony or compatibility with every other mod. Internal renderer reflection is deliberately isolated in `NativeOutline.cs` and checked against the installed assemblies. +These are compiled API and logic checks, not Unity rendering tests or a co-op session. The in-game testing above covers those for the 1.0.0 behavior; for 1.1.0's new behavior, the playtest checklist below still has to be run. Neither establishes frame-rate impact in a very large colony or compatibility with every other mod. Internal renderer reflection is deliberately isolated in `NativeOutline.cs` and checked against the installed assemblies. ## Release playtest checklist diff --git a/docs/faq.html b/docs/faq.html index 16d910d..c1fabd7 100644 --- a/docs/faq.html +++ b/docs/faq.html @@ -87,7 +87,7 @@

Safety and compatibility

Is it safe for my saves? Can I remove it mid-game? -

Yes. The mod never writes to your save files and doesn't change buildings, beavers or the simulation. Pins aren't saved at all. You can disable or delete the mod at any time and your colony loads as normal.

+

Yes. The mod never writes to your save files and doesn't change buildings, beavers or the simulation. Pins are kept in their own small file outside your saves. You can disable or delete the mod at any time and your colony loads as normal.

Does it work in multiplayer? Do both players need it? @@ -119,7 +119,11 @@

Features and limits

Do my pins survive saving and loading? -

No. Pins reset when you leave the map, load a save, or a multiplayer resync happens. That's deliberate, so the mod can never affect a saved colony.

+

Yes, since version 1.1.0. Each settlement's pins are remembered on your own computer in Documents\Timberborn\PersistentWorkAreas\Pins.txt and come back when you load any save of that settlement. They are never written into the save itself, so the mod can't affect a saved colony. A different settlement starts with no pins, and a co-op guest's pins usually don't come back after a resync, because the guest's settlement is named after the host's save. To forget every pin, delete that file.

+
+
+ Why do farmhouse or forester outlines appear when I pick a crop or tree? +

Since version 1.1.0, picking a crop or tree in the planting tools outlines the working area of every building that can plant it: farmhouses for crops, aquatic farmhouses for aquatic crops, and foresters for trees and bushes, including ones still under construction. The outlines go away when you leave the planting tool. Clear pinned areas removes only your pins, not these.

Can it pin district road colors, effect radii or placement ghosts? @@ -127,11 +131,11 @@

Features and limits

Is it translated? -

Not yet. The mod's text is English only.

+

Not yet. The mod's text is English only, but since version 1.1.0 all of it lives in one file, version-1.1/Localizations/enUS_PersistentWorkAreas.csv. A translation is one more file there with the same keys, named for the game's language code, for example deDE_PersistentWorkAreas.csv.

Will it slow down my game? -

It's designed not to. Outlines recalculate at most five times per second and only when something changes, all pins share one combined mesh, nothing runs while there are no pins, and the mesh is released when you clear. If you notice a drop in a very large colony, let us know.

+

It's designed not to. A terrain or path change re-checks only the pinned buildings it can reach, at most five times per second, and selecting a building redraws from what was already worked out. All outlines share one combined mesh, nothing runs while there are no pins and no planting tool is open, and the mesh is released once nothing is drawn. If you notice a drop in a very large colony, let us know.

diff --git a/docs/index.html b/docs/index.html index 189a8b8..851d99c 100644 --- a/docs/index.html +++ b/docs/index.html @@ -150,6 +150,8 @@

Supported

  • Several pins at once, merged where they overlap
  • Outlines that follow terrain, path, visible-level and construction-mode changes
  • Automatic cleanup when a pinned building is deleted
    • +
  • Planting tools that outline every farmhouse or forester able to plant the chosen crop or tree
    • +
  • Pins remembered for each settlement, in a small local file
    • @@ -159,19 +161,19 @@

    Not included

  • Effect-radius overlays that are not navigation-based
  • Building-placement ghosts
  • Pin controls for Builder's Huts
    • -
  • Saving pins between sessions, and non-English UI text
    • +
  • Translations other than English (adding one takes a single CSV file)
    • -

    Pins are temporary

    -

    Pins reset when you leave the map, load a save or a multiplayer resync happens, and they are never written to your save file. That is deliberate: it keeps the mod from ever affecting a colony.

    +

    Pins are remembered, not saved

    +

    Each settlement's pins are kept on your own computer, in Documents\Timberborn\PersistentWorkAreas\Pins.txt, and come back when you load that settlement. They are never written to your save file, so the mod can't affect a colony and each co-op player keeps their own.

    Fails on its own

    If a future game update changes the internals the outline renderer relies on, pinning disables itself for that map and says so in the panel and the game log. Nothing else is affected.

    -

    Running a large colony? The outline recalculates at most five times per second, does no work while nothing is pinned, and releases its meshes when you clear.

    +

    Running a large colony? A terrain or path change re-checks only the pinned buildings it can reach, at most five times per second. Nothing runs while nothing is pinned and no planting tool is open, and the meshes are released once nothing is drawn.

    @@ -183,8 +185,8 @@

    Fails on its own

    Game versionTimberborn 1.1.2.4 or a compatible 1.1 build. Built and tested on 1.1.2.4; later versions may change the internal renderer API. MultiplayerDesigned for compatibility with the BeaverBuddies Stability Fork. Tested in two-player co-op with the mod on both computers, which is the recommended setup. It sends no multiplayer events and pins are always local. Other modsNo required mods. No Harmony patches and no BeaverBuddies dependency. - SavesUntouched. You can remove the mod at any time. - LanguageEnglish UI text. + SavesUntouched. Pins live in their own small local file. You can remove the mod at any time. + LanguageEnglish UI text, translatable with one CSV file. diff --git a/docs/install.html b/docs/install.html index 6a322ee..7b65162 100644 --- a/docs/install.html +++ b/docs/install.html @@ -132,10 +132,10 @@

    Updating

  • Extract it into the same Mods folder and choose Replace when asked about existing files.
  • Start the game and confirm Persistent Work Areas is still enabled in the mod manager.
    • -

    Pins are never saved, so there's nothing to migrate.

    +

    Replace the whole folder rather than only the DLL: since 1.1.0 the mod reads its text from the Localizations folder beside it. Your pins are kept outside the mod folder, in Documents\Timberborn\PersistentWorkAreas\Pins.txt, so updating keeps them.

    Uninstalling

    -

    Disable the mod in the mod manager, or close the game and delete Documents\Timberborn\Mods\PersistentWorkAreas. Your saves are unaffected because the mod never writes to them.

    +

    Disable the mod in the mod manager, or close the game and delete Documents\Timberborn\Mods\PersistentWorkAreas. Your saves are unaffected because the mod never writes to them. To remove the remembered pins too, delete the Documents\Timberborn\PersistentWorkAreas folder.

    diff --git a/docs/troubleshooting.html b/docs/troubleshooting.html index 949fb9c..90cbdd5 100644 --- a/docs/troubleshooting.html +++ b/docs/troubleshooting.html @@ -132,7 +132,7 @@

    I pinned a building but no outline is showing

    The outline doesn't match my recent terrain or path changes

    What to expect
    -
    Outlines refresh when terrain, paths, visible level, construction mode or your selection change, at most five times per second, so a change can take a moment to show.
    +
    Outlines recalculate when terrain, paths or construction mode change near a pinned building, at most five times per second, so a change can take a moment to show. Selection and visible-level changes redraw from the last result right away.
    Fix
    Wait a second. If it's still stale, uncheck and re-check the building's box to rebuild it, and report it if it keeps happening, saying what you changed.
    @@ -142,9 +142,9 @@

    The outline doesn't match my recent terrain or path changes

    My pins disappeared

    Why
    -
    Pins are temporary by design. They reset when you leave the map, load a save, or a multiplayer resync happens. They are never written to your save file. Deleting a pinned building also removes its pin, and Clear pinned areas removes all of them.
    +
    Pins are remembered for each settlement in Documents\Timberborn\PersistentWorkAreas\Pins.txt, never in your save. A different settlement starts with none. A co-op guest's pins usually don't come back after a resync, because the guest's settlement is named after the host's save. Deleting a pinned building removes its pin, Clear pinned areas removes all of them, and deleting Pins.txt forgets every settlement's pins. Outlines that appeared because a planting tool was open go away when you leave the tool; they were never pins.
    Fix
    -
    Pin the buildings again. This is expected behavior, not a fault.
    +
    Load a save of the same settlement, or pin the buildings again. If pins don't come back for the same settlement, look in Player.log for a [PersistentWorkAreas] Pinned areas not warning and report it.
    @@ -214,7 +214,7 @@

    Co-op and BeaverBuddies

    Slowdowns with many pins

    What to expect
    -
    The outline only recalculates when something changes, at most five times per second, and does no work while nothing is pinned. All pins share one combined mesh.
    +
    A terrain or path change re-checks only the pinned buildings it can reach, at most five times per second. Nothing runs while nothing is pinned and no planting tool is open. All outlines share one combined mesh. Opening a planting tool works out every matching farmhouse's or forester's area at once, which can take a moment in a very large colony.
    Fix
    Clear pins you no longer need. If you still see a drop in frame rate, report it with roughly how many pins and how large your colony is.
    diff --git a/packaging/PersistentWorkAreas/version-1.1/manifest.json b/packaging/PersistentWorkAreas/version-1.1/manifest.json index 29ea7db..6eaa088 100644 --- a/packaging/PersistentWorkAreas/version-1.1/manifest.json +++ b/packaging/PersistentWorkAreas/version-1.1/manifest.json @@ -1,8 +1,8 @@ { "Name": "Persistent Work Areas", - "Version": "1.0.0", + "Version": "1.1.0", "Id": "kyler.persistentworkareas", "MinimumGameVersion": "1.1.2.4", - "Description": "Pin farm, forester, lumberjack and other navigation-based working-area outlines. Clear all pins from the top-right button or a configurable key binding. Local display only; designed for compatibility with the BeaverBuddies Stability Fork.", + "Description": "Pin farm, forester, lumberjack and other navigation-based working-area outlines. Planting tools also outline the farmhouses or foresters that plant the chosen crop or tree, and pins are remembered per settlement in a local file, never in the save. Clear all pins from the top-right button or a configurable key binding. Local display only; designed for compatibility with the BeaverBuddies Stability Fork.", "RequiredMods": [] } diff --git a/source/PersistentWorkAreas.csproj b/source/PersistentWorkAreas.csproj index 9c1a6a5..3756871 100644 --- a/source/PersistentWorkAreas.csproj +++ b/source/PersistentWorkAreas.csproj @@ -2,7 +2,7 @@ netstandard2.1 latest - 1.0.0 + 1.1.0 C:\Program Files (x86)\Steam\steamapps\common\Timberborn $(GameDir)\Timberborn_Data\Managed