GML Functions: Particle Types

A particle type describes the shape, color, motion, etc. of a particular kind of particles. You need to define a particle type only once in the game. After this it can be used in any particle system in the game. Particle types have a large number of parameters that can be used to change all aspects of it. Setting these right you can create almost any effect you like. We will discuss the settings below.

Creating Particle Types
A number of routines are available to create new particle types and destroy them again:


 * part_type_create Creates a new particle type. It returns the index of the type. This index must be used in all calls below to set the properties of the particle type. So you will often store it in a global variable.
 * part_type_destroy(ind) Destroys particle type ind. Call this if you don't need it anymore to save space.
 * part_type_exists(ind) Returns whether the indicated particle type exists.
 * part_type_clear(ind) Clears the particle type ind to its default settings.

The Shape of a Particle
A particle has a shape. This shape is indicated by a sprite. You can use any sprite you like for your particles but there are 15 built-in sprites. These are all 64x64 in size and have alpha values set such that they nicely blend with the background. They are indicate by the following constants:


 * pt_shape_pixel 
 * pt_shape_disk 
 * pt_shape_square 
 * pt_shape_line 
 * pt_shape_star 
 * pt_shape_circle 
 * pt_shape_ring 
 * pt_shape_sphere 
 * pt_shape_flare 
 * pt_shape_spark 
 * pt_shape_explosion 
 * pt_shape_cloud 
 * pt_shape_smoke 
 * pt_shape_snow 

You set the shape using the following function:


 * part_type_shape(ind,shape) Sets the shape of the particle type to any of the constants above (default is pt_shape_pixel).

You can also use your own sprite for the particle. If the sprite has multiple subimages you can indicate what should be done with them. You can pick a random one, animate the sprite, start at the beginning of the animation or at a random place, etc. You use the following function for this.


 * part_type_sprite(ind,sprite,animat,stretch,random) Sets your own sprite for the particle type. With animate you indicate whether the sprite should be animated (1) or not (0). With stretch (1 or 0) you indicate whether the animation must be stretched over the lifetime of the particle. And with random (1 or 0) you can indicate whether a random subimage must be choosen as starting image.

Once you have choosen the sprite for the particle type (either a default shape or your own) you can indicate the size of it. A size of 1 indicates the normal size of the sprite. A particle type can be defined such that all particles have the same size or have different sizes. You can indicate a range of sizes. Also, you can indicate whether the size should change over the lifetime of the particle and whether some wiggling in the size will happen, giving a blinking effect.


 * part_type_size(ind,size_min,size_max,size_incr,size_wiggle) Sets the size parameters for the particle type. You specify the minimum starting size, the maximum starting size, the size increase in each step (use a negative number for a decrease in size) and the amount of wiggling. (The default size is 1 and default the size does not change.)


 * part_type_scale(ind,xscale,yscale) Sets the horizontal and vertical scale. This factor is multiplied with the size. It is in particular useful when you need to scale differently in x- and y-direction.

The particles also have an orientation. Again the orientation can be the same for all particles, can be different, and can change over the lifetime of the sprite. The angles specify counter-clockwise rotations, in degrees.


 * part_type_orientation(ind,ang_min,ang_max,ang_incr,ang_wiggle,ang_relative) Sets the orientation angle properties for the particle type. You specify the minimum angle, the maximum angle, the increase in each step and the amount of wiggling in angle. (Default all values are 0.) You can also indicate whether the given angle should be relative (1) to the current direction of motion or absolute (0). E.g. by setting all values to 0 but ang_relative to 1, the particle orientation will precisely follow the path of the particle.

