🌍 中文 | English | 日本語

📥 安装 | 快速开始 | 详细文档

Ale Inventory System - 仓库系统

Ale Inventory System 是一款面向 Unity 的数据驱动库存系统插件，把 道具 / 仓库 / 商店 / 制作 / 装备 五大子系统整合进同一套工具链。
它用一个 InventoryDatabase 资产集中配置五大子系统的静态定义数据（枚举类型、功能标签、道具模板、仓库、商店、蓝图、装备组等），配套一整套开箱即用的运行时 UI（背包 / 商店 / 制作 / 装备界面）与各自的运行时管理器（拥有数量、交易进度、制作产出、已装备道具、存档均由管理器维护）。
面向设计师：编辑器始终且仅在 ScriptableObject 上工作，全程支持 Undo / Redo；JSON / 二进制仅作为单向导出格式。文本组件（TextMeshPro）、本地化（Unity Localization）、资源加载（Addressables）均通过编译宏可选启用，因此插件包本身不引入任何硬依赖。

📜 目录

• Ale Inventory System - 仓库系统
  • 📜 目录
  • 简介
    • 项目特性
    • 五大子系统
  • 💻 环境要求
  • 📦 安装
    • 使用 UPM（推荐）
    • 导入演示 Sample（可选）
    • 其他方式
  • 🚀 快速开始
    • 1. 创建数据文件
    • 2. 打开编辑器并配置
    • 3. 导出（可选）
    • 4. 运行时挂载
    • 5. 一键 Demo
  • 🖥️ 欢迎窗口
  • 🧩 可选宏开关
  • 📖 详细文档
  • 📁 目录结构
  • 📋 待办事项
  • 📄 许可

简介

大多数游戏都需要一套「道具 + 背包 + 商店 + 制作 + 装备」的数据体系，但这些系统各自零散、互相耦合，反复造轮子成本高。Ale Inventory System 把它们收拢到同一份数据资产与同一套编辑器下：

1. 集中配置 —— 一个 InventoryDatabase 承载五大子系统的全部静态定义，编辑器为「顶部系统页签 + 三列布局（定义配置 / 条目列表 / 详细 Inspector）」，支持模板过滤、搜索、拖拽重排、键盘导航、实时重复 ID 检查。
2. 灵活属性 —— 道具与各配置条目的字段由一套灵活属性系统承载（Bool / Int / Float / String / Text / Vector / Color / Enum / Sprite / Prefab / AudioClip / AnimationCurve… 每种都支持数组形态），可按功能标签成组增删，无需改代码即可扩展数据结构。
3. 运行时开箱即用 —— 各子系统配套轻量运行时管理器与虚拟滚动 UI 组件，查询、增删、整理、交易、制作、装备、存档 / 读档均有现成接口。
4. 零硬依赖 —— TextMeshPro / Localization / Addressables 全部经编译宏可选启用，未开启时插件照常工作。

项目特性

