# 当前运行时物品生成系统设计整理

更新时间：`2026-04-02`

## 0. 目标

这份文档只回答一个问题：

**当前仓库里，运行时物品是怎么被“定义、生成、发放、使用、转化、进入 build 结算”的。**

它不是未来方案，而是对现状的结构化整理，方便后续继续扩展 AI 原生玩法。

## 1. 当前系统的总体判断

当前仓库里的运行时物品系统，不是“纯 AI 生成”，而是一个 **本地规则驱动 + 局部程序化生成 + AI 负责叙事文本** 的体系。

它大体由 5 层组成：

1. **物品骨架层**
   - 用 `InventoryItem`、`ItemStatProfile`、`ItemUseProfile`、`ItemBuildProfile` 承载运行时能力。
2. **基础生成层**
   - 用 `src/data/itemCatalog.ts` + `src/data/itemDesign.ts` 从素材路径推导出物品目录与设计元数据。
3. **运行时发放层**
   - 在初始背包、NPC 库存、宝藏奖励、怪物掉落、拆解/锻造/重铸、自定义世界运行时生成等入口，把物品真正放进 `GameState`。
4. **战斗/背包生效层**
   - 装备通过 `equipmentEffects.ts` 生效，消耗品通过 `inventoryEffects.ts` 生效，build 标签通过 `buildTags.ts` + `buildDamage.ts` 生效。
5. **叙事包装层**
   - AI 负责把这些本地规则已经确定的结果写成剧情、聊天、宝藏描述、选项文案，但 **AI 当前并不直接产出结构化运行时物品**。

一句话概括：

**当前系统已经有“运行时物品玩法骨架”，但还没有“与具体背景 / 当前 NPC / 当前事件强绑定的 AI 原生物品导演层”。**

## 2. 当前核心数据结构

### 2.1 `InventoryItem`

运行时所有物品最终都落到 `InventoryItem`：

- 基础身份：`id`、`category`、`name`、`quantity`、`rarity`
- 通用标签：`tags`
- 世界/表现：`iconSrc`、`description`、`worldAffinity`、`worldProfiles`
- 装备信息：`equipmentSlotId`
- 数值能力：`statProfile`
- 使用能力：`useProfile`
- build 能力：`buildProfile`
- 经济能力：`value`

这意味着当前系统已经允许同一个物品同时具备：

- 装备加成
- 消耗品效果
- build 标签
- 世界观文案
- 经济价值

### 2.2 `ItemStatProfile`

当前可直接进入数值结算的字段主要是：

- `maxHpBonus`
- `maxManaBonus`
- `outgoingDamageBonus`
- `incomingDamageMultiplier`

这套结构已经足够支撑“少量直接数值提升”的物品设计。

### 2.3 `ItemUseProfile`

当前消耗品/可使用物品可提供：

- `hpRestore`
- `manaRestore`
- `cooldownReduction`
- `buildBuffs`

这意味着当前系统已经具备“限时 build 标签道具”的基础承载能力。

### 2.4 `ItemBuildProfile`

当前 build 相关物品数据包括：

- `role`
- `tags`
- `setId`
- `setName`
- `pieceName`
- `synergy`
- `craftTags`
- `forgeRank`

这说明当前物品系统已经不仅仅是“数值装备”，而是已经向 **build / 套装 / 锻造** 方向扩展。

## 3. 当前物品是如何被生成出来的

## 3.1 素材目录 -> 物品目录

`src/data/itemCatalog.ts` 负责把素材路径转成 `ItemCatalogEntry`：

- 先从素材路径推导：
  - `category`
  - `rarity`
  - `tags`
  - `name`
- 再调用 `src/data/itemDesign.ts` 补充更完整的设计：
  - `statProfile`
  - `useProfile`
  - `buildProfile`
  - `value`
  - 世界观名称/描述

也就是说，当前项目里相当一部分物品，不是手工逐个写死的，而是 **“素材驱动 + 规则推导”**。

## 3.2 `itemDesign.ts` 的设计角色

`src/data/itemDesign.ts` 是当前最重要的“物品规则设计器”。

它会按素材族系推导出不同风格物品：

- `Armory` 系列
  - 生成武器/护甲
  - 自动带 `buildProfile`
  - 自动挂 `setId / setName / pieceName / synergy`
- `Jewelry` 系列
  - 生成饰品
  - 偏向 `relic` 与 build 补位
- `Potions` 系列
  - 生成消耗品
  - 可恢复 HP / Mana / 冷却
  - 部分药剂会生成 `buildBuffs`
- `Gems` / `Skills` / `Librarium` 系列
  - 生成稀有品、法器、技能相关物品
  - 部分带 build 倾向

这层已经是“半程序化设计”，不是纯静态表。

## 3.3 自定义世界运行时程序化生成

`src/data/customWorldRuntime.ts` 提供了另一条明显不同的生成链：

