Skip to main content
The ParticleEngine manages all particle effects in the game, from breaking blocks to spell effects, providing visual feedback for player actions and environmental effects.

Overview

See: ParticleEngine.h:11

Texture Types

Particles are organized by texture source:
See: ParticleEngine.h:18-24

Particle Management

Storage Structure

Particles are stored in deques organized by dimension and texture type:
Dimensions:
  • 0 = Overworld
  • 1 = Nether
  • 2 = The End
See: ParticleEngine.h:29

Particle Limits

To maintain performance, particle counts are capped:
See: ParticleEngine.h:14-15 When limits are reached, oldest particles are removed (FIFO):
See: ParticleEngine.cpp:34

Particle Base Class

See: Particle.h:11

Particle Lifecycle

  1. Creation - Particle spawned at position with velocity
  2. Tick - Update position, check collisions, age
  3. Render - Draw billboarded quad
  4. Removal - Age exceeds lifetime or marked removed

Rendering

Particles are rendered as billboarded quads that always face the camera. Parameters:
  • t - Tesselator for vertex submission
  • a - Frame interpolation alpha
  • xa, za - Camera right vector
  • ya - Camera up vector
  • xa2, za2 - Camera forward vector
See: Particle.h:44

Particle Types

Terrain Particles

TerrainParticle

Used when breaking blocks:
Spawned via:
Creates 4×4×4 = 64 particles per block broken. See: ParticleEngine.cpp:171

Crack Particles

Creates particles when hitting a block (mining). See: ParticleEngine.cpp:189

Misc Texture Particles

BubbleParticle

See: 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

Has special higher limit (1000 particles).

Item Texture Particles

BreakingItemParticle

See: 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

See: ParticleEngine.cpp:59 Process:
  1. Calculate camera vectors from Camera class
  2. Set static offsets for camera position
  3. 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

See: ParticleEngine.cpp:121 Renders entity particles (e.g., TakeAnimationParticle) with proper lighting.

Lighting Integration

See: ParticleEngine.cpp:104 Particles can receive world lighting via the second texture unit.

Particle Update

See: ParticleEngine.cpp:38 Process:
  1. Iterate all dimensions
  2. Iterate all texture types
  3. Tick each particle
  4. Remove particles marked as removed
  5. Use swap-and-pop for efficient removal
See: 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)
See: ParticleEngine.cpp:33 Only particles in the current dimension are rendered.

Adding Particles

Direct Add

See: ParticleEngine.h:36 Directly adds a particle to the appropriate queue.

Via LevelRenderer

Factory method that creates appropriate particle type.

Performance Considerations

Particle Batching

Particles are batched by texture type:
See: ParticleEngine.cpp:95 Minimizes texture binds and draw calls.

Memory Management

Using deque instead of vector:
  • Efficient front removal (FIFO)
  • No reallocation on push_back
  • Stable iteration

Camera Offset

Static camera offset avoids per-particle calculation:
See: ParticleEngine.cpp:69

Statistics

See: ParticleEngine.cpp:208 Returns total particle count for current dimension (for debug display).

Integration with Game Systems

Block Breaking

When a block is destroyed:
Creates terrain particles showing the block’s texture.

Block Mining

When hitting a block:
Creates a single particle from the hit face.

Level Events

Various level events trigger particles:
  • Redstone activation
  • Potion effects
  • Enchanting
  • Breeding
  • Weather effects

Custom Particles

To create a custom particle:
  1. Extend Particle base class
  2. Override tick() for custom behavior
  3. Override render() if needed
  4. Set texture via setMiscTex() or custom icon
  5. Add to engine via add()
Example structure: