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

Loading...
Searching...
No Matches
CRM64Pro::ParticleEmitter
Graphics modules » Particle Effects

Particle emitter object class. More...

## Detailed Description

Particle emitter object class.

ParticleEmitter controls the full state of a particle effect: emission, simulation, rendering and storage. Objects are owned by ParticleMgr and must be obtained through ParticleMgr::get().

## Public Member Functions
bool | info (Sint32 iMode=0) override
| Request ParticleEmitter information.
const string & | getName () const override
| Get the emitter name.
Sint32 | getID () const override
| Get the emitter handle.
bool | play ()
| Start or resume particle emission.
bool | pause ()
| Pause particle updates without clearing live particles.
bool | stop ()
| Stop particle updates and emission.
bool | reset ()
| Clear particles and restart the emitter.
bool | clear ()
| Remove all live particles.
Sint32 | burst (Sint32 iCount)
| Emit a fixed number of particles immediately.
eGeneralStatus | status () const
| Get current emitter status.
bool | setVisible (bool bVisible)
| Set emitter visibility.
bool | isVisible () const
| Check emitter visibility.
bool | setVisual (eParticleVisual eVisual, Sint32 idRes=0, Sint32 iAnim=-1)
| Set particle visual type and optional image/sprite resource.
bool | setBlendMode (SDL_BlendMode bmValue)
| Set particle blend mode.
bool | setGlowRender (bool bEnabled, float fIntensity=1.0f)
| Enable additive glow rendering for supported particle visuals.
bool | setSpriteAnimation (eParticleSpriteAnimation eMode)
| Set Sprite particle frame selection mode.
bool | setBoundsEnabled (bool bEnabled)
| Enable or disable cached emitter bounds.
bool | setShape (eParticleEmitterShape eShape, float fWidth=0.0f, float fHeight=0.0f)
| Set emitter spawn shape.
bool | setEmissionRate (float fParticlesPerSec)
| Set continuous emission rate.
bool | setEmissionDistance (float fDistance)
| Set movement-distance emission spacing.
bool | setMaxParticles (Sint32 iMaxParticles)
| Set maximum live particle count.
bool | setDuration (float fSeconds)
| Set emission duration in seconds; negative means unlimited.
bool | setLoop (bool bLoop)
| Enable or disable duration looping.
bool | setLifeSpan (float fMinSec, float fMaxSec)
| Set particle lifetime range in seconds.
bool | setDirection (float fAngleDeg, float fSpreadDeg)
| Set emission direction and angular spread in degrees.
bool | setDirectionMode (eParticleDirectionMode eMode)
| Set initial velocity direction mode.
bool | setSpeed (float fMinSpeed, float fMaxSpeed)
| Set particle speed range.
bool | setVelocityLimit (float fMaxSpeed)
| Set the maximum particle velocity magnitude.
bool | setVelocityInheritance (float fAmount)
| Set inherited emitter movement velocity.
bool | setPhysics (float fGravityX, float fGravityY, float fDamping=0.0f)
| Set gravity and damping.
bool | setAttraction (float fStrength, float fRadius=0.0f, float fFalloff=0.0f)
| Set attraction toward emitter center.
bool | setOrbit (float fStrength, float fRadius=0.0f, float fFalloff=0.0f)
| Set orbit force around emitter center.
bool | setCollision (SceneLayerTile *pTileLayer, eParticleCollisionMode eMode=PCM_BOUNCE, float fBounciness=0.5f)
| Set tile-layer collision behavior and runtime layer binding.
bool | setCollisionMode (eParticleCollisionMode eMode, float fBounciness=0.5f)
| Set persistent collision behavior.
bool | setCollisionLayer (SceneLayerTile *pTileLayer)
| Bind the runtime collision tile layer.
bool | setColorKeys (const vector< ParticleColorKey > &vKeys)
| Set color ramp keys.
bool | setTintPalette (const vector< SDL_Color > &vColors)
| Set random tint palette.
const vector< SDL_Color > & | getTintPalette () const
| Get random tint palette.
bool | setScaleRamp (float fStartScale, float fEndScale)
| Set scale interpolation from birth to death.
bool | setScaleKeys (const vector< ParticleScaleKey > &vKeys)
| Set scale ramp keys.
bool | setRotation (float fStartAngle, float fSpinVelocity)
| Set initial angle and spin velocity.
bool | setStretch (float fAmount, bool bAlignToVelocity=true)
| Set stretch amount.
bool | setTurbulence (float fStrength)
| Set random velocity perturbation strength.
bool | setSimulationScale (float fScale)
| Set emitter simulation speed.
bool | setWarmUp (float fSeconds)
| Set fresh-start simulation warm-up time.
bool | setLocalSpace (bool bLocalSpace)
| Select world-space or emitter-local particle movement.
bool | setDrawOrder (eParticleDrawOrder eOrder)
| Set particle rendering order.
bool | setBursts (const vector< ParticleBurst > &vBursts)
| Set timed particle bursts.
bool | setSubEmitters (const vector< ParticleSubEmitter > &vSubEmitters)
| Set particle-triggered sub-emitters.
bool | applyPreset (eParticleEffectPreset ePreset)
| Apply a built-in particle preset.
bool | setPosition (float fX, float fY)
| Set emitter world position.
bool | teleport (float fX, float fY)
| Move the emitter without producing distance emission or inherited movement velocity.
bool | setSeed (Uint32 iSeed)
| Set deterministic random seed.
float | getX () const
| Get emitter X position.
float | getY () const
| Get emitter Y position.
Sint32 | getLiveCount () const
| Get current live particle count.
float | getEmissionRate () const
| Get continuous emission rate.
Sint32 | getMaxParticles () const
| Get maximum live particle count.
bool | getVisual (eParticleVisual *eVisual, Sint32 *idRes, Sint32 *iAnim) const
| Get particle visual configuration.
SDL_BlendMode | getBlendMode () const
| Get particle blend mode.
bool | getGlowRender (float *fIntensity=nullptr) const
| Get additive glow rendering configuration.
eParticleSpriteAnimation | getSpriteAnimation () const
| Get Sprite particle frame selection mode.
bool | getBoundsEnabled () const
| Check if cached emitter bounds are enabled.
bool | getBounds (SDL_FRect *pBounds) const
| Get cached emitter bounds.
bool | getShape (eParticleEmitterShape *eShape, float *fWidth, float *fHeight) const
| Get emitter spawn shape.
float | getEmissionDistance () const
| Get movement-distance emission spacing.
float | getDuration () const
| Get emission duration.
bool | getLoop () const
| Get duration looping mode.
bool | getLifeSpan (float *fMinSec, float *fMaxSec) const
| Get particle lifetime range.
bool | getDirection (float *fAngleDeg, float *fSpreadDeg) const
| Get emission direction and spread.
eParticleDirectionMode | getDirectionMode () const
| Get initial velocity direction mode.
bool | getSpeed (float *fMinSpeed, float *fMaxSpeed) const
| Get particle speed range.
float | getVelocityLimit () const
| Get maximum particle velocity magnitude.
float | getVelocityInheritance () const
| Get inherited emitter movement velocity.
bool | getPhysics (float *fGravityX, float *fGravityY, float *fDamping) const
| Get gravity and damping configuration.
bool | getAttraction (float *fStrength, float *fRadius, float *fFalloff) const
| Get attraction configuration.
bool | getOrbit (float *fStrength, float *fRadius, float *fFalloff) const
| Get orbit configuration.
bool | getCollision (SceneLayerTile **ppTileLayer, eParticleCollisionMode *eMode, float *fBounciness) const
| Get collision configuration.
SceneLayerTile * | getCollisionLayer () const
| Get the runtime collision tile layer.
const vector< ParticleColorKey > & | getColorKeys () const
| Get color ramp keys.
const vector< ParticleScaleKey > & | getScaleKeys () const
| Get scale ramp keys.
bool | getRotation (float *fStartAngle, float *fSpinVelocity) const
| Get initial angle and spin velocity.
bool | getStretch (float *fAmount, bool *bAlignToVelocity) const
| Get stretch configuration.
float | getTurbulence () const
| Get random velocity perturbation strength.
float | getSimulationScale () const
| Get emitter simulation speed.
float | getWarmUp () const
| Get fresh-start simulation warm-up time.
bool | getLocalSpace () const
| Get local-space simulation mode.
eParticleDrawOrder | getDrawOrder () const
| Get particle rendering order.
const vector< ParticleBurst > & | getBursts () const
| Get timed particle bursts.
const vector< ParticleSubEmitter > & | getSubEmitters () const
| Get particle-triggered sub-emitters.
eParticleEffectPreset | getPreset () const
| Get applied built-in particle preset.
Uint32 | getSeed () const
| Get deterministic random seed.
bool | update (float fDeltaTime)
| Advance emitter simulation.
Sint32 | render (Sint32 idRes=0)
| Render live particles.
Sint32 | save (const string &sCDCFile, const string &sResourceName="")
| Save emitter to a CDC file.
Sint32 | save (Sint32 idCDC, const string &sResourceName="")
| Save emitter to an opened CDC archive.

