particles-vfx

Godot 4.3+ のパーティクルシステム

すべての例は、非推奨 API を使用せず Godot 4.3+ を対象としています。まず GDScript を示し、次に C# を示します。

関連スキル： カスタムパーティクルシェーダーについては shader-basics、パーティクルに影響するライティングと環境については 3d-essentials、2D レンダリングのコンテキストについては 2d-essentials、コードで駆動する VFX のタイミングについては tween-animation、パーティクルのパフォーマンス調整については godot-optimization を参照してください。

---

1. 基本概念

GPU パーティクルと CPU パーティクル

ノード	処理方式	機能	用途
GPUParticles2D	GPU	フル機能、高いパーティクル数、トレイル	ほとんどの 2D エフェクト
GPUParticles3D	GPU	フル機能、アトラクター、衝突	ほとんどの 3D エフェクト
CPUParticles2D	CPU	シンプル、トレイル／アトラクターなし	低性能デバイス、少数のパーティクル
CPUParticles3D	CPU	シンプル、トレイル／アトラクターなし	低性能デバイス、少数のパーティクル

目安： デフォルトでは GPU パーティクルを使用してください。CPU パーティクルに切り替えるのは、低性能デバイスやウェブ向けのターゲットに限ります。どちらのノードも、スクリプトからパーティクルごとの位置を取得できないため、パーティクルの位置にオブジェクトを生成するには、独自のシミュレーションが必要です。

エディターで GPU パーティクルと CPU パーティクルを相互に変換できます。ノードを選択 → ツールバー → Convert to CPUParticles2D/3D（またはその逆）。

パーティクルシステムのアーキテクチャ

GPUParticles2D/3D
├── Process Material (ParticleProcessMaterial)   ← physics, emission, color
├── Draw Pass 1 (Mesh)                            ← what each particle looks like
└── (Optional) Draw Pass 2-4                      ← additional meshes

最小限のセットアップ

1. GPUParticles2D（または 3D）ノードを追加します
2. インスペクター → Process Material → New ParticleProcessMaterial を選択します
3. Amount（パーティクル数）を設定します
4. 放出、方向、速度、重力を設定します
5. （2D）パーティクルの外観を指定する Texture を設定します
6. （3D）メッシュとして Draw Pass 1 を設定します（ビルボードには QuadMesh、またはカスタムメッシュを使用します）

---

2. 主要なノードプロパティ

GPUParticles2D/3D のプロパティ

プロパティ	型	説明
emitting	bool	放出を開始／停止します
amount	int	同時に存在するパーティクルの合計数
lifetime	float	各パーティクルの寿命（秒）
one_shot	bool	1 回だけ放出して停止します
preprocess	float	最初のフレームより前にシミュレーションする秒数
speed_scale	float	パーティクル物理の時間倍率
explosiveness	float	0.0 = 寿命にわたって分散、1.0 = 一斉に放出
fixed_fps	int	パーティクルの更新レートを固定します（0 = レンダリング FPS に合わせる）
local_coords	bool	パーティクルがノードとともに移動する（true）か、ワールド内にとどまる（false）か
draw_order	enum	Index、Lifetime、または Reverse Lifetime
amount_ratio	float	放出するパーティクルの割合（0.0–1.0）

ワンショットと連続放出

# Continuous emitter (fire, smoke, ambient dust)
$GPUParticles2D.one_shot = false
$GPUParticles2D.emitting = true

# One-shot burst (explosion, impact splash)
$GPUParticles2D.one_shot = true
$GPUParticles2D.emitting = false  # arm it
# Later, trigger:
$GPUParticles2D.restart()
$GPUParticles2D.emitting = true

// Continuous
var particles = GetNode<GpuParticles2D>("GPUParticles2D");
particles.OneShot = false;
particles.Emitting = true;

// One-shot burst
particles.OneShot = true;
particles.Emitting = false;
// Trigger:
particles.Restart();
particles.Emitting = true;

ローカルビルボードのアライメント（Godot 4.7+）

GPUParticles3D に TRANSFORM_ALIGN_LOCAL_BILLBOARD（= 4）が追加されます。各パーティクルの Z 軸をカメラに向けながら、指定した軸（X または Y。transform_align_axis で選択）を維持します。ビルボードパーティクルでは、transform_align_channel_filter によって、角度の計算に使用するカスタムチャンネルを選択します。ParticleProcessMaterial では、軸ごとの回転速度を組み合わせて使用できます。use_rotation_velocity_3d を有効にし、rotation_velocity_3d_min/max（Vector3、パーティクルのローカル軸上の値）を設定します。また、必要に応じて rotation_velocity_3d_curve（寿命にわたる軸ごとのカーブ）を設定します。

