Design_SubModule/Scripts/Editor/Design_Tools/DESIGN_TOOLS_SKILL.md

策划工具系统 (Design Tools) - AI Skill 文档

概述

策划工具系统是基于Unity Editor的配置数据管理工具集，主要用于编辑xlsx配置表数据，并与美术资源（ArtTableSO）联动显示预览。所有工具通过Unity菜单栏「策划工具」菜单访问。

---

项目结构

代码目录

Assets/Design_SubModule/Scripts/Editor/Design_Tools/
├── BaseDesignToolEditor.cs          # 编辑器基类（Git管理、路径管理、UI框架）
├── ItemConfigEditor.cs              # 道具配置编辑器 (Item.xlsx)
├── Common/
│   └── DesignToolItemPickerWindow.cs # 通用道具选择弹窗（搜索+分页+筛选）
├── Collections/
│   ├── HeadFrameConfigEditor.cs     # 头像框配置 (Avatar.xlsx)
│   ├── HeadConfigEditor.cs          # 头像配置 (Face.xlsx)
│   └── EmojiConfigEditor.cs         # 表情配置 (Emoji.xlsx)
├── DesignSoundEditorWindow/
│   ├── AmbientSoundConfigEditor.cs  # 环境音配置 (Sound.xlsx - AmbientSound)
│   └── SoundItemConfigEditor.cs     # 音效配置 (Sound.xlsx - Sound)
├── Friends/
│   ├── FriendTreasureChestEditor.cs # 宝箱奖励及概率 (FriendTreasure.xlsx - Chest)
│   └── InviteRewardEditor.cs        # 邀请奖励 (Invite.xlsx - Reward)
├── LimitedTimeEvent/
│   └── CatTrickConstEditor.cs       # 小猫戏法常量 (LimitedTimeEvent.xlsx - Const)
└── Scene/
    ├── DecorateCostPlannerEditor.cs  # 装饰消耗规划 (DecorateCost.xlsx)
    ├── IndoorProgressEditor.cs       # 场景进度奖励 (IndoorProgress.xlsx + Item.xlsx)
    └── MaxAreaIdEditor.cs            # 最大场景ID (Constant.xlsx - ConstantInt)

菜单路径

菜单路径	编辑器类	操作的xlsx文件
策划工具/Item配置	ItemConfigEditor	Item.xlsx (Sheet: Item)
策划工具/收藏品/头像框	HeadFrameConfigEditor	Avatar.xlsx (Sheet: Avatar)
策划工具/收藏品/头像	HeadConfigEditor	Face.xlsx (Sheet: Face)
策划工具/收藏品/表情	EmojiConfigEditor	Emoji.xlsx (Sheet: Emoji)
策划工具/好友/好友馈赠/宝箱奖励及概率	FriendTreasureChestEditor	FriendTreasure.xlsx (Sheet: Chest)
策划工具/好友/邀请奖励	InviteRewardEditor	Invite.xlsx (Sheet: Reward)
策划工具/限时活动/小猫戏法常量	CatTrickConstEditor	LimitedTimeEvent.xlsx (Sheet: Const)
策划工具/场景/装饰消耗规划	DecorateCostPlannerEditor	DecorateCost.xlsx (Sheet: DecorateCost)
策划工具/场景/场景进度奖励	IndoorProgressEditor	IndoorProgress.xlsx + Item.xlsx
策划工具/场景/最大场景ID	MaxAreaIdEditor	Constant.xlsx (Sheet: ConstantInt)
策划工具/音效配置/环境音	AmbientSoundConfigEditor	Sound.xlsx (Sheet: AmbientSound + Sound)
策划工具/音效配置/音效	SoundItemConfigEditor	Sound.xlsx (Sheet: Sound)

---

Excel 表格约定

通用格式规则

• 第1行：Key行（列名/字段名，如 Id, Name, IType, Res 等）
• 第2行：备注行（中文说明，程序不读取）
• 第3行起：实际数据行

数据起始行常量

所有编辑器中 DATA_START_ROW = 3（即从第3行开始读写数据）。

xlsx文件位置

所有xlsx文件存放在Docs项目（外部Git仓库）的 config/ 目录下。

主要xlsx结构

Item.xlsx (Sheet: Item)

列名	类型	说明
Id	int	道具唯一ID
Name	string	道具名称
IType	int	道具类型（见IType类型表）
Effect	string	效果数据（格式因IType而异）
Res	string	美术资源引用，格式: "TableName,ItemName" → 对应ArtTableSO的TableName和ArtItemData的Name

IndoorProgress.xlsx (Sheet: IndoorProgress)

