Skip to content

feat: System tick performance metrics#870

Open
Doglightning wants to merge 1 commit intomainfrom
Anthony/tick-performance
Open

feat: System tick performance metrics#870
Doglightning wants to merge 1 commit intomainfrom
Anthony/tick-performance

Conversation

@Doglightning
Copy link
Contributor

@Doglightning Doglightning commented Feb 14, 2026

https://www.loom.com/share/bd3c9f6293ad488b83d2b9fce3d8d9a4

TL;DR

Added performance monitoring and profiling capabilities to Cardinal's debug module to track system execution times and tick performance.

What changed?

This PR adds comprehensive performance monitoring to Cardinal's debug module:

  1. Added a new performance package with:
    • Ring buffer data structures for storing tick timing samples and system execution spans
    • Statistics collection for tick durations, overruns, and system-level execution times
    • Freshness tracking to monitor tick recency
  2. Enhanced the ECS scheduler to:
    • Track execution time of individual systems
    • Pass tick timestamps through the execution chain
    • Support optional performance callbacks for instrumentation
  3. Added new debug service endpoints:
    • PerfOverview - Returns aggregated tick timing statistics (avg, p95, max durations)
    • PerfSchedule - Returns detailed per-system execution spans for visualizing the tick timeline
  4. Modified the World's tick flow to:
    • Record tick start/end times
    • Track system execution spans
    • Maintain performance metrics with minimal overhead when debug mode is disabled

How to test?

  1. Enable debug mode when creating a Cardinal world
  2. Use the debug service endpoints to query performance data:
    • Call PerfOverview with a window of 10, 60, or 300 seconds to get tick timing statistics
    • Call PerfSchedule with a window of 10 or 60 seconds to get system execution spans
  3. Observe the performance metrics in high-load scenarios to identify bottlenecks

Why make this change?

Performance monitoring is critical for game development to:

  1. Identify systems that are taking too long to execute
  2. Detect when ticks are exceeding their time budget (overruns)
  3. Visualize the execution timeline to optimize system scheduling
  4. Provide developers with insights to maintain consistent tick rates
  5. Help diagnose performance issues in production environments

This change enables developers to profile their Cardinal worlds with minimal overhead, making it easier to build performant games that maintain consistent frame rates.

Copy link
Contributor Author

Doglightning commented Feb 14, 2026


How to use the Graphite Merge Queue

Add the label graphite/merge to this PR to add it to the merge queue.

You must have a Graphite account in order to use the merge queue. Sign up using this link.

An organization admin has enabled the Graphite Merge Queue in this repository.

Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.

This stack of pull requests is managed by Graphite. Learn more about stacking.

This was referenced Feb 14, 2026
@Doglightning Doglightning marked this pull request as ready for review February 14, 2026 02:29
@rmrt1n rmrt1n changed the base branch from ryan/debugger to graphite-base/870 February 15, 2026 17:29
@rmrt1n rmrt1n mentioned this pull request Feb 15, 2026
@rmrt1n rmrt1n requested a review from smsunarto February 17, 2026 15:15
@Doglightning Doglightning force-pushed the Anthony/tick-performance branch from d41d0b0 to 787c431 Compare February 18, 2026 15:37
@Doglightning Doglightning changed the base branch from graphite-base/870 to ryan/debugger February 18, 2026 15:37
@Doglightning Doglightning requested a review from rmrt1n February 18, 2026 15:50
@rmrt1n
Copy link
Contributor

rmrt1n commented Feb 22, 2026

Here's an amp thread I used to help w my review if you're interested. It's a bit unstructured though.

Base automatically changed from ryan/debugger to main February 23, 2026 07:31
@Doglightning Doglightning force-pushed the Anthony/tick-performance branch from 787c431 to 4ab389a Compare February 25, 2026 18:17
@Doglightning Doglightning force-pushed the Anthony/tick-performance branch from 4ab389a to bc62f47 Compare February 25, 2026 18:27
@Doglightning Doglightning requested a review from rmrt1n February 25, 2026 19:00
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.

2 participants