godot-particles

パーティクルシステムで絶対にしてはいけないこと

• 動的なパフォーマンス最適化に amount_ratio を絶対に使用しないでください — GPU メモリの節約にも処理の改善にもならず、amount 全体が割り当てられます。代わりに amount プロパティを直接変更してください。
• デスクトップでパフォーマンスが重要なエフェクトに CPUParticles2D を絶対に使用しないでください — GPU 非対応のローエンドモバイルを対象とする場合を除き、GPUParticles を使用してください。ただし、2D で移動するボディの滑らかなトレイルに物理補間が必要な場合は、CPUParticles2D を使用してください。
• preprocess に非常に大きな値を絶対に設定しないでください — 大きな値（例：60 秒）を設定すると、GPU に単一のレンダー処理内で数千フレームをシミュレートさせることになり、即座に GPU がクラッシュするおそれがあります。
• 大規模なシステムで visibility_aabb を未設定のまま絶対に放置しないでください — 不正な AABB はフラスタムカリングのエラー（パーティクルのちらつき）を引き起こし、LOD の計算を妨げます。エディターツールバーを使って AABB を生成してください。
• テストせずにモバイル／Web でタービュランスを絶対に有効にしないでください — パーティクルごとの 3D ノイズ評価は非常に負荷が高くなります。ローエンドのプラットフォームでは、Feature Tags を使って無効にしてください。
• ワンショットの寿命終了処理に Timer を絶対に使用しないでください — smart_oneshot_recycler.gd の使用を推奨します。finished + restart() を使うか、本当に破棄してよいインスタンスに限り queue_free() を使用してください。
• トレイルに local_coords = true を絶対に使用しないでください — 飛翔体の後に残る煙や炎には、必ずグローバル空間（local_coords = false）を使用してください。そうしないと、トレイルが硬い棒のように飛翔体についていきます。
• Godot 4.3 で GPUParticles2D が正しく補間されると絶対に期待しないでください — 物理ボディを親にすると、動きがぎくしゃくします。高速な 2D 移動には fract_delta = true を設定した CPUParticles2D を使用してください。
• finished シグナルの直後に emitting = true を絶対に実行しないでください — GPU の非同期状態による遅延で、再起動に失敗することがあります。代わりに restart() メソッドを使用してください。
• サブエミッターで再帰を絶対に試みないでください — パーティクルシステムは自身をサブエミッターにできません。設定しても何も起こらず、失敗します。
• カラーグラデーションのアルファ値を絶対に設定し忘れないでください — 寿命の終わりにパーティクルが突然消えると不自然に見えます。滑らかに消えるよう、必ず 1.0 にアルファ値 0.0 のグラデーションポイントを追加してください。
• ボリュームのある爆発に EMISSION_SHAPE_POINT を絶対に使用しないでください — すべてのパーティクルを一点から生成すると平面的に見えます。自然な 3D の広がりを得るには、Sphere または Box の形状を使用してください。
• ワンショット VFX で、初期状態の emitting = false を絶対に設定し忘れないでください — これにより、スクリプトでノードを配置する前にシーンの原点で意図せずパーティクルが放出されるのを防げます。

テーブルを選択（一致するスクリプトのみを読み込む）

選択した行では必須です。単一のエフェクトでは、使用しないパーティクルスクリプトを読み込まないでください。

目的	優先するもの	スクリプト
バースト／単発のVFX（ヒット、マズルフラッシュ、爆発）	GPUParticles* + 再利用	必須 particle_burst_emitter.gd + smart_oneshot_recycler.gd
移動体の後ろに残る軌跡	local_coords = false	必須 local_vs_global_coords.gd
天候（雨／雪）のハイトフィールド	カメラに追従する衝突判定	必須 screenspace_weather_heightfield.gd
数百万のエンティティの群れ	GPUParticlesではなくMultiMesh	必須 massive_swarm_multimesh.gd
カスタムGPUモーション／ユーザーデータ	プロセスマテリアルシェーダー	custom_particle_logic.gdshader、dynamic_userdata_modulation.gd
衝突サブエミッター	衝突サブパーティクル	sub_emitter_impact.gdshader
グローバルコストをかけずにアトラクターを使用	cull_maskによる分離	particle_attractor_opt.gd
遠距離の環境VFXのLOD	visibility_range	particle_lod_manager.gd
2D物理ノードに親子付けした軌跡のカクつき	CPUParticles2D + fract_delta	必須 2d_physics_interpolation_fix.gd
シェーダーパラメーターの制御	マテリアルヘルパー	vfx_shader_manager.gd

