Index of every page on this site: llms.txt
All skills
jame581 avatar

/particles-vfx

@426e8ab
by Jan Mesarčjame581/godotprompter979 stars
63
Run it yourself

Use when implementing particle effects — GPUParticles2D/3D, ParticleProcessMaterial, emission shapes, subemitters, trails, attractors, collision, and common VFX recipes

Use this Skill: https://skilld.dev/gh/jame581/godotprompter/particles-vfx

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈46 tokens for metadata: the name and description. ≈3.2k when used: this file. ≈5.9k more on demand in 7 files.

Description uses 2.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈184 characters, or 2.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Particle Systems in Godot 4.3+

All examples target Godot 4.3+ with no deprecated APIs. GDScript is shown first, then C#.

Related skills: shader-basics for custom particle shaders, 3d-essentials for lighting and environment that affect particles, 2d-essentials for 2D rendering context, tween-animation for code-driven VFX timing, godot-optimization for particle performance tuning.


1. Core Concepts

GPU vs CPU Particles

Node Processing Features Use For
GPUParticles2D GPU Full features, high counts, trails Most 2D effects
GPUParticles3D GPU Full features, attractors, collision Most 3D effects
CPUParticles2D CPU Simpler, no trails/attractors Low-end devices, few particles
CPUParticles3D CPU Simpler, no trails/attractors Low-end devices, few particles

Rule of thumb: Use GPU particles by default. Switch to CPU particles only for low-end/web targets. Neither node exposes per-particle positions to scripts, so spawning objects at particle locations needs your own simulation.

You can convert between GPU and CPU particles in the editor: select the node → toolbar → Convert to CPUParticles2D/3D (or vice versa).

Particle System Architecture

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

Minimal Setup

  1. Add a GPUParticles2D (or 3D) node
  2. In Inspector → Process Material → New ParticleProcessMaterial
  3. Set Amount (number of particles)
  4. Configure emission, direction, velocity, gravity
  5. (2D) Set Texture for particle appearance
  6. (3D) Set Draw Pass 1 mesh (QuadMesh for billboards, or custom mesh)

2. Key Node Properties

GPUParticles2D/3D Properties

Property Type Description
emitting bool Start/stop emission
amount int Total particles alive at once
lifetime float Seconds each particle lives
one_shot bool Emit once then stop
preprocess float Simulate this many seconds before first frame
speed_scale float Time multiplier for particle physics
explosiveness float 0.0 = spread over lifetime, 1.0 = all at once
fixed_fps int Lock particle update rate (0 = match render FPS)
local_coords bool Particles move with the node (true) or stay in world (false)
draw_order enum Index, Lifetime, or Reverse Lifetime
amount_ratio float Fraction of particles to emit (0.0–1.0)

One-Shot vs Continuous

# 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;

Local Billboard Alignment (Godot 4.7+)

GPUParticles3D gains TRANSFORM_ALIGN_LOCAL_BILLBOARD (= 4): each particle's Z axis faces the camera while preserving a given axis — X or Y, chosen via transform_align_axis. For billboarded particles, transform_align_channel_filter selects which custom channel to read to calculate their angle. ParticleProcessMaterial pairs this with per-axis rotation velocity: enable use_rotation_velocity_3d, then set rotation_velocity_3d_min/max (Vector3, on the particle's local axes) and optionally rotation_velocity_3d_curve (per-axis curve over lifetime).

# 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 — Essential Properties

The material drives per-particle behavior: emission shape (Point / Sphere / Box / Ring / Points / Directed Points), direction + spread + initial velocity, gravity, scale and color over lifetime (via scale_curve / color_ramp), damping, radial/tangential acceleration, and angular velocity.

See references/process-material-basics.md for the emission-shape table and GDScript + C# snippets for each property group.

Per-Axis 3D Scale & Rotation (Godot 4.7+)

Randomize scale and initial orientation per axis instead of uniformly. use_scale_3d enables scale_3d_min/max (Vector3 random scale per particle); use_rotation_3d enables rotation_3d_min/max (Vector3, degrees — works only in 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);

Inheriting Emitter Scale (Godot 4.7+)

particle_flag_inherit_emitter_scale (default false): if true, particles inherit the scale of the emitter node. Has no effect when local_coords is true, since particles in local space are already affected by the emitter's scale.

mat.particle_flag_inherit_emitter_scale = true
mat.ParticleFlagInheritEmitterScale = true;

4. Common VFX Recipes

The recipes most projects need: fire (2D, looped emission with hot-color gradient + scale-down), explosion burst (one-shot, high-amount short-lifetime), dust / footstep puff (one-shot, scale-up + rapid fade).

See references/vfx-recipes.md for ready-to-use GDScript wiring and recommended ParticleProcessMaterial settings for all three.


