# API de scripting Lua de pxstud.io — Grupos de opciones

> Parte de la referencia de scripting Lua de pxstud.io, cuya introducción (https://pxstud.io/es/docs/scripting.md) explica sus convenciones. Los grupos de opciones y los tipos a los que remite están en https://pxstud.io/es/docs/scripting/option-groups.md y https://pxstud.io/es/docs/scripting/types.md. Todo en un solo archivo (en inglés): https://pxstud.io/llms-full.txt. El índice de todo el sitio (en inglés): https://pxstud.io/llms.txt.

## Grupos de opciones
Conjuntos de opciones compartidos por varias funciones, definidos una sola vez aquí. La tabla `opts` de una función indica qué grupos admite además: "también acepta Opciones de pintura" significa que se acepta cada opción de abajo, con el mismo significado y los mismos valores predeterminados, además de las propias de la función.

### Opciones de pintura (`paint`)
Las toman todos los comandos que pintan píxeles (las funciones de dibujo y las herramientas de trazo). Todas son opcionales. Por omisión, un comando de dibujo ignora la selección y no refleja, sea lo que sea que muestre el editor en ese momento; actívalo con respectSelection = true y symmetry = app.getContext().symmetry (o una lista de ejes). tilemapMode se rellena a partir del contexto de edición.
Lo admiten: `app.blur`, `app.dodgeBurn`, `app.drawContour`, `app.drawCurve`, `app.drawEllipse`, `app.drawGradient`, `app.drawHexagon`, `app.drawIsoShape`, `app.drawLine`, `app.drawPolygon`, `app.drawRectangle`, `app.drawStar`, `app.drawStroke`, `app.drawTriangle`, `app.floodFill`, `app.jumble`, `app.scatter`, `app.spray`.

  - `respectSelection` (boolean; predeterminado false) — Pasa true para pintar solo dentro de la selección actual (léela con app.getSelection / app.isSelected). Por omisión se ignora la selección.
  - `symmetry` (lista de SymmetryAxis: "horizontal" | "vertical" | "diagonal" | "antidiagonal"; predeterminado none) — Ejes de reflejo que pasan por el centro del lienzo (o por symmetryX / symmetryY); las combinaciones (horizontal + vertical) dan simetría en 4 direcciones. Por omisión ninguno: pasa symmetry = app.getContext().symmetry para seguir el interruptor de simetría del editor, o una lista de ejes como { "vertical" }.
  - `symmetryX` (number ≥ 0; predeterminado the canvas center (width / 2)) — Dónde está el eje vertical (y el punto en que se cruzan ambas diagonales): píxeles desde el borde izquierdo del lienzo, un múltiplo de 0.5 (entero = entre píxeles, x.5 = por el centro de un píxel). Se limita al lienzo. Pasa app.getContext().symmetryX para seguir la guía del editor (nil ahí significa centrado).
  - `symmetryY` (number ≥ 0; predeterminado the canvas center (height / 2)) — Dónde está el eje horizontal (y el cruce de las diagonales): píxeles desde el borde superior del lienzo, un múltiplo de 0.5. Se limita al lienzo.
  - `tilemapMode` (TilemapEditMode: "pixels-edit" | "pixels-auto"; predeterminado context.tilemapMode) — Cómo recibe la pintura de píxeles una capa de tilemap: auto da a cada celda pintada su propio tile, edit cambia el tile compartido en su lugar. Se ignora en las capas de imagen.

### Opciones de colocación (`tilePlace`)
Todas son opcionales. Por omisión, los tiles van en cada celda indicada, sea lo que sea que muestre el editor. Las celdas reflejadas reciben el tile reflejado: un eje vertical alterna flipH, uno horizontal alterna flipV, uno diagonal lo transpone (rotate90 más un volteo). Una celda sobre un eje conserva el tile tal como se colocó.
Lo admiten: `app.fillTiles`, `app.stampTiles`.

  - `respectSelection` (boolean; predeterminado false) — Pasa true para omitir las celdas sin ningún píxel seleccionado (un relleno también se detiene en ellas).
  - `symmetry` (lista de SymmetryAxis: "horizontal" | "vertical" | "diagonal" | "antidiagonal"; predeterminado none) — Coloca también en las celdas reflejadas respecto a estos ejes (y sus combinaciones). Pasa app.getContext().symmetry para seguir el interruptor del editor.
  - `symmetryX` (number ≥ 0; predeterminado the canvas center (width / 2)) — Dónde está el eje vertical, en píxeles desde el borde izquierdo del lienzo (un múltiplo de 0.5).
  - `symmetryY` (number ≥ 0; predeterminado the canvas center (height / 2)) — Dónde está el eje horizontal, en píxeles desde el borde superior del lienzo (un múltiplo de 0.5).

### Opciones de pincel (`brush`)
Las toman las herramientas de trazo (drawStroke, blur, jumble). Pasa un pincel integrado por tamaño y forma, o un pincel personalizado por nombre o en línea.
Lo admiten: `app.blur`, `app.dodgeBurn`, `app.drawStroke`, `app.jumble`, `app.scatter`.

  - `brushSize` (integer 1–64; predeterminado context.brushSize) — Tamaño del pincel en píxeles.
  - `brushShape` (BrushShape: "circle" | "square" | "line" | "diamond" | "cross" | "x" | "star" | "horizontal"; predeterminado context.brushShape) — Forma del pincel. Para un pincel personalizado usa `brush`.
  - `brushAngle` (integer 0–180; predeterminado context.brushAngle) — Ángulo del pincel en grados: inclina la forma "line" (0 = horizontal, 90 = vertical) y rota "square".
  - `brush` (brush name, or an inline { rows } / { width, height, mask }) — Un pincel personalizado: el nombre de uno que definiste con app.defineBrush, o una definición en línea. Reemplaza a brushSize, brushShape y brushAngle.

### Opciones de tinta (`ink`)
Las toman todos los comandos de pintura excepto erase: cómo se combina el color de pintura con los píxeles que ya hay. Las opciones omitidas vienen del contexto de edición (ink, shades). Con ink = "shading" se ignora el color y cada píxel tocado cuyo color está en `shades` avanza un paso por esa lista (una vez por comando, sin importar cuántas veces lo cubra la forma).
Lo admiten: `app.drawContour`, `app.drawCurve`, `app.drawEllipse`, `app.drawGradient`, `app.drawHexagon`, `app.drawIsoShape`, `app.drawLine`, `app.drawPolygon`, `app.drawRectangle`, `app.drawStar`, `app.drawStroke`, `app.drawTriangle`, `app.floodFill`, `app.scatter`, `app.spray`.

  - `ink` (Ink: "copy" | "simple" | "lock-alpha" | "shading"; predeterminado context.ink) — copy reemplaza los píxeles, simple compone el alfa, lock-alpha recolorea solo los píxeles visibles, shading avanza los colores por `shades`. Lo ignora erase.
  - `shades` (a list of colors ("#rrggbb[aa]" or { r, g, b, a }), in ramp order; predeterminado context.shades) — La rampa por la que avanza shading. Un píxel cuyo color no está en la lista no se toca; un píxel al final de la lista se queda ahí.
  - `shadeReverse` (boolean; predeterminado false) — Shading retrocede por `shades` (el botón derecho del mouse en la interfaz) en lugar de avanzar.