Skip to content
Estella

Profiler

The StatsPlugin provides real-time performance monitoring with an on-screen overlay showing FPS, frame time, rendering stats, and per-system timings.

Enabling the Profiler

Add StatsPlugin in your script’s setup function:

import { StatsPlugin } from 'esengine';


export function setup(app) {
    app.addPlugin(new StatsPlugin());
}

Configuration

new StatsPlugin({
    overlay: true,                  // Show on-screen panel (default: true)
    position: 'top-left',          // 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
    container: document.body,       // DOM parent for the overlay
})
OptionTypeDefaultDescription
overlaybooleantrueShow the on-screen stats panel
positionstring'top-left'Overlay position on screen
containerHTMLElementdocument.bodyDOM parent for the overlay element

Metrics

The overlay displays:

Performance

  • FPS — frames per second, smoothed over a 60-frame window
  • Frame time — average milliseconds per frame

Rendering

  • Draw calls — number of draw calls per frame
  • Triangles — total triangle count
  • Sprites / Text / Spine / Meshes — rendered count per type
  • Culled — entities skipped by frustum culling

World

  • Entities — total entity count

Systems

  • Top 5 slowest systems with average and peak execution time in milliseconds (displayed as avg / max ms)
  • Stats are throttled to 500ms updates for stable readability without losing peak information

Reading Stats in Code

Access the Stats resource in your systems:

import { defineSystem, addSystem, Res, Stats } from 'esengine';


addSystem(defineSystem(
    [Res(Stats)],
    (stats) => {
        console.log(`FPS: ${stats.fps}`);
        console.log(`Draw calls: ${stats.drawCalls}`);
        console.log(`Entities: ${stats.entityCount}`);
    }
));

Frame History

FrameHistory is a utility class that maintains a rolling buffer for trend analysis. Create an instance and feed it data from the Stats resource:

import { FrameHistory, Stats, Res, defineSystem, addSystem } from 'esengine';


const history = new FrameHistory(300);


addSystem(defineSystem(
    [Res(Stats)],
    (stats) => {
        history.push(stats.frameTimeMs, new Map());
    }
));


// Get the most recent frame snapshot
const latest = history.getLatest();
if (latest) {
    console.log(`Frame time: ${latest.frameTimeMs}ms`);
}


// Get all recorded frames
const frames = history.getAll();

Editor Integration

The profiler panel is accessible from the editor toolbar. It provides:

  • Pause/resume stats collection
  • Per-frame inspection — step through individual frames to analyze spikes
  • System timing breakdown per frame