dota2-custom-game-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DOTA2 Custom Game Dev

DOTA2自定义游戏开发

Use this skill for DOTA2 custom game addon work across Lua, TypeScriptToLua/TSTL, SolidJS Panorama UI, Panorama JS/TS, Panorama CSS/XML, KV files, and live Dota 2 runtime inspection when Dota2 MCP tools are available.

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

Reference Source

参考来源

Prefer live Dota2 MCP tools when the runtime exposes them. Use bundled

BigCiba/vscode-dota2-tools

snapshots when MCP tools are unavailable, Dota 2 is not running, or the user only needs offline source work.

Upstream repo:

https://github.com/BigCiba/vscode-dota2-tools

Local source map:
```
references/upstream-source-map.md
```
TSTL DOTA2 guide:
```
references/tstl-dota2.md
```
SolidJS Panorama guide:
```
references/solid-panorama-ui.md
```
Refresh script:
```
scripts/update_references.ps1
```
API search helper:
```
scripts/search_dota2_api.py
```
TSTL project detector:
```
scripts/detect_tstl_project.py
```

SolidJS Panorama detector:

scripts/detect_solid_panorama_project.py

Do not treat the bundled references as permanent truth. They are snapshots and should be refreshed from upstream when the user asks for latest API behavior or when API accuracy matters.

当运行时提供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 Workflow

Dota2 MCP工作流程

Use Dota2 MCP only when live game evidence helps: testing an addon, checking in-game behavior, reading console errors, launching a map, or inspecting current runtime state. Do not make MCP a prerequisite for ordinary source edits.

Call

dota_status

first for live testing/debugging. It reports connection, addon/map state, and the next useful step. If the client exposes

project_info

instead of

dota_status

, use

project_info

as the status fallback.

Prefer the fast runtime loop: edit source, let the repo build/watch command compile, reload in the live game, then verify with MCP. Do not call

dota_restart

just to pick up routine code edits; use

console_send

with project reload commands such as

reload_script

when the addon supports them.

Do not mutate live game state, send destructive console commands, or run arbitrary server Lua unless the user asked for live debugging/testing. For ordinary source edits, read project files first and use MCP output only as evidence.

仅当需要实时游戏证据时才使用Dota2 MCP：测试插件、检查游戏内行为、读取控制台错误、启动地图或检查当前运行时状态。不要将MCP作为常规源码编辑的先决条件。

进行实时测试/调试时，首先调用

dota_status

。它会报告连接状态、插件/地图状态以及下一步操作建议。如果客户端提供

project_info

而非

dota_status

，则使用

project_info

作为状态备选方案。

优先使用快速运行时循环：编辑源码，让仓库的构建/监听命令编译，在实时游戏中重新加载，然后通过MCP验证。不要仅为了获取常规代码编辑而调用

dota_restart

；当插件支持时，使用

console_send

执行项目重新加载命令，如

reload_script

。

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

Project Model

项目结构模型

Start by identifying the addon roots:

Game scripts:
```
game/scripts/vscripts/
```
NPC/KV config:
```
game/scripts/npc/
```
Panorama layout:
```
content/panorama/layout/custom_game/
```
Panorama JS:
```
content/panorama/scripts/custom_game/
```
Panorama CSS:
```
content/panorama/styles/custom_game/
```
Localization:
```
game/resource/
```
TSTL source, when present:
```
src/vscripts/
```
,
```
src/panorama/
```
,
```
src/common/
```

SolidJS Panorama source, when present:

solid/src/ui/

solid/src/components/

solid/src/utils/

If the project layout differs, search for

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

, and

solid/src/ui

For TSTL projects, inspect the generated Lua but edit the TypeScript source. Do not patch generated Lua under

game/scripts/vscripts/

unless the user explicitly asks for an emergency generated-output patch.

For SolidJS Panorama projects, inspect generated JS/XML/CSS but edit the Solid TSX, Less/SCSS, declarations, or build scripts. Do not patch generated Panorama assets unless the user explicitly asks for an emergency generated-output patch.

首先识别插件根目录：

