什么是宝藏文件？

宝藏文件决定了 BetterStructures 箱子的战利品表。它们通常分配给生成器，但也可以在单个建筑配置级别设置。

这些战利品表非常强大，但也需要了解一些基本的统计概念才能理解。

统计学概念

在这里阅读这些概念，页面的其余部分假设你已经理解它们！

加权概率

BetterStructures 和 EliteMobs（同一作者的另一个插件）都在其战利品系统中使用加权概率的概念。这是为了解决一个简单的问题：如何设置从可能无限的物品列表中选择某个物品的概率？

加权概率为每个物品分配权重。100 个物品的权重都为 1 时，每个物品被选中的概率是 1%。再添加一个权重为 1 的物品，101 个物品的概率就都变为约 0.99%。如果最后一个物品的权重改为 2，总权重变为 102，它被选中的概率就是 2/102，约 1.96%。如果最后一个物品的权重改为 100，总权重变为 200，它占总权重的一半，被选中的概率就是 50%。

如你所见，当你可能有数百个需要随机选择的物品时，这个方法非常有用。

高斯分布

高斯分布是一个钟形的数学函数。

你可能想知道这与战利品系统有什么关系。BetterStructures 在设置箱子战利品时需要决定的一件事是箱子里出现多少战利品。数量应该始终在某个特定数字附近，但最好不要太可预测，以使开箱更加令人兴奋。

为了实现这种半随机效果，使用高斯分布来随机化选择多少物品。一旦确定了这个数量，加权概率就会从稀有度表中随机选择一个元素并考虑权重。

那么高斯分布是如何工作的？

幸运的是，你不必担心其背后的数学原理，只需关注修改它的两个设置：均值和标准差。

均值

mean 设置用于确定战利品尝试次数的高斯抽样中心。实现会向上取整，将负值限制为零，再增加一次尝试。因此，均值为 5 并不意味着实际放入的物品堆平均恰好为 5。

标准差

standardDeviation 控制初始抽样的分散程度。取整前，约 68% 的高斯值落在均值上下一个标准差以内，约 95% 落在两个标准差以内。均值为 5、标准差为 1 时，约 68% 的原始结果在 4 到 6 之间。调整标准差会改变这种分散程度。

这些是概率，不是严格的最小值或最大值。最终放入的物品堆数还取决于战利品条目是否有效，以及物品栏是否有空槽位。

默认均值为 4，默认标准差为 3。

实现细节

了解宝藏系统的内部工作原理可以帮助你更有效地配置它：

最少尝试次数

自定义稀有度列表非空时，战利品尝试次数为 max(ceil(gaussian(mean, standardDeviation)), 0) + 1。额外的一次尝试意味着配置的均值不是最终物品堆数的平均值。至少会尝试一次，但物品表无效或为空、物品创建失败或箱子填充事件被取消时，箱子仍可能为空。

随机槽位放置

物品放在箱子内的随机槽位中，而不是从第一个槽位开始依次填充。每堆物品会放入一个随机选中的空槽位，已有内容永远不会被覆盖。容器没有空槽位后，抽取就会停止；本来就已装满的容器不会获得任何战利品，无论是自定义还是原版战利品。

错误处理

如果物品材料在当前 Minecraft 版本中不存在，该条目会被静默跳过。无法解析为实际 minecraft: 附魔键的条目也会被静默跳过。不过，以不存在的材料为键的 procedurallyGeneratedItemSettings 块会记录包含文件名的警告。

缺少或无效的 amount 会产生警告。读取到的最小值会提高到至少 1，最大值会提高到至少等于最小值。未指定数量会变为 1，5-2 会变为固定数量 5。格式错误的范围可能保留已成功解析的最小值。请修正文件，不要依赖这种修补。

稀有度和物品都应使用有限的正权重。权重缺失、为零、为负或不是数字的稀有度会被忽略。权重缺失、为负或不是数字的物品条目会被丢弃；非数字值和负值会记录一条注明文件名的警告。权重为 0 的物品会留在表中，但永远不会被选中。如果某个稀有度中所有物品的权重都为 0，抽到该稀有度时不会添加任何物品。选择失败的警告在插件保持加载期间，每个警告类别只出现一次，而不是每个文件一次。不要指望所有错误权重都会触发警告。

特殊格式

宝藏文件有一个特殊格式，如下所示：

