Gizmo Components

Retained-mode gizmos are ECS components that persist on entities and render every frame until the component is removed. Each component requires the canonical Transform component from @shell/transform to define its position.

---

Usage

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 }),
);

---

GizmoCircle

export const GizmoCircle = Define.component('gizmoCircle')
  .withSchema({
    radius: { type: StoreType.Float32, default: 16 },
    color: { type: StoreType.Int32, default: 0x00ff00 },
    alpha: { type: StoreType.Float32, default: 1 },
    width: { type: StoreType.Float32, default: 0 },
    layer: { type: StoreType.String, default: 'default' },
  })
  .serializable()
  .showInEditor();

Field	Type	Default	Description
radius	number	16	Circle radius
color	number	0x00ff00	Stroke color (hex)
alpha	number	1	Opacity (0-1)
width	number	0	Stroke width (0 uses gizmos.defaultLineWidth)
layer	string	'default'	Layer name for rendering and visibility

---

GizmoRect

export const GizmoRect = Define.component('gizmoRect')
  .withSchema({
    width: { type: StoreType.Float32, default: 32 },
    height: { type: StoreType.Float32, default: 32 },
    color: { type: StoreType.Int32, default: 0x00ff00 },
    alpha: { type: StoreType.Float32, default: 1 },
    strokeWidth: { type: StoreType.Float32, default: 0 },
    layer: { type: StoreType.String, default: 'default' },
  })
  .serializable()
  .showInEditor();

Field	Type	Default	Description
width	number	32	Rectangle width
height	number	32	Rectangle height
color	number	0x00ff00	Stroke color (hex)
alpha	number	1	Opacity (0-1)
strokeWidth	number	0	Stroke width (0 uses gizmos.defaultLineWidth)
layer	string	'default'	Layer name for rendering and visibility

The rectangle is centered on the entity’s Transform position.

---

GizmoLine

export const GizmoLine = Define.component('gizmoLine')
  .withSchema({
    toX: { type: StoreType.Float32, default: 50 },
    toY: { type: StoreType.Float32, default: 0 },
    color: { type: StoreType.Int32, default: 0x00ff00 },
    alpha: { type: StoreType.Float32, default: 1 },
    width: { type: StoreType.Float32, default: 0 },
    layer: { type: StoreType.String, default: 'default' },
  })
  .serializable()
  .showInEditor();

Field	Type	Default	Description
toX	number	50	End point offset from transform X
toY	number	0	End point offset from transform Y
color	number	0x00ff00	Stroke color (hex)
alpha	number	1	Opacity (0-1)
width	number	0	Stroke width (0 uses gizmos.defaultLineWidth)
layer	string	'default'	Layer name for rendering and visibility

The line starts at the entity’s Transform position and ends at Transform + (toX, toY).

---

GizmoArrow

export const GizmoArrow = Define.component('gizmoArrow')
  .withSchema({
    toX: { type: StoreType.Float32, default: 50 },
    toY: { type: StoreType.Float32, default: 0 },
    headLength: { type: StoreType.Float32, default: 10 },
    color: { type: StoreType.Int32, default: 0x00ff00 },
    alpha: { type: StoreType.Float32, default: 1 },
    width: { type: StoreType.Float32, default: 0 },
    layer: { type: StoreType.String, default: 'default' },
  })
  .serializable()
  .showInEditor();

Field	Type	Default	Description
toX	number	50	End point offset from transform X
toY	number	0	End point offset from transform Y
headLength	number	10	Length of the arrowhead
color	number	0x00ff00	Stroke color (hex)
alpha	number	1	Opacity (0-1)
width	number	0	Stroke width (0 uses gizmos.defaultLineWidth)
layer	string	'default'	Layer name for rendering and visibility

---

GizmoCross

export const GizmoCross = Define.component('gizmoCross')
  .withSchema({
    size: { type: StoreType.Float32, default: 8 },
    color: { type: StoreType.Int32, default: 0x00ff00 },
    alpha: { type: StoreType.Float32, default: 1 },
    width: { type: StoreType.Float32, default: 0 },
    layer: { type: StoreType.String, default: 'default' },
  })
  .serializable()
  .showInEditor();

Field	Type	Default	Description
size	number	8	Half-length of each cross arm
color	number	0x00ff00	Stroke color (hex)
alpha	number	1	Opacity (0-1)
width	number	0	Stroke width (0 uses gizmos.defaultLineWidth)
layer	string	'default'	Layer name for rendering and visibility

---

Notes

• All components are serializable and visible in the editor.
• All components require a Transform component from @shell/transform to define their position.
• Component defaults use green (0x00ff00). Immediate-mode defaults use white (0xffffff).
• Component gizmos on a disabled layer are skipped during rendering.