Aseprite Lua API 简介｜什么都能自动化的脚本系统
Aseprite 的 Lua API 是什么
Aseprite 从 v1.0 开始内置 Lua 脚本引擎——几乎所有你在 Aseprite 界面里能做的操作，都能用 Lua 脚本调用。这意味着：
- 批量导出一堆
.ase文件的 Sprite Sheet → 跑一个脚本就行，不用一个个手动导 - 自动调色板转换、自动切片、自动缩放 → 几行脚本的事
- 写自定义工具和面板 → 可以扩展 Aseprite 的功能
- v1.3.16 新增的 Run Command 窗口（Ctrl+Space）→ 可以直接输入 Lua 表达式，不用写文件
Aseprite 的 Lua API 参考文档非常完善，社区也有上千个现成脚本可以直接用。
两种运行方式
方式一：命令行批处理（无界面）
aseprite -b --script export-spritesheets.lua *.ase-b= Batch Mode，不打开 GUI，跑完脚本直接退出--script指定要运行的 Lua 脚本文件- 后面可以跟任意参数（文件名、脚本参数等）
这是做自动化工作流的主要方式——把脚本塞进 CI/CD 管道、或者写进 PowerShell/Bash 脚本里，一键批量处理。
方式二：GUI 里运行
在 Aseprite 界面里：
- File → Scripts → Open Script → 选择脚本文件运行
- 或把脚本放进 Aseprite 的 Scripts 文件夹，自动出现在菜单里
- v1.3.16 新增：Ctrl+Space → Run Command 窗口 → 直接输入 Lua 代码片段或选择预装脚本
最简脚本示例
-- 导出当前打开的 sprite 为 PNG
local sprite = app.activeSprite
if sprite then
local filename = sprite.filename:gsub(".ase", ".png")
sprite:saveAs(app.fs.filePath(filename))
app.alert("已导出: " .. filename)
end这个脚本只有 7 行——获取当前激活的 sprite → 把文件名从 .ase 改成 .png → 导出 → 弹窗提示。你可以在 Run Command 窗口里直接复制粘贴运行。
API 的核心对象
Aseprite Lua API 里最重要的几个对象：
| 对象 | 是什么 | 常用方法 |
|---|---|---|
app | 全局应用对象 | app.activeSprite（当前画布）、app.command（调用命令）、app.fs（文件系统） |
Sprite | 精灵图（画布） | filename、width、height、palette、tags、layers |
Layer | 图层 | name、isVisible、opacity、cels |
Frame | 帧 | duration、cel |
Tag | 标签 | name、fromFrame、toFrame、loopDirection |
Palette | 调色板 | colors、addColor()、setColor() |
Run Command 窗口（Ctrl+Space）
v1.3.15.3 新增的杀手级功能——按 Ctrl+Space 弹出一个命令搜索窗口：
三种用法
- 命令搜索：输入关键词（比如 "export"、"sprite sheet"），弹出 Aseprite 所有相关命令，直接点击运行
- 数学表达式：输入
16 * 8直接显示结果 - Lua 表达式：输入任何有效的 Lua 代码片段（比如
app.activeSprite.width），直接求值
实用场景
- 快速检查当前画布尺寸：Ctrl+Space → 输入
app.activeSprite.width→ 回车 - 临时批量操作：Ctrl+Space → 输入 Lua 代码 → 回车执行
- 快速搜索功能：记不住某个菜单在哪？Ctrl+Space 搜
这大大降低了 Lua 脚本的门槛——不用先写文件、保存、再运行，直接 Ctrl+Space 输入一行代码就能跑。