| name | dota2-item |
| description | Dota 2 自定义物品编写指南。触发词：物品、item、装备、道具、配方、recipe、合成。 |
为 DOTA2 自定义游戏项目编写自定义物品。
game/scripts/npc/ 下的 KV 文件的 AbilityValues 中。通过 this.GetSpecialValueFor('键名') 在 TSTL 中读取，禁止在代码中硬编码任何可能变化的配置值。修改配置后需运行 npx gulp kv_2_js 刷新 JSON，保证前后端数据一致| 文件 | 路径 | 用途 |
|---|---|---|
| 物品 KV | game/scripts/npc/items_list/<物品名>.txt | 物品 KV 键值对（手动创建的自定义物品） |
| KV 入口 | game/scripts/npc/npc_items_custom.txt | 引用 #base "items_list.txt"，自动生成部分由 Excel 管理 |
| Excel 数据 | excels/物品表.xlsx | 自动生成 items_list.txt（请勿手动修改） |
| 物品源码 | game/scripts/src/abilities/<模块名>/<物品名>.ts | TSTL 物品逻辑（物品继承 BaseItem） |
| 本地化 | game/resource/addon.csv | 物品名称、描述、数值标签 |
在 game/scripts/npc/items_list/<物品名>.txt 中创建 KV 文件，或在 excels/物品表.xlsx 中添加行（由 Gulp 自动生成到 items_list.txt）。
KV 文件必须在 npc_items_custom.txt 中通过 #base 引用后生效。
物品名必须以 item_ 开头。
KV 结构规则：物品名称必须在第一级，所有属性写在第二级的 {} 内：
"item_custom_sword"
{
"BaseClass" "item_lua"
"AbilityBehavior" "DOTA_ABILITY_BEHAVIOR_PASSIVE"
"ItemCost" "2150"
"ItemQuality" "rare"
"AbilityTextureName" "item_custom_sword"
}
修改 KV 文件后，必须运行以下命令将 KV 编译为 JSON，供前后端统一引用：
# 编译所有 KV 文件为 JSON
npx gulp kv_2_js
# 或快捷命令（同时执行 sheet→kv 和 kv→js）
npx gulp jssync
编译后输出到：
content/panorama/src/json/ — 前端 Panorama 使用game/scripts/src/json/ — 后端 TSTL 使用前后端数据分离原则：
如果物品有自定义行为（包括纯被动），在 game/scripts/src/abilities/<模块名>/<物品名>.ts 中：
dota_ts_adapter 导入 BaseItem、registerAbility@registerAbility() 装饰器注册物品类，继承 BaseItemOnSpellStart、OnChannelFinish 等）this.GetSpecialValueFor('键名') 读取 KV 中的 AbilityValues.ts 文件中，不需要单独建文件；只有独立的、机制性的 modifier（不被任何技能/物品直接引用，如通用抛物线运动、通用buff，或者多个技能共用的modifier等）才需要单独放在 src/modifiers/ 目录下在 game/resource/addon.csv 中添加：
DOTA_Tooltip_ability_item_<物品名> → 物品显示名DOTA_Tooltip_ability_item_<物品名>_Description → 物品描述DOTA_Tooltip_ability_item_<物品名>_<AbilityValues键名> → 数值标签物品继承所有技能的 KV 键，此外还有物品专属键。
| 键名 | 说明 | 示例值 |
|---|---|---|
BaseClass | 基类 | item_lua |
AbilityBehavior | 行为类型 | DOTA_ABILITY_BEHAVIOR_PASSIVE / DOTA_ABILITY_BEHAVIOR_NO_TARGET | DOTA_ABILITY_BEHAVIOR_ITEM |
AbilityTextureName | 图标名称 | item_magic_wand |
MaxLevel | 最大等级 | 1 / 3 |
AbilityCooldown | 冷却 | 12 |
AbilityManaCost | 魔法消耗 | 100 |
AbilityCastRange | 施法距离 | 600 |
AbilityCastPoint | 施法前摇 | 0.0 |
AbilityUnitTargetTeam | 目标队伍 | DOTA_UNIT_TARGET_TEAM_ENEMY |
AbilityUnitTargetType | 目标类型 | DOTA_UNIT_TARGET_HERO | DOTA_UNIT_TARGET_BASIC |
AbilityUnitDamageType | 伤害类型 | DAMAGE_TYPE_MAGICAL |
ScriptFile | 脚本路径 | abilities/<模块名>/item_custom.lua |
AbilityValues | 自定义数值 | （子键） |
Precache | 预缓存 | （子键：particle、soundfile、model） |
| 键名 | 说明 | 示例值 |
|---|---|---|
ItemCost | 物品价格 | 2150 |
ItemShopTags | 商店标签 | damage;attack_speed |
ItemQuality | 物品品质 | component / common / rare / epic / secret_shop / consumable |
ItemAliases | 别名 | tp;town portal scroll;teleport |
ID | 唯一 ID | 3003 |
| 键名 | 说明 | 示例值 |
|---|---|---|
ItemStackable | 是否可堆叠 | 1 |
ItemInitialCharges | 初始充能数 | 1 |
ItemRequiresCharges | 需要充能 | 1 |
ItemDisplayCharges | 显示充能数 | 1 |
ItemPermanent | 永久物品 | 0 |
ItemShareability | 共享性 | ITEM_FULLY_SHAREABLE / ITEM_PARTIALLY_SHAREABLE / ITEM_NOT_SHAREABLE |
ItemDeclares | 物品声明 | DECLARE_USAGE_BOT |
ItemCanBeDisassembled | 可拆分 | 1 |
ItemCanBeSoldByPlayer | 玩家可出售 | 0 |
| 键名 | 说明 | 示例值 |
|---|---|---|
SecretShop | 秘密商店 | 1 |
SideShop | 边路商店 | 1 |
IsObsolete | 是否过时 | 1 |
SuggestPregame | 建议出门装 | 1 |
SuggestEarlygame | 建议前期装 | 1 |
SuggestLategame | 建议后期装 | 1 |
| 键名 | 说明 | 示例值 |
|---|---|---|
ItemRecipe | 是否为配方 | 1 |
ItemResult | 合成结果 | item_bfury |
ItemRequirements | 合成需求 | "01" "item_broadsword;item_mithril_hammer" |
UpgradesItems | 升级物品 | item_boots |
UpgradeRecipe | 升级配方 | 1 |
MaxUpgradeLevel | 最大升级等级 | 3 |
SubAbilityNames | 子技能名称 | ability1;ability2 |
ReplaceAbility | 替换技能 | ability_name |
| 键名 | 说明 | 示例值 |
|---|---|---|
Model | 模型路径 | models/props_gameplay/quelling_blade.vmdl |
Effect | 效果 | particles/... |
UIDropSound | 丢弃声音 | Item.Drop |
UIPickupSound | 拾取声音 | Item.PickUp |
WorldDropSound | 世界丢弃声音 | Item.WorldDrop |
PingOverrideText | Ping 覆盖文本 | #DOTA_Ping_GG |
| 键名 | 说明 | 示例值 |
|---|---|---|
SpeciallyAllowedInNeutralSlot | 允许放入中立物品栏 | 1 |
SpeciallyBannedFromNeutralSlot | 禁止放入中立物品栏 | 1 |
ShouldNotSuggestMainGame | 主模式不推荐 | 1 |
ShowDroppedItemTooltip | 显示掉落提示 | 1 |
ShowGiveIndicatorOnTargetCast | 显示给与指示 | 1 |
TokenTier | 代币等级 | 1 / 2 / 3 / 4 / 5 |
| 常量 | 说明 |
|---|---|
ITEM_FULLY_SHAREABLE | 完全共享 |
ITEM_PARTIALLY_SHAREABLE | 部分共享 |
ITEM_NOT_SHAREABLE | 不可共享 |
| 常量 | 说明 |
|---|---|
component | 组件 |
common | 普通 |
rare | 稀有 |
epic | 史诗 |
secret_shop | 秘密商店 |
consumable | 消耗品 |
| 装饰器/基类 | 用途 |
|---|---|
@registerAbility() | 注册物品类（物品也使用此装饰器） |
BaseItem | 物品基类，所有的物品类都需要继承 |
| 方法 | 用途 |
|---|---|
OnSpellStart() | 使用物品时 |
OnAbilityPhaseStart() | 使用前摇阶段（返回 bool） |
OnChannelFinish(bInterrupted) | 持续施法结束 |
GetBehavior() | 获取行为类型 |
GetSpecialValueFor(key) | 读取 AbilityValues 中的值 |
Precache(context) | 预缓存资源 |
GetCooldown(level) | 获取冷却 |
GetManaCost(level) | 获取魔法消耗 |
GetCurrentCharges() | 获取当前充能数 |
SetCurrentCharges(charges) | 设置充能数 |
GetCost() | 获取物品价格 |
GetPurchaseTime() | 获取购买时间 |
GetPurchaser() | 获取购买者 |
IsCombineLocked() | 是否锁定合成 |
SetCombineLocked(bLocked) | 锁定/解锁合成 |
| 方法 | 用途 |
|---|---|
OnItemEquipped(hUnit) | 装备时 |
OnItemUnequipped(hUnit) | 卸下时 |
OnItemPurchased() | 购买时 |
OnItemSold() | 出售时 |
OnItemSpawned() | 物品生成时 |
DOTA2 自定义游戏服务端逻辑开发指南。触发词：游戏逻辑、服务端、server、game mode、游戏模式、GameRules、modifier、timer、lua、TSTL。Use when user asks to create or modify DOTA2 custom game server-side logic, game mode configuration, modules, game events, net tables, or data synchronization.
Dota 2 自定义技能编写指南。触发词：技能、ability、spell、被动、主动。
DOTA2 自定义游戏 UI（Panorama）开发指南。触发词：UI、界面、面板、panorama、frontend、前端、HUD、layout、xml、css、样式。Use when user asks to create or modify DOTA2 custom game UI panels, React components, CSS styles, layout XML, game events communication, or net table data binding.
Dota 2 自定义单位编写指南。适用于编写/修改单位 KV 配置文件（`game/scripts/npc/custom_units/`）。触发词：单位、unit、creature、怪物、召唤物、建筑、塔、npc。
为 DOTA2自定义游戏 项目生成 Dota 2 本地化文本（addon.csv）。触发词：本地化、翻译、loc、i18n、addon.csv、文本、tooltip、多语言。Use when user asks to generate localization entries for abilities/units/items/modifiers, translate Chinese to English based on character width balance, or add entries to game/resource/addon.csv.