APEX Particles Module Users Guide Introduction¶
Introduction¶
The APEX Particles module is a particle (object) pipeline that is designed to produce a wide range of scalable effects in games. Each stage of the pipeline is an APEX actor derived from an APEX asset whose parameters are authored. The particle pipelines consists of a particle emitter, an Instanced Object Simulation (IOS) that computes the physical movement and life remaining of each particle, and an Instanced Object Effects (IOFX) actor that based on the particles physical characteristics determines how the particles (objects) in the pipeline are rendered. A game level editor can create multiple emitter actors in a game level. They can be of the same type or of different types. The emitter actors can reference any number of IOS or IOFX actors. The IOS and IOFX actors are created automatically by APEX.
APEX Particle Pipeline
The new unified Particles module for APEX 1.3¶
APEX 1.3 introduces a new module called ‘Particles’. This new singular ‘Particles’ module, which is delivered as a DLL under the Windows platform, now combines all particle related modules (IOFX, Emitter, IOS, etc.) into a single binary. It does not include the Turbulence module due to how the source code for this component is licensed.
The primary reason for this change is to simplify the process of managing these modules as well as to make it easier to create binary distributions. Now, instead of an application loading the IOFX modules, Emitter module, etc. separately, the application simply loads the single ‘Particles’ module. The application now needs only to load the ‘Particles’ module on startup, release it on exit, and when it comes to deployment distribute only this single binary DLL. If the application needs access to the various sub-component modules, such as IOFX, Emitter, etc. they still exist but are now accessed via the ‘ModuleParticles’ class using the method ‘getModule’.
Relatively modest changes are required to existing source code developed against a previous version of the APEX SDK; changes which primarily involve deleting source which used to have to deal with the granular module loading mechanism. In short, it essentially cleans up your startup and shutdown code.
Another feature introduced with the new unified ‘Particles’ module is the ‘EffectPackageActor’ and ‘EffectPackageAsset’. The ‘effect package’ system combines a collection of particle related actors into a single instantiation which can be manipulated as whole unit. Imagine you have an ‘effect’ which involves multiple emitters, a turbulence grid, a heat source, and some jet field samplers. Rather than having to instantiate and manage five or six separate APEX actors you can now instantiate them all as a single ‘effect’ and manage it as a unit. The newly introduced ‘Particle Effect Tool’ (PET) now allows a designer/artist to author ‘effects’ which can be managed in this way. This feature is optional and is not required to work with APEX particles. You can still instantiate and manage APEX particle related actors manually and even use individual assets authored via the ParticleEffectTool as well. One of the additional features afforded by using ‘effect packages’ is a mechanism to perform level of detail operations using artist/designer ‘per effect’ settings.
Emitters¶
APEX particle emitter actors emit particles at the start of the particle pipeline. Presently there are three basic types of Emitter Authorable Objects. They are the Simple Shape Emitter, Air / Ground Emitter, and the Weapon Impact Emitter. The current shape emitters are the box emitter, the sphere emitter, the sphere shell emitter, and the explicit emitter. The box and sphere emitters emit particles (objects) in their shape. The sphere shell emitter emits particles within the shell of a specified thickness around a sphere. Finally the explicit emitter outputs particles at explicit user defined locations. The parameters that control the behavior of each of these emitters is documented in the following links.
The Simple Shape Emitter Parameters:
- APEX Box Emitter Parameters
- APEX Cylinder Emitter Parameters
- APEX Sphere Emitter Parameters
- APEX Sphere Shell Emitter Parameters
The Explicit Particle Position (available in the simple shape emitter) Parameters:
The Air/Ground Emitter Parameters:
The Weapon/Impact Emitter Parameters:
IOSes¶
Two IOSes exist, the Basic IOS and the PxParticle IOS. The Basic IOS is implemented within APEX as either a CPU or GPU simulation and its purpose is to be a very high performance simulation with very high particle counts for Turbulence. It supports collision with PhysX static and dynamic shapes, but these are proxied from the PhysX scene and not a native component of the simulation. The PxParticle IOS uses the PhysX 3 particle simulation; either PxParticleSystem or PxParticleFluid, depending on the parameters specified in the asset. If the intent is to have lots of dynamic and static collision between the particles, actors, and the environment then this IOS is intended to be used.
IOFX¶
There are multiple IOFX modifiers that each provide unique capabilities. Multiple IOFX modifiers can be used by a particle pipeline. Within the IOFX library the modifiers act as elements in the particle pipeline passing the output of one modifier to the input of the next. The following diagram illustrates the internal IOFX pipeline.
APEX IOFX Pipeline
The IOFX Asset Parameters are documented in APEX IOFx Users Guide
Effect Packages¶
The EffectPackageActor is only available with the PhysX 3.3 SDK and above. An EffectPacakgeAsset is authored using the new ParticleEffectTool (PET). This asset represents a collection of one or more particle related assets bound into a single easy to use unit. A single ‘EffectPackage’ might contain three emitters, each with different properties, a turbulence grid, and other field samplers such as jets or attractors. It could include heat sources and force fields as well. Each of these sub-elements can have different timing values controlling when they are created and whether or not they loop, for how long, and how many times. Finally an EffectPackage can have artist defined level of detail properties to control how to control the effect based on distance from the camera and even using screen space culling as well.