Castler at 03:17, 6 January 2014

2014-01-06T03:17:21Z

BDota at 14:59, 29 September 2013

2013-09-29T14:59:37Z

Castler at 02:51, 26 August 2013

2013-08-26T02:51:44Z

Castler at 01:48, 26 August 2013

2013-08-26T01:48:16Z

Castler: Created page with "Particle effects can be used to add pizzazz to your game. There are two parts to adding particles: invoking the particles from your main Lua code and actually defining them. ..."

2013-07-19T03:24:27Z

Created page with "Particle effects can be used to add pizzazz to your game. There are two parts to adding particles: invoking the particles from your main Lua code and actually defining them. ..."

New page

Particle effects can be used to add pizzazz to your game. There are two parts to adding particles: invoking the particles from your main Lua code and actually defining them. We'll cover invoking particle effects first, since it's considerably simpler, and you'll want to be able to invoke your new effects to test them out and tune their parameters.

= Invoking Particles =

Assuming your particle effect is named "my_particle.lua" (see [[#Defining Particles|below]], there are a few main options for invoking it. (Other alternatives also exist for more specialized circumstances.)

== On the map ==

The [http://te4.org/docs/t-engine4/1.0.0/modules/engine.Map.html#_M:particleEmitter Map.particleEmitter function] can add a particle effect to the map. For example, if a talent should display an effect centered on the user, add the following code to your talent's <code>action</code> function:

game.level.map:particleEmitter(self.x, self.y, 1, "my_particle")

Make sure that your particle effect limits how many particles it generates; otherwise, it can run forever.

== On an entity ==

A long-lasting particle effect can be added to an entity with [http://te4.org/docs/t-engine4/1.0.0/modules/engine.Entity.html#_M:addParticles Entity.addParticles] and removed with [http://te4.org/docs/t-engine4/1.0.0/modules/engine.Entity.html#_M:removeParticles Entity.removeParticles]. For example, to associate a particle effect with a status condition, add the following to the appropriate <code>newEffect</code> block in your <code>timed_effects.lua</code>:

activate = function(self, eff)
eff.particle = self:addParticles(Particles.new("my_particle", 1))
end,
deactivate = function(self, eff)
self:removeParticles(eff.particle)
end,

== As a projectile ==

See [http://te4.org/docs/t-engine4/1.0.0/modules/engine.interface.ActorProject.html ActorProject].

== Testing your particle effects ==

Note that particle effects files are loaded ''every time'' they're invoked. This makes it very easy to test your particles: make up a talent that invokes the particles, give it no resource cost and no cooldown, and invoke it as much as you want as you tweak the particle parameters.

= Defining Particles =

To define a new particle effect, create a Lua file under your module's <code>data/gfx/particles</code> directory.

The ToME source code has a huge set of existing particle effects under [http://git.net-core.org/darkgod/t-engine4/tree/master/game/modules/tome/data/gfx/particles game/modules/tome/data/gfx/particles], so you can look there to see how particular effects are implemented.

== Basic concepts ==

Particle effects are processed at 30 frames per second (regardless of the T-Engine's actual frame rate).

A particle effect is a fragment of Lua code that returns the following:

# A table of [[#parameters|parameters]] for each particle. This table can define parameters directly, or it can contain a <code>generator</code> function that returns a table of parameters each time it's invoked.
# An emitter function. This function is called every frame (i.e., 30 times a second). Its main job is to call <code>self:ps:emit(N)</code> (where N is the number of particles to generate for that frame) as appropriate.
# (Optional) A number giving the maximum number of particles that the system will handle for this particle effect. Setting this too high will slightly hurt performance.
# (Optional) A string giving an image filename (minus extension) to load and use in place of the standard dot or spherical image.
# (Optional) A boolean that can be set to cause the particle system to not be automatically deleted when no more particles exist. Use with care.

Under normal conditions, a particle system will be automatically deleted when no more particles exist. The emitter function often limits itself to only running a certain number of times to ensure that particle systems don't go on forever.

Some basic trigonometry may be helpful to convert between x, y coordinates and angles on a circle.

== Parameters ==

Particle effect code can return a table of parameters directly for use with the T-Engine's simple generator, or it can return a generator function.

=== Simple generator ===

A table for use with the simple generator might look like this:

<pre>
return {
base = 1000,

angle = { 0, 360 }, anglev = { 2000, 4000 }, anglea = { 200, 600 },

life = { 5, 10 },
size = { 3, 6 }, sizev = {0, 0}, sizea = {0, 0},

r = {0, 0}, rv = {0, 0}, ra = {0, 0},
g = {80, 200}, gv = {0, 10}, ga = {0, 0},
b = {0, 0}, bv = {0, 0}, ba = {0, 0},
a = {255, 255}, av = {0, 0}, aa = {0, 0},
}
</pre>

Note that each value is given as a pair of numbers; these give the minimum and maximum values for the RNG to randomly generate each particle. Also note that colors (r, g, b, and a) range from 0 to 255. Only integers are permitted.

The simple generator is fairly restrictive; it's only really suitable for particles moving outwards from a central point.

=== Generator function ===

The same particle effect expressed as a generator function would look like this: (UNTESTED)

<pre>
return { generator = function()
return {
trail = 0,

life = rng.range(5, 10),
size = rng.range(3, 6), sizev = 0, sizea = 0,

x = 0, xv = 0, xa = 0,
y = 0, yv = 0, ya = 0,
dir = math.rad(rng.range(0, 360)), dirv = 0, dira = 0,
vel = rng.range(2, 4), velv = rng.range(0.2, 0.6), vela = 0,

r = 0, rv = 0, ra = 0,
g = rng.range(80, 200)/255, gv = rng.range(0, 10)/255, ga = 0,
b = 0, bv = 0, ba = 0,
a = 1, av = 0, aa = 0
}
end }
</pre>

The generator function invokes the RNG itself and returns floating point numbers.

=== Parameter values ===

Several parameters have ...v and ...a values. These give velocity and acceleration for that value. Each frame, velocity is added to the base value, then acceleration is added to velocity (causing velocity to change for future frames). For example:

r = 1, rv = -0.1, ra = 0
g = 0, gv = 0, ga = 0,
b = 0, bv = 0, ba = 0

starts out solid red and fades to black over 10 frames.

As another example:

y = 0, yv = 0, ya = -0.4

creates a particle that is initially motionless but starts moving up faster and faster.

Details on values:

<table class="wikitable">
<tr>
<td colspan=2>'''''General settings'''''</td>
</tr>
<tr>
<td>life</td>
<td>Number of frames for which the particle will exist</td>
</tr>
<tr>
<td>size, sizev, sizea</td>
<td>Size of the particle</td>
</tr>
<tr>
<td colspan=2>'''''Simple generator only'''''</td>
</tr>
<tr>
<td>base</td>
<td>All velocity and acceleration values are divided by this before being processed (since the default generator can't take fractional values directly).</td>
</tr>
<tr>
<td>angle, anglev, anglea</td>
<td>Angle along which the particle should move, in degrees, and velocity and acceleration at which it should move along that angle. Generator functions can use dir and vel for a similar effect.</td>
</tr>
<tr>
<td colspan=2>'''''Generator function only'''''</td>
</tr>
<tr>
<td>trail</td>
<td>Used to draw trails from one particle to another</td>
</tr>
<tr>
<td>x, xv, xa</td>
<td>x coordinate, relative to the center of the particle system</td>
</tr>
<tr>
<td>y, yv, ry</td>
<td>y coordinate, relative to the center of the particle system</td>
</tr>
<tr>
<td>dir, dirv, dira</td>
<td>Angle along which the particle should move, in radians. dirv and dira give the rate at which that angle should change.</td>
</tr>
<tr>
<td>vel, velv, vela</td>
<td>Velocity to move along the angle given by dir, and the "velocity of velocity" (i.e., acceleration) and the "acceleration of velocity." Movement can be done via xv, xa, yv, ya or dir, vel (or both at the same time).</td>
</tr>
<tr>
<td colspan=2>'''''Color'''''</td>
</tr>
<tr>
<td>r, rv, ra</td>
<td>Red component</td>
</tr>
<tr>
<td>g, gv, ga</td>
<td>Green component</td>
</tr>
<tr>
<td>b, bv, ba</td>
<td>Blue component</td>
</tr>
<tr>
<td>a, av, aa</td>
<td>Alpha component. 255 (for the simple generator) or 1 (for a generator function) means fully opaque, 0 means fully transparent.</td>
</tr>

@@ Line 195: / Line 195: @@
          <td>Alpha component.  255 (for the simple generator) or 1 (for a generator function) means fully opaque, 0 means fully transparent.</td>
      </tr>
 {{Module Guides}}

← Older revision		Revision as of 14:59, 29 September 2013
Line 195:		Line 195:
	<td>Alpha component. 255 (for the simple generator) or 1 (for a generator function) means fully opaque, 0 means fully transparent.</td>		<td>Alpha component. 255 (for the simple generator) or 1 (for a generator function) means fully opaque, 0 means fully transparent.</td>
	</tr>		</tr>
		+
		+	{{Module Guides}}

@@ Line 3: / Line 3: @@
 = Invoking Particles =
-Assuming your particle effect is named "my_particle.lua" (see [[#Defining Particles|below]], there are a few main options for invoking it.  (Other alternatives also exist for more specialized circumstances.)
+Assuming your particle effect is named "my_particle.lua" (see [[#Defining Particles|below]]), there are a few main options for invoking it.  (Other alternatives also exist for more specialized circumstances.)
 == On the map ==
@@ Line 26: / Line 26: @@
 == As a projectile ==
-See [http://te4.org/docs/t-engine4/1.0.0/modules/engine.interface.ActorProject.html ActorProject].
+See [http://te4.org/docs/t-engine4/1.0.0/modules/engine.interface.ActorProject.html ActorProject].  Specifically:
 == Testing your particle effects ==

@@ Line 155: / Line 155: @@
      <tr>
          <td>trail</td>
-         <td>Used to draw trails from one particle to another</td>
+         <td>Used to draw trails from one particle to another.  trail is 0-based, unlike most values in T-Engine.</td>
      </tr>
      <tr>

Particle Effects - Revision history

Castler at 03:17, 6 January 2014

BDota at 14:59, 29 September 2013

Castler at 02:51, 26 August 2013

Castler at 01:48, 26 August 2013

Castler: Created page with "Particle effects can be used to add pizzazz to your game. There are two parts to adding particles: invoking the particles from your main Lua code and actually defining them. ..."