卡尔·卡尔曼的奖励箱

奖励箱核心 - 技术文档

reward_box 是一个用于 Minecraft 1.20.1（Forge）的数据驱动箱子框架。数据包控制箱子内容、纹理、挖掘掉落物和玩家所有权锁定。

---

1. 概述与架构

• 客户端/服务器分离： 服务器处理箱子逻辑和战利品生成。客户端处理箱子纹理和 3D 物品渲染。
• 延迟战利品生成： 只有当玩家首次打开箱子时才会生成战利品。

---

2. JSON 配置

将箱子定义存储在以下数据包路径中： data/<命名空间>/reward_boxes/<箱子名称>.json

{
  "box_id": "stones:resonance_box",
  "texture": "stones:textures/entity/chest/resonance_chest.png",
  "lock_duration_seconds": 300,
  "break_drop_item": "minecraft:lapis_lazuli",
  "break_drop_count": 1,
  "guaranteed_items": [
    {
      "item": "minecraft:diamond",
      "count": 2
    }
  ],
  "vanilla_loot_pools": [
    {
      "loot_table": "minecraft:chests/simple_dungeon",
      "rolls": 3
    }
  ]
}

参数说明

键	类型	描述	默认值
box_id	字符串	箱子的唯一标识符。	(必填)
texture	资源路径	模组资源中 64x64.png 纹理的路径。	默认纹理
lock_duration_seconds	整数	锁定持续时间（秒）。设置为 0 可禁用锁定。	300
break_drop_item	资源路径	方块被破坏时掉落的物品 ID。	reward_box:reward_chest
break_drop_count	整数	方块被破坏时掉落的物品数量。	1
guaranteed_items	数组	始终在箱子中生成的物品列表。	[]
vanilla_loot_pools	数组	用于抽取箱子战利品的原版战利品表列表。	[]

3. 机制与权限系统

• 玩家锁定： 方块实体在放置时保存玩家 UUID 和名称。其他玩家会收到带有剩余锁定时间的动作栏消息。

• 管理员绕过： 处于创造模式或拥有权限等级 2+ 的玩家可以随时打开已锁定的箱子。

• 物品 NBT 数据： 箱子物品从 NBT 标签 BoxId（字符串）和 RewardTier（整数）中读取属性。

• 创造模式标签页与 JEI/EMI： 创造模式标签页会动态列出所有已加载的 JSON 配置及其示例等级。