Tiled 命令系统(Using Commands)完全指南:从命令行按钮到变量替换的实战与源码解析
Tiled 命令系统(Using Commands)完全指南:从命令行按钮到变量替换的实战与源码解析
Tiled 的 Command Button(命令按钮)允许你在编辑器内直接创建并运行外部程序(shell 命令),用于衔接游戏引擎的加载、资源打包、地图导出等外部流程。本文以 Tiled 官方手册《Using Commands》为核心,结合仓库源码逐层讲解命令按钮的入口、命令编辑对话框的全部配置项、可用变量及替换规则,并给出可直接复制的多平台示例命令,帮助你搭建属于自己的"一键式"工作流。
认识命令系统:它解决什么问题
在游戏开发中,编辑地图只是流程的一环——保存地图后往往还要运行自定义游戏程序加载地图、调用引擎工具链进行资源转换,或导出为特定格式。Tiled 的命令系统把"启动外部程序"这件事集成进编辑器:
- 你可以配置任意数量的命令,例如为多个项目分别配置各自的启动命令;
- 也可以为同一个游戏配置多条命令,分别加载不同的检查点(checkpoint)或配置文件;
- 每条命令都可绑定自定义键盘快捷键,并可通过工具栏按钮或 File 菜单快速触发。
核心实现位于 src/tiled/command.cpp 与 src/tiled/command.h:Command 结构体承载一条命令的全部配置(可执行文件、参数、工作目录、快捷键、是否显示输出等),CommandProcess 则基于 Qt 的 QProcess 完成实际启动与输出转发。
Command Button:命令按钮的使用
命令按钮位于主工具栏上,撤销/重做(redo)按钮的右侧,外观是一个运行图标(system-run)。它的交互分为两种:
- 单击按钮本体:直接运行"默认命令"——即命令列表中第一条处于启用(Enabled)状态的命令;
- 单击按钮右侧的下拉箭头:展开菜单,列出所有已启用命令,可选择运行任意一条;菜单底部还提供 "Edit Commands..."(编辑命令)入口,用于打开命令编辑对话框。
此外,所有已启用的命令也会出现在 File 菜单中,并且每条命令都可以在编辑对话框中配置自定义键盘快捷键(Shortcut)。
按钮的底层行为见 src/tiled/commandbutton.cpp:它继承 QToolButton 并设置为 MenuButtonPopup 弹出模式,菜单内容由 CommandManager 动态注册填充。当列表中没有任何可用的命令时,单击按钮会弹出警告框"Error Executing Command",提示"你还没有设置任何命令",并附带 "Edit Commands..." 按钮引导你直接进入编辑对话框——这一设计在 commandmanager.cpp 的 executeDefaultCommand() 中体现:它遍历命令列表,执行第一条 isEnabled == true 的命令;若全部禁用或列表为空则返回失败。
编辑命令:Edit Commands 对话框
通过命令按钮下拉菜单、File 菜单或主菜单栏打开 "Edit Commands..." 后,会进入命令编辑对话框。对话框以**标签页(Tab)**形式组织命令(见 commanddialog.cpp):
- Global Commands(全局命令):存储在你的用户偏好设置中,对所有项目生效;
- Project Commands(项目命令):随当前项目(
.tiled-project)文件一起保存,仅在该项目中生效。只有当当前确实打开了项目文件时该标签页才可用(tabWidget->setTabEnabled(1, !project.fileName().isEmpty()))。
命令列表以表格形式呈现(数据模型见 commanddatamodel.cpp),包含三列:Name(名称)、Shortcut(快捷键)、Enable(启用)。列表底部有一行 <new command>(新建命令)占位,在名称列输入新名字即会追加一条命令。对已有命令点击右键会出现上下文菜单,提供 Move Up / Move Down(上移/下移)、Execute(执行)、Execute in Terminal(在终端中执行,Linux/macOS 可用)、Delete(删除) 等操作;列表还支持拖拽排序,甚至可以把命令拖出到文本编辑器或终端中(拖出的文本即最终命令字符串),或从外部拖入文本创建新命令。
选中某条命令后,右侧/下方区域显示该命令的完整属性编辑控件(对应 commandsedit.cpp):
| 属性 | 说明 | 备注 |
|---|---|---|
| Name(名称) | 命令在下拉列表与菜单中显示的名称,便于识别 | 列表首列可直接编辑 |
| Executable(可执行文件) | 要运行的程序,可以是完整路径,也可以是系统 PATH 中的可执行文件名 | 可通过 Browse 按钮(exBrowseButton)用文件选择器定位 |
| Arguments(参数) | 运行可执行文件时附加的参数 | 支持变量替换 |
| Working directory(工作目录) | 命令运行时的工作目录路径 | 可通过 Browse 按钮选择目录,支持 %executablepath 变量 |
| Shortcut(快捷键) | 触发该命令的自定义按键序列 | 可用 "Clear" 按钮清除重置 |
| Show output in Console view(在控制台视图中显示输出) | 启用后,命令的 stdout 与 stderr 会显示在 Console(控制台)面板中,位于 View > Views and Toolbars > Console | 默认开启 |
| Save map before executing(执行前保存地图) | 启用后,命令执行前会自动保存当前地图 | 默认开启 |
| Enabled(启用) | 快速启用/禁用命令;被禁用的命令会从下拉列表与菜单中移除,默认命令是第一条启用的命令 | 列表"Enable"列勾选 |
注意:如果可执行文件路径或任意参数中包含空格,这些部分必须用引号括起来(详见下文源码处理逻辑)。
编辑界面的细节能力
- 浏览按钮:Executable 与 Working directory 旁的 Browse 按钮分别调用文件/目录选择器,并会记住上一次的选择路径(存储在
Session中),下次打开自动定位,见 commandsedit.cpp。 - 默认命令示例:首次启动 Tiled 时,系统会自动添加一条默认命令 "Open in text editor"(在 Linux 上为
gedit %mapfile,macOS 上为open -t %mapfile,Windows 上为notepad.exe %mapfile),但默认处于禁用状态——这样你在第一次点击命令按钮时会看到提示,从而了解如何配置命令(见 commandmanager.cpp)。
命令的存储位置
从源码看,命令的持久化方式分两层(commandmanager.cpp 与 project.cpp):
- 全局命令:以
commandList为键存入用户偏好设置(Preferences),通过Command::toVariant()/Command::fromVariant()序列化为QVariantHash(字段包括arguments、command、enabled、name、saveBeforeExecute、shortcut、showOutput、workingDirectory); - 项目命令:保存在项目文件(
.tiled-project)中,随项目分发,方便团队共享同一套命令配置。
变量替换(Substituted Variables)
这是命令系统最具价值的能力:在 Executable(可执行文件)、Arguments(参数)、Working directory(工作目录) 三个字段中,你可以使用占位变量,执行时会被替换为当前编辑环境对应的真实值。变量替换逻辑实现在 command.cpp 的 replaceVariables() 函数中。
所有可用变量
| 变量 | 含义 | 引入版本 |
|---|---|---|
%mapfile |
当前文件(地图或图集)的完整路径 | 一直可用 |
%mappath |
当前文件所在目录的路径 | 一直可用 |
%exportfile |
当前文件最后一次导出的完整路径;若尚未导出过则为空字符串 | 一直可用 |
%exportpath |
最后一次导出所在的目录路径;若尚未导出过则为空字符串 | 一直可用 |
%projectpath |
当前项目所在目录的路径 | Since Tiled 1.4 |
%objectclass |
当前选中对象的 class 名称(若选中对象);另提供 %objecttype 作为 Tiled < 1.9 的兼容别名 |
一直可用(%objectclass 语义随版本演进) |
%objectid |
当前选中对象的 ID(若选中对象) | 一直可用 |
%layername |
当前选中图层的名称 | 一直可用 |
%tileid |
当前选中瓦片的 ID,多个 ID 以逗号分隔的列表(针对图集文档) | Since Tiled 1.6 |
%worldfile |
当前地图所属 world 文件的完整路径(若存在) | Since Tiled 1.9 |
仅工作目录字段还额外支持一个变量:
| 变量 | 含义 |
|---|---|
%executablepath |
可执行文件所在目录的路径 |
变量替换的源码级行为
- 自动加引号:默认情况下,替换时变量值会被自动包裹在英文双引号中(
replaceString = "\"%1\""),因此即使路径包含空格也能安全传递。唯一的例外是工作目录字段(quoteValues = false,见 command.cpp),因为工作目录通常不含空格,且%executablepath需要在替换后再处理。 %executablepath的解析顺序:先替换工作目录中的其余变量,再定位可执行文件——优先使用配置的完整路径,若文件不存在则通过QStandardPaths::findExecutable()在系统 PATH 中查找,最后用其所在目录替换%executablepath(command.cpp)。- 变量按当前上下文动态求值:
%mapfile、%mappath来自DocumentManager当前打开的文档;%exportfile/%exportpath来自文档记录的"最后导出文件名"(lastExportFileName());%projectpath来自ProjectManager当前项目文件所在目录;%layername仅在地图文档中、且存在当前图层时替换;%tileid仅在图集文档中替换,多个选中瓦片的 ID 用逗号连接;%objectclass/%objectid仅在当前选中对象是MapObject时替换;%worldfile通过WorldManager查询当前地图所属的 world。若文档不满足替换条件(例如未打开任何文档),对应变量保持原样留在命令中。 - 最终命令的组装:
finalCommand()(command.cpp)会先对可执行文件做修剪与引号处理——若其未以引号开头,则自动为其补上双引号,保证含空格的路径也能正确启动,然后拼接参数并统一执行变量替换。
执行流程:从点击到进程启动
当一条命令被触发(点击按钮、菜单项、快捷键)时,Command::execute()(command.cpp)执行如下流程:
- 若开启了 "Save map before executing",先触发
ActionManager中的 "Save" 动作保存当前文档;若当前地图属于某个 world,还会一并保存该 world 文档(见 command.cpp)。 - 创建
CommandProcess(继承QProcess)并异步启动进程。 - 若命令为空或纯空白,直接报告
FailedToStart错误,弹出包含最终命令文本的错误对话框(command.cpp)。 - 若启用了 "Show output",执行前会在 Console 打印
Executing: <最终命令>,并将子进程的 stdout 转发为 INFO 日志、stderr 转发为 ERROR 日志,统一汇入 Console 面板(command.cpp)。 - 进程启动失败、崩溃或超时都会通过
handleProcessError弹出错误提示(command.cpp)。 - 进程结束时自动释放对象(
finished信号连接deleteLater)。
"Execute in Terminal"(在终端中执行):Linux 上优先使用 gnome-terminal -x,否则回退到 xterm -e;macOS 上则会生成一个临时 .command 文件、chmod +x 后通过 open -W -n 在 Terminal 中打开(command.cpp)。
示例命令(Example Commands)
启动自定义游戏并传入当前地图
假设你有一个名为 mygame 的游戏程序,希望在 Tiled 中一键加载当前编辑的地图:
mygame -loadmap %mapfile
执行后等价于运行 mygame -loadmap "/path/to/current/map.tmx"(路径已自动加引号)。
macOS 上启动应用
macOS 上 App 本质上是文件夹,因此直接使用应用程序名通常无法执行,需要运行其内部真正的可执行文件(位于 Contents/MacOS 目录):
/Applications/TextEdit.app/Contents/MacOS/TextEdit %mapfile
或者使用 open 命令打开应用(注意:参数中包含空格的部分必须用引号括起来):
open -a "/Applications/CoronaSDK/Corona Simulator.app" /Users/user/Desktop/project/main.lua
用系统默认程序打开当前地图
许多系统提供"用关联程序打开文件"的命令,非常适合配合 %mapfile 实现"在系统默认编辑器中打开当前地图":
- macOS(OSX):
open %mapfile - GNOME 系(如 Ubuntu):
gnome-open %mapfile - FreeDesktop.org 标准(多数 Linux 桌面):
xdg-open %mapfile
组合变量实现"导出并运行"工作流
结合 %exportfile/%exportpath 可以构建导出-运行闭环,例如把地图导出到固定目录后立即触发引擎热加载工具(示意):
/opt/myengine/tools/reload %exportpath
当最后一次导出路径为空时,该变量会被替换为空字符串,命令照常执行——因此这类命令通常与 Tiled 的导出功能配合使用,确保先完成导出。
结语与延伸
命令系统的设计目标是把"编辑器之外"的重复性操作收敛进 Tiled:通过全局/项目两级命令、快捷键绑定、变量替换与 Console 输出集成,它成为衔接地图编辑与游戏运行/工具链的关键枢纽。想要深入了解实现细节,可以继续阅读:
- 命令数据结构与执行:src/tiled/command.h、src/tiled/command.cpp
- 命令的加载、保存与菜单构建:src/tiled/commandmanager.cpp
- 命令按钮交互:src/tiled/commandbutton.cpp
- 编辑对话框与列表模型:src/tiled/commanddialog.cpp、src/tiled/commanddatamodel.cpp
- 属性编辑控件:src/tiled/commandsedit.cpp
对照官方手册原文 docs/manual/using-commands.rst,配合上述源码,即可完全掌握 Tiled 命令系统的全部能力。