OGRE Particle Editor

Manual

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.

Introduction

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.

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.

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 system template.
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.

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:

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 emitted etc.
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 affector types.

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.

The Editor Options Window has a tab for controlling the camera and a tab to configure various visual aspects and settings.

Camera - A drop down combo box allows you to change the camera type. You can then use the arrow buttons to 'orbit' or 'slide' the camera depending on the camera mode (Orbit or Target). A circular button allows you to reset the camera type to its default value.
You can also zoom in and out with the zoom buttons, and reset the zoom with the circular reset zoom button.
You can orbit the camera around your particle system automatically by selecting the Camera Auto-Rotate radio button.
You can control the speed of the camera movement with the slider and text input box.
Hint: Moving and resetting the camera can be controlled by keyboard shortcuts. See the tooltips.
Miscellaneous - You can change the behaviour and look of various things in the editor from this panel, such as switching the emitter guides on or off. The Area emitter guide shows the position and size of the currently selected emitter. The Direction emitter guide is a small arrow that points in the direction of currently emitted particles. The remaining items in this tab are self explanatory - hover over them to get more information from the tooltips.

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.

Windows button
The windows button is useful for quickly hiding any visible editor windows. Clicking it again will show all the windows that were hidden.
Reset button
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.
Help button
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.
Quit button
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.

Use the Colour Helper, Direction Helper and Material Helper windows to easily change the associated parameter values.

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.

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

Performance

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

Enjoy :)