## Member Function Documentation

## ◆ info()

bool CRM64Pro::ParticleEmitter::info | ( | Sint32 | iMode = 0 | ) |
| override

Request ParticleEmitter information.

Writes information to the default log.

Parameters

  iMode | Reserved for future use. Pass 0.

Returns
  true on success, or false on failure.

## ◆ getName()

const string & CRM64Pro::ParticleEmitter::getName | ( |  | ) | const
| override

Get the emitter name.

Returns
  Constant reference to the emitter name.

## ◆ getID()

Sint32 CRM64Pro::ParticleEmitter::getID | ( |  | ) | const
| override

Get the emitter handle.

Returns
  ParticleEmitter id managed by ParticleMgr.

## ◆ play()

bool CRM64Pro::ParticleEmitter::play | ( |  | ) |

Start or resume particle emission.

Returns
  true on success, or false on failure.

Note
  Existing live particles continue from their current state.

## ◆ pause()

bool CRM64Pro::ParticleEmitter::pause | ( |  | ) |

Pause particle updates without clearing live particles.

Returns
  true on success, or false on failure.

## ◆ stop()

bool CRM64Pro::ParticleEmitter::stop | ( |  | ) |

Stop particle updates and emission.

Returns
  true on success, or false on failure.

Note
  Live particles are kept until clear() or reset() is called.

## ◆ reset()

bool CRM64Pro::ParticleEmitter::reset | ( |  | ) |

Clear particles and restart the emitter.

Returns
  true on success, or false on failure.

## ◆ clear()

bool CRM64Pro::ParticleEmitter::clear | ( |  | ) |

Remove all live particles.

Returns
  true on success, or false on failure.

## ◆ burst()

Sint32 CRM64Pro::ParticleEmitter::burst | ( | Sint32 | iCount | ) |

Emit a fixed number of particles immediately.

