FreeMinecraftModelsのパーティクル

FreeMinecraftModelsは、モデルのBlockbenchアニメーションに含まれるパーティクルのキーフレームを再生します。対象はカスタムエンティティ、プロップ、手持ちアイテムです。Javaプレイヤーには、FMMがサーバー上でシミュレートするパケット専用のスプライトとしてパーティクルが表示されます。Bedrockプレイヤーには、元のSnowstormエフェクトがプレイヤー自身のクライアントで描画されます。

アニメーション名と再生ルールについてはアニメーションを、ロケーターやその他のインポート仕様についてはモデル制作メモを参照してください。

Blockbenchでの作成

1. Blockbenchのパーティクルエディター（Snowstorm）でエフェクトを作成し、.jsonのパーティクルファイルとして保存します。
2. エフェクトの発生元にしたい位置に、モデルのロケーターを追加します。ボーン内のロケーターはそのボーンのアニメーションと一緒に動くため、回転する腕に付けたロケーターは腕の軌道に沿って軌跡を残します。
3. アニメーションでEffectsアニメーターを開き、particleキーフレームを追加します。エフェクト名、ロケーター、パーティクルファイルを設定します。任意のスクリプト欄は、エフェクトの開始前にMolangとして実行されます（例：v.size = 2;）。
4. パーティクルファイルとそのテクスチャPNGを.bbmodelの隣（またはその隣のparticles/フォルダ）に置き、モデルと一緒に配布します。

ロケーターのないキーフレームは、モデルの原点で再生されます。モデルに存在しないロケーターを指定したキーフレームも原点で再生され、警告がログに記録されます。

FMMがパーティクルファイルを探す場所

Blockbenchはパーティクルファイルについて作者のローカルパスしか保存しないため、FMMはファイル名で検索します。各エフェクトについて、まずモデルのフォルダ、次にその隣のparticles/フォルダで、以下の順に探します：

1. キーフレームに保存されたファイル名
2. <effect>.particle.json
3. <effect>.json

パーティクルファイルではない.json（エフェクトと同じ名前のディスプレイモデルなど）はスキップされます。何も見つからない場合、コンソールにParticle effect '<effect>' used by animation '<animation>' in <model> was not foundと表示され、それらのキーフレームは破棄されますが、モデルの残りの部分は通常どおり読み込まれます。

テクスチャ

パーティクルファイルのbasic_render_parameters.textureは、パスの最後の部分で照合されます。textures/particle/sparkであれば、FMMはspark.pngを、まずパーティクルファイルの隣、次にモデルの隣、最後にモデルのparticles/フォルダで探します。

PNGが見つからない場合、Javaプレイヤーにはエフェクトの色で着色された無地の白いスプライトが表示され、コンソールに警告が出ます。Bedrockでは元のテクスチャパスが維持されるため、textures/blocks/wool_colored_whiteのようなバニラのBedrockテクスチャはそのまま機能します。Javaでも同じ見た目にするには、対応する名前のPNGを同梱してください。

エフェクトが再生されるタイミング

• エフェクトは、アニメーションがそのキーフレームに到達したときに開始します。ループするアニメーションではループのたびにキーフレームが再び発火し、エミッターが再スタートします。
• アニメーションが停止または切り替わると、ループするエミッターは新しいパーティクルの生成を止めます。すでに空中にあるパーティクルは寿命が尽きるまで残ります。
• どのJavaプレイヤーからもモデルが見えない間、エミッターは一時停止します。filmicModeはすべてのロード済みモデルを表示状態に保つため、そのパーティクルも動き続けます。
• モデルを削除すると、そのエミッターとすべてのパーティクルスプライトがすぐに削除されます。これには死亡、デスポーン、チャンクのアンロード、/fmm deleteallも含まれます。

プロップ

プロップが自動で再生するのはidleだけです。パーティクルのキーフレームをidleに置くか、プロップのLuaスクリプトからキーフレームを含むアニメーションを再生してください：

context.prop:play_animation("sparkle", true, true)

手持ちアイテム

