Skip to content

perf: Record macOS frame cadence for an idle overlay - #1478

Merged
omesser merged 3 commits into
mainfrom
perf/426-frame-cadence
Oct 10, 2026
Merged

omesser merged 3 commits into
mainfrom
perf/426-frame-cadence

Conversation

@omesser

@omesser omesser commented Oct 10, 2026

Copy link
Copy Markdown
Owner

Why

An idle overlay was supposed to show whether animation frames hold 60 fps and whether interpolation sits one Engine tick behind. This machine had no such sample. A release binary also never fed the bench, because process_log::init keeps stderr in process.log.

What changed

summarizeTimestamps turns frame timestamps into a histogram, a drop count, and an average fps. DROP_MS is the only 20 ms threshold, and the tests read that constant. The bench waits on process.log and copies it out before deleting the scratch home.

The idle minute is docs/research/macos-idle-frame-cadence.md. Consecutive callbacks averaged 1.6 fps, with 93 gaps over 20 ms, because a perched sprite does not ask for the next frame. One armed gap was over 20 ms. Still Engine ticks averaged 21.6 ms (46.4 Hz). Interpolation lag is empty, because the sprite never moved.

Walking, CPU load, riding a window, and a seam crossing were not run. Linux and Windows were not measured.

How to verify

node --test tests/frame-cadence.test.js covers the timestamp summary and the process-log prefix.

cargo test --workspace --all-targets passed (0 failed). node --test tests/*.test.js passed (603 tests, 0 failed).

The GUI sample is the research note. Rerun it with FIDGET_BENCH_GREEN_LIGHT=1 scripts/bench-frame-cadence-macos.sh idle --seconds 60 --bin target/release/fidget.

Notes

This does not close #426. Riding and a seam crossing need a drag. A still sprite cannot confirm the one-tick lag claim.

— Grok Build, on @omesser's behalf.

summarizeTimestamps turns frame times into a histogram, a drop count, and an average fps. The test places the over-threshold gap from DROP_MS.
Release process_log::init keeps stderr off the terminal, so the bench was stopping the app before a landed frame showed up. It now waits on process.log and copies the trace out before deleting the scratch home.
One perched minute on this Mac. The overlay does not stay at 60 fps while the sprite is still, and a still sprite has no interpolation lag to measure.

@omesser omesser left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Soft CLEARED

Tip: 62bfafd6

What changed

  • Frame summary: summarizeTimestamps turns timestamps into a histogram, a drop count and an average fps. DROP_MS is the one 20 ms threshold and the tests read it.
  • Release log: unwrapProcessLog strips the epoch prefix, and the bench harvests process.log into the run log before the scratch home is deleted. It waits on that file too, so a release run no longer kills the app before the trace lands.
  • Research note: one idle minute on a Mac, with a 1.6 fps callback rate explained by the loop stopping on a perched sprite.

What is wrong
Nothing blocking.

Soft-FIX
None.

Non-blocking

  • Bash glue: harvest_process_log and log_has have no test. They are macOS bench plumbing, and the research note is their live evidence.

Verified: node --test tests/frame-cadence.test.js passes 10 of 10, bash -n and shellcheck are clean, and the note's histogram counts add up to its 94 gaps and 93 drops. I did not rerun the Mac sample.

— Cursor agent (Architect), on @omesser's behalf.

@omesser
omesser merged commit bd37844 into main Oct 10, 2026
6 checks passed
@omesser
omesser deleted the perf/426-frame-cadence branch October 10, 2026 20:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

perf: Benchmark frame cadence and dropped frames (all platforms)

1 participant