Dota 2 自定义地图开发手册

这是一套面向 Dota 2 自定义地图开发者和 AI 编程助手的开源开发手册。内容覆盖从 Workshop Tools 环境、Hammer 地图、Lua/KV、Panorama UI 到测试、性能、版本控制和 Steam Workshop 发布的完整流程。

仓库同时提供两个可直接复用的入口：

• 开发手册 / 远程 Skill：以 SKILL.md 为 AI 入口，按任务加载 references/ 中的必要章节。
• 地图项目模板：通过 dota2-addon-template 创建独立项目，或从 Releases 下载版本化 ZIP。

当前状态：文档、模板和脚本已通过静态检查；核心示例尚未在当前版本 Dota 2 Workshop Tools 中完成全流程实机验证。请保留各章节的验证标签，不要把“静态核对”视为“已在游戏内运行”。

从这里开始

你的目标	推荐入口
完全零基础，不知道从哪里开始	Dota 2 地图开发新手导航
第一次了解完整开发流程	完整开发流程
安装工具并创建第一个 Addon	环境与项目创建
立即创建一个最小项目	最小 Addon 脚手架
从 GitHub 创建可独立维护的地图仓库	dota2-addon-template
让 AI 编写、修改或排查地图代码	SKILL.md 和 完整使用说明
对现有 Addon 做静态检查	Addon 静态检查
查看所有必须人工完成的操作	人工操作清单
在 Workshop Tools 中执行首次验收	实机验证运行手册

五分钟快速开始

1. 创建项目仓库

打开 Dota 2 Addon Template，点击 Use this template 创建自己的仓库，然后克隆到本机。

2. 初始化内部名

在新仓库根目录运行：

powershell -NoProfile -ExecutionPolicy Bypass -File ./scripts/initialize-addon.ps1 `
  -AddonName "my_custom_game"

内部名只能包含小写字母、数字和下划线，必须以字母开头，长度为 3 到 64 个字符。初始化只能执行一次；检查失败时脚本会恢复本次修改。

3. 接入 Workshop Tools

模板中的目录与实际 Addon 目录按以下方式对应：

模板仓库/game/     -> <DOTA_ROOT>/game/dota_addons/my_custom_game/
模板仓库/content/  -> <DOTA_ROOT>/content/dota_addons/my_custom_game/

先在 Workshop Tools 中创建或确认同名 Addon，再合入模板文件。不要覆盖未提交的地图或工具生成文件。详细步骤、目录变量和两种接入方式见 完整使用说明。

4. 运行静态检查

powershell -NoProfile -ExecutionPolicy Bypass -File ./scripts/check-addon.ps1 `
  -GameAddonPath ./game `
  -ContentAddonPath ./content

静态检查通过后，仍需在 Hammer 和 Dota 2 中完成构建、启动和多人场景验证。

作为 AI Skill 使用

支持读取 GitHub 仓库的 AI 助手可以直接使用以下提示：

请把 https://github.com/NameForTac/dota2-map-development-guide
作为 Dota 2 自定义地图开发 Skill 使用。
先读取 SKILL.md，再只读取与当前任务相关的 references 文件。
请先检查我的目标 Addon，不要猜测路径或未核验的 Dota 2 API。

目标项目：<本地路径或仓库地址>
任务：<要实现或排查的内容>

如果 AI 工具不能访问 GitHub，先克隆本仓库，再把本地目录和目标 Addon 目录一并提供给它。不同 AI 产品的 Skill 安装与发现方式可能不同，因此仓库不假定某一条全局安装命令；显式要求读取 SKILL.md 是最通用的入口。

更多实现、排错和代码审查提示词见 完整使用说明。

手册目录

基础与生产流程

• 完整开发流程
• 开发环境与项目创建
• 项目目录及文件加载关系
• 原型、垂直切片、测试与发布里程碑
• 版本控制、协作与发布管理
• 版本兼容、迁移与 Dota 更新回归

地图、玩法与服务端

• Hammer 地图开发
• Hammer 实体、触发器与脚本协作
• 关卡设计、地形、光照与地图美术
• Lua、游戏规则与事件
• Lua 架构、模块与生命周期
• KV 配置
• 技能、物品、单位与 Modifier
• 完整游戏模式与比赛状态机
• 英雄、单位、生成与生命周期
• 物品、商店与经济系统
• 战斗、伤害、命令与投射物
• 单位 AI、刷怪与寻路
• 数据驱动设计、配置与内容模板

客户端、资源与在线系统

• Panorama UI
• 客户端与服务端通信
• 选人、准备、计分板与结算 UI 数据流
• 镜头、输入与玩家控制
• 资源与本地化
• 本地化与文本工作流
• 粒子、声音与反馈系统
• 资源预载、加载与首帧体验
• 存档、外部服务与安全边界
• 观战、活动与自定义赛事支持
• 可访问性、玩家安全与社区体验

调试、验证与发布

• 调试与性能优化
• 性能基准、分析与回归
• Playtest、反馈与平衡迭代
• Workshop Tools、控制台与诊断工作流
• 客户端滥用、作弊防护与服务端权威
• 打包与发布
• 资料来源与实机验证台账
• 最小 Addon 与完整技能示例

仓库结构

.
|-- README.md          # 项目说明与快速入口
|-- 新手导航.md  # 零基础第一张地图学习路线
|-- 使用说明.md           # 面向开发者和 AI 的完整使用方法
|-- 人工操作清单.md   # Steam、工具、测试和发布的人工操作清单
|-- SKILL.md           # AI 助手入口、任务路由和执行规则
|-- 开发计划.md            # 整改、验证与待办台账
|-- references/        # 按主题拆分的开发知识
|-- examples/          # 跨文件示例
|-- scripts/           # 检查、脚手架、模板导出和发布脚本
|-- assets/            # 最小 Addon 与模板仓库源文件
`-- tests/             # 静态检查测试夹具

验证与维护

验证标签含义：

• 已实机验证：已在标注日期和版本的 Workshop Tools 中执行。
• 脚本验证 / 静态核对：结构、代码关系或自动测试通过，但尚未在游戏内运行。
• 待复核：工具界面、命令、字段或行为可能随 Dota 2 更新变化。

检查本仓库：

powershell -NoProfile -ExecutionPolicy Bypass -File ./scripts/check-docs.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File ./scripts/test-check-addon.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File ./scripts/test-new-addon-scaffold.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File ./scripts/test-export-addon-template.ps1

贡献版本敏感内容前，请阅读 贡献与核验规范。问题可通过 GitHub Issues 提交；安全问题请遵循 SECURITY.md。

许可证

根目录、references/ 和 examples/ 中的文档采用 CC BY 4.0；脚本、模板、测试、GitHub 配置、Skill 元数据及文档内代码示例采用 MIT。详见 LICENSE。Valve 与 Dota 2 的商标和游戏资源不包含在这些授权中。