RandallLiuXin/GodotMaker / skills/reviewer/particles
particles-review
VerifiedReviews Godot Particles implementation for known pitfalls. Triggers AFTER implementation, when code involves GPUParticles2D, GPUParticles3D, CPUParticles2D, CPUParticles3D, ParticleProcessMaterial, trail_enabled, sub-emitters, GPUParticlesCollision, or particle amount/emission control. Do NOT use this skill for planning or teaching — only for post-implementation review.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 1.4 KB |
| checklist.md | markdown | 2.1 KB |
| gotchas.md | markdown | 4.4 KB |
gotchas.md
View on GitHub# Particles Gotchas
Design-level constraints — intentional engine behaviors, not bugs. Stable across Godot 4.x.
## G1. Changing particle `amount` at runtime kills all particles [GDScript] [C#]
**Symptom**: all visible particles vanish instantly when `amount` property is modified at runtime.
**Root cause**: engine reallocates the entire particle buffer on `amount` change, destroying existing particle state. Applies to both CPUParticles and GPUParticles.
**Correct approach**:
- GDScript: `gpu_particles.amount_ratio = 0.5` (GPU — scales without realloc), `cpu_particles.emitting = false` (CPU — no amount_ratio available)
- C#: `gpuParticles.AmountRatio = 0.5f;`, `cpuParticles.Emitting = false;`
**Wrong approach**:
- `cpu_particles.amount = 50` or `gpu_particles.amount = 50` at runtime
- Tweening `amount` for fade-in/fade-out effects
- Scaling `amount` based on distance for LOD
- Note: setting `amount` once in `_ready()` or `_init()` is fine (initialization before particles exist)
## G2. Particle collision is GPU-only and separate from PhysicsServer [GDScript] [C#]
**Symptom**: particles pass through StaticBody, RigidBody, and Area nodes. Sub-emitter `at_collision` never triggers despite particles visually hitting objects.
**Root cause**: particle collision runs on GPU with dedicated nodes (GPUParticlesCollision*), completely separate from PhysicsServer. 2D has no particle collision at all.
**Correct approach**:
- Add dedicated `GPUParticlesCollisionBox3D` / `GPUParticlesCollisionSphere3D` / `GPUParticlesCollisionHeightField3D` child nodes
- Sub-emitter `at_collision` triggers on GPUParticlesCollision nodes ONLY
- For gameplay hit detection (projectile hits enemy): use PhysicsServer, spawn VFX via script
**Wrong approach**:
- Expecting particles to interact with physics bodies (StaticBody3D, RigidBody3D)
- Using sub-emitter `at_collision` for gameplay hit detection against Area3D or CharacterBody3D
- Trying particle collision in 2D (no collision nodes exist for 2D particles)
- Adding a StaticBody3D as "floor" expecting particles to land on it
## G3. Trails require renderer AND mesh material opt-in [GDScript] [C#]
**Symptom**: `trail_enabled = true` but no visible trail. No error message.
**Root cause**: two independent requirements must both be met: (1) Forward+ or Mobile renderer (not Compatibility), (2) trail draw pass mesh material must set `use_particle_trails = true`. Missing either = silent failure.
**Correct approach**:
- GDScript: `gpu_particles.trail_enabled = true` AND `mesh_material.use_particle_trails = true`
- C#: `gpuParticles.TrailEnabled = true;` AND `meshMaterial.UseParticleTrails = true;`
- Verify `project.godot` → `rendering/renderer/rendering_method` is `forward_plus` or `mobile`
**Wrong approach**:
- Only setting `trail_enabled = true` on the node without touching mesh material
- Enabling trails in a Compatibility renderer project (silent failure)
- Setting `use_particle_trails` on the process material instead of the mesh material
- Enabling turbulence on Compatibility renderer (same renderer constraint)
## G4. Sub-emitter amount is overridden by parent [GDScript] [C#]
**Symptom**: sub-emitter particle count doesn't match what was set on its GPUParticles node.
**Root cause**: the parent emitter's `amount` property overrides the sub-emitter's `amount` at runtime by engine design. No warning emitted.
**Correct approach**: design sub-emitter effects that work within the inherited count. Adjust parent `amount` knowing it affects both.
**Wrong approach**:
- Setting independent `amount` on the sub-emitter GPUParticles node
- Trying to script sub-emitter `amount` at runtime for independent control
## G5. Particles without acceleration silently skip collision [GDScript] [C#]
**Symptom**: particles with initial velocity pass through GPUParticlesCollision nodes despite correct setup.
**Root cause**: collision detection relies on acceleration data for trajectory prediction. Zero acceleration = collision math doesn't trigger.
**Correct approach**:
- GDScript: `material.gravity = Vector3(0, -0.1, 0)` — even minimal acceleration enables collision
- C#: `material.Gravity = new Vector3(0, -0.1f, 0);`
- Also set `gpu_particles.fixed_fps = 60` or higher for fast particles
**Wrong approach**:
- `material.gravity = Vector3.ZERO` with only `initial_velocity` set
- Relying on `linear_accel` curve alone without any gravity
- Debugging collision node placement when the real issue is zero acceleration
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |