Circinus

◆ Circinus ◆

Find out what your mods actually cost. Circinus records timestamped runs with tick rate, frame rate and frame timing, attributes cost to individual mods and individual Harmony patches, captures the errors your game throws while it loads, and keeps a history you can compare against later. It has its own profiler, its own test runner and its own benchmarks, so Harmony is the only thing it needs. The point is not another number on screen. The point is a number you can trust, which means the tool has to be willing to say when it does not know.

⚠ Accuracy Disclaimer

Circinus and circinus.sh publish measurements volunteered by real installs playing real mod lists. Every corpus figure is a field report, not a ranking, and any figure can be inaccurate for reasons that have nothing to do with the mod it is attached to. Broken load orders (missing dependencies, bad sorting, incompatible or wrong-version mods), save-specific workload (a mod whose work scales with pawn count legitimately measures higher in a big colony), hardware differences, and small sample sizes can all skew results. What the system does about it: runs the game itself reports broken are excluded from cost figures and counted as excluded; no mod is ranked or banded below 25 clean measured runs AND 10 independent installs; display names come from the mod's actual Workshop listing or a verified author claim — where neither exists the raw package id is shown, never a name derived from it; per-pawn-scaling costs are labelled as workload-dependent; and every refusal is printed on the page it affects. What no automation can do: replace independent testing. A controlled before/after comparison on your own machine — the run diff built into this tool — outranks any corpus figure about your specific situation. Never use a number from Circinus to harass, brigade or pile onto a mod author. If a figure looks wrong, report it: the site's contact page and author claim system exist so corrections reach the data, authors can reply publicly on their mod's page, and any author can have their figures withheld entirely, no questions asked.

✦ The Profiler

• Cost per mod and per patch: reported as a share of frame time.
• Arm what you want to watch: around 35 curated targets, a by mod view, and a free text method search. Nothing is instrumented until you ask for it.
• Selective by design: instrumenting every patch on a 900 mod list produced a frame that lasted 88 seconds. Per target arming exists so that never happens to you by accident.
• Baselines: pin the current costs, change something, then see exactly what moved.

✦ Run History

• Every session recorded: sampled roughly once a second, with tick rate against its target, frame rate, worst frame, heap and pawn count.
• Compare up to three runs side by side: best and worst are marked only when the runs are genuinely comparable, and the reason is shown when they are not.
• Survives a crash: runs are flushed periodically and saved on exit, then labelled as recovered. The session that ended badly is usually the one worth keeping.
• Warmup is excluded: samples inside the warmup window are kept but never counted, because they carry the one off cost of arming the profiler.

✦ Errors

• Startup and def loading: the errors that scroll past while your game loads, grouped by stack signature and counted. On a large mod list that is routinely a hundred distinct problems nobody has ever read.
• Attributed, not blamed: each class names the mods its stack frames point at which is where the error surfaced, not proof of what caused it.
• Copy to clipboard: one click gives you the message, the stack, the attribution, your game version, your mod count and your processor, ready to paste into a bug report.

✦ Benchmarks and Calibration

• Seven scenarios: pathfinding, region flooding, def lookup, stat evaluation, pawn generation and more, with configurable iteration counts and persistent baselines.
• A frozen hardware index: a single threaded benchmark scored in millions of iterations per second, taken as the best of five passes because every source of interference only ever makes a pass slower.
• Refuses bad comparisons: a different iteration count is a different experiment, so no delta is offered.

✦ What it refuses to tell you

A tool that answers everything confidently is a tool that is sometimes confidently wrong. These are deliberate:

• No ranking on thin data: below 25 clean measured runs AND 10 independent installs a mod reads as insufficient rather than taking a position. 25 runs from one machine is one anecdote repeated, not a ranking.
• No aggregating broken sessions: runs that logged an error storm, or where the game itself reported missing dependencies or incompatible mods active, are excluded from cost figures and shown as an explicit excluded count.
• No guessed names: a mod's page shows its real Workshop listing title (attested by multiple independent installs, or by a verified author claim) or the bare package id. A name derived from a package id is a guess, and guesses have mistitled mods before.
• No diff across a profiling mismatch: an observed run and an unobserved one are not measuring the same thing.
• No blame for induced cost: if one mod enlarges another's workload, the time lands on the second. Cost means time spent inside a mod's own code, never time a mod caused.
• No profiler reads as no data, never as zero cost, because otherwise a missing measurement looks like a performance win.

✦ Sharing, if you want to

Circinus asks once, on first load, with two buttons. Say no and nothing ever leaves your machine. Say yes and your finished runs go to circinus.sh, where you can compare your results against machines like yours and see which errors are common across other installs. The site is free, open and non commercial, with a versioned API anyone can read. Sent: timing samples, per mod and per patch costs, the package ids of your installed mods (plus, for Workshop mods, the mod's public Workshop item id, so its page can show the real listing title instead of a guess), four counts of load-order problems the game itself reported, and a coarsened hardware description. Never sent: file paths, your username, your save games, your colony or pawn names, and the names, versions or load order of your mods. Error text is reduced to a template before it leaves, so a message naming one of your colonists becomes a message naming nobody.

✦ Compatibility

• Harmony is the only dependency. No performance mod, no test framework, nothing else required.
• Safe alongside other profilers: Circinus never instruments its own patches, and discloses the ones it does add.
• Add it or remove it at any time. It stores nothing in your save.

✦ Open

The API is public and versioned, and everything the site shows is available through it.

Disclaimer

• Fully Tested: Every feature and line of code has been thoroughly tested in-game to ensure it functions as intended and integrates smoothly.
• Active Support: I am fully committed to maintaining this mod. If you encounter any bugs, compatibility issues, or unintended behavior, please report them in the comments or a dedicated discussion thread.
• No Abandonware: I will actively patch, refine, and update this mod to keep it working and up to standard.