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.
| System | Priority | What it draws |
|---|---|---|
RenderSystem | 40 | Every entity's RenderableComponent, every level-map layer and every particle emitter, in one sorted list |
ParallaxRenderSystem | 105 | ParallaxComponent 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.
| Component | Size fields |
|---|---|
Rectangle2DComponent | width, height, cornerRadius |
Circle2DComponent | radius |
Capsule2DComponent | width, height; round at both ends of the longer side |
Polygon2DComponent | vertices, a list of Offsets closed back to the first |
Line2DComponent | start (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.
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.LevelLayersholds the usual values:background(-200),backgroundNear(-100),main(0) andforeground(100).zOrder: the order within a layer.layerId: the name the editor's layer panel groups by (mainby default). It does not change the order.visibleandlocked: 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:
batchShapesdraws runs of rectangles with square corners and circles in oneCanvas.drawVerticescall, 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.cullOffscreenskips 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'sbounds.
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.onRenderdraws in the entity's own space, andboundsOfgives the bounds that culling uses.TextRenderabledraws a line of text the same way. - On the screen: add a callback to
engine.rendering.overlayHooks(over the world) orbackgroundHooks(behind it). TheseRenderHookChains run in screen space, outside the camera transform, in ascendingorder.GameWidgetadds the world's own drawing at order 0 and the engine adds plugin overlays at 100.removetakes a hook out, andaddIfAbsentnever adds one twice. - After the renderables, in world space: give
RenderSystemextrapasses. ARenderPassruns inside the camera transform, in ascendingorder. The default list is oneComponentPainterPass(order 100), which draws components whose definition has a painter, such asjust_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:
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.statsdescribes the whole last frame:lastRenderMs,drawCalls,renderedObjects,culledObjects,batchedSpritesandpostProcessPasses. The defaultRenderSystemreports into it; one you make yourself counts only if you passstatsSink: engine.rendering.engine.world.getSystem<RenderSystem>()?.statsholdsdrawCalls,renderedObjects,culledObjectsandbatchedSpritesfor 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:
| Removed | Use instead |
|---|---|
engine.rendering.addRenderable, removeRenderable, renderables, useSpatialIndex and the other spatial-index and layer members | An entity with a RenderableComponent; cullOffscreen for culling |
engine.parallax, ParallaxSystem | ParallaxComponent and ParallaxRenderSystem |
onRenderOverlay, onRenderBackground | overlayHooks, backgroundHooks |