FreeMinecraftModelsモデル作成の注意事項

ここでは、FreeMinecraftModelsがインポート時と実行時に読み取るモデルファイル、付属ファイル、名前の規則を説明します。

ソース形式

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

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

付属ファイルのない単体の.bbmodelは、次の手順でインポートします：

拡張子を小文字の.bbmodelにして、plugins/FreeMinecraftModels/importsの直下に配置
/fmm reloadを実行
変換された.fmmodelが有効なモデルフォルダに現れ、リロードが成功したことを確認

単体ファイルのインポーターは元ファイルをimportsに残すため、次回以降も変換し直します。同じ場所にある単体の.jsonや.ymlは取り込まず、単体の.fmmodelも受け付けません。付属ファイルのあるモデル一式は、有効なmodelsフォルダ内にまとめるか、正しい構造のコンテンツパッケージにしてください。pack.metaのない任意のimportsサブフォルダはスキップされます。リロードが拒否されると以前のカタログが残る場合があるため、コンソールを確認してください。

単体ファイルの変換ではテクスチャのsource、id、nameだけを残し、アニメーションの寸法や時間のメタデータは削除します。また、textures配列が必要です。こうしたメタデータが必要な場合は、有効なモデルフォルダか元ファイルを保持するパッケージを使ってください。実行時のモデルリーダー自体は、テクスチャ配列がないモデルも受け付けます。

フォルダの役割

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

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

古い環境では、大文字で始まるModelsフォルダがある場合があります。実行時のFreeMinecraftModelsは、小文字のmodelsがあれば優先し、なければModelsを使います。大文字小文字を区別しないファイルシステムでは同じディレクトリですが、区別する場合は両方が存在できます。その場合、共有パッケージインポーターは既存のModelsを優先する一方、ランタイムはmodelsを読みます。サーバーを停止してバックアップを取り、小文字のmodelsに統合し、インポート先が有効なモデルツリーから外れないようにしてください。

モデルID

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

IDの正規化と衝突

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

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

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

変換が実行される前に、FreeMinecraftModelsはモデルツリー全体をスキャンして、同じIDに正規化されるファイルがないかを確認します。2つのコンテンツパッケージが同じモデルを同梱している場合のように、そのIDを持つすべてのファイルがバイト単位で同一であれば、FMMは絶対パスの並び順で最初になるファイルを読み込み、コピーは警告なしでスキップします。ファイルの内容が異なる場合：

すべての衝突ファイルが拒否されます — どれも読み込まれないため、静かに「最後の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ファイルはマージせずに渡されます。マージ済みのoutlinerなら動作する場合がありますが、名前のない生のv5グループノードは、スケルトンリーダーが名前を必要とする箇所でモデルの読み込みに失敗する場合があります
- 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を記録します。空のグループはhas a hitbox bone but no hitbox cube!を記録し、寸法がゼロになります。ヒットボックスがない場合とは異なります。キューブの移動や回転はヒットボックスのオフセットになりません。パーサーは辺の絶対長とゼロのモデルオフセットを使います
- アニメーションされず（hitboxを対象とするアニメーショントラックはスキップされます）、描画もされず、Bedrockのジオメトリエクスポートからも除外されます。Bedrockでは、hitboxボーンのないモデルは1.0 x 2.0にフォールバックします
tag_...
- 作者が任意で追加するネームプレートアンカーです。後述のネームプレートの位置を参照してください
h_...
- ヘッドボーンとして扱われます
b_...
- Javaランタイムの非表示ボーンです。構造用にはキューブのないボーンを使ってください。Bedrockのジオメトリエクスポートはb_プレフィックスを除外しないため、そのボーンのキューブが表示される場合があります
m_...
- マウントポイントボーン。このプレフィックスを持つ各ボーンは、MountPointManagerが管理するプレイヤー用の座席を作成します。複数のm_ボーンで複数の座席になります。マネージャーは最初の空席を選び、使用中は一時的なInteractionエンティティを使います。公開のマウントメソッドが受け付けるのはプレイヤーで、任意のエンティティではありません。

プレフィックスは大文字小文字を区別しますが、hitboxという名前の比較は区別しません。これらの名前は変換と実行時の動作に影響します。

ネームプレートの位置

tag_ボーンは任意です。FMMは名前のアルファベット順で最初のtag_ボーンをネームプレートのアンカーにします。なければ、スケール適用後のヒットボックスの上に配置するため、タグのないモデルでも名前を表示できます。

自動配置が適切でない場合は、キューブのないtag_nameボーンを使ってください。タグボーンを複数作っても、同じネームプレートが複数表示されることはありません。

APIは複数行の名前、スケール、行間、表示・非表示に対応しています。行は上から下の順で、最終行がアンカーの位置になります。APIガイドを参照してください。

キューブのシェーディングと発光

Blockbenchのキューブのlight_emission値は、0から15の整数であれば保持されます。それ以外の値は破棄され、with invalid light_emission. Expected an integer from 0 to 15; ignoring this value.で終わる警告がコンソールに出力されます
シェーディングをオフにしたキューブ（shade: false）には、生成されるジオメトリでshade_direction_override: "up"も付与されるため、Minecraft 26.3のクライアントでも旧クライアントと同じくシェーディングなしで描画されます。FMMは同じルールを兄弟のディスプレイモデル.json内のキューブにも適用します。自分で設定した値は保持されます

