Guía de scripting

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 te guía para escribir y ejecutar uno. Esta página cubre todo lo que lo rodea.

El menú Scripts

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.

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 pide antes sus valores. Mientras se ejecuta, los controles de ejecución ocupan su lugar (más abajo).
• 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:

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 documenta cada una, generada a partir del propio editor, en secciones:

• Drawing: las herramientas como comandos (app.drawLine, app.floodFill, app.drawIsoShape...), Images para trabajar píxel a píxel, y Pixels para listas planas de píxeles, rellenos y el cuentagotas;
• Document, Layers, Frames, Cels, Selection, Slices y Tilemaps;
• Palette, Adjustments y Brushes;
• ayudas: matemáticas de Color, números Random con semilla, y el Editing context (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:

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; 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).

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 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:

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, 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.

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.