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).

Directory structure

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.
Startup screen
The Particle Editor when loaded with the default particle system - PEExamples/pentagram
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.

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.

management window
The Available tab within the Template Management Window shows all the currently loaded particle systems.
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.
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:

bottom section
Perform general tasks from the bottom panel within the Particle System Parameters Window.
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.
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.
Camera panel Miscellaneous panel
The Editor Options Window has a tab for controlling the camera and a tab to configure various visual aspects and settings.

Status Bar

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.

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 button helper buttons which are located in the Particle System Parameters Window.
Colour helper Direction helper Material helper
Use the Colour Helper, Direction Helper and Material Helper windows to easily change the associated parameter values.

Keyboard Shortcuts

[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:

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).

Enjoy :)