Frequently asked questions

It removes work the game repeats in large colonies (rebuilding hauling job lists, rebuilding route maps after road changes, measuring paths to trees that cannot matter, and optionally the memory clean-up freezes) so the game stutters less, without changing what the game decides.

Players whose colony has grown big enough that the game hitches, typically hundreds of beavers late in a game. A small colony has little repeated work to remove, so you are unlikely to notice much there.

There is no single figure, because it depends on your colony and your computer. What has been reported so far:

• Noticeably fewer lag spikes in a late-game save of about 350 beavers (played as 0.4.8; 0.4.9 runs the same code).
• On a computer that had memory clean-up freezes of most of a second about once a minute, incremental garbage collection removed them and made the frame rate much steadier at high tick rates.

There is no controlled frame rate benchmark yet. The mod logs its own timing line so you can see your colony's numbers.

It is built not to. The hauling list is assembled in the same order and sorted with the same comparison as the game's, the tree and plant search returns the game's own answer, and rebuilt route maps have exactly the game's contents. Tests check each of these against the game's own code, and the mod can be run in a mode that compares against the game's code while you play.

There is one known difference. Route maps are now filled before the game first asks for them instead of when it does. A few code paths in the game use a route map only if it is already filled, so they can take the cached route where the unmodded game would have searched again. That is why route maps are always on instead of a setting: every player on the same version runs them alike.

Yes, but none of them change what the game simulates.

• In the game (Mods > Late Game Performance): Incremental garbage collection, Warn when garbage collection is not incremental, Record per-component timings and Adaptive garbage collection pacing (experimental).
• In version-1.1\LateGamePerformance.cfg: testing switches, how the work is split over threads, and which log lines are written. Restart after editing.

The hauling cache, the route maps and the tree and plant search are always on, the same for everyone. To run without one of them, disable the mod.

It stores nothing in saves. To uninstall, disable it and restart. It is still a young mod, so try it on a copy of a save first.

From the GitHub releases page, as a ZIP you extract into your Mods folder. It also needs Harmony and Mod Settings from the Steam Workshop. See the install guide.

Yes, and keeping BeaverBuddies games in step has been the top priority throughout its development. In multiplayer every player's game must calculate exactly the same thing, so a speed-up is only worth having if it gives the game's own answer.

• Hauling lists, tree searches and route maps are checked against the game's own code, including node for node for route maps.
• Nothing that affects the simulation is a setting, so the same version behaves the same for every player.
• Which route maps get built never depends on what any single player's screen asked for.
• The startup line Simulation features: HaulCache on, RouteMaps on, YielderSearch on is the same in every player's log.

See what is tested, and what isn't.

Yes. Every player installs the same version. The mod changes which code runs during the simulation, so all players have to run the same code. A multiplayer mod's own version check covers it, and there is nothing else to match.

No. Incremental garbage collection, adaptive pacing, thread counts and the timing options do not affect the simulation, so each player can set them differently, and each player benefits separately.

Yes, in multiplayer sessions on two computers, including a 35-minute session logged on both. That is two-player play; bigger groups have not been reported. If you try it, please tell us how it went.

Every time a hauler looks for work, the game asks every building with an inventory in the district for its hauling jobs and their weights, sorts the whole list, and tries the jobs in order. It repeats that for every hauler decision, even when nothing changed in between. The mod keeps each building's jobs until something that feeds them changes (stock, reservations, allowed goods, enabled inventories, blocked state, emptying mark, obtain or supply setting, recipe or priority), and keeps the district's sorted list until a building in it changes. As a safety net everything cached is dropped every tick, so an input the mod does not track, such as one added by another mod, can be out of date for at most a single tick.

Every building with an entrance keeps a route map: the road distance from its entrance to every road tile it can reach. When a road changes, the game throws away every map that contains a changed tile, which in a connected district is nearly all of them, and rebuilds each one on the main thread when something next asks for it. The mod rebuilds them at the end of the navigation tick on up to 7 worker threads, in the background, using the game's own map generator on a private copy. The main thread only ever waits for the single map it is about to use.