5. Trails (Forward+ and Mobile only)

Set trail_enabled = true on GPUParticles2D/3D and assign a Mesh (RibbonTrailMesh or TubeTrailMesh). Trails are NOT supported in the Compatibility renderer.

See references/trails.md for the setup and trail-mesh-type comparison.

Godot 4.8+: Trail3D (inherits LineBase3D) draws a flat line behind a moving object without particles, such as a sword swing or a projectile. Size it with width / width_curve, and limit it by lifetime (default 0.2 s) or max_length through limit_mode; mesh_alignment picks a 3D line or a billboard. color / color_gradient only show when the material uses vertex color as albedo.


6. Subemitters

A particle can make another particle system emit at a constant rate, at collision, at its death, or (Godot 4.4+) at its birth. Configure via ParticleProcessMaterial.sub_emitter_mode + the sub_emitter property on the parent particles node.

See references/subemitters.md for trigger modes, scene setup, GDScript and C# (v1.6.0 parity), and limitations.

Note: With sub_emitter_keep_velocity = true (default false), subemitted particles inherit the parent particle's velocity when they spawn. This is unchanged in 4.7: a regression in 4.7 dev builds that broke the inheritance was fixed before 4.7 stable (GH-118062), so nothing needs migrating from 4.6.


7. Attractors & Collision (3D)

GPUParticlesAttractor*3D (Box / Sphere / Vector Field) pulls particles toward a region. GPUParticlesCollision*3D (Box / Sphere / SDF / HeightField) lets particles bounce off geometry. Compatibility runs box/sphere attractors and box/sphere/height-field colliders; vector-field attractors and SDF colliders need Forward+ or Mobile. 2D has no attractor nodes, but GPUParticles2D collide with LightOccluder2D nodes when collision_mode is set.

See references/attractors-and-collision.md for full setup of each attractor and collision type.


8. Turbulence

Set turbulence_enabled = true on ParticleProcessMaterial and tune turbulence_noise_strength (0.5–2.0 typical), turbulence_noise_scale (higher = larger, smoother swirls), turbulence_noise_speed (animate the noise field). Cheap effect for "alive" smoke, fire, dust.


9. Flipbook Animation (2D)

Sprite-sheet animated particles via ParticleProcessMaterial.AnimSpeedMin/Max + CanvasItemMaterial.ParticlesAnimHFrames/VFrames for the sheet layout. Particles cycle through frames over their lifetime.

See references/flipbook-animation.md for the full setup with GDScript + C# (v1.6.0 parity).


10. Performance and Common Pitfalls

The biggest wins are the obvious ones: keep amount at the minimum that reads well, keep fixed_fps at its default 30 for ambient systems (0 updates every frame), always set visibility_rect on 2D particles, and expose amount_ratio as a quality slider. Godot 4.7+ adds request_particles_process() for seeking a paused timeline.

Most "broken particles" reports are one of eleven known causes — invisible (no texture / no draw-pass mesh), vanishing (lifetime too short), one-shot not re-firing (emitting = true is ignored until the last burst's particles finish; restart() re-fires at once), wrong direction (2D Y is inverted), or a dark base color, which multiplies color_ramp.

Full performance table, the 4.7+ timeline-seek API, dynamic quality scaling (GDScript + C#), and the complete symptom/cause/fix table: references/performance-and-pitfalls.md


11. Implementation Checklist

  • Particle amount is set to the minimum needed for the visual effect
  • lifetime matches the visual duration — not too short or too long
  • one_shot is enabled for burst effects (explosions, impacts)
  • preprocess is set for always-visible ambient effects (fire, smoke, dust)
  • Emission shape matches the source geometry (sphere for explosions, box for area effects)
  • color_ramp fades alpha to 0 at the end so particles don't vanish abruptly
  • scale_curve shrinks particles over lifetime for natural fade
  • local_coords is set correctly — true for attached effects, false for world-space
  • One-shot particles are cleaned up with queue_free after lifetime + margin
  • visibility_rect (2D) is set to prevent particles from being culled prematurely
  • Dynamic quality scaling uses amount_ratio for player-accessible quality settings
  • Performance-heavy features (turbulence, trails) are disabled on low-end targets

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts7d3 checks · Risk SAFE
  • Gen Agent Trust Hub7d

    The skill provides comprehensive and safe documentation for creating particle effects in Godot 4.3+. It includes GDScript and C# examples for common VFX tasks. No malicious patterns or security risks were identified.

  • Socket7d

    No alerts

  • Snyk7d

    Risk: LOW · No issues

Signed by skilld at 426e8ab. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 6 days ago.

Activeupdated last week

README badge

README badge for jame581/godotprompter/particles-vfx