Particles engine - jjppof/goldensun_html5 GitHub Wiki

This article will cover how to configure an object that will describe an emission of particles. It contains properties explanation that will describe the behavior of your particles for an emission that the user wants to make and tell the particles engine how to achieve it.

Particles engine object properties

data [object]: the object that will describe the behavior of your particles after they are emitted.
- [key name] [object]: the key of this object will be the key name of the particles data that will be passed to emitter object emitter_data_key property. This particle data object will contain the info to describe the particles' behavior. Check Particle properties section.
zones [object]: the object that will describe the geometric zones that particles can interact with.
- [key name] [object]: the key of this object will be the key name of the zones data that will be passed to emitter object zone_key property, for example. This zone data object will contain the info to describe the zone shape. Check Zone properties section.
emitters [array]: the array of objects that will describe how the particles will be emitted. You can have multiple emissions objects in this array, each object will describe a particular emission. Check Emitter properties section to see how to fill the emitters object.
emission_delay [number]: the amount of time all emitters will wait before start emitting in ms. Default is 0.
emission_finish [number]: the amount of time the engine will wait to kill all the emitters. Required property.
group_type [string]: only valid if emitting particles in overworld. Will tell if the particles should be in the layers below npcs ("lower"), in the same layer ("middle"), or above npcs ("over"). Optional property.

Zone properties

Zone are geometric regions in the canvas that particles can interact with.

type [string]: the type of the zone. It can be "rectangle", "line", "circle", "ellipse", "point". Required property.
radius [number]: the circle zone radius. Required property for circle type.
width [number]: the width of the rectangle or ellipse. Required property for rectangle and ellipse types.
height [number]: the height of the rectangle or ellipse. Required property for rectangle and ellipse types.
points [array]: array of objects containing the points info. Required property for line and point type. Line type demands two points.
- x [number|string]: the x position of the point. In case of battle, you can set it as the following strings: "caster", to get the x caster position; "targets", to get the average x targets position.
- y [number|string]: the y position of the point. In case of battle, you can set it as the following strings: "caster", to get the y caster position; "targets", to get the average y targets position.
- shift_x [number]: the shift in x axis relative to the x position property. Useful when x is set as string. Default is 0.
- shift_y [number]: the shift in y axis relative to the y position property. Useful when y is set as string. Default is 0.

Particle properties

Properties that will define how a particle will behave and look after its emission. Some properties can assume specific types described here.

image [string]: if it's a sprite particle, set the sprite key name. If in battle, the sprite key name will probably be "<ability key name>_battle_animation", example: "frost_battle_animation".
animations [object]: use this property to setup the animations of the particle. A particle can assume different animations.
- [animation key name] [object]: use this property to setup a particular animation of a particle. Set the animation key name as this object key.
  - frameRate [number]: the animation frame rate.
  - loop [boolean]: if the animation will loop or not.
  - yoyo [boolean]: if true, the animation will loop in a direct and reverse way.
  - frames [object]: object that will config how the frame names should be interpreted by the engine.
    - start [number]: the initial frame index.
    - stop [number]: the final frame index.
    - zeroPad [number]: the zero pad number to be added to the index.
    - prefix [string]: the frame name prefix string.
    - sufix [string]: the frame name sufix string.
