Particle Effects - UQcsse3200/2024-studio-2 GitHub Wiki

To enhance the 'juice' of the game, a particle service was created to facilitate and manage particle effects.

Creating Your Own Effects

To create your own particle effects, you can use the GDX Particle Editor.

Once you have made your particle effects, you will need to place the .p particle file under the assets/particles folder and any images that the particle effect uses should be placed in the assets/particles/images folder.

Finally, you will need to add a description of the particle effect to the ParticleService.ParticleType enum in ParticleService.java.

The enum constructor takes 3 values:

  • path path to the particle effect .p file
  • initialCapacity initial capacity for the internal ParticleEffectPool. Half of max is probably reasonable.
  • max max number of particle effects of this type that could be active at once.

For example:

BUBBLES("particles/trail.p", 2, 4)

ParticleService

The primary class that manages particle effects is the ParticleService class.

You can retrieve this service from the service locator with ServiceLocator.getParticleService().

The ParticleService maintains object pools for each particle effect. These pools reduce garbage collector usage if particle effects were used heavily as described here.

To play a particle effect at a location, you can use the playEffect function. You will need to pass in the particle effect type along with world coordinates. This will play the particle effect at that location until it completes or until you call the dispose() or allowCompletion() methods of the returned ParticleEffectRenderer.

Example

To play the DAMAGE10 particle effect at the position (1.2, 1.5) in world coorindates, you can use the following:

ServiceLocator.getParticleService().playEffect(ParticleService.ParticleType.DAMAGE10, new Vector2(1.2f, 1.5f));

ParticleEffectRenderer

The ParticleEffectRenderer is a wrapper of ParticleEffect that facilitates drawing the particle effect to the screen.

To check if the ParticleEffectRenderer is still valid, i.e. the underlying ParticleEffect hasn't completed yet, you can use the isValid() method.

For further control, you can access the underlying LibGDX ParticleEffect using getEffect(). This will be null if isValid() returns false.

To terminate the particle effect programmatically you can either call the dispose() method to immediately stop displaying all particles or you can call the allowCompletion() method which will stop the spawn of new particles but let the particles that are currently on the screen finish their movement.

ParticleEffectComponent

If you want to make a particle effect to follow an entity, you can use the ParticleEffectComponnent.

Example

To play the BUBBLES particle effect that follows the maze game player, you can use the following:

Entity player = new Entity().addComponent(new ParticleEffectComponent(ParticleService.ParticleType.BUBBLES));

You can also control this particle effect component with the following:

  • forceEmit() will force the particle effect to restart emission.
  • emit() will cause the particle effect to start emitting again if it is completed.
  • allowCompletion() will cause the particle affect to stop emitting particles, but will still render previously emitted particles until completion.
  • stop() causes the particle effect to stop emitting and removes all existing particles immediately.

The particle effect is automatically stopped when the entity is disposed.