Parameters

  iCount | Number of particles to emit. Must be greater than 0.

Returns
  Number of particles emitted on success, or a negative error code on failure.

Note
  The emitted amount can be lower than iCount when the configured maximum live particle count is reached.

## ◆ status()

eGeneralStatus CRM64Pro::ParticleEmitter::status | ( |  | ) | const

Get current emitter status.

Returns
  ::GS_ENABLED while visible and playing, ::GS_HIDDEN while playing with visibility disabled, ::GS_PAUSED while paused, ::GS_DISABLED while stopped or not started, or ::GS_END after finite non-looping emission finishes and all particles expire.

## ◆ setVisible()

bool CRM64Pro::ParticleEmitter::setVisible | ( | bool | bVisible | ) |

Set emitter visibility.

Parameters

  bVisible | true to render the emitter, false to skip rendering while still allowing updates.

Returns
  true on success, or false on failure.

## ◆ isVisible()

bool CRM64Pro::ParticleEmitter::isVisible | ( |  | ) | const

Check emitter visibility.

Returns
  true if the emitter is visible, or false if rendering is disabled.

## ◆ setVisual()

bool CRM64Pro::ParticleEmitter::setVisual | ( | eParticleVisual | eVisual,
|  | Sint32 | idRes = 0,
|  | Sint32 | iAnim = -1 )

Set particle visual type and optional image/sprite resource.

Parameters

  eVisual | Visual rendering mode. Check ::eParticleVisual for further information.
  idRes | Optional Image or Sprite id used by ::PV_IMAGE and ::PV_SPRITE. Use 0 for primitive visual modes.
  iAnim | Sprite animation index used by sprite visual modes. Use -1 to keep the Sprite current animation. Default is -1.

Returns
  true on success, or false on failure.

Note
  The resource handle is borrowed; it is not closed by the emitter. Visual resources loaded through ParticleMgr::load() are owned by the loaded emitter.

## ◆ setBlendMode()

bool CRM64Pro::ParticleEmitter::setBlendMode | ( | SDL_BlendMode | bmValue | ) |

Set particle blend mode.

Parameters

  bmValue | SDL blend mode used when rendering particles.

Returns
  true on success, or false when bmValue is ::SDL_BLENDMODE_INVALID.

## ◆ setGlowRender()

bool CRM64Pro::ParticleEmitter::setGlowRender | ( | bool | bEnabled,
|  | float | fIntensity = 1.0f )

Enable additive glow rendering for supported particle visuals.

Parameters

  bEnabled | true to render supported visuals through GFX glow helpers, false to use the standard particle renderer.
  fIntensity | Glow brightness multiplier clamped to [0.0, 1.0]. Default is 1.0.

Returns
  true on success, or false on failure.

Note
  Applies to ::PV_SOFT, ::PV_IMAGE and ::PV_SPRITE. Additive ::PV_SOFT particles use the cached GFX glow path even when this setting is disabled.
  Image glow rendering is centered. Sprite glow rendering uses the current animation hotspot. Both paths are additive and uniform-scale; particle rotation and stretch are ignored.

## ◆ setSpriteAnimation()

bool CRM64Pro::ParticleEmitter::setSpriteAnimation | ( | eParticleSpriteAnimation | eMode | ) |

Set Sprite particle frame selection mode.

Parameters

  eMode | ::PSA_SHARED keeps the current shared-Sprite-frame behavior. ::PSA_RANDOM_OFFSET assigns one random frame offset per particle at spawn.

Returns
  true on success, or false when eMode is invalid.

Note
  Applies only to ::PV_SPRITE and is persisted in CDC data.

## ◆ setBoundsEnabled()

bool CRM64Pro::ParticleEmitter::setBoundsEnabled | ( | bool | bEnabled | ) |

Enable or disable cached emitter bounds.

Parameters

  bEnabled | true to compute bounds during update, false to skip bounds work.

Returns
  true on success.

Note
  Disabled by default. Bounds are broad-phase world-space AABB data and are not persisted in CDC data.

## ◆ setShape()

bool CRM64Pro::ParticleEmitter::setShape | ( | eParticleEmitterShape | eShape,
|  | float | fWidth = 0.0f,
|  | float | fHeight = 0.0f )

Set emitter spawn shape.

Parameters

  eShape | Emitter shape. Check ::eParticleEmitterShape for further information.
  fWidth | Shape width in pixels in the range [0, 1000000]. Default is 0.
  fHeight | Shape height in pixels in the range [0, 1000000]. Used by rectangle and ellipse emitters; ignored by circle and ring emitters. Default is 0.

Returns
  true on success, or false on failure.

## ◆ setEmissionRate()

bool CRM64Pro::ParticleEmitter::setEmissionRate | ( | float | fParticlesPerSec | ) |

Set continuous emission rate.

Parameters

  fParticlesPerSec | Number of particles emitted per second in the range [0, 1000000]. Use 0 to disable continuous emission.

Returns
  true on success, or false on failure.

## ◆ setEmissionDistance()

bool CRM64Pro::ParticleEmitter::setEmissionDistance | ( | float | fDistance | ) |

Set movement-distance emission spacing.

Parameters

  fDistance | Distance in pixels between emissions. Use 0 to disable distance emission.

Returns
  true on success, or false on failure.

Note
  Particles are placed at interpolated points along emitter movement.

## ◆ setMaxParticles()

bool CRM64Pro::ParticleEmitter::setMaxParticles | ( | Sint32 | iMaxParticles | ) |

Set maximum live particle count.

Parameters

  iMaxParticles | Maximum live particle count in the range [1, 65536].

Returns
  true on success, or false on failure.

Note
  Lowering iMaxParticles immediately discards the newest live particles above the new capacity without firing death sub-emitter triggers; new spawns are limited by the new value.

## ◆ setDuration()

bool CRM64Pro::ParticleEmitter::setDuration | ( | float | fSeconds | ) |

Set emission duration in seconds; negative means unlimited.

Parameters

  fSeconds | Emission duration in seconds in the range [0, 86400]. Positive values smaller than 1/4096 second are rejected. Use a negative value for unlimited duration.

Returns
  true on success, or false on failure.

## ◆ setLoop()

bool CRM64Pro::ParticleEmitter::setLoop | ( | bool | bLoop | ) |

Enable or disable duration looping.

Parameters

  bLoop | true to restart duration-limited emission automatically, false to stop at the end.

Returns
  true on success, or false on failure.

## ◆ setLifeSpan()

bool CRM64Pro::ParticleEmitter::setLifeSpan | ( | float | fMinSec,
|  | float | fMaxSec )

Set particle lifetime range in seconds.

Parameters

  fMinSec | Minimum particle lifetime in seconds. Must be greater than 0.
  fMaxSec | Maximum particle lifetime in seconds. Must be greater than or equal to fMinSec and no greater than 86400.

Returns
  true on success, or false on failure.

## ◆ setDirection()

bool CRM64Pro::ParticleEmitter::setDirection | ( | float | fAngleDeg,
|  | float | fSpreadDeg )

Set emission direction and angular spread in degrees.

Parameters

  fAngleDeg | Center direction in degrees.
  fSpreadDeg | Random angular spread in degrees around fAngleDeg. Must be greater than or equal to 0.

Returns
  true on success, or false on failure.

## ◆ setDirectionMode()

bool CRM64Pro::ParticleEmitter::setDirectionMode | ( | eParticleDirectionMode | eMode | ) |

Set initial velocity direction mode.

Parameters

  eMode | Fixed configured direction or radial direction from the emitter center.

Returns
  true on success, or false when eMode is invalid.

## ◆ setSpeed()

bool CRM64Pro::ParticleEmitter::setSpeed | ( | float | fMinSpeed,
|  | float | fMaxSpeed )

Set particle speed range.

Parameters

  fMinSpeed | Minimum start speed in pixels per second. Must be greater than or equal to 0.
  fMaxSpeed | Maximum start speed in pixels per second. Must be greater than or equal to fMinSpeed.

Returns
  true on success, or false on failure.

## ◆ setVelocityLimit()

bool CRM64Pro::ParticleEmitter::setVelocityLimit | ( | float | fMaxSpeed | ) |

Set the maximum particle velocity magnitude.

Parameters

  fMaxSpeed | Maximum speed in pixels per second. Use 0 to disable velocity limiting.

Returns
  true on success, or false on failure.

## ◆ setVelocityInheritance()

bool CRM64Pro::ParticleEmitter::setVelocityInheritance | ( | float | fAmount | ) |

Set inherited emitter movement velocity.

Parameters

  fAmount | Emitter velocity multiplier added to new particles. Must be greater than or equal to 0. Default is 0.

Returns
  true on success, or false on failure.

## ◆ setPhysics()

bool CRM64Pro::ParticleEmitter::setPhysics | ( | float | fGravityX,
|  | float | fGravityY,
|  | float | fDamping = 0.0f )

Set gravity and damping.

Parameters

  fGravityX | Horizontal acceleration in pixels per second squared.
  fGravityY | Vertical acceleration in pixels per second squared.
  fDamping | Velocity damping factor. Must be greater than or equal to 0. Default is 0.

Returns
  true on success, or false on failure.

## ◆ setAttraction()

bool CRM64Pro::ParticleEmitter::setAttraction | ( | float | fStrength,
|  | float | fRadius = 0.0f,
|  | float | fFalloff = 0.0f )

Set attraction toward emitter center.

Parameters

  fStrength | Attraction strength. Positive values pull particles toward the emitter center; negative values repel.
  fRadius | Effective radius in pixels. Use 0 for unlimited radius. Default is 0.
  fFalloff | Falloff exponent. Use 0 for no falloff. Default is 0.

Returns
  true on success, or false on failure.

## ◆ setOrbit()

bool CRM64Pro::ParticleEmitter::setOrbit | ( | float | fStrength,
|  | float | fRadius = 0.0f,
|  | float | fFalloff = 0.0f )

Set orbit force around emitter center.

Parameters

  fStrength | Orbit strength. Positive and negative values rotate in opposite directions.
  fRadius | Effective radius in pixels. Use 0 for unlimited radius. Default is 0.
  fFalloff | Falloff exponent. Use 0 for no falloff. Default is 0.

Returns
  true on success, or false on failure.

## ◆ setCollision()

bool CRM64Pro::ParticleEmitter::setCollision | ( | SceneLayerTile * | pTileLayer,
|  | eParticleCollisionMode | eMode = PCM_BOUNCE,
|  | float | fBounciness = 0.5f )

Set tile-layer collision behavior and runtime layer binding.

Parameters

  pTileLayer | Borrowed Scene tile-layer pointer used for collision checks, or nullptr to leave collision configured but inactive. CRM64Pro does not take ownership. The pointer must remain valid until it is replaced, unbound with setCollisionLayer(nullptr), or this emitter is closed.
  eMode | Collision behavior. Check ::eParticleCollisionMode for further information. Default is ::PCM_BOUNCE.
  fBounciness | Velocity multiplier used by ::PCM_BOUNCE. Must be greater than or equal to 0. Default is 0.5.

