blockbench-particles

Blockbench パーティクル

Blockbench にあるパーティクルシステムは 1 つだけです。それは Bedrock パーティクルエフェクトで、Snowstorm が編集する JSON 形式です。Blockbench は、アニメーションの Effects トラックにある パーティクルキーフレームが発火したときに、Wintersky でプレビューします。ボーン上の ロケーターで発生させることもできます。同じファイルは Minecraft Bedrock でも動作し、GeckoLib アニメーションでは、同じキーフレームが MOD のパーティクルハンドラーに渡されます。Blockbench のその他の形式（glTF、OBJ、Java ブロックモデル、Hytale）では、パーティクルはエクスポートされません。

まず blockbench-use を読み込んでください。パーティクルはアニメーションに紐づくため、モデルにクリップがまだない場合は blockbench-animation も読み込んでください。

1. エフェクトの出力先を決める

出力先が不明な場合は確認してください。以下のすべてがそれによって決まります。

出力先	パーティクル	エフェクトの格納場所
Bedrock のエンティティまたはアタッチャブル（bedrock）	ネイティブ	パーティクル JSON ＋ジオメトリ内のロケーター＋アニメーション JSON またはコントローラーの状態内のキーフレーム＋クライアントエンティティ内の particle_effects マップ。配布を参照してください。
GeckoLib（geckolib_model）	キーフレームのみ	キーフレーム（エフェクト、ロケーター、スクリプト）はアニメーション JSON にエクスポートされます。実際のパーティクルは MOD のパーティクルキーフレームハンドラーが生成します。ここでの Bedrock JSON は Blockbench のプレビュー専用です。
汎用モデル / glTF、Java ブロック／アイテム、Hytale、OBJ	なし	ジオメトリ、発光するフリップブックテクスチャ、ボーンキーフレームでエフェクトを擬似的に表現するか、実行環境に任せてください。パーティクル非対応の出力先を参照してください。

作成を始める前に、トリガーも決めてください。Bedrock では、次の 2 つを異なる方法で扱います。

• アニメーションキーフレーム（manage_particle_keyframes）：発火後は停止指示を送らない方式です。単発のエフェクト（衝撃の火花、着地時の煙、ハート）に適しています。この方法で発火させた ループする エミッターは、ゲーム内で停止しません。また、ループするクリップでは、サイクルごとに新しいエミッターが起動します。ループするクリップに紐づけた連続エフェクトには、looping: false を指定し、duration をクリップの長さと一致させて、時刻 0 にキーフレームを設定してください。
• アニメーションコントローラーの状態：ゲームは状態に入るとエミッターを開始し、状態を抜けると停止します。持続的なループ（燃焼状態、詠唱状態など）には、こちらが適しています。MCP ツールではコントローラーを編集できません。Blockbench の Animation Controllers パネルまたはコントローラー JSON にエントリーを追加してください（配布）。

キーフレームにループエフェクトを設定すると、ツールは警告します。

2. ツール

デスクトッププラグイン（Blockbench を開いている場合）：

ツール	用途
list_particle_presets	プリセット、組み込みのスプライトとテクスチャ、マテリアル、向きのモードを確認します。デザイン前に読み込んでください。
create_particle_effect	プリセットとデザイン用パラメーター（または生の JSON）から、検証後にプレビューへ読み込まれる <pack_root>/particles/<name>.json を作成します。Blockbench のテクスチャまたは PNG からカスタムテクスチャを指定できます。
update_particle_effect	既存ファイルのパラメーターを変更します（各パラメーターが管理するコンポーネントのみを書き換えます）。生の JSON に置き換えることも、ディスクからファイルを読み込むこともできます。
add_locator	エフェクトの生成位置となり、エフェクトが追従するボーン上の名前付きポイントです。ロケーターに対応する形式：Bedrock Entity、GeckoLib、Generic Model。
manage_particle_keyframes	アニメーションのパーティクルキーフレームを追加、削除、一覧表示します。ロケーターと時刻を検証します。
list_particle_effects	読み込み済みエフェクト、使用状況、プレビューの問題、キーフレームでループする際の警告、クライアントエンティティのマップを表示します。
export_particle_pack	使用中のエフェクトとカスタムテクスチャをリソースパックにコピーし、particle_effects マップを返します。
animation_timeline set_time, capture_screenshot	プレビューします。

ヘッドレスサーバー（ファイルのみ、並列エージェント向け）：bbmodel_particle_effect（モデルの隣にファイルを作成または更新）、bbmodel_edit の各操作 add_locator、set_particle_keyframe、remove_particle_keyframe、および bbmodel_particle_pack。キーフレームの file パスは .bbmodel からの相対パスです（particles/smoke.json）。bbmodel_particle_effect に model を指定すると、適切な値を keyframe_file として返します。ヘッドレスサーバーではパーティクルをレンダリングできません。プレビューするには、Blockbench でモデルを開いてください。

3. ワークフロー

