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,
)
  • showFPS shows FPS: n in the top right corner, from engine.gameLoop.currentFPS. It updates about once a second and costs the rest of the widget nothing.
  • showDebug adds a Collider2DDebuggerSystem to 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 sets engine.rendering.debugMode, which prints the rendering figures (render time, draws, culled objects) in the top left corner. Both go away when showDebug turns off.
  • showTerminal enables 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:

KeyWhat it is
frameFixed steps run while the engine was running, since it was made.
deltaTimeThe dt of the last step: the fixed step times the time scale.
lastUpdateMsMilliseconds the last step's update tasks took together.
budgetRemainingMs, isOverBudgetThe last step measured against a 16.67 ms frame.
systemTimesMsMilliseconds per update task: input, ecs, and any you registered. Physics and particles are inside ecs.
schedulerengine.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, and systemTimesMs with each system's update time by type name, plus TransformHierarchy.
  • engine.physics.stats: bodyCount, awakeBodies, lastStepMs and the pure-Dart engine's broadphase counters. On native platforms, backend is box2d_v3, or dart_fallback when the Box2D library did not load; the web has no backend key. The key is for diagnostics: to branch on the backend, ask engine.physics.isNative.
  • engine.rendering.stats: lastRenderMs, drawCalls, renderedObjects, culledObjects, batchedSprites and postProcessPasses for the whole frame. world.getSystem<RenderSystem>()?.stats holds what the world's RenderSystem drew.
  • Live getters: engine.gameLoop.currentFPS and interpolation; engine.time.deltaTime, totalTime, timeScale and frameCount; engine.cache.isUsingMemoryFallback; and engine.assets.cacheStats for 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 seeLikely cause
A blank screen, nothing movesNo defaultSystems in EngineConfig, or engine.start() was not called.
EngineNotReadyErrorengine.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 showThe file is not listed under flutter: assets:, or the atlas image is not beside its JSON.
An animator never changes stateIt 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 moveParticleSystem was not added; it is not a default system.
UnknownComponentTypeException loading a levelThe package that defines the component was not given to EngineConfig(extensions: ...).
The player falls through a map on the first frameCall await LevelMaps.preload(world) after loading the scene.
Your system reads stale input or runs after physicsIts priority: character control belongs at SystemPriorities.playerControl (95).
No collider outlinesAdd a Collider2DDebuggerSystem to the world, or use GameWidget(showDebug: true).
Every timing reads 0A release build: see the note above.
No sound on the web until the first clickExpected: browsers keep audio silent until the player interacts.
This page as Markdown