Authoring Layouts Canvas

Authoring Layouts — Canvas

A canvas is a layout element that lets you position children at absolute coordinates rather than letting the layout engine arrange them automatically. Use it when you need pixel-perfect overlay control — such as overlaying badges on a map, drawing decorative artwork at specific positions, or recreating a hand-designed UI that doesn't fit any of the automatic layouts.

See Authoring Layouts for the file format and base fields. This page only covers fields specific to the canvas type.

JSON schema

Parsed in EmoTracker.Data/Layout/CanvasPanel.cs. Matches the canvas branch in layouts.json.

Field	Type	Required	Default	Description
type	"canvas"	yes	—	Literal string.
content	array	no	empty	The children to position on the canvas. Each child should set canvas_left / canvas_top (and optionally canvas_depth).

Plus the standard base fields from Authoring Layouts → Fields every layout element shares.

How children position themselves

Canvas children read three positioning fields from the layout-element base, which only have an effect when the parent is a Canvas:

Field	Description
canvas_left	The X coordinate of the child's top-left corner, in canvas-local pixel units.
canvas_top	The Y coordinate of the child's top-left corner.
canvas_depth	Z-order. Higher values draw on top of lower ones. Defaults to declaration order if unset.

The canvas itself sizes to whatever its parent allocates — typically you'll give it explicit width and height to make the coordinate system stable, otherwise children may end up positioned relative to a moving target.

Examples

Two icons at fixed positions

{
  "type": "canvas",
  "width": 400,
  "height": 200,
  "content": [
    {
      "type": "image",
      "image": "images/sword_icon.png",
      "canvas_left": 50,
      "canvas_top": 30,
      "width": 32,
      "height": 32
    },
    {
      "type": "image",
      "image": "images/shield_icon.png",
      "canvas_left": 100,
      "canvas_top": 30,
      "width": 32,
      "height": 32
    }
  ]
}

Layered art with explicit z-order

{
  "type": "canvas",
  "width": 256,
  "height": 256,
  "content": [
    {
      "type": "image",
      "image": "images/background.png",
      "canvas_left": 0,
      "canvas_top": 0,
      "canvas_depth": 0
    },
    {
      "type": "image",
      "image": "images/foreground.png",
      "canvas_left": 0,
      "canvas_top": 0,
      "canvas_depth": 10
    }
  ]
}

The foreground image is drawn on top because its canvas_depth is higher.

Tips and pitfalls

• Always set width and height on the canvas itself. Without them the canvas's size is determined by its parent — which means your canvas_left / canvas_top coordinates become meaningless when the parent area changes.
• Coordinates are in pack-authored units, not screen pixels. They scale with whatever sizing the runtime applies to the canvas. Author them as if the canvas is its declared size and they'll scale uniformly.
• Children without canvas_left / canvas_top end up at (0, 0). That's typically not what you want — set both fields explicitly on every child.
• For lists, prefer Array or Item Grid. Canvas should be reserved for cases where automatic layout genuinely can't express what you need.
• For docking to edges, prefer Dock. Canvas is overkill for "left-bar + center area + right-bar" arrangements.

See also

• Authoring Layouts — top-level format and base fields
• Authoring Layouts — Container — for stacking children at the same position without absolute coordinates
• Authoring Layouts — Dock — for edge-pinned arrangements
• layouts.json schema — authoritative JSON schema