| CRM64Pro GDK v0.19.0 A free cross-platform game development kit built on top of SDL 3.0

Loading...
Searching...
No Matches
Particle Effects
Graphics modules

## Description

Particle Manager and ParticleEmitter objects for configurable realtime particle effects [v26.07.0].

### Overview

The Particle module provides CPU-simulated particle emitters rendered through CRM64Pro graphics resources. Emitters can use primitive visuals, Image resources, Sprite resources or soft radial particles, with configurable lifetime, color, scale, velocity, gravity, attraction, orbit and tile-layer collision behavior. Soft additive particles can use the cached GFX glow path, and Image/Sprite particles can opt into additive glow-helper rendering for decorative emissive effects.

### Key features

- Emitter control: Play, pause, stop, reset, clear and burst particles
- Visual modes: Pixel, rectangle, line, soft particle, Image, Sprite and additive glow rendering
- Simulation controls: Lifetime, fixed/radial direction, speed limits, gravity, damping, turbulence, attraction, orbit, local space and time scaling
- Advanced emission: Time rate, movement distance, timed bursts, warm-up and death/collision sub-emitters
- Scene integration: Persisted collision behavior with a separately assigned runtime SceneLayerTile
- CDC storage: Save and load configured emitters with their owned visual resources
- Presets: Ready-made practical groups for environment, fire, weather, gameplay hits, auras, trails, thrust, pickups and fireworks

### Built-in preset groups

Built-in presets are ordered by practical group so tools can display the preset enum directly.

- Environment and atmosphere: cloud, smoke, steam, poison cloud and falling leaves.
- Fire and heat: fire, embers, lava and sparks.
- Weather and water: rain, storm, snow, waterfall, fountain, water splash and rain splash.
- Gameplay one-shots: muzzle flash, explosion, shockwave, magic hit, blood splatter, debris, dust and ice shards.
- Loops, auras and trails: electric arc, spell aura, portal, heal, glow aura, soft trail and engine thrust.
- Decorative: bubbles, bubble pop, twinkle, confetti, pickup sparkle and fireworks.

### Manager type

This is a standard object manager. ParticleEmitter objects are created or loaded by ParticleMgr and accessed by handle. The manager owns all ParticleEmitter instances and releases them automatically when Main is terminated.

### Best practices

- Use Main::getLogicDeltaTime() for deterministic ParticleEmitter::update() calls
- Use ParticleMgr::update() and ParticleMgr::render() when all loaded effects should be processed together
- Use ParticleMgr::playOneShot() for fire-and-forget preset effects; use ParticleEmitter::burst() for custom immediate bursts
- Keep maximum live particle counts close to the visible effect requirements
- Use setSeed() plus reset() when an effect must replay the same deterministic sequence
- Access the manager exclusively through Main::particleMgr()

Note
  The Particle Manager is a singleton, automatically created once Main is instantiated. You can get a reference to this manager using Main::particleMgr() method.
  The Particle Manager is automatically released when Main::terminate() is called. At this time, any resource still loaded will be released, avoiding resource leaks.

## Classes
struct | CRM64Pro::ParticleColorKey
| Particle color ramp key. More...
struct | CRM64Pro::ParticleScaleKey
| Particle scale ramp key. More...
struct | CRM64Pro::ParticleBurst
| Timed particle burst entry. More...
struct | CRM64Pro::ParticleSubEmitter
| Particle sub-emitter definition. More...
struct | CRM64Pro::ParticlePresetDesc
| Particle preset descriptor. More...
class | CRM64Pro::ParticleEmitter
| Particle emitter object class. More...
class | CRM64Pro::ParticleMgr
| Particle manager class. More...