浮遊キューブ

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

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

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

IKコントローラーとしてのBlockbenchヌルオブジェクト
IKチェーンブループリントとランタイムIKソルビング（FABRIK）
ロケーターのパース。ロケーターはBlockbenchのパーティクルエフェクトのアンカーにもなります。パーティクルを参照してください

ヌルオブジェクトがIKコントローラーになるには、.bbmodelエントリにik_source（ソースボーン）とik_target（ターゲットボーンまたはロケーター）の両方が必要です。インポーターは兄弟間や下方向も含めて階層を探索します。ルート階層の兄弟同士ではソースだけのチェーンになります。lock_ik_target_rotationは読み取って保存されますが、現在のソルバーは適用しません。

重要な実用上の制約：

ソース／ターゲットのリンクは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を動かしません

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を読み取り、リソースパックにコピーしてtexturesマップ内の名前空間のない値を書き換えます。数値のテクスチャキーは抽出済みテクスチャのインデックスに対応し、一致しないキーには利用可能なテクスチャがあればそれを使います。名前空間付きの値は変更しません。付属JSONがない場合はベースマテリアルの外観になり、通常はプロップ設置アイテムなら紙、手持ちアイテムなら設定されたマテリアルです。不正な付属ファイルはFailed to process display model JSON for ...を記録し、そのディスプレイモデルを登録しません。

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

モデルの付属YAMLにmaterialを設定すると、手持ちアイテムを登録できます：

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
lore:
  - "&7A blade with a fire enchantment"
enchantments:
  - "minecraft:fire_aspect,2"

エンチャントIDは小文字で名前空間付きにしてください。革のマテリアルにはLEATHER_CHESTPLATE:ff8800のようなRGBの染色サフィックスを付けられます。設定を参照してください。未対応のマテリアル、名前空間のないエンチャント、空でないscripts:リストを持つアイテムは利用できません。コンソールに理由が表示され、元ファイルは保持されます。scripts:は引き続きプロップ専用です。

真偽値でないisEnabled、形式が不正なエンチャント項目、重複エンチャント、不正なアイテムファイル名などは、候補カタログとリロード全体の拒否につながる場合があります。アイテムファイル名は小文字で、a-z、0-9、.、_、-のみを使い、128文字以内にしてください。カスタムアイテムの走査は.ymlを読み、.yamlは読みません。登録済みアイテムは/fmm giveitem <item>または管理者ブラウザで取得します。プロップのレシピやショップ購入で得られるのは、紙の設置アイテムです。

アイテムの効果はエンチャント定義で設定します。ワンドやスタッフは魔法武器の設定を使います。いずれも旧装備アイテム用Luaランタイムは使いません。

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はリソースパック生成時に弓とクロスボウの表示状態を自動検出します。各必須状態には、読み込み済みモデルと、処理に成功した付属ディスプレイ.jsonの両方が必要です。ファイル名だけでは不十分です。手持ちアイテムをベース名で設定し、適切なBOWまたはCROSSBOWマテリアルを使ってください。

命名規則

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

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

ファイルレイアウトの例

plugins/FreeMinecraftModels/models/my_weapons/
  cool_bow_idle.bbmodel
  cool_bow_idle.json
  cool_bow_draw_start.bbmodel
  cool_bow_draw_start.json
  cool_bow_draw_half.bbmodel
  cool_bow_draw_half.json
  cool_bow_draw_full.bbmodel
  cool_bow_draw_full.json
  cool_bow.yml

クロスボウの場合はcool_bow_charged.bbmodelとcool_bow_charged.jsonも追加します。アイテム設定は_idleを付けないベース名のcool_bow.ymlです。

検出の仕組み

検出はリソースパック生成時（起動時または/fmm reload時）に自動的に行われます。
表示状態が一式そろうと、cool_bow.jsonのようにベース名で1つの公開アイテム定義を生成します。_idle、引き絞り、装填済みの各アイテム定義は削除されますが、ジオメトリはベース定義から参照され続けます
ディスプレイレジストリはベースIDを公開し、状態IDを削除します。_chargedを含む完全な一式はクロスボウ、含まなければ弓として扱います。表示状態が不足しているとグループ化しません
YML設定にはcool_bow.ymlのようなベース名を使います。アイテムカタログは状態サフィックス付きYMLをスキップし、プロップ設定の検索でもサフィックスを除去します

ディスプレイモデルJSON

各必須状態には、cool_bow_idle.jsonやcool_bow_draw_full.jsonのように、それぞれ付属ディスプレイ.jsonが必要です。FMMは生成したベースアイテム定義を通じてそれらを接続します。条件と出力先はリソースパック出力を参照してください。

範囲外

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

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

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

ソース形式​

フォルダの役割​

モデルID​

IDの正規化と衝突​

Blockbench互換性​

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

ネームプレートの位置​

キューブのシェーディングと発光​

浮遊キューブ​

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

1.21.4+出力の分離​

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

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

Bedrockとレンダーパスの注意​

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

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

命名規則​

ファイルレイアウトの例​

検出の仕組み​

ディスプレイモデルJSON​

範囲外​