特性	描述
单资产集中配置	一个 InventoryDatabase 集中五大子系统全部静态数据；编辑器仅在 ScriptableObject 上工作，全程 Undo / Redo。
灵活属性系统	20+ 字段类型（含数组形态）：Bool / Int / Float / String / Text（纯文本 fallback + 可选本地化引用）/ Vector2~4 / VectorInt / Color / Enum / StringIntPair / EnumIntPair / Sprite / Texture / Prefab / Material / AudioClip / AnimationClip / AnimationCurve / PhysicsMaterial。
自定义枚举 + 功能标签	枚举值系统自动分配、永不复用、可拖拽重排；功能标签定义一组属性字段，增删标签自动增删道具对应字段，可锁定到模板。
五大子系统一体化	道具 / 仓库 / 商店 / 制作 / 装备，共享同一份数据与属性系统，条目互相引用（如商店价格取自道具属性、装备加成汇总自道具属性）。
统一虚拟滚动 UI	网格与顺序列表均为虚拟滚动（对象池 + 仅渲染可见区）；增量差异刷新、生成限速（spawnPerSecond）、逐格浮现、分配 / 回收淡入淡出（下沉 toolkit 通用），海量条目不卡顿。
运行时管理器	InventoryDataManager（查询）+ 仓库 / 商店 / 制作 / 装备各自的运行时管理器，装备状态与商店进度均可存档。
单向导出	InventoryDtoMapper → JSON / 二进制，覆盖数据库全部配置数据（五大子系统 17 个列表）；对象引用以 AssetGUID 承载，可选经 Addressable 异步加载。
三个可选宏	TextMeshPro（ATK_TMP）/ Unity Localization（ATK_LOCALIZATION）/ Unity Addressables（ATK_ADDRESSABLE），在 Ale Toolkit 欢迎窗口一键开关并检测对应包是否安装（宏为项目级全局设定，已下沉 toolkit）；插件包本身零硬依赖。
本地化工具	一键为 InventoryDatabase 生成 / 关联多语言表，遍历全库 Text 字段自动生成中文 Key 并回填条目（进度条 + 日志 + 取消）。
欢迎窗口向导	统一入口：创建数据、打开编辑器 / 工具窗口、生成示例预制体，以及「一键生成完整可运行示例」（数据库 + 全部 UI 预制体 + 管理器）；界面语言与插件宏等全局设定跳转到 Ale Toolkit 欢迎窗口。
编辑器界面三语	在 Ale Toolkit 欢迎窗口一键切换 中文 / English / 日本語，Inventory Editor 配置编辑器（五大系统全部面板）整体切换；选择持久化保存，与运行时内容本地化互不相关。

五大子系统

子系统	配置内容	运行时管理器
道具系统	枚举类型、功能标签、道具模板、道具 + 灵活属性	InventoryDataManager（查询）
仓库系统	仓库模板、仓库、容量 / 重量 / 标签限制、整理排序	InventoryRuntimeManager（格子状态 + 存档）
商店系统	商店模板、商店、商品组、价格来源、刷新计划	ShopRuntimeManager（交易 + 进度存档）
制作系统	分组标签、蓝图模板、蓝图（配方）、制作仓库	CraftingRuntimeManager（消耗 → 产出）
装备系统	分组标签、装备组模板、装备组（槽位列表 / 装备槽 / 道具限制 / 属性加成）	EquipmentRuntimeManager（装备 / 卸下 + 加成 + 存档）

每个子系统的完整配置与运行时说明见详细文档。

💻 环境要求

• Unity 2022.3 或更新版本（package.json 声明的最低版本；本仓库基于 Unity 6000.3 开发与维护）。
• 核心插件为纯 C#，不引入任何硬依赖——TextMeshPro / Unity Localization / Unity Addressables 均通过编译宏可选启用（见可选宏开关）。
• 未启用 ATK_TMP 时，UI 文本组件回退到 UnityEngine.UI.Text，插件照常工作。

📦 安装

⚠️ 本插件依赖通用底层包 com.ale.toolkit，必须先装它、再装本插件。 自 1.8.0 起本插件依赖它；Unity Package Manager 不支持在 package.json 的 dependencies 里写 git URL，无法自动拉取，故顺序不能颠倒。用与下方相同的方式先安装 toolkit：https://github.com/AleFeng/unity-ale-toolkit.git?path=/Packages/com.ale.toolkit#1.5.1。漏装或颠倒会报 找不到 Ale.Toolkit.* 一类编译错——补装 toolkit 并等重新编译即可，无需重装本插件。

使用 UPM（推荐）

Window > Package Manager → 左上角 + → Install package from git URL... → 粘贴：

https://github.com/AleFeng/unity-ale-inventory-system.git?path=/Packages/com.ale.inventory

这样装的是 main 的最新提交。要固定版本，把 #<tag> 加在整条 URL 的最末尾（必须在 ?path= 之后）：

https://github.com/AleFeng/unity-ale-inventory-system.git?path=/Packages/com.ale.inventory#1.11.1

可用的 tag 见 Releases。

