APEX EffectPackage Users Guide

Introduction

An EffectPackageActor represents an instantiation of a collection of related particle actors. An EffectPackage allows for multiple related particle actors to be instantiated as a single unit each relative to a central root pose transform. An effect package can combine one or more emitters as well as associated field samplers, heat sources, and forcefields. The combined EffectPackageActor can be subject to fully customizable level of detail culling and otherwise manipulated as a single unit.

EffectPackages are authored using the ‘ParticleEffectTool’ which allows the developer to rapidly prototype a combined ‘package of effects’ which link to shared resources. This is a PhysX 3.x only feature.

APEX EffectPackage Authoring Parameters Overview

LOD Settings

Each EffectPackageActor can have a set of level of detail optimizations applied to it. These are optional settings but can offer powerful control over how to cull effects within a game. There are two primary ways to cull an effect; based on distance from the camera and based on screen culling.

The following properties control how level of detail is applied to an effect package.

• FadeDistanceBegin - The distance from the camera to begin fading out this effect package.
• FadeDistanceEnd - The distance from the camera to completely fade out and then disable this effect package.
• RandomizeEmitterRate - Whether or not to randomize the emitter rate over time
• FadeOutRate - The amount of time to fade out an effect when it is disabled.
• CullOffScreen - Whether or not to cull this effect package if it is considered off screen; requires a valid view and projection matrix
• OffScreenCullTime - How long the effect is off screen (in seconds) before it is disabled; to prevent an effect from turning on/off immediately when it rapidly spins in and out of view.
• NonVisibleDeleteTime - How long an effect is considered non-visible before it is completely deleted; rather than simply faded out.
• ScreenCullSize - Screen culling takes place in 2d where the origin point of the effect is transformed into screen-space. This value determines how far ‘off screen’ this point is before the entire effect is considered non-visible. See detailed notes about screen-space culling.
• ScreenCullDistance - Because of the nature of how 3d points are projected into 2d; you probably want to disable screen-culling if the effect is very close to the camera. This distance determines a threshold distance an effect must be from the camera before screen culling is enabled.
• FadeEmitterRate - If true then the emitter rate is faded out over time. Other ‘Fade’ options determine if those properties are faded when the entire effect package is faded out.

Screen Space Culling

When a 3d point is projected into screen space the resulting projection translates as shown in the above image. The projected coordinate ranges from -1,-1 to +1,+1. Any projected point within these bounds can therefore be considered ‘on-screen’. However, an ‘effect’ is more than just a single point; it usually has a volume representing a large number of particles being emitted from a central location. Using the ‘ScreenCullSize’ parameter an additional border can be added to account for this. The artist/designer can adjust this value based on the overall size of the effect they are placing into the environment. In the image above note that even though the center of the effect is considered ‘off screen’ the boundary of the particles still intersects it. By adjusting ‘ScreenCullSize’ this extra border can be taken into account. Due to the nature of 3d to 2d projection you should not use screen space culling for effects which are extremely close to the camera. The value for ‘ScreenCullDistance’ will disable any screen culling for effects which are within this distance from the camera origin.

Not every effect you create necessarily needs screen-space culling. The designer should decide on a case by case basis whether or not this feature makes sense for the type of effect that is being created. In general, though, it is desirable to avoid creating effects that cannot be seen.

To use the screen-culling feature the application must provide the APEX SDK not only with a valid view matrix but a valid projection matrix as well.

One feature of the effect culling system is that it will prevent effects with a fixed lifetime duration from even being created if they are considered non-visible at the time they are spawned.

EffectProperties

Each effect contained within an effect package can have unique properties relative to its instantiation into the scene. Primarily these properties are a parent relative transform and timing values. The user call also specifiy an arbitrary UserProperties field which the application can use for additional annotations if needed.

The following properties can be applied to any effect attached to an effect package.

• UserString - This is an arbitrary string which can be interpreted by the application to contain user meta-data.
• Enable - This flag determines whether or not, by default, this effect is enabled when the EffectPackageActor is instantiated.
• Position - This is the parent relative position of this effect.
• Orientation - This is the parent relative orientation of this effect; specified as an euler rotation which can be edited using the PET
• InitialDelayTime - This is an optional time to delay creation of this effect.
• Duration - This is how long this effect should be alive for; default value is zero, which means to stay alive infinitely.
• RepeatCount - This value determines how many times this effect should repeat. The default value is one, meaning to just play the effect once for the specified duration. A value of 9999 is a special reserved value which means to repeat forever.
• RepeatDelay - This is an optional delay value to wait before restarting the effect each time the Duration value expires.
• RandomizeRepeatTime - This value determines how much to randomize the repeat intervals. A value of zero means no randomness, a value of 1 means completely random between 0 and the entire original duration range specified.

EffectPacakge EmitterProperties

If the effect is an emitter then there is an optional additional feature where the particle lifetime and/or emitter rate can be adjusted based on the velocity of the effect. Sometimes this is a useful feature if the particles need to have a higher rate and longer lifetime if the emitter is moving faster or slower.

For each option, adjusting the lifetime or adjusting the emitter rate, there are five properties that can be edited.

