You may have heard something regarding new particle control commands in Lua, whether it be Lee's brief announcement about an extra command to attach particles to an entity or my own announcements and demos. Well these commands are in the Beta and will probably all be in a public release some time soon so I'm going to start in on a series of tutorial posts.

I'm going to aim this at the absolute complete beginner level:

What exactly is a 'particle'? Well in 3D engines a 'particle' is really just a small simple object that rather than being positioned by hand or by the physics interactions, is created on the fly and positioned according to a simple set of rules.

What does that mean in GG terms?
Currently a 'particle' in GG (to be precise a 'ravey_particle' as there are others ) is actually a 'camera orientated quad' or to put it another way a small flat square always facing the camera. Onto this is projected an image generated from a sprite sheet. The sprite sheet can contain many images which can either be played as an animation or simply have one selected at random.

But that's just a 'decal' isn't it?
Well yes, and no, it is the exact same principal as a 'decal' but a 'decal' is usually a statically positioned object (unless you move them about under script control as I've amply demonstrated in the past) and they are also usually quite detailed. A decal for example may be used for pasting a sign on a wall or something similar so needs to be high definition.
A 'particle' otoh can be just a small fuzzy blob (in fact for most fancy effects that is what works the best!), using an animated image is *not* the norm for most particle systems, particles are also designed to be used in multiples, many many multiples in most cases whereas a 'decal' is normally a single use beast.

So how does it work?
First you have to define an 'emitter', this is a particle generating object, all it does is pump out new particles.
There are really just two types of emitter (at least at the moment!) one type is attached to the player position, basically as the player moves around so does the emitter, the second type is attached to an entity, if the entity moves so does the emitter.
Once an emitter is defined it will start pumping out particles until it is destroyed but the way it pumps out the particles can be controlled via Lua commands, this means that by for example changing the frequency of the emitter or the max particles it can produce you can effectively switch it on and off under script control!

What would I use a particle emitter for?
One simple example would be to have smoke from a chimney, for a static building you could use a simple static decal, but what if you wanted to have a wind effect? Or maybe instead of a static chimney it is a vehicle smoke stack? In these cases (and just because it looks a lot better!) you can use a particle emitter.

To Be Continued:

Ok, so I mentioned that 'particles' are "created on the fly and positioned according to a simple set of rules", what exactly are these rules?
Each particle emitter that is created is first set up with a bunch of parameters controlling how the particles are emitted, here is a list of those parameters:
frequency : This is the rate at which new particles are created in milliseconds, so a value of 20 would mean the emitter will produce new particles every 1/50th of a second (or quicker that the period the human eye can actually distinguish!).

life : This is simply how long the particle should exist for, again in milliseconds.
offset : The position relative to the emitter position that a particle should start from.
speed : How fast the particle should move (and the direction as this is a vector).
scale : How big to display the particles.
rotation : The rotation speed of the particle (remember it is camera facing so this is +ve for clockwise -ve for anticlockwise).
alpha : How see-through the particle is (this is actually very important as we'll see later).
animspeed : Bit weird to get your head round to begin with, if you have 64 frames in the sprite sheet the a value of 1 would be 64 FPS, if you have 16 frames then 1 would be 16 FPS. If you wanted a 64 frame sheet to animate at 32 FPS then the value would be 0.5.

There are a couple of other control variables but before covering those I want to expand on the 'rules' I mentioned first.

For some of the variables above you don't specify a single value, what you do is specify a range of values and for each particle emitted the emitter chooses a random value between them.
For offset there is offsetMinX, offsetMinY, offsetMinZ, offsetMaxX, offsetMaxY and offsetMaxZ.
For example if you wanted a particle to be emitted above the emitter position by 200 units you could set offsetMinY and offsetMaxY to 200 and that will do the trick, but much more interesting is when you want to have the particles start somewhere above 200, say within 50 units, then you simply set offsetMinY to 200 and offsetMaxY to 250. Now each particle will pop into existance at a random position within the specified points.
(if using the 'player position' type of emitter and you set the offset values to -200, 200, -200, 200, 250, 200 then the particles would all pop into existance in a box above the players head, no matter where the player goes. Good for snow or rain or volcanic ash falls.)

Some variables have a 'start' and 'end' specification, for example if you specified scaleStartMin and scaleStartMax as 1 and scaleEndMin andscaleEndMax as 10 then the particles would all pop into existance as 1x1 square size and would grow to 10x10 square size at the endo of the life period.

To Be Continued.

Right back at the beginning I mentioned two 'types' of emitter, how do we select these types?
The (new) Lua command ParticlesAddEmitterEx() (don't blame me, Lee named it ) creates an emitter that is relative to an entity or an entity 'limbindex' (whatever that is, presumably useful for weapons?). The last 4 parameters for this command are entity, limbindex, particleimage, imageframe. If entity is set to -1 then the emitter will be 'player centric', i.e. the variables in the first 28 parameters are relative to th eplayer position, otherwise the specified entity id (and limbindex is specified) position is used.

Hold on a minute what are those last two all about? Well this command allows you to specify which image file to use and the number of frames it contains. There are 3 particle sheets loaded by default, 0 is 'flare', 1 is 'smoke' and 2 is 'flame', but that is a bit limiting so you can load your own sheets (or any of the others dotted around the gameguru files) using the Lua command:
ParticlesLoadImage( <path+file> , slot)

For example:
ParticlesLoadImage( "gamecore\\decals\\sparks\\decal.dds", 3 )
would load the 16 frame sparks decal into particleimage slot 3 so you could then specify a particle emitter using it.

If you need to allocate the first unused slot you would use:
local imageFile = ParticlesLoadImage( "gamecore\\decals\\sparks\\decal.dds" )

time for an example script.

Attach the attached to an an active entity, a crate iow .

To Be Continued.

Another example, this time of an emitter attached to an entity (attach it to a crate ).

Homework:
1) Both of these examples are using existing sprite sheets, try making your own and changing the scripts to load those.

2) Try changing the emitter parameters to create other effects.

3) Use any of the following Lua commands to change the emitter behaviour in real time:

