ParticleEngine manages all particle effects in the game, from breaking blocks to spell effects, providing visual feedback for player actions and environmental effects.
Overview
ParticleEngine.h:11
Texture Types
Particles are organized by texture source:ParticleEngine.h:18-24
Particle Management
Storage Structure
Particles are stored in deques organized by dimension and texture type:- 0 = Overworld
- 1 = Nether
- 2 = The End
ParticleEngine.h:29
Particle Limits
To maintain performance, particle counts are capped:ParticleEngine.h:14-15
When limits are reached, oldest particles are removed (FIFO):
ParticleEngine.cpp:34
Particle Base Class
Particle.h:11
Particle Lifecycle
- Creation - Particle spawned at position with velocity
- Tick - Update position, check collisions, age
- Render - Draw billboarded quad
- Removal - Age exceeds lifetime or marked removed
Rendering
t- Tesselator for vertex submissiona- Frame interpolation alphaxa, za- Camera right vectorya- Camera up vectorxa2, za2- Camera forward vector
Particle.h:44
Particle Types
Terrain Particles
TerrainParticle
Used when breaking blocks:ParticleEngine.cpp:171
Crack Particles
ParticleEngine.cpp:189
Misc Texture Particles
BubbleParticle
BubbleParticle.h:4
- Rises in water
- Pops at surface
- Used in water and lava
SmokeParticle
- Various smoke types
- Torch smoke
- Fire smoke
- Velocity and gravity affected
FlameParticle
- Fire particles
- Torch flames
- Entity burning effect
ExplodeParticle
- Explosion debris
- TNT explosions
- Creeper explosions
HeartParticle
- Animal breeding
- Taming success
- Rises upward
NoteParticle
- Note block particles
- Colored based on pitch
- Musical note icon
NetherPortalParticle
- Portal effect
- Purple particles
- Drifting motion
EnderParticle
- Enderman teleport effect
- End portal particles
- Purple/black particles
SpellParticle
- Potion effects
- Beacon effects
- Colored based on effect type
CritParticle / CritParticle2
- Critical hit effect
- Enhanced damage indicator
RedDustParticle
- Redstone wire
- Redstone torch
- Red sparkles
SnowShovelParticle
- Snow digging
- White particles
SplashParticle
- Water splash
- Rain drops
- Fishing bobber
DripParticle
- Water dripping from blocks
- Lava dripping
- Falls downward
LavaParticle
- Lava surface particles
- Fire-like behavior
SuspendedParticle / SuspendedTownParticle
- Floating particles in air
- Village/town ambient particles
FootstepParticle
- Walking particles
- Various block types
WaterDropParticle
- Water droplets
- Rain particles
EchantmentTableParticle
- Enchantment table runes
- Float toward book
- Galactic alphabet symbols
HugeExplosionParticle / HugeExplosionSeedParticle
- Large explosion effects
- Ender dragon death
- TNT explosion core
DragonBreathParticle
Item Texture Particles
BreakingItemParticle
BreakingItemParticle.h:4
Used when:
- Breaking tools
- Eating food
- Throwing items
Entity Particles
TakeAnimationParticle
- Item pickup animation
- Moves toward player
- Rendered in lit pass
PlayerCloudParticle
- Player-specific effects
- Custom particle system
Rendering Process
Main Render
ParticleEngine.cpp:59
Process:
- Calculate camera vectors from
Cameraclass - Set static offsets for camera position
- For each texture type:
- Skip entity particles (rendered separately)
- Skip if no particles
- Bind appropriate texture
- Begin tesselation
- Render all particles of this type
- End tesselation
Lit Particle Render
ParticleEngine.cpp:121
Renders entity particles (e.g., TakeAnimationParticle) with proper lighting.
Lighting Integration
ParticleEngine.cpp:104
Particles can receive world lighting via the second texture unit.
Particle Update
ParticleEngine.cpp:38
Process:
- Iterate all dimensions
- Iterate all texture types
- Tick each particle
- Remove particles marked as removed
- Use swap-and-pop for efficient removal
ParticleEngine.cpp:48
Dimension Handling
Particles are dimension-aware:- Dimension 0: Overworld
- Dimension -1: Nether (stored in index 1)
- Other: The End (stored in index 2)
ParticleEngine.cpp:33
Only particles in the current dimension are rendered.
Adding Particles
Direct Add
ParticleEngine.h:36
Directly adds a particle to the appropriate queue.
Via LevelRenderer
Performance Considerations
Particle Batching
Particles are batched by texture type:ParticleEngine.cpp:95
Minimizes texture binds and draw calls.
Memory Management
Usingdeque instead of vector:
- Efficient front removal (FIFO)
- No reallocation on push_back
- Stable iteration
Camera Offset
Static camera offset avoids per-particle calculation:ParticleEngine.cpp:69
Statistics
ParticleEngine.cpp:208
Returns total particle count for current dimension (for debug display).
Integration with Game Systems
Block Breaking
When a block is destroyed:Block Mining
When hitting a block:Level Events
Various level events trigger particles:- Redstone activation
- Potion effects
- Enchanting
- Breeding
- Weather effects
Custom Particles
To create a custom particle:- Extend
Particlebase class - Override
tick()for custom behavior - Override
render()if needed - Set texture via
setMiscTex()or custom icon - Add to engine via
add()
Related Systems
- Level Renderer - Particle integration
- Entity Renderer - Entity particles
- Level Events - Particle triggers