run_lua_script
Execute custom Lua scripts in Aseprite batch mode for operations not available through dedicated tools. Output results using print().
Instructions
Execute arbitrary Aseprite Lua code in batch mode (escape hatch).
Use this when no dedicated tool covers what you need. The full API is documented at https://www.aseprite.org/api/. Anything the curated tools do can also be done here — they are Lua underneath.
Essentials for batch-mode scripts:
When filename is given, it is opened first and available as app.activeSprite.
Changes are NOT saved automatically; call spr:saveAs(spr.filename) at the end if you modified the sprite.
print() is the only way to return data; a clean exit does not mean your logic succeeded, so print what you need to verify.
Coordinates on cel images are cel-local: offset sprite-global coordinates by cel.position before getPixel/putPixel.
WARNING: this executes unrestricted code (including io/os access) on the host running Aseprite. Only pass scripts you trust.
Args: script: Lua source code to execute filename: Optional Aseprite file to open before running
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| script | Yes | ||
| filename | No |