Tiny Things – Particle Generator
I wrote this tool mainly to satisfy my own needs (and to entertain myself).
If there had been something else I would not have done it.
I am glad to thank Dave C. Polcino for support and beta testing. It’s nice when you know there’s someone out there and that the computer in front of your face is not all there is.
Creating particle effects is a very time consuming process. It is true that GameStudio has an extremely efficient (and underestimated) particle system – but due to the troublesome script coding it seldom shows its advantages. The sheer number of parameters, and moreover, the complicated way in which they interact, cannot be assessed in advance. For that purpose one needs a tool that will allow you to experiment with the parameters in real-time – like the good old Moog synthesizers. Only by the means of such an instrument can one can exploit the countless possibilities of GameStudio’s particle generator.
But such a machine has not existed up till now –a complete, intuitive, particle creation system with realtime feedback and instant integration into your game or program. To make such a tool available was the basic idea that led to the construction of »Tiny Things«.
Who Is Tiny Things For
We are following the GameStudio motto “programming for non-programmers”. Or to put it another way: to make things as easy as possible.
Installation is very simple. Nevertheless there are some »Tiny Things« that need to be done in order to take full advantage of the program’s many features.
Once you have Tiny Things installed, the interface is quite easy to work with. It allows you to play around – and see immediately what consequence the alteration of a single parameter has. Experimenting with the sliders and various values while watching the real-time feedback will allow you to understand the possibilities and limitations of the particle system without having to type in advanced calculations by hand.
Though the interface has an intuitive and friendly layout, it is by no means some simplistic thing. On the contrary: it extends the functionality that is implemented in GameStudio. One could liken Tiny Things to an automatic coding machine, which generates WDL and C++ code.
The concept of particle manipulation
What are particles? They are very small objects that appear in swarms and clusters, as dust, water fountains or even insects. Technically, particles are bitmaps that simulate spatial depth, following the old tromple l’oeil tradition (betraying the eye, Renaissance technique of perspective painting). The very trick – and the limitation – of particles is the fact that the bitmap is always oriented to the player/camera, the center of the scene. So it is not truly a three-dimensional object, but a strange mix: a two-dimensional sprite in 3D space. By making many instances of these sprites and combining movement and varying opacities, you can create many different, dynamic illusions with particle systems. Also by using more than one visual representation you could eventually created animated sprites within the particle cloud (see the “morphing” section).
A particle can create many illusions (clouds, smoke, fire, fountains, etc). This is also the reason why they are difficult to work with. All the parameters of a particle system must combine to create the right effect. Gravity, velocity, the quantity (emission), alpha values and randomization are just some of the elements that need to be defined when creating a particle system.
If one looks at GameStudio’s particle system you will realize that a lot of these factors are implemented already. Nevertheless – after having coded one or more particle scripts, you will see that particles tend to repeat in a rather consistent, non-organic way. So, what will make a particle system more exciting? The unpredictable. A basic means to make something unpredictable is randomization, difference, and deviation. In this sense the most important concept Tiny Things relies on is randomization. Following this concept, every parameter (every potential source of mechanical looking repetition) has its own random factor to help create a more realistic, organic effect.
The *pfx (ParticleFX) data format
To realize the expansion of the current particle system, the given WDL-environment was not sufficient anymore. And since we were forced to create a dll we have preferred to create something new: not the common WDL action, but a C++ class with it’s own data format (*.pfx).
To support the common way of handling things, the particle effect is saved as a WDL action. All the saved effects will therefore appear in WED’s Action Attach window, and you can assign them to any object (like you assign template actions). This assigned action in turn calls the actual functions contained in the dll.
One of the advantages of Tiny Things is that it will allow users to exchange custom particle effects. Only the .pfx and matching .wdl files will need to be transferred, and these are quite small.
Features of version 1.0
a) visual, easy-to-use interface
b) picture panel (with a preset of 22 alpha-blended picture presets
c) random control
d) process control
e) range limiter
f) automatic scripting
g) plug-in functionality
h) special effects: environment, circular surround, morphing
What is planned in the 1.xx version of Tiny Things is
a) a grouping function
b) improvement of the mathematics section
c) further special effects
All of this is embedded in the current data format in the form of placeholders for convenient future expansion.
Will it be free
That depends upon what you are looking for. The player engine of Tiny Things (which includes 10 particle effects) is freeware. If there will be a collection of free *.pfx files it would be a very efficient freeware tool which could be attached to the GameStudio engine. It is also granted to use TinyThings in your own non-commercial projects. For commercial projects you have to be a registered user and include the following credit: additional effect programming: superfluxus /TinyThings .
The demo that you have downloaded from the Internet is a fully functional program, only the ability to save your own particle creations is disabled.
To get a full version, you can register at http://www.superfluxus.de/TinyReg.html. Price: 19.99 Euro or $19.99 US (plus VAT). You will receive a registration key, which will enable the save functionality.
When you read these lines it’s because you have succeeded in doing the main part of the installation (run setup.exe). Tiny Things is now available in your program menu. You may immediately start to play. But before drowning in the endless possibilities you might like to know that there are three different ways to use this program.
1. In a way this is self-explanatory. Just launch the TinyThings.exe, click “New” and by adjusting the various sliders and values, see what kind of visual effects are possible.
2. You can also just use the free effects for your game development. To do that you have to integrate TinyThings as a plug-in dll, and there are a few lines of code you have to add to your wdl file. Just five minutes, not more. Moreover it is a very easy process even a beginner can achieve without problems.
3. You are a registered user - or a candidate for registration - and want to use TinyThings as a tool to create and save highly complex particle effects. Installation process is the same as in 2) with the only difference that there is a registration key to be installed. You’ll also want to learn how to work with the TinyThings editing panels within your actual developing application or game.
How do I embed the plug-in into my development environment?
As mentioned, there are three ways to use the program:
Think of the three approaches like a tape recorder. You can playback TinyThings particles in your GameStudio project, or you can use TinyThings standalone to create particle effects, or, most powerful, record and playback within your current project.
Because TinyThings’ effects are very complex, the generated wdl script is merely a pointer file to TinyThings’ own custom format, the .pfx file. So the custom effects (the ones that come with TinyThings or your own) are therefore stored in both the tinythings.wdl and tinythings.pfx files.
Installation of the dll (Tiny Things as player/recorder
Here are the steps to embed TinyThings as player/recorder:
1) Add the TinyThings path to your wdl file
2) Include three wdl files: producer.wdl, definitions.wdl and tinythings.wdl
3) In your main function, write scripting for opening the dll and run the function TinyThingsInit();
4) Move tinythings.dll into your main project directory (up one level from where it should be once the TinyThings folder is copied to the appropriate location)
Starting point of your game is a *wdl file, the one where the main function is declared. To make TinyThings a working plug-in you have to add a few lines of code to your main .wdl file. Just copy/paste the following lines into your project.
First, the dll has to have access to its resources (bitmaps mainly). Copy the TinyThings folder that was installed with the setup.exe into your work directory.
So if your current project is at this location:
Your TinyThings folder path should look something like this (TinyThings folder renamed to “Tiny” in this example):
Your wdl has to know where to look for the bitmaps, so declare a path at the beginning of the wdl file. If the subdirectory is - as in this example - tiny, insert at the beginning of the file:
path „C:\\Program Files\\GSTUDIO\\template“;
At the beginning of the file where you find the other includes please insert the following lines:
Ok, that’s done. Now you have to call the actual *dll. This is accomplished by adding the following command at the end of your main function:
partikel_handle = dll_open(“TinyThings.dll“);
Note: Partikel is German for Particle. You probably guessed that!
partikel_handle has the function of a key which allows to open up and close the dll which is necessary for TinyThings. If you have various dll’s and don’t open and close them properly, be aware that there might be some conflicts (see the GameStudio manual for more information).
Copy the files producer.wdl, definitions.wdl and TinyThings.dll into your game development root folder. Dlls for GameStudio must be in the same root directory as the project. Having done this, installation is nearly complete, and the next time you run your project, you will see the TinyThings interface on the screen.
This mode has a big advantage. When you create an effect and save it, the corresponding files (TinyThings.wdl und TinyThings.pfx) are written into the directory where they are needed for playback. There is no need to copy files from one directory to another (what you have to do if you use TinyThings as an isolated program).
The second, maybe even bigger advantage is the fact that you may control, in real-time, what your effects will look like under the very same conditions they will appear in the game (same light conditions, position, as well as frame rate). So you do not plan in an abstract environment, but in-game, as if you were playing.
Note: You can alternatively place the TinyThings files in your main work directory and skip creating a subdirectory path. This is convenient because it may avoid any path-related errors, but can make for a sloppy directory. Be aware also that the standard files “menu, movement, etc” are not needed to run TinyThings in your own project. Those a purely for the simple shell project that comes with TinyThings. Be careful when copying files not to overwrite any of your own custom .wdl files.
The playback environment
After you’ve designed your particle systems (or wish to use pre-made particles in your project), you’ll want to set up TinyThings as a playback-only device and remove all interface items and panels from your game/project.
Comment out the line which refers to the producer wdl, so it looks like this:
The interface will disappear.
But wait a moment! To avoid an ugly error message you have to add another line. At the position where the dll is called comment out the TinyThingsInit(). Now add the playback function call. Your code should now look like this:
That’s all you have to do. And TinyThings has turned into a playback device which does its work in the background.
Now when you select an entity in WED and bring up its properties, your new particle actions will be available in the Action List. Simply attach that to the object you want to emit particles (you may wish to turn off visibility of the object if you don’t want the emitter to be seen).
For advanced users: the architecture of the TinyThings interface
Nearly all the processes of particle manipulation are triggered by the dll. The interface to wdl is reduced to the moment of the initialization at the end of the main function and to the notation of the action in the TinyThings.wdl. A typical TinyThings particle call action looks like this:
my.skill34 = 1; // das sollte die ID sein
temp.x = 1;
effect(ParticlePlayer, 1, my.x, temp);
By means of the keyword »action« there is an internal wdl object generated - and because this appears in the included file it also appears in WED. What does that mean? That any object may incorporate a particle effect (and vice versa, that you may transform a particle effect into much more than this - combining weapons and laser beams, whatever). But generally this does not make too much sense and one will prefer to render the object invisible, writing:
my.visible = OFF;
In the example above you find a while-loop. That means: the effect is permanent, without ceasing. But this is not necessarily so. You may use the effect just once, for an explosion for example. Generally the action allows all the manipulations you are acquainted with, event handling, my, you, vector transformations, etc. And you have access to all the skills - with two exceptions:
my.skill34 stores the ID of the effect and is for that reason blocked. If you change this value, you ask for another (which might not exist - with the ugly consequence of a system crash).
my.skill29 stores the rhythm of the system. If you plan to use the effect once and not repeatedly you are free to use that skill also.
What is the meaning of the inner part of the loop? Why the use of the temp-variable? In a way this is makeshift solution, due to the fact that WDL is strongly regimented - and the effect command does not allow the takeover of arbitrary or overloaded parameters. So we have to smuggle the main information (the ID) into the dll, using the fourth parameter which normally transports the vec_vel vector (already stored in *.pfx, therefore redundant). We use it to transport the ID and allow the dll file to retrieve the corresponding effect from the *.pfx file. These three lines are crucial, so you shouldn’t change them. Be sure to recreate this part of the script when doing your own custom C-scripts.
How can you use the fabricated wld action for further coding? (which might be useful when you want to
establish event handling).
This is very easy to be done. You can use the TinyTings.wdl - and refine the action to your needs. The one and only ting that you have to think of is not to rename the action. In fact this won’t do non harm in the current state, but it will colllide wih the planned data system mechanismus which needs the action name as an identifier.
A The main panel
One requirement which was important for the design of the Tiny Things interface was the idea that you may use this tool in your normal development environment – and that the panels therefore should be narrow and screen-saving.
At the upper part of the screen you will find the main panel. It is the place where the most frequently accessed parameters are located for the active particle system.
If you want to change a value, you click the button of the respective parameter. On the display the name of the changeable parameter appears and the digit field displays the actual value. If you drag the slider, you can adjust this value.
As default, the scales are tuned to plausible ranges. It would make no sense to apply a negative number to a color value which ranges from 0 to 255. On the other hand such a negative value makes perfect sense for an x or y coordinate.
From time to time you may need to adjust the scale to your own requirements. This can be done by clicking the little meter that looks like a clock located at the upper left. An input field opens up, which allows you to set the minimum and maximum value ranges. You can define your own scale and thereby control even the finest details. So you could control a gravity value between –1 and + 1 for super fine-tuning (don’t be thrown off by the display that shows only integer numbers. It works).
2. The group of parameters
The right part of the main panel (where you see the two rows of buttons) represents the changeable parameters. Whereas the upper row stands for the attributes, the lower row stands for the corresponding random values (on a scale that ranges from 0 to 100). If randomisation is set to zero, no random generation takes place. If it is set to 100, there is a 100 % chance that a totally arbitrary value may appear. The group member of the swarm will be equipped with varying start conditions, which may vacillate between the lowest value (usually zero, sometimes one) and your predefined value. It is very important to understand that mechanism. Every value passes though such a random modulation. If you want to exclude randomization, you have to set the random value slider to its lowest value – otherwise the random modulator will overrule your predefined value.
The parameters are (from left to right) [the numbers in brackets describe the default range]
size – the particle’s size (from 1.. x)
lifetime – it’s duration (from 1..5000 Frames)
red – red value (0 - 255)
green – green value (0- 255)
blue – blue value (0 - 255)
alpha – regulates transparency of the particle (0-100)
gravity – regulates gravity that is applied on the particle (-3 ... +3)
vel_x – emission velocity on x-axis (-5 ... +5)
vel_y – emission velocity on y-axis (-5 ... +5)
vel_z – emission velocity on z-axis
x – offset of the original position on the x-axis
y - offset of the original position on the y-axis
z - offset of the original position on the z-axis
time – rhythm of emission
quantity – number of emitted particles
The round buttons in the lower row stand for the corresponding random coefficients.
A little above the xyz parameter you see a small grey button that turns orange when clicked. It opens up a window of special effects (more on this later).
3. Creating a new particle effect
On the right side of the panel you find two buttons to create and to save a particle effect. If you press NEW, a small cube model is created and placed into your interactive environment. Your particle effect is attached to this temporary cube. You’ll replace the cube with a model, or hide it for your actual project.
The very moment you press the “NEW” button the particle effect starts its work. If you change a parameter value you can see the results immediately.
It is possible to edit a series of particle effects, but during edit state you will only see the state of the current particle system. Nevertheless, the playback of particle effects allows up to 100 various effects to be replayed at the same time (this value is arbitrary and may be raised in following editions).
4. Saving an effect
Storing an effect is a simple operation: click the “Save” button. If you’ve registered TinyThings you’ll hear a small beep, and your effect has now been saved. It’s important though to understand how and where TinyThings stores an effect since you’ll want to use it in your projects. When the »SAVE« button is pressed the program attaches the data to the already stored effects in the TinyThings.pfx file. But this information can only processed by the TinyThings.dll. To make the effect accessible to the GameStudio Engine, there has to be a matching *.wdl file. This is the second step in the SAVE process. Parallel to the TinyThings.pfx file the TinyThings.wdl is also written. This has the big advantage that you will find the new effect in the action menu in the WED instantly!
5. Assigning a picture
If you want to use an image for the particle effect (which is recommended since the pixel cube is not a very picturesque thing) you have to assign your particle system an image. Open the image window to accomplish this (click the long tab at bottom right of the main panel)
In the current version there are 22 (alpha-blended) images which will help you to create smoke, fog, fire, meteorites and some other interesting effects. (This preset collection will be increased in following editions – and you may add your own pictures as well.
Assigning an image is very simple – just click on an image and the effect uses the image as a particle. It goes without saying that you can substitute it with another click – and thereby step through the picture row. Also you may use the color and alpha parameters to further fine-tune the images.
You can step through all the available images by pressing the small red button with the letter “S”, on the right of the picture window.
To step to the next or previous row of pictures, use the tiny red boxes also on the right side of the picture window.
Important tip: If you want the picture to be exactly like it appears in the image preview window, you have to take care that the color values are set to their maximum values (R-255, G-255, B-255). Set the alpha at 100% if you don’t want any transparency.
So far you’ve been using rather permanent values (e.g. particles always shoot straight up, or red continually cycles from 10-140). To add more realism and organic fluctuation, you’ll need to use the Formula Editor.
B. The formula editor
An overview of the formula editor
You open the formula editor by clicking the long tab located on the bottom right of the main panel.
On first sight one may think this panel looks fairly simple, but in fact the contrary is true. It is more complex than the main menu – and therefore it is important to understand its functionality in detail.
On the display you read the name of the current parameter. It starts out by saying “param”, that means it is void and no parameter is currently assigned. All the parameters available in the main panel can be controlled by the Formula Editor. First – choose the parameter you want to edit. If you click the red button at the right you may step forward – if you click the left one you step backward. Now that you have a parameter listed in the Formula Editor window, the second thing you have to do is turn the formula engine on. Press the green button (which is a Power ON/OF button). It turns red and signals you that the effect machine (for that specific parameter) is now active and running.
If you edit multiple parameters and step through the parameter’s list, you will see that the program stores all the settings, Power Button, values, etc. So every parameter can have its own formula attached to it. In this sense, a particle effect may be understood as a combination of param * function(param) possibilities, that’s a lot of possibilities! But you do not really have to worry about metaphysics; all you have think about is the simple interface and the actual parameter you want to modify.
You can think of this device as an automatic code generator – it creates code. Commands like pump up the volume, grow gradually in strength, or let it shrink, are some basic examples. Another good example: instead of having your particles disappear after their lifespan, you can make them fade away nicely with the Formula Editor affecting the particles’ alpha parameter.
Using the formula editor
First select a parameter and then activate the formula editor by clicking the green button. It now turns red, telling you that the formula editor has been activated for that particular parameter.
You have access to two sliders, which help control and confine the formula. The left slider controls the increment or decrement of the effect for the respective cycle. So you can increase or decrease the parameter’s value.
The right slider is the limiter. It helps you to control the range. For instance, if you’re editing the value of red, it can only range from 0 to 255, so you set the limiter so we don’t end up with out-of-range values.
The strangely entitled “killer” button will remove the particle if it has reached its limit.
Turn the formula off for each parameter by clicking the formula power button again (Green = off, Red = on).
The mathematics editor
The mathematics editor works in conjunction with the formula editor. It affords you much more power than the formula editor alone. With that power comes a price: it is more complicated and may seem somewhat illogical in its operation. This will be improved in later versions (there has to be a complete redesign of that section, since this tool will be the entry point for much more sophisticated manipulations).
But let’s talk about the status, imperfect as it may be. The mathematics editor follows the idea of process control, much like the formula editor. The difference is that it needs no limiter slider because it is built in. What is it? You can’t see it on the screen, but you’ve known it all your life: it’s the logic of the circle, sinus and cosinus.
Imagine that we want the size of the object to oscillate between 5 and 15. We have a minimum range and a maximum range – and that’s what you see when you click on that little clock-like icon on the formula editor. Fill in 5 as min. Range and 15 as max. Range. Then click on either T_cos or T_sin (I will explain their meanings a little bit later). Now you have to adjust the right slider of the mathematics editor. This is the one that allows you to control the pulse modulation, make it accelerate or slowdown. And now you will see that the particles pump up and shrink again. This will work with all of the different parameters. (a later version will also support the random value parameters).
When you think a little about the opportunities this wonderful circle logic offers you, you will see there’s no limit anymore. One can fade in and fade out everything – and everything will have the air of an organic movement.
What is the meaning of the T_cos and T_sin in contrast to sin? In the current version there is no difference, but there will be a difference soon. T means – that the sinus and cosinus operation is applied to whole flocks of particles (so T is for total). So it’s not the single particle but the swarm as a whole that is pumped up or shrunk. So you can manipulate the particle swarm as a whole or by individual particles.
There is a fourth button, labelled lin. Lin stands for linear – and if you click this button the mathematics is turned off and the linear logic of the formula editor will take control again.
One remark, how you can use sin and cos in companionship. If you separate the spatial axes in x y z (or x y for a two-dimensional movement) you have a cos for the x axis and a sin function for the y axis. So if you use the two of them together you will get ellipsoid movement.
Play around with the mathematics editor. You have to adjust yourself a little bit – because the engine may fabricate strange things. Color manipulation is a peculiar thing (since there are so many co-effective circumstances). But after a while you will find it an indispensable tool in your particle arsenal.
C. Special effects
At the upper part of the main panel there is a small grey button that turns orange when clicked (it is a toggle switch, indicating the ON/OFF state of the special effects section). It is important to understand what these special effects do. They do not apply to the particle’s process (its individual life, it you take it that way), but merely on the moment of its generation, or more precisely: on the location of its generation. That is the reason why it is located above the xyz parameter group.
If you turn on the special effects section it is quite probable that nothing will happen. Why? Because the effect isn’t visible until you change the x/y values. You do not have absolute coordinates anymore, but relative ones. Environment relates to the player (and x/y turns into some kind of distance meter). Surrounding the player (who replaces the cube as the center of the effect) the x/y/z coordinates turn into distance meters (and offsets). An application where such an effect is very impressive is the simulation of rain or snowfall in the player’s view.
The function Circular is quite similar, the only difference is that the object stays center.
The most remarkable function in this context is morphing. What exactly does morphing do? It is not, as one may think, a visual morph of the picture. What is morphed are the elements the particle effect consists of – with the result, that all the A elements turn smoothly into Bs. This is comparable to the African ant that occupies the hostile ant population by replacing just the queen – so that after a while the whole population is replaced by the occupants.
There are three different morph types
once - triggers once
loop - plays from A to B, then starts again
to and fro - this morph type creates a shuttle movement, A to B, B to A, and so on.
The value you may type in this panel relates to the duration of the effect (counted in cycles). This is not identical to absolute time. If the rhythm of emission is 60 frames, 10 cycles would mean 60 * 10, which equates to a duration of 600 frames.
How do I assign a morph target? If you click the option “morph”, a little yellow button appears on the picture panel with the number caption “2”. With that button I select the picture, not by means of the mouse but via keystroke. L moves the button to the left, R to the right. This effect, like any other effect in TinyThings, is visible in real-time and allows you to follow the results and modifications with ease.
Note: this little mechanism is the main architecture of a bigger module that will allow you to create particle effects with not 2, but up to 10 pictures!
So the steps involved in creating a morph are:
Open the effects window.
Choose Morph from the available choices
Select a process (once, loop or to-and-fro)
Use the “R” and “L” keys to choose the second morph image
If you don’t see the changes that you expect, select the x or y velocity parameter in the main panel and move it a bit. This will refresh the effect.