OGRE Particle Editor
Welcome to the OGRE Particle Editor Manual.
If you would like to view a quick tutorial on how to use the editor, please visit the tutorial page.
The OGRE Particle Editor is a real-time visual particle system editor.
It is a tool that provides the ability to rapidly create OGRE particle system templates that can be used in any OGRE
driven application. The effects are stored and loaded as templates via standard OGRE particle scripts (*.particle).
Before we load up the particle editor lets take a look at the directory structure.
You should have a bin and data directory.
Go into data and you should see a
few more folders, most significantly three called material_scripts, particle_scripts
and textures. If you want to tweak your own existing particle scripts or add your own materials
and textures, put your files in these respective folders. Particle templates that are saved via the editor are stored in this particle_scripts folder.
The data directory should also have a folder called config.
If you ever feel that you need to modify the default parameter range values, modify them via the
'parameters.cfg', but be careful when making changes to this file.
There should also be another file called 'editordefaults.cfg'; use this file to specify the name of a particle
system that you would like to automatically load when the editor starts up.
To start up the editor double click the ParticleEditor.exe in the bin folder.
There are four main panels on
view in the editor: the Template Management Window, the Particle System Parameters Window, the Editor
Options Window and a Status Bar.
The Particle Editor when loaded with the default particle system - PEExamples/pentagram
Hint: Hovering the mouse cursor over certain buttons and text will show a tool tip. Tooltips will give some further explanation, and describe any
keyboard shortcuts if any exist.
Template Management Window
The Template Management Window is where you can load, save, delete and generally manage all your particle
templates. It has three tabs: Selected, Available and New Template.
- The Selected Template tab holds the information relevant to the currently selected template -
you can only have one particle template selected at once. This tab has buttons to load/reload and
unload a particle system based on this template, and it has buttons to delete and save the template
into a particle script.
- The Available tab shows a list of templates found by the editor. To select a template, click the
item in the list and that template will become the currently selected template. This tab also has
two buttons. The first, Unload All, simply unloads all particle systems currently loaded. The
Load Exclusive button will unload all active particle systems and reload that specific particle
- The New Template tab is where you can create new templates. You can build one based on an existing
template, or you can create a blank template that will have the default parameters set.
As already mentioned, you can only have one template selected at once. The selected template will appear
in the Available tabs list of templates with a blue bar marking that item in the list. To select another template, simply click
on the item in the list that relates to the template. When you select a template, not only will the Selected tab
be updated with the correct information, but the Particle System Parameters Window will refresh to reflect the
newly selected template. If you click on a selected template in the list you will quickly jump to the Selected tab.
The Available tab within the Template Management Window shows all the currently loaded particle systems.
Particle templates that have been loaded (i.e. a particle system is active in the editor) will appear in the list
with orange text. When you unload a template, the associated particle system will be destroyed and text colour will
change to the normal colour.
When saving a template, be aware that if you specify a new template name you are effectively creating a new template
(the 'save confirmation' window that appears will tell you this). When the new template has been saved into whatever
particle script you specified, it will then become the currently selected template.
Particle System Parameters Window
This window is where you will do the bulk of your work when tweaking your creations.
It is divided into two; the upper section contains the particle system components and parameters
associated with a selected component, and the bottom section consists of a panel where you can
perform certain actions on that component.
Along the top of the upper section is a list of button tabs that relate to the components that make up
your particle template. Beneath these buttons are all the parameters that are associated with the
selected component. There are three types of components:
- Basic - All particle templates have basic parameters that define the common elements of your template,
such as the quota (maximum number of particle), material, particle size etc.
- Emitters - Emitters are self explanatory, they emit particles. You can have as many as you want (be aware
of the performance issues associated with many emitters).
Parameters include the particles life span, the colour of the particle, the direction particles are
- Affectors - Affectors are also self explanatory, they affect all the particles within your particle
system. By using affectors you can apply forces on particles, change their size, modify their colour etc.
You can only define a certain type of affector once within a template, but you can use any combination of
In the bottom section of the Particle System Parameters (the boxed area) you can find buttons that allow you to
randomise and restore parameters in the selected template component. The other controls are dynamically altered depending on the selected component.
Perform general tasks from the bottom panel within the Particle System Parameters Window.
If the Basic component panel is selected, buttons and combo lists will appear that allow Emitters and
Affectors to be added to the particle system. Note that in addition to adding the standard emitter types,
you can also choose to clone an existing emitter if the selected particle system has multiple emitters.
If an emitter or affector component is selected, a button will appear that if pressed will remove the
corresponding emitter or affector from the particle system.
Editor Options Window
This window contains two tab panels that allow you to manually control the camera, and to change miscellaneous editor settings.
The Editor Options Window has a tab for controlling the camera and a tab to configure various visual aspects and settings.
The status bar lives at the bottom of the editor screen. Certain actions (such as loading a
particle system) will result in a text message been displayed in the status bar.
The status bar has two buttons at either end of the inner area, and a 'toggle bar' button located at the top center
of the outer bar.
The windows button is useful for quickly hiding any visible editor windows. Clicking it again will
show all the windows that were hidden.
Use the reset button to restore all the editor windows to their default values. It is possible to move,
collapse and close all of the editor windows, so this button will come in use when you need to find a
lost window. The window values that are restored are position, size, whether it's collapsed and also
the alpha transparency of the windows.
Click on the help button to open the help window. The help window may hold some useful tips,
the keyboard shortcuts and also some basic information about the editor.
Use this button to format your hard disk.
Toggle bar button
The toggle bar button will hide or display the Status bar. If you click this button to hide the
Status Bar, the bar will be hidden and this button will slowly fade out of view. To get this button back
into view, move your mouse cursor over the last position of the button and click.
Hint: In addition to the Status Bar buttons to hide the editor windows, you can toggle the entire GUI from view by pressing the F1 key.
Additional Helper Windows
The editor has three different helper windows that can be accessed by clicking on the appropriate helper buttons
which are located in the Particle System Parameters Window.
- Colour Helper - Modify the colour values and view the resulting colour in real-time before applying it to the particle system.
- Direction Helper - Use the preset directions to generate direction vectors easily, including the ability to point at the position of existing emitters.
- Material Helper - View all the available materials before applying them to the particle system.
[ESC] - quit
[PRINTSCR] - take screenie
[PAUSE] - toggle time freeze
[ALT-F] - toggle FPS display
[F1] - toggle free flight mode
Camera (Editor mode):
[ALT-LEFT] - orbit / target left
[ALT-RIGHT] - orbit / target right
[ALT-UP] - orbit / target up
[ALT-DOWN] - orbit / target down
[PGUP] - zoom in
[PGDOWN] - zoom out
[ALT-Z] - reset camera zoom
[ALT-O] - reset camera orbit / target
Camera (free flight mode):
[A] - strafe left
[D] - strafe right
[W] - fly forward
[S] - fly backward
[PGUP] - fly up
[PGDOWN] - fly down
mouse - free look
Be warned, if you attempt to run the Particle Editor on certain "slower" hardware and older graphics cards, you
may experience intermittent slow downs or just plain poor performance. There isn't a concrete dividing line
dictating what minimum hardware is necessary to get acceptable performance, but the editor has been extensively
tested on the following setups with the editor running with no noticeable performance hits:
- Setup 1:
- AMD Athlon XP 2800
- 512 Mb Ram
- ATI Radeon 9800 Pro
- Setup 2:
- Pentium 2.4
- 1024 Mb Ram
- ATI Radeon 9600
- Setup 3:
- Pentium 2.4
- 1024 Mb Ram
- GeForce FX 5600XT - slower than with the Radeon 9600, but still usable
- Setup 4:
- Centrino 1.6
- 512 Mb Ram
- ATI Radeon 9600 Mobile
However, the editor was also tested on the following setup resulting in very unresponsive results:
- Older System:
- AMD Athlon XP 1700
- 512 Mb Ram
- Geforce 2 MX
The best option is just to try it and see what sort of performance you get.
What causes the lag? Well, it can be down to a number of things. The particle editor makes very heavy use of
various CEGUI widgets and windows. This means a large number of quads get sent through to the renderer, and in
addition to all the particles that a loaded particle system may be throwing around, this may start to cause a
strain on your hardware.
There are a number of things you can do to try and improve the editor's performance:
- Optimise your particle template parameters! Keep the particle system quotas and emission rates down as low
as possible. Take special care when adding multiple emitters.
- Do not have more than one particle system loaded at the same time.
- Close all unused GUI windows, including the Status Bar - the Particle System Parameters Window will be in use the most, but you do not need
the other windows to be showing all the time. Besides, having fewer windows open increases your viewable work space.
- Deactivate the tooltips and emitter guides, and set a single colour as the editor background in the Editor Options Window.
Authors / License / Thanks
Developed by mac (mac "AT" gamecat.de) and spannerman (spannerworx "AT" gmail.com).
Please send comments, suggestions and bug reports to us at the above email addresses (remember to replace "AT" with @), or on the
OGRE forums in the appropriate forum post. If you find this tool useful, we would love to hear it!
This editor is available under the same licensing scheme as the OGRE engine i.e. the GNU Lesser Public License (LGPL).
Big thanks to Sinbad and the OGRE team for the outstanding OGRE engine (OGRE), and to Crazy Eddie for his superb GUI system (CEGUI).