particles.h File Reference

A particle system for visual effects and environmental elements. More...

#include <SDL.h>
#include <vec2.h>
#include <stdbool.h>
#include <timer.h>
#include <camera.h>
#include <colliders.h>

Go to the source code of this file.

Classes
struct	Particle
	A struct that represents a particle. More...
struct	ParticleEmitter
	A struct that represents the configurations of a particle emitter. More...

Typedefs
typedef struct Particle	Particle
	A struct that represents a particle.
typedef struct ParticleEmitter	ParticleEmitter
	A struct that represents the configurations of a particle emitter.

Functions
void	ParticleEmitter_SetMaxParticles (ParticleEmitter *emitter, int maxParticles)
	Sets the maximum number of particles for an emitter.
void	ParticleEmitter_Emit (ParticleEmitter *emitter)
	Emits particles from the emitter.
int	ParticleEmitter_GetNextReady (ParticleEmitter *emitter)
	Gets the next available particle index.
void	ParticleEmitter_UpdateParticles (ParticleEmitter *emitter)
	Updates the particles of an emitter.
void	ParticleEmitter_Update (ParticleEmitter *emitter)
	Updates the emitter.
void	ParticleEmitter_ActivateOnce (ParticleEmitter *emitter)
	Activates the emitter once.
void	ParticleEmitter_Deactivate (ParticleEmitter *emitter)
	Deactivates the emitter.
void	ParticleEmitter_Render (ParticleEmitter *emitter)
	Renders the particles of an emitter.
void	ParticleEmitter_DestroyEmitter (ParticleEmitter *emitter)
	Destroys the emitter and frees its memory.
bool	ParticleEmitter_ParticlesAlive (ParticleEmitter *emitter)
	Checks if the emitter has any particles alive.

Detailed Description

A particle system for visual effects and environmental elements.

Particles are emitted from structs called ParticleEmitters.
Therefore, to generate particles, you have to, of course, create a Particle Emitter first. Emitters can be created based on a preset in particle_emitterpresets.c (Information on how to create a preset can be found inside particle_emitterpresets.h) After that, you can update and render the particles inside the game loop.

Usage

This is how it's done:

Step 1: Choose a preset

Look for a preset in particle_emitterpresets.c, for example ParticleEmitter_Default

Step 2: Create the emitter

These lines are called somewhere inside App_Start()

ParticleEmitter *emitter = ParticleEmitter_CreateFromPreset(ParticleEmitter_Default);
emitter->selfReference = &emitter;    // YOU HAVE TO DO THIS OR YOU DIE

Step 3: Update and render in the game loop

These lines are called somewhere inside App_PostUpdate()

// You can modify the emitter's properties as needed.   
emitter->position = ....; 
emitter->direction = ....;
 
// Update and render the emitter
ParticleEmitter_Update(emitter);            
ParticleEmitter_Render(emitter);

Step 4: One-time activation (optional)

For emitters that don't loop infinitely, add conditionals to activate the emitter

if (...) {
    ParticleEmitter_ActivateOnce(gunSparksEmitter);  // Activate the emitter once
}

Author

Mango

Date

2025-03-05

Typedef Documentation

Particle

typedef struct Particle Particle

A struct that represents a particle.

Particles are created and managed by a ParticleEmitter.

ParticleEmitter

typedef struct ParticleEmitter ParticleEmitter

A struct that represents the configurations of a particle emitter.

Emitter is responsible for creating and managing particles. Emitter presets (such as fire, smoke, gunshots, etc.) can be created and reused inside particle_emitterpresets.h and .c Emitters themselves can be created with ParticleEmitter_CreateDefault() and then modified as needed.

Warning

Make sure to set the selfReference field to the address of the emitter pointer.

ParticleEmitter *emitter = ParticleEmitter_CreateDefault(); 
emitter->selfReference = &emitter;

Call ParticleEmitter_Update() and ParticleEmitter_Render() every frame to update and render the particles.

Function Documentation

ParticleEmitter_ActivateOnce()

void ParticleEmitter_ActivateOnce