- 输入：
  - `CustomWorldProfile`
  - `seedKey`
  - 查询条件：`categories / preferredTags / keywords / rarityFloor / count`
- 输出：
  - 运行时即时程序化物品

它的特点是：

- 基于世界档案与种子稳定生成
- 可以按角色、用途、标签、关键词筛选
- 能生成：
  - 武器
  - 护甲
  - 饰品
  - 消耗品
  - 材料
  - 稀有品
  - 专属物品

当前它已经被用于：

- 自定义世界角色初始装备
- 自定义世界角色初始背包
- 自定义世界 NPC 角色库存

但这条链目前更像 **“主题化程序物品池”**，还不是“事件级、NPC级、场景级实时定制物品”。

## 4. 当前运行时有哪些物品发放入口

## 4.1 玩家初始物品

玩家开局物品主要来自两条链：

1. `buildInitialPlayerInventory`
   - 来自 `npcInteractions.ts`
   - 普通世界走角色预设背包
   - 自定义世界走 `buildCustomWorldStarterInventoryItems`
2. `buildInitialEquipmentLoadout`
   - 来自 `equipmentEffects.ts`
   - 根据角色预设初始装备，转成可装备的 `InventoryItem`

这说明玩家初始 build 其实已经部分依赖物品体系，而不是只靠角色裸属性。

## 4.2 NPC 库存

`buildInitialNpcState` 会给每个 NPC 建立运行时库存：

- 角色型 NPC：
  - 从角色装备 + 角色背包推导
- 怪物型 encounter：
  - 从怪物 preset 的 `lootTable` 推导
- 普通场景 NPC：
  - 从职业/身份模板库存推导
- 自定义世界 NPC：
  - 可走 `buildRuntimeCustomWorldInventoryItems`

因此当前 NPC 交易、赠礼、击败掉落，已经都能围绕同一套 `InventoryItem[]` 进行。

## 4.3 宝藏奖励

`src/data/treasureInteractions.ts` 负责宝藏奖励：

- 根据世界类型选择奖励池
- 根据 encounter 信息和 action 做 seed
- 产出：
  - 稀有品
  - 消耗品
  - 材料
  - HP / Mana 恢复
  - 货币

这条链已经是运行时生成，但目前仍然是 **世界模板池级别**，不是“根据当前场景背景 / 当前 NPC / 最近事件”深度定制。

## 4.4 怪物掉落 / NPC 击败掉落

当前掉落主要有两种：

1. 怪物 preset 自带 `lootTable`
2. NPC 击败后，从 `npcState.inventory` 里按玩家收益排序取高价值物品

这里的核心是：

**当前系统已经把“掉落”统一成库存消费问题，而不是单独的一套特殊奖励系统。**

## 4.5 拆解 / 合成 / 锻造 / 重铸

`src/data/forgeSystem.ts` 已经形成第二类运行时物品生成入口：

- `executeDismantleItem`
  - 把装备拆成基础材料 + 标签精粹
- `executeForgeRecipe`
  - 消耗材料生成成品装备
- `executeReforgeItem`
  - 保留原物品基础上重投 build 标签并增强数值

这说明运行时物品系统已经不只是“掉落 -> 使用”，而是进入了：

**掉落 -> 持有 -> 拆解 -> 再生产 -> build 迭代**

的循环。

## 5. 当前物品如何进入玩法结算

## 5.1 装备生效

`src/data/equipmentEffects.ts` 会把 `EquipmentLoadout` 汇总为：

- `maxHpBonus`
- `maxManaBonus`
- `outgoingDamageMultiplier`
- `incomingDamageMultiplier`

当前实现已经会优先读取 `statProfile`，没有时才走 rarity fallback。

这意味着：

- 装备的直接数值提升已经真实生效
- 不是只在 UI 显示

## 5.2 build 标签生效

`src/data/buildTags.ts` + `src/data/buildDamage.ts` 已经形成完整 build 入口：

- 角色 `combatTags`
- 装备 `buildProfile.tags`
- 套装标签
- 限时 `TimedBuildBuff`

会被统一整理为激活标签集，再计算 build 伤害乘区。

当前 build 标签来源已经包括：

- 角色
- 怪物
- 装备
- 套装
- 消耗品/技能 buff

## 5.3 消耗品生效

`src/data/inventoryEffects.ts` + `src/hooks/useInventoryFlow.ts` 会在使用物品时：

- 恢复 HP
- 恢复 Mana
- 推进技能冷却
- 追加 `activeBuildBuffs`

这意味着当前系统已经存在：

- **直接恢复型物品**
- **节奏调整型物品**
- **限时 build 强化型物品**

三种雏形。

## 6. 当前 AI 在物品系统里的角色

当前 AI 与物品系统的关系主要有两种：

## 6.1 自定义世界“离线式”生成

