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は現在無効になっているダウンロード済みまたはインストール済みのパッケージコンテンツを含みます

モデルID

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

Blockbench互換性

• FreeMinecraftModelsはインポート時にBlockbenchファイルバージョンを検出します
• 現在のインポーターにはBlockbench v5より古いバージョンの互換性ブランチが含まれています
• インポートログでモデル形式がFreeMinecraftModelsと互換性がないと表示された場合、Wikiやコマンドの問題ではなく、まずモデル形式の問題として対処してください

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

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

• hitbox
  • ヒットボックス生成用に予約されています
  • ビジュアルボーンとして使用するのではなく、モデルのヒットボックスをクリーンに定義する必要があります
• tag_...
  • ネームタグ関連の仮想ボーンとして扱われます
• h_...
  • ヘッドボーンとして扱われます
• b_...
  • 非表示ボーン（ランタイムで非表示）。ゲーム内でレンダリングすべきでない構造的または整理用のボーンに使用してください。
• m_... または mount_...
  • マウントポイントボーン。このプレフィックスを持つ各ボーンはモデル上に乗車可能なシート位置を作成します。プレイヤーやエンティティはランタイムでこれらの位置にマウントできます。複数のマウントボーンで複数のシートが作成されます。内部的にはMountPointManagerによって管理されます。

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

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

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

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

重要な実用上の制約：

• IKコントローラーの検索は名前ベースのため、コントローラーの命名はモデル構造とアニメーションデータの間で安定している必要があります

1.21.4+出力の分離

Minecraft 1.21.4+では、FreeMinecraftModelsは以下のパスにアイテムモデル定義ファイルを生成します：

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

古いバージョンではレガシーのアイテムモデルパスを使用します。オーサリング中に生成出力を確認する場合は、サーバーバージョンに適した出力形式を確認してください。

ディスプレイモデル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      # オプション — 設定するとモデルがカスタムアイテムにもなります
name: '&b&lMy Custom Sword'  # オプション — 表示名
lore:                         # オプション
  - '&7A custom weapon'
enchantments:                 # オプション — 形式: ENCHANTMENT_NAME,LEVEL
  - SHARPNESS,5
  - FIRE_ASPECT,2

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

Bedrockとレンダーパスの注意

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

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

• ファイル名はランタイムIDになるため、安定させてください
• Blockbenchのアニメーション検索は名前駆動のため、コントローラーとアニメーションの命名は明示的にしてください
• 予約された仮想ボーン名は意図的に使用してください（hitbox、tag_、h_、b_、m_、mount_）
• 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                  <-- 設定は_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の特殊事項

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