Graphics

Rendering & layers

How the engine draws your world: the render system, draw order, self-drawing shapes, culling, render hooks and passes, parallax backgrounds and render stats.

Everything a 2D game shows is drawn by one ECS system, RenderSystem, inside the GameWidget that hosts your engine. You describe what to draw with components; the system sorts it and draws it through the camera once per display frame.

What the rendering systems do

EngineConfig(defaultSystems: DefaultSystems.all) includes DefaultSystem.rendering, which adds two systems. Both draw through engine.camera.mainCamera.

SystemPriorityWhat it draws
RenderSystem40Every entity's RenderableComponent, every level-map layer and every particle emitter, in one sorted list
ParallaxRenderSystem105ParallaxComponent backgrounds, behind the world

DefaultSystems.headless leaves both out, for servers and tests. Around them, engine.rendering (a RenderingEngine) owns the frame: the background colour (backgroundColor), render hooks, post-processing and frame stats.

Drawing happens once per display frame, between the fixed 60 Hz updates. Moving physics bodies, and their children, are drawn between their last two poses so they stay smooth on a 120 Hz screen; everything else is drawn where it is. See The engine for the loop.

Shapes that draw themselves

Five components draw themselves, centred on their entity's TransformComponent. Lines and polygons take points relative to it.

ComponentSize fields
Rectangle2DComponentwidth, height, cornerRadius
Circle2DComponentradius
Capsule2DComponentwidth, height; round at both ends of the longer side
Polygon2DComponentvertices, a list of Offsets closed back to the first
Line2DComponentstart (the entity's position by default), end, roundCaps

Each has a fillStyle and a strokeStyle (a line has only the stroke), filled, and a strokeWidth in world units. By default a shape is filled white with a translucent white outline one unit wide. The outline is drawn whenever its style is not fully transparent, so pass strokeStyle: const ShapePaintStyle(color: Colors.transparent) to remove it.

A ShapePaintStyle is a color plus an optional gradient. With a gradient, the colour tints it through blendMode (BlendMode.modulate by default, so the default white leaves it as it is). ShapeGradient.linear runs from begin to end, ShapeGradient.radial spreads from center out to radius (a fraction of the shape's shorter side), and ShapeGradient.sweep turns round center. All three take colors and optional stops.

lib/scenery.dart
import 'package:flutter/material.dart';
import 'package:just_game_engine/just_game_engine.dart';

void addScenery(World world) {
  // Far behind everything: a gradient sky with no outline.
  world.createEntityWithComponents([
    TransformComponent(position: Vector3(0, -150, 0)),
    Rectangle2DComponent(
      width: 2400,
      height: 700,
      fillStyle: const ShapePaintStyle(
        gradient: ShapeGradient.linear(
          colors: [Color(0xFF14213D), Color(0xFF5B7DB1)],
          begin: Alignment.topCenter,
          end: Alignment.bottomCenter,
        ),
      ),
      strokeStyle: const ShapePaintStyle(color: Colors.transparent),
    ),
    LayerComponent(layer: LevelLayers.background),
  ], name: 'Sky');

  // The main layer, drawn after main-layer entities with a lower zOrder.
  world.createEntityWithComponents([
    TransformComponent(position: Vector3(0, 140, 0)),
    Capsule2DComponent(
      width: 32,
      height: 72,
      fillStyle: const ShapePaintStyle(
        gradient: ShapeGradient.radial(colors: [Colors.white, Colors.teal]),
      ),
    ),
    LayerComponent(zOrder: 10),
  ], name: 'Hero');

  // In front of everything: an outlined triangle.
  world.createEntityWithComponents([
    TransformComponent(position: Vector3(220, 120, 0)),
    Polygon2DComponent(
      vertices: const [Offset(0, -30), Offset(26, 15), Offset(-26, 15)],
      filled: false,
      strokeStyle: const ShapePaintStyle(color: Colors.amber),
      strokeWidth: 2,
    ),
    LayerComponent(layer: LevelLayers.foreground),
  ], name: 'Warning');
}

/// Shapes are stored as RenderableComponent: read them back by that type.
void highlight(Entity entity) {
  final shape = entity.getComponent<RenderableComponent>();
  if (shape is Rectangle2DComponent) shape.strokeWidth = 6;
  shape?.renderable.tint = Colors.yellow;
}

Every field is read when the shape draws, so change width, radius or a style at any time and the next frame shows it. To find a shape later, keep the component you created, or ask for RenderableComponent and check its type, as highlight does: getComponent<Circle2DComponent>() finds nothing. The renderable inside also has opacity, tint and visible, which effects such as FadeEffect animate (see Particles, effects & post-processing).

Draw order and layers

RenderSystem sorts by layer, then by zOrder; lower values draw first, further back. Entities with equal keys keep the order they were found in, so they never swap from one frame to the next. Give an entity a LayerComponent to place it:

  • layer: the coarse order. LevelLayers holds the usual values: background (-200), backgroundNear (-100), main (0) and foreground (100).
  • zOrder: the order within a layer.
  • layerId: the name the editor's layer panel groups by (main by default). It does not change the order.
  • visible and locked: used by the editor only; the game ignores them.
  • mapLayer: on a child of a level map, draws the entity among that map layer's tiles. See Level maps.

An entity without a LayerComponent sorts by its renderable's own layer and zOrder, which are 0 for the built-in shapes. For a top-down game, set ySort on a renderable: it then draws after the rest of its layer and zOrder, ordered by world y, so whatever stands lower on screen is drawn in front.

Batching and culling

Sprites batch on their own: consecutive sprites from one image, drawn at one uniform positive scale, go into a single Canvas.drawRawAtlas call. A mirrored or stretched sprite draws by itself, and a batch is flushed whenever the draw order key changes, so batching never changes the order.

RenderSystem has two more switches, both off by default. Set them on the default one, for example engine.world.getSystem<RenderSystem>()?.batchShapes = true:

  • batchShapes draws runs of rectangles with square corners and circles in one Canvas.drawVertices call, when their fill and outline are plain colours and the entity is fully opaque, untinted and has no shader. Edges are not anti-aliased and a circle becomes a 16- or 24-sided polygon, so use it for many small shapes: bullets, debris, blockouts.
  • cullOffscreen skips renderables whose bounds lie wholly outside the view. Level-map layers and particle emitters are always drawn, and it is only as good as each renderable's bounds.

For large levels, ViewCullingSystem also stops simulating what is far away. Add it yourself with world.addSystem(ViewCullingSystem(camera: engine.camera.mainCamera)); only entities you give a CullStateComponent take part, so don't give one to the player. Outside the render area (1.2 times the view by default) an entity's renderable is hidden. Outside the active area (2 times the view) its CullStateComponent.isActive turns false and MovementSystem and Physics2DSystem skip it; check the same flag in your own systems, such as AI. A hysteresisMargin (24 units) stops entities on the edge from flickering.

Drawing your own things

There are three ways in, depending on where the drawing belongs:

  • In the world, sorted with everything else: put a RenderableComponent(renderable: CustomRenderable(onRender: ...)) on an entity. onRender draws in the entity's own space, and boundsOf gives the bounds that culling uses. TextRenderable draws a line of text the same way.
  • On the screen: add a callback to engine.rendering.overlayHooks (over the world) or backgroundHooks (behind it). These RenderHookChains run in screen space, outside the camera transform, in ascending order. GameWidget adds the world's own drawing at order 0 and the engine adds plugin overlays at 100. remove takes a hook out, and addIfAbsent never adds one twice.
  • After the renderables, in world space: give RenderSystem extra passes. A RenderPass runs inside the camera transform, in ascending order. The default list is one ComponentPainterPass (order 100), which draws components whose definition has a painter, such as just_ui_editor's world-space text; keep it in your own list.

The default RenderSystem is made during initialize(), so a game that wants custom passes leaves rendering out of the default set and adds its own:

lib/axes.dart
import 'package:flutter/material.dart';
import 'package:just_game_engine/just_game_engine.dart';

/// Draws the world's x and y axes, inside the camera transform.
class AxesPass extends RenderPass {
  final Paint _paint = Paint()..color = const Color(0x55FFFFFF);

  // Before ComponentPainterPass, which runs at 100.
  @override
  int get order => 50;

  @override
  void render(Canvas canvas, RenderContext context, RenderPassFilter filter) {
    final view = context.camera?.visibleBounds;
    if (view == null) return;
    canvas
      ..drawLine(Offset(view.left, 0), Offset(view.right, 0), _paint)
      ..drawLine(Offset(0, view.top), Offset(0, view.bottom), _paint);
  }
}

Future<Engine> startWithAxes() async {
  final engine = Engine(
    config: EngineConfig(
      // Everything but rendering, which this game sets up itself.
      defaultSystems: DefaultSystems.all.difference({DefaultSystem.rendering}),
    ),
  );
  await engine.initialize();
  engine.world.addSystem(
    RenderSystem(
      camera: engine.camera.mainCamera,
      statsSink: engine.rendering,
      // What moves in a 2-D material (a wave, a shine) reads this clock.
      clock: () => engine.time.totalTime,
      passes: [ComponentPainterPass(), AxesPass()],
    ),
  );
  // Adds ParallaxRenderSystem; the RenderSystem above is kept.
  registerDefaultSystems(
    engine.world,
    engine,
    include: {DefaultSystem.rendering},
  );

  // A crosshair in screen space, over the world (which draws at order 0).
  engine.rendering.overlayHooks.add((canvas, size) {
    final c = size.center(Offset.zero);
    final paint = Paint()..color = Colors.white;
    canvas
      ..drawLine(c - const Offset(8, 0), c + const Offset(8, 0), paint)
      ..drawLine(c - const Offset(0, 8), c + const Offset(0, 8), paint);
  }, order: 50);
  return engine;
}

Parallax backgrounds

A ParallaxComponent holds a ParallaxBackground: a list of ParallaxLayers from back to front. ParallaxRenderSystem scrolls it against the camera and draws it in screen space, behind the world. Several backgrounds are ordered by their entity's LayerComponent.

Each layer takes a decoded image. scrollFactorX and scrollFactorY say how far it moves with the camera, from 0 (fixed, like a sky) to 1 (with the world), 0.5 by default; ParallaxLayer.uniform takes one scrollFactor for both. velocityX and velocityY auto-scroll it in pixels per second, for drifting clouds, and it also takes a scale, offset, opacity, tint, and repeat (tile to fill the view, on by default). Parallax backgrounds are not saved in scenes, so add them in code:

import 'package:just_game_engine/just_game_engine.dart';

Future<void> addBackground(Engine engine) async {
  final assets = engine.assets;
  final sky = (await assets.loadImage('assets/backgrounds/sky.png')).image!;
  final hills = (await assets.loadImage('assets/backgrounds/hills.png')).image!;
  engine.world.createEntityWithComponents([
    ParallaxComponent(
      background: ParallaxBackground(
        layers: [
          ParallaxLayer(image: sky, scrollFactorX: 0, scrollFactorY: 0),
          ParallaxLayer(image: hills, scrollFactorX: 0.3, scrollFactorY: 0.1),
        ],
      ),
    ),
  ], name: 'Background');
}

Render stats

  • engine.rendering.stats describes the whole last frame: lastRenderMs, drawCalls, renderedObjects, culledObjects, batchedSprites and postProcessPasses. The default RenderSystem reports into it; one you make yourself counts only if you pass statsSink: engine.rendering.
  • engine.world.getSystem<RenderSystem>()?.stats holds drawCalls, renderedObjects, culledObjects and batchedSprites for the world alone, without the extra passes' drawing. In tests, RenderSystem.debugDrawOrder() lists the draw order.
  • Debugging covers the on-screen tools.

The removed legacy path

Adding renderables to the rendering engine directly, as 1.x games did, is gone in 2.0:

RemovedUse instead
engine.rendering.addRenderable, removeRenderable, renderables, useSpatialIndex and the other spatial-index and layer membersAn entity with a RenderableComponent; cullOffscreen for culling
engine.parallax, ParallaxSystemParallaxComponent and ParallaxRenderSystem
onRenderOverlay, onRenderBackgroundoverlayHooks, backgroundHooks
This page as Markdown