FreeMinecraftModelsモデル作成の注意事項

このページでは、FreeMinecraftModelsのコードベースで確認できる現在のオーサリングの詳細を文書化しています。意図的に控えめな内容にしています：すべてのBlockbenchワークフロー設定ではなく、インポート/ランタイムの規約に焦点を当てています。

ソース形式

FreeMinecraftModelsは現在、以下を受け付けます：

• .bbmodelファイル（編集可能なソースインポート用）
• .fmmodelファイル（軽量化されたランタイム対応モデルデータ用）

通常のインポートフローは以下の通りです：

1. plugins/FreeMinecraftModels/importsにモデルを配置
2. /fmm reloadを実行
3. FreeMinecraftModelsがモデルをアクティブモデルセットにインポートし、生成リソースパックを再構築するのを待つ

フォルダの役割

plugins/FreeMinecraftModels/imports
plugins/FreeMinecraftModels/models
plugins/FreeMinecraftModels/models_disabled

• importsは手動モデルインポートおよび公式パッケージダウンロードの処理前の受け取りフォルダです
• modelsはアクティブなインストール済みモデルコンテンツを含みます
• models_disabledは現在無効になっているダウンロード済みまたはインストール済みのパッケージコンテンツを含みます

古いインストール環境では、代わりに大文字始まりのModelsフォルダが存在する場合があります。FreeMinecraftModelsは、正規の小文字modelsが存在すればそちらを優先し、存在しない場合にのみ旧来のModelsにフォールバックすることでこれを解決します。WindowsとmacOSではどちらの名前も同じディレクトリを指しますが、大文字小文字を区別するLinuxのファイルシステムでは、古いインストールもそのまま動作します。ただし両方のディレクトリが何らかの理由で存在する場合、小文字のmodelsだけが読み込まれます。両方見つかった場合はmodelsに統合してください。

モデルID

• ランタイムモデルIDはファイル名から取得され、.bbmodelまたは.fmmodel拡張子は含まれません
• コマンドやAPI呼び出しがこのIDで解決するため、安定した一意のファイル名を使用してください
• Blockbenchのアニメーション参照は名前ベースのため、モデル内での重複や不明確な命名はクリーンで明示的な命名規則よりも問題を引き起こしやすくなります
• 拡張子の照合は大文字小文字を区別しないため、.BBModelや.FMModelも受け付けられます

IDの正規化と衝突

ファイル名は、ランタイムのモデルIDおよびリソースパックのファイル名になる前に正規化されます：

1. 小文字化する
2. a-z、0-9、.、_、- 以外のすべての文字を _ に置き換える

そのため、My Table.bbmodel、my table.bbmodel、my_table.bbmodel はすべて同じID my_table に正規化されます。

変換が実行される前に、FreeMinecraftModelsはモデルツリー全体をスキャンして、同じIDに正規化されるファイルがないかを確認します。衝突が見つかった場合：

• すべての衝突ファイルが拒否されます — どれも読み込まれないため、静かに「最後の1つが勝つ」ことはありません
• そのモデルIDは、その読み込みパスの残りの間ブロックされます
• 拒否されたモデルはBedrockのカスタムエンティティバンドルのエクスポートからも除外されます
• コンソールには次が出力されます：

[FMM Models] Rejected normalized model ID collision '<id>'. These files normalize to the same ID: <paths>. Rename the files so every normalized model ID is unique; no colliding model was loaded.

対処法は常に、正規化後のIDが区別できるようにファイル名を変更することです。最も安全な習慣は、最初から小文字とアンダースコアでモデルファイルに名前を付けること（stone_table.bbmodel）です。そうすればファイル名とランタイムIDが同一になり、思いがけない衝突の可能性がなくなります。

Blockbench互換性

