宝ファイルとは？

宝（treasure）ファイルは、BetterStructuresのチェストのルートテーブルを決定するものです。通常はジェネレーターに割り当てられますが、個別のビルド設定のレベルで指定することもできます。

これらのルートテーブルは非常に強力ですが、理解するには基本的な統計の概念に関する知識も必要です。

統計の基礎知識

それらの概念についてはここをお読みください。このページの残りの部分は、内容を理解していることを前提としています！

重み付き確率

BetterStructuresとEliteMobs（同じ作者による別のプラグイン）は、どちらもルートシステムで重み付き確率という概念を使用しています。これは単純な問題を解決するためのものです。潜在的に無限の長さになりうるアイテムのリストから1つを選ぶ確率を、どう設定すればよいのでしょうか？

重み付き確率では、各アイテムにウェイトを設定します。100個のアイテムのウェイトがすべて1なら、それぞれが選ばれる確率は1%です。ウェイト1のアイテムを追加すると、101個すべての確率が約0.99%になります。最後のアイテムのウェイトを2にすると合計は102になり、そのアイテムの確率は2/102、約1.96%になります。最後のアイテムのウェイトを100にすると合計は200になり、そのアイテムが全体の半分を占めるため、選ばれる確率は50%です。

このように、数百もの候補からランダムに選ぶようなリストを扱う場合に便利な仕組みです。

ガウス分布

ガウス分布は、釣り鐘の形をした数学的な関数です。

これがルートシステムとどう関係するのか疑問に思うかもしれません。BetterStructuresがチェストのルートを設定する際に決めなければならないことの1つが、そのチェストにどれだけのルートを入れるかです。その数量は一貫して特定の値の周辺にあるべきですが、理想的には、チェストを開ける楽しみが薄れるほど予測可能であってはいけません。

この半ランダムな効果を実現するために、選ばれるアイテムの個数をランダム化するのにガウス分布が使われます。個数が決まったら、次に重み付き確率が、ウェイトを考慮しつつレアリティテーブルから要素を1つランダムに選びます。

では、ガウス分布はどのように機能するのでしょうか？

幸いなことに、背後の数学がどう動くかを気にする必要はなく、それを調整する2つの設定、つまり平均（mean）と標準偏差（standard deviation）に集中すればよいのです。

平均（Mean）

meanは、ルートの試行回数を決めるガウス抽選の中心です。実装では切り上げ後の負の値を0にし、さらに1回を加えます。そのため、平均を5にしても、実際に配置されるスタック数の平均がちょうど5になるわけではありません。

標準偏差（Standard deviation）

standardDeviationは最初の抽選値のばらつきを決めます。丸める前のガウス分布では、約68%が平均から標準偏差1個分以内、約95%が2個分以内に収まります。平均5、標準偏差1なら、丸める前の約68%が4から6の間です。標準偏差を変えると、このばらつきが変わります。

これらは確率であり、厳密な最小値や最大値ではありません。実際に配置されるスタック数は、有効なルートエントリやインベントリの空きスロットにも左右されます。

デフォルトのmeanは4、デフォルトのstandard deviationは3です。

実装の詳細

宝システムが内部でどう動作しているかを理解すると、より効果的に設定できます。

最低試行回数

カスタムレアリティリストが空でなければ、試行回数はmax(ceil(gaussian(mean, standardDeviation)), 0) + 1です。1回を加えるため、設定した平均と最終的なスタック数の平均は異なります。少なくとも1回は試行しますが、アイテムテーブルが無効または空の場合、アイテム作成に失敗した場合、チェスト補充イベントがキャンセルされた場合には、チェストが空のままになることがあります。

ランダムなスロット配置

アイテムは最初のスロットから順に詰めるのではなく、チェストのランダムなスロットに配置されます。各スタックはランダムに選ばれた空きスロットに入り、既存の内容が上書きされることはありません。コンテナに空きスロットがなくなった時点で抽選は止まり、最初から満杯のコンテナにはカスタムもバニラも戦利品は入りません。

エラー処理

アイテムのマテリアルがあなたのMinecraftバージョンに存在しない場合（たとえば、アイテム名が変更された新しいバージョンで古い設定を使っている場合など）、そのアイテムはエラーを発生させるのではなく静かにスキップされます。実在するminecraft:のエンチャントキーに解決できないエンチャントのエントリも同様に静かにスキップされますが、存在しないマテリアルをキーとするprocedurallyGeneratedItemSettingsブロックは、該当ファイル名を示す警告をログに出します。

amountがない場合や無効な場合は警告が出ます。読み取った最小値は少なくとも1に、最大値は少なくともその最小値に引き上げられます。未指定なら1、5-2なら固定数5になります。不正な範囲でも、先に読み取れた最小値が残る場合があります。この補正に頼らず、ファイルを修正してください。

レアリティと各アイテムには、有限の正のウェイトを使ってください。ウェイトがない、0、負、または数値でないレアリティは除外されます。ウェイトがない、負、または数値でないアイテムのエントリは破棄され、数値でない値と負の値ではファイル名を示す警告がログに出ます。ウェイトが0のアイテムはテーブルに残りますが、選ばれることはありません。レアリティ内のすべてのアイテムのウェイトが0の場合、そのレアリティが抽選で選ばれても何も追加されません。選択失敗の警告は、プラグインが読み込まれている間、警告カテゴリごとに1回だけ出ます。ファイルごとではありません。すべての不正なウェイトで警告が出るとは限りません。

特別なフォーマット

宝ファイルには、次のような特別なフォーマットがあります。

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

つまり、commonのアイテムはepicのアイテムより6倍ドロップしやすくなっています。weightについての詳細はこちらをお読みください！

ウェイトとは別に、各レアリティテーブルはそれぞれ独自のitemsリストを持ちます。

レアリティ内のアイテム

レアリティのアイテムはマップリストで、そのレアリティテーブルが持つすべてのアイテムを列挙します。

これらのアイテムには次の設定があります。

キー	値	デフォルト
`amount`	min-max 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のいずれか1つだけを使います。有効なmaterialも存在する場合は、シリアライズしたアイテムやMMOItemsより優先されます。手続き型エンチャントはmaterialエントリにのみ適用されます。

mmoitem

MMOItemsプラグインのカスタムアイテムを設定します。これは、バニラのMinecraftマテリアルの代わりにカスタムアイテムを使用するための、materialフィールドの代替手段です。

フォーマットは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ブロック内のそれ以外のものは警告なしでスキップされるため、カスタムエンチャントが静かに何もしないというのは、バグではなく想定どおりの症状です。互換性についてはそのエンチャントプラグインの作者に確認してください。

空のチェストが現れる

最低回数はルートの試行に適用され、アイテムの配置成功を保証しません。空のチェストが見つかる場合は、以下を確認してください。

そのチェストが（他のプラグインではなく）BetterStructuresによって満たされていること
宝ファイル内のすべてのアイテムが有効であること（コンソールの警告を確認）
その宝ファイルが実際に読み込まれていること（起動ログを確認）

統計の基礎知識​

実装の詳細

特別なフォーマット

isEnabled

mean

standardDeviation

vanillaTreasure

items

レアリティ​

レアリティ内のアイテム​

amount​

material​

serializedの扱い​

mmoitem​

info​

weight​

procedurallyGenerateEnchantments​