游戏脚本：
```
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 Lookup Workflow

API查询工作流程

Prefer Dota2 MCP API tools for live/current API behavior. If MCP is unavailable, prefer targeted lookup through the bundled script instead of reading large JSON files directly. Run examples from this skill directory, or replace

.\scripts

with the resolved path to the skill directory when working from another current directory.

powershell

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>

When references are missing or stale, refresh them from this skill directory:

powershell

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

优先使用Dota2 MCP API工具获取实时/当前API行为。如果MCP不可用，优先通过内置脚本进行定向查询，而非直接读取大型JSON文件。运行本技能目录中的示例，或在其他工作目录时将

.\scripts

替换为技能目录的解析路径。

powershell

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

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

Boundaries

边界规范

Server Lua is authoritative. Do not trust Panorama client payloads for economy, damage, inventory, rewards, cooldowns, or win conditions.
Panorama JS is client UI logic. It can send intent to the server, read public state from custom net tables, and update panels, but server Lua must validate.
KV files define data and engine bindings. Verify
```
ScriptFile
```
,
```
BaseClass
```
,
```
AbilitySpecial
```
, modifier names, and localization tokens against Lua and Panorama usage.
CSS is Panorama CSS, not browser CSS. Check the DOTA2 CSS reference before using modern web CSS.
XML panels are Panorama panels, not DOM elements. Check panel-specific attributes/events before assuming browser semantics.
TSTL changes should preserve emitted Lua semantics. Be careful with
```
this
```
, multi-return values, Lua arrays/tables, decorators, module imports, and APIs that rely on Lua colon-call behavior.
Generated Lua and generated Panorama JS are build artifacts in TSTL template projects. Prefer fixing
```
src/**/*.ts
```
and then running the repo's build/typecheck command.
SolidJS Panorama is not browser DOM work. Components render into Panorama panels, use Panorama events/attributes, and must respect Panorama CSS/XML limitations.
Solid effects and subscriptions must clean up
```
GameEvents
```
,
```
CustomNetTables
```
, timers, and panel handlers with
```
onCleanup
```
or the project's helper utilities.

服务器端Lua具有权威性。不要信任Panorama客户端负载中的经济、伤害、Inventory（背包）、奖励、冷却时间或胜利条件相关数据。
Panorama JS是客户端UI逻辑。它可以向服务器发送意图、从自定义网络数据表读取公共状态并更新面板，但服务器端Lua必须进行验证。
KV文件定义数据和引擎绑定。验证
```
ScriptFile
```
,
```
BaseClass
```
,
```
AbilitySpecial
```
, Modifier名称和本地化令牌与Lua和Panorama的使用是否一致。
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的Effects和Subscriptions必须通过
```
onCleanup
```
或项目的辅助工具清理
```
GameEvents
```
,
```
CustomNetTables
```
, 计时器和面板处理程序。

Common Workflows

常见工作流程

—

Lua技能或Modifier开发：

For Lua ability or modifier work:

Find the KV entry and
```
ScriptFile
```
.
Inspect Lua class names,
```
LinkLuaModifier
```
, intrinsic modifiers, and special value reads.
Use Dota2 MCP API/runtime tools when available; otherwise search the Lua API snapshot for engine calls.
Validate server/client boundary and authority.

For TSTL vscripts work:

Run or emulate
```
scripts/detect_tstl_project.py
```
to find
```
package.json
```
,
```
tsconfig.json
```
, TSTL packages, and source/output roots.
Read
```
references/tstl-dota2.md
```
before changing TypeScript semantics.
Trace from KV
```
ScriptFile
```
to generated Lua and then back to
```
src/vscripts/**/*.ts
```
.
Prefer source edits in TypeScript and validate with the repository's scripts such as
```
npm run build
```
,
```
npm run build:vscripts
```
,
```
npm run dev
```
, or
```
npx tstl -p tsconfig.json
```
, depending on what exists.

For live verification, prefer watch/build plus

console_send(commands="reload_script")

and

console_output(channel="VScript", level=3)

before restarting the map.

If build commands need dependencies or network, ask for permission or report the missing dependency clearly.

For Panorama UI work:

Locate XML, JS, CSS, and
```
custom_ui_manifest.xml
```
.

Search JS APIs for

GameEvents

CustomNetTables

Players

Entities

, or

Abilities

Search CSS and panel references for unsupported properties or wrong panel attributes.
Trace event flow between JS and Lua through
```
CustomGameEventManager
```
and
```
GameEvents
```
.
When live MCP tools are available, use
```
console_output
```
with
```
PanoramaScript
```
and the Panorama API/CSS/event tools to confirm runtime errors and supported UI APIs.

For SolidJS Panorama UI work:

Run or emulate
```
scripts/detect_solid_panorama_project.py
```
to find
```
package.json.panorama
```
, Solid dependencies, source roots, build scripts, and output roots.
Read
```
references/solid-panorama-ui.md
```
before changing Solid rendering, reactivity, generated XML/CSS, or manifest behavior.

Trace a UI entry from

package.json.panorama

solid/src/ui/<name>/<name>.tsx

, then to generated

content/<addon>/panorama/scripts/custom_game/<name>.js

, layout XML, styles, and

custom_ui_manifest.xml

Prefer source edits in TSX/Less/SCSS/declarations/build plugins and validate with
```
npm run build:solid
```
or the project's equivalent command.
Keep DOTA2 trust boundaries: Solid/Panorama may send intent and render replicated state, but server vscripts remain authoritative.

For synchronization bugs:

Identify whether state should be push event, net table, or local-only UI state.

In Lua, inspect

CustomGameEventManager:RegisterListener

CustomNetTables:SetTableValue

, and player validation.

In JS, inspect

GameEvents.Subscribe

GameEvents.SendCustomGameEventToServer

, and

CustomNetTables.SubscribeNetTableListener

When live MCP tools are available, inspect console output, entities/modifiers, and safe Lua expressions to confirm actual runtime state.
Report stale state, trust boundary, and lifecycle risks separately.

找到KV条目和
```
ScriptFile
```
。
检查Lua类名、
```
LinkLuaModifier
```
、固有Modifier和特殊值读取逻辑。
若Dota2 MCP API/运行时工具可用则使用；否则在Lua API快照中搜索引擎调用。
验证服务器/客户端边界和权威性。

Output

TSTL脚本开发：

When explaining an API or fixing code, include:

Which layer is involved: Lua server, Panorama JS, CSS/XML, KV, or localization.
The exact project files and API references used.
Any server/client trust boundary.
Whether the code is source TypeScript or generated Lua/JS.
Whether SolidJS Panorama source or generated Panorama assets were changed.
Whether Dota2 MCP live evidence was used, or why the work fell back to bundled/offline references.
Any reference freshness caveat if the bundled snapshot was not refreshed in the current turn.

运行或模拟
```
scripts/detect_tstl_project.py
```
以找到
```
package.json
```
,
```
tsconfig.json
```
, TSTL包和源码/输出根目录。
修改TypeScript语义前，阅读
```
references/tstl-dota2.md
```
。
从KV的
```
ScriptFile
```
追踪到生成的Lua，再回溯到
```
src/vscripts/**/*.ts
```
。
优先在TypeScript中编辑源码，并通过仓库脚本验证，如
```
npm run build
```
,
```
npm run build:vscripts
```
,
```
npm run dev
```
或
```
npx tstl -p tsconfig.json
```
，具体取决于项目可用命令。

实时验证时，优先使用监听/构建加上

console_send(commands="reload_script")

和

console_output(channel="VScript", level=3)

，再重启地图。

若构建命令需要依赖或网络，请求许可或清晰报告缺失的依赖。

—

Panorama UI开发：

—

定位XML、JS、CSS和
```
custom_ui_manifest.xml
```
。

在JS API中搜索

GameEvents

CustomNetTables

Players

Entities

或

Abilities

。

在CSS和面板参考中搜索不支持的属性或错误的面板属性。
通过
```
CustomGameEventManager
```
和
```
GameEvents
```
追踪JS与Lua之间的事件流。
若实时MCP工具可用，使用
```
console_output
```
搭配
```
PanoramaScript
```
和Panorama API/CSS/事件工具确认运行时错误和支持的UI API。

—

SolidJS Panorama UI开发：

—

运行或模拟
```
scripts/detect_solid_panorama_project.py
```
以找到
```
package.json.panorama
```
, Solid依赖、源码根目录、构建脚本和输出根目录。
修改Solid渲染、响应式、生成的XML/CSS或清单行为前，阅读
```
references/solid-panorama-ui.md
```
。

从

package.json.panorama

追踪UI入口到

solid/src/ui/<name>/<name>.tsx

，再到生成的

content/<addon>/panorama/scripts/custom_game/<name>.js

, 布局XML、样式和

custom_ui_manifest.xml

。

优先在TSX/Less/SCSS/声明文件/构建插件中编辑源码，并通过
```
npm run build:solid
```
或项目等效命令验证。
遵守DOTA2信任边界：Solid/Panorama可发送意图并渲染复制状态，但服务器端脚本仍具有权威性。

—

同步问题排查：

—

确定状态应为推送事件、网络数据表或本地仅UI状态。

在Lua中检查

CustomGameEventManager:RegisterListener

CustomNetTables:SetTableValue

和玩家验证逻辑。

在JS中检查

GameEvents.Subscribe

GameEvents.SendCustomGameEventToServer

和

CustomNetTables.SubscribeNetTableListener

。

若实时MCP工具可用，检查控制台输出、实体/Modifier和安全Lua表达式以确认实际运行时状态。
分别报告Stale State（过期状态）、信任边界和生命周期风险。

—

输出要求

—

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

涉及的层级：服务器端Lua、Panorama JS、CSS/XML、KV或本地化文件。
使用的具体项目文件和API参考。
任何服务器/客户端信任边界。
代码是TypeScript源码还是生成的Lua/JS。
修改的是SolidJS Panorama源码还是生成的Panorama资源。
是否使用了Dota2 MCP实时证据，或为何退而使用内置/离线参考资料。
若当前回合未刷新内置快照，需说明参考资料的时效性问题。