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.
Drawing modes
Section titled “Drawing modes”Immediate mode
Section titled “Immediate 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' });})Retained mode
Section titled “Retained mode”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 }),);Layers
Section titled “Layers”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'); // trueThe '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.
Topics
Section titled “Topics”- Gizmos Resource — Immediate-mode drawing and layer management
- Gizmo Components — Retained-mode persistent gizmos