Color and Blending
Particles will have a color. There are different ways in which you can specify colors for a particle. The simplest way is to indicate a single color. You can also specify two or three colors between which the color of the particle is interpolated during its life time. For example, the particle can start white and become more and more black over its lifetime. Another possibility is that you indicate that the color of each particle must be different, picked from a range of colors. You can either give a range in red, green and blue, or a range in hue, saturation, and value. Default the color is white. When you use a sprite with its own colors, this is normally what you want and no color needs to be specified.


 * part_type_color1(ind,color1) Indicates a single color to be used for the particle.
 * part_type_color2(ind,color1,color2) Specifies two colors between which the color is interpolated.
 * part_type_color3(ind,color1,color2,color3) Similar but this time the color is interpolated between three colors that represent the color at the start, half-way, and at the end.
 * part_type_color_mix(ind,color1,color2) With this function you indicate that the particle should get a color that is a random mixture of the two indicated colors. This color will remain fixed over the lifetime of the particle.
 * part_type_color_rgb(ind,rmin,rmax,gmin,gmax,bmin,bmax) Can be used to indicate that each particle must have a fixed color but choosen from a range. You specify a range in the red, green, and blue component of the color (each between 0 and 255).
 * part_type_color_hsv(ind,hmin,hmax,smin,smax,vmin,vmax) Can be used to indicate that each particle must have a fixed color but choosen from a range. You specify a range in the hue saturation and value component of the color (each between 0 and 255).

Besides the color you can also give an alpha transparency value. The built-in particle shapes already have some alpha transparency but you can use these settings to e.g. make the particle vanish over its life time.


 * part_type_alpha1(ind,alpha1) Sets a single alpha transparency parameter (0-1) for the particle type.
 * part_type_alpha2(ind,alpha1,alpha2) Similar but this time a start and end value are given and the alpha value is interpolated between them.
 * part_type_alpha3(ind,alpha1,alpha2,alpha3) This time three values are given between which the alpha transparency is interpolated.

Normally particles are blended with the background in the same way as sprites. But it is also possible to use additive blending. This gives in particular a great effect for explosion.


 * part_type_blend(ind,additive) Sets whether to use additive blending (1) or normal blending (0) for the particle type.

Life and Death
Particles live for a limited amount of time, their lifetime. After this they disappear. Lifetime is measured in steps. You can indicate the lifetime (or a range of lifetimes) for each particle type. Particles can create new particles of different types. There are two ways for this. They can create new particles in each step or they can create particles when they die. Be careful that the total number of particles does not get too high.


 * part_type_life(ind,life_min,life_max) Sets the lifetime bounds for the particle type. (Default both are 100.)
 * part_type_step(ind,step_number,step_type) Sets the number and type of particles that must be generated in each step for the indicated particle type. If you use a negative value, in each step a particle is generated with a chance -1/number. So for example with a value of -5 a particle is generated on average once every 5 steps.
 * part_type_death(ind,death_number,death_type) Sets the number and type of particles that must be generated when a particle of the indicated type dies. Again you can use negative numbers to create a particle with a particular chance. Note that these particles are only created when the particle dies at the end of its life, not when it dies because of a destroyer (see below).

Particle motion
Particles can move during their lifetime. They can get an initial speed (or range of speeds) and direction, and the speed and direction can change over time. Also gravity can be defined that pulls the particles in a particular direction. The following functions exist for this:


 * part_type_speed(ind,speed_min,speed_max,speed_incr,speed_wiggle) Sets the speed properties for the particle type. (Default all values are 0.) You specify a minimal and maximal speed. A random value between the given bounds is chosen when the particle is created. You can indicate a speed increase in each step Use a negative number to slow the particle down (the speed will never become smaller than 0). Finally you can indicate some amount of wiggling of the speed.
 * part_type_direction(ind,dir_min,dir_max,dir_incr,dir_wiggle) Sets the direction properties for the particle type. (Default all values are 0.) Again you specify a range of directions (in counterclockwise degrees; 0 indicated a motion to the right). For example, to let the particle move in a random direction choose 0 and 360 as values. You can specify an increase in direction for each step, and an amount of wiggling.
 * part_type_gravity(ind,grav_amount,grav_dir) Sets the gravity properties for the particle type. (Default there is no gravity.) You specify the amount of gravity to be added in each step and the direction. E.g. use 270 for a downwards direction.