## Enumerations
enum | CRM64Pro::eParticleVisual : Uint32 { CRM64Pro::PV_PIXEL = 0 , CRM64Pro::PV_RECT = 1 , CRM64Pro::PV_IMAGE = 2 , CRM64Pro::PV_SPRITE = 3 , CRM64Pro::PV_SOFT = 5 , CRM64Pro::PV_LINE = 6 }
| Particle visual rendering types. More...
enum | CRM64Pro::eParticleSpriteAnimation : Uint32 { CRM64Pro::PSA_SHARED = 0 , CRM64Pro::PSA_RANDOM_OFFSET = 1 }
| Particle sprite frame selection mode. More...
enum | CRM64Pro::eParticleEmitterShape : Uint32 { CRM64Pro::PES_POINT = 0 , CRM64Pro::PES_LINE = 1 , CRM64Pro::PES_RECT = 2 , CRM64Pro::PES_CIRCLE = 3 , CRM64Pro::PES_RING = 4 , CRM64Pro::PES_ELLIPSE = 5 }
| Particle emitter geometric shapes. More...
enum | CRM64Pro::eParticleDirectionMode : Uint32 { CRM64Pro::PDM_FIXED = 0 , CRM64Pro::PDM_RADIAL = 1 }
| Particle initial velocity direction modes. More...
enum | CRM64Pro::eParticleDrawOrder : Uint32 { CRM64Pro::PDO_STORAGE = 0 , CRM64Pro::PDO_OLDEST_FIRST = 1 , CRM64Pro::PDO_YOUNGEST_FIRST = 2 }
| Particle render ordering. More...
enum | CRM64Pro::eParticleCollisionMode : Uint32 { CRM64Pro::PCM_NONE = 0 , CRM64Pro::PCM_BOUNCE = 1 , CRM64Pro::PCM_STOP = 2 , CRM64Pro::PCM_KILL = 3 }
| Particle collision behavior. More...
enum | CRM64Pro::eParticleEffectPreset : Uint32 { CRM64Pro::PEP_BLANK = 0 , CRM64Pro::PEP_CLOUD = 1 , CRM64Pro::PEP_SMOKE = 2 , CRM64Pro::PEP_STEAM = 3 , CRM64Pro::PEP_POISON = 4 , CRM64Pro::PEP_FALLING_LEAVES = 5 , CRM64Pro::PEP_FIRE = 6 , CRM64Pro::PEP_EMBERS = 7 , CRM64Pro::PEP_LAVA = 8 , CRM64Pro::PEP_SPARKS = 9 , CRM64Pro::PEP_RAIN = 10 , CRM64Pro::PEP_STORM = 11 , CRM64Pro::PEP_SNOW = 12 , CRM64Pro::PEP_WATERFALL = 13 , CRM64Pro::PEP_FOUNTAIN = 14 , CRM64Pro::PEP_WATER_SPLASH = 15 , CRM64Pro::PEP_RAIN_SPLASH = 16 , CRM64Pro::PEP_MUZZLE_FLASH = 17 , CRM64Pro::PEP_EXPLOSION = 18 , CRM64Pro::PEP_SHOCKWAVE = 19 , CRM64Pro::PEP_MAGIC_HIT = 20 , CRM64Pro::PEP_BLOOD_SPLATTER = 21 , CRM64Pro::PEP_DEBRIS_BURST = 22 , CRM64Pro::PEP_DUST_PUFF = 23 , CRM64Pro::PEP_ICE_SHARDS = 24 , CRM64Pro::PEP_ELECTRIC_ARC = 25 , CRM64Pro::PEP_SPELL_AURA = 26 , CRM64Pro::PEP_PORTAL = 27 , CRM64Pro::PEP_HEAL = 28 , CRM64Pro::PEP_GLOW_AURA = 29 , CRM64Pro::PEP_SOFT_TRAIL = 30 , CRM64Pro::PEP_ENGINE_THRUST = 31 , CRM64Pro::PEP_BUBBLES = 32 , CRM64Pro::PEP_BUBBLE_POP = 33 , CRM64Pro::PEP_TWINKLE = 34 , CRM64Pro::PEP_CONFETTI = 35 , CRM64Pro::PEP_PICKUP_SPARKLE = 36 , CRM64Pro::PEP_FIREWORK_BURST = 37 , CRM64Pro::PEP_FIREWORK_ROCKET = 38 }
| Particle effect presets. More...
enum | CRM64Pro::eParticleSubEmitterTrigger : Uint32 { CRM64Pro::PST_NONE = 0x00u , CRM64Pro::PST_DEATH = 0x01u , CRM64Pro::PST_COLLISION = 0x02u }
| Sub-emitter trigger flags. More...

## Enumeration Type Documentation

## ◆ eParticleVisual

enum CRM64Pro::eParticleVisual : Uint32

Particle visual rendering types.

Enumerator
PV_PIXEL | Render each particle as a pixel.
PV_RECT | Render each particle as a filled rectangle.
PV_IMAGE | Render each particle using an Image resource.
PV_SPRITE | Render each particle using a Sprite resource.
PV_SOFT | Render each particle as a soft radial glow.
PV_LINE | Render each particle as a line segment.

## ◆ eParticleSpriteAnimation

enum CRM64Pro::eParticleSpriteAnimation : Uint32

Particle sprite frame selection mode.

Enumerator
PSA_SHARED | Use the shared Sprite current frame for every particle.
PSA_RANDOM_OFFSET | Give each particle a random frame offset within the shared Sprite animation range.

## ◆ eParticleEmitterShape

enum CRM64Pro::eParticleEmitterShape : Uint32

