GPUParticles2D/3D in Godot 4 — Complete Guide Godot 4のGPUParticles2D/3D 完全ガイド

1. Introduction1. はじめに

Godot 4 uses GPUParticles2D and GPUParticles3D as the default particle system nodes. These run entirely on the GPU, making them significantly faster than their CPU counterparts for large particle counts. The old ParticlesMaterial from Godot 3 has been replaced by ParticleProcessMaterial, which offers more control over particle behavior.

Godot 4ではGPUParticles2DとGPUParticles3Dがデフォルトのパーティクルシステムノードです。GPU上で完全に実行されるため、大量のパーティクルでもCPU版より大幅に高速です。Godot 3のParticlesMaterialはParticleProcessMaterialに置き換えられ、パーティクルの動作をより細かく制御できるようになりました。

CPUParticles2D and CPUParticles3D still exist as fallback nodes for devices that lack GPU compute support or when you need to access individual particle data from GDScript. For most use cases, GPU particles are the recommended choice.

CPUParticles2DとCPUParticles3Dは、GPUコンピュートをサポートしないデバイス向け、またはGDScriptから個々のパーティクルデータにアクセスする必要がある場合のフォールバックとして引き続き利用可能です。ほとんどのケースではGPUパーティクルが推奨されます。

2. GPUParticles2D vs CPUParticles2D2. GPUParticles2D vs CPUParticles2D

3. Basic Setup3. 基本セットアップ

To create a basic particle effect, add a GPUParticles2D node to your scene and assign a ParticleProcessMaterial to it. Here is a minimal setup in GDScript:

基本的なパーティクルエフェクトを作成するには、シーンにGPUParticles2Dノードを追加し、ParticleProcessMaterialを割り当てます。GDScriptでの最小構成は以下の通りです：

# Create a GPUParticles2D node via code
var particles = GPUParticles2D.new()
particles.amount = 50
particles.lifetime = 2.0
particles.explosiveness = 0.0  # 0 = continuous, 1 = all at once
particles.randomness = 0.5

# Create and assign the material
var mat = ParticleProcessMaterial.new()
mat.direction = Vector3(0, -1, 0)  # Note: uses Vector3 even in 2D
mat.initial_velocity_min = 50.0
mat.initial_velocity_max = 100.0
mat.gravity = Vector3(0, 98, 0)

particles.process_material = mat
add_child(particles)

Key properties on the GPUParticles2D node itself:

GPUParticles2Dノードの主要プロパティ：

• amount — Number of particles alive at any time (default: 8)同時に存在するパーティクル数（デフォルト: 8）
• lifetime — How long each particle lives in seconds (default: 1.0)各パーティクルの生存時間（秒）（デフォルト: 1.0）
• one_shot — Emit once then stop (default: false)一度だけ放出して停止（デフォルト: false）
• explosiveness — 0.0 = continuous stream, 1.0 = all particles at once0.0 = 連続放出、1.0 = 全パーティクルを一度に放出
• randomness — Random offset to emission timing (0.0-1.0)放出タイミングのランダムオフセット（0.0-1.0）
• speed_scale — Multiplier for simulation speedシミュレーション速度の倍率
• emitting — Whether the system is currently emitting現在放出中かどうか

4. ParticleProcessMaterial Deep Dive4. ParticleProcessMaterial 詳解

ParticleProcessMaterial controls how individual particles behave over their lifetime. All directional properties use Vector3, even for 2D particles (the Z component is simply ignored).

ParticleProcessMaterialは個々のパーティクルのライフタイム中の動作を制御します。2Dパーティクルでも方向プロパティはすべてVector3を使用します（Z成分は単に無視されます）。

Direction & Velocity方向と速度

var mat = ParticleProcessMaterial.new()

# Direction: normalized vector for initial particle heading
mat.direction = Vector3(0, -1, 0)  # Upward in 2D (Y is flipped)

# Spread: cone angle in degrees (0 = straight line, 180 = hemisphere)
mat.spread = 45.0

# Initial velocity: particles spawn with speed in this range
mat.initial_velocity_min = 100.0
mat.initial_velocity_max = 200.0

# Gravity: constant acceleration applied every frame
mat.gravity = Vector3(0, 98, 0)  # Pulls downward in 2D

Angular Velocity角速度

Spin particles as they move. Useful for debris, confetti, or leaves.

パーティクルを移動中に回転させます。破片、紙吹雪、落ち葉などに便利です。

mat.angular_velocity_min = -180.0  # degrees per second
mat.angular_velocity_max = 180.0

