Particle Effects

Description

Particle Manager and ParticleEmitter objects for configurable real-time particle effects [v26.08.00].

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 world-space 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
• Collision: Persisted response behavior with independent runtime tile-layer, object-layer and Physics collision-set bindings
• 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.

Persistence and Scene integration

Saved effects are named C64_PARTICLE CDC resources. Built-in presets are templates, not live shared emitters. A C64Particle Scene object clones the asset named by c64scn_particle; its c64scn_particle_preset is used only when no asset is set. Every Scene object owns independent particle state, timing and random sequence.

Threading

ParticleEmitter::update() advances one emitter serially on the main thread. ParticleMgr::update() batches standalone emitters and can use internal workers while the main thread participates. Scene-owned emitters use the same batch automatically during Scene::update() and are excluded from ParticleMgr::update() and ParticleMgr::render(). Every update call waits for simulation, collision collection, sub-emitter creation and auto-close processing before returning; rendering remains on the main thread. See Threading conventions.

Best practices

• Use Main::getLogicDeltaTime() for deterministic ParticleEmitter::update() calls
• Use ParticleMgr::update() and ParticleMgr::render() for standalone emitters; use Scene::update() and Scene::render() for C64Particle emitters
• 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.