TheDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/Minecraft-Community-Edition/client/llms.txt
Use this file to discover all available pages before exploring further.
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