Scale Over Lifetimeライフタイム中のスケール変化

Use a CurveTexture to change particle size over their lifetime:

CurveTextureを使ってパーティクルサイズをライフタイム中に変化させます：

var curve = Curve.new()
curve.add_point(Vector2(0.0, 1.0))  # Full size at birth
curve.add_point(Vector2(0.5, 1.2))  # Slightly larger at midlife
curve.add_point(Vector2(1.0, 0.0))  # Shrink to nothing at death

var curve_tex = CurveTexture.new()
curve_tex.curve = curve
mat.scale_curve = curve_tex

Damping & Attractor減衰とアトラクター

Damping slows particles over time, simulating air resistance. Attractors (separate nodes) pull particles toward a point.

ダンピングはパーティクルを時間とともに減速させ、空気抵抗をシミュレートします。アトラクター（別ノード）はパーティクルをポイントに引き寄せます。

mat.damping_min = 5.0
mat.damping_max = 10.0

5. Color Gradients5. カラーグラデーション

The color_ramp property on ParticleProcessMaterial accepts a GradientTexture1D to smoothly change particle color over their lifetime. This is essential for realistic fire, smoke, and magic effects.

ParticleProcessMaterialのcolor_rampプロパティはGradientTexture1Dを受け取り、パーティクルの色をライフタイム中に滑らかに変化させます。リアルな炎、煙、魔法エフェクトに不可欠です。

Fire Gradient Example炎のグラデーション例

var gradient = Gradient.new()
gradient.colors = PackedColorArray([
    Color(1.0, 1.0, 1.0, 1.0),    # White (hot core)
    Color(1.0, 1.0, 0.2, 1.0),    # Yellow
    Color(1.0, 0.5, 0.0, 1.0),    # Orange
    Color(0.8, 0.1, 0.0, 0.8),    # Red
    Color(0.2, 0.0, 0.0, 0.0),    # Dark red, transparent (fade out)
])
gradient.offsets = PackedFloat32Array([0.0, 0.15, 0.4, 0.7, 1.0])

var grad_tex = GradientTexture1D.new()
grad_tex.gradient = gradient
mat.color_ramp = grad_tex

You can also set a flat color property instead of a gradient for uniform-colored particles:

均一な色のパーティクルにはグラデーションの代わりにフラットなcolorプロパティも設定できます：

mat.color = Color(0.2, 0.6, 1.0, 0.8)  # Semi-transparent blue

6. Emission Shapes6. エミッション形状

The emission shape determines where particles spawn. Set via emission_shape on ParticleProcessMaterial.

エミッション形状はパーティクルの出現位置を決定します。ParticleProcessMaterialのemission_shapeで設定します。

Point

All particles spawn at the node's origin. Default shape.

全パーティクルがノードの原点から出現します。デフォルトの形状です。

mat.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_POINT

Sphere / Sphere Surface

Particles spawn randomly within a sphere (or only on its surface).

パーティクルが球体内（またはその表面上のみ）にランダムに出現します。

mat.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_SPHERE
mat.emission_sphere_radius = 50.0

# Surface only:
mat.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_SPHERE_SURFACE
mat.emission_sphere_radius = 50.0

Box

Particles spawn randomly within a rectangular volume.

パーティクルが矩形ボリューム内にランダムに出現します。

mat.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_BOX
mat.emission_box_extents = Vector3(100, 10, 0)  # Wide and thin

Ring

Particles spawn on a ring (donut) shape, defined by inner/outer radius and height.

パーティクルがリング（ドーナツ）形状に出現します。内径/外径/高さで定義されます。

mat.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_RING
mat.emission_ring_radius = 80.0       # Outer radius
mat.emission_ring_inner_radius = 60.0 # Inner radius (hole)
mat.emission_ring_height = 0.0        # Flat ring
mat.emission_ring_axis = Vector3(0, 0, 1)  # Ring normal

7. Practical Recipes7. 実践レシピ

Fire炎

Orange-red gradient, upward velocity, slight spread, scale decreasing over lifetime.

オレンジ～赤のグラデーション、上方向の速度、わずかな広がり、ライフタイム中にスケール縮小。