パーティクルはFMMのカスタムアイテム、つまり/fmm giveitemや管理者メニューで入手したアイテムでも再生されます。アイテムのモデルにパーティクルのキーフレームが必要です。FMMは、アイテムが手の中のどこにあるかを求めるため、そのディスプレイモデル（兄弟の.json）のthirdperson_righthandとthirdperson_lefthandのトランスフォームを読み取ります。ディスプレイモデルがない場合、Javaではアイテムにディスプレイトランスフォームがないものとしてパーティクルが配置され、Bedrockでは手持ちアイテムのパーティクルは表示されません。

• FMMは、アイテムをどちらかの手に持っている間、モデルのheldアニメーションをループ再生します。パーティクルのキーフレームを含むheldアニメーションがない場合は、キーフレームを含むアニメーションのうち名前順で最初のものを使います。
• 手持ちアイテムではボーンはアニメーションしません。ロケーターはアイテム上の静止位置にとどまります。
• Java： サーバーは、プレイヤーが一人称、三人称、前面カメラのどれを使っているかを知ることができません。FMMは、持ち主の体の向き、スニーク状態、アイテムを持っている手、scale属性、ディスプレイモデルのトランスフォームから、三人称のポーズでのアイテムの先端にパーティクルを配置します。持ち主を含むすべてのJavaプレイヤーには、その1つの位置に表示されます。一人称では、持ち主には一人称のアイテム上ではなく、三人称での手の位置にパーティクルが見えます。腕の振りやアイテム使用時のポーズは追跡されないため、腕が動いている間はパーティクルがアイテムからわずかに遅れることがあります。持ち主から48ブロック以内のJavaプレイヤーにパーティクルが表示されます。
• Bedrock： パーティクルはアイテムのBedrockアタッチャブルに追加され、Bedrockクライアントがどのカメラ視点でも実際の手の上に描画します。これにはResourcePackManagerのBedrock変換が必要です。

Javaでの描画

• 各パーティクルはitem_displayのパケットエンティティです。ワールドには存在しないため、他のプラグインが当たり判定を取ったり、保存したり、削除したりすることはできません。
• FMMはパーティクルを2ティックごとに動かし、その間の動きはクライアントが補間します。
• UV式は読み込み時にサンプリングされ、エフェクトごとに最大16のテクスチャバリエーションになります。各バリエーションのフリップブックのフレームは、それぞれ独立したスプライトになります。それらのスプライトはリソースパックのassets/freeminecraftmodels/items/particle/<model>/<effect>/に、テクスチャはtextures/entity/fmm_particles/<model>/<effect>.pngに入ります。FMMはassets/freeminecraftmodels/rspm_item_java_only/particle/<model>/<effect>.jsonも書き出し、スプライトアイテムをBedrockのカスタムアイテムに変換しないようResourcePackManagerに伝えます。
• エフェクトにminecraft:particle_appearance_lightingがない限り、パーティクルは最大の明るさで描画されます。
• 1つのモデル上の1つのエフェクトで表示されるパーティクルは、最大でmaxParticlesPerEmitter個、またはファイル自体のmax_particlesがそれより低ければその数までです。1人のJavaプレイヤーに表示されるパーティクルは、すべてのモデルを合わせて最大maxParticlesPerViewer個です。上限を超えると、そのプレイヤー向けの新しいパーティクルは、古いものが消えるまでスキップされます。
• particleEffectsEnabled: falseを設定すると、モデルを編集せずにすべてのエフェクトをオフにできます。

Javaが対応するコンポーネント

コンポーネント	Javaでの対応
emitter_rate_instant、emitter_rate_steady	完全対応
emitter_lifetime_once、emitter_lifetime_looping、emitter_lifetime_expression	完全対応
emitter_initialization	生成時と更新ごとの式
emitter_local_space	位置と回転
emitter_shape_point、_sphere、_box、_disc、_custom	オフセット、半径、半分の寸法、平面の法線、surface_only、およびoutwards、inwardsまたはカスタムの方向
particle_initialization	更新ごとと描画ごとの式
particle_initial_speed、particle_initial_spin	完全対応
particle_motion_dynamic	直線の加速度と抵抗、回転の加速度と抵抗
particle_lifetime_expression	max_lifetimeとexpiration_expression
particle_appearance_billboard	サイズ、向きのモード、方向、フリップブックを含むUV
particle_appearance_tinting	固定色、チャンネルごとの式、グラデーション
particle_appearance_lighting	最大の明るさの既定動作をオフにします