• AdjustEnabled - Set this flag to true if you want to enable velocity adjustment.
• VelocityLow - This is the low velocity (in distance units per second) before any modulation is performed.
• VelocityHigh - This is the high velocity range for corresponding modulation of lifetime or emitter rate.
• LowValue - This determines how much to modulate the corresponding property. This number is multiplied times the base rate.
• HighValue - This is the high modulation value for the corresponding property.

The ParticleEffectTool (PET)

The ParticleEffectTool is a standalone Windows application that is designed to author all particle related asset types.

You can configure some defaults for how the PET runs by editing the file ‘ParticleEffectToolPublic.ini’

The first section, DATABASES, controls where the assets authored with the PET are stored. By default all of the raw source APEX assets are stored as XML/APX files into the subdirectory ‘particle_databases’. The combined runtime binary files are stored in ‘publish_particle_databases’.

When using APEX effect packages, binary files representing all of the various interelated assets which were authored for your title are pre-loaded on startup. Details about this process will be covered in the programmer’s guide.

You do not have to use this process or effect packages at all to take advantage of the ParticleEffectTool. If all you want to do is use this tool to author individual particle effect files which you load and manage individually in your project, you can do that too.

Currently the ParticleEffectTool does not yet support organizing assets into sub-directories or browsing files from various locations on a hard drive. Today you simply place all asset files associated with a particular project into a single sub-directory as identified by the configuration .INI file mentioned above. Future releases may introduce the concept of a ‘workspace’, the ability to browse files from any location on a hard drive, and/or subdirectories. The workflow for this, however, introduces a lot more complexity in terms of how fully qualified names are resolved and some other issues. With this initial release, simply organize all related ‘effects’ you might be working on into a single directory for now.

The ‘OPTIONS’ section of the INI file controls the following features.

• LocalUser - This property determines if the application is running from the formal installer or a version built internally from source code. The version from the installer stores assets into the ‘My Documents’ folder for the current user.
• UsePerforce - The PET has Perforce integration available. If you use Perforce for your source control system you can enable this and assets will automatically be opened for edit, added, or deleted, to the current default changelist. Only enable this if your asset directories are properly mapped to your Perforce server location.
• DisableGpu - This is a debug option which allows the PET to run without GPU particles enabled. Used only for debugging.
• SceneGravity - The default gravity value is -9.8 distance units per second squared, assuming your application’s distance units are meters. However, if you want to experiment with different gravity values you can edit this option.
• GlobalSpriteSize - This setting allows you to apply a metric to scale sprite sizes in the tool to more closely match sprite sizes for the same assets in your own game engine.
• UseZup - By default the PET runs with Y as the up-axis. Set this to true if your game engine uses Z as the up-axis.
• UseSplitWindow - This is a debug feature as this point, as the preferred and supported mechanism for editing assets is using the split-window view.

PET Output Asset Files

When using the PET to edit assets, each is saved out to a unique filename which can be loaded by your own application.

BASE FILE NAME	APEX Module	APEX ASSET PREPROCESSOR NAME	APEX ASSET NXPARAMETERIZED CLASS NAME
EffectPackageEffectPackages	Particles	PARTICLES_EFFECT_PACKAGE_AUTHORING_TYPE_NAME	EffectPackageAssetParams
EffectPackageEmitters	Emitter	APEX_EMITTER_AUTHORING_TYPE_NAME	ApexEmitterAssetParameters
EffectPackageFieldSamplers	ForceField,BasicFS	SEVERAL	SEVERAL
EffectPackageGraphicsEffects	IOFX	IOFX_AUTORING_TYPE_NAME	IofxAssetParameters
EffectPackageGraphicsMaterials	Particles	Not an APEX asset	GraphicsMaterialData
EffectPackageParticleSimulations	ParticlesIOS, BasicIOS	BASIC_IOS_AUTHORING_TYPE_NAME (and PARTICLE_IOS)	BasicIOSAssetParam, ParticleIosAssetParam

Any one of these asset files can be loaded and used by an application as individual discrete assets. However, another way you can use this is to ‘publish’ all of the files authored using PET into binary versions which can combine all of the data into a single resource. These assets are all quite small, comprising little more than a set of numbers defining various properties. If you choose to use the ‘publish’ option you will get, as a result, ten binaries files (.APB) which can be preloaded up front by your project and registered with the Particles module.

When the APEX named resource provider asks for an asset, rather than going out to disk or in some other fashion retreiving the individual asset, you have the option of just immediately returning the version which was preloaded via the published output. You could then combine dozens, or even hundreds, of particle related assets into just these ten files.

PET Published Binary Output Asset Files

PUBLISH FILE NAME	Purpose
EffectPackageEffectPackagesDatabase.apb	Contains an array of all EffectPackage assets authored in PET
EffectPackageEmittersDatabase.apb	Contains an array of all Emitter assets authored in PET
EffectPackageFieldSamplersDatabase.apb	Contains an array of all FieldSampler related assets authored in PET
EffectPackageGraphicsEffectsDatabase.apb	Contains an arary of all IOFX assets authored in PET
EffectPackageGraphicsMaterialsDatabase.apb	Contains an array of all Graphics Material properties authored in PET; not required
EffectPackageParticleSimulationsDatabase.apb	Contains an array of all BasicIOS and ParticleIOS assets authored in PET