Performance Log 0.1.4 — Preview 5

Fixes for what the first 0.1.3 recording from a real game showed, a more honest estimate of what the mod itself costs, and one new opt-in setting. Still a preview, and none of this has been played yet; docs/TESTING.md lists what each change needs a recording to confirm. Nothing here changes what the game simulates.

Recording

• Beavers are one row again. A beaver loaded from a save was keyed by its own name (BeaverAdult Malak), one born during play by BeaverAdult(Clone), so beavers showed as 14% of entity time instead of 85%. Entities are now keyed by kind. (#1)
• overheadUs counts what the per-call patches really cost. patchCallNs is now the real entity patch bodies (new patchBodyNs in the # calibration| line) plus Harmony's cost; up to 0.1.3 it timed an empty patch and read 0 in every recording. (#2)
• Watch methods are sampled at their own rate, sharing the watched methods' budget, so one busy method no longer leaves the rest timed on 1 call in 30. Windows nobody timed are written with sampled 0, not counted as 0 ms. (#2)
• Frames with a garbage collection are counted as "allocation not measured" (new # capability-final|allocSource| line) and left out of allocation-per-second, instead of read as 0 KB. (#3)
• New: AutoWatch (PerformanceLog.cfg only, off by default) times other mods' prefixes/postfixes/finalizers on the game's hot methods in the free Watch slots (40 in all), leaving out patches on the random numbers, Guid and DateTime. It patches once, when the first game loads, and restores the game's random state afterwards for BeaverBuddies co-op. Keep it off in co-op until it has been played with two players. (#5)

summary.md and perflog.py

• Slow frames are blamed on a singleton only if it took 10% of the frame or 5 ms; otherwise it says none stood out and whether the frame had a save or a collection. (#3)
• otherMs is split by Unity phase (Update, LateUpdate, plPost, the phases before Update, between phases), and the "not the game's code" finding points at scripts or at the graphics card accordingly. (#3)
• report names the other mods whose patches run inside a singleton's time; compare lists patches only one session has. (#3)
• Older recordings: entity rows are added up by kind so compare lines 0.1.3 and 0.1.4 up, and a KNOWN ISSUE is printed when a recording's rows are split or its overheadUs understated the patches. (#1, #2)

Full list: CHANGELOG.md.

Install

1. Close Timberborn. Extract PerformanceLog-0.1.4.zip into Documents\Timberborn\Mods, replacing your existing install.
2. Still requires Harmony (2.4.1+) and Mod Settings (1.1.0.0+) from the Steam Workshop.
3. Enable Performance Log in the mod manager and restart.

Verified before release

113 checks of the mod (against the game's real assemblies) and 65 checks of the analysis tool, all passing. Each fix has a check that fails without it.

SHA-256 of PerformanceLog-0.1.4.zip: 70CB7791F9BA4FCC64A69D010CFA8C4AC52D483CB230507AC687780A4CEF1F0C

Performance Log 0.1.3 — Preview 4

Changes the mod's defaults — not new options, the starting values — to capture the most detail a session can hold without configuring anything. Still a preview, and none of this has been played; see docs/TESTING.md for exactly what's unverified, including a new item specific to this release.

What changed

Setting	Was	Now
Profile	standard	deep — samples every entity component (Walker, Workplace, …), not just entity kinds
SpikeContributors	5	8 — every spike slot filled, tied to the constant that defines the max so it can't drift out of sync
OverheadBudgetPercent	0.5	1 — doubles how dense entity/component/allocation sampling is allowed to be, still comfortably under the report's own 2% "measuring costs too much" line

SlowFrameMs, SummarySeconds, ProfileSeconds and MaxSlowRowsPerMinute are unchanged — they trade off row count and file size, not the depth of any one row, and MaxSlowRowsPerMinute specifically exists as a deliberate cap against filling the disk in a pathologically bad session.

Nothing here is a new setting; the in-game Mod Settings panel and PerformanceLog.cfg both still work exactly as in 0.1.2, just starting from these new values.

Worth knowing before you play

Profile = deep has never run in a real game. The one real recording so far (0.1.0) used standard. Deep mode's patch on entity components (MeteredTickableComponent.Tick) has only had its target validated against the game's real assemblies, never actually applied under Harmony/Mono — and it's now what every fresh install gets. Worth checking first: the patch shows installed in frames.csv's header, and profile.csv gets rows of kind component.

Expect a real, measurable increase in the mod's own overhead from this — deep's component sampling plus doubled sampling density. Still designed to stay under the 2% threshold the report warns about, but it's a genuine tradeoff. OverheadBudgetPercent is the setting to lower if it runs hotter than you'd like.

Install

1. Close Timberborn. Extract PerformanceLog-0.1.3.zip into Documents\Timberborn\Mods, replacing your existing install.
2. Still requires Harmony (2.4.1+) and Mod Settings (1.1.0.0+) from the Steam Workshop.
3. Enable Performance Log in the mod manager and restart.

Verified before release

91 checks of the mod and 44 checks of the analysis tool, all passing — including new assertions that a fresh Config really is deep/8/1 by default, and that a bad or missing Profile line falls back to deep, not standard.

SHA-256 of PerformanceLog-0.1.3.zip: A45E28F1C680CB15067FA68193AD34760BA5729546BAFEA99E4086C186B157CB

Performance Log 0.1.2 — Preview 3

Adds an in-game settings page, hooked into the Mod Settings mod (which is now a required dependency, like Harmony). Still a preview, and this feature specifically has not been played at all — see docs/TESTING.md for exactly what is and isn't checked.

What's new

Open Timberborn's Mod Settings menu (from the main menu or in a running game) and you'll find Performance Log with six sliders:

• Slow frame threshold (ms)
• Summary window (s)
• Profile window (s)
• Overhead budget (% of a frame)
• Spike contributors
• Slow frame rows per minute, at most

Changes apply from the next game or save you load — no restart. The panel starts from whatever PerformanceLog.cfg already says; once you touch a setting in the menu, the menu remembers it from then on and the .cfg line for it stops doing anything.

Enabled, Profile, Watch and OutputFolder stay in PerformanceLog.cfg only, and still need a restart. They decide which parts of the game get patched — including whether the entity tick is patched at all when Profile = off — and that's decided before Mod Settings (or any Bindito context) exists. A note in the panel says so.

Install

1. Close Timberborn. Extract PerformanceLog-0.1.2.zip into Documents\Timberborn\Mods, replacing your existing install.
2. It now requires the Harmony mod (2.4.1+) and the Mod Settings mod (1.1.0.0+) from the Steam Workshop.
3. Enable Performance Log in the mod manager and restart. Open Mod Settings to confirm the panel is there.
4. Play with the game in front, and leave normally.

Verified before release

91 checks of the mod (up from 89: two new checks cover the settings panel's clamping and that it seeds correctly from PerformanceLog.cfg) and 44 checks of the analysis tool, all passing. What's genuinely untested: whether Mod Settings actually renders the panel and its sliders, and whether a value changed in-game reaches a real session — both need the running game (see docs/TESTING.md's five-minute checklist, which now includes changing a setting and checking it took effect).

SHA-256 of PerformanceLog-0.1.2.zip: AAAFDCD91048F60B832CDED7CFB5CEB5092118F0E060450ED67F4F58DAC2A893

Performance Log 0.1.1 — Preview 2

Fixes for what the first recording from a real game showed. Still a preview: 0.1.0 has been played once (every patch applied, a 31 minute session ended in a normal exit), but these fixes have only been checked outside the game. See docs/TESTING.md for what the first run proved and what is still unproven.

What was wrong in 0.1.0, and is fixed

• The mod swapped its timing wrappers into the game's singleton arrays about four times every frame (488,601 swaps in 122,150 frames): the game keeps two singleton services alive and they alternate, and the mod remembered only one. That garbage and time were counted inside otherMs / otherKB. Each service is now wrapped once. In 0.1.0 recordings, distrust the allocation figures and the garbage-collection section; tools/perflog.py report now prints a KNOWN ISSUE line for each known defect of the version that made a recording.
• Files were held open, so zipping or copying a session folder while the game ran silently left out frames.csv, profile.csv, spikes.csv and events.csv. They are now opened, appended to and closed on each write, shared with readers, and retried if someone else holds them.
• Every singleton of the game itself was labelled with no mod ("unknown"). They are now game.
• workingMB was always 0 (Unity's Mono reports 0). It now asks Windows, and the header says where the figure comes from.
• Loading steps now record how much the managed heap grew during each one, in profile.csv, summary.md and the report. (The first recording's heap went from 54 MB to 1.7 GB while loading, and nothing said which steps did it.)
• LoadAll never ran was a false alarm (the counter was cleared when the session started in the middle of the load).
• Draw calls: Unity 6 has no Draw Calls Count, Batches Count or GC Allocated In Frame counter (checked against this game's UnityPlayer.dll). prDraw is now the sum of Unity 6's draw call counters.
• The allocation source line now says why the exact counter was not used, and the cost of a Harmony patch is measured after warming up.

Install

1. Close Timberborn. Extract PerformanceLog-0.1.1.zip into Documents\Timberborn\Mods, replacing 0.1.0. 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 with the game in front (a game in the background is throttled and says little), and leave normally.
4. Give the newest session folder to Claude, or run python PerformanceLog\tools\perflog.py report <folder> (Python 3.8+). Each folder has a README.md that explains how to read it.

What to check on the first run

Open the frames.csv header: # capability|workingSet| should say from Windows, and at the end # capability-final|patchCalls|singleton wrappers put in place should be a handful, not hundreds of thousands. Details are in the checklist in docs/TESTING.md.

Verified before release

89 checks of the mod (core timing against a scripted clock; the game-facing parts against the game's real 1.1.2.4 assemblies) and 44 checks of the analysis tool. Each fix that can be checked outside the game has a check that fails without it.

SHA-256 of PerformanceLog-0.1.1.zip: 063CEFFD7739E2686801671A1E502B862A5F5D3EBB644028A4E5885D509F6026

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