导入演示 Sample（可选）

装好后在 Package Manager 里选中本包 → Samples → 导入 Inventory System Demo（数据库资产 InventoryDatabase + 管理器预制体 + UI 示例场景），可直接进 Play 体验。也可以直接用欢迎窗口的「一键生成」向导现场生成一套完整示例。

其他方式

也可以下载仓库，把 Packages/com.ale.inventory 整个文件夹拷进你项目的 Packages/ 目录（不是 Assets/）—— Unity 会自动把它识别为本地包。

安装成功后，菜单栏会出现 Tools → Inventory System，Unity 会话首次打开时还会自动弹出欢迎窗口。

🚀 快速开始

下面是最短路径的使用流程，完整的子系统配置与 API 说明见 详细文档。

1. 创建数据文件

Project 面板右键 > Create > Inventory System > Inventory Database

（或在欢迎窗口点击「创建新数据文件」；可先在欢迎窗口配置「数据模板」，新建时从模板深拷贝全部数据。）

2. 打开编辑器并配置

• 选中 .asset，在 Inspector 顶部点击「在 Inventory Editor 中编辑」；或菜单 Tools > Ale Toolkit > Inventory System > Inventory Editor。
• 编辑器为顶部系统页签 + 三列布局（左：定义配置 / 中：条目列表 / 右：详细 Inspector）。依次在「道具 / 仓库 / 商店 / 制作 / 装备」页签中配置。中间条目列表支持模板过滤、搜索、拖拽重排、↑ / ↓ 键盘导航。

3. 导出（可选）

工具栏「导出 JSON」或「导出二进制」（存在非空重复 ID 时按钮禁用；空白 ID 条目导出时自动跳过）。编辑器始终在 ScriptableObject 上工作，导出为单向格式。

自 1.6.0（格式 v6） 起，导出覆盖数据库的全部配置数据——五大子系统的 17 个列表都在内。此前只导出道具系统四项，其余静默丢弃。

4. 运行时挂载

在场景中新建 GameObject，添加 InventoryRuntimeManager 组件，把 .asset 拖入 databases 数组。游戏启动时自动注册数据库并初始化各仓库空状态。

using Ale.Inventory.Runtime;

// 查询静态数据
Item item = InventoryDataManager.Instance.GetItem("sword_01");

// 运行时操作仓库
InventoryRuntimeManager.Instance.TryAddItem("backpack", "sword_01", 1);
bool has = InventoryRuntimeManager.Instance.HasItem("backpack", "sword_01");

// 存档 / 读档（LoadSaveData 为覆盖语义：存档中没有的仓库回到初始空态）
var saveData = InventoryRuntimeManager.Instance.GetSaveData();
InventoryRuntimeManager.Instance.LoadSaveData(saveData);

// 开新游戏：清空全部运行时状态
InventoryRuntimeManager.Instance.ResetAll();

5. 一键 Demo

在欢迎窗口展开「测试工具-预制体生成 → 生成全部」，一键生成完整可运行示例（数据库 + 全部 UI 预制体 + 背包 / 商店 / 制作 / 装备面板 + 管理器）。

🖥️ 欢迎窗口

插件的统一入口面板，集中了「创建数据 / 打开编辑器 / 查看文档 / 生成示例」等库存领域操作。每次 Unity 会话首次会自动弹出一次，也可随时手动打开：

Tools > Ale Toolkit > Inventory System > Welcome Window

界面语言、枚举翻译、可选依赖宏均为项目级全局设定，自 1.10.0 起已下沉到 Ale Toolkit 欢迎窗口（Tools > Ale Toolkit > Welcome）统一配置。 本窗口顶部提供「打开 Ale Toolkit 设置」按钮一键跳转；语言切换后 Inventory Editor（五大系统全部面板）随之刷新，仅影响编辑器界面文案，与运行时内容本地化无关。

页眉之下自上而下：「打开 Ale Toolkit 设置」跳转、快捷操作（创建数据 / 打开各编辑器与工具窗口 / 一键生成示例预制体）、数据模板（指定一个 InventoryDatabase 作为新建蓝本）、向导字体（启用 ATK_TMP 时，供向导生成 Prefab）、启动时自动显示。

🧩 可选宏开关

三个宏均在 Ale Toolkit 欢迎窗口（Tools > Ale Toolkit > Welcome）的「插件支持（编译宏）」区一键开关，并实时检测对应 Package 是否已安装（未安装时勾选会弹确认对话框）；库存欢迎窗口提供跳转按钮：

开关	宏	作用
TextMeshPro	ATK_TMP	开启后 UI 文本组件使用 TMP_Text，否则用 UnityEngine.UI.Text；可配「默认字体」应用到向导生成的 Prefab。
Unity Localization	ATK_LOCALIZATION	开启后 Text 字段可挂本地化引用（表 + 条目）；配合「本地化工具窗口」一键建表 / 生成中文 Key，支持多语言。
Unity Addressables	ATK_ADDRESSABLE	开启后运行时资源经 Addressable 按需异步加载、引用计数自动卸载；导出时自动登记被引用资源。

切换宏后需等待 Unity 重新编译生效。

📖 详细文档

本 README 面向整体介绍与快速上手。完整的使用说明——每个子系统的配置细节、运行时 API、灵活属性参考、UI 组件与架构说明等——请见插件内文档：

👉 Packages/com.ale.inventory/README.md

子系统与参考文档（位于 Packages/com.ale.inventory/Docs~/）：

• 道具系统 — 枚举类型 / 功能标签 / 道具模板 / 道具 / 灵活属性
• 仓库系统 — 仓库模板 / 仓库 / 整理排序 / 运行时 API / 存档
• 商店系统 — 商店类型 / 价格来源 / 商品组 / 刷新计划 / 交易 API
• 制作系统 — 分组标签 / 蓝图模板 / 蓝图配方 / 制作仓库 / 制作 API
• 装备系统 — 分组标签 / 装备组模板 / 槽位列表 / 装备槽 / 道具限制 / 属性加成 / 装备 API
• 属性系统 — 字段类型参考、AttributeValue 取值 / 显示 / 排序比较
• UI 组件指南 — UI 组件、预制体制作、宏开关、Demo 向导
• 架构说明 — 设计目标、数据流、编辑器与运行时架构、扩展指南

📁 目录结构

Packages/com.ale.inventory/          ← 包根
├── package.json  CHANGELOG.md  LICENSE.md  README.md   ← 详细使用文档
├── Runtime/
│   ├── Data/            数据模型（Item / Inventory / Shop / Crafting* / AttributeValue 等）
│   ├── Manager/         DataManager / 仓库 / 商店 / 制作 / 装备 运行时管理器
│   ├── Serialization/   DTO + JSON / 二进制序列化
│   ├── Assets/          资源加载抽象（直接加载）
│   ├── Addressables/    Addressable 资源加载支持
│   ├── Localization/    TMP 文本 / 字体本地化事件
│   └── UI/              运行时 UI 组件（Item / ItemList / Tab / Tool / View / Common）
├── Editor/
│   ├── ItemSystem/ InventorySystem/ ShopSystem/ CraftingSystem/ EquipmentSystem/   ← 五大系统面板
│   ├── Common/         通用属性 / 配置绘制器 + 工具窗口基类
│   ├── Addressables/   Addressable 资源引用迁移工具窗口
│   ├── Localization/   本地化工具窗口（建表 / 生成中文 Key）
│   ├── Create/         数据文件创建菜单
│   └── DemoWizard/     一键生成测试数据与预制体
├── Docs~/              详细文档
└── Samples~/Demo/      演示 Sample（数据库 + 管理器预制体 + UI 示例场景）

📋 待办事项

• 商店「等价交换」类型的完整实现（当前为占位）。
• 更多示例场景与运行时用例。

📄 许可

本项目基于 MIT License 开源，可自由用于商业与非商业项目。