Skip to content

Gizmos

The @shell/gizmos package provides 2D debug and editor visualization for the ECS world. It supports both immediate-mode (one-frame) drawing and retained-mode (persistent) components, drawn by the world’s renderer in the world at z 1000: above the usual scene content, under world content with a higher z and under the UI layer.


Add GizmoPlugin to the world:

import { GizmoPlugin } from '@shell/gizmos';
world.addPlugin(GizmoPlugin);

This registers the Gizmos resource (IoC key: 'gizmos'), five gizmo components, and GizmoClearSystem at Schedule.PreUpdate, which clears immediate-mode draw buffers. It has no renderer: a world without one records the commands.

The world’s renderer draws them. On Pixi that is GizmoPixiPlugin from @shell/gizmos-pixi (GizmoRenderSystem at Schedule.PreRender, through PixiJS Graphics), which Engine2D and the editor’s scene view bring, and which draws only in a world that has GizmoPlugin. A system of yours that draws gizmos in PreRender runs .before(GizmoDrawSet), the set a renderer draws them in. Both run in edit mode.


Draw one-frame shapes inside a system update. Commands are cleared automatically at PreUpdate.

.update(({ resources }) => {
const gizmos = resources.get('gizmos');
gizmos.line({ x: 0, y: 0 }, { x: 100, y: 0 }, { color: 0xff0000 });
gizmos.circle({ x: 200, y: 200 }, 50, { color: 0x00ff00, layer: 'physics' });
})

Attach gizmo components to entities for persistent visuals. Each component requires the canonical Transform component from @shell/transform.

import { GizmoCircle } from '@shell/gizmos';
import { Transform } from '@shell/transform';
commands.spawn(
Define.prefab()
.with(Transform, { x: 100, y: 100 })
.with(GizmoCircle, { radius: 50, color: 0xff0000 }),
);

Gizmos are organized into named layers with independent visibility and depth sorting.

const gizmos = resources.get('gizmos');
gizmos.setLayer('physics', { zIndex: 10 });
gizmos.setLayer('ai', { zIndex: 5, enabled: false });
gizmos.enableLayer('physics');
gizmos.disableLayer('ai');
gizmos.isLayerEnabled('physics'); // true

The 'default' layer exists at zIndex: 0 automatically. Any other layer exists once it is set, switched or drawn on. Draw calls to a disabled layer are discarded. Component gizmos on a disabled layer are skipped during rendering.

In the editor, View › Gizmos has a switch for each layer that the edit world or a game in play draws on, apart from the editor’s own editor:* layers. The engine’s layers have plain names (physics:colliders is Colliders, default is Default Layer); a game’s own layer is listed by its name. One switch is for both worlds at once, starts on, and is kept per browser.