• FreeMinecraftModelsは.bbmodelからmeta.format_versionを読み取り、そのメジャー番号で分岐します
• metaブロックがない、format_versionがない、または解析できない値の場合はいずれもバージョン4にフォールバックし、該当モデル名を示すinfo/warning行が出力されます
• textures配列がない場合も受け付けられ、インポーターがクラッシュする代わりに空のテクスチャリストとして扱われます。ただしBedrockのカスタムエンティティエクスポーターは、Bedrockエクスポートに最低1つのテクスチャが必要なため、そのモデルをスキップします
• 抽出されたテクスチャのファイル名は、.png拡張子1つに正規化されます。body.jpg、body.PNG、bodyのようなソース名は、いずれもbody.pngとして書き出され参照されます
• format_version 4.x 以前：ボーンはoutlinerツリーから直接読み取られ、そこにボーン名がインラインで含まれています
• format_version 5.x 以降：outlinerのスキーマが変更されました。outlinerは、名前キーを持たない、素のUUID文字列と{uuid, isOpen, children}の辞書からなる入れ子ツリーになり、別途フラットなgroups配列が実際のボーンデータ（nameを含む）を保持します。FMMは両者をUUIDで結合します — 各outlinerノードを対応するgroupsエントリで置き換え、その後で子を再帰的にマージします — これによりボーン名、原点、回転が通常どおり解決されます
• .bbmodelファイルを手編集または生成する際に知っておくべき影響：
  • groups配列を欠いたv5ファイルはマージされないまま通過するため、ボーンが名前を失い、予約された接頭辞（tag_、h_、b_、m_、hitbox）が認識されなくなります
  • UUIDはoutlinerとgroupsの間で正確に一致する必要があります。対応するgroupがないoutlinerノードは、破棄されるのではなくそのまま保持されます
  • v5のformat_versionとv4形式のoutliner（またはその逆）を混在させないでください — 分岐は実際の形状ではなく宣言されたバージョンから選択されます
• インポートログでモデル形式がFreeMinecraftModelsと互換性がないと表示された場合、Wikiやコマンドの問題ではなく、まずモデル形式の問題として対処してください

ランタイムに影響するボーン命名規則

現在のコンバーターとスケルトンパイプラインは、いくつかの命名規則を認識します：

• hitbox
  • ヒットボックス生成用に予約されています
  • ビジュアルボーンとして使用するのではなく、モデルのヒットボックスをクリーンに定義する必要があります
  • outliner上のトップレベルのボーンでなければなりません。インポーターはルートレベルしか確認しないため、別のボーンの中に入れ子になったhitboxグループは通常のボーンとして扱われます
  • ちょうど1つのキューブを含む必要があり、それがランタイムの幅（x）、奥行き（z）、高さ（y）を定義します。キューブが余分にあるとhas more than one value defining a hitbox! Only the first cube will be usedが出力され、空のhitboxボーンはhas a hitbox bone but no hitbox cube!を出力してヒットボックスが生成されません
  • アニメーションされず（hitboxを対象とするアニメーショントラックはスキップされます）、描画もされず、Bedrockのジオメトリエクスポートからも除外されます。Bedrockでは、hitboxボーンのないモデルは1.0 x 2.0にフォールバックします
• tag_...
  • モデルがネームタグを持つための唯一の手段です。後述のネームタグにはtag_ボーンが必要を参照してください
• h_...
  • ヘッドボーンとして扱われます
• b_...
  • 非表示ボーン（ランタイムで非表示）。ゲーム内でレンダリングすべきでない構造的または整理用のボーンに使用してください。
• m_...
  • マウントポイントボーン。このプレフィックスを持つ各ボーンはモデル上に乗車可能なシート位置を作成します。プレイヤーやエンティティはランタイムでこれらの位置にマウントできます。複数のm_ボーンで複数のシートが作成されます。内部的にはMountPointManagerによって管理されます。

これらは単なるスタイル規則ではなく、変換とランタイムの動作に影響します。

ネームタグにはtag_ボーンが必要

これは、配布されたコンテンツのモブに名前が付かない最も一般的な原因なので、はっきり述べる価値があります：

モデルがネームタグを持つのは、名前がtag_で始まるボーンを含んでいる場合だけです。 フォールバックはありません。

仕組み：

• インポート時、tag_...という名前のボーンには、ネームタグボーンとしてフラグが立てられた並行の自動生成「メタ」ボーン（fmm_nametag_bone_<name>）が付与されます。パイプライン内でこのフラグを立てるものは他にありません
• ランタイムではスケルトンがフラグ付きのボーンを収集し、tag_ボーンの原点にテキストディスプレイがスポーンされます。その位置とテキストはそのボーンに追従します
• ModeledEntity.setDisplayName(...)とsetDisplayNameVisible(...)はそのコレクションを走査します。tag_ボーンがなければコレクションは空になり、どちらの呼び出しも何もせずに終了します — エラーも警告も名前も出ません

バニラのネームタグが代わりにならない理由：