(

ParticleEmitter *

emitter

)

Activates the emitter once.

Parameters

emitter

The emitter to activate.

Activates the emitter once.

Reactivates a particle emitter that was inactive, setting up its state for another emission cycle.

Parameters

emitter

A pointer to the particle emitter

ParticleEmitter_Deactivate()

void ParticleEmitter_Deactivate

(

ParticleEmitter *

emitter

)

Deactivates the emitter.

Parameters

emitter

The emitter to deactivate.

Deactivates the emitter.

Stops a particle emitter from emitting new particles, though existing particles will continue to update and render.

Parameters

emitter

A pointer to the particle emitter

ParticleEmitter_DestroyEmitter()

void ParticleEmitter_DestroyEmitter

(

ParticleEmitter *

emitter

)

Destroys the emitter and frees its memory.

Parameters

emitter

The emitter to destroy.

Destroys the emitter and frees its memory.

Frees all resources associated with a particle emitter, including particle array and timer.

Parameters

emitter

A pointer to the particle emitter

ParticleEmitter_Emit()

void ParticleEmitter_Emit

(

ParticleEmitter *

emitter

)

Emits particles from the emitter.

Parameters

emitter

The emitter to emit particles from.

Emits particles from the emitter.

Creates a new particle with initial properties derived from the emitter settings plus appropriate randomization.

Parameters

emitter

A pointer to the particle emitter

ParticleEmitter_GetNextReady()

int ParticleEmitter_GetNextReady

(

ParticleEmitter *

emitter

)

Gets the next available particle index.

Parameters

emitter

The emitter to get the next available particle index from.

Returns

The next available particle index.

Gets the next available particle index.

Particle is available of it's dead, basically. Searches through the particle array to find the first particle that is not alive.

Parameters

emitter

A pointer to the particle emitter

Returns

The index of the next available particle, or maxParticles if none available

ParticleEmitter_ParticlesAlive()

bool ParticleEmitter_ParticlesAlive

(

ParticleEmitter *

emitter

)

Checks if the emitter has any particles alive.

Parameters

emitter

The emitter to check.

Returns

true if the emitter has particles alive, false otherwise.

Checks if the emitter has any particles alive.

Scans through all particles in the emitter to determine if any are still active.

Parameters

emitter

A pointer to the particle emitter

Returns

true if any particles are alive, false otherwise

ParticleEmitter_Render()

void ParticleEmitter_Render

(

ParticleEmitter *

emitter

)

Renders the particles of an emitter.

Parameters

emitter

The emitter to render the particles of.

Renders the particles of an emitter.

Draws all active particles with their current color, size, and position.

Parameters

emitter

A pointer to the particle emitter

ParticleEmitter_SetMaxParticles()

void ParticleEmitter_SetMaxParticles	(	ParticleEmitter *	emitter,
		int	maxParticles
	)

Sets the maximum number of particles for an emitter.

Parameters

emitter	The emitter to set the maximum particles for.
maxParticles	The maximum number of particles.

Sets the maximum number of particles for an emitter.

This is probably never going to be used, since this is already set inside particle_emitterpreset. Only use this if (for some reason) you want to change a particle emitter's max particles in the middle of a game

Parameters

emitter	A pointer to the particle emitter
maxParticles	The target max particle number

ParticleEmitter_Update()

void ParticleEmitter_Update

(

ParticleEmitter *

emitter

)

Updates the emitter.

Parameters

emitter

The emitter to update.

Updates the emitter.

Updates all aspects of a particle emitter including emission of new particles, updating existing particles, and handling emitter lifecycle events.

Parameters

emitter

A pointer to the particle emitter

ParticleEmitter_UpdateParticles()

void ParticleEmitter_UpdateParticles

(

ParticleEmitter *

emitter

)

Updates the particles of an emitter.

Parameters

emitter

The emitter to update the particles of.

Updates the particles of an emitter.

Processes all active particles, updating their position, color, size, and rotation based on their current state and lifecycle.

Parameters

emitter

A pointer to the particle emitter