虚空宝箱（Void Chest）

一个 Valheim 模组：一件随角色旅行的魔法容器。

装备后按热键打开专属容器；内容绑定在角色存档上 —— 丢进箱子、交易、掉落、合成升级都不会丢失或转移。支持四级升级链、附近快速存储与「守护石」远程仓库。

本地化：English / 简体中文 / 繁體中文

功能

• 四级宝箱链：黑金属 → 魔能 → 烈焰 → 水晶，容量依次 2×6 / 3×6 / 3×8 / 4×8（可配置）。
• 角色级数据：内容存于角色档案（Player.m_customData），跨世界、跨服务器随身携带；宝箱物品只是"钥匙"。
• 装备打开：占用 Utility 槽（兼容 ExtraSlots 额外槽），默认热键 B（可配置）。
• 重量上限：默认 100 / 150 / 300 / 800（0 = 无限制，可配置）。
  • 拖拽 / Shift 快速移动超额时自动分堆（只存入可容纳数量）。
  • 重量已满时无反应（物品回弹）。
  • 容器重量显示为 当前/上限。
  • 附近 / 远程存储不受重量限制。
• 附近存储：一键把背包物品存进周围 30m（可配置）内所有箱子。
  • 自动忽略：物品栏第一排（快捷栏）、已装备物品、ExtraSlots 专用槽位（快捷/弹药/食物/杂项/额外装备）、被其他玩家占用的箱子。
• 守护石远程仓库：出门在外，把物资远程存进「你有权限的守护石」领地范围内的家里所有箱子。
• 可配置：容量、重量、范围、过滤规则、远程解锁方式、热键、超时与缓存（支持 ConfigurationManager）。

制作配方

使用

1. 装备虚空宝箱（Utility 槽）。
2. 按 B 打开界面。
3. 界面按钮（单按钮动态切换）：
   • 附近存储：存入周围箱子；
   • 远程存入：存入守护石领地内的家箱（需要装备魔能/L2 及以上宝箱解锁；或在配置中开启"始终可用"）。
4. 原版"全部堆叠 / 全部取出"按钮同样可用。

远程仓库说明

• 需要玩家是守护石的创建者或已在它的 permitted（允许）名单中。
• 范围使用守护石自带的领地半径（XZ 圆形）。
• 仅单机 / 主机模式可用；专用服务器需要服务端安装本模组。
• 扫描结果会缓存（默认 300 秒），重复存入秒级完成；被拆的箱子自动跳过。

配置

配置文件：BepInEx/config/liu.valheim.voidchest.cfg（支持 ConfigurationManager 图形界面）。

安装

1. 安装 BepInExPack for Valheim。
2. 安装 Jotunn。
3. 将 VoidChest.dll 放入 BepInEx/plugins/VoidChest/。

依赖

• BepInExPack Valheim 5.4.2350+
• Jotunn 2.29.2+
• 可选：Valheim Plus（兼容，启用附近存储时自动屏蔽其 AutoStack 扩散）
• 可选：ExtraSlots（额外 Utility 槽装备支持）

构建

cd VoidChest
dotnet build .\VoidChest.csproj -c Release

输出：BepInEx/plugins/VoidChest/VoidChest.dll（工程内已配置输出路径）。

已知限制

• 远程存入仅单机/主机模式（专用服务器需服务端安装，尚未支持）。
• 调整容量后，超出显示范围的物品数据会保留但不可见（换回更大容量可见）。
• 卸载模组后宝箱物品会失效；角色档案中的数据仍保留（重装可恢复）。

更新日志

• 0.4.0：容量/重量可配置；远程解锁机制（默认 L2 解锁）；单按钮动态切换；物品描述本地化（英/简/繁）。
• 0.3.2：远程存储性能优化（全量快照分类、缓存、8ms 帧预算、分阶段性能统计）。
• 0.3.1：修复 ZDO 对象池复用风险（只保存 ZDOID）。
• 0.3.0：P2 守护石远程仓库。
• 0.2.0：P1 附近存储、ExtraSlots 兼容、V+ 门控、界面按钮。
• 0.1.x：P0 基础（物品/配方/虚拟容器/存档/热键）。

