yoshida yoshida
Open the editor

Docs Format Layers

Layer: group

On this page

A group holds other layers and draws them as one picture, so they can be organised, moved, hidden, faded and rotated together.

{
  "id": "badge",
  "type": "group",
  "opacity": 0.9,
  "rotate": -8,
  "layers": [
    { "id": "badge_bg", "type": "ellipse", "box": { "x": 820, "y": 60, "w": 120, "h": 120 }, "fill": "accent" },
    { "id": "badge_text", "type": "text", "text": "{level}", "anchor": "center",
      "at": { "x": "@badge_bg.bounds.cx", "y": "@badge_bg.bounds.cy" } }
  ]
}
FieldKindDefaultMeaning
layersarray of layersrequired (error 1102)Drawn in array order inside the group, first is bottom. Groups may contain groups
translate{ x, y }, number{ 0, 0 }The group's origin: everything inside moves by it, and coordinates inside are relative to it. See translate
repeatobjectnoneDraw the layers inside once per iteration, as one unit. See repeat
id, note, visible, opacity, rotate, effectsAs in Layers, applied to the group's picture (per iteration in a repeated group)

How it works

  • A group has no position or size of its own. @group.bounds.* is the union of the bounds of its visible layers, including all repeat iterations. An empty or fully hidden group has zero bounds at the origin. @group.opacity, @group.visible and @group.rotate can be referenced too.
  • The layers inside are drawn into a separate picture. Then the group's effects (relative to the group's bounds, so fade and crop work on the group's edges), opacity and rotate (around the centre of the bounds) are applied, and the picture is composited at the group's place in the stack.
  • Layers inside a group are ordinary layers: ids are unique across the whole design (error 1108), they can be referenced from anywhere, and they can use repeat and extends.
  • A group itself cannot have anchor or extends (error 1101). Nesting deeper than 16 levels is error 5001.
  • A hidden layer (visible: false) is not drawn, but it can still be referenced with @ and used as an extends base, inside a group or not. A hidden group's layers can be referenced too.
  • Diagnostics inside a group use nested pointers, such as /layers/2/layers/0/box/x.

Translate

Without translate, coordinates inside a group are canvas coordinates. With it, they are relative to the group's origin:

{ "id": "badge", "type": "group", "translate": { "x": 820, "y": 60 }, "layers": [
  { "id": "badge_bg", "type": "ellipse", "box": { "x": 0, "y": 0, "w": 120, "h": 120 }, "fill": "accent" },
  { "id": "badge_text", "type": "text", "text": "{level}", "anchor": "center",
    "at": { "x": "@badge_bg.bounds.cx", "y": "@badge_bg.bounds.cy" } }
] }
  • Moving the badge means changing only the translate. Translates of nested groups add up.
  • @layer positions (bounds.*, box.x, box.y, at.x, at.y) are given in the frame of the layer that reads them: inside the group, @badge_bg.bounds.cx is 60; outside it, 880. So references work the same everywhere.
  • %, vw and vh stay relative to the canvas size.
  • translate.x and translate.y are expressions; they can use params, constants, the group's own loop names and layers outside the group. A layer inside the group is a cycle (error 3004).

Repeat

A group can repeat: the layers inside are drawn once per iteration, as one unit, and every layer inside can use the group's loop names. With translate, each iteration gets its own origin:

{ "id": "tile", "type": "group",
  "repeat": { "each": "tiles", "item": "t", "index": "i" },
  "translate": { "x": "tile_x(i)", "y": "tile_y(i)" },
  "layers": [
    { "id": "tile_bg", "type": "rect", "box": { "x": 6, "y": 6, "w": 158, "h": 158 }, "fill": "t.kind == 'safe' ? c_safe : c_plain" },
    { "id": "tile_text", "type": "text", "text": "{t.text}", "anchor": "center",
      "at": { "x": "@tile_bg.bounds.cx", "y": "@tile_bg.bounds.cy + 30" } }
  ] }
  • References between layers inside the same repeated group mean the same iteration: in the example, each text is centred on its own tile.
  • From outside, pick an iteration with an index: @tile_bg[3].bounds.cx is the background of tile 4, @tile[3].bounds the whole tile. See Repeat.
  • visible, opacity and rotate of the group can use the loop names, so single iterations can be hidden.
  • The group counts as one layer per visible iteration toward the layer limit, plus its visible layers.

The board game example draws its 40 tiles this way.

Layout: rows and columns

layout places the group's children one after another, measured by their bounds, so a row of text and icons grows and shrinks with the text. The children's own positions are replaced; only their sizes count. Hidden children take no room, and every iteration of a repeated child is one item.