GPUParticlesとCPUParticles、MultiMeshの比較

• GPUParticles* — デスクトップ／コンソールのVFX量の予算におけるデフォルトです。
• CPUParticles2D — 2D物理補間／滑らかな親子付けが必要な場合にのみ使用します（「使用しないケース」を参照）。
• MultiMesh — エンティティ数がパーティクルの範囲を超える場合に使用します（魚／昆虫／デブリのフィールド）。

利用可能なスクリプト

smart_oneshot_recycler.gd

単発エフェクトのライフサイクルにおける推奨パターンです。finished + restart() を使い、タイマーによる解放は使用しません。

particle_burst_emitter.gd

リサイクラーに接続された単発バーストです。

local_vs_global_coords.gd

オーラと軌跡の座標空間、およびテレポート時の restart() を扱います。

screenspace_weather_heightfield.gd

カメラに追従するハイトフィールド衝突判定によるグローバルな天候表現です。

massive_swarm_multimesh.gd

set_buffer_interpolated() を使用する、数百万のエンティティに対応した手法です。

custom_particle_logic.gdshader

CUSTOM／USERDATAを使用した、プロシージャルなGPUパーティクルのモーションです。

sub_emitter_impact.gdshader

衝突によって駆動される emit_subparticle() のインパクト表現です。

particle_attractor_opt.gd

アトラクターの cull_mask による分離です。

dynamic_userdata_modulation.gd

GPUバッチを崩さずに、実行時のUSERDATAを扱います。

particle_lod_manager.gd

環境VFX向けの visibility_range 階層です。

2d_physics_interpolation_fix.gd

物理ノードに親子付けした2D軌跡に、CPUParticles2D + fract_delta を使用します。

vfx_shader_manager.gd

パーティクルマテリアルへのカスタムシェーダー統合ヘルパーです。

エキスパート向けの要点

• 単発エフェクト：シーンの原点で emitting = false に設定 → 配置 → restart() を呼び出します（smart_oneshot_recycler.gd）。
• 軌跡：local_coords = false に設定しないと、軌跡が投射物に張り付いたままになります。
• ここで爆発／煙／きらめき用のマテリアル設定を独自に考案しないでください。マテリアルUIは公式ドキュメントで扱います。このスキルが担当するのはライフサイクル、座標、LOD、群れの振り分けです。

必要に応じた詳細解説

• 衝突サブエミッター、流体シェーダー、VFX プール → expert-vfx-patterns.md
• VFX プールのリサイクルパターン → vfx_pool_manager.gd
• 理由 GPU パーティクルでは衝突ごとの SFX を発生させられません。CPU に衝突コールバックがないためです。サブエミッターか、ループするインパクト音のみ使用できます。

リファレンス

段階的開示：特定の API を調べる場合にのみ公式ドキュメントのリンクを開き、関連スキルは関連分野へ移行する場合に読み込んでください。全体を事前に読み込まないでください。

公式ドキュメント

