Tiled 脚本系统完全指南从扩展安装到命令行自动化【免费下载链接】tiledFlexible level editor项目地址: https://gitcode.com/gh_mirrors/ti/tiledTiled灵活的关卡编辑器自 1.3 起内置了基于 JavaScript 的脚本系统允许开发者编写自定义动作、新工具、自定义文件格式乃至自动化工作流。本文以 docs/manual/scripting.rst 为核心骨架结合仓库内 scriptmanager.cpp、scriptmodule.cpp 等源码实现系统讲解脚本扩展的存放位置、加载机制、控制台与命令行执行方式以及脚本运行环境的关键细节读完即可上手编写并部署自己的 Tiled 扩展。脚本系统概览Tiled 的脚本系统以 JavaScript 为扩展语言功能覆盖三个层面见 scripting.rst 引言自定义地图/图块集格式通过tiled.registerMapFormat/tiled.registerTilesetFormat实现读写自定义格式自定义动作与工具通过tiled.registerAction注册菜单/快捷键动作、通过tiled.registerTool注册新的编辑工具基于信号Signal的自动化监听文档打开、保存、当前文档切换等事件自动执行批处理逻辑。脚本在三种场景下运行启动时自动执行扩展目录中的脚本、通过 Console 视图即时求值、通过命令行--evaluate运行。所有脚本共享同一个 JavaScript 上下文single JavaScript context即扩展之间可以访问彼此的全局变量。完整的 API 参考由 docs/scripting-doc/index.d.tsTypeScript 类型定义生成该定义文件同时也是官方mapeditor/tiled-apiNPM 包的来源编辑器可据此提供自动补全。官方还维护了一个 Tiled Extensions 扩展仓库提供示例脚本与社区扩展链接。JavaScript 宿主环境脚本由 Qt QML 模块自带的 JavaScript 引擎执行。源码 scriptmanager.cpp 中ScriptManager实际创建的是QQmlEngine而非普通QJSEngine注释明确解释了原因mEngine必须是QQmlEngine才能提供 Qt 模块某些 API 需要传递Qt.size、Qt.point之类的对象同时QQmlEngine默认已包含常用扩展无需再手动调用installExtensions。QML 运行时大体实现 ECMAScript 第 7 版ES7并附加了一些扩展。因此语法层面以 ES7 为准异步、模块化能力有限直到 Tiled 1.8 引入.mjs模块后才支持import/export脚本中可以访问Qt全局对象如Qt.size、Qt.point、Qt.rect这在向部分 API 传参时是必需的类型定义中特别注明__filename未在生成的 API 文档中记录因为它与 Node.js 类型冲突。__filename的可用范围__filename保存当前被求值文件的路径但只在文件初次求值期间可用——后续由该文件定义并调用的函数中不再可用若需在函数内使用应先把值拷贝到局部作用域const myDir __filename; // 只在文件顶层求值时可用 function later() { console.log(myDir); // 需要时用拷贝值 }实现见 scriptmanager.cpp求值前把__filename写入全局对象求值结束后立即删除该属性。脚本化扩展Scripted Extensions扩展目录系统级与项目级扩展可以放在系统级目录或项目级目录scripting.rst平台系统级扩展目录WindowsC:/Users/USER/AppData/Local/Tiled/extensions/macOS~/Library/Preferences/Tiled/extensions/Linux~/.config/tiled/extensions/系统级目录可以在Preferences对话框的 Plugins 标签页中一键打开。源码中该目录由 scriptmanager.cpp 基于Preferences::configLocation()拼出extensions子目录不存在时会自动创建。项目级扩展目录默认是.tiled-project文件所在目录下的extensions文件夹可在Project Properties中修改。加载路径的拼接逻辑见 scriptmanager.cpp系统目录与项目目录合并、去重后排序作为最终搜索路径集合。1.7 起的项目扩展安全策略警告Tiled 1.7 起项目级扩展默认只对你在 Tiled 中新建并保存的项目自动启用打开其他项目时若检测到脚本扩展目录会弹出提示询问是否启用。务必谨慎对待非自己创建的项目因为扩展拥有文件访问与进程执行能力可能包含恶意代码。该策略在源码中有完整对应ScriptManager维护mProjectExtensionsSuppressed标志scriptmanager.h启用状态以项目文件名为键保存在Scripting/EnabledProjects偏好中scriptmanager.cpp。只有被列入白名单的项目其扩展目录才会加入搜索路径scriptmanager.cpp。加载机制与热重载扩展可直接放在扩展目录中也可放在其子目录中所有脚本文件在启动时执行。loadExtensions()scriptmanager.cpp会遍历每个扩展路径及其一层子目录把每个目录加入 Qt 的搜索路径前缀ext:供icon等资源引用使用然后逐个目录加载扩展。加载细节scriptmanager.cpp只识别*.js与*.mjs两类文件.js用evaluateFile()直接求值读取文件、自动探测编码、默认 UTF-8scriptmanager.cpp.mjs走importModule()作为 ES 模块加载scriptmanager.cpp每个被加载的文件都会被FileSystemWatcher监控。热重载任何已加载脚本被修改、或扩展目录中有文件新增/删除时脚本引擎会自动重建并重新加载全部脚本无需重启 Tiled方便快速迭代。实现见 scriptmanager.cppscriptFilesChanged触发reset()重置计时器500ms 防抖后删除并重建引擎与模块若脚本正被弹出框阻塞则延迟重试ResetBlocker见 scriptmanager.h。1.8 起的 ES 模块支持使用.mjs扩展名时脚本按 JavaScript modules 加载可用import/export语句把功能拆到多个文件中且不会污染全局作用域避免不同扩展间的命名冲突scripting.rst。注意命令行下.mjs模块只会加载一次同一模块不能重复求值scripting.rst。扩展资源除脚本外扩展还可以附带图片用作脚本化动作ScriptedActionicon属性见 scriptedaction.h或脚本化工具ScriptedToolicon属性见 scriptedtool.h的图标。这些图片放在扩展目录内即可加载时已注册到 Qt 的ext:搜索路径脚本中可按ext:/图标文件名方式引用。Console 视图交互式求值View Views and Toolbars Console打开 Console 视图底部的文本输入框可以写入或粘贴脚本表达式进行求值scripting.rst。按Up/Down键可翻看之前输入过的表达式表达式的求值结果会以临时全局变量$0、$1、$2… 的形式保留可直接在后续表达式中引用对应 scriptmanager.h 的createTempValue命名规则见 scriptmanager.cpp脚本错误与警告会显示在 Console 中含堆栈回溯stack traceback或行号信息scriptmanager.cpp。典型用法tiled.version查看版本、tiled.open(map.tmx)打开地图或直接调用自定义扩展注册的函数。命令行执行Tiled 1.9 起从命令行执行脚本.js或加载模块.mjstiled --evaluate my-script.js # 或 -e tiled --evaluate my-script.js arg1 arg2 # 脚本文件名之后的参数传给脚本 tiled -e a.js -e b.js # 多个脚本依次执行执行完脚本后 Tiled 立即退出UI 不会被实例化依赖界面存在的函数不会生效、部分属性为null对应 scriptmodule.cpp 中DocumentManager::maybeInstance()的空判断逻辑但脚本仍可通过tiled.mapFormats/tiled.tilesetFormats使用所有已安装的读写格式加载、修改并保存地图与图块集文件名之后的非选项参数通过tiled.scriptArguments读取scriptmodule.cpp。命令行处理逻辑位于 src/tiledapp/main.cpp-e/--evaluate选项注册与 main.cppevaluateScript实现先强制退出标记、收集参数、初始化插件与扩展然后evaluateFileOrLoadModule执行。// headless-batch.js命令行批处理示例 const [inputFile, outputFile] tiled.scriptArguments; const map tiled.mapFormats[tmx].read(inputFile); if (!map) throw new Error(Failed to load: inputFile); map.width 64; // 修改地图属性 tiled.mapFormats[tmx].write(map, outputFile);全局 API 速览脚本全局对象由 scriptmanager.cpp 的initialize()注入包括tiled主模块对象ScriptModule提供version、platform、arch、extensionsPath、projectFilePath、openAssets、activeAsset、mapFormats、tilesetFormats、registerAction、registerTool、extendMenu等声明见 scriptmodule.hTiledScriptModule的元对象静态成员类型构造函数TileMap、Tileset、TileLayer、ObjectGroup、MapObject、Tile、Layer、GroupLayer、ImageLayer、WangSet、WangIndex、Image、AssetType、BlendModeQtQt 命名空间Qt.size、Qt.point、Qt.rect等配合ScriptModule中的cell()、filePath()、objectRef()、color()等工厂方法使用辅助模块Base64、Dialog、File、FileInfo、Geometry、Process以及属性类型注册分别对应registerBase64、registerDialog、registerFile、registerFileInfo、registerGeometry、registerProcess、registerPropertyTypes。每个类型都在 scriptmanager.cpp 中通过qRegisterMetaType注册为元类型确保信号回调中的参数传递正确。完整属性与方法清单以 docs/scripting-doc/index.d.ts 为准该文件 5900 余行覆盖tiled、TileMap、TileLayer、Tileset、region、rect等全部 API 与since版本标注。从源码理解脚本模块的完整生命周期ScriptManager是脚本引擎与模块的单例管理者其生命周期scriptmanager.cpp初始化ensureInitialized()首次调用时创建QQmlEngine与ScriptModule注入全部全局对象随后loadExtensions()加载所有扩展运行控制台、命令行、动作/工具回调均通过同一个引擎执行ScriptModule构造时scriptmodule.cpp若存在DocumentManager会连接documentCreated、documentOpened、documentSaved、currentDocumentChanged等信号供脚本注册监听实现自动化热重载文件变化触发reset()重建引擎与模块重新加载扩展清理ScriptModule析构时scriptmodule.cpp注销所有脚本注册的动作、清理菜单扩展、移除 Issue 上下文并关闭所有脚本对话框。依赖关系为ProjectManager提供项目扩展路径与可选的DocumentManager提供文档信号与当前活动资产见 scriptmanager.h。上手建议从 Console 起步打开 Console 视图输入tiled.version、tiled.mapFormats验证环境再尝试tiled.open()打开地图并修改建立扩展目录按上文平台对照表创建系统级extensions目录或用 Tiled 新建项目并让其自动创建extensions子目录编写首个扩展在扩展目录放入my-extension.js用tiled.registerAction注册一个动作指定id、回调与菜单/工具栏位置或tiled.registerTool注册一个自定义工具保存文件后 Tiled 会自动热重载无需重启利用类型定义安装mapeditor/tiled-api类型包以获得编辑器自动补全需要模块化时改用.mjs用import/export拆分代码避免全局命名冲突自动化批处理走命令行用tiled --evaluate script.js [args]在无 UI 环境下批量读写地图与图块集配合tiled.scriptArguments传参。参考路径官方手册docs/manual/scripting.rst类型定义与 API 参考源docs/scripting-doc/index.d.ts脚本引擎管理src/tiled/scriptmanager.cpp、src/tiled/scriptmanager.h脚本主模块src/tiled/scriptmodule.cpp、src/tiled/scriptmodule.h脚本化动作与工具src/tiled/scriptedaction.h、src/tiled/scriptedtool.h命令行入口src/tiledapp/main.cpp项目文件说明docs/manual/projects.rst、偏好设置docs/manual/preferences.rstPython 脚本扩展另一种脚本化途径src/plugins/python/【免费下载链接】tiledFlexible level editor项目地址: https://gitcode.com/gh_mirrors/ti/tiled创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
企业数字化 ERP 产品动态
相关推荐
gbrain 的 perplexity-research 技能：基于大脑上下文的增量式 Web 研究指南 人工智能RAGAgent 记忆MCP 服务知识管理 【免费下载链接】gbrain Garrys Opinionated OpenClaw/Hermes Agent Brain 项目地址： https://gitcode.com/gh_mirrors/gb/gbrain 点击查看 免费下载 本文围绕 gbrain 技能库中的 skills/perplexity-research/SKILL.md 展开… · 2026/9/23 2:48:49
基于Matlab GUI的汽车零部件设计计算系统开发 1. 项目概述作为一名在汽车工程领域摸爬滚打多年的工程师，我深知零部件设计计算这个环节有多让人头疼。记得刚入行时，光是计算一根传动轴的强度就要翻遍各种手册，在Excel里反复核对公式，稍不留神就会出错。直到后来接触到Matlab G… · 2026/9/23 2:48:43
Flutter与OpenHarmony开发剧本杀组队App表单实践 1. 项目背景与核心需求剧本杀作为当下年轻人最热衷的社交娱乐方式之一，线下组队的需求日益增长。传统的微信群、QQ群组队方式存在信息杂乱、效率低下等问题。我们团队基于OpenHarmony和Flutter技术栈开发的剧本杀组队App，正是为了解决这一痛点。在完成基… · 2026/9/23 2:48:43
科沃斯X12S PRO实测：从扫拖到托管，真正解放双手的地面清洁体验 如果你问我，过去两年里扫地机器人最值得关注的变化是什么，我的答案不是导航精度提高了多少，也不是吸力又翻了几倍，而是“托管能力”。科沃斯X12S PRO这台机器，从命名到宣传口径，都在刻意强调同一个词&#… · 2026/9/23 3:35:15
AI判断也能写if语句？置信度路由让模型输出变成可控逻辑 1. 别把AI当黑盒：先理解「置信度路由」到底解决了什么问题先说个我自己的经历。早先做一个文本分类项目，模型同时要判断用户提问的意图、情绪，还要抽取出关键实体。按照常规做法，我写了三个独立的函数，每个函数单独调一… · 2026/9/23 3:35:15
金蝶kis迷你版5大避坑指南附完整示例 金蝶kis迷你版5大避坑指南附完整示例 官方文档翻了三遍还是配不平账？别急，金蝶kis迷你版的逻辑确实反直觉。 很多老会计被这套系统坑得够呛，尤其是数据迁移和凭证生成环节。 这篇干货直接给你5个高频报错的 完整示例… · 2026/9/23 3:35:09
降AI率工具全面测评：十大工具实测对比与底层逻辑解析 1. 为什么要降AI率？先把这个事说透先说个可能让你不太舒服的事实：现在大学里交论文、交课程报告，老师最先看的往往不是你写了什么，而是你的文字“像不像人写的”。2026年了，AI写作早就渗透进本科生的日常，从… · 2026/9/23 3:35:09
PowerSploit Recon 模块 Get-DomainDFSShare 深度解析：枚举域内分布式文件系统共享 PowerSploit Recon 模块 Get-DomainDFSShare 深度解析：枚举域内分布式文件系统共享 【免费下载链接】PowerSploit PowerSploit - A PowerShell Post-Exploitation Framework 项目地址: https://gitcode.com/gh_mirrors/po/PowerSploit
导读
Get-DomainDFSSh… · 2026/9/23 3:35:02
YOLO遥感油罐检测数据集全解析：标签格式转换与训练避坑指南 简介：面向YOLO目标检测学习者与遥感图像分析人员，这份遥感油罐检测数据集来自真实场景，图片质量高、场景丰富，使用LabelImg标注且框体质量高，可直接用于YOLOv5、YOLOv8等主流目标检测模型的训练与算法效果验证。压缩包… · 2026/9/23 3:35:02
3招搞定手机怎么下载微信面试难题实战项目解析 3招搞定手机怎么下载微信面试难题实战项目解析 面试被问“手机怎么下载微信”背后的原理，90%的人答不上来。别笑，这看似弱智的问题，实则是考察你对移动应用分发机制、安全校验及网络协议理解的试金石。我带过不少校招新人，他们背了八股文，却连一个A… · 2026/9/23 0:00:03
你有新短消息请注意查收：3个新手避坑指南搞定消息系统选型 你有新短消息请注意查收：3个新手避坑指南搞定消息系统选型 面试被问“高并发下如何保证消息不丢失”，你张口就是“用Redis”，结果面试官追问“如果Redis宕机了怎么办”，你瞬间卡壳。这种场景太常见了，很多新手在背八股文时，只记住了技术名词… · 2026/9/23 0:00:29