{
  "id": "cost", "type": "group",
  "layout": { "direction": "row", "gap": 8, "x": "50%", "y": 900, "align": "center", "cross": "center" },
  "layers": [
    { "id": "label", "type": "text", "text": "{name}", "at": { "x": 0, "y": 0 }, "size": 28 },
    { "id": "coin", "type": "image", "src": "icons/gold.png", "repeat": { "count": "cost" }, "box": { "x": 0, "y": 0, "w": 28, "h": 28 } }
  ]
}
FieldDefaultMeaning
directionrowrow (left to right) or column (top to bottom)
gap0Space between children
x, y0Where the line goes, in the group's coordinates (after translate)
alignstartAlong the line: start puts its first child at x (row) or y (column), center centres it there, end ends it there
crossstartAcross the line: start puts every child's top (row) or left (column) at y (x), center centres it, end puts its bottom (right) there

align and cross may be expressions that give one of the words, as with anchor.

A shared background for adjacent items is a layer that reads the group's bounds, for example a rect before the group with "box": { "x": "@cost.bounds.left - 12", "w": "@cost.bounds.w + 24", ... }. A child can be a group, which moves as a whole; every iteration of a repeated group is one item, so a row of chips can be one repeated group (or one included component) inside a layout group.

Shared components (include)

Layers that several designs share, such as an effect row, can live in one component file. A group takes them with include instead of layers:

{ "id": "effects", "type": "group", "include": "components/effect-row.json", "translate": { "x": 40, "y": 820 } }

components/effect-row.json:

{
  "format": 1,
  "name": "Effect row",
  "layers": [
    { "id": "effect_bg", "type": "rect", "box": { "x": 0, "y": 0, "w": 670, "h": 90 }, "radius": 12, "fill": "#EEE6D8" },
    { "id": "effect_text", "type": "text", "markup": true, "text": "{effect}", "at": { "x": 16, "y": 16 }, "wrap": 638 }
  ]
}
  • The path is from the project folder. Any name works; *.component.json keeps them apart from designs, and schema/component.schema.json checks them in an editor.
  • The layers are compiled as part of the design that includes them: they use that design's params, constants, functions, fonts and icons, and the design's layers can reference them (@effect_bg.bounds.bottom) and extends them. Every design that includes the component needs the params it uses.
  • The group works like any group: translate, layout, visible, repeat and effects apply to the included layers. Components can include other components (a cycle is error 3004).
  • Ids must be unique in the design, so a second include of the same component is error 1108 unless it has an id_prefix (below). To show one component several times with different params, repeat the group instead.
  • Problems inside a component name the component file and its line.

Including a component twice (id_prefix)

id_prefix puts text in front of the id of every layer the component brings, so the same component can be included more than once:

{ "id": "left_pill", "type": "group", "include": "components/pill.component.json", "id_prefix": "l_" },
{ "id": "right_pill", "type": "group", "include": "components/pill.component.json", "id_prefix": "r_",
  "translate": { "x": 300, "y": 0 } }

With the component of the example above, the layers are l_effect_bg and r_effect_bg. The design refers to them by the new ids (@l_effect_bg.bounds.bottom).

  • The prefix is lowercase letters, digits and _, starting with a letter or _; anything else is error 1103. It applies to groups with include only (error 1101 elsewhere).
  • Inside the component, @id references to the component's own layers and its extends follow the new ids, so the component keeps working. A reference to the design's params, constants and other layers is not changed. References are renamed by matching @ and the exact id, in every string of the component.
  • Components the component includes get the prefix too; if they have an id_prefix of their own, the two are joined (outer first). A reference from the outer component to a layer of an included component is not renamed.
  • Params are not passed per include: both copies use the design's params. To vary them, give the second include a different translate and use a repeat with item, or make a second component.
  • In the builder, a group becomes a component with Create component, and a component's layers are edited in place; see Builder: Layers. Live values are not shown for fields inside a component yet.

Moving a group

In the editor, moving a group with a translate changes the translate; moving a group without one moves every layer in it. Group a set of layers with Ctrl+G (the group takes the place of the topmost selected layer and keeps the order) and ungroup with Ctrl+Shift+G. See Builder: Layers.

Known limits

In the editor, layers inside a rotated group show unrotated selection boxes on the canvas, and groups have no resize handles (their size comes from their layers). Layers inside a repeated group are outlined once per iteration. See Known Gaps.

Layers in a group in the editor Layers in a group in the editor

↑↓ to moveEnter to openEsc to close