# 3D only — billboard toward the camera while keeping the Y axis fixed.
# Assumes a ParticleProcessMaterial is assigned (section 1 setup).
$GPUParticles3D.transform_align = GPUParticles3D.TRANSFORM_ALIGN_LOCAL_BILLBOARD
$GPUParticles3D.transform_align_axis = RenderingServer.PARTICLES_ALIGN_AXIS_Y

var mat: ParticleProcessMaterial = $GPUParticles3D.process_material
mat.use_rotation_velocity_3d = true
mat.rotation_velocity_3d_min = Vector3(-2.0, 0.0, 0.0)
mat.rotation_velocity_3d_max = Vector3(2.0, 0.0, 0.0)

// Assumes a ParticleProcessMaterial is assigned (section 1 setup).
var particles = GetNode<GpuParticles3D>("GPUParticles3D");
particles.TransformAlign = GpuParticles3D.TransformAlignEnum.LocalBillboard;
particles.TransformAlignAxis = RenderingServer.ParticlesTransformAlignAxis.Y;

var mat = (ParticleProcessMaterial)particles.ProcessMaterial;
mat.UseRotationVelocity3D = true;
mat.RotationVelocity3DMin = new Vector3(-2.0f, 0.0f, 0.0f);
mat.RotationVelocity3DMax = new Vector3(2.0f, 0.0f, 0.0f);

---

3. ParticleProcessMaterial — 基本的なプロパティ

マテリアルは、パーティクルごとの動作を制御します。放出形状（Point / Sphere / Box / Ring / Points / Directed Points）、方向＋拡散＋初期速度、重力、寿命に応じたスケールと色（scale_curve / color_ramp を使用）、減衰、半径方向／接線方向の加速度、角速度を設定できます。

各プロパティグループの放出形状テーブルと GDScript ＋ C# のスニペットについては、references/process-material-basics.md を参照してください。

軸ごとの 3D スケールと回転（Godot 4.7+）

均一に設定する代わりに、軸ごとにスケールと初期向きをランダム化できます。use_scale_3d を有効にすると scale_3d_min/max（パーティクルごとのランダムな Vector3 スケール）が使えるようになります。use_rotation_3d を有効にすると rotation_3d_min/max（Vector3、度単位）が使えるようになります。後者は 3D でのみ機能します。

mat.use_scale_3d = true
mat.scale_3d_min = Vector3(0.5, 1.0, 0.5)
mat.scale_3d_max = Vector3(1.0, 2.0, 1.0)

mat.use_rotation_3d = true  # 3D only
mat.rotation_3d_min = Vector3(0.0, -180.0, 0.0)  # degrees
mat.rotation_3d_max = Vector3(0.0, 180.0, 0.0)

mat.UseScale3D = true;
mat.Scale3DMin = new Vector3(0.5f, 1.0f, 0.5f);
mat.Scale3DMax = new Vector3(1.0f, 2.0f, 1.0f);

mat.UseRotation3D = true;  // 3D only
mat.Rotation3DMin = new Vector3(0.0f, -180.0f, 0.0f);  // degrees
mat.Rotation3DMax = new Vector3(0.0f, 180.0f, 0.0f);

エミッターのスケールを継承する（Godot 4.7+）

particle_flag_inherit_emitter_scale（デフォルトは false）：true の場合、パーティクルはエミッターノードのスケールを継承します。local_coords が true の場合、ローカル空間のパーティクルはすでにエミッターのスケールの影響を受けているため、効果はありません。

mat.particle_flag_inherit_emitter_scale = true

mat.ParticleFlagInheritEmitterScale = true;

---

4. よく使われる VFX のレシピ

多くのプロジェクトで必要となるレシピです。炎（2D、ループ放出、暖色系のカラーグラデーション＋縮小）、爆発バースト（ワンショット、高い発生数、短い寿命）、ほこり／足元の煙（ワンショット、拡大＋素早いフェード）を紹介します。

3 つすべてのレシピで、そのまま使える GDScript の設定方法と推奨される ParticleProcessMaterial の設定については、references/vfx-recipes.md を参照してください。

---

5. トレイル（Forward+ と Mobile のみ）

GPUParticles2D/3D で trail_enabled = true に設定し、Mesh（RibbonTrailMesh または TubeTrailMesh）を割り当てます。トレイルは Compatibility レンダラーではサポートされていません。

設定方法とトレイルメッシュタイプの比較については、references/trails.md を参照してください。

---

6. サブエミッター