列名	类型	说明
Id	int	唯一ID
Scene	int	场景编号
Lv	int	等级/步骤
Item	string	道具奖励JSON: [{"Id":83,"Num":1}]
Emit	string	发射的道具ID: 83
Reward	string	奖励: 83=1
BigReward	string	大奖励: Energy=25 或 Energy=50,PurplePig=1
AreaReward	string	区域奖励JSON: [{"Id":100001,"Num":25}]
Part	int	零件数量

FriendTreasure.xlsx (Sheet: Chest)

列名	类型	说明
第1列	int	Id
第2列	string	Items JSON: [{"Id":83,"Num":1}]
第3列	int	Prob 概率（总和=1000，即千分之）

Avatar.xlsx (Sheet: Avatar)

列名	类型	说明
Id	int	头像框ID
NameKey	string	多语言key
Init	int	是否初始拥有 (0/1)
Icon	int	图标资源ID（对应HeadFrameResource SO中的ArtItemData.Id）
FrameImageScale	float	缩放比例

Face.xlsx (Sheet: Face)

列名	类型	说明
Id	int	头像ID
NameKey	string	多语言key
Init	int	是否初始拥有
Icon	int	图标资源ID（对应HeadResource SO中的ArtItemData.Id）

Emoji.xlsx (Sheet: Emoji)

类似Face.xlsx结构，Icon对应EmojiResource SO。

---

IType 道具类型表

IType	名称	说明
1	能量	Energy
2	星星	Star
3	钻石	Diamond
97	Playroom宠物道具
98	卡牌
99	背包道具
100	棋子	数量最多的类型
101	卡包
102	限时事件	Effect格式: eventId,seconds
103	小猪存钱罐
104	万能卡
105	头像框	Effect关联Avatar.xlsx
106	活动代币
107	竞赛游戏代币
108	Pet Playroom拜访道具
109	表情	Effect关联Emoji.xlsx
110	头像	Effect关联Face.xlsx
111	Playroom装饰
112	Playroom服装
113	Playroom装饰套装
114	Playroom服装套装
115	Playroom道具宝箱
116	活动通行证代币道具

---

美术资源系统 (Art Resource)

核心类

ArtTableSO (ScriptableObject)

路径: Assets/Art_SubModule/Art_Scripts/ArtTableSO.cs

字段	类型	说明
TableId	int	表ID（全局唯一，系统自动分配）
TableName	string	表名称（全局唯一标识符，如 "HeadFrameResource"）
Items	List<ArtItemData>	资源项列表

ArtItemData (Serializable)

路径: Assets/Art_SubModule/Art_Scripts/ArtItemData.cs

字段	类型	说明
Id	int	资源ID（表内唯一）
Name	string	资源名称（唯一，用于查询）
Desc	string	资源描述
Sprite	Sprite	图片资源引用（Editor模式）
SpritePath	string	图片资源路径（Runtime模式）
SpineAsset	SkeletonDataAsset	Spine骨骼资源（Editor模式）
SpineAssetPath	string	Spine资源路径（Runtime模式）
SpineAnimName	string	Spine动画名称

Art_SO 目录结构

Assets/Art_SubModule/Art_SO/
├── art_table_manifest.json         # 资源表全局配置清单
├── Collections/                    # 收藏品资源
│   ├── EmojiResource.asset         # 表情（TableName="EmojiResource"）
│   ├── HeadFrameResource.asset     # 头像框（TableName="HeadFrameResource"）
│   └── HeadResource.asset          # 头像（TableName="HeadResource"）
├── DecorateIcon/                   # 装饰图标资源（按场景区间分组）
│   ├── DecorateIconResource_1_8.asset
│   ├── DecorateIconResource_9_17.asset
│   └── ...（共9个按区间的资源）
├── DecorateScene/                  # 装饰场景资源
│   └── Scene1Resource.asset ~ Scene55Resource.asset
├── Scene/
│   └── SceneExpression.asset
└── Shop/
    ├── ShopBig.asset
    └── ShopOther.asset

Res字段格式

Item.xlsx中的Res字段格式为 "TableName,ItemName"：

• TableName → 对应 ArtTableSO.TableName（全局唯一标识符）
• ItemName → 对应 ArtItemData.Name（表内唯一名称）
• 例如: "HeadFrameResource,frame_001" 表示 TableName="HeadFrameResource" 的 ArtTableSO 中 Name="frame_001" 的 ArtItemData
• 仅选了表但未选Item时: "HeadFrameResource,"（逗号后为空）

历史格式: 旧版本使用 "TableId,ItemId"（数字格式如 "3,15"）。ItemConfigEditor中提供了「迁移Res格式(ID→Name)」按钮，可一键将旧格式转换为新格式。