• 動的モデルは基盤となるリビングエンティティをクライアントから隠すため（setVisibleByDefault(false)と不可視フラグ）、バニラのモブ自身のネームタグも描画されません
• 結果として、呼び出し側のプラグインが表示名を正常に設定したにもかかわらず、まったく名前のないモブになります

実践的なルール：

• モデルが名前を持つエンティティ（EliteMobsのボス、クエストNPC、プラグインがsetDisplayNameを呼ぶもの）を表す場合は、tag_ボーンを追加してください
• ネームタグを浮かせたい位置 — 通常は頭のすぐ上 — に配置してください
• ボーンにキューブは不要です。位置を決めるアンカーです。特にtag_nameはアイテムモデル定義の生成時にスキップされるため、ジオメトリとして描画されることはありません
• tag_ボーンは複数あっても構いません。それぞれが同じ名前を表示する独自のテキストディスプレイを持ちます
• コンソールにnametag bone did not spawn name tagが出ている場合、ボーンは認識されたもののテキストディスプレイのスポーンに失敗しています — tag_ボーンがまったくない場合とは別の問題です

浮遊キューブ

グループに入れずにアウトライナーの最上位で宣言されたキューブは、ボーンエントリではなく素のUUID文字列として届きます。FreeMinecraftModelsはそれらを自動生成されたルートボーン（freeminecraftmodels_autogenerated_root）に接続するため、描画自体は行われます。ただしアニメーションからアドレス指定できないため、アニメーションさせたいものは必ず実際のグループの中に入れてください。

IK、ヌルオブジェクト、ロケーター

現在のコードでサポートが確認されているもの：

• IKコントローラーとしてのBlockbenchヌルオブジェクト
• IKチェーンブループリントとランタイムIKソルビング（FABRIK）
• ロケーターのパース

ヌルオブジェクトがIKコントローラーになるのは、その.bbmodelエントリがik_source（チェーンの起点となるボーン）とik_target（チェーンが到達しようとするボーンまたはロケーター）の両方を持っている場合だけです。lock_ik_target_rotationも読み取られます。チェーンはターゲットからソースへボーン階層を遡ることで検出されるため、この2つは実際につながっている必要があります。

重要な実用上の制約：

• ソース／ターゲットのリンクはUUIDによるものなので、名前変更には耐えます。ただしどちらかのUUIDがモデル内に存在しない場合、コンソールにIK chain in model <model>: Could not find source bone with UUID ...／Could not find target with UUID ...が出力され、そのチェーンはスキップされます
• ソースからターゲットへの経路が見つからない場合はCould not find path from source to targetが出力され、そのチェーンはスキップされます
• コントローラーのアニメーション検索は名前ベースのため、コントローラーの命名はモデル構造とアニメーションデータの間で安定している必要があります
• ヌルオブジェクト上で意味を持つのは位置キーフレームだけで、これがIKのゴールオフセットになります。ヌルオブジェクトの回転・スケールのトラックは無視されます

IKがフレームごとにどう駆動されるかについては、アニメーションを参照してください。

1.21.4+出力の分離

FreeMinecraftModelsはapi-version: 1.21.4を宣言しているため、1.21.4が最低サーバーバージョンであり、常に最新のアイテムモデル定義レイアウトが使用されます：

plugins/FreeMinecraftModels/output/FreeMinecraftModels/assets/freeminecraftmodels/items

レガシー（1.21.4より前）の革の馬鎧オーバーライドの分岐はコード上にまだ存在しますが、現行プラグインをロードできるサーバーがそこに到達することはありません。古いメモや古い出力フォルダを見ている場合、その違いが原因です。

ディスプレイモデルJSON（1.21.4+）

管理者は.bbmodelまたは.fmmodelファイルの隣に同じベース名で.jsonファイルを配置できます（例：table.bbmodel + table.json）。このJSONはBlockbenchから「Java Block/Item」モデルとしてエクスポートされたもので、手に持った時やインベントリに表示された時のアイテムの見た目を定義します。

インポート時に、FMMはこのJSONをリソースパック出力にコピーし、内部のベアテクスチャ参照をモデルの抽出されたテクスチャを指すように自動的に書き換えます。隣接JSONが存在しない場合、アイテムはゲーム内で普通の紙として表示されます。

YMLでのカスタムアイテム設定

隣接する.yml設定ファイル（モデルと同じベース名）は、オプションのアイテムフィールドをサポートするようになりました。material:が設定されている場合、モデルはカスタムの手持ちアイテムとしても利用可能になります。完全なYML形式は以下の通りです：

