Skip to main content

Particles

Not up to date

This page is not up to date for MonoGame.Extended 4.0.3. If you would like to contribute to updating this document, please create a new PR

MonoGame.Extended.Particles is ported from the Mercury Particle Engine. A particle engine helps you simulate phenomena, which are otherwise very hard to reproduce with conventional rendering techniques. examples include replicating fire, explosions, smoke, moving water, sparks.

Quick start​

We start by including the required namespaces.

using MonoGame.Extended;
using MonoGame.Extended.Particles;
using MonoGame.Extended.Particles.Modifiers;
using MonoGame.Extended.Particles.Modifiers.Containers;
using MonoGame.Extended.Particles.Modifiers.Interpolators;
using MonoGame.Extended.Particles.Profiles;
using MonoGame.Extended.TextureAtlases;

Next, we declare our ParticleEffect and Texture2D fields

private ParticleEffect _particleEffect;
private Texture2D _particleTexture;

Which we assign in the LoadContent function

_particleTexture = new Texture2D(GraphicsDevice, 1, 1);
_particleTexture.SetData(new[] { Color.White });

TextureRegion2D textureRegion = new TextureRegion2D(_particleTexture);
_particleEffect = new ParticleEffect(autoTrigger: false)
{
    Position = new Vector2(400, 240),
    Emitters = new List<ParticleEmitter>
    {
        new ParticleEmitter(textureRegion, 500, TimeSpan.FromSeconds(2.5),
            Profile.BoxUniform(100,250))
        {
            Parameters = new ParticleReleaseParameters
            {
                Speed = new Range<float>(0f, 50f),
                Quantity = 3,
                Rotation = new Range<float>(-1f, 1f),
                Scale = new Range<float>(3.0f, 4.0f)
            },
            Modifiers =
            {
                new AgeModifier
                {
                    Interpolators =
                    {
                        new ColorInterpolator
                        {
                            StartValue = new HslColor(0.33f, 0.5f, 0.5f),
                            EndValue = new HslColor(0.5f, 0.9f, 1.0f)
                        }
                    }
                },
                new RotationModifier {RotationRate = -2.1f},
                new RectangleContainerModifier {Width = 800, Height = 480},
                new LinearGravityModifier {Direction = -Vector2.UnitY, Strength = 30f},
            }
        }
    }
};

Since _particleTexture and _particleEffect are not loaded with the ContentManager, we need to dispose them in UnloadContent.

_particleTexture.Dispose();
_particleEffect.Dispose();

Finaly, we add implement Update and Draw

protected override void Update(GameTime gameTime)
{
    _particleEffect.Update((float)gameTime.ElapsedGameTime.TotalSeconds);
    base.Update(gameTime);
}

protected override void Draw(GameTime gameTime)
{
    GraphicsDevice.Clear(Color.Black);

    _spriteBatch.Begin(blendState: BlendState.AlphaBlend);
    _spriteBatch.Draw(_particleEffect);
    _spriteBatch.End();

    base.Draw(gameTime);
}

Profiles​

Profiles determine how the particles are distributed

CircleProfile​

The Circle profile distributes the particles within a circle

CircleRadiation​

Determines the heading direction of the particles

Code

Profile.Circle(150, Profile.CircleRadiation.In)

circleProfileIn

PointProfile​

The Point profile distributes the particles at the same point

Code

Profile.Point()

PointProfile

BoxProfile​

The Box profile distributes the particles over the edge of a box

note

The box profile distributed 25% of the particle on each edge. If you have a rectangular shape and you want an even distribution, use the BoxUniform profile

Code

Profile.Box(150,150)

BoxProfile

BoxUniformProfile​

The BoxUniform profile evenly distributes the particles over the edge of a box

Code

Profile.BoxUniform(150,300)

BoxUniformProfile

BoxFillProfile​

The BoxFill profile distributes the particles within a box

Code

Profile.BoxFill(150,150)

BoxFillProfile

LineProfile​

The Line profile distributes the particles over a line

Code

Profile.Line(new Vector2(1,1), 150)

LineProfile

RingProfile​

The Ring profile distributes the particles over a line

CircleRadiation​

Determines the heading direction of the particles

Code

Profile.Ring(150, Profile.CircleRadiation.In)

RingProfile

SprayProfile​

The Spray profile prays the particles in a given direction

Code

Profile.Spray(new Vector2(1,1), 2f )

SprayProfile

Modifiers​

AgeModifier​

The AgeModifier Uses Interpolators to modify the particle over its lifespan.

Code

new AgeModifier
{
    Interpolators =
    {
        new ColorInterpolator
        {
            StartValue = Color.Yellow.ToHsl(),
            EndValue = Color.Blue.ToHsl()
        }
    }
}

Result

AgeModifier

CircleContainerModifier​

This Modifier makes the particles collide with a circle container.

Radius​

The radius of the CircleContainer.

Inside​

Whether the particles should stay inside the of outside the container

