# JME 3 Tutorial (12) - Hello Effects

Previous: Hello Audio, Next: Hello Physics

When you see one of the following in a game, then a particle system is likely behind it:

- Fire, flames, sparks;
- Rain, snow, waterfalls, leaves;
- Explosions, debris, shockwaves;
- Dust, fog, clouds, smoke;
- Insects swarms, meteor showers;
- Magic spells.

These things typically cannot be modeled by meshes. In very simple terms:

- The difference between an explosion and a dust cloud is the speed of the effect.
- The difference between flames and a waterfall is the direction and the color of the effect.

Particle effects can be animated (e.g. sparks, drops) and static (strands of grass, hair). Non-particle effects include bloom/glow, and motion blur/afterimage. In this tutorial we will look at animated particles (com.jme3.effect).

## Sample Code

    package jme3test.helloworld;

    import com.jme3.app.SimpleApplication;
    import com.jme3.effect.ParticleEmitter;
    import com.jme3.effect.ParticleMesh;
    import com.jme3.material.Material;
    import com.jme3.math.ColorRGBA;
    import com.jme3.math.Vector3f;

    /** Sample 11 - how to create fire, water, and explosion effects. */
    public class HelloEffects extends SimpleApplication {

      public static void main(String[] args) {
        HelloEffects app = new HelloEffects();
        app.start();
      }

      @Override
      public void simpleInitApp() {

        ParticleEmitter fire = new ParticleEmitter("Emitter", ParticleMesh.Type.Triangle, 30);
        Material mat_red = new Material(assetManager, "Common/MatDefs/Misc/Particle.j3md");
        mat_red.setTexture("Texture", assetManager.loadTexture("Effects/Explosion/flame.png"));
        fire.setMaterial(mat_red);
        fire.setImagesX(2); fire.setImagesY(2); // 2x2 texture animation
        fire.setEndColor(  new ColorRGBA(1f, 0f, 0f, 1f));   // red
        fire.setStartColor(new ColorRGBA(1f, 1f, 0f, 0.5f)); // yellow
        fire.setInitialVelocity(new Vector3f(0, 2, 0));
        fire.setStartSize(1.5f);
        fire.setEndSize(0.1f);
        fire.setGravity(0);
        fire.setLowLife(0.5f);
        fire.setHighLife(3f);
        fire.setVelocityVariation(0.3f);
        rootNode.attachChild(fire);

        ParticleEmitter debris = new ParticleEmitter("Debris", ParticleMesh.Type.Triangle, 10);
        Material debris_mat = new Material(assetManager, "Common/MatDefs/Misc/Particle.j3md");
        debris_mat.setTexture("Texture", assetManager.loadTexture("Effects/Explosion/Debris.png"));
        debris.setMaterial(debris_mat);
        debris.setImagesX(3); debris.setImagesY(3); // 3x3 texture animation
        debris.setRotateSpeed(4);
        debris.setSelectRandomImage(true);
        debris.setInitialVelocity(new Vector3f(0, 4, 0));
        debris.setStartColor(new ColorRGBA(1f, 1f, 1f, 1f));
        debris.setGravity(6f);
        debris.setVelocityVariation(.60f);
        rootNode.attachChild(debris);
        debris.emitAllParticles();

      }
    }

You should see an explosion that sends debris flying, and a fire. More example code

### Texture Animation and Variation

Start by choosing a material texture for your effect. If you provide the emitter with a set of textures (see image), it can use them either for variation (random order), or as animation steps (fixed order).

Setting emitter textures works just as you have already learned in previous chapters. This time we use the `Particle.j3md` default material. In the following example, we have a closer look at the Debris effect.

        ...
        Material debris_mat = new Material(assetManager, "Common/MatDefs/Misc/Particle.j3md");
        debris_mat.setTexture("Texture", assetManager.loadTexture("Effects/Explosion/Debris.png"));
        debris.setMaterial(debris_mat);
        debris.setImagesX(3); // columns
        debris.setImagesY(3); // rows
        debris.setSelectRandomImage(true);
        ...

1. Load the texture in the emitter's material.
2. Tell the Emitter into how many animation steps (x*y) the texture is divided. 1x1 is default.
3. Optionally, tell the Emitter whether the animation steps are to be at random, or in order.

