Tutorial 1: Our first particle system - tiagodinis/GParticles GitHub Wiki

In this tutorial, we'll learn how to set up a simple particle system with GParticles. It's assumed the GParticles repo has just been downloaded and had no prior change before this tutorial.

Starting from the "/App" folder location, we create another folder named "/projects/Tutorial_1" and, inside it, the project definition file, which we'll name "Tutorial_1.xml". After opening the file, we add a project and resources tag, required in every GParticles project. Since we are making a basic particle system, we'll use the prefab attribute to reference a file that holds the default resources like so:

<project>
    <resources prefab="prefabs/resources/defaultResources.xml" />
</project>

Most of the time, we'll define our project resources using a prefab, since they rarely change between particle systems and its just so easy. Even so, keep in mind that we are able to add more resources on top of the ones we referenced in the prefab file. The prefab attribute page has some examples of this functionality.

The next step is defining the particle system itself. We add a psystem tag with a name attribute, and two other required tags inside it: properties and events.

    <psystem name="simple">
        <properties>
        </properties>

        <events>
        </events>
    </psystem>

It is important to note that both of these work as containers for other project configurations and allow the use of a prefab attribute. Starting with the properties, we add the position, rotation, scale and lifetime tags. To increase the maximum number of particles in our system ("defaultResources.xml" sets it to 10), we'll use an override tag and change the value of the uniform maxParticles to 500.

        <properties>
            <position x=0 y=0 z=-5 />
            <rotation x=1 y=0 z=0 angle=0 />
            <scale x=1 y=1 z=1 />
            <lifetime value=5 unit="seconds"/>
        </properties>

        <override type="uniform" name="maxParticles" value=500 />

Because working with events is a bit out of scope for this tutorial, we'll just use prefabs for all of them, making sure the prefab path is exactly like the one below:

        <events>
            <emission prefab="prefabs/emission/simpleEmissionPrefab.xml" />

            <update prefab="prefabs/update/simpleUpdatePrefab.xml" />

            <render prefab="prefabs/render/simpleRenderPrefab.xml" />
        </events>

All that is left for us to do now is setting the GParticles output window dimensions (through the GPDATA singleton) and loading our project particle systems into the GPARTICLES singleton. Then, to perform one iteration of particle data processing, we call the processParticles function in our application main loop, passing in the matrices we find necessary for the scene (in our case, the projection and view matrix).

GPDATA.setWindowDimensions(1024, 576);

GPARTICLES.loadProject("projects/Tutorial_1/Tutorial_1.xml");

while(!quit)
{
	...

	float windowRatio = GPDATA.getWindowWidth() / GPDATA.getWindowHeight();
	glm::mat4 projection = glm::perspective(45.0f, windowRatio, 0.1f, 100.0f);

	GPARTICLES.processParticles(glm::mat4(), c.getViewMatrix(), projection);

	...
}

Running the project we should be able to see something like this:

There you go, easy like Sunday morning. If, however, you were unable to get the same result, be sure to take a look at the final xml file here.

Exercises:

  • Try creating a prefab for your particle system properties (check the prefab attribute page if you haven't already).
  • After exploring the properties XML documentation, can you alter the current particle system so that it dies after 10 seconds?
⚠️ **GitHub.com Fallback** ⚠️