RestitutionCoefficient​

The bounces back force of the particles

Code

new CircleContainerModifier()
{
    Radius = 50,
    Inside = true,
    RestitutionCoefficient = 0.2f
}

Result

CircleContainerModifier

RectangleContainerModifier​

This Modifier makes the particles collide with a rectangle container.

Width​

Width of the container

Height​

Height of the container

RestitutionCoefficient​

The bounces back force of the particles

Code

new RectangleContainerModifier
{
    Width = 150,
    Height = 150,
    RestitutionCoefficient = 0.2f,
}

Result

RectangleContainerModifier

RectangleLoopContainerModifier​

This Modifier keeps the particles inside a rectangular container by looping them around.

Width​

Width of the container

Height​

Height of the container

Code

new RectangleLoopContainerModifier
{
    Width = 150,
    Height = 150
}

Result

RectangleLoopContainerModifier

DragModifier​

The DragModifier simulates the effects of the particle passing through a medium such as water, air, etc., which exert a force (drag) which slows the particles down.

DragCoefficient​

The drag coefficient of the particle.

Density​

The density of the medium through which the particle is moving.

Code

new DragModifier
{
    Density = 1f, DragCoefficient = 1f
}

Result

DragModifier

LinearGravityModifier​

LinearGravityModifier applies linear gravity to the particle

Direction​

The direction of gravity.

Strength​

Strength of the gravity

Code

new LinearGravityModifier
{
    Direction = new Vector2(0,-1), 
    Strength = 30f
}

Result

DragModifier

OpacityFastFadeModifier​

OpacityFastFadeModifier fades the particles over the span of their lifetime

Code

new OpacityFastFadeModifier()

Result

DragModifier

RotationModifier​

The RotationModifier rotates the particles by a given RotationRate

Code

new RotationModifier
{
    RotationRate = 5f
}

Result

RotationModifier

VelocityColorModifier​

The VelocityColorModifier Colors the particle by its velocity

StationaryColor​

The color when the velocity is 0

VelocityColor​

The particle color when it reaches the VelocityThreshold

VelocityThreshold​

The threshold of the velocity

Code

new VelocityColorModifier
{
    StationaryColor = Color.Green.ToHsl(),
    VelocityColor = Color.Blue.ToHsl(),
    VelocityThreshold = 80f
}

Result

VelocityColorModifier

VelocityModifier​

The VelocityModifier Uses Interpolators to modify the particles depending on their velocity.

Code

new VelocityModifier()
{
    Interpolators =
    {
        new ColorInterpolator
        {
            StartValue = Color.Green.ToHsl(),
            EndValue = Color.Blue.ToHsl()
        }
    },
    VelocityThreshold = 80f
}

Result

VelocityModifier

VortexModifier​

This VortexModifier moves the particles in a whirling vortex. This can be used for creating wind effects, etc.

Mass​

The mass of the vortex

Position​

The position of the vortex relative to the ParticleEmitter

Code

new VortexModifier()
{
    Mass = 10f,
    MaxSpeed = 1f,
    Position = new Vector2(0,-150)
},
new VortexModifier()
{
    Mass = 10f,
    MaxSpeed = 1f,
    Position = new Vector2(-150,0)
}

Result

VortexModifier

Interpolators​

Interpolators are used by AgeModifier and VelocityModifier to interpolate particle properties

ColorInterpolator​

The ColorInterpolator Interpolates from a Start to an End color.

Code

new AgeModifier
{
    Interpolators =
    {
        new ColorInterpolator
        {
            StartValue = Color.Yellow.ToHsl(),
            EndValue = Color.Blue.ToHsl()
        }
    }
}

Result

ColorInterpolator

HueInterpolator​

The HueInterpolator Interpolates from a Start to an End Hue.

note

Make sure to set the particle color

Code

new AgeModifier()
{
    Interpolators = new List<Interpolator>()
    {
        new HueInterpolator { StartValue = 0f, EndValue = 360f }
    }
}

Result

HueInterpolator

OpacityInterpolator​

The OpacityInterpolator Interpolates from a Start to an End Opacity.

Code

new AgeModifier()
{
    Interpolators = new List<Interpolator>()
    {
        new OpacityInterpolator { StartValue = -2f, EndValue = 1f }
    }
}

Result

OpacityInterpolator

RotationInterpolator​

The RotationInterpolator Interpolates from a Start to an End Rotation.

Code

new AgeModifier()
{
    Interpolators = new List<Interpolator>()
    {
        new RotationInterpolator { StartValue = 0f, EndValue = 5f }
    }
}

Result

RotationInterpolator

ScaleInterpolator​

The ScaleInterpolator Interpolates from a Start to an End Scale.

Code

new AgeModifier()
{
    Interpolators = new List<Interpolator>()
    {
        new ScaleInterpolator { StartValue = new Vector2(1,1), EndValue = new Vector2(10,10) }
    }
}

Result

ScaleInterpolator