パーティクルは、一定間隔、衝突時、消滅時、または（Godot 4.4+ では）生成時に、別のパーティクルシステムからパーティクルを放出させることができます。親パーティクルノードの ParticleProcessMaterial.sub_emitter_mode と sub_emitter プロパティで設定します。

トリガーモード、シーンの設定方法、GDScript と C#（v1.6.0 と同等の機能）、制限事項については、references/subemitters.md を参照してください。

注： sub_emitter_keep_velocity = true（デフォルトは false）にすると、サブエミッターから放出されたパーティクルは、生成時に親パーティクルの速度を継承します。これは 4.7 でも変更されていません。継承が機能しなくなる 4.7 開発ビルドのリグレッションは、4.7 の安定版リリース前に修正されたため（GH-118062）、4.6 から移行する必要はありません。

---

7. アトラクターと衝突（3D）

GPUParticlesAttractor*3D（Box / Sphere / Vector Field）は、パーティクルを領域に引き寄せます。GPUParticlesCollision*3D（Box / Sphere / SDF / HeightField）を使うと、パーティクルをジオメトリに衝突させられます。Compatibility では、ボックス／球体アトラクターと、ボックス／球体／高さフィールドコライダーが動作します。ベクトルフィールドアトラクターと SDF コライダーには、Forward+ または Mobile が必要です。2D にはアトラクターノードはありませんが、collision_mode が設定されている場合、GPUParticles2D は LightOccluder2D ノードと衝突します。

各アトラクターと衝突タイプの詳しい設定方法については、references/attractors-and-collision.md を参照してください。

---

8. 乱流

ParticleProcessMaterial で turbulence_enabled = true に設定し、turbulence_noise_strength（一般的には 0.5～2.0）、turbulence_noise_scale（値を大きくすると、より大きく滑らかな渦になります）、turbulence_noise_speed（ノイズフィールドをアニメーションさせます）を調整します。煙、炎、ほこりに「生き生きとした」動きを加える、低コストのエフェクトです。

---

9. フリップブックアニメーション（2D）

ParticleProcessMaterial.AnimSpeedMin/Max と、シートレイアウト用の CanvasItemMaterial.ParticlesAnimHFrames/VFrames を使って、スプライトシートでパーティクルをアニメーションさせます。パーティクルは寿命の間にフレームを順番に再生します。

GDScript ＋ C#（v1.6.0 と同等の機能）を使った詳しい設定方法については、references/flipbook-animation.md を参照してください。

---

10. パフォーマンスとよくある落とし穴

最も効果が大きいのは、基本的な対策です。見た目に問題がない範囲で amount を最小限に抑え、環境効果では fixed_fps をデフォルトの 30 に設定します（0 にすると毎フレーム更新されます）。2D パーティクルでは必ず visibility_rect を設定し、品質スライダーとして amount_ratio を公開します。Godot 4.7 以降では、一時停止中のタイムラインをシークする request_particles_process() が追加されています。

「パーティクルが壊れている」という報告の多くは、既知の 11 個の原因のいずれかです。表示されない（テクスチャがない、または描画パスのメッシュがない）、消えてしまう（lifetime が短すぎる）、ワンショットが再発射されない（最後のバーストのパーティクルが終わるまで emitting = true は無視される。restart() を使うとすぐに再発射される）、方向が間違っている（2D では Y 軸が反転している）、またはベースの color が暗く、color_ramp に乗算されてしまう、などです。

パフォーマンスの完全な表、4.7 以降のタイムラインシーク API、動的な品質スケーリング（GDScript + C#）、症状／原因／対処法の完全な表については、references/performance-and-pitfalls.md を参照してください。

---

11. 実装チェックリスト

• パーティクルの amount を、視覚効果に必要な最小値に設定する
• lifetime を視覚的な持続時間に合わせる。短すぎたり長すぎたりしないようにする
• バースト効果（爆発、衝撃）では one_shot を有効にする
• 常に表示する環境効果（炎、煙、ほこり）では preprocess を設定する
• 放出形状を発生源の形状に合わせる（爆発には球、範囲効果にはボックス）
• パーティクルが突然消えないよう、color_ramp の最後でアルファ値を 0 にする
• 自然にフェードするよう、scale_curve でパーティクルを時間経過とともに縮小する
• local_coords を正しく設定する。アタッチする効果には true、ワールド座標には false
• lifetime に余裕を加えた時間が経過した後、ワンショットのパーティクルを queue_free で解放する
• パーティクルが早期にカリングされないよう、visibility_rect（2D）を設定する
• 動的な品質スケーリングでは、プレイヤーが設定できる品質項目に amount_ratio を使用する
• パフォーマンス負荷の高い機能（乱流、トレイル）は、低性能のターゲットでは無効にする