ParticlesSetSpeed( emitterId, speedMinX, speedMinY, speedMinZ, speedMaxX, speedMaxY, speedMaxZ )

ParticlesSetOffset( emitterId, offsetMinX, offsetMinY, offsetMinZ, offsetMaxX, offsetMaxY, offsetMaxZ )

ParticlesSetScale( emitterId, scaleStartMin, scaleStartMax, scaleEndMin, scaleEndMax )

ParticlesSetAlpha( emitterId, alphaStartMin, alphaStartMax, alphaEndMin, alphaEndMax )

Cool. Thanks.
Will check this out after work.

Oh my goodness, I was going to have Sunday off - was!

This is really cool AmenMoses!

Thanks

Reliquia....

Excellent stuff @Amenmoses really informative my knowledge on the party-tickles and what can be done with them is all thanks to your tuition so thank you kind sir

Next thing to cover, as it's real simple, the ParticlesSetWindVector( xv, zv ) command.

I've added 'wind' to the previous example so you can see how it works.

The 'wind' vector will act upon *all* particles and simply adds a movement factor to mimic a constant wind. With a bit of clever coding you can have the vector change over time to mimic gusts etc.

So how many particles can we have?
Currently 1000 on screen at once, to see what this looks like add the attached script to a crate, extract it and paste another 24 down on the map.
When you test this you should find a constant stream of bubbles from each of the 25 crates, now count the bubbles, only joking .

If you add some more you will discover at some point that the constant stream becomes a sort of pulse effect, this is due to hitting the 1000 particles limit.

You can have up to 100 emitters active, each of which can have by default a maximum of 100 particles (this can be changed from Lua) which can be spawned at a maximum rate of 50 particles at once.

As a matter of interest, if you do try out the 25 crates test above have a look at the frame rate you get, I don't see any dip below 60 FPS on my system. I suspect that lower spec CPUs may not be able to cope as well but would be interested to see any results you get.

This is very cool stuff AmenMoses.

Is it possible to attach an emitter to an object when it is destroyed and just play one random burst. Would be good to mimic an explosion on objects in the air where they don't need to affect the world around them.

Reliquia....

@reliquia stay tuned

