[tharbad08]

Summary

Standalone Timberborn 1.1 port of Benchmark & Optimizer, derived from the project's existing v1.1 implementation. The original BenchmarkAndOptimizer/ mod is untouched. The port remains separate from the gameplay-focused TB Optimizer.

This supersedes closed PR datvm#46, whose branch had diverged and unintentionally included thousands of unrelated files. This PR is rebased onto the current upstream master with one commit and 38 files: the BenchmarkAndOptimizerV11Port/ module plus its dedicated GitHub Actions workflow.

Features

• On-demand 120-second profiling through Mod Settings, exporting a per-system CSV (name, originating assembly/mod, calls, cumulative, average/min/max execution times).
• Frame/GC CSV including frame-time and FPS sampling, managed heap and GC counts; reports real frame cadence, not achieved simulation speed.
• Optional observational TimberPhysics timing (StepAll / Physics.Simulate), when available.
• Opt-in per-system update intervals (default 1/vanilla), persisted in optimizer-v11.json.
• Critical global simulation and dispatcher systems are excluded from throttling. Benchmark sessions temporarily disable configured intervals to measure unthrottled execution and restore them afterwards.
• Settings panel with mod/system names, filtering, protected-system indicators and the UI crash prevention fix (filter row visibility instead of rebuilding the tree).
• Startup system discovery with additional systems encountered during active benchmarks; not a promise of exhaustive discovery.

Compatibility and design

• Separate mod ID: BenchmarkAndOptimizerV11Port; dedicated .NET Standard 2.1 project and isolated test/build-time stubs.
• Manifest declares Timberborn 1.1, Harmony, eMka.ModSettings and TimberUi dependencies.
• Original U7 implementation and manifests unchanged.
• No EBR, BFR, Keystone, SuperCursor, terrain, GC tuning, gameplay patches, experimental save/load hooks, or startup guards.
• No performance win is claimed from this port itself; it is a diagnostic tool and optional interval controller. Interval >1 changes update frequency and can change behavior; users should test on disposable saves.
• The build workflow compiles and stages a ready-to-install ZIP artifact. Stub compilation is not proof of in-game API compatibility.

Testing / review checklist

• Clean fork branch based on current upstream master, no historical unrelated changes.
• Diff reviewed: one commit, 38 files, all confined to port and its workflow.
• Source/manifests checked for private real-name attribution; GitHub commit attributed to tharbad08.
• Reviewed upstream Agents.MD and original Benchmark & Optimizer author conventions; style cleanup committed as 3deafdeb.
• Updated clean-branch GitHub Actions build succeeded (run 38803735830); artifact ZIP inspected: DLL + manifest.
• Launch Timberborn 1.1 with required dependencies, enable the port with older Benchmark & Optimizer disabled.
• Verify startup and existing save loading without exceptions.
• Run complete benchmark; validate both system and frame/GC CSV timestamps, columns, totals, and file paths.
• Confirm default intervals = 1 and protected global systems cannot be throttled.
• Apply a safe noncritical interval, verify persistence and restoration after benchmarking and load/restart.
• Test settings search/filter repeatedly for UI crashes.
• Test modded systems loaded later and document any not discovered.
• Test with TimberPhysics installed and absent; investigate any 1.1 API mismatches in Player.log.

Known limitations

• Startup and benchmark discovery may miss systems loaded later or not exercised; Refresh detected systems refreshes the existing catalog, not a new scan.
• FPS metrics are not simulation throughput measurements.
• Modded interval controls may have game-specific safety side effects despite hard exclusions.
• In-game compatibility of this exact isolated branch has not yet been validated.

See BenchmarkAndOptimizerV11Port/README.md and TICK_SAFETY.md for details.

Author: tharbad08. Please leave as draft until game validation is complete.

Upstream comparison: datvm/TimberbornMods@master...tharbad08:TimberbornMods:pr/benchmark-optimizer-v11-clean

Pause-menu compatibility fix (2026-10-16)

• Corrected the mod repository lookup from BenchmarkAndOptimizerV11 to manifest ID BenchmarkAndOptimizerV11Port.
• Replaced the incorrect reflected rootElement lookup with the original author's direct publicized GameOptionsBox._root access; preserve external game field names when applying member style rules.
• Added duplicate-button protection and retained graceful failure logging.
• GitHub Actions run 38859797534 compiled successfully and uploaded an installable ZIP; game-side verification remains pending.

Timberborn 1.1 runtime API fix (2026-10-16)

• Player.log reported FieldAccessException at BenchmarkAndOptimizerV11.OptimizerMenuService.Load: direct access to the game-private GameOptionsBox._root prevented colony loading.
• Retain _root only as the exact external game field-name string, accessed via reflection with non-public binding flags; our own members follow Agents.MD and do not use underscore-prefixed fields.
• The compile-only GameOptionsBox stub now marks _root non-public so accidental direct access fails future builds.
• GitHub Actions run 38867544608 succeeded on commit faf95230, and ZIP integrity was checked. Pause menu still requires in-game verification.

Coexistence contract with TB Optimizer

Both mods are intended to run together. TB Optimizer (separate TBOptimizer assembly/mod ID/Harmony owner) retains stable fixes; Benchmark & Optimizer is the separate diagnostic profiler with opt-in intervals. During a benchmark, only B&O's interval throttles are suspended; all TB Optimizer fixes stay active. Shared targets include SingletonLifecycleService.UpdateSingletons (B&O profiling and TB Optimizer GC hook) and optional TimberPhysics execution (B&O timings with TB Optimizer catch-up logic). No conflict found in static source inspection, but live combined-stack profiling remains to be tested. Source review details added to BenchmarkAndOptimizerV11Port/README.md. Do not tell testers to disable TB Optimizer.

Optional load-order dependency

BenchmarkAndOptimizerV11Port/manifest.json now declares TBOptimizer in OptionalMods, not RequiredMods, so Timberborn loads stable fixes first when both are enabled, without making TB Optimizer necessary for standalone benchmarking. No reciprocal declaration in TB Optimizer. Manifest version follows the new build convention and is now 1.1.104. Validate the resolved order in Player.log when testing.

Build version convention correction

Manifest Version=1.1.104, project AssemblyVersion/FileVersion=1.1.104.0, GitHub Actions artifact name BenchmarkAndOptimizerV11Port_1.1.104. The shared project and TB Optimizer AGENTS guides now specify <game version>.<build number> with a build-number increment on every changed installable test/release binary. CI artifact from run 38868790897 was retrieved and ZIP integrity verified; in-game runtime validation is pending.

1.1.109 runtime crash fix (2026-10-18)

User's Player(20261018-020758).log confirms FieldAccessException from B&O OptimizerMenuService.Load() on direct GameOptionsBox._root access during colony startup. Version 1.1.108's publicized-reference/IgnoresAccessChecksTo strategy compiled but still failed on Unity Mono. Restored guarded reflection of the existing private game field, left local naming conventions intact, made compile-only _root non-public, and added a CI regression check to block direct access. Manifest/assembly/artifact all bumped to 1.1.109. Build passed, ZIP validated, but corrected 1.1.109 has not yet been tested inside the game. TB Optimizer 1.1.120 starts before B&O and is not implicated.