isEnabled: true
scripts:
  - my_script.lua
material: DIAMOND_SWORD      # optional — if set, model is also a custom item
name: '&b&lMy Custom Sword'  # optional — display name
lore:                         # optional
  - '&7A custom weapon'
enchantments:                 # optional — format: ENCHANTMENT_NAME,LEVEL
  - SHARPNESS,5
  - FIRE_ASPECT,2

material:が存在する場合、モデルはプロップと共に管理者コンテンツブラウザに表示され、機能的なアイテムとしてプレイヤーに付与できます。

Bedrockとレンダーパスの注意

• BedrockサポートはsendCustomModelsToBedrockClientsV2（デフォルトはtrue。古いsendCustomModelsToBedrockClientsキーを置き換えます）および周囲のFloodgate/Geyser/リソースパックパスに依存します
• サポートされているバージョンのJavaクライアントは、useDisplayEntitiesWhenPossibleが有効な場合、ディスプレイエンティティレンダリングを使用できます
• Javaクライアントで正しく表示されるモデルが、Bedrockパスでも自動的に安全であると想定しないでください

実践的なオーサリングアドバイス

• ファイル名はランタイムIDになるため、安定させてください
• Blockbenchのアニメーション検索は名前駆動のため、コントローラーとアニメーションの命名は明示的にしてください
• 予約された仮想ボーン名は意図的に使用してください（hitbox、tag_、h_、b_、m_）— そして、名前を表示させたいモデルにはtag_ボーンが必要であり、なければ何の警告もなく名前なしになることを忘れないでください
• 自動的に発火させたいステートアニメーションにはspawn、idle、walk、attack、deathという名前を付けてください。それ以外はすべて自分でトリガーするカスタムアニメーションです（アニメーションを参照）
• /fmm disguiseで使うことを想定したモデルには、最低でもidleを同梱すべきです。加えて、ディスガイズコントローラーだけが認識するsneakとjumpを用意することもできます（プレイヤーディスガイズを参照）
• Blockbench内だけでなく、/fmm reload後にインポートされた出力を検証してください
• 特に1.21.4+では、ターゲットのMinecraftバージョン用の生成パック内容を確認してください

弓とクロスボウの状態モデル

FMMはカスタムの弓およびクロスボウアイテムの自動引き絞りアニメーション状態をサポートしています。設定は不要です -- モデルファイルに正しいサフィックスを付けて命名するだけで、FMMがリソースパック生成時に自動的に状態セットを検出します。

命名規則

サフィックス	用途	弓	クロスボウ
_idle	手に持っている状態、引いていない・装填されていない	必須	必須
_draw_start	引き始め	必須	必須
_draw_half	半分引いた状態	必須	必須
_draw_full	完全に引いた状態	必須	必須
_charged	装填済みクロスボウ（矢またはロケット）	--	必須

弓には4つのモデルが必要です（_charged以外すべて）。クロスボウには5つすべてが必要です。

ファイルレイアウトの例

plugins/FreeMinecraftModels/imports/
  cool_bow_idle.bbmodel
  cool_bow_draw_start.bbmodel
  cool_bow_draw_half.bbmodel
  cool_bow_draw_full.bbmodel
  cool_bow.yml                  <-- config uses the base name, not _idle

クロスボウの場合は5番目のファイルcool_bow_charged.bbmodelを追加します。

検出の仕組み

• 検出はリソースパック生成時（起動時または/fmm reload時）に自動的に行われます。
• _idleモデルのみが出力パックにアイテム定義JSONを取得します。引き絞りと装填済みの状態はその定義内の条件付きエントリとして参照されます。
• ベース名のみがYML設定ファイルを取得します。上記の例では、設定はcool_bow.ymlであり、cool_bow_idle.ymlではありません。

ディスプレイモデルJSON

各状態モデルには独自の隣接.jsonディスプレイモデルを持つことができます（例：cool_bow_idle.json、cool_bow_draw_full.json）。FMMはそれらを生成されたアイテム定義に自動的に組み込みます。生成される正確なJSON構造についてはリソースパック出力を参照してください。

範囲外

このページでは以下を保証するものではありません：

• 正確なBlockbench UIの手順
• 芸術的なワークフローの好み
• 古いローカルREADME資料に記載されているすべてのレガシー.bbmodelの特殊事項

これらの詳細は、上記の検証済みランタイム規約よりも速く変化します。