As you see in the debris example, texture animations improve effects because each "flame" or "piece of debris" looks different. Also think of electric or magic effects, where you can create very interesting animations by using an ordered morphing series of lightning bolts; or flying leaves or snow flakes, for instance.

### Default Particle Textures

The following effect textures are some of the example textures included in `test-data.jar`.

Texture Path | Dimension | Preview
--- | --- | ---
Effects/Explosion/Debris.png | 3*3 |
Effects/Explosion/flame.png | 2*2 |
Effects/Explosion/shockwave.png | 1*1 |
Effects/Explosion/smoketrail.png | 1*3 |
Effects/Smoke/Smoke.png | 1*15 |

Copy them into you `assets/Effects` directory to use them.

## Creating Custom Textures

For your game, you will likely create custom textures. Look at the fire example again.

        ParticleEmitter fire = new ParticleEmitter("Emitter", ParticleMesh.Type.Triangle, 30);
        Material mat_red = new Material(assetManager, "Common/MatDefs/Misc/Particle.j3md");
        mat_red.setTexture("m_Texture", assetManager.loadTexture("Effects/Explosion/flame.png"));
        fire.setMaterial(mat_red);
        fire.setImagesX(2); // columns
        fire.setImagesY(2); // rows
        fire.setEndColor(  new ColorRGBA(1f, 0f, 0f, 1f));   // red
        fire.setStartColor(new ColorRGBA(1f, 1f, 0f, 0.5f)); // yellow

- Black parts of the image will be rendered transparent.
- White/gray parts of the image are transparent and will be colored.
- You set the color (here, a gradient from yellow to red) in the code.
- By default the animation will be played in order (?) and loop.

Create a grayscale texture in a graphic editor, and save it to your `assets/Effects` directory. If you split up one image file into x*y animation steps, make sure each animation step is of equal size–just as you see in the examples here.

### Emitter Parameters

A particle system is always centered around an emitter.

Use the `setShape()` method to change the EmitterShape:

- EmitterPointShape(Vector3f.ZERO) – default shape
- EmitterSphereShape(Vector3f.ZERO,2f)
- EmitterBoxShape(new Vector3f(-1f,-1f,-1f),new Vector3f(1f,1f,1f))

Example: `emitter.setShape(new EmitterPointShape(Vector3f.ZERO));`

You create different effects by changing the emitter parameters:

Parameter | Method (default value) | Description
--- | --- | ---
number | `setNumParticles()` | The maximum number of particles visible at the same time. Value is specified by user in constructor.
velocity | `setInitialVelocity()` (Vector3f.ZERO) | You must specify a vector how fast particles should move and it which start direction.
direction | `setVelocityVariation()` (0.2f) `setFacingVelocity()` (false) `setRandomAngle()` (false) `setFaceNormal()` (Vector3f.NAN) `setRotateSpeed()` (0f) | Optional accessors that control in which direction particles face when flying.
lifetime | `setLowLife()` (3f) `setHighLife()` (7f) | Minimum and maximum time period before particles fade.
emission rate | `setParticlesPerSec()` (20) | How many new particles are emitted per second.
color | `setStartColor()` `setEndColor()` (gray) | Set to two different colors for gradient effects, or to same color.
size | `setStartSize()` (0.2f) `setEndSize()` (2f) | Set to two different values for shrink/grow effect, or to same size.
gravity | `setGravity()` (0.1f) | Whether particles falls down eventually. Set to 0f for zero-g effects.

You can find details about effect parameters in the user guide. Add and modify one paramter at a time, and try different values until you get the effect you want. Tip: Use the jMonkeyPlatform SceneComposer to preview effects settings (instructions: TODO).

## Exercise

Can you "invert" the campfire into a small waterfall?

- Change the Red and Yellow color to Cyan and Blue…
- Invert the velocity vector (direction) by using a negative number…
- Swap start and end size…
- Activate gravity by setting it to 1…

## Conclusion

You have learned that many different effects can be created by changing the parameters and textures of one general emitter object.

Now we move on to the next exciting chapter – the simulation of physical objects. Let's shoot some cannon balls at a brick wall!

beginner, documentation, intro, transparency, effect

view online version