ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

Tiled 脚本 API 类型定义包(@mapeditor/tiled-api)演进全解析:从 1.4.3-alpha 到 1.11.0 的 CHANGELOG 深度导读

Tiled 脚本 API 类型定义包(@mapeditor/tiled-api)演进全解析:从 1.4.3-alpha 到 1.11.0 的 CHANGELOG 深度导读 游戏开发桌面应用开发工具【免费下载链接】tiledFlexible level editor项目地址https://gitcode.com/gh_mirrors/ti/tiled点击查看免费下载本篇以 docs/scripting-doc/CHANGELOG.md 为骨架结合仓库内 docs/scripting-doc/index.d.ts约 5960 行类型声明、docs/scripting-doc/README.md 以及 src/tiled/scriptmodule.cpp 等源码逐版本梳理 Tiled 脚本 API 类型定义的演进脉络。读完本文你将掌握该类型定义包各版本引入的 API 变更、strict 模式与命名空间化改造的来龙去脉以及如何在 VS Code 中借助mapeditor/tiled-api获得插件脚本的自动补全与类型检查能力。一、这个 CHANGELOG 记录的是什么CHANGELOG 记录的对象并不是 Tiled 主程序本身而是其脚本 API 的 TypeScript 类型定义包mapeditor/tiled-api。这一点可从 docs/scripting-doc/package.json 确认包名mapeditor/tiled-apitypes入口./index.d.ts当前版本1.11.0与 Tiled 1.11 对应许可证MIT该包的核心价值在于Tiled 通过内嵌 JavaScript 引擎QJSEngine暴露了一套完整的脚本 API可用于注册自定义地图/图块集格式tiled.registerMapFormat、自定义动作tiled.registerAction、自定义工具tiled.registerTool以及基于信号Signal的自动化脚本。而index.d.ts就是这套 API 的 TypeScript 声明文件它让开发者可以直接编写 TypeScript 脚本并获得编译期类型检查在 VS Code 等编辑器中为 JavaScript 脚本获得自动补全IntelliSense。CHANGELOG 因此天然具有版本矩阵性质每个版本号对应一批 Tiled 主程序新增的 API 声明 一批文档/类型的修正。读懂它等于拿到了一份 Tiled 脚本 API 的浓缩演进地图。二、从 CHANGELOG 到版本演进时间线将 CHANGELOG 中记录的各版本按时间线整理如下版本时间对应 Tiled 主版本里程碑意义1.4.3-alpha2020-12-15Tiled 1.4首个发布仅包含部分 API1.6.02021-05-03Tiled 1.6首个稳定版基于 Tiled 1.6 API1.8.02022-02-07Tiled 1.8引入 strict 模式、升级 TypeScript 4.4 / Typedoc 0.211.8.12022-02-08—修复 strict 模式错误1.8.22022-05-03—File API 改为 namespace、补充严格空值声明1.9.22022-09-22Tiled 1.8.5 / 1.9.0 / 1.9.1 / 1.9.2FileInfo 改为 namespace1.10.0—Tiled 1.10补齐 Qt 控件文档、链接迁移 Qt 61.10.1—Tiled 1.10.1补充 MapObject 构造器文档1.11.0—Tiled 1.10.2 / 1.11.0拆分 ToolDefinition、增强擦除与预览文档可以看到两个关键的演进主线其一是 API 声明随 Tiled 主程序功能持续扩充其二是类型系统从宽松可用走向严格可检查的工程化过程1.8.0 起。三、工程化改造主线strict 模式与 namespace 化3.1 启用 strict 模式1.8.0 → 1.8.1CHANGELOG 在 1.8.0 一栏写道Enabled strict mode次日1.8.1立即发布修复Fixed strict mode error。这说明 1.8.0 是一次类型严格度的大跃迁从此所有声明必须显式处理null/undefined类型系统能够捕获更多空值误用。随后 1.8.2 一栏的 Strict mode corrections (adding| nullor| undefined) 进一步确认了这一过程的持续性——大量 API 返回值与可选属性被逐一补齐空值联合类型。到 1.11.0 一栏仍有 Fixed missing| nullin a few more places说明严格化是一个覆盖全声明文件的长期工程。3.2 File / FileInfo 的 namespace 化1.8.2、1.9.2CHANGELOG 记录了两次影响 JavaScript 调用方式的 API 形态变更1.8.2Changed File API to a namespace so it can be accessed in TypeScript1.9.2Changed FileInfo API to a namespace so it can be accessed in TypeScript (#3346)这两条变更都对应 GitHub issue #3346其意图是让File、FileInfo以命名空间namespace形式暴露从而在 TypeScript 中可直接通过FileInfo.xxx静态访问。与之配套1.11.0 一栏提到 DocumentedFileEdit.isDirectory/filter而 docs/scripting-doc/index.d.ts 第 5639 行可看到isDirectory: boolean;的声明印证了文件编辑类 API 文档的持续补全。3.3 类型声明的精确化细节CHANGELOG 中大量条目属于类型精度修正例如1.10.0Fixed type ofImageLayer.transparentColor——修正透明色属性的类型1.10.0FixedQDoubleSpinBoxstep value property name——修正属性名拼写1.11.0Fixed the type ofFilePath.urlandImageLayer.imageSource——修正 URL 相关字段类型1.11.0Fixed hidden doc forDialog.exec()(#3837)——修复文档被隐藏的注解问题1.10.0Updated links to Qt documentation to Qt 6——外部文档链接统一迁移到 Qt 6 版本文档。这类修正虽然细碎但对脚本作者至关重要错误的类型声明会导致编辑器误报错误或漏报潜在问题而属性名写错这类 bug 在动态语言脚本中最难排查。四、API 扩展主线Tiled 新版本能力的声明化4.1 版本对应关系几乎每个版本栏目的第一行都是 Added the new API from Tiled X.Y形成一条清晰的对应链1.8.0 → Tiled 1.81.9.2 → Tiled 1.8.5、1.9.0、1.9.1、1.9.2一次合并多个补丁版本1.10.0 → Tiled 1.10.01.10.1 → Tiled 1.10.11.11.0 → Tiled 1.10.2、1.11.0值得注意 1.9.2 与 1.11.0 都出现一次版本聚合多个主程序补丁版的模式mapeditor/tiled-api的版本节奏与 Tiled 主程序并不严格一一对应而是按发布批次批量同步 API 声明。4.2 代表性新增文档ToolDefinition 的拆分1.11.01.11.0 一栏中最具结构性的一条是 SplitToolDefinitionfromToolforregisterToolfunction。在 docs/scripting-doc/index.d.ts 第 4478 行可以找到interface ToolDefinition的完整定义其核心字段包括name工具栏上显示的工具名称必填icon?图标文件名设置后工具栏显示图标、名称变为 tooltiptoolBarActions?要添加到工具专属工具栏的动作 ID 列表可用-插入分隔符动作需通过tiled.registerAction()注册自 1.9 起usesSelectedTiles?是否使用当前选中的图块默认false。当为false且选中图块变化时Tiled 会自动切回 Stamp Brush设为true则保持本工具激活自 1.8 起与 Wang 集相关的开关默认false为false时点击 Wang 颜色会自动激活 Terrain Brush。从实现侧看src/tiled/scriptmodule.cpp 第 463-478 行的ScriptModule::registerTool()展示了注册流程校验 shortName 非空 → 通过ScriptedTool::validateToolObject()校验工具对象 → 以 shortName 生成Id并注册到mRegisteredTools映射。这也解释了为何类型定义强调定义与实现的分离——ToolDefinition描述的是传入registerTool的对象形状Tool则是在 Tiled 内部实例化后的运行态工具。4.3 擦除图块与 Tool.preview 文档强化1.11.01.11.0 中 Clarify how to erase tiles and highlight it in theTool.preview 是对自定义工具开发者的直接赋能。Tool.preview对应 src/tiled/scriptedtool.cpp 第 112 行的ScriptedTool::preview()其返回EditableMap *即工具可维护一个可编辑地图作为实时预览叠加层。擦除图块的标准做法是通过TileLayerEdit其apply方法在 1.11.0 一栏同样被扩展了文档来执行区域擦除并在preview中高亮受影响区域从而在鼠标移动时即时反馈擦除结果。4.4 常用 API 文档补全1.10.0 批次1.10.0 一栏集中补全了一批高频 Qt 控件与核心类型的文档QComboBox.clear、QTextEdit.html、QTextEdit.markdown、QLineEdit.text、QWidget.styleSheet——脚本对话框Dialog见 docs/scripting-doc/index.d.ts 第 5674 行declare class Dialog extends Qt.QWidget中常用控件的缺失文档Dialog.exec、Dialog.addImage、Dialog.addTextEdit——对话框模态执行与控件添加方法Tileset.transparentColor、Tile.imageRect——图块集与图块核心属性TileLayer.flagsAt返回值澄清、TileLayerEdit.setTile文档澄清——图层编辑语义的精确定义。这些补全让脚本作者不再需要猜测返回值类型也修复了此前文档与实现不一致的隐患。五、示例与实战在 VS Code 中启用补全与类型检查README.md 提供了接入mapeditor/tiled-api的最小实践路径mkdir example-tiled-ts-plugin cd example-tiled-ts-plugin npm init npm install mapeditor/tiled-api --save-dev随后在脚本头部声明引用即可获得自动补全/// reference typesmapeditor/tiled-api / const action tiled.registerAction(CustomAction, function(action) { tiled.log(action.text was (action.checked ? checked : unchecked)) }) action.text My Custom Action action.checkable true action.shortcut CtrlK tiled.extendMenu(Edit, [ { action: CustomAction, before: SelectAll }, { separator: true } ]);若改用 TypeScript 编写插件除了补全外还能获得编译期错误提示。这正是 CHANGELOG 中多次出现 Fixed missing| null、marked readonly 等条目的意义所在——声明文件的精度直接决定了你在编辑器里看到的是正确提示还是错误干扰。5.1 类型定义的生成与检查机制仓库提供了类型声明的维护工具链generate-scripting-tsdoc.sh 使用npx typedoc --name Tiled Scripting API ... index.d.ts从index.d.ts生成在线文档站点这正是 CHANGELOG 中 Updated typedoc to 0.211.8.0条目的实际作用点docs/scripting-doc/tsconfig.json 配合package.json中的test: tsc脚本在发布前对声明文件执行 TypeScript 编译校验——strict 模式相关的修正1.8.0/1.8.1/1.8.2/1.11.0都能在这一步被自动发现。5.2 与 Tiled 运行时脚本的对应关系脚本 API 的运行时实现位于 src/tiled/scriptmodule.cppScriptModule类共 787 行其中除了前文提到的registerTool还包括registerMapFormat第 445-447 行附近创建ScriptedMapFormat实例、registerTilesetFormat第 449-461 行等注册入口。类型声明与这些 C 实现一一对应构成声明index.d.ts→ 运行时scriptmodule.cpp的完整链条这也是脚本作者在排查为什么声明存在但行为不符时可以深入源码的依据。六、总结如何高效使用这份 CHANGELOG作为 API 变更参考升级mapeditor/tiled-api前先对照 CHANGELOG 检查目标版本引入了哪些新声明、改动了哪些类型重点关注 1.8.0 的 strict 模式、1.8.2/1.9.2 的 File/FileInfo namespace 化这类破坏性形态变更以及 1.11.0 的ToolDefinition拆分作为文档补全清单CHANGELOG 中列出的每条 Fixed ... docs 都指向一个此前不准确或不完整的 API 文档可作为检索index.d.ts对应声明时的速查线索作为版本对齐工具由于mapeditor/tiled-api的版本与 Tiled 主程序并非严格一一对应如 1.9.2 一次涵盖 1.8.5~1.9.2在讨论某 API 自哪个 Tiled 版本可用时需同时参考index.d.ts中的since标注如toolBarActions标注since 1.9、usesSelectedTiles标注since 1.8而非仅看包版本号。从 2020 年 12 月的 1.4.3-alpha仅含部分 API到当前 1.11.0完整覆盖 Tiled 1.11 脚本能力这份 CHANGELOG 记录的不只是版本号递增更是 Tiled 脚本生态从能用到好用的完整工程化历程类型声明越来越严格、文档越来越精确、API 形态越来越清晰。对脚本插件开发者而言它是理解 Tiled 脚本 API 演进、规避升级风险的第一手资料。赞分享游戏开发桌面应用开发工具【免费下载链接】tiledFlexible level editor项目地址https://gitcode.com/gh_mirrors/ti/tiled点击查看免费下载相关推荐Tiled TMX 文件格式演进史从 Tiled 0.8 到 1.12 的 Changelog 深度解读Tiled TMX 文件格式演进史从 Tiled 0.8 到 1.12 的 Changelog 深度解读 TMXTile Map XML是 Tiled 编游戏开发桌面应用开发工具iced 版本演进全解析从 0.1.0-alpha 到 0.14.0 的 Changelog 深度解读iced 版本演进全解析从 0.1.0 alpha 到 0.14.0 的 Changelog 深度解读 本篇技术指南以 iced 仓库的 CHANGELOG.前端跨平台UI组件桌面应用从 v1 到 v6next-forge 版本演进全解析Changelog 深度导读从 v1 到 v6next forge 版本演进全解析Changelog 深度导读 本篇以 next forge 仓库的 CHANGELOG.md htt前端后端示例工程CLI创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表