Particle emitter geometric shapes.

Enumerator
PES_POINT | Emit from a single point.
PES_LINE | Emit along a horizontal line centered on emitter position.
PES_RECT | Emit inside a rectangle centered on emitter position.
PES_CIRCLE | Emit uniformly across the area of a circle centered on emitter position.
PES_RING | Emit along a circle edge centered on emitter position.
PES_ELLIPSE | Emit uniformly across the area of an ellipse centered on emitter position.

## ◆ eParticleDirectionMode

enum CRM64Pro::eParticleDirectionMode : Uint32

Particle initial velocity direction modes.

Enumerator
PDM_FIXED | Use the configured direction angle and spread.
PDM_RADIAL | Point away from the sampled spawn position, then apply the configured spread.

## ◆ eParticleDrawOrder

enum CRM64Pro::eParticleDrawOrder : Uint32

Particle render ordering.

Enumerator
PDO_STORAGE | Render in internal particle storage order without sorting.
PDO_OLDEST_FIRST | Render older particles first and younger particles last.
PDO_YOUNGEST_FIRST | Render younger particles first and older particles last.

## ◆ eParticleCollisionMode

enum CRM64Pro::eParticleCollisionMode : Uint32

Particle collision behavior.

Enumerator
PCM_NONE | No particle collision.
PCM_BOUNCE | Bounce on collision and keep alive.
PCM_STOP | Stop movement after first collision while lifetime, animation and death processing continue.
PCM_KILL | Kill particle on first collision.

## ◆ eParticleEffectPreset

enum CRM64Pro::eParticleEffectPreset : Uint32

Particle effect presets.

Enumerator
PEP_BLANK | Empty emitter state.
PEP_CLOUD | Large soft drifting cloud bank.
PEP_SMOKE | Rising grey smoke column.
PEP_STEAM | Pale white and blue rising mist.
PEP_POISON | Green and purple toxic gas cloud.
PEP_FALLING_LEAVES | Falling leaves with turbulence and rotation.
PEP_FIRE | Additive flame plume.
PEP_EMBERS | Slow rising fire ember flakes.
PEP_LAVA | Slow heavy molten globs.
PEP_SPARKS | Continuous fast line sparks.
PEP_RAIN | Fast diagonal rain streaks.
PEP_STORM | Heavy rain variant with denser and faster streaks.
PEP_SNOW | Slow soft drifting snow field.
PEP_WATERFALL | Vertical curtain of fast downward water streaks.
PEP_FOUNTAIN | Upward water spray that arcs down with gravity.
PEP_WATER_SPLASH | One-shot droplets ejected from an impact point.
PEP_RAIN_SPLASH | Lightweight one-shot rain collision splash.
PEP_MUZZLE_FLASH | One-shot short weapon muzzle flash.
PEP_EXPLOSION | One-shot radial explosion burst.
PEP_SHOCKWAVE | One-shot expanding soft impact ring.
PEP_MAGIC_HIT | One-shot purple and cyan magical impact burst.
PEP_BLOOD_SPLATTER | One-shot radial blood splatter.
PEP_DEBRIS_BURST | One-shot dirt and rock impact fragments.
PEP_DUST_PUFF | One-shot soft dust puff.
PEP_ICE_SHARDS | One-shot frozen shard burst.
PEP_ELECTRIC_ARC | Continuous blue-white electric arcs around the emitter.
PEP_SPELL_AURA | Additive magical swirl and spell aura.
PEP_PORTAL | Compact inward-pulling portal ring.
PEP_HEAL | Rising green and gold healing orbs.
PEP_GLOW_AURA | Large slow soft aura particles.
PEP_SOFT_TRAIL | Soft fading object trail made from particles.
PEP_ENGINE_THRUST | Continuous left-facing ship or engine exhaust.
PEP_BUBBLES | Rising translucent bubbles.
PEP_BUBBLE_POP | Lightweight one-shot bubble pop sparkle.
PEP_TWINKLE | Additive star and twinkle field.
PEP_CONFETTI | Falling colored rectangular celebration particles.
PEP_PICKUP_SPARKLE | One-shot sparkle burst for collected items.
PEP_FIREWORK_BURST | One-shot colorful radial spark explosion.
PEP_FIREWORK_ROCKET | One-shot rising rocket that triggers a firework burst on death.

## ◆ eParticleSubEmitterTrigger

enum CRM64Pro::eParticleSubEmitterTrigger : Uint32

Sub-emitter trigger flags.

Enumerator
PST_NONE | No sub-emitter trigger.
PST_DEATH | Trigger when a particle reaches the end of its lifetime.
PST_COLLISION | Trigger on the particle's first collision.