isEnabled: true
mean: 4.0
standardDeviation: 3.0
vanillaTreasure: BURIED_TREASURE
items:
  common:
    weight: 60
    items:
    - amount: 1-1
      material: STONE_PICKAXE
      procedurallyGenerateEnchantments: true
      weight: 1.0
    - amount: 1-1
      material: STONE_SHOVEL
      procedurallyGenerateEnchantments: true
      weight: 1.0
  rare:
    weight: 30
    items:
    - amount: 1-1
      material: ANVIL
      weight: 6.0
    - amount: 1-6
      material: BEETROOT
      weight: 6.0
  epic:
    weight: 10
    items:
    - amount: 2-10
      material: DIAMOND
      weight: 1.0
    - amount: 1-1
      material: DIAMOND_AXE
      weight: 6.0
procedurallyGeneratedItemSettings:
  golden_sword:
    bane_of_arthropods:
      minlevel: 1
      maxlevel: 5
      chance: 0.2
    looting:
      minlevel: 1
      maxlevel: 3
      chance: 0.2

这是精简示例。附带的宝藏文件包含更大的物品表和附魔设置，部分预设的均值和标准差也不同。例如，木桶食物表的均值为 1，标准差为 0.7。

isEnabled

键	值	默认值
`isEnabled`	Boolean	`true`

此字段会保存，但当前宝藏加载器和战利品抽取逻辑不会用它禁用表。仅设置为 false 不会停止战利品生成。请禁用对应的建筑或生成器；木桶则可使用木桶战利品开关。

mean

键	值	默认值
`mean`	Double	`4`

设置 mean（均值）。在这里阅读相关详情。

standardDeviation

键	值	默认值
`standardDeviation`	Double	`3`

设置 standardDeviation（标准差）。在这里阅读相关详情。

vanillaTreasure

键	值	默认值
`vanillaTreasure`	String	无，随附的 `vanilla_*` 文件除外

设置在自定义战利品之外使用的可选原版战利品表。使用 Bukkit 的 LootTables 枚举值，例如 BURIED_TREASURE、SHIPWRECK_TREASURE、SIMPLE_DUNGEON，不区分大小写。原版抽取在自定义战利品之后进行，使用剩余空槽位。未设置时只使用自定义战利品；无效名称会产生警告并禁用原版部分。

随附的原版宝藏文件在缺少此键时会默认使用对应的战利品表：vanilla_bastion_treasure.yml 使用 BASTION_TREASURE，vanilla_buried_treasure.yml 使用 BURIED_TREASURE，vanilla_end_city_treasure.yml 使用 END_CITY_TREASURE，vanilla_fishing_treasure.yml 使用 FISHING_TREASURE，vanilla_shipwreck_treasure.yml 使用 SHIPWRECK_TREASURE。其他任何文件都需要明确设置此字段；仅凭 vanilla_* 文件名不会选择战利品表。

items

这里变得有些复杂，因为管理员可以设置许多选项。让我们放大之前的配置文件示例。

items:
  common:
    weight: 60
    items:
    - amount: 1-1
      material: STONE_PICKAXE
      procedurallyGenerateEnchantments: true
      weight: 1.0
    - amount: 1-1
      material: STONE_SHOVEL
      procedurallyGenerateEnchantments: true
      weight: 1.0
  rare:
    weight: 30
    items:
    - amount: 1-1
      material: ANVIL
      weight: 6.0
    - amount: 1-6
      material: BEETROOT
      weight: 6.0

在这里，你可以看到 items 配置键下有一个包含 common 和 rare 的映射。这些就是 rarities（稀有度）！

稀有度

稀有度没有固定的名称。你可以添加或删除它们，并根据需要进行自定义，只要使用相同的格式即可。

请注意，使这些稀有度表更稀有或更常见的是战利品表的 weight（权重）！

默认情况下：

common 的默认 weight 为 60
rare 的默认 weight 为 30
epic 的默认 weight 为 10

使普通物品的掉落概率是史诗物品的 6 倍。你可以在这里阅读更多关于 weight 的信息！

除了权重之外，每个稀有度表都有自己的 items 列表。

稀有度物品

稀有度物品是一个映射列表，列出了稀有度表拥有的所有物品。

这些物品有以下设置：

键	值	默认值
`amount`	最小-最大 Integer	可变
`material`	Material	可变
`procedurallyGenerateEnchantments`	Boolean	可变
`weight`	Double	可变

amount

设置掉落数量。可以表示为范围 amount: MIN-MAX 或单个值 amount: VALUE 表示固定数量。示例：

可变数量：amount: 1-5（掉落 1 到 5 个物品）
固定数量：amount: 3（始终掉落正好 3 个）

material

使用 Spigot API 名称设置可能掉落物品的材料。

serialized 的特殊处理

/bs lootify 使用 Bukkit 物品序列化写入 serialized 映射，保留手持物品的数据。请用命令生成，不要手动构造。每个条目只使用一种物品来源：material、serialized 或 mmoitem。如果同时存在有效的 material，它优先于序列化物品或 MMOItems 物品。程序化附魔只适用于材料条目。

mmoitem

设置来自 MMOItems 插件的自定义物品。这是 material 字段的替代方案，用于使用自定义物品而不是原版 Minecraft 材料。

格式为：mmoitem: TYPE@ITEMNAME

示例：

- amount: 1-1
  mmoitem: SWORD@Excalibur
  weight: 1.0

需要 MMOItems。字段名也接受 mmoitems。无效的物品查询通常会产生警告并跳过条目，但对未安装 MMOItems 的情况没有可靠保护。缺少类可能导致内容加载失败。请安装依赖，或在加载文件前移除这些条目。

info

用于向物品条目添加备注或注释的可选字段。此字段被插件完全忽略，仅用于管理文档目的。使用它来提醒自己某些物品为何以特定方式配置。

示例：

- amount: 1-1
  material: DIAMOND_SWORD
  weight: 1.0
  info: "Rare drop for completing the dungeon"

weight

设置加权概率的权重。更多信息请点击这里。

procedurallyGenerateEnchantments

设置物品是否应根据 procedurallyGeneratedItemSettings 中的设置程序化生成。请注意，根据设置，这可能导致物品生成时没有附魔。

procedurallyGeneratedItemSettings

让我们再看看我们的配置文件示例：

procedurallyGeneratedItemSettings:
  golden_sword:
    bane_of_arthropods:
      minlevel: 1
      maxlevel: 5
      chance: 0.2
    looting:
      minlevel: 1
      maxlevel: 3
      chance: 0.2

如你所见，此文件列出了材料类型，后跟附魔，然后是最小和最大等级以及概率。

此部分接受 Bukkit 材料及注册在 minecraft: 命名空间下的附魔，其他附魔命名空间会被跳过。需要保留其他插件提供的物品时，请使用序列化物品条目。

如果宝藏文件中没有 procedurallyGeneratedItemSettings 部分，BetterStructures 会把默认附魔表写入该文件。已经包含此部分的文件只使用其中列出的条目。

至于附魔设置：

键	值	默认值
`minlevel`	Integer	可变
`maxlevel`	Integer	可变
`chance`	Chance	可变

minlevel

设置最小附魔等级。应至少为 1，且不大于 maxlevel。

maxlevel

设置最大附魔等级，随机抽取包含此值。插件不会将其限制在原版附魔上限内，而是绕过 Bukkit 的等级限制添加附魔。无效数字或颠倒的范围可能导致加载或物品创建失败。

chance

设置附魔被应用的概率，作为 0.0（永不）到 1.0（总是）之间的小数值。例如，值 0.2 表示 20% 的概率。这使用简单的概率检查，而不是像物品选择系统那样的加权概率。

故障排除

物品未出现在箱子中

确认建筑和生成器已启用，并引用有效的宝藏文件。即使 schematic 设置了覆盖项，生成器也仍需有效的宝藏表
检查控制台是否有关于无效材料或物品的警告
如果使用自定义物品，确保已安装 MMOItems
材料必须使用精确的 Spigot API 名称

附魔未应用

在物品上设置 procedurallyGenerateEnchantments: true
验证附魔名称匹配 Minecraft 的命名空间键
检查最小/最大等级是否在该附魔的有效范围内
记住 chance 值是概率（0.2 = 20%），不是保证

自定义插件附魔不工作

只有注册在原版 minecraft: 命名空间下的附魔才会被读取。procedurallyGeneratedItemSettings 块中的其他任何内容都会被跳过且不给出警告，因此一个悄无声息毫无作用的自定义附魔是预期的表现，而不是 bug。请与附魔插件的作者确认兼容性。

出现空箱子

最小值适用于战利品尝试次数，不保证成功放入物品。如果你看到空箱子，请验证：

箱子正在被 BetterStructures 填充（不是其他插件）
宝藏文件中的所有物品都是有效的（检查控制台警告）
宝藏文件确实被加载了（检查启动日志）

统计学概念​

实现细节

特殊格式

isEnabled

mean

standardDeviation

vanillaTreasure

items

稀有度​

稀有度物品​

amount​

material​

serialized 的特殊处理​

mmoitem​

info​

weight​

procedurallyGenerateEnchantments​