yoshida yoshida
Open the editor

Docs Format

Params

On this page

Params are the inputs a card can set. Each one has a name and a type. Layers read them by name in expressions and templates: {title}, level * 2, accent.

"params": {
  "scale":       { "type": "number",  "default": 2, "min": 0.5 },
  "level":       { "type": "integer", "default": 4, "min": 0, "max": 12 },
  "title":       { "type": "text",    "default": "Untitled", "max_length": 60 },
  "foil":        { "type": "bool",    "default": false },
  "accent":      { "type": "color",   "default": "#660940" },
  "card_type":   { "type": "enum",    "options": ["spell", "trap"], "default": "spell" },
  "art":         { "type": "image",   "required": true },
  "ingredients": { "type": "list", "item": { "amount": "text", "unit": "text", "name": "text" }, "default": [] }
}

Names

A param name follows the identifier rule [a-z_][a-z0-9_]* (lowercase letters, digits and underscores, not starting with a digit). It must not be a reserved word (canvas, render, card, true, false, and, or, not, in); that is error 1106. A function name is allowed: in an expression a bare name is a value, and only a name followed by ( calls a function.

NameValid?
title, c_start, tile_num, stat2, _tmpyes
tile_Num, Titleno: uppercase letters
2nd, tile-numno: starts with a digit, contains -

The same rule applies to the loop names in repeat (index, item), where a bad name is error 1103.

Params and layers live in separate namespaces, because layer references always start with @. A param called background and a layer called background can coexist.

Types

TypeValue in card dataNotes
numberJSON numberAny real number
integerJSON numberWhole numbers only
textJSON string
booltrue / false
colorhex string such as "#660940"#RRGGBB, #RRGGBBAA, or the 16-bit forms
enumone of optionsLiteral word, not an expression
imageproject path or https:// URLUsed in src templates and image functions (avg_color(art))
listarray of objectsItems described by item

Fields

FieldApplies toMeaning
typeallOne of the types above
defaultallLiteral value used when the card does not set it. A JSON literal, not an expression
requiredalltrue: the card must set it (error 2003). A required param has no default
label, noteallShown in the editor
groupallFree text naming the editor section the param belongs to, such as "Monster stats". Params with the same group are shown together in the editor's params list and card form, in order of first appearance; params without one come first. No effect on rendering
min, maxnumber, integerInclusive range (error 2002 when a card is outside it)
max_lengthtextMaximum characters (error 2002)
optionsenumNon-empty array of strings
itemlistObject of field name to field type: number, integer, text, bool, color, or { "type": ..., "options": [...], "default": ... } for enum fields and defaults. image and list fields are error 1103. See lists

A param with neither default nor required: true is error 1107.

When a card leaves out a param that has no default and is not required (which 1107 prevents), the value would be the type's zero value: 0, "", false, transparent, an empty list.

Lists

A list param holds several items, each with the same fields:

"stats": {
  "type": "list",
  "item": { "name": "text", "value": "number" },
  "default": []
}

In card data:

{ "id": "001", "stats": [ { "name": "Speed", "value": 8 }, { "name": "Power", "value": 3 } ] }

Item fields

A field is a type name, or an object with type, options (enum fields only) and default:

"tiles": {
  "type": "list",
  "item": {
    "kind": { "type": "enum", "options": ["plain", "safe", "skip"], "default": "plain" },
    "text": "text",
    "color": { "type": "color", "default": "#7FD1E8" }
  },
  "default": []
}
  • An enum field must have one of its options in every item: "kind": "shortcuts" in card data is error 2006 (item 1 field 'kind': 'shortcuts' is not one of plain, safe, skip), not a plain tile. In expressions it reads as text: t.kind == 'safe'. A typo in the expression itself (t.kind == 'saef') is not found.
  • A field an item leaves out takes the field's default; without one, the zero value of its type (0, "", false, #00000000), and an enum field its first option.
  • Item fields have no min, max or max_length.

Changing single items of the default

A card's list value replaces the default list. To change only some items, give an object of positions (0-based) instead of an array; the rest of the default stays:

{ "id": "variant", "tiles": { "11": { "kind": "safe", "text": "Rest stop" }, "20": { "kind": "skip" } } }

Each change sets only the fields it names. A position the default list does not have is error 2006, and so is an object for a list param without a default. In CSV the cell holds the same JSON object. The editor saves card edits this way when the default list has items and the card keeps their number.

You can use a list three ways:

  • Index: stats[0].value (0-based; an index out of range is error 3102 at render time).
  • Key: stats.Speed or stats["Speed"]. See List lookup by key.
  • Repeat: draw a layer once per item with "repeat": { "each": "stats", "item": "s" }, or use "count": "stats" (the number of items). See Repeat.

In CSV files a list cell holds a JSON array, see Card Data.

Sharing params and constants between designs

Designs of one game often have the same params (a title, a cost) and the same constants (a margin). Put them in a definitions file, any *.defs.json file in the project, and name it in import:

{
  "format": 1,
  "name": "Common",
  "params": { "title": { "type": "text", "default": "Untitled", "max_length": 40 } },
  "consts": { "pad": 24 }
}
{ "format": 1, "name": "Monster", "import": ["shared/common.defs.json"], "...": "..." }
  • params and consts of a definitions file work as if they were written at the top of the design, before its own. Their order is the order in the card form.
  • A design's own param or constant with the same name replaces the imported one (for example to change a default). With several imports, a later file replaces an earlier one.
  • A definitions file holds only format, name, note, params and consts. Its paths are relative to the project folder. A missing file is error 1201 and a path outside the project is 1203; a problem inside the file is reported against that file.
  • Constants in a definitions file can use params and the canvas size of the design that imports them.
  • Imported params are in card data like any other. The editor's params panel shows only the params written in the design file itself; edit the definitions file in the file browser or the JSON view.
  • A definitions file is not a set and is never rendered.

Image params

An image value is a path inside the project (assets/images/shiro.jpg) or an https:// URL. Use it in an image layer's src:

{ "id": "art", "type": "image", "src": "{art}", "box": { "x": 0, "y": 0, "w": 400, "h": "auto" } }

In the editor

The editor builds its card form from the params: a color picker for color, a dropdown for enum, a file picker for image, a table for list. The order of params in the file is the order of the form, within each group. See Builder: Params and Builder: Card data.

↑↓ to moveEnter to openEsc to close