# Guía de scripting

Escribe scripts en Lua que dibujan y editan tus sprites, ejecuta scripts y generadores de la biblioteca, y añade tus propias ventanas y comandos de menú.

_Los atajos están escritos para Windows y Linux. En un Mac, usa ⌘ Cmd donde dice Ctrl y ⌥ Option donde dice Alt._

Los scripts son programas en Lua que trabajan sobre el sprite abierto. Usan el mismo motor que el editor:
cada herramienta, capa, fotograma, celda, etiqueta, slice, tile y entrada de paleta que puedes cambiar a mano, un script
puede cambiarlo con código. Úsalos para generar arte (árboles, rocas, texturas, campos de estrellas), para repetir
una edición tediosa o para añadir tus propios comandos a los menús.

¿Nuevo en el scripting? [Tu primer script](https://pxstud.io/es/docs/scripting/first-script.md) te guía para escribir y ejecutar
uno. Esta página cubre todo lo que lo rodea.

## El menú Scripts

| Elemento | Qué hace |
| - | - |
| Scripts > Nuevo script... | Pone nombre a un script nuevo y lo abre en el panel Scripts. |
| Scripts > Abrir mi script... | Lista tus scripts: elige uno para abrirlo, o renómbralo o elimínalo. Los últimos cinco que abriste aparecen en el menú debajo de él. |
| Scripts > Explorar la biblioteca de scripts... | La biblioteca de scripts: busca, ejecuta, bifurca y marca con corazón scripts compartidos, incluidos los generadores oficiales. Consulta [La biblioteca](https://pxstud.io/es/docs/manual/guides/library.md). |
| Scripts > Comandos de scripts... | Instala comandos de menú a partir de tus scripts ([más abajo](https://pxstud.io/es/docs/scripting/guide.md#script-commands)). |
| Scripts > API de scripting | Abre la referencia de la [API de scripting](https://pxstud.io/es/docs/scripting.md) en una pestaña nueva. |

Todos ellos están también en la paleta de comandos (`Ctrl+K`).

## El panel Scripts

El panel **Scripts** se abre cuando creas o abres un script (en las disposiciones predeterminadas, acoplado a
la derecha del lienzo, para que puedas ver cómo dibuja un script; en un teléfono, delante de él).
Ver > Paneles > Scripts lo muestra y lo oculta, y al recargar se vuelve a abrir el script que tenías abierto (su
último borrador guardado). Tiene un editor de código con resaltado de Lua, sugerencias para cada función de `app.`
mientras escribes y una descripción cuando apuntas a una. Debajo del código, un área de salida
muestra lo que imprime el script y cualquier error.

![El panel Scripts mostrando el código de un script, con su barra de herramientas arriba y su salida impresa debajo](https://pxstud.io/scripting/images/first-script-panel.light.webp)

_El panel Scripts_

A lo largo de la parte superior, de izquierda a derecha:

- **El nombre del script.** Haz doble clic para renombrar el script. Un `*` significa que hay cambios sin
  guardar; a su lado, "draft" para un script que no has publicado, o la versión que estás editando
  ("v2", "v2 · edited").
- **Privado** o **Compartido**: quién puede ver el script en la biblioteca. Haz clic para cambiarlo.
- **Referencia de la API de scripts** (el libro) abre la referencia en una pestaña nueva.
- **Ejecutar** (el botón de reproducir) ejecuta el script en el sprite activo; un script con un
  [formulario de configuración](https://pxstud.io/es/docs/scripting/guide.md#config-forms) pide antes sus valores. Mientras se ejecuta, los controles de ejecución ocupan su
  lugar ([más abajo](https://pxstud.io/es/docs/scripting/guide.md#running-pausing-and-stopping)).
- **Guardar borrador** (el disco) guarda el script en este navegador.
- **Publicar** pide una nota de versión opcional, luego guarda el script y lo publica como una nueva
  versión.
- **Ajustes del script** (los controles deslizantes) abre los ajustes del script: sus etiquetas, quién puede verlo, su formulario de
  configuración y sus versiones publicadas.
- **Ocultar panel** cierra el panel. El script abierto sigue listado en el menú Archivo, con los
  sprites: elige ahí su nombre para volver a mostrar el panel.

El script de otra persona (abierto con **Ver código** en la biblioteca) es de solo lectura. Su barra de herramientas tiene
**Bifurcar** en lugar de Guardar borrador y Publicar: copia el script en un script nuevo tuyo para editarlo.

## Ejecutar, pausar y detener

Un script se ejecuta en el sprite que estás mirando, y lo ves dibujar sobre la marcha. Por mucho que
cambie, una ejecución es **un solo paso de deshacer**: `Ctrl+Z` revierte toda la ejecución.

Los scripts **no tienen límite de tiempo**. Mientras uno se ejecuta, sus controles de ejecución te permiten terminarlo antes:

| Control | Qué hace |
| - | - |
| **Pausar** / **Reanudar** | Detiene el script donde está, incluso en medio de un bucle, y continúa más tarde. |
| **Detener** | Termina el script y conserva lo que ha hecho hasta ese momento. |
| **Detener y revertir** | Termina el script y deshace todo lo que cambió. |

En el panel Scripts son botones pequeños de la barra de herramientas. Un script ejecutado desde la biblioteca
cubre el editor con una ventana que muestra su nombre, su salida y los mismos tres controles, hasta que
termina.

Cuando un script falla, la salida muestra el error; en el panel, la línea en la que falló se
resalta. Un script no puede pintar en una capa bloqueada: el comando se rechaza y el script se detiene
con un error.

## Escribir scripts

Cada función está en la tabla `app`. La [API de scripting](https://pxstud.io/es/docs/scripting.md) documenta cada una,
generada a partir del propio editor, en secciones:

- [Drawing](https://pxstud.io/es/docs/scripting/drawing.md): las herramientas como comandos (`app.drawLine`, `app.floodFill`,
  `app.drawIsoShape`...), [Images](https://pxstud.io/es/docs/scripting/images.md) para trabajar píxel a píxel, y
  [Pixels](https://pxstud.io/es/docs/scripting/pixels.md) para listas planas de píxeles, rellenos y el cuentagotas;
- [Document](https://pxstud.io/es/docs/scripting/document.md), [Layers](https://pxstud.io/es/docs/scripting/layers.md),
  [Frames](https://pxstud.io/es/docs/scripting/frames.md), [Cels](https://pxstud.io/es/docs/scripting/cels.md),
  [Selection](https://pxstud.io/es/docs/scripting/selection.md), [Slices](https://pxstud.io/es/docs/scripting/slices.md) y
  [Tilemaps](https://pxstud.io/es/docs/scripting/tilemaps.md);
- [Palette](https://pxstud.io/es/docs/scripting/palette.md), [Adjustments](https://pxstud.io/es/docs/scripting/adjustments.md) y
  [Brushes](https://pxstud.io/es/docs/scripting/brushes.md);
- ayudas: matemáticas de [Color](https://pxstud.io/es/docs/scripting/color.md), números [Random](https://pxstud.io/es/docs/scripting/random.md) con semilla,
  y el [Editing context](https://pxstud.io/es/docs/scripting/context.md) (los colores, el pincel y las opciones de herramienta actuales).

Algunas cosas que conviene saber:

- **Empieza con `print(app.describe())`.** `app.describe()` devuelve la estructura completa del sprite:
  capas, fotogramas, celdas, etiquetas, slices, la selección y los ajustes actuales.
- **Los ajustes que omites vienen del editor.** Un comando de dibujo sin color usa el color de
  primer plano; sin pincel, el pincel actual; y así con cada opción de herramienta.
- **La selección y la simetría se aplican solo cuando las pides.** Pasa `respectSelection = true` para seguir
  pintando dentro de la selección, y `symmetry = app.getContext().symmetry` para reflejarla.
- **Trabaja píxel a píxel en una Image.** `app.getImage(layer, frame)` lee una celda en una Image que
  vive dentro del script; `img:getPixel` e `img:setPixel` son baratos, así que recorre tantos píxeles
  como quieras y luego escríbela de vuelta una sola vez con `app.putImage(layer, frame, img)`. Cada llamada a `app.*`
  es un viaje al editor; los métodos de una Image no. En sprites indexados, `img:getIndex` e
  `img:setIndex` trabajan con índices de la paleta.
- **Usa `app.random` para la aleatoriedad.** Un generador creado con `app.random.new(seed)` da los mismos
  números para la misma semilla, así que una ejecución se puede repetir exactamente. `pairs()` también recorre las claves de una tabla en
  el mismo orden en cada ejecución.
- **Usa `app.color` para las matemáticas de color.** Las mezclas, rampas y tonos se calculan en un espacio
  de color perceptual, que se ve mejor que promediar valores hexadecimales.
- **Imprime para comprobar cosas.** `print(...)` escribe en el área de salida; las tablas se imprimen completas.

Por ejemplo, este script reparte estrellas en una capa nueva; cambia la semilla para obtener otro cielo:

```lua
local layer = app.addLayer("Stars")
local frame = app.getActiveFrameId()

local rng = app.random.new(42)                        -- same seed, same stars
local colors = app.color.ramp({ "#5a6b9e", "#ffffff" }, 4)

local img = app.getImage(layer, frame)                -- the layer's pixels, inside the script
for i = 1, img.width * img.height // 40 do
  img:setPixel(rng:int(0, img.width - 1), rng:int(0, img.height - 1), rng:pick(colors))
end
app.putImage(layer, frame, img)                       -- written back as one change
```

## Formularios de configuración

Un script puede pedir ajustes antes de ejecutarse: cuando eliges **Ejecutar** (en la biblioteca o en el
panel Scripts), se abre un formulario con sus campos (números, texto, casillas, opciones, colores, y un pincel o una paleta
de tus propias bibliotecas), y el script lee lo que escribiste como la tabla `app.config`. Los campos
pueden mostrarse u ocultarse según las elecciones anteriores. **Aleatorio** genera valores nuevos dentro de los rangos
que eligió la persona autora del script, para variaciones rápidas. Todos los generadores oficiales funcionan así.

Para dar un formulario a uno de tus scripts, escríbelo como JSON en **Formulario de configuración** en los ajustes del script,
con la forma que describe la referencia de [Config forms](https://pxstud.io/es/docs/scripting/config-forms.md); los ajustes
te dicen qué está mal antes de guardar. El formulario forma parte del borrador y de cada versión
publicada. Aun así, un script debería leer cada campo como opcional y recurrir a sus propios valores predeterminados.
Para recibir datos mientras un script se ejecuta, abre en su lugar una ventana de script.

## Ventanas de script

Un script puede abrir una ventana propia con `Dialog{}`, construida como las construyen los scripts de Aseprite:
etiquetas, cuadros de texto y de números, controles deslizantes, casillas, botones de opción, listas desplegables, campos de color,
filas de muestras de color, botones y un selector de archivos (solo archivos de texto pequeños).

```lua
local dlg = Dialog{ title = "Quick Fill" }
dlg:color{ id = "paint", label = "Color", color = "#3a8f4a" }
dlg:button{ id = "fill", text = "Fill layer", onclick = function()
  local layer, frame = app.getActiveLayerId(), app.getActiveFrameId()
  app.floodFill(layer, frame, 0, 0, { color = dlg.data.paint })
end }
dlg:show{ wait = false }
```

- `dlg:show{ wait = false }` abre una **ventana flotante** y el script espera, inactivo, mientras tú
  sigues dibujando; cada pulsación de botón o cambio al que reacciona es su propio paso de deshacer. Sin
  `wait = false`, la ventana es modal: el editor queda bloqueado hasta que la cierres.
- La barra de título de la ventana nombra el script y la marca como de un script, y todo lo que contiene es
  texto simple, así que un script no puede hacer pasar su ventana por parte del editor.
- Cerrar la ventana termina el script; detener el script cierra sus ventanas.

La referencia de [Dialogs and commands](https://pxstud.io/es/docs/scripting/dialogs.md) tiene cada widget y sus opciones.

## Comandos de script

Un script puede añadir **comandos** a los menús del editor, igual que lo hace un plugin de Aseprite. Define
una función `init(plugin)` que los registre con `plugin:newCommand`:

```lua
local function mirror()
  app.flip("horizontal", app.getActiveLayerId())
end

function init(plugin)
  plugin:newCommand{ id = "mirror", title = "Mirror Layer", group = "layer", onclick = mirror }
end
```

Guarda el script, luego elige Scripts > Comandos de scripts... y pulsa **Instalar** junto a él. El
comando aparece ahora:

- en el menú que nombra su `group` (`file`, `file_import`, `edit`, `edit_transform`, `edit_fx`,
  `edit_adjustments`, `sprite`, `layer`, `frame`, `select` o `view`), mostrado con el nombre del
  script; sin grupo, en Scripts, en un submenú con el nombre del script;
- en la paleta de comandos;
- en Ajustes > Atajos de teclado..., donde puedes asignarle un atajo.

Ejecutar el comando ejecuta tu script guardado y luego el `onclick` del comando, como un solo paso de deshacer.
Tras cambiar qué comandos registra un script, pulsa **Reinstalar**; **Quitar** los saca
de los menús. Un script puede añadir hasta 32 comandos. Los comandos instalados se guardan en este navegador.

Para instalar comandos del script de otra persona, bifúrcalo primero a tus scripts.

## Guardar y publicar

Tus scripts se guardan en este navegador, como tus sprites, y funcionan sin conexión. Con
[Sync](https://pxstud.io/es/docs/manual/concepts/how-work-is-organized.md#where-things-are-kept), también se guardan en tu cuenta y en tus otros
dispositivos.

**Publicar** comparte un script en la biblioteca de scripts. Todo script empieza como **Privado**, así que solo tú
puedes verlo; elige **Compartido en la biblioteca** en sus ajustes (**Ajustes del script**, o la
insignia Privado) para que aparezca en la lista. Entonces:

- **Guardar borrador** mantiene tus ediciones en privado. Las personas que usan la biblioteca siempre obtienen tu última
  versión publicada, nunca el borrador.
- **Publicar** guarda el borrador y lo convierte en la siguiente versión numerada, con la nota de versión
  que escribas (se muestra en el historial de versiones). Las versiones publicadas nunca cambian; publica de nuevo para crear
  una nueva.
- Los ajustes del script listan cada versión publicada. **Ver código** abre una antigua en solo lectura,
  y **Restaurar en el borrador** la copia en tu borrador.
- Un script puede tener hasta 3 etiquetas, que ayudan a encontrarlo en la biblioteca.

Publicar requiere una cuenta con Sync en pxstud.io.
Ejecutar, bifurcar y marcar con corazón scripts (con una cuenta gratuita) se explica en
[La biblioteca](https://pxstud.io/es/docs/manual/guides/library.md).

## Lo que los scripts no pueden hacer

Los scripts están en un entorno aislado, así que ejecutar un script escrito por otra persona es seguro:

- **Sin red, archivos ni carga de código.** Un script no puede acceder a internet ni a tus archivos (salvo
  un archivo de texto que elijas en su ventana), y no puede cargar otro código. Las bibliotecas `io`, `os` y
  `debug` de Lua no están; `string`, `math`, `table`, `utf8` y `coroutine` sí.

- **Solo el sprite abierto.** Un script edita el sprite en el que lo ejecutaste, como un solo paso de deshacer. No puede
  abrir, guardar, exportar, cerrar ni eliminar sprites, usar el portapapeles, ni cambiar la vista y los paneles.

- **Tus bibliotecas solo cuando eliges de ellas.** Un script ve uno de tus pinceles o paletas guardados
  solo cuando su formulario de configuración lo pide y tú lo eliges.

- **Un presupuesto de memoria.** Una ejecución no puede usar más de una cantidad fija de memoria: para sus Images, sus
  datos de Lua, los píxeles que añade al sprite y el paso de deshacer que construye. Al superarla, el script se
  detiene con un error que indica cuál, y lo que hizo hasta entonces queda como un solo paso de deshacer, de modo que un
  script descontrolado no puede bloquear el editor ni expulsar tus pasos anteriores del historial de deshacer.

No hay límite de tiempo; un script descontrolado siempre se puede pausar o detener.

## Los generadores oficiales

La biblioteca de scripts de pxstud.io tiene un conjunto de scripts oficiales, marcados como **Oficial**: generadores de
degradados, tableros de ajedrez, rellenos de ruido, muros de ladrillo, adoquines, tablones de madera, texturas de hierba y agua,
rayos, tornados, arcoíris, cometas, galaxias, planetas, estrellas, árboles, arbustos y
rocas. Inicia sesión con una cuenta gratuita, abre Scripts > Explorar la biblioteca de scripts..., elige **Oficiales** y pulsa
**Ejecutar** en uno: rellena su formulario (o pulsa **Aleatorio**) y dibuja en tu sprite. Bifurca uno para
ver cómo está hecho, o para cambiarlo.