Returns
  true on success, or false on failure.

Note
  Unbind the layer from every ParticleEmitter before closing the layer or its owning Scene.

## ◆ setCollisionMode()

bool CRM64Pro::ParticleEmitter::setCollisionMode | ( | eParticleCollisionMode | eMode,
|  | float | fBounciness = 0.5f )

Set persistent collision behavior.

Parameters

  eMode | Collision behavior persisted in CDC data. Use ::PCM_NONE to disable collision.
  fBounciness | Velocity multiplier used by ::PCM_BOUNCE. Must be greater than or equal to 0. Default is 0.5.

Returns
  true on success, or false on invalid input.

Note
  Collision is evaluated only while a runtime tile layer is assigned with setCollisionLayer().

## ◆ setCollisionLayer()

bool CRM64Pro::ParticleEmitter::setCollisionLayer | ( | SceneLayerTile * | pTileLayer | ) |

Bind the runtime collision tile layer.

Parameters

  pTileLayer | Borrowed Scene tile-layer pointer used for collision checks, or nullptr to unbind it. CRM64Pro does not take ownership. The pointer must remain valid until it is replaced, unbound, or this emitter is closed.

Returns
  true on success.

Note
  The layer pointer is runtime-only and is not persisted in CDC data.
  Unbind the layer from every ParticleEmitter before closing the layer or its owning Scene.

## ◆ setColorKeys()

bool CRM64Pro::ParticleEmitter::setColorKeys | ( | const vector< ParticleColorKey > & | vKeys | ) |

Set color ramp keys.

Parameters

  vKeys | Color keys used to interpolate particle color over lifetime. Pass an empty vector to restore the default white ramp.

Returns
  true on success, or false on failure.

Note
  Key fT values are clamped to [0.0, 1.0] and sorted internally.

## ◆ setTintPalette()

bool CRM64Pro::ParticleEmitter::setTintPalette | ( | const vector< SDL_Color > & | vColors | ) |

Set random tint palette.

Parameters

  vColors | Tint colors used for per-particle random color variation. Pass an empty vector to restore the single white default.

Returns
  true on success, or false on failure.

Note
  One tint is selected at particle spawn and multiplied with the lifetime color ramp. Use a single white color to disable random tinting.

## ◆ getTintPalette()

const vector< SDL_Color > & CRM64Pro::ParticleEmitter::getTintPalette | ( |  | ) | const

Get random tint palette.

Returns
  Tint colors used for per-particle random color variation.

## ◆ setScaleRamp()

bool CRM64Pro::ParticleEmitter::setScaleRamp | ( | float | fStartScale,
|  | float | fEndScale )

Set scale interpolation from birth to death.

Parameters

  fStartScale | Particle scale at birth in the range [0, 10000]. Zero-scale particles are not rendered.
  fEndScale | Particle scale at death in the range [0, 10000]. Zero-scale particles are not rendered.

Returns
  true on success, or false on failure.

## ◆ setScaleKeys()

bool CRM64Pro::ParticleEmitter::setScaleKeys | ( | const vector< ParticleScaleKey > & | vKeys | ) |

Set scale ramp keys.

Parameters

  vKeys | Scale keys interpolated over particle lifetime. Pass an empty vector to restore the default scale ramp.

Returns
  true on success, or false on failure.

Note
  Up to eight keys are accepted. Key fT values are clamped to [0.0, 1.0], scales must be in [0, 10000], and keys are sorted internally. Zero-scale particles are not rendered.

## ◆ setRotation()

bool CRM64Pro::ParticleEmitter::setRotation | ( | float | fStartAngle,
|  | float | fSpinVelocity )

Set initial angle and spin velocity.

Parameters

  fStartAngle | Initial render angle in degrees.
  fSpinVelocity | Angular velocity in degrees per second.

Returns
  true on success, or false on failure.

## ◆ setStretch()

bool CRM64Pro::ParticleEmitter::setStretch | ( | float | fAmount,
|  | bool | bAlignToVelocity = true )

Set stretch amount.

With bAlignToVelocity enabled, rectangle, line, image and sprite visuals align to the true velocity angle.

Parameters

  fAmount | Stretch multiplier. Must be greater than or equal to 0.
  bAlignToVelocity | true to align supported visuals to the particle velocity angle. Default is true.

Returns
  true on success, or false on failure.

## ◆ setTurbulence()

bool CRM64Pro::ParticleEmitter::setTurbulence | ( | float | fStrength | ) |

Set random velocity perturbation strength.

Parameters

  fStrength | Random turbulence strength in pixels per second. Must be greater than or equal to 0.

Returns
  true on success, or false on failure.

## ◆ setSimulationScale()

bool CRM64Pro::ParticleEmitter::setSimulationScale | ( | float | fScale | ) |

Set emitter simulation speed.

Parameters

  fScale | Simulation time multiplier. Must be greater than or equal to 0. Use 0 to freeze simulation without changing status.

Returns
  true on success, or false on failure.

## ◆ setWarmUp()

bool CRM64Pro::ParticleEmitter::setWarmUp | ( | float | fSeconds | ) |

Set fresh-start simulation warm-up time.

Parameters

  fSeconds | Particle simulation seconds processed before the first rendered frame, in the range [0.0, 30.0].

Returns
  true on success, or false on failure.

Note
  Warm-up is applied on play() or reset() only when no live particles exist.