1. エフェクトを計画します。 エフェクトが何を伝えるのか、どこで生成されるのか、どれくらい続くのか、ピーク時にパーティクルが何個存在するのか、連続的か単発かを書き出します。スケール、タイミング、色、予算のルールについては、エフェクトデザインを読んでください。
2. ロケーターを配置します。 煙突の先端、口、剣の先、車輪の接地点など、生成位置に配置します。エフェクトを追従させるボーンの子にしてください。位置はモデルの絶対単位です（1ブロックあたり16）。

   add_locator: name="mouth", parent="head", position=[0, 26, -7]
   

3. エフェクトを作成します。 最も近いプリセットを使い、パラメーターを調整します。単位はブロックと秒です。

   create_particle_effect: identifier="mymod:dragon_smoke", preset="smoke",
     design={rate: 10, size: [0.3, 0.9], color: ["#6b5b53cc", "#3a3a3a"], looping: false, duration: 2}
   

   独自の名前空間を使い、minecraft: は使わないでください。カスタムスプライトには、まず小さな PNG（8〜32 px、背景透過）を描画または生成し、texture_image に渡します。スプライトシートには design.flipbook を使います（デフォルトは垂直ストリップで、フリップブックテクスチャと同様です）。
4. キーフレームを設定します。 ループするクリップ上の連続エフェクトの場合：looping: false、duration = クリップの長さのバリアントを指定して、0 にキーフレームを1つ設定します。単発の場合：接触フレームにキーフレームを設定します。

   manage_particle_keyframes: animation_id=<clip uuid>, action="add",
     keyframes=[{time: 0, effect: "mymod:dragon_smoke", locator: "mouth"}]
   

   返された警告をすべて確認し、報告するのではなく修正してください。
5. プレビューします。 Animate モードで、animation_timeline set_time を使って時刻をまず 0 にし、その後、初期、ピーク、終盤の2〜3時点に設定して、それぞれを撮影します。エフェクトを編集した後は、まず時刻を 0 に戻し、新しい設定でエミッターが再始動するようにしてください。近距離だけでなく、想定するカメラ距離で見やすいか確認します。
6. 検証します。 list_particle_effects を使い、問題やチェッカーボード状のテクスチャがなく、数が適切であることを確認します。
7. 納品します。 納品に従い、export_particle_pack でリソースパックにエクスポートし、返された client_entity.particle_effects をクライアントエンティティに貼り付け、アニメーション JSON をエクスポートして、.bbmodel を保存します。書き込んだファイルと、ユーザーに残した手順（クライアントエンティティの編集、コントローラーの状態、ゲーム内での確認）を報告します。

4. エフェクトの破損を防ぐルール

• ピクセルではなくブロック単位です。 パーティクルのサイズ、速度、オフセット、形状の半径はブロック単位です。ロケーターとモデルの座標はピクセル単位です（1ブロックあたり16ピクセル）。ビルボードのsizeは半幅です。0.1はバニラの煙のパフ（幅0.2ブロック）に相当し、0.5はブロック全体に広がります。
• フェードはマテリアルで決まります。 particles_alphaは部分的な透明度を切り捨てるため、アルファグラデーションが目立つ段差になります。煙や柔らかな形状にはparticles_blendを、光（炎、魔法、火花、発光）にはparticles_addを使用してください。
• スプライトの色を保つには白を使います。 色は乗算されます。色付きのスプライト（炎、ハート、泡、ソウル、火）には白、または色指定なしを使用してください。
• 稼働中のパーティクル数に上限を設けます： 発生率 × 寿命です。環境エフェクトのループは約50未満、派手なエフェクトは100未満に抑え、エフェクトの途中で継続的なエミッターがmax_particlesの上限に達しないようにしてください（バリデーターが報告します）。
• ローカル空間とワールド空間： local_space: trueにすると、パーティクルはボーンに追従して動きます（オーラ、リング、周回する粒子）。煙、軌跡、排気は、モデルの移動後もその場に残るようにオフにしてください。キーフレームでbind_to_actor: falseにすると、エミッター全体が生成された位置に留まります。
• プレビューはゲーム内の表示とは異なります。 Blockbenchには衝突するブロックがなく、ライティングも近似的に再現されます。また、ループするエミッターはduration秒ごとに再起動します（プリセットで10 sを使用しているのはそのためです）。可能であれば、ゲーム内で衝突、ライティング、entity_aabbの形状を確認し、確認できない場合はその旨を伝えてください。
• 名前が正しく解決される必要があります。 キーフレームではエフェクトの名前を使用し、クライアントエンティティが名前を識別子に対応付けます。export_particle_packは、名前の競合、テクスチャの欠落、ファイルのないキーフレームを報告します。

参考資料

• エフェクトの設計：計画、プリセット、レシピ、色、タイミング、上限、Molangのパターン、カスタムスプライト。
• Bedrockのパーティクル形式：コンポーネントの早見表、生のJSONの骨組み、イベントとカーブ。ツールの設定では表現できないエフェクト向けです。
• 配布：Bedrockのリソースパックの接続、コントローラーの状態、アタッチャブル、GeckoLibのハンドラー、およびパーティクルに対応していないターゲット向けの代替手段。
• 主な情報源：パーティクルエンティティの統合（Microsoft）、Bedrockのパーティクルに関するドキュメント、手動編集用のSnowstorm、および作成例としてのMojangのバニラのパーティクルファイル。