OCC 背包与物品系统 · 方案 v1

状态：方案已基本实装（B1~B3、B5 完成，B4 未接完）。本文档保留为设计意图的记录； 代码里当前跑着什么，以 玩法系统现状 为准，逐条差距见 未完成清单。 日期：2026-10-14（方案）/ 2026-10-15（实装状态复核） 定位：背包是整个玩法的总接口 —— 采集、制造、建造、战斗、科技解锁全都要从它过。 承接：玩法方案-Planet Civilization-v1 ⚠️ 本文档成文时积分商城仍在，该商城已于 2026-10-15 整体下线；文中涉及商城之处均已标注。

---

0. 一句话

背包不是"一个装东西的格子表"，而是四种交互的统一入口： 采集的东西进这里、造出来的东西进这里、要用/要放/要交的东西都从这里出去。 所以本方案的核心不是"多少格"，而是每类物品点一下会发生什么。

---

1. 物品总表：按「怎么用」分类

1.1 七大类（关键设计）

分类不按"是什么"、按"怎么用" —— 因为交互方式才是 UI 与代码的分支依据。

🔴 最后一行是有意为之：科技材料必须"看起来不能用、且丢不掉"。 否则新手会把结晶当垃圾丢掉，然后卡在科技树上找不到原因。

1.2 物品定义 itemDef（单一定义源）

放 server/items.js，前端启动随世界配置一起拉取（和 world-config.js 同一套模式，不在前端硬编码）。

{
  id: 'copper_ore',
  name: '铜矿石',
  cat: 'material',         // 七选一
  icon: 'assets/icons/copper_ore.svg',
  stack: 999,              // 单格上限
  tier: 1,                 // 科技层级（0 = 无门槛）
  desc: '基础导电材料，可冶炼成铜锭。',
  // 按分类才有的可选字段
  use:    null,            // consumable：{ kind:'heal', value:3 } / { kind:'buff', ... }
  place:  null,            // deployable：{ building:'miner', size:[3,3] }
  equip:  null,            // equipment：{ slot:'weapon'|'armor'|'engine'|'tool', mods:{...} }
  ammo:   null,            // ammo：{ kind:'blast', damage:2, blastRadius:14 }
}

规则：cat 决定走哪个分支函数；其余字段只在该分类下被读取。 新增物品 = 加一条数据，不改代码 —— 这是让后面能快速堆内容的前提。

1.3 首版物品清单

---

2. 三层容器

2.1 关系

优先级：采集/掉落 → 背包；基地内制造 → 仓库（可一键转背包）；建造 → 优先扣背包。

2.2 ⚠️ 对玩法方案的修订：取消「货仓」，统一为背包

玩法方案 §1.3 原本写的是"货仓 cargo（跨星球携带）"。现在取消这个概念，统一为背包：

• 去战场时，背包里装的就是你带去的东西（弹药、修理包、建筑）。
• 战场掉落进背包。
• 被击毁 → 背包随机掉一半（不是"货仓"掉一半）。

理由：两套容器都是"随身容量"，合并后规则只有一条，UI 也只有一套。 （已同步修改 玩法方案-Planet Civilization-v1 §1.3。）

---

3. 容量与堆叠

⚠️ 实装偏差（未接完）：方案原本要求"由装配机制造「背包扩容模块」后使用"， 目前 bagExpand 是直接免费扩容（store.js 里自注"这里先直接提供接口"）。 也就是说容量还没走生产循环，这是方案与现状之间一处明确的差距 —— 见 未完成清单。 当初的理由是"不让背包容量变成商城消费点"；积分商城已于 2026-10-15 下线， 所以这条约束现在只剩"容量应该属于生产循环"这一半。

---

4. 交互：四种「使用」落点

4.1 统一交互语言（和现有面板一致）

4.2 四种使用落点（需求里那句话的答案）

4.3 装备槽

v1 只开 2 个槽：weapon（发射器）和 tool（工具）。 armor / engine 先留在数据结构里不开放（装备时报"尚未开放"）。

这个取舍是刻意的：第一版不引入新的数值成长线，把背包先做成"功能载体"， 等老大觉得功能够了，再决定要不要让装备参与数值。 （原方案写的是"伤害成长仍归商城 weapon 等级"；商城已下线，那条线现在由科技树承接。）

4.4 弹药

现在纸飞机是免费无限补弹（只有 2.4s 的节奏限制）。改法：