play [list]: the list of animations that will be played. Default is to randomly play all of them.
playOnKill [string]: set an animation name that will be played on particle kill.
frame [list]: the list of frame names that can be set for a particle from the image you set in image property.
pixelSize [number]: if particles are pixels, set their size.
pixelReducingFactor [number]: only valid if pixelSize is set. The size reducing factor throughout the lifespan.
blendMode [string]: the particle blend mode. It can be "SCREEN" or "NORMAL".
lifespan [option 1 | option 2]: the life of this particle in milliseconds.
delay [option 1 | option 2]: a delay before this particle becomes active in milliseconds.
anchorX [number]: the anchor point x component for this particle (from 0 to 1).
anchorY [number]: the anchor point y component for this particle (from 0 to 1).
scale [option 1 | option 2 | option 3]: this parameter is a convenience which combines scaleX and scaleY. Controls the scale of the particle.
scaleX [option 1 | option 2 | option 3]: controls the scale x component of the particle.
scaleY [option 1 | option 2 | option 3]: controls the scale y component of the particle.
velocity [option 1 | option 4]: this parameter is a convenience which combines vx and vy. Controls the velocity of the particle.
vx [option 1 | option 2 | option 3]: controls the velocity x component of the particle.
vy [option 1 | option 2 | option 3]: controls the velocity y component of the particle.
ax [option 1 | option 2 | option 3]: controls the acceleration x component of the particle.
ay [option 1 | option 2 | option 3]: controls the acceleration y component of the particle.
rotation [option 1 | option 2 | option 3]: controls the rotation of the particle. Values in deg.
red [option 1 | option 2 | option 3]: controls the red channel of the pixel particle. Values 0 to 255.
green [option 1 | option 2 | option 3]: controls the green channel of the pixel particle. Values 0 to 255.
blue [option 1 | option 2 | option 3]: controls the blue channel of the pixel particle. Values 0 to 255.
alpha [option 1 | option 2 | option 3]: controls the alpha channel of the particle. Values 0 to 1.
sendToBack [boolean]: if true, will send the particle to back in current group.
bringToFront [boolean]: if true, will bring the particle to front in current group.
hsv [option 1 | option 2 | option 3]: controls the hue channel of the particle. Values in deg.
target [object]: particles can reach specific targets like a specific point or zones.
- x [number]: in case of a specific point, the x location.
- y [number]: in case of a specific point, the y location.
- zone_key [string]: the zone key corresponding to the zone that will anchor on top of x and y location.

Particle properties value

Many particle properties can assume one of the following value types.

Option 1:

[property]: [number]: a raw number.

Option 2:

[property]: [object]: random number between min & max.
- min: [number]: the min value.
- max: [number]: the max value.

Option 3:

[property]: [object]: the value will follow this equation: initial + (value + delta) * control(time). time is a variable that varies between 0 and particle lifespan, control is in function of it.
- initial: [number|object]: it will be added to the calculation every time this parameter is used. If an object, then it can be like option 2 format.
- value: [number]: the current base value of the parameter, when this parameter is used, an equation is applied to determine the actual value. If an object, then it can be like option 2 format.
- delta: [number]: it will be added onto the value every time the particle is updated. If an object, then it can be like option 2 format.
- control: [list|string]: it can be the following strings: "linear", "reverse", "yoyo". It can also be a list of points that will multiply value at the specified time point. Each point is an object like below. When setting control, you must at least set a point for x = 0.0 and x = 1.0, basically the beginning and end points of the particle lifespan.
  - x: [number]: the time point in percentage of lifespan of the particle. 0 is when the particle is just emitted, 1 is the end of lifespan.
  - y: [number]: the factor that will multiply the value.

Option 4:

[property]: [object]: sets a value in radial format. The value will follow this equation: initial + random(arc.min, arc.max) * control(time). time is a variable that varies between 0 and particle lifespan, control is in function of it.
- radial: [object]: the start and end arc values.
  - arcStart: [number]: the initial arc angle value in deg.
  - arcEnd: [number]: the final arc angle value in deg.
- value: [number]: the current base value of the parameter, when this parameter is used an equation is applied to determine the actual value. If an object, then it can be like option 2 format.
- control: [list|string]: see option 3 control section.

Emitter properties

Emitter is the source location of the particles. You can also configure how the particles will be generated and emitted.

