Performance Log 0.1.0 — Preview 1

First release. A preview: it has passed its automated checks but has not been run in a game yet. Please read the first-run check below before relying on it.

Performance Log records where a Timberborn session's time and memory go, and writes it to Documents\Timberborn\PerformanceLog\<date and time>\ in a form a person or an AI assistant can read to diagnose slowness in the game or in other mods. It only observes: it never changes what the game simulates.

Install

1. Close Timberborn. Extract PerformanceLog-0.1.0.zip into Documents\Timberborn\Mods. It contains one PerformanceLog folder.
2. It requires the Harmony mod (2.4.1 or newer) from the Steam Workshop. Requires Timberborn 1.1.2.4 or a compatible 1.1 build.
3. Enable Performance Log in the mod manager and restart. Play, and leave normally (menu → exit).
4. Give the newest session folder to Claude, or run python PerformanceLog\tools\perflog.py report <folder> (Python 3.8+, nothing to install). Each folder has a README.md that explains how to read and diagnose it.

What it records

• Every frame's time and where it went (simulation tick loop, once-per-tick singletons, entity ticks, the wait for the parallel tick, per-frame updates, saving, drawing and the rest), Unity's frame phases, garbage collection and allocation.
• The cost of every singleton (timed on every call, so a slow frame is blamed on the exact one), every kind of entity (sampled), and any method named in the config (Watch), each tagged with the mod it belongs to.
• Saves with their stages, loading (every singleton's Load and PostLoad), the colony's size, the game speed, the computer and settings, every enabled mod and which mod patches which hot method.
• What each measurement source could do, and what measuring itself costs.

tools\perflog.py has report (findings with evidence and next steps), compare (two sessions, and what else differed between them) and list.

First-run check (5 minutes)

Nothing that needs the running game has been seen working yet: Harmony applying the patches, Unity's player-loop hooks, the profiler counters. If a part fails to start it says so in Player.log and at the top of summary.md, that part stays off, and the game carries on. The checklist in docs/TESTING.md says what to look for; the short version is: play three minutes, then open summary.md and read its "Read first" list, and check that the # capability|patch|... lines in the frames.csv header say installed.

Verified before release

82 checks of the mod (core timing against a scripted clock, and the game-facing parts against the game's real 1.1.2.4 assemblies: every patch target resolves and can be patched, the singleton wrappers run through the game's own load and tick loops) and 40 checks of the analysis tool. An independent read-only review of the game-facing code, checked against the game's decompiled code and BeaverBuddies, found no crash or hang; the issues it did find are fixed in this release. See docs/TESTING.md for the full list and what is not verified.

SHA-256 of PerformanceLog-0.1.0.zip: 157CCA4DC70297932879C2D591449455D7E3787886B6ADD40F073367FE0434C4