## ◆ setLocalSpace()

bool CRM64Pro::ParticleEmitter::setLocalSpace | ( | bool | bLocalSpace | ) |

Select world-space or emitter-local particle movement.

Parameters

  bLocalSpace | true to move existing particles with the emitter, false to leave them in world space.

Returns
  true on success, or false on failure.

## ◆ setDrawOrder()

bool CRM64Pro::ParticleEmitter::setDrawOrder | ( | eParticleDrawOrder | eOrder | ) |

Set particle rendering order.

Parameters

  eOrder | Storage order or normalized-age sorting mode.

Returns
  true on success, or false on failure.

## ◆ setBursts()

bool CRM64Pro::ParticleEmitter::setBursts | ( | const vector< ParticleBurst > & | vBursts | ) |

Set timed particle bursts.

Parameters

  vBursts | Timed bursts fired when the emitter timeline crosses each entry. Pass an empty vector to disable timed bursts.

Returns
  true on success, or false on failure.

Note
  Up to sixteen entries are accepted. Entries are sorted by time internally and repeat with finite looping emitters.

## ◆ setSubEmitters()

bool CRM64Pro::ParticleEmitter::setSubEmitters | ( | const vector< ParticleSubEmitter > & | vSubEmitters | ) |

Set particle-triggered sub-emitters.

Parameters

  vSubEmitters | Sub-emitter definitions. Pass an empty vector to disable sub-emission.

Returns
  true on success, or false on failure.

Note
  Up to eight definitions are accepted. Targets must be finite one-shot built-in presets. Collision triggers fire at most once per particle.
  Recursive child spawning is limited to four levels and 256 child events per manager update.
  Use ParticleMgr::update() and ParticleMgr::render() so spawned child emitters are advanced and rendered with their parent.

## ◆ applyPreset()

bool CRM64Pro::ParticleEmitter::applyPreset | ( | eParticleEffectPreset | ePreset | ) |

Apply a built-in particle preset.

Parameters

  ePreset | Preset identifier. Check ::eParticleEffectPreset for further information.

Returns
  true on success, or false on failure.

Note
  Presets stop the emitter, clear live particles, reset elapsed emission time and overwrite emitter configuration. Apply the preset first, then adjust custom values.
  One-shot presets such as ::PEP_MUZZLE_FLASH, ::PEP_EXPLOSION, ::PEP_SHOCKWAVE, ::PEP_WATER_SPLASH and ::PEP_PICKUP_SPARKLE emit exact configured bursts when played.

## ◆ setPosition()

bool CRM64Pro::ParticleEmitter::setPosition | ( | float | fX,
|  | float | fY )

Set emitter world position.

Parameters

  fX | Horizontal position in pixels in the range [-1000000000, 1000000000].
  fY | Vertical position in pixels in the range [-1000000000, 1000000000].

Returns
  true on success, or false on failure.

Note
  Movement is used by distance emission and emitter velocity inheritance. Use teleport() for discontinuous relocation.

## ◆ teleport()

bool CRM64Pro::ParticleEmitter::teleport | ( | float | fX,
|  | float | fY )

Move the emitter without producing distance emission or inherited movement velocity.

Parameters

  fX | Horizontal destination in pixels.
  fY | Vertical destination in pixels.

Returns
  true on success, or false on failure.

Note
  Local-space particles follow the teleport; world-space particles remain in place.

## ◆ setSeed()

bool CRM64Pro::ParticleEmitter::setSeed | ( | Uint32 | iSeed | ) |

Set deterministic random seed.

Parameters

  iSeed | Seed value used by the emitter random generator.

Returns
  true on success, or false on failure.

Note
  Reusing the same seed and the same update sequence produces deterministic particle spawning across emitter handles and CDC reloads. Fresh play and reset restart the sequence.

## ◆ getX()

float CRM64Pro::ParticleEmitter::getX | ( |  | ) | const

Get emitter X position.

Returns
  Horizontal emitter position in pixels.

## ◆ getY()

float CRM64Pro::ParticleEmitter::getY | ( |  | ) | const

Get emitter Y position.

Returns
  Vertical emitter position in pixels.

## ◆ getLiveCount()

Sint32 CRM64Pro::ParticleEmitter::getLiveCount | ( |  | ) | const

Get current live particle count.

Returns
  Number of live particles currently owned by the emitter.

## ◆ getEmissionRate()

float CRM64Pro::ParticleEmitter::getEmissionRate | ( |  | ) | const

Get continuous emission rate.

Returns
  Number of particles emitted per second.

## ◆ getMaxParticles()

Sint32 CRM64Pro::ParticleEmitter::getMaxParticles | ( |  | ) | const

Get maximum live particle count.

Returns
  Configured maximum live particle count.

## ◆ getVisual()

bool CRM64Pro::ParticleEmitter::getVisual | ( | eParticleVisual * | eVisual,
|  | Sint32 * | idRes,
|  | Sint32 * | iAnim ) const

Get particle visual configuration.

Parameters

  eVisual | Output particle visual mode.
  idRes | Output Image or Sprite resource id.
  iAnim | Output sprite animation index.

Returns
  true on success, or false on failure.

## ◆ getBlendMode()

SDL_BlendMode CRM64Pro::ParticleEmitter::getBlendMode | ( |  | ) | const

Get particle blend mode.

Returns
  SDL blend mode used when rendering particles.

## ◆ getGlowRender()

bool CRM64Pro::ParticleEmitter::getGlowRender | ( | float * | fIntensity = nullptr | ) | const

Get additive glow rendering configuration.