func create_fire() -> GPUParticles2D:
    var p = GPUParticles2D.new()
    p.amount = 40
    p.lifetime = 0.8
    p.randomness = 0.3

    var mat = ParticleProcessMaterial.new()
    mat.direction = Vector3(0, -1, 0)
    mat.spread = 15.0
    mat.initial_velocity_min = 40.0
    mat.initial_velocity_max = 80.0
    mat.gravity = Vector3(0, -20, 0)  # Slight upward pull
    mat.damping_min = 5.0
    mat.damping_max = 10.0

    # Color ramp: white -> yellow -> orange -> red -> transparent
    var grad = Gradient.new()
    grad.colors = PackedColorArray([
        Color(1, 1, 1, 1), Color(1, 1, 0.2, 1),
        Color(1, 0.4, 0, 0.9), Color(0.6, 0.1, 0, 0.4),
        Color(0.2, 0, 0, 0)
    ])
    grad.offsets = PackedFloat32Array([0.0, 0.1, 0.35, 0.7, 1.0])
    var grad_tex = GradientTexture1D.new()
    grad_tex.gradient = grad
    mat.color_ramp = grad_tex

    # Scale: shrink over time
    var curve = Curve.new()
    curve.add_point(Vector2(0, 0.8))
    curve.add_point(Vector2(0.3, 1.0))
    curve.add_point(Vector2(1, 0.0))
    var curve_tex = CurveTexture.new()
    curve_tex.curve = curve
    mat.scale_curve = curve_tex

    p.process_material = mat
    return p

Smoke煙

Gray gradient, slow upward movement, large spread, low alpha for wispy look.

灰色のグラデーション、ゆっくりとした上昇、大きな広がり、低アルファで薄い見た目。

func create_smoke() -> GPUParticles2D:
    var p = GPUParticles2D.new()
    p.amount = 25
    p.lifetime = 3.0
    p.randomness = 0.5

    var mat = ParticleProcessMaterial.new()
    mat.direction = Vector3(0, -1, 0)
    mat.spread = 35.0
    mat.initial_velocity_min = 10.0
    mat.initial_velocity_max = 30.0
    mat.gravity = Vector3(0, -5, 0)
    mat.damping_min = 2.0
    mat.damping_max = 5.0
    mat.angular_velocity_min = -30.0
    mat.angular_velocity_max = 30.0

    var grad = Gradient.new()
    grad.colors = PackedColorArray([
        Color(0.6, 0.6, 0.6, 0.0), Color(0.5, 0.5, 0.5, 0.3),
        Color(0.4, 0.4, 0.4, 0.2), Color(0.3, 0.3, 0.3, 0.0)
    ])
    grad.offsets = PackedFloat32Array([0.0, 0.15, 0.6, 1.0])
    var grad_tex = GradientTexture1D.new()
    grad_tex.gradient = grad
    mat.color_ramp = grad_tex

    # Scale: grow over time (smoke expands)
    var curve = Curve.new()
    curve.add_point(Vector2(0, 0.3))
    curve.add_point(Vector2(0.5, 1.0))
    curve.add_point(Vector2(1, 1.5))
    var curve_tex = CurveTexture.new()
    curve_tex.curve = curve
    mat.scale_curve = curve_tex

    p.process_material = mat
    return p

Rain雨

Blue-white streaks, strong downward gravity, narrow spread, high particle count.

青白い線、強い下向きの重力、狭い広がり、大量のパーティクル。

func create_rain() -> GPUParticles2D:
    var p = GPUParticles2D.new()
    p.amount = 200
    p.lifetime = 1.0

    # Use a box emission to cover the screen width
    var mat = ParticleProcessMaterial.new()
    mat.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_BOX
    mat.emission_box_extents = Vector3(600, 0, 0)
    mat.direction = Vector3(0.05, 1, 0)  # Slightly angled
    mat.spread = 3.0
    mat.initial_velocity_min = 400.0
    mat.initial_velocity_max = 500.0
    mat.gravity = Vector3(0, 200, 0)

    var grad = Gradient.new()
    grad.colors = PackedColorArray([
        Color(0.7, 0.8, 1.0, 0.6), Color(0.7, 0.85, 1.0, 0.4),
        Color(0.7, 0.85, 1.0, 0.0)
    ])
    grad.offsets = PackedFloat32Array([0.0, 0.8, 1.0])
    var grad_tex = GradientTexture1D.new()
    grad_tex.gradient = grad
    mat.color_ramp = grad_tex

    # Stretch particles to look like streaks
    mat.scale_min = 0.5
    mat.scale_max = 0.5

    p.process_material = mat
    return p

Sparks火花

Yellow-orange, explosive burst, high initial velocity, short lifetime.

黄色～オレンジ、爆発的な放出、高い初速度、短いライフタイム。

