dota2-custom-game-dev

DOTA2 自定义游戏开发

将此技能用于 DOTA2 自定义游戏插件开发，涵盖 Lua、TypeScriptToLua/TSTL、SolidJS Panorama UI、Panorama JS/TS、Panorama CSS/XML、KV 文件，以及 Dota 2 MCP 工具可用时对 Dota 2 实时运行环境的检查。

参考资料来源

运行环境支持时，优先使用实时 Dota2 MCP 工具。MCP 工具不可用、Dota 2 未运行，或用户只需要离线源码处理时，使用打包的 BigCiba/vscode-dota2-tools 快照。

• 上游仓库：https://github.com/BigCiba/vscode-dota2-tools
• 本地源映射：references/upstream-source-map.md
• TSTL DOTA2 指南：references/tstl-dota2.md
• SolidJS Panorama 指南：references/solid-panorama-ui.md
• 刷新脚本：scripts/update_references.ps1
• API 搜索辅助工具：scripts/search_dota2_api.py
• TSTL 项目检测器：scripts/detect_tstl_project.py
• SolidJS Panorama 检测器：scripts/detect_solid_panorama_project.py

不要将打包的参考资料视为永久准确的信息。它们只是快照；用户询问最新 API 行为或 API 准确性很重要时，应从上游刷新。

Dota2 MCP 工作流

仅在实时游戏证据有助于测试插件、检查游戏内行为、读取控制台错误、启动地图或检查当前运行状态时，才使用 Dota2 MCP。普通源码编辑不应以 MCP 为前提。

进行实时测试/调试时，先调用 dota_status。它会报告连接、插件/地图状态以及下一步建议。如果客户端提供的是 project_info 而非 dota_status，则将 project_info 用作状态查询的备用选项。

优先采用快速运行时循环：编辑源码，让仓库的构建/监视命令进行编译，在实时游戏中重新加载，然后用 MCP 验证。不要仅为加载常规代码编辑而调用 dota_restart；如果插件支持，可使用 console_send 执行 reload_script 等项目重载命令。

除非用户要求进行实时调试/测试，否则不要修改实时游戏状态、发送破坏性控制台命令或运行任意服务器端 Lua。普通源码编辑时，先阅读项目文件，并仅将 MCP 输出用作证据。

项目模型

首先确定插件根目录：

• 游戏脚本：game/scripts/vscripts/
• NPC/KV 配置：game/scripts/npc/
• Panorama 布局：content/panorama/layout/custom_game/
• Panorama JS：content/panorama/scripts/custom_game/
• Panorama CSS：content/panorama/styles/custom_game/
• 本地化：game/resource/
• 存在时的 TSTL 源码：src/vscripts/、src/panorama/、src/common/
• 存在时的 SolidJS Panorama 源码：solid/src/ui/、solid/src/components/、solid/src/utils/

如果项目布局不同，则搜索 addon_game_mode.lua、npc_abilities_custom.txt、custom_net_tables.txt、custom_events.txt、custom_ui_manifest.xml、layout/custom_game、package.json、tsconfig.json、tstl、solid/build.ts 和 solid/src/ui。

对于 TSTL 项目，检查生成的 Lua，但编辑 TypeScript 源码。除非用户明确要求紧急修补生成的输出，否则不要修改 game/scripts/vscripts/ 下生成的 Lua。

对于 SolidJS Panorama 项目，检查生成的 JS/XML/CSS，但编辑 Solid TSX、Less/SCSS、声明文件或构建脚本。除非用户明确要求紧急修补生成的输出，否则不要修改生成的 Panorama 资源。

API 查询工作流

优先使用 Dota2 MCP API 工具查询实时/当前 API 行为。如果 MCP 不可用，优先通过打包的脚本进行定向查询，而不是直接读取大型 JSON 文件。从此技能目录运行示例；如果当前工作目录不同，则将 .\scripts 替换为解析后的技能目录路径。

python .\scripts\search_dota2_api.py --kind lua --query CustomGameEventManager
python .\scripts\search_dota2_api.py --kind js --query SendCustomGameEventToServer
python .\scripts\search_dota2_api.py --kind css --query flow-children
python .\scripts\search_dota2_api.py --kind panel --query DOTAAbilityImage
python .\scripts\detect_tstl_project.py <path-to-addon>
python .\scripts\detect_solid_panorama_project.py <path-to-addon>

参考资料缺失或过时时，从此技能目录刷新：

powershell -ExecutionPolicy Bypass -File .\scripts\update_references.ps1

边界