If you find your particle effects all start to look like smoke the most likely reason is that GG needs restarting. When you escape out of test mode GG doesn't do a complete clean up! In particular (pun intended) the sprite sheets are still loaded from the previous run, so when you load new ones it uses the next empty slot until eventually it runs out of slots, this isn't fatal as it will simply fall back to using the default smoke effect.

So remember to restart GG occasionally just to clean everything up.

with what build does this work.?
it does not work if i try it.

Only in beta I think.



Keenly indeed

Reliquia....

Probably still only in the Beta then, not sure when Lee is putting out a new PP, should be soon.

(as I said it the very first paragraph of the thread, I've just realised )

I was all pumped to try this out! And then this What the?

You can always email Lee for beta access.

Lee@thegamecreators.com

Hi all

Been messing with this awesome addition to the engine.

This is just so cool AmenMoses - great stuff.

FYI:
I have been messing around making decals and playing with all the settings in the scripts, with the intent to get a fire\smoke thing happening.
Using two emitters one for fire, one for smoke - I wanted to have the fire going up and the smoke getting caught in the breeze a little.

One thing I have found is that if you use an emitter without the wind factor and also one that has the wind factor in the same level, both will mimic the wind factor. Lol - sounds like a riddle...

Reliquia....

The wind factor is global, i.e. applies to all emitters. Maybe as a future addition I could add a flag to disable the wind effect for a specified emitter, will look into it.

Ok, cool - we wait in anticipation

Reliquia....

Are particles subject to any collision? Like if I set up some rain outside, can it detect buildings and coverings and whatnot and not rain inside?

If not, some sort of 'deflectors' system would be fantastic. A way of setting meshes as surfaces particles could bounce off. I remember seeing this functionality in some visual effects software several years ago and it looks great.

AE

No collision, it would have to be 'faked' somehow.

To stop it raining inside for example you would probably have to create a zone which when the player enters it the particles emitters do not, you could attach the emitters to a hidden object that simple follows the player around but stops outside the 'exclusion zone'.

That way you could go indoors then look out at the rain.

It is feasible although probably not very practical to use small simple shapes for the particles instead of 'camera facing quads', maybe spheres, then they would be able to interact with the environment but I doubt you could have enough of them active to mimic rain.

I have a Lua script that does something similar for leaves blowing around but it is really tricky to get realistic behaviour as you can't actually have a 'leaf' collision shape!

This is great reading A M thank for putting it up

Dave

Why do the emitters have to follow the player around? Can't those hidden objects just be immobile and placed in the sky to only rain down on specific areas? I guess that would look a bit weird to not have rain coming down on the roof of the building but it might work in certain scenarios.

AE

They could but then you would need to switch between them as the player moves around and it would be quite hard to make it seamless.

I suppose it could be done in a similar way to the way dynamic lights work, i.e. only the nearest emitter objects to the player are triggered and as the player moves away from them they switch off.

Just a teaser to show what we can do at present.

Hi all

Great stuff as always - really exciting stuff.

I have been testing smoke decals on one of my maps - which seam to working be fine. However when you get about half way through the map, I get this slow-motion effect happening - like player moving slowly, gun re-load in slow-motion, happens for a bit then stops.

If I remove the emitter it doesn't happen.

Haven't changed the scripts yet to test it, but I am guessing we should turn emitters off when player is not within range to see them active?

Anyways, awesome stuff all this - thanks for great work AM and Graphix.

Reliquia....

I hope i can finally get some time to play around with these new lua commands

Look at the ParticlesDeleteEmitter command, i.e. create the emitters as you need them, player enters a zone for example, and delete them when no longer required.
The performance hit depends a lot on how powerful your CPU is, a modern i5 or i7 will handle them fine, older duo's or AMD CPU's will have a harder time of things.

Is there any chance to get a demo map with scripts to show some cool stuff

I think we already did that, the search facility doesn't seem to be working at present but I'm pretty sure GraPhiX released the fireworks demo in the thread at some point last November.

Btw, the fireworks demo we did would work much better now that Preben fixed a few GG issues.

any links about topic you mentioned?

https://forum.game-guru.com/thread/220163#msg2607030

thanks

but there isnt any link in that topic sadly..

I did my homework
I created a sandstorm

https://forum.game-guru.com/thread/220055#msg2622747

Probably a good place to put a link to the particles tester script.