func create_sparks() -> GPUParticles2D:
    var p = GPUParticles2D.new()
    p.amount = 30
    p.lifetime = 0.5
    p.one_shot = true
    p.explosiveness = 1.0  # All at once

    var mat = ParticleProcessMaterial.new()
    mat.direction = Vector3(0, -1, 0)
    mat.spread = 180.0  # Full sphere
    mat.initial_velocity_min = 150.0
    mat.initial_velocity_max = 300.0
    mat.gravity = Vector3(0, 200, 0)  # Fall quickly
    mat.damping_min = 10.0
    mat.damping_max = 20.0

    var grad = Gradient.new()
    grad.colors = PackedColorArray([
        Color(1, 1, 0.8, 1), Color(1, 0.7, 0.1, 1),
        Color(1, 0.3, 0, 0.5), Color(0.5, 0.1, 0, 0)
    ])
    grad.offsets = PackedFloat32Array([0.0, 0.2, 0.6, 1.0])
    var grad_tex = GradientTexture1D.new()
    grad_tex.gradient = grad
    mat.color_ramp = grad_tex

    # Scale: start small, stay small
    mat.scale_min = 0.3
    mat.scale_max = 0.6

    p.process_material = mat
    return p

Snow雪

White particles, slow gentle descent, wide spread, slight horizontal drift.

白いパーティクル、ゆっくりとした穏やかな降下、広い範囲、わずかな水平方向のドリフト。

func create_snow() -> GPUParticles2D:
    var p = GPUParticles2D.new()
    p.amount = 100
    p.lifetime = 5.0
    p.randomness = 0.8

    var mat = ParticleProcessMaterial.new()
    mat.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_BOX
    mat.emission_box_extents = Vector3(500, 0, 0)
    mat.direction = Vector3(0.1, 1, 0)
    mat.spread = 10.0
    mat.initial_velocity_min = 20.0
    mat.initial_velocity_max = 40.0
    mat.gravity = Vector3(0, 10, 0)
    mat.damping_min = 1.0
    mat.damping_max = 3.0
    mat.angular_velocity_min = -45.0
    mat.angular_velocity_max = 45.0

    var grad = Gradient.new()
    grad.colors = PackedColorArray([
        Color(1, 1, 1, 0), Color(1, 1, 1, 0.8),
        Color(1, 1, 1, 0.7), Color(1, 1, 1, 0)
    ])
    grad.offsets = PackedFloat32Array([0.0, 0.05, 0.8, 1.0])
    var grad_tex = GradientTexture1D.new()
    grad_tex.gradient = grad
    mat.color_ramp = grad_tex

    mat.scale_min = 0.3
    mat.scale_max = 0.8

    p.process_material = mat
    return p

8. 3D Particles (GPUParticles3D)8. 3Dパーティクル (GPUParticles3D)

GPUParticles3D works identically to GPUParticles2D but operates in 3D space. The same ParticleProcessMaterial is used. Key differences:

GPUParticles3DはGPUParticles2Dと同じ仕組みですが、3D空間で動作します。同じParticleProcessMaterialを使用します。主な違い：

• All 3 axes of Vector3 are active (X, Y, Z)Vector3の3軸すべてが有効（X, Y, Z）
• Emission shapes work in full 3D (spheres are actual spheres, boxes are volumes)エミッション形状が完全な3Dで動作（球は本物の球体、ボックスはボリューム）
• You can use draw_pass_1 with a QuadMesh or custom mesh for billboard particlesdraw_pass_1にQuadMeshやカスタムメッシュを使ってビルボードパーティクルを作成可能
• Mesh particles can use StandardMaterial3D or ORMMaterial3DメッシュパーティクルにはStandardMaterial3DやORMMaterial3Dを使用可能

# 3D fire torch example
var particles_3d = GPUParticles3D.new()
particles_3d.amount = 60
particles_3d.lifetime = 1.0

var mat = ParticleProcessMaterial.new()
mat.direction = Vector3(0, 1, 0)  # Upward in 3D
mat.spread = 20.0
mat.initial_velocity_min = 1.0
mat.initial_velocity_max = 2.0
mat.gravity = Vector3(0, -0.5, 0)  # Slight counter-gravity

# Emission from a small sphere
mat.emission_shape = ParticleProcessMaterial.EMISSION_SHAPE_SPHERE
mat.emission_sphere_radius = 0.2

particles_3d.process_material = mat

# Use a QuadMesh as the particle shape
var quad = QuadMesh.new()
quad.size = Vector2(0.3, 0.3)
particles_3d.draw_pass_1 = quad

# Billboard mode: particles always face the camera
mat.billboard_mode = BaseMaterial3D.BILLBOARD_ENABLED

add_child(particles_3d)

