Flutter & shipping
Debugging & stats
Read the engine's performance and per-subsystem stats, switch on the debug overlay and the developer terminal, and fix the most common problems.
Every stat the engine keeps can be read at run time, without external tools, and all of them are cheap enough to read every frame. GameWidget adds an FPS badge, a debug overlay and a developer terminal on top.
The debug overlay
GameWidget(
engine: engine,
showFPS: true, // the default
showDebug: kDebugMode,
showTerminal: kDebugMode,
)showFPSshowsFPS: nin the top right corner, fromengine.gameLoop.currentFPS. It updates about once a second and costs the rest of the widget nothing.showDebugadds aCollider2DDebuggerSystemto the world, which outlines every 2-D collider as simulated (coloured by body kind) and every 2-D character through the main camera. It also setsengine.rendering.debugMode, which prints the rendering figures (render time, draws, culled objects) in the top left corner. Both go away whenshowDebugturns off.showTerminalenables the developer terminal (below).
Physics2DSystem draws nothing: collider outlines come only from a Collider2DDebuggerSystem in the world. Without showDebug, add one yourself, engine.world.addSystem(Collider2DDebuggerSystem(camera: engine.camera.mainCamera)), and narrow it with outlineFilter; a collider's own showDebugOutline has the last word. Remove it with engine.world.removeSystem(...) to hide them again.
The developer terminal
With showTerminal: true, the backquote key opens a command console over the game. While it is open, the keyboard goes to the terminal, not the game. It has help and clear built in; register your own commands on engine.terminal:
void addDebugCommands(Engine engine) {
engine.terminal.registerCommand(
name: 'stats',
description: 'Show entity counts and the last update time.',
handler: (args) {
final world = engine.world.stats;
final perf = engine.performanceStats;
return 'entities ${world['activeEntities']}/${world['totalEntities']}, '
'update ${perf['lastUpdateMs']} ms';
},
);
engine.terminal.registerCommand(
name: 'timescale',
description: 'Set the time scale. Usage: timescale <value>',
handler: (args) {
final value = args.isEmpty ? null : double.tryParse(args.first);
if (value == null || value < 0) return 'Usage: timescale <value>';
engine.time.timeScale = value;
return 'time scale $value';
},
);
}A handler gets the words after the command name and returns a line to print, or null to print nothing. A command name is one word; registering a name again replaces its handler.
Engine stats
engine.performanceStats is safe to read in any state. It covers the last fixed step:
| Key | What it is |
|---|---|
frame | Fixed steps run while the engine was running, since it was made. |
deltaTime | The dt of the last step: the fixed step times the time scale. |
lastUpdateMs | Milliseconds the last step's update tasks took together. |
budgetRemainingMs, isOverBudget | The last step measured against a 16.67 ms frame. |
systemTimesMs | Milliseconds per update task: input, ecs, and any you registered. Physics and particles are inside ecs. |
scheduler | engine.systemManager.schedulerStats: task count and timings. |
The subsystems' own figures exist only between initialize() and dispose(); check engine.isInitialized first when that can happen.
engine.world.stats:totalEntities,activeEntities,systems,activeSystems,archetypes(a number that keeps growing points to component churn),lastUpdateMs,lastCommandFlushes, andsystemTimesMswith each system's update time by type name, plusTransformHierarchy.engine.physics.stats:bodyCount,awakeBodies,lastStepMsand the pure-Dart engine's broadphase counters. On native platforms,backendisbox2d_v3, ordart_fallbackwhen the Box2D library did not load; the web has nobackendkey. The key is for diagnostics: to branch on the backend, askengine.physics.isNative.engine.rendering.stats:lastRenderMs,drawCalls,renderedObjects,culledObjects,batchedSpritesandpostProcessPassesfor the whole frame.world.getSystem<RenderSystem>()?.statsholds what the world'sRenderSystemdrew.- Live getters:
engine.gameLoop.currentFPSandinterpolation;engine.time.deltaTime,totalTime,timeScaleandframeCount;engine.cache.isUsingMemoryFallback; andengine.assets.cacheStatsfor loaded assets and their estimated memory.
One map with every subsystem's figures, to log or send to telemetry:
Map<String, dynamic> snapshot(Engine engine) => {
...engine.performanceStats,
if (engine.isInitialized) ...{
'fps': engine.gameLoop.currentFPS,
'ecs': engine.world.stats,
'physics': engine.physics.stats,
'rendering': engine.rendering.stats,
'cacheInMemory': engine.cache.isUsingMemoryFallback,
},
'assets': engine.assets.cacheStats,
};The overlay shows no update or physics timings; draw your own from these maps, for example from lastUpdateMs, systemTimesMs and physics.stats['lastStepMs'].
When something does not work
| What you see | Likely cause |
|---|---|
| A blank screen, nothing moves | No defaultSystems in EngineConfig, or engine.start() was not called. |
EngineNotReadyError | engine.world or another subsystem was used before await engine.initialize(), or after dispose(). |
StateError from start() | The engine is not initialized, or already running. |
| Things appear in the wrong place | +Y is down, and the camera's position is the world point in the middle of the screen. |
| A sprite does not show | The file is not listed under flutter: assets:, or the atlas image is not beside its JSON. |
| An animator never changes state | It needs a SpriteAnimationComponent on the same entity. A parameter whose binding is not registered in engine.context.animatorBindings silently keeps its default. |
| Particles do not move | ParticleSystem was not added; it is not a default system. |
UnknownComponentTypeException loading a level | The package that defines the component was not given to EngineConfig(extensions: ...). |
| The player falls through a map on the first frame | Call await LevelMaps.preload(world) after loading the scene. |
| Your system reads stale input or runs after physics | Its priority: character control belongs at SystemPriorities.playerControl (95). |
| No collider outlines | Add a Collider2DDebuggerSystem to the world, or use GameWidget(showDebug: true). |
| Every timing reads 0 | A release build: see the note above. |
| No sound on the web until the first click | Expected: browsers keep audio silent until the player interacts. |