Parameters

  fIntensity | Optional output glow brightness multiplier.

Returns
  true when glow rendering is enabled, or false when disabled.

## ◆ getSpriteAnimation()

eParticleSpriteAnimation CRM64Pro::ParticleEmitter::getSpriteAnimation | ( |  | ) | const

Get Sprite particle frame selection mode.

Returns
  Sprite particle frame selection mode.

## ◆ getBoundsEnabled()

bool CRM64Pro::ParticleEmitter::getBoundsEnabled | ( |  | ) | const

Check if cached emitter bounds are enabled.

Returns
  true when bounds are computed during update, or false otherwise.

## ◆ getBounds()

bool CRM64Pro::ParticleEmitter::getBounds | ( | SDL_FRect * | pBounds | ) | const

Get cached emitter bounds.

Parameters

  pBounds | Output world-space AABB covering live renderable particles.

Returns
  true when bounds are enabled and valid, or false when disabled, empty or not yet updated.

Note
  The returned rectangle is conservative broad-phase data, not pixel-perfect collision. It is updated by update().

## ◆ getShape()

bool CRM64Pro::ParticleEmitter::getShape | ( | eParticleEmitterShape * | eShape,
|  | float * | fWidth,
|  | float * | fHeight ) const

Get emitter spawn shape.

Parameters

  eShape | Output emitter shape.
  fWidth | Output shape width in pixels.
  fHeight | Output shape height in pixels.

Returns
  true on success, or false on failure.

## ◆ getEmissionDistance()

float CRM64Pro::ParticleEmitter::getEmissionDistance | ( |  | ) | const

Get movement-distance emission spacing.

Returns
  Distance in pixels between emissions, or 0 when disabled.

## ◆ getDuration()

float CRM64Pro::ParticleEmitter::getDuration | ( |  | ) | const

Get emission duration.

Returns
  Emission duration in seconds, or -1 for unlimited duration.

## ◆ getLoop()

bool CRM64Pro::ParticleEmitter::getLoop | ( |  | ) | const

Get duration looping mode.

Returns
  true when duration-limited emission loops, or false otherwise.

## ◆ getLifeSpan()

bool CRM64Pro::ParticleEmitter::getLifeSpan | ( | float * | fMinSec,
|  | float * | fMaxSec ) const

Get particle lifetime range.

Parameters

  fMinSec | Output minimum particle lifetime in seconds.
  fMaxSec | Output maximum particle lifetime in seconds.

Returns
  true on success, or false on failure.

## ◆ getDirection()

bool CRM64Pro::ParticleEmitter::getDirection | ( | float * | fAngleDeg,
|  | float * | fSpreadDeg ) const

Get emission direction and spread.

Parameters

  fAngleDeg | Output center direction in degrees.
  fSpreadDeg | Output angular spread in degrees.

Returns
  true on success, or false on failure.

## ◆ getDirectionMode()

eParticleDirectionMode CRM64Pro::ParticleEmitter::getDirectionMode | ( |  | ) | const

Get initial velocity direction mode.

Returns
  Configured fixed or radial direction mode.

## ◆ getSpeed()

bool CRM64Pro::ParticleEmitter::getSpeed | ( | float * | fMinSpeed,
|  | float * | fMaxSpeed ) const

Get particle speed range.

Parameters

  fMinSpeed | Output minimum start speed in pixels per second.
  fMaxSpeed | Output maximum start speed in pixels per second.

Returns
  true on success, or false on failure.

## ◆ getVelocityLimit()

float CRM64Pro::ParticleEmitter::getVelocityLimit | ( |  | ) | const

Get maximum particle velocity magnitude.

Returns
  Maximum speed in pixels per second, or 0 when disabled.

## ◆ getVelocityInheritance()

float CRM64Pro::ParticleEmitter::getVelocityInheritance | ( |  | ) | const

Get inherited emitter movement velocity.

Returns
  Emitter velocity multiplier applied to new particles.

## ◆ getPhysics()

bool CRM64Pro::ParticleEmitter::getPhysics | ( | float * | fGravityX,
|  | float * | fGravityY,
|  | float * | fDamping ) const

Get gravity and damping configuration.

Parameters

  fGravityX | Output horizontal acceleration.
  fGravityY | Output vertical acceleration.
  fDamping | Output velocity damping factor.

Returns
  true on success, or false on failure.

## ◆ getAttraction()

bool CRM64Pro::ParticleEmitter::getAttraction | ( | float * | fStrength,
|  | float * | fRadius,
|  | float * | fFalloff ) const

Get attraction configuration.

Parameters

  fStrength | Output attraction strength.
  fRadius | Output effective radius in pixels.
  fFalloff | Output falloff exponent.

Returns
  true on success, or false on failure.

## ◆ getOrbit()

bool CRM64Pro::ParticleEmitter::getOrbit | ( | float * | fStrength,
|  | float * | fRadius,
|  | float * | fFalloff ) const

Get orbit configuration.

Parameters

  fStrength | Output orbit strength.
  fRadius | Output effective radius in pixels.
  fFalloff | Output falloff exponent.

Returns
  true on success, or false on failure.

## ◆ getCollision()

bool CRM64Pro::ParticleEmitter::getCollision | ( | SceneLayerTile ** | ppTileLayer,
|  | eParticleCollisionMode * | eMode,
|  | float * | fBounciness ) const

Get collision configuration.