9. Sub-Emitters9. サブエミッター

Godot 4 supports sub-emitters for particle-on-particle effects. A sub-emitter is another GPUParticles2D/GPUParticles3D node that emits particles at the position of each parent particle. This is ideal for:

Godot 4はパーティクルからパーティクルを生成するサブエミッターに対応しています。サブエミッターは、親パーティクルの位置で新たなパーティクルを放出する別のGPUParticles2D/GPUParticles3Dノードです。以下に最適です：

• Sparks flying off fire particles炎パーティクルから飛び散る火花
• Smoke trails behind firework bursts花火の爆発後の煙の軌跡
• Splash droplets on collision衝突時の飛沫
• Secondary explosions二次爆発

To set up sub-emitters:

サブエミッターのセットアップ方法：

# 1. Create the sub-emitter node (must be a sibling or child)
var sub_sparks = GPUParticles2D.new()
sub_sparks.amount = 4
sub_sparks.lifetime = 0.3
sub_sparks.explosiveness = 1.0
sub_sparks.emitting = false  # Controlled by parent
var sub_mat = ParticleProcessMaterial.new()
sub_mat.direction = Vector3(0, -1, 0)
sub_mat.spread = 180.0
sub_mat.initial_velocity_min = 50.0
sub_mat.initial_velocity_max = 100.0
sub_sparks.process_material = sub_mat
add_child(sub_sparks)

# 2. Reference it from the parent material
var parent_mat: ParticleProcessMaterial = fire_particles.process_material
parent_mat.sub_emitter_mode = ParticleProcessMaterial.SUB_EMITTER_AT_END
# Also: SUB_EMITTER_AT_COLLISION, SUB_EMITTER_CONSTANT

# 3. Set the sub_emitter property on the parent node
fire_particles.sub_emitter = fire_particles.get_path_to(sub_sparks)

Sub-emitter modes:

サブエミッターモード：

• SUB_EMITTER_CONSTANT — Continuously emit from each parent particle各親パーティクルから連続的に放出
• SUB_EMITTER_AT_END — Emit when the parent particle dies親パーティクルが消滅する時に放出
• SUB_EMITTER_AT_COLLISION — Emit when the parent particle collides親パーティクルが衝突した時に放出

10. Performance Tips10. パフォーマンスのコツ

• Amount vs Lifetime tradeoff:数量 vs ライフタイムのトレードオフ： Total visible particles = amount. If you increase lifetime, particles accumulate longer. Reduce amount to compensate, or increase it for denser effects. 同時表示パーティクル数 = amount。lifetimeを増やすとパーティクルが長く残ります。補正のためamountを減らすか、より密度の高いエフェクトにするため増やしてください。
• Use Visibility Range (3D):Visibility Range（3D）を使う： Set visibility_range_end on GPUParticles3D so distant particle systems stop rendering. This is a big win for open worlds. GPUParticles3Dにvisibility_range_endを設定すると、遠くのパーティクルシステムがレンダリングされなくなります。オープンワールドでは大きな効果があります。
• Fixed FPS:固定FPS： Set fixed_fps on the particle node (e.g., 30) to limit simulation updates. Particles will still interpolate smoothly but use less GPU time. パーティクルノードにfixed_fpsを設定（例: 30）するとシミュレーション更新が制限されます。パーティクルは滑らかに補間されますがGPU使用量は減ります。
• One-shot for bursts:バースト用のOne-shot： For explosion-like effects, use one_shot = true with explosiveness = 1.0. The node can then be freed after the lifetime ends. 爆発エフェクトにはone_shot = trueとexplosiveness = 1.0を使用します。ライフタイム終了後にノードを解放できます。
• Use LOD for 3D:3DでのLOD活用： Combine visibility_range_begin/end with multiple particle nodes at different detail levels for Level of Detail (LOD) particle effects. visibility_range_begin/endを複数の異なる詳細レベルのパーティクルノードと組み合わせて、LOD（Level of Detail）パーティクルエフェクトを実現できます。
• Avoid overdraw:オーバードローを避ける： Many semi-transparent particles overlapping = expensive fill rate. Reduce amount and use larger particles with lower alpha instead. 半透明パーティクルが大量に重なる = フィルレートのコスト増大。amountを減らし、低アルファの大きなパーティクルを使いましょう。

11. Godot 3 to 4 Migration11. Godot 3から4への移行

If you are migrating a project from Godot 3 to Godot 4, here are the key changes for particles:

Godot 3からGodot 4にプロジェクトを移行する場合、パーティクルの主な変更点は以下の通りです：