Gizmos Resource

The Gizmos resource provides immediate-mode drawing. Commands are pushed into per-layer buffers during a system update and rendered automatically. They are cleared at PreUpdate every frame, so each draw call lasts exactly one frame.

Accessing the resource

The resource is bound to IoC key 'gizmos' when GizmoPlugin is registered.

.update(({ resources }) => {
  const gizmos = resources.get('gizmos');
  gizmos.circle({ x: 0, y: 0 }, 10);
})

Draw methods

Method	Signature	Notes
`line`	`(from: Vec2, to: Vec2, options?: DrawOptions)`	Line segment
`circle`	`(center: Vec2, radius: number, options?: DrawOptions)`	Circle outline
`rect`	`(position: Vec2, size: { width, height }, options?: DrawOptions)`	Centered rectangle outline
`arrow`	`(from: Vec2, to: Vec2, options?: ArrowOptions)`	Line with arrowhead
`cross`	`(center: Vec2, size: number, options?: DrawOptions)`	Plus/cross marker
`lineStrip`	`(points: Vec2[], options?: LineStripOptions)`	Connected segments (min 2 points)

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' });
gizmos.rect({ x: 50, y: 50 }, { width: 100, height: 60 });
gizmos.arrow({ x: 0, y: 0 }, { x: 80, y: 0 }, { headLength: 12 });
gizmos.cross({ x: 100, y: 100 }, 8);
gizmos.lineStrip(
  [
    { x: 0, y: 0 },
    { x: 10, y: 20 },
    { x: 30, y: 5 },
  ],
  { closed: true },
);

Draw options

type Vec2 = { x: number; y: number };

type DrawOptions = {
  color?: number; // hex, default: 0xffffff (white)
  alpha?: number; // 0-1, default: 1
  width?: number; // stroke width, default: 0 (uses Gizmos.defaultLineWidth)
  layer?: string; // default: 'default'
};

type ArrowOptions = DrawOptions & {
  headLength?: number; // default: 10
};

type LineStripOptions = DrawOptions & {
  closed?: boolean; // default: false
};

Resource properties

Property	Type	Default	Description
`enabled`	`boolean`	`true`	Master toggle. When `false`, no gizmos are drawn.
`defaultLineWidth`	`number`	`2`	Stroke width when a draw call passes `width: 0`.
`defaultAlpha`	`number`	`1`	Multiplied with per-call alpha.

Layer management

Method	Signature	Notes
`setLayer`	`(name: string, config: GizmoLayerConfig)`	Create or update layer config
`enableLayer`	`(name: string)`	Set `enabled = true` (creates on demand)
`disableLayer`	`(name: string)`	Set `enabled = false` (creates on demand)
`isLayerEnabled`	`(name: string): boolean`	Returns `false` for unknown layers

type GizmoLayerConfig = {
  zIndex?: number; // render order, higher = on top
  enabled?: boolean; // visibility toggle
};

Gotchas

Immediate-mode calls are one-frame only — they’re cleared at PreUpdate.
A draw call width: 0 means “use Gizmos.defaultLineWidth”, not zero-width stroke.
Gizmos render in a container at zIndex: 1000 on the PixiJS stage, so they always appear on top of normal scene content.
Immediate-mode defaults use white (0xffffff). Retained-mode component defaults use green (0x00ff00).