• パーティクルシステム（2D） — GPUParticles2D／CPUParticles2D の設定、amount／lifetime／one-shot、および 2D トレイルの滑らかな動きに CPU パーティクルが必要となる場合について説明します。
• ParticleProcessMaterial 2D — 放出形状、重力／速度カーブ、カラ―ランプを扱います。これらを使えば、ほとんどの 2D VFX をカスタムシェーダーなしで作成できます。
• 3D パーティクルシステムの作成 — GPUParticles3D のシーン構成、プロセスマテリアルの割り当て、3D VFX の初回放出チェックリストを説明します。
• プロセスマテリアルのプロパティ — エキスパートパターンで使われる ParticleProcessMaterial の放出、力、スケール／カラーのカーブ、衝突／サブエミッターモードを説明します。
• パーティクルのプロパティ — ノードレベルの amount、lifetime、explosiveness、local_coords、可視 AABB、preprocess、および restart／finished のライフサイクルを説明します。
• パーティクルサブエミッター — インパクト／破片システムの連鎖と、パーティクルシステムを自身のサブエミッターとして再帰的に使えない理由を説明します。
• パーティクルの衝突 — GPUParticlesCollision* の形状、rigid／hide モード、GPU 衝突と CPU 同期 SFX の制限を説明します。
• パーティクルアトラクター — アトラクターの種類に加え、グローバルな天候がすべてのアトラクターのコストを負担しないようにする cull_mask／レイヤー分離を説明します。
• パーティクルトレイル — トレイルリボンと、煙／炎のトレイルでグローバル空間（local_coords = false）を使う必要がある理由を説明します。
• パーティクルシェーダー — shader_type particles、CUSTOM／USERDATA、COLLIDED／emit_subparticle()、keep_data のプロセスループを説明します。
• MultiMesh の使用 — 数百万のエンティティを MultiMesh と補間バッファーで描画し、GPUParticles を介さない方がよい場合について説明します。
• 可視性範囲 — GeometryInstance3D の距離フェード／ヒステリシスによって、遠方の環境パーティクル処理を停止する方法を説明します。

関連スキル

前提条件

• godot-project-foundations — VFX Prefab と GradientTexture1D マテリアルをパッキングする前に、シーン、リソース、インポートの基本を学びます。
• godot-gdscript-mastery — 型付き GPUParticles API、finished ハンドラー、プールやバーストスポーナーで使う安全な restart()／await パターンを学びます。
• godot-shaders-basics — shader_type particles のプロセスロジックに必要な ShaderMaterial のワークフローとシェーディング言語の基礎を学びます。

補完

• godot-3d-materials — GPUParticles3D が生成したクアッド/メッシュを描画するマテリアル、透明ソート、next_pass スタック。
• godot-3d-lighting — 発光する炎/火花と環境露出の対比。VFX でシーンを照らす必要がある場合は、パーティクルのアルベドを実際のライトと組み合わせます。
• godot-audio-systems — パーティクル単位の衝突オーディオが利用できない場合に、GPU エミッターがアクティブな間の衝撃音/ループ SFX。
• godot-performance-optimization — VFX が GPU 時間を支配する場合の amount 予算、可視性 AABB、アトラクタマスク、MultiMesh への切り替え。
• godot-camera-systems — カメラ追従のハイトフィールド、可視範囲のしきい値、フラスタムを考慮した天候エミッター。
• godot-signal-architecture — 幽霊コールバックを漏らしてはならないプール型リサイクラー向けの finished とワンショット接続の衛生管理。
• godot-2d-physics — CPUParticles2D + 補間がカクつく GPUParticles2D を置き換える、物理に親子付けされた 2D トレイル。

ダウンストリーム / コンシューマー

• godot-combat-system — ダメージ解決から生成されるヒットスパーク、血/破片のバースト、マズル FX。
• godot-ability-system — アビリティのライフサイクルとターゲティングフィードバックに紐づくキャスト/チャネル/インパクト VFX。
• godot-genre-shooter — これらのパーティクルパターン上に構築されたマズルフラッシュ、トレーサー、爆発、環境スモークスタック。
• godot-monte-carlo-balancer — VFX の密度/可読性が体感難易度やテレグラフの明瞭さを変える場合に、ジュース予算を戦闘結果とともにシミュレートします。

マスター

• godot-master — スキル横断的な発見のためのライブラリルーターおよびミラーリングされたモジュールエントリ。