资源查找流程

Res = "TableName,ItemName"
  → 找到 ArtTableSO (where TableName == TableName)
  → 在 Items 列表中找到 ArtItemData (where Name == ItemName)
  → 获取 Sprite / SpinePath 等资源

ItemConfigEditor中的DrawResField使用三级选择UI：

1. 组(Folder) → Art_SO下的子文件夹（Collections/DecorateIcon等）
2. 表(Table) → 该文件夹下的ArtTableSO
3. Item → 该表中的ArtItemData

---

基类架构 (BaseDesignToolEditor)

继承关系

EditorWindow
├── BaseDesignToolEditor (抽象基类)
│   ├── FriendTreasureChestEditor
│   ├── InviteRewardEditor
│   ├── CatTrickConstEditor
│   ├── AmbientSoundConfigEditor
│   ├── SoundItemConfigEditor
│   ├── DecorateCostPlannerEditor
│   └── MaxAreaIdEditor
│
├── ItemConfigEditor (独立，未继承基类)
├── HeadFrameConfigEditor (独立)
├── HeadConfigEditor (独立)
├── EmojiConfigEditor (独立)
└── IndoorProgressEditor (独立)

基类提供的能力

• docsRootPath 管理和EditorPrefs持久化
• LoadData() 统一加载流程：路径校验 → Git检查/更新 → 分支检查 → 子类LoadConfigData()
• ExecuteGitCommand() Git命令执行
• CheckAndUpdateDocsRepository() Docs仓库fetch/pull/冲突检测
• CheckAndSwitchDesignSubModuleBranch() Design_SubModule分支切换
• 统一UI框架：工具栏、路径选择、加载按钮、底部保存/重载按钮
• GetDocsConfigFilePath(fileName) 拼接Docs配置文件路径

子类必须实现的抽象方法

• GetDocsPathPrefKey() - 返回唯一的EditorPrefs key
• GetWindowTitle() - 窗口标题
• LoadConfigData() - 具体的数据加载逻辑
• DrawDataEditor() - 具体的UI绘制逻辑

子类可选覆盖的虚方法

• GetMinWindowSize() - 窗口最小尺寸（默认1000x600）
• NeedCheckDesignSubModuleBranch() - 是否检查分支（默认true）
• SaveDataToExcel() - 保存到Excel
• ShowBottomButtons() - 是否显示底部按钮（默认true）

---

通用组件

DesignToolItemPickerWindow（道具选择弹窗）

路径: Common/DesignToolItemPickerWindow.cs

功能：弹出模态窗口，供用户在大量道具中快速查找并选择
使用方式：

DesignToolItemPickerWindow.ShowWindow(
    items,          // List<DesignToolItemPickerItem> 所有道具
    itemTypes,      // List<int> 所有IType列表
    typeNames,      // Dictionary<int,string> IType名称映射
    currentType,    // 当前筛选的IType
    selectedItemId, // 当前选中的ItemId
    ownerRect,      // 父窗口位置（弹窗居中用）
    onSelected      // Action<int> 选中回调，返回ItemId
);

UI特性：搜索框（按ID/Name匹配）、IType下拉筛选、分页（每页20条）、当前选中高亮

使用者：FriendTreasureChestEditor、IndoorProgressEditor（道具奖励和区域奖励均使用）

---

多语言支持

加载 AllLanguage.xlsx (Sheet: client)：

• 第1行: key行（key, zh_CN, en_US, pt_BR...）
• 第2行: 备注行
• 第3行起: 数据行
• 用于Collections编辑器中显示名称tooltip

---

Git工作流

所有工具在加载数据前会：

1. 检查Docs目录是否为Git仓库（.git目录存在）
2. git fetch 检查远程更新
3. git status -uno 检查本地状态
4. 如有远程更新则 git pull
5. 检查Design_SubModule当前分支，必要时 checkout main

保存后会提醒用户手动commit和push。

---

关键数据格式

格式名	示例	使用场景
Item JSON	[{"Id":83,"Num":1}]	IndoorProgress.Item / FriendTreasure.Items
多Item JSON	[{"Id":100001,"Num":50},{"Id":100021,"Num":1}]	IndoorProgress.AreaReward
Reward字符串	83=1	IndoorProgress.Reward
BigReward字符串	Energy=25,PurplePig=1	IndoorProgress.BigReward（使用MY_ITEM_DICT映射名称）
Res引用	"TableName,ItemName" 如 "HeadFrameResource,frame_001"	Item.xlsx.Res字段
Effect引用	"id,param" 如 "5,0"	Item.xlsx.Effect字段（收藏品/限时事件）
限时事件	"eventId,seconds"	IType=102的Effect