Konfigurationsformulare

Ein Skript kann ein kleines Formular deklarieren, das vor dem Ausführen angezeigt wird. Was im Formular eingetragen wird, kommt als Tabelle app.config an, geordnet nach der ID jedes Felds. Felder sind reine Daten – ein Skript beschreibt nie eine Oberfläche – und der Editor stellt sie dar und validiert sie. Farben, Pinsel und Paletten sind der Weg, wie ein Skript etwas aus deinen eigenen Sachen erfragt: Die Engine liest nie deine Bibliotheken, ein Skript bekommt also genau das, was du auswählst.

• number — Eine Zahleneingabe. In Lua: number. Optionen: default (Der Startwert.); min (Der kleinste erlaubte Wert.); max (Der größte erlaubte Wert.); optional (Erlaubt, das Feld leer zu lassen.); randomMin / randomMax (Der Bereich, aus dem Zufall würfelt, innerhalb von min..max (Standard min..max; ohne beide Grenzen lässt Zufall den Wert in Ruhe). Ganze Zahlen, wenn die Grenzen und der Standardwert ganze Zahlen sind.); randomize (false behält den Wert, wenn das Formular zufällig befüllt wird.).
• text — Eine Textzeile. In Lua: string. Optionen: default (Der Starttext.); optional (Erlaubt, das Feld leer zu lassen.).
• checkbox — Ein Ein/Aus-Schalter. In Lua: boolean. Optionen: default (Ob das Feld anfangs angehakt ist.); randomize (false behält den Wert, wenn das Formular zufällig befüllt wird.).
• select — Eine Auswahl aus einer festen Liste. In Lua: string (der Wert der gewählten Option). Optionen: options (Die Auswahlmöglichkeiten, jeweils { value, label }.); default (Der Wert, der anfangs ausgewählt ist.); randomize (false behält die Auswahl, wenn das Formular zufällig befüllt wird.).
• color — Eine Farbe, gewählt mit der Farbauswahl des Editors – die Palette des Sprites und die zuletzt verwendeten Farben sind mit einem Klick erreichbar. Gib jeder Rolle ihr eigenes Feld (Blatt hell, Blatt dunkel, Rinde ...), dann wählt man sie alle aus. In Lua: string, "#rrggbb" (oder "#rrggbbaa" mit Alpha) – wird überall direkt akzeptiert, wo eine Farbe hingehört. Optionen: default (Die Startfarbe, "#rrggbb" oder "#rrggbbaa" (Schwarz, wenn weggelassen).); randomize (true lässt Zufall auch eine Farbe wählen (der Alphawert bleibt erhalten). Standardmäßig aus: Die Farben der meisten Skripte sind fein abgestimmt.).
• brush — Einer der gespeicherten Pinsel, ausgewählt aus der Pinselbibliothek. In Lua: Tabelle { name, width, height, mask } – übergib sie an app.defineBrush; fehlt, wenn optional und leer gelassen. Optionen: optional (Erlaubt, das Feld leer zu lassen (dann ist app.config.<id> nil).).
• palette — Eine der gespeicherten Paletten, ausgewählt aus der Palettenbibliothek. In Lua: Liste von Strings "#rrggbb" (oder "#rrggbbaa") – übergib sie an app.setPalette oder wähle per Farbrechnung daraus aus; fehlt, wenn optional und leer gelassen. Optionen: optional (Erlaubt, das Feld leer zu lassen (dann ist app.config.<id> nil).).

Beispielformular (JSON) und das Skript, das es verwendet:

{
  "fields": [
    {
      "id": "leafLight",
      "type": "color",
      "label": "Leaf (light)",
      "default": "#6cc24a"
    },
    {
      "id": "leafMid",
      "type": "color",
      "label": "Leaf (mid)",
      "default": "#3a8f4a"
    },
    {
      "id": "leafDark",
      "type": "color",
      "label": "Leaf (dark)",
      "default": "#23603a"
    },
    {
      "id": "barkLight",
      "type": "color",
      "label": "Bark (light)",
      "default": "#8a5a35"
    },
    {
      "id": "barkDark",
      "type": "color",
      "label": "Bark (dark)",
      "default": "#5a3a22"
    },
    {
      "id": "stamp",
      "type": "brush",
      "label": "Leaf brush",
      "optional": true
    }
  ]
}

local layer, frame = app.getActiveLayerId(), app.getActiveFrameId()
local c = app.config

-- trunk: two bark colors the user chose
app.drawRectangle(layer, frame, 14, 20, 17, 31, { color = c.barkDark, fill = "filled" })
app.drawRectangle(layer, frame, 14, 20, 15, 31, { color = c.barkLight, fill = "filled" })

-- canopy: three leaf colors, with the user's own brush if they picked one
if c.stamp then app.defineBrush("leaf", c.stamp) end
for i, color in ipairs({ c.leafDark, c.leafMid, c.leafLight }) do
  app.drawStroke(layer, frame, { { 8, 18 - i * 4 }, { 24, 18 - i * 4 } },
    { color = color, brush = c.stamp and "leaf" or nil, brushSize = 4 })
end

Verzweigung

Jedes Feld kann ein when tragen – { "<earlier field id>": [values] } – und wird dann nur angezeigt, solange jedes genannte select einen dieser Optionswerte hat (oder jede checkbox true/false ist) und selbst angezeigt wird. Bedingungen schauen nur auf frühere selects und checkboxes, sodass sie sich beliebig tief verketten lassen: Schalte die Wurzel um, und ihr ganzer Zweig verschwindet. Ein verborgenes Feld fehlt in app.config, das Skript fällt also auf seinen eigenen Standardwert zurück – lies jedes Feld als optional.

{
  "fields": [
    {
      "id": "kind",
      "type": "select",
      "label": "Kind",
      "options": [
        {
          "value": "broadleaf",
          "label": "Broadleaf"
        },
        {
          "value": "conifer",
          "label": "Conifer"
        }
      ],
      "default": "broadleaf"
    },
    {
      "id": "crown",
      "type": "select",
      "label": "Crown",
      "options": [
        {
          "value": "round",
          "label": "Round"
        },
        {
          "value": "weeping",
          "label": "Weeping"
        }
      ],
      "when": {
        "kind": [
          "broadleaf"
        ]
      }
    },
    {
      "id": "droop",
      "type": "number",
      "label": "Droop",
      "min": 0,
      "max": 100,
      "randomMin": 20,
      "randomMax": 80,
      "when": {
        "crown": [
          "weeping"
        ]
      }
    },
    {
      "id": "tiers",
      "type": "number",
      "label": "Tiers",
      "min": 2,
      "max": 12,
      "when": {
        "kind": [
          "conifer"
        ]
      }
    },
    {
      "id": "newLayer",
      "type": "checkbox",
      "label": "Draw on a new layer",
      "randomize": false
    }
  ]
}

Zufall

Jedes Formular bekommt eine Schaltfläche Zufall. Sie würfelt jede Zahl innerhalb von randomMin..randomMax (Standard min..max; eine Zahl ohne beide Grenzen bleibt erhalten), wählt eine beliebige select-Option und schaltet Checkboxen um; Farben werden nur mit randomize: true gewürfelt, und Text, Pinsel und Paletten bleiben immer unberührt. Setz randomMin/randomMax auf den Bereich, der noch gut aussieht, und randomize: false bei Einstellungen, die nicht zur Kunst gehören (neue Ebene, Auswahl beachten ...).

Als Markdown: config-forms.md.