x [number|string|object]: the x position of the emitter. In case of battle, you can set it as the following strings: "caster", to get the x caster position; "targets", to get the average x targets position. In overworld, you can also set this as an object specifying it as an event value, check event_value property in "set_value" Game Event to see how to fill this object. Required property.
y [number|string|object]: the x position of the emitter. In case of battle, you can set it as the following strings: "caster", to get the x caster position; "targets", to get the average x targets position. In overworld, you can also set this as an object specifying it as an event value, check event_value property in "set_value" Game Event to see how to fill this object. Required property.
shift_x [number]: the shift in x axis relative to the x position property. Useful when x is set as string. Default is 0.
shift_y [number]: the shift in y axis relative to the y position property. Useful when y is set as string. Default is 0.
position [string]: only valid for battle. Required property if it's for battle. It can be "behind" if the sprite is behind caster and target groups. "between" if the sprite is between the groups. Or "over" if the sprite is over the two groups.
zone_key [string]: the zone id that this emitter will use to emit the particles. The zone anchor point will be placed on top of x and y properties. If no zone is passed, the emission will start from emitter position point.
random_in_zone [boolean]: if a zone is set, this will emit the particles from random locations within the zone.
bring_to_top [boolean]: if true, will move emitter to the top position on the group it's created.
send_to_back [boolean]: if true, will move emitter to the bottom position on the group it's created.
render_type [string]: the type of particle this emitter will emit. Set "pixel" for "bullet" particle types of a solid color. Set "sprite" if the particles will come from a sprite. Required property.
emitter_data_key [string]: the key name of the data object defined in particle "data" property that will tell which particle describer specification this emitter will use. Required property.
show_trails [boolean]: if the particles will render trails while they move. Optional property. Default is false.
trails_clear_factor [number]: the trail density that a moving particle will render. This property is only valid if show_trails is set to true. Optional property. Set values bigger than zero.
pixel_size [number]: the size of the pixel particle type. This property is only valid if render_type is set to "pixel". Optional property. Set values bigger than one.
pixel_reducing_factor [number]: the reducing factor that will be applied to the particle. This property is only valid if render_type is set to "pixel". Optional property. Set values bigger than one.
pixel_is_rect [boolean]: if true, the pixel will be rendered as a square, otherwise a circle. This property is only valid if render_type is set to "pixel". Optional property.
render_white_core [boolean]: if true, it will render a white core inside the pixel particle. This property is only valid if render_type is set to "pixel". Optional property.
core_custom_color [string]: you can set a custom core color in the format "rgb(r,g,b,a)" where r, g, b vary between 0 and 255 and a between 0 and 1. This property is only valid if render_white_core is set to true. Optional property.
core_size_factor [number]: this value will multiply the pixel size of the particle to determine the size of the core. This property is only valid if render_white_core is set to true. Optional property.
particles_display_blend_mode [string]: the blend mode of the particles, it can be set as "screen" or "normal". Optional property. Default is "normal".
total [number]: the number of particles that will be emitted. Default is 1.
repeat [number]: the emitter will repeat the emission of the number of particles set in total by the number of times set in this property spaced out by the interval time set in frequency. Default is 1.
frequency [number]: the interval time between each emission in ms.

Emitter `total`, `repeat`, and `frequency` properties explanation

On its own, a single emission setup will emit just one particle. But let's say you want to emit 30 particles, then you can use the total property:

{ total: 30 }

This will emit 30 particles all at the same time. A more common requirement is to emit the particles over a period of time. For this, you can use the repeat property:

{ repeat: 29, frequency: 500 }

The line above will emit 30 particles as well, but this time they will be spaced out by 500ms each (as controlled by the frequency). Why is the repeat value 29? It’s because emit always emits 1 particle as default, so you want to repeat that process another 29 times, giving you 30 emissions in total. You can combine repeat and total together:

{ total: 4, repeat: 9, frequency: 2500 }

Here, the emitter will emit 4 particles at once (the total property), then it will wait for 2.5 seconds (frequency) and emit another 4 particles. This process will repeat 9 times. By the end of it, the emitter will have emitted 40 particles in total (4 * 10).