仓库

https://github.com/1264600905/valheim-voidchest （Private，开发中）

0.5.1

• 包名（GUID）统一为 trigger.valheim.voidchest（旧配置自动迁移）
• 物品描述改为功能说明（英文优先，三语保留）
• README 改为英文优先（英文 + 简体中文 + 繁體中文）

0.5.0

• 新增：远程存入支持联机客户端（专用服务器 / 联机主机）——不再仅限主机使用
  • 客户端把按本地规则过滤后的背包快照通过自定义 RPC 发送给服务端；
  • 服务端沿用原扫描/堆叠流程处理快照，回传实际移动差异（物品标识 + 数量）；
  • 客户端按差异从实时背包精确扣除，避免并发变动导致误删/复制；
  • 需要服务端与客户端安装相同版本的本 mod；服务端未安装时 30 秒后提示
• 变更：扫描缓存按玩家作用域隔离（不同玩家的守护石权限不同）
• 新增：服务端禁用远程存入时向客户端返回明确提示

0.4.1

• 修正 L3 烈焰虚空宝箱的配方材料：Flametal → FlametalNew （Valheim 1.0 中"焰金属"对应的 prefab 是 FlametalNew；旧 Flametal 已更名为"上古金属"，导致配方永远无法解锁）

0.4.0

• 新增：每级容量可配置（行/列，1-8）
• 新增：每级重量上限可配置（默认 100/150/300/800，0 = 无限制）
• 新增：重量显示为"当前/上限"
• 新增：手动存入（拖拽 / Shift 快速移动）超重时自动分堆，重量已满时无反应；附近/远程存储不受重量限制
• 新增：远程存储解锁机制（RemoteStore.AlwaysAvailable，默认关闭 = 装备魔能/L2 及以上宝箱解锁）
• 变更：界面合并为单按钮（未解锁显示"附近存储"，解锁后显示"远程存入"）
• 新增：物品描述（北欧魔法风格）
• 新增：三语言本地化（English / 简体中文 / 繁體中文）
• 新增：仓库与发布文件（README / manifest / icon / LICENSE）

0.3.2

• 性能：远程存储扫描改为全量快照分类（2006 批 → 1 批），扫描耗时从 1.4-1.7 秒降至 ~40ms
• 性能：分类阶段预读 prefab hash，避免 100 万次 ZDO 字典查询
• 性能：帧预算 4ms → 8ms；增加分阶段性能统计（快照/分类/筛选/堆叠/数据写入）

0.3.1

• 修复：远程存储只保存 ZDOID，消除 ZDO 对象池复用导致的数据污染风险

0.3.0

• 新增：P2 守护石远程仓库（单机/主机模式）
• 扫描玩家有权限（创建者 / permitted 名单）的守护石，远程存入其领地范围内的所有箱子
• 排除船/车/墓碑；跳过使用中的箱子
• 全量 ZDO 数据操作（远处箱子无需加载）

0.2.0

• 新增：自研"附近存储"（可配置范围、过滤规则、串行队列 + 超时）
• 新增：宝箱界面按钮注入
• 新增：ExtraSlots 软依赖（额外 Utility 槽装备检测与专用槽位过滤）
• 新增：Valheim Plus AutoStack 门控（启用附近存储时屏蔽 V+ 扩散）

0.1.0

• 初始版本（P0）：
• 四级虚空宝箱物品链（黑金属 / 魔能 / 烈焰 / 水晶）
• 角色级数据（Player.m_customData），跨世界携带；物品仅作为钥匙
• 虚拟容器 + 原版容器 UI（堆叠 / 取出可用）
• 容量随等级裁剪显示；低等级打开数据保留
• 配方链（熔炉 / 黑熔炉）、图标与材质运行时换色