Parameters

  ppTileLayer | Optional output that receives the borrowed collision tile-layer pointer. CRM64Pro retains ownership; the caller must not delete it. The pointer remains valid until it is replaced, unbound, or the layer or emitter is closed.
  eMode | Output collision behavior.
  fBounciness | Output bounce velocity multiplier.

Returns
  true on success, or false on failure.

## ◆ getCollisionLayer()

SceneLayerTile * CRM64Pro::ParticleEmitter::getCollisionLayer | ( |  | ) | const

Get the runtime collision tile layer.

Returns
  Borrowed runtime tile-layer pointer, or nullptr when no layer is bound.

Note
  The returned pointer must not be deleted. It remains valid until it is replaced, unbound, or the layer or emitter is closed.

## ◆ getColorKeys()

const vector< ParticleColorKey > & CRM64Pro::ParticleEmitter::getColorKeys | ( |  | ) | const

Get color ramp keys.

Returns
  Color keys used to interpolate particle color over lifetime.

## ◆ getScaleKeys()

const vector< ParticleScaleKey > & CRM64Pro::ParticleEmitter::getScaleKeys | ( |  | ) | const

Get scale ramp keys.

Returns
  Scale keys used to interpolate particle scale over lifetime.

## ◆ getRotation()

bool CRM64Pro::ParticleEmitter::getRotation | ( | float * | fStartAngle,
|  | float * | fSpinVelocity ) const

Get initial angle and spin velocity.

Parameters

  fStartAngle | Output initial render angle in degrees.
  fSpinVelocity | Output angular velocity in degrees per second.

Returns
  true on success, or false on failure.

## ◆ getStretch()

bool CRM64Pro::ParticleEmitter::getStretch | ( | float * | fAmount,
|  | bool * | bAlignToVelocity ) const

Get stretch configuration.

Parameters

  fAmount | Output stretch multiplier.
  bAlignToVelocity | Output velocity-alignment mode.

Returns
  true on success, or false on failure.

## ◆ getTurbulence()

float CRM64Pro::ParticleEmitter::getTurbulence | ( |  | ) | const

Get random velocity perturbation strength.

Returns
  Turbulence strength in pixels per second.

## ◆ getSimulationScale()

float CRM64Pro::ParticleEmitter::getSimulationScale | ( |  | ) | const

Get emitter simulation speed.

Returns
  Simulation time multiplier.

## ◆ getWarmUp()

float CRM64Pro::ParticleEmitter::getWarmUp | ( |  | ) | const

Get fresh-start simulation warm-up time.

Returns
  Warm-up duration in seconds.

## ◆ getLocalSpace()

bool CRM64Pro::ParticleEmitter::getLocalSpace | ( |  | ) | const

Get local-space simulation mode.

Returns
  true for emitter-local movement, or false for world-space movement.

## ◆ getDrawOrder()

eParticleDrawOrder CRM64Pro::ParticleEmitter::getDrawOrder | ( |  | ) | const

Get particle rendering order.

Returns
  Configured particle rendering order.

## ◆ getBursts()

const vector< ParticleBurst > & CRM64Pro::ParticleEmitter::getBursts | ( |  | ) | const

Get timed particle bursts.

Returns
  Timed burst definitions.

## ◆ getSubEmitters()

const vector< ParticleSubEmitter > & CRM64Pro::ParticleEmitter::getSubEmitters | ( |  | ) | const

Get particle-triggered sub-emitters.

Returns
  Particle sub-emitter definitions.

## ◆ getPreset()

eParticleEffectPreset CRM64Pro::ParticleEmitter::getPreset | ( |  | ) | const

Get applied built-in particle preset.

Returns
  Last applied or loaded preset identifier.

## ◆ getSeed()

Uint32 CRM64Pro::ParticleEmitter::getSeed | ( |  | ) | const

Get deterministic random seed.

Returns
  Seed used by the emitter random generator.

## ◆ update()

bool CRM64Pro::ParticleEmitter::update | ( | float | fDeltaTime | ) |

Advance emitter simulation.

Parameters

  fDeltaTime | Elapsed time in seconds in the range [0, 1]. The scaled delta must also be no greater than 1.

Returns
  true on success, or false on failure.

Note
  Use Main::getLogicDeltaTime() for fixed-step simulation.
  Returns false when more than 8192 emission timestamps are generated in one update.

## ◆ render()

Sint32 CRM64Pro::ParticleEmitter::render | ( | Sint32 | idRes = 0 | ) |

Render live particles.

Parameters

  idRes | Render target id. Use 0 for the default screen target.

Returns
  0 on success, or a negative error code on failure.

Note
  Pixel, rectangle, line and non-glow soft rendering to an Image target supports standard alpha blending. Other blend modes for those paths require a Screen target and return an unsupported-operation error.
  Image and Sprite visuals are scaled but not rotated when rendering to an Image target.

## ◆ save() [1/2]

Sint32 CRM64Pro::ParticleEmitter::save | ( | const string & | sCDCFile,
|  | const string & | sResourceName = "" )

Save emitter to a CDC file.

Parameters

  sCDCFile | string containing the [directory]+filename.
  sResourceName | Optional resource name inside the CDC archive. When empty, the emitter name is used.

Returns
  0 on success, or a negative error code on failure.

## ◆ save() [2/2]

Sint32 CRM64Pro::ParticleEmitter::save | ( | Sint32 | idCDC,
|  | const string & | sResourceName = "" )

Save emitter to an opened CDC archive.

Parameters

  idCDC | CDC id.
  sResourceName | Optional resource name inside the CDC archive. When empty, the emitter name is used.

Returns
  0 on success, or a negative error code on failure.