• 标准纸飞机 = 不进背包、免费无限（完全保持现状，战斗节奏不变）
• 爆破 / 穿甲纸飞机 = 背包物品，装备后在补弹时优先消耗背包里的特种弹
• 特种弹用完 → 自动回落到标准弹（不会出现"打不出子弹"的挫败）

这样"制造弹药"有意义，但老玩家的战斗体验零变化。

4.5 掉落与拾取

• 死亡掉落的物品成为地上的掉落物实体（Server-authoritative，带 TTL 120s）。
• 掉落物要广播给同一世界的其他玩家（这是背包系统里唯一需要广播的部分）。
• 走近自动拾取（或按 E），背包满则提示。
• 战场击杀精英/Boss 的掉落也是同一套实体（玩法方案 §4 的结晶/合金从"直接进账"改为"掉在地上要捡"）。

⚠️ 这会提高战场的风险感（打到一半被打死，掉落会被别人捡走），符合"战场"的定位。

---

5. 与现有系统的Integrate

---

6. 技术实现

6.1 数据模型（Server-authoritative）

store.js 的 profile 上新增（沿用 ensureProfile() 的"读时补默认值"做法，老存档零迁移）：

profile.bag = {
  size: 24,
  slots: new Array(64).fill(null),   // 定长数组：空 = null，占用 = { id, n, meta? }
  quick: [-1,-1,-1,-1,-1,-1,-1,-1],  // 存 slot 索引
  equip: { weapon: null, tool: null, armor: null, engine: null },
};
profile.storage = { slots: new Array(500).fill(null) };  // 家园基地仓库

• 定长数组是刻意的：索引稳定 → 快捷栏可以只存索引、拖拽不需要重排数组、前端可直接按下标 diff。
• 存档开销：64 × 约 40 字节 ≈ 2.6KB/玩家，可忽略（对比建筑数组是主要负担）。
• meta 预留给"有耐久/有等级的实例化物品"（首版所有物品都是纯 id + 数量，不做实例化）。

6.2 协议（WS）

关键决策：背包不广播。 它只属于自己，服务端只回给本人 —— 这让背包系统的网络成本几乎为零。 唯一需要广播的是 §4.5 的地面掉落物。

6.3 Server-authoritative边界

• 使用消耗品、放置建筑、装备武器 —— 全部等服务端回包（不做乐观更新）。

理由：这些操作频率低（几秒一次），100ms 延迟无感；而做错了会被刷物品。

• 采集是唯一的高频写入：客户端保持一份背包镜像用于"满了没满"的即时判断，

但真正的入包以服务端 bagDelta 为准（采集本来就有 0.5s 节流，频率可接受）。

6.4 UI 结构

复用现有 #panel 的那套 DOM 骨架与 esc() 转义习惯，但背包是独立的全屏 overlay（类似 #auth）：

┌─ 背包 ────────────────────────────────── 18/24 ── ✕ ─┐
│ [全部][资源][消耗][弹药][装备][建筑][科技]  [Search]     │
├──────────────┬────────────────────────────────────────┤
│ 装备槽        │  格子区（6×4，格子 56px）              │
│ [武器] [工具] │  ┌──┬──┬──┬──┬──┬──┐                  │
│              │  │铜│铁│木│  │  │  │                  │
│ 快捷栏        │  ├──┼──┼──┼──┼──┼──┤                  │
│ 1 2 3 4      │  │  │  │  │  │  │  │                  │
│ 5 6 7 8      │  └──┴──┴──┴──┴──┴──┘                  │
│              │  ── 详情 ──────────────                 │
│ [转入仓库]    │  铜矿石 ×137                           │
│ [一键整理]    │  基础导电材料，可冶炼成铜锭。           │
│              │  [使用] [拆分] [丢弃] [查看配方]        │
└──────────────┴────────────────────────────────────────┘

• 快捷键 B 开合（不改现有的 G 线框 / 数字键动作映射）。
• 背包打开时 不暂停作品（多人作品不能暂停），但释放鼠标并显示光标（cursor:none 的例外名单要加 #bag，

和现有 #auth 同样处理 —— 这是踩过的坑，见记忆）。

• 图标：SVG（体素风的小方块堆，和 Boss 的体素美术统一，且体积极小）。

6.5 性能

---

7. 分期

---

8. 等老大拍板的 5 个点

---

9. 需求对照