Tiled 命令系统(Using Commands)完全指南:从命令行按钮到变量替换的实战与源码解析

原创2026-09-22 17:18:031,423 阅读
文章标签:游戏开发桌面应用开发工具图形学

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)执行如下流程:

  1. 若开启了 "Save map before executing",先触发 ActionManager 中的 "Save" 动作保存当前文档;若当前地图属于某个 world,还会一并保存该 world 文档(见 command.cpp)。
  2. 创建 CommandProcess(继承 QProcess)并异步启动进程。
  3. 若命令为空或纯空白,直接报告 FailedToStart 错误,弹出包含最终命令文本的错误对话框(command.cpp)。
  4. 若启用了 "Show output",执行前会在 Console 打印 Executing: <最终命令>,并将子进程的 stdout 转发为 INFO 日志、stderr 转发为 ERROR 日志,统一汇入 Console 面板(command.cpp)。
  5. 进程启动失败、崩溃或超时都会通过 handleProcessError 弹出错误提示(command.cpp)。
  6. 进程结束时自动释放对象(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 输出集成,它成为衔接地图编辑与游戏运行/工具链的关键枢纽。想要深入了解实现细节,可以继续阅读:

对照官方手册原文 docs/manual/using-commands.rst,配合上述源码,即可完全掌握 Tiled 命令系统的全部能力。

登录后查看全文
tiled