When a lumberjack looks for a tree (or a gatherer or farmer for a plant), the game measures the path distance from the building to every candidate and only then asks whether the plant has anything to take. For lumberjacks the candidates are every unreserved marked tree on the map, and most of them are still growing. A plant with nothing to take matters only for whether it can be reached, and only until the search has found something reachable that is grown or alive. After that its distance cannot change the answer, so the mod leaves that lookup out. Plants that have something to take are looked up exactly as before, in the same order.

If anything throws inside a feature, that feature switches itself off for the rest of the session and the game's own code runs. If a game method a feature needs is missing (for example after a game update), the feature does not start at all and the startup line says OFF. Patches on methods that Harmony cannot patch safely are refused. See Troubleshooting.

Yes. HaulCacheVerify = true and YielderSearchVerify = true in LateGamePerformance.cfg run the game's own code as well, compare, log any difference, and use the game's result. They are slower than no mod, so use them for a test session and switch them off afterwards. In the stats lines look for verify mismatches 0. Any mismatch is a bug worth reporting.

The game cleans up memory with every thread stopped, and each time it goes over everything still in use. In a late-game colony that is 1.6 GB and more. Incremental collection does the same work a few milliseconds at a time across many frames. In one 35-minute multiplayer session the computer without it had 39 collections with a median of 675 ms each, about 30 seconds frozen in total; the computer with it had one collection frame over 50 ms outside of saves. Those were two different computers, so hardware counts as well as the setting.

Unity reads the incremental collection choice from Timberborn_Data\boot.config before any mod loads, so a mod cannot switch it while the game runs. Ticking the box adds one line, gc-max-time-slice=3, and unticking removes it. Nothing else in the file is touched, a backup (boot.config.before-incremental-gc.bak) is written beside it before the first change and never overwritten, and the file is only ever written because you clicked the box, never at startup for a player who never ticked it. Steam's "verify integrity of game files" and game updates restore the original; if the box is still ticked, the mod puts the line back at the next start.

With incremental collection on, Unity does up to a fixed 3 ms of clean-up per frame while a cycle is running. The experimental pacing setting picks the slice each frame from recent frame times: 3 ms when frames are slow, 6 ms when they are fast, 8 ms while paused. One session each way showed no difference that could be told from noise, so it is off by default and marked experimental. It only changes the length of a slice, never what is collected, and it does not affect the simulation.

One line every 1,000 ticks in Player.log. It shows:

• Ticks per second against what the game's time scale asks for, which says whether the game is keeping up at all. Above speed 1 the game itself slows large colonies down, and the figure is the speed after that.
• Simulation time per tick against everything else per frame (rendering, animation, the game's and other mods' per-frame systems, and Unity itself), as shares of the main thread.
• The longest frame and the longest simulation slice.
• Garbage collections: how long the frames containing one took, and whether collection is incremental.
• Saves, reported on their own, since a save freezes the game for most of a second.
• Managed memory in use and the allocation rate.

The RouteMaps: line's "longest single pause" is the figure to watch for hitching.

Yes. Tick Record per-component timings on the settings page and load a save. The mod switches on the game's own per-component timers and writes a report to Documents\Timberborn\LateGamePerformance every 3,000 ticks. It applies from the next save load, the game runs a little slower while it is on, and it does not affect the simulation. Launching the game with -metrics has the same effect.

The hauling cache is dropped every tick, so an input the mod does not track, for example one added by another mod, can be out of date only within a single tick. It needs Harmony and Mod Settings. Beyond that, keep a copy of your save when combining mods, as always.

It is built against 1.1.2.4 and asks for 1.1.2.4 or newer. On start the mod checks that every game method it patches still exists. After a game update that moves something, the affected feature does not start, the game runs its own code, and the startup line says OFF for it.

Yes, MIT licensed, and free. The source is on GitHub. It is an unofficial mod and is not affiliated with Mechanistry.

Open an issue with the mod and game versions, the [LateGamePerformance] lines from Player.log and what you were doing. More detail in Troubleshooting.