Skip to content

Particle FX

Purpose

Captures Unity built-in ParticleSystem (Shuriken) effects into frame sequences and sprite sheets for game-ready output. Uses deterministic ParticleSystem.Simulate() replay, supports single-angle and multi-angle (directional) capture, and provides a live in-editor preview.

A production Expert tab (alongside VFX Graph) — always visible, with a first-run expectation panel and per-effect bake-suitability warnings instead of Labs gating.

Good vs poor baking candidates

Baking flattens a 3D effect into a framed sprite/sheet, so it suits effects with a clear focal subject and a beginning/middle/end:

  • Bakes well: bursts, explosions, impacts/hits, projectiles, pickups, buffs, muzzle flashes, target-anchored auras.
  • Bakes poorly: rain, snow, fog, ambient fields, looping screen-wide weather — volumetric/continuous by design, with no compact subject to frame.

This is an inherent suitability limit, not a capture defect — those effects look weak baked no matter how clean the alpha is.

Owns

  • The Particle FX preview: deterministic playback, a preview-only speed control, a widenable preview window + skip-warm-up scrub for hunting seamless-loop frames, prime-on-select (shows a representative frame immediately), and an optional export-shader preview
  • The Particle FX export: single + multi-angle, warm-up + trim, looping (manual seamless-loop crossfade via the shared LoopCrossfadeProcessor; automatic best-loop-point detection via the shared LoopPointDetector + LoopPointScorer that trims to the closest-matching cut and applies a short residual crossfade; or a ping-pong bounce via the shared LoopPingPongProcessor), blend-mode-aware alpha capture, sprite-sheet assembly hand-off
  • Alpha capture — recovers correct transparency by rendering the same frame over black + white and reconstructing straight alpha; Auto detects Straight vs Additive from the pack's blend mode (the recovery math + blend rules live in Logic)
  • Built-in ParticleSystem analysis — scene sampling that suggests duration/fps/type (the heuristics themselves live in Logic)
  • The URP particle burst shader swapper (AlphaTint / Additive) — now a rescue path for packs that won't render in URP, not the default capture

Does NOT Own

  • VFX Graph capture (the sibling Features/VFX territory)
  • The capture/composite/encode pipeline (consumes the shared CaptureRequest → StaticCaptureExecutor funnel)
  • The particle heuristics / frame-range / bounds / alpha-recovery MATH — that lives in the unit-tested Logic kernel (ParticleFxHeuristics, ParticleCaptureRange, ParticleBoundsCalculator, ParticleAlphaReconstruction, ParticleBlendClassification)
  • Sprite-sheet / GIF assembly (the Export feature)
  • GameReady trim / clip / prefab (it consumes this feature's Frame_###.png output)

Allowed Dependencies

Particle FX may depend on:

  • Logic — the pure, unit-tested kernels (ParticleFxHeuristics, ParticleCaptureRange, ParticleBoundsCalculator, ParticleAlphaReconstruction, ParticleBlendClassification)
  • The shared Capture pipeline (CaptureEngine, CaptureRequest, StaticCaptureExecutor)
  • Directional Capture (orientation presets), Export (sprite-sheet assembler)
  • Diagnostics (logging), UI styling helpers
  • UnityEditor + UnityEngine particle APIs (ParticleSystem.Simulate, GetParticles)

Notes

  • Graphics API — Direct3D11 recommended. Heavy FX exports (dual-background alpha, multi-angle) render intensively. On some GPUs — older NVIDIA cards in particular — Unity's Direct3D12 backend can hang the device under that load (a GPU-timeout crash). Direct3D11 is the most stable choice and costs nothing (VFX Graph and particles both run fine on it): Player Settings → Other Settings → Rendering → Graphics APIs for Windows → put Direct3D11 first → restart. The export panels show an in-editor tip when D3D12 is detected.
  • Output is {prefab}_Frame_###.png (capital Frame_) so it feeds GameReady on case-sensitive filesystems; multi-angle writes Angle_###/ subfolders.
  • Export folder default is Assets/Exports/ParticleFX. VFX uses its own VfxExportPath pref — the keys must not be shared (an earlier collision let VFX stomp the particle path).
  • Alpha capture defaults to Auto — it detects the blend mode and reconstructs clean transparency from dual-background (black + white) renders, instead of a single transparent capture that fringes soft edges or drops additive particles. Manual Straight / Additive / None overrides exist.
  • Force export shaders (preview + export) is OFF by default and is now a rescue lever, not the alpha path: turn it on only for packs that render invisibly in URP (Built-in / exotic shaders) — it is a lossy unlit look, not the pack's real look.
  • Preview playback speed is preview-only; it does not affect export timing (Duration / FPS govern that).
  • No editor-coroutine dependency — the path is fully synchronous via deterministic Simulate(). SNAP no longer uses com.unity.editorcoroutines at all (the VFX export was rewritten off it too).
  • The grid shows a placeholder tile for particle prefabs (a static thumbnail of a system at rest is empty). A naive "simulate one frame" thumbnail was tried and looked poor (sparse frozen clouds at 128px), so the placeholder stays.

Future Candidates

  • Real grid thumbnails — would need a curated/animated preview, not the naive frozen-frame approach that was tried and rejected.
  • Sync export duration/fps with the preview analyzer.
  • Alpha-capture tuning (Slice D): gamma-vs-linear un-premultiply, per-channel alpha for coloured glass, additive brightness curve — only if specific packs fringe.
  • A shared IFrameSimulator abstraction with Features/VFX's VFXSimulator (the long-deferred "slice 5").