`src/services/customWorld.ts` + `src/services/customWorldBuilder.ts` 会让 AI 生成：

- 世界名
- playable NPC
- story NPC
- 关键物品样本
- 地标

然后本地再把这些骨架扩展成更大的世界档案。

这时 AI 的角色是：

**提供世界观语义骨架，而不是直接在单次 encounter 里临场造出一个可结算物品。**

## 6.2 运行时叙事包装

`prompt.ts` 和相关 story flow 里，AI 主要负责：

- 剧情文本
- 对话
- 选项文案
- 氛围描述

但当前 AI 不负责：

- 直接返回结构化物品
- 决定物品数值是否合法
- 决定 build 标签是否合法
- 决定库存如何变更

这与仓库已有开发经验文档里的原则一致：

**AI 负责解释世界，本地规则负责改动世界。**

## 7. 当前系统的优点

## 7.1 已有统一物品骨架

`InventoryItem` 已经足够承载：

- 永久装备
- 消耗品
- build 标签
- 世界观描述
- 经济系统

后续不需要另起一套物品结构。

## 7.2 已有 build 玩法骨架

当前系统已经支持：

- 装备 build 标签
- 套装 build 标签
- 消耗品限时 build buff
- 角色/怪物 combatTags

这让“物品影响 build”不再只是概念。

## 7.3 已有多个运行时入口

当前物品已经能从这些入口进入游戏：

- 初始背包
- 初始装备
- NPC 库存
- 宝藏
- 怪物掉落
- 击败 NPC
- 合成
- 拆解
- 锻造
- 重铸
- 自定义世界程序化生成

系统入口已经比较完整。

## 7.4 本地规则边界明确

当前实现最大的稳定性来源，是物品最终由本地规则落库和结算：

- 可测试
- 可复现
- 可存档兼容
- 不依赖模型临场稳定性

这非常适合继续向 AI 原生玩法演化。

## 8. 当前系统的主要缺口

## 8.1 非自定义世界的运行时发放仍偏模板池

当前普通世界的宝藏、NPC 库存、基础奖励，更多还是：

- 世界模板
- 身份模板
- 怪物 preset

而不是根据以下上下文动态拼装：

- 当前场景背景
- 当前 NPC 动机
- 当前事件阶段
- 最近剧情行为
- 玩家当前 build 缺口

## 8.2 宝藏与物品的叙事绑定不够深

当前宝藏奖励会根据世界类型变化，但还没有强绑定：

- 地标
- scene preset
- treasure hint
- 相关 NPC
- 最近发生的事件

所以“玩法可用”，但“故事贴脸感”还不够强。

## 8.3 自定义世界运行时物品偏“主题生成”，还不是“关系生成”

`customWorldRuntime.ts` 已经能做：

- 世界主题相关
- 标签/关键词相关
- 角色用途相关

但还没有直接把以下关系结构编进物品：

- 这个物品和哪个 NPC 有关系
- 为什么在这个时刻出现
- 它与哪个任务/线索绑定
- 它是否属于某个 faction / 场景 / 地标

## 8.4 一些运行时奖励没有补足完整 build 元数据

例如部分宝藏奖励和 NPC 模板奖励，当前只是简单 `InventoryItem`：

- 有 `category / rarity / tags`
- 但未必有完整 `statProfile / useProfile / buildProfile`

这会导致它们更像资源或商品，而不是强 build 物品。

## 8.5 缺少“物品生成导演层”

当前系统缺的不是单个函数，而是一层明确的运行时物品导演：

- 输入当前上下文
- 决定掉落/奖励/商店/赠礼候选
- 决定叙事来源
- 决定 build 倾向
- 决定是永久收益还是限时收益
- 决定数值预算

这层目前分散在：

- `treasureInteractions.ts`
- `npcInteractions.ts`
- `customWorldRuntime.ts`
- `forgeSystem.ts`

之间，还没有统一起来。

## 9. 对当前系统的结论

当前仓库里的“运行时物品生成系统”已经不是空白，反而已经具备了很好的扩展前提：

- 有统一物品数据结构
- 有 build 标签体系
- 有限时 buff 体系
- 有装备/消耗品/材料/稀有品的分类
- 有宝藏、NPC、掉落、锻造等运行时入口
- 有自定义世界程序化物品能力
- 有明确的“AI 叙事、本地规则结算”边界

但它现在更像：

**“规则系统已经就位，AI 原生上下文驱动物品导演还没补上。”**

后续如果要继续往 AI 原生游戏推进，最值得补的不是推翻现有系统，而是：

1. 在现有 `InventoryItem` 体系上增加上下文生成层。
2. 让物品生成同时读取场景、NPC、剧情、build 缺口。
3. 让 AI 负责物品语义与叙事来源，本地规则负责编译成可结算物品。
4. 把宝藏、NPC 交易、任务奖励、掉落统一接入同一套“运行时物品导演”。