その他のコンポーネント（particle_motion_parametric、particle_motion_collision、emitter_rate_manual、emitter_shape_entity_aabbなど）はJavaでは無視されます。モデルの読み込み時に、コンソールにその名前が一覧表示されます。Bedrockプレイヤーには引き続きエフェクト全体が表示されます。

向きのモードはディスプレイエンティティのビルボードに対応付けられます。rotate_xyz、lookat_xyz、lookat_directionはカメラの方を向きます。rotate_yとlookat_yは垂直軸の周りだけを回転します。direction_x、direction_y、direction_zとemitter_transform_*モードは、パーティクルの方向またはエミッターの回転から決まる固定の向きを保ちます。

Molang

式は算術演算、比較、?:、??、代入、returnに対応しています。数学関数：

abs、acos、asin、atan、atan2、ceil、clamp、cos、die_roll、die_roll_integer、exp、floor、hermite_blend、lerp、lerprotate、ln、max、min、mod、pow、random、random_integer、round、sin、sqrt、trunc、および定数math.pi。

三角関数はBedrockと同じく度数法で動作します。組み込み変数：

• variable.particle_age、variable.particle_lifetime、variable.particle_random_1～_4
• variable.emitter_age、variable.emitter_lifetime、variable.emitter_random_1～_4

初期化式やキーフレームのスクリプトで定義した独自のv.変数も使えます。カーブ（linear、catmull_rom、bezier、bezier_chain）も同様です。未知の変数とクエリは0として読み取られます。

Bedrock

sendCustomModelsToBedrockClientsV2が有効な場合、Bedrockバンドルには各エフェクトがparticles/<model>_<effect>.jsonとして、識別子fmm:<model>_<effect>で含まれます。パーティクルのテクスチャ、ジオメトリのボーン上のロケーター、Bedrockアニメーション内のパーティクルのキーフレームも含まれます。これによりBedrockクライアントは、Javaがスキップするコンポーネントも含めて、エフェクトをネイティブに再生します。

手持ちアイテムについては、FMMはJava出力にassets/freeminecraftmodels/rspm_item_particles/display/<item>.jsonを書き出します。ResourcePackManagerはアイテムの変換時にこれを読み取り、ロケーターとループするパーティクルアニメーションをアイテムのアタッチャブルに追加します。

トラブルシューティング

Particle effect '<effect>' ... was not foundと表示される。 FMMがパーティクルファイルを見つけられませんでした。ファイルを<effect>.jsonまたは<effect>.particle.jsonとしてモデルの隣に置くか、キーフレームに保存されたファイル名で置いてください。FMMがパーティクルファイルを探す場所を参照してください。

... uses <components>, which Java players do not see yetと表示される。 これは情報メッセージです。Javaではエフェクトのそれ以外の部分がすべて再生され、Bedrockではすべてが再生されます。

... uses texture '<path>', which is not next to <file>と表示される。 そのパスの最後の部分にちなんだ名前で、テクスチャPNGをパーティクルファイルの隣に置いてください。

... follows locator '<name>', which the model does not haveと表示される。 ロケーターの名前が変更されたか、削除されています。キーフレームが既存のロケーターを指定するまで、エフェクトはモデルの原点で再生されます。

プロップのパーティクルがまったく表示されない。 プロップが自動で再生するのはidleだけです。キーフレームをidleに移すか、スクリプトからアニメーションを再生してください。

一人称で、手持ちアイテムのパーティクルがアイテムから離れて浮いている。 Javaではこれは想定どおりの動作です。サーバーはパーティクルを三人称での手の位置に配置します。他のプレイヤーや三人称視点では、アイテム上に表示されます。

手持ちアイテムにパーティクルが表示されない。 アイテムはFMMのカスタムアイテム（fmm_item_idを持つもの）である必要があり、そのモデルのアニメーションのいずれかに、FMMがファイルを見つけられたパーティクルのキーフレームが含まれている必要があります。