魔法物品储藏室

功能特性

双重存储模式

• 本地模式 (默认) — 离线 JSON 文件存储，无需 API 或 Discord，开箱即用。
• 网页模式 — 云端同步保险库，配有网页控制面板、Discord 绑定及跨服务器转移功能。
• 可通过 config.json 随时切换模式
• /miv import 和 /miv export 命令可在模式间迁移保险库数据 (仅管理员)

物品保险库

• 每位玩家拥有各自独立的保险库，每个服务器单独存储
• 原生箱子风格 UI，容器面板中显示保险库的 3D 模型
• 物品在服务器重启或世界重置后仍保留
• 带智能防抖功能的自动保存，防止数据丢失
• 内置自动排序支持
• 可配置保险库容量 (最多 63 格)

可合成的保险库方块

• 在工作台 (巧工类别) 合成魔法物品保险库
• 配方: 1 个破旧箱子 + 5 个金锭 + 5 个银锭
• 放置在世界中后按 F 键打开 — 与普通箱子无异
• 带开合动画的自定义 3D 模型 (仍处于重度开发阶段)
• 可朝 4 个方向旋转 (北/东/南/西)

跨服务器物品转移 (网页模式)

• 服主可将其他 MIV 服务器加入白名单以启用物品转移
• 转移需要双向白名单 — 双方服务器均需互相批准
• 通过网页控制面板拖放即可转移服务器间物品
• 黑名单物品被禁止转移到不允接收它们的服务器
• 所有转移操作均有完整审计日志 (操作者、内容、来源、去向)

网页控制面板 (网页模式)

• 完整功能的网页界面，位于 miv.hytaletravelers.com
• 查看你在所有玩过的服务器上的全部保险库
• 通过搜索、排序 (按名称、数量、稀有度) 和筛选浏览物品
• 物品详情弹窗，显示 ID、数量、耐久度、稀有度、槽位及元数据
• 在白名单服务器之间拖放转移物品
• 侧边栏按转移关系分组服务器
• 服务器在线/离线状态实时指示
• 自动刷新保持保险库视图最新 (3 秒轮询)
• 带缓存的云端 API 提供物品图标

Discord 账号绑定 (网页模式)

• 通过网页界面的 OAuth 将游戏账号绑定至 Discord
• 在网站上生成绑定码，然后在游戏内使用 /miv link <code>
• 一次性设置 — 跨会话保持绑定状态
• 每位玩家对应一个 Discord 账号，每个 Discord 账号对应一位玩家
• 在本地模式下，/miv link 无需使用，并会提示玩家

服务器管理 (网页模式控制面板)

• 注册服务器并接收 API 密钥
• 按服务器配置保险库容量 (1-63 格)
• 管理服务器白名单 — 控制哪些服务器可发送/接收物品转移
• 管理物品黑名单 — 阻止特定物品被存放在保险库中
• 密钥泄露时可重新生成
• 查看服务器在线状态 (基于最后心跳)

命令

命令	描述
/miv vault	打开你的保险库 (也可用 /miv open、/miv chest、/miv storage)
/miv link <code>	绑定你的 Discord 账号 (仅网页模式)
/miv status	查看保险库系统状态和配置信息
/miv import	从网页 API 导入保险库数据到本地存储 (仅管理员)
/miv export	从本地存储导出保险库数据到网页 API (仅管理员)
/miv help	显示所有可用命令
/miv reload	重载插件配置 (管理员)
/miv info	显示插件信息 (管理员)

配置

插件会生成一个 config.json 文件，每个设置有内联帮助：

• storageMode — "local" (默认) 或 "web"
• vaultCapacity — 保险库槽位数 (默认: 63，本地模式下使用；网页模式下从 API 获取)
• allowCommandOpen — 允许使用 /miv vault 命令，或仅限通过保险库方块交互打开
• API 设置 — apiBaseUrl、apiKey、serverIp (网页模式必填；本地模式下导入/导出时可选)
• 服务器白名单 — 控制哪些其他服务器可向你的服务器转移物品 (网页模式)
• 物品黑名单 — 阻止特定物品被存储或转移 (网页模式)
• 调试模式 — 启用详细日志以进行故障排除

图标同步 (网页模式)

• 物品图标从游戏自动上传到云端 API
• 图标在网页控制面板上显示在每个物品旁边
• 搜索基础游戏和模组目录中的图标资源
• 启动时预加载已知图标以减少上传量

审计日志 (网页模式)

• 所有保险库操作均被记录：存入、取出、转移、绑定、服务器注册
• 每条日志条目包含时间戳、操作类型、用户、服务器、物品详情
• 存储在服务端，用于问责和调试

安全性与可靠性

• 所有保险库数据在窗口关闭和玩家断开连接时保存
• 脏数据追踪防止不必要的保存/API 调用
• 优雅的错误处理，带有描述性的游戏内消息
• 所有聊天消息中的链接可点击，方便导航
• 详细的系统状态，包含设置帮助和故障排除指导
• 带读写锁的线程安全会话管理
• 每次 API 请求均验证服务器 IP (网页模式)

---

设置 (服主)

本地模式 (默认 — 无需设置)

1. 将插件放入服务器的 mods/ 文件夹
2. 启动服务器 — 将自动创建默认的 config.json
3. (可选) 调整 config.json 中的 vaultCapacity
4. 玩家即可立即合成和使用保险库方块

网页模式

1. 将插件放入服务器的 mods/ 文件夹
2. 启动服务器 — 将自动创建默认的 config.json
3. 在 config.json 中设置 "storageMode": "web"
4. 前往 miv.hytaletravelers.com 并使用 Discord 登录
5. 注册你的服务器并复制 API 密钥
6. 粘贴 API 密钥并在 config.json 中设置你的 serverIp
7. 使用 /miv reload 或重启服务器
8. (可选) 将其他 MIV 服务器加入白名单以启用跨服转移

模式间迁移

• 要将网页保险库数据导入本地：将 storageMode 设为 "local"，保持 apiKey 和 serverIp 配置，然后在游戏内使用 /miv import
• 要将本地保险库数据导出到网页：相同配置，然后在游戏内使用 /miv export

设置 (玩家)

本地模式

1. 合成或找到魔法物品保险库方块，按 F 键打开你的保险库
2. 搞定 — 无需绑定或注册

网页模式

1. 访问 miv.hytaletravelers.com 并使用 Discord 登录
2. 生成一个绑定码
3. 在游戏内使用 /miv link <code>
4. 合成或找到魔法物品保险库方块，按 F 键打开你的保险库