Tiled 项目（.tiled-project）完整使用指南：项目文件、会话恢复与资源管理

Tiled 项目.tiled-project完整使用指南项目文件、会话恢复与资源管理【免费下载链接】tiledFlexible level editor项目地址: https://gitcode.com/gh_mirrors/ti/tiled引言为什么需要项目文件对于大型游戏关卡项目直接打开单个 .tmx 地图文件会带来明显痛点切换地图需要层层浏览文件对话框、不同地图间的自定义属性类型无法统一、扩展脚本分散在各处难以管理。Tiled 提供的项目文件.tiled-project机制正是为解决这些问题而设计。本指南将带你完整掌握项目文件的组成结构、核心配置项、会话Session机制以及如何利用项目快速打开任意资源文件帮助你建立起适合团队协作与长期迭代的关卡资产管理流程。读完本文你将能够熟练创建和配置 Tiled 项目理解其 JSON 配置的每一个字段含义并利用会话功能在多次编辑之间无缝恢复工作状态。项目文件功能自 Tiled 1.4 起引入是后续自定义属性类型、脚本扩展、自动映射等进阶特性的基础承载单元。本文所有内容均基于当前仓库中的 projects.rst 文档并结合源码实现深入展开。项目文件里有什么一个 Tiled 项目文件的核心作用是定义该项目的资产文件夹列表同时为 会话文件 提供锚点。从 project.h 的源码可以看到项目对象在内部维护以下成员成员类型用途mFoldersQStringList项目包含的文件夹列表相对路径mExtensionsPathQString项目级扩展脚本目录mAutomappingRulesFileQString项目级自动映射规则文件mCommandsQVectorCommand项目自定义命令列表mPropertyTypesSharedPropertyTypes项目自定义属性类型mCompatibilityVersionCompatibilityVersion保存/导出时的目标版本除了文件夹列表之外项目还包含以下属性它们都可以通过Project - Project Properties...项目 - 项目属性对话框修改。兼容版本Compatibility Version该属性指定保存或导出文件时目标 Tiled 版本。用于维持与较早版本 Tiled 的兼容性或者与尚不支持某些不向后兼容改动的 TMX 地图支持文档 中所列工具保持兼容。例如某些旧版游戏引擎无法解析新版 TMX 格式新增的字段此时将兼容版本调低可以确保生成的文件仍可被旧工具读取。从源码看Tiled 内部通过CompatibilityVersion枚举定义于 tiled.h来管理版本号Tiled_1_8 1080, Tiled_1_9 1090, Tiled_1_10 1100, Tiled_Current Tiled_1_10, Tiled_Latest 65535,其中Tiled_Current是当前代码的默认版本Tiled_Latest表示始终跟随最新格式。在 project.cpp 的保存逻辑中只有当兼容版本不等于Tiled_Latest时才会在 JSON 中写入compatibilityVersion字段。而在加载时project.cpp未指定该字段的项目会默认按Tiled_Latest处理。扩展目录Extensions Directory项目专属的扩展目录用于放置 Tiled 扩展脚本。默认值为extensions也就是说只要在项目文件所在目录旁有一个名为 extensions 的文件夹它就会被自动加载。该目录中的扩展脚本会在全局扩展之外额外加载这非常适合存放只对当前项目生效的专属脚本工具。从 project.cpp 的加载逻辑可以看到当 JSON 中缺少extensionsPath字段时会使用默认值extensionsproject-mExtensionsPath absolute(dir, projectJson.value(QLatin1String(extensionsPath)).toString(QStringLiteral(extensions)));同时在保存逻辑中project.cpp如果项目尚未保存过且扩展目录为空会默认初始化为项目文件旁的extensions目录。自动映射规则文件Automapping Rules File指向一个 自动映射 规则文件rules.txt或单个规则地图。当此项目加载时该规则会应用于项目中所有地图。对于地图文件旁已经存在rules.txt的情况项目级规则会被忽略——即地图目录内的规则优先级更高。关于自动映射的规则文件设置详见 automapping.md 中的说明自 Tiled 1.4 起可以通过项目属性对话框将 Automapping rules 属性指向项目中的rules.txt如果只有一个规则地图也可以直接引用该地图文件。自定义属性类型在 自定义类型编辑器 中定义的所有自定义类型自定义枚举enum和自定义类class都会保存在项目文件中。这也是为什么 custom-properties.rst 特别强调必须先创建项目才能设置自定义类型——因为这些类型没有项目文件就没有落点。项目文件的 JSON 结构剖析项目文件本质是一个 JSON 文件文件名通常为项目名.tiled-project。仓库自带的 examples.tiled-project 是一个极佳的参考样例其顶层字段包括{ automappingRulesFile: , commands: [], extensionsPath: extensions, folders: [., ../tests], propertyTypes: [...] }对照 project.cpp 的保存代码项目文件实际可能包含的字段有JSON 字段含义默认值propertyTypes自定义属性类型数组空数组folders项目资产文件夹列表相对项目文件的路径空数组extensionsPath扩展脚本目录相对路径extensionsautomappingRulesFile自动映射规则文件相对路径空字符串commands项目自定义命令空数组properties项目自身的自定义属性空compatibilityVersion兼容版本仅当不等于Tiled_Latest时写入无加载时默认Tiled_Latestfolders字段在保存时会将内部路径转为相对项目文件的路径project.cpp加载时则反向解析为绝对路径project.cpp保证项目文件可以整体移动而不会失效。propertyTypes 字段示例propertyTypes数组中的每一项可以是自定义枚举或自定义类。以下摘自 examples.tiled-project自定义枚举enum示例{ id: 1, name: BodyType, storageType: string, type: enum, values: [Static, Dynamic], valuesAsFlags: false }自定义类class示例{ color: #ffa0a0a4, id: 10, members: [ { name: fixture, propertyType: Fixture, type: class, value: {} }, { name: type, propertyType: BodyType, type: string, value: Static } ], name: Body, type: class, useAs: [property, map, layer, object, tile, tileset, wangcolor, wangset] }可以看到自定义类可以包含指向其他自定义类如Fixture和自定义枚举如BodyType的成员并允许在项目级 JSON 中以类的实例值value预设默认数据。会话Sessions自动恢复工作状态每个项目文件都会伴随一个同名的*.tiled-session文件存放在项目文件旁边。会话文件通常不应与他人共享因为它存储的是个人工作状态包括最后打开的文件列表每个文件的部分编辑器状态如视口中心、缩放、当前图层等对话框中最后使用的参数如新建地图时的方向、尺寸、图层格式等会话文件是 JSON 格式通过 session.cpp 中的Utils::jsonSettings加载其中project、recentFiles、openFiles、expandedProjectPaths、activeFile和fileStates等键在保存时都会被转换为相对会话文件的路径session.cpp同样保证了可移植性。会话的自动切换机制当你在不同项目之间切换时Tiled 会自动切换到与项目关联的会话文件从而让你能够从上次离开的地方继续工作。当没有加载任何项目时则使用全局会话文件位于 Tiled 数据目录下的default.tiled-session见 session.cpp。这一机制在 mainwindow.cpp 中实现切换项目时调用Session::switchCurrent(Session::defaultFileNameForProject(project-fileName()))并将当前项目记录到会话的project字段中而会话文件名则由defaultFileNameForProject根据项目文件路径推导session.cppQString Session::defaultFileNameForProject(const QString projectFile) { if (projectFile.isEmpty()) return defaultFileName(); const QFileInfo fileInfo(projectFile); QString sessionFile fileInfo.path(); sessionFile QLatin1Char(/); sessionFile fileInfo.completeBaseName(); sessionFile QStringLiteral(.tiled-session); return sessionFile; }即项目文件为MyGame.tiled-project时会话文件即为同目录下的MyGame.tiled-session。会话还记录了什么从 session.cpp 的源码可以看到会话还维护了各类文件对话框的上次使用路径last.*键包括可执行文件路径用于命令导出文件路径外部图块集路径图片路径对象模板路径对象类型文件路径工作目录世界文件路径快捷键设置文件路径在获取某个文件类型的起始目录时Tiled 会依次尝试会话中记录的上次路径 → 当前文档所在目录 → 当前项目所在目录 → 系统默认位置session.cpp。此外Tiled 还提供了一套SessionOptionT模板session.h供各对话框读写会话级参数并支持注册变更回调onChange当会话切换时所有已注册回调都会被调用以刷新界面状态。在项目中快速打开文件建立项目的另一个优势是你可以快速打开项目文件夹中任意具有受支持扩展名的文件。操作方式是使用File - Open File in Project文件 - 在项目中打开文件快捷键CtrlP打开文件过滤器直接输入你想打开的文件名即可无需在系统文件对话框中逐层导航。该功能对 .tmx 地图、.tsx 图块集、.png 图片、对象模板、世界文件等所有受支持类型的资源都有效是项目工作流中最高频的提速操作之一。项目功能的扩展方向关于项目机制官方文档在 projects.rst 中列出了几个未来可能的增强方向这些可以作为社区讨论与贡献的参考让项目中定义的自定义类型能够通过 脚本 API 访问对应 issue #3419支持按项目关闭某些功能以简化界面、降低误操作概率识别项目中的各类资源使图片、图块集和模板的选择更高效有望替代系统文件对话框动手实践创建一个项目以下是基于上述内容整理的标准操作流程创建项目通过Project - New Project...项目 - 新建项目创建项目文件选择项目文件保存位置并添加资产文件夹。配置项目属性通过Project - Project Properties...项目 - 项目属性设置兼容版本、扩展目录默认为项目文件旁的extensions以及自动映射规则文件。定义自定义类型在自定义类型编辑器中定义枚举与类它们会自动保存进项目文件。放置扩展脚本在项目文件旁创建extensions目录并放入 .js 脚本重启或重新加载后项目专属扩展即生效。享受会话与快速打开切换项目时自动恢复上次打开的文件与编辑器状态按CtrlP快速打开项目内的任意资源。参考链接项目文档原始 RST项目核心实现 project.h项目读写逻辑 project.cpp会话实现 session.cpp会话定义 session.h项目文件样例 examples.tiled-project自定义属性与自定义类型自动映射规则文件设置扩展脚本指南TMX 地图格式兼容性说明【免费下载链接】tiledFlexible level editor项目地址: https://gitcode.com/gh_mirrors/ti/tiled创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考