• 服务端 Lua 是权威来源。不要信任 Panorama 客户端载荷中的经济、伤害、库存、奖励、冷却时间或胜利条件。
• Panorama JS 是客户端 UI 逻辑。它可以向服务端发送意图、从自定义网络表读取公开状态并更新面板，但必须由服务端 Lua 进行验证。
• KV 文件定义数据和引擎绑定。请根据 Lua 和 Panorama 中的用法，核实 ScriptFile、BaseClass、AbilitySpecial、修饰器名称和本地化令牌。
• CSS 是 Panorama CSS，不是浏览器 CSS。使用现代 Web CSS 前，请先查阅 DOTA2 CSS 参考。
• XML 面板是 Panorama 面板，不是 DOM 元素。假定其语义与浏览器一致之前，请先检查面板专属属性和事件。
• TSTL 的更改应保留生成的 Lua 语义。请注意 this、多返回值、Lua 数组/表、装饰器、模块导入，以及依赖 Lua 冒号调用行为的 API。
• 在 TSTL 模板项目中，生成的 Lua 和 Panorama JS 是构建产物。请优先修改 src/**/*.ts，然后运行仓库的构建/类型检查命令。
• SolidJS Panorama 不是浏览器 DOM 开发。组件会渲染到 Panorama 面板中，使用 Panorama 事件/属性，并且必须遵守 Panorama CSS/XML 的限制。
• Solid 效果和订阅必须使用 onCleanup 或项目的辅助工具，清理 GameEvents、CustomNetTables、计时器和面板处理程序。

常见工作流

处理 Lua 技能或修饰器时：

1. 查找 KV 条目和 ScriptFile。
2. 检查 Lua 类名、LinkLuaModifier、内置修饰器以及特殊值读取。
3. 如果有可用的 Dota2 MCP API/运行时工具，请使用；否则搜索 Lua API 快照，查找引擎调用。
4. 验证服务端/客户端边界和权限。

处理 TSTL vscripts 时：

1. 运行或模拟 scripts/detect_tstl_project.py，查找 package.json、tsconfig.json、TSTL 软件包以及源码/输出根目录。
2. 更改 TypeScript 语义前，先阅读 references/tstl-dota2.md。
3. 从 KV 的 ScriptFile 跟踪到生成的 Lua，再回溯到 src/vscripts/**/*.ts。
4. 优先修改 TypeScript 源码，并根据项目实际情况，使用仓库脚本进行验证，例如 npm run build、npm run build:vscripts、npm run dev 或 npx tstl -p tsconfig.json。
5. 进行实时验证时，优先使用 watch/build，配合 console_send(commands="reload_script") 和 console_output(channel="VScript", level=3)；之后再重启地图。
6. 如果构建命令需要依赖或网络，请先征求许可，或明确报告缺少的依赖。

处理 Panorama UI 时：

1. 定位 XML、JS、CSS 和 custom_ui_manifest.xml。
2. 搜索 JS API，查找 GameEvents、CustomNetTables、Players、Entities 或 Abilities。
3. 搜索 CSS 和面板引用，检查不受支持的属性或错误的面板属性。
4. 通过 CustomGameEventManager 和 GameEvents 跟踪 JS 与 Lua 之间的事件流。
5. 如果有可用的实时 MCP 工具，请使用 console_output 并指定 PanoramaScript，再配合 Panorama API/CSS/事件工具，确认运行时错误和受支持的 UI API。

处理 SolidJS Panorama UI 时：

1. 运行或模拟 scripts/detect_solid_panorama_project.py，查找 package.json.panorama、Solid 依赖、源码根目录、构建脚本和输出根目录。
2. 更改 Solid 渲染、响应性、生成的 XML/CSS 或清单行为前，先阅读 references/solid-panorama-ui.md。
3. 从 package.json.panorama 跟踪 UI 入口至 solid/src/ui/<name>/<name>.tsx，再跟踪至生成的 content/<addon>/panorama/scripts/custom_game/<name>.js、布局 XML、样式和 custom_ui_manifest.xml。
4. 优先修改 TSX/Less/SCSS/声明文件/构建插件源码，并使用 npm run build:solid 或项目对应命令进行验证。
5. 遵守 DOTA2 信任边界：Solid/Panorama 可以发送意图并渲染复制的状态，但服务端 vscripts 始终具有权威性。

处理同步错误时：

1. 判断状态应通过推送事件、网络表，还是仅本地 UI 状态来处理。
2. 在 Lua 中检查 CustomGameEventManager:RegisterListener、CustomNetTables:SetTableValue 和玩家验证。
3. 在 JS 中检查 GameEvents.Subscribe、GameEvents.SendCustomGameEventToServer 和 CustomNetTables.SubscribeNetTableListener。
4. 如果有可用的实时 MCP 工具，请检查控制台输出、实体/修饰器以及安全的 Lua 表达式，以确认实际运行时状态。
5. 分别报告过期状态、信任边界和生命周期风险。

输出

解释 API 或修复代码时，请包含：

• 涉及的层：Lua 服务端、Panorama JS、CSS/XML、KV 或本地化。
• 使用的确切项目文件和 API 参考。
• 任何服务端/客户端信任边界。
• 代码是 TypeScript 源码，还是生成的 Lua/JS。
• 是否修改了 SolidJS Panorama 源码或生成的 Panorama 资源。
• 是否使用了 Dota2 MCP 实时证据；如果工作改用捆绑的/离线参考资料，请说明原因。
• 如果当前轮次未刷新捆绑的快照，请说明参考资料可能过时。