Genarrative/docs/prd/RUNTIME_ITEM_GENERATION_CURRENT_SYSTEM_DESIGN.md

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

更新时间：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 交易、任务奖励、掉落统一接入同一套“运行时物品导演”。