Overview

Creating Special Effects

Special effects are used to represent graphical effects such as fire, smoke, rain, steam, exhaust, and similar short term and highly animated effects. The Special Effects tool is a dialog based utility, accessed from the Tools menu. It is used to help create and refine the emitter and particle based effects.

This document describes the Special Effects tool (FX Tool), the special effects file format, the controller file format, and how to add special effects to ESP.

See Also

• SDK Overview

Table of Contents

• Setup
• The FX Tool Dialog
• The Effects File Format
• A Simple .fx File
• More Complex .fx Files
• The Controller File Format
• How to add special effects to ESP
• Testing Effects
• Step 1: Create an XML file for the Effect
• Step 2: Create a BGL file for the Effect
• Step 3: Move the BGL file into ESP

Setup

The tool itself is coded in visualfxtool.dll, and can be found in the Environment Kit\Special Effects SDK folder. To install a new library first locate the dll.xml file. On Windows XP this should be in the C:\Documents and Settings\<user name>\Application Data\Microsoft\ESP folder. For Windows Vista the file should be in the C:\Users\<user name>\AppData\Roaming\Microsoft\ESP folder. The dll.xml file defines all the libraries that are to be loaded along with the simulation, not just the one for special effects.

If the dll.xml file already exists in this folder, check it contains the following lines that are in bold -- and ensure that the Disabled parameter is set to False. If the file exists, but no reference is made to the visualfxtool.dll, then add the bold lines to the file. If the dll.xml file does not already exist in the right folder, then copy the dll.xml from the Special Effects SDK folder over to the folder mentioned above.

<?xml version="1.0" encoding="Windows-1252"?>
<SimBase.Document Type="Launch" version="1,0">
<Descr>Launch</Descr>
<Filename>dll.xml</Filename>
<Disabled>False</Disabled>
<ManualLoad>False</ManualLoad>

<Launch.Addon>
<Name>Special Effects Tool </Name>
<Disabled>False</Disabled>
<Path>SDK\Environment Kit\Special Effects SDK\visualfxtool.dll</Path>
</Launch.Addon>
 
</SimBase.Document>

Note that the Path parameter is either absolute, or relative to the installation Microsoft ESP/1.0/ folder. The path given above might change if the SDK or ESP were not installed to their default folders. If there are other addons that need to be loaded, such as the Object Placement Tool, then they will also need Launch.Addon entries.

This is all the setup that is necessary. The tool can be run simply be selecting FX Tool from the Tools menu.

Notes

The tool contains a bewildering collection of fields, documented in the next section.

Special effect files all reside in the effects folder, a sub-folder of the main Microsoft ESP/1.0/ folder. Special effects are stored in a specific XML file format. The files can be edited directly, but the advantage of using the tool over editing the file is that using the tool will allow you to view changes to the effects without having to exit and restart ESP each time.

No programming knowledge is needed; however, it may take some practice using the parameters to understand how all the fields control the effects.

To attach special effects to aircraft refer to documentation on aircraft configuration files, and the AttachTool described in Using Modeling Tools.

Many of the effects file parameters require two values separated by a comma. The first value is the minimum number that the simulation engine will use; the second value is the maximum number. Every second, the simulation engine randomly chooses a number somewhere between these two values, thus randomizing effects. For example, if you have a lifetime of 5.00, 7.00, some particles will live for 5 seconds while others may live for 6, 7, or 5.2 seconds. The first number must be less than the second number, or the effect will not work.

A forest fire sample effect is supplied with this SDK, but all the effects files in the Microsoft ESP/1.0/effects folder are readable and can be examined as examples of effects.

An existing effect can be disabled by replacing it with fx_dummy.fx, which is an empty effect.

The FX Tool Dialog

• File Menu
• Edit Menu
• View Menu
• Insert Menu
• Main Dialog
• Particle Tab
• Emitter Tab
• Main Dialog

	New	Clear the dialog back to the defaults.
	Open...	Load an existing effect.
	Save, Save As	Save or Save as options.
	Copy Current Tab	Makes an identical copy of both the current particle and current emitter, and adds them to the effect.
	Delete Current Tab	Removes the current particle and current emitter.
	Tab Name	A small dialog will appear allowing you to enter a descriptive name. This name will be used both for the particle and the emitter.
	Stop Animations	Freezes any running animation.
	Always on Top	Check this to keep the tool dialog in focus.
	Sprite	Particles use 2D square sprites as the basic element.
	Debris	Debris allows an effect to emit a library object. Refer to the list of objects in Library Objects.
	Friendly Name	A name can be entered here to help identify the effect.	Display Name=friendly name
	Show Location	If this is checked a cross-hair will appear at the point of the emitter.
	Offset x,y,z	This allows the special effect to be moved from its actual position to a better position simply for viewing while being edited. The range of each of the options is -50m to +50m.
	Radius	The maximal size of the effect. You must give an effect a radius for it to show up as scenery. Measured in meters.	Radius=0
	Priority	The number of particles drawn in any one scene can be limited by the various performance settings. Setting Priority to 0 maximizes the chances of the effect being drawn. Setting it to another number will lower the chances of the full effect being drawn if there are performance issues.	Priority=0
	Has Sound	Set this check box if there is an audio file that should be played each time a particle is emitted.
	Looping	Set this check box to loop the audio file. The file will be played for the lifetime of the particle.	Looping=TRUE
	Min Attenuation Distance	The distance from the source of the sound, that the sound will no longer be heard, in meters.	MinAttenuationDistance=300.0
	.WAV file	The filename of the sound. The file should be placed in the Microsoft ESP/1.0/sound folder.	FileName=filename
	Do Effect	Runs the effect.
	Lifetime	The lifetime of the particle in seconds. The actual value selected by the effects engine will be chosen at random within the minimum and maximum range entered. If zeros are entered here the particles will have an infinite life.	Lifetime=0.00, 0.00
	X scale	The width of the particle in meters.	X Scale=0.00
	Y scale	The height of the particle in meters.	Y Scale=0.00   Note: Z Scale=0.00 is ignored in the effects file, as particles are all two dimensional.
	Rate	The rate at which a particle grows from zero to its scale goal size. The larger the number, the faster the scaling.	X Scale Rate=0.00 Y Scale Rate=0.00 Z Scale Rate=0.00   Note: Z Scale Rate is ignored. Edit the effects file directly if different Y and X rates are required, as the tool will not allow you to do this.
	Scale Goal	The final size of the particle, in meters.	X Scale Goal=0.00 Y Scale Goal=0.00 Z Scale Goal=0.00   Note: Z Scale Goal is ignored. Edit the effects file directly if different Y and X goals are required, as the tool will not allow you to do this.
	Offset x, y, z	The distance that the emitted particles are offset from the emitter in the X, Y, and Z directions. These parameters can be combined with the Emitter Rotation parameters to create swirling particle effects. They can also be used to spread particles out over an area.	X Offset=0.00, 0.00 Y Offset=0.00, 0.00 Z Offset=0.00, 0.00
	Color Start Red, Green, Blue, Alpha	The initial color of a particle. Use the color dialog, or input the values directly. The alpha value here applies throughout. The alpha value in the XML file for Color End is ignored.	Color Start= 0, 0, 0, 0
	Color Goal Red, Green, Blue	The final color of a particle. Use the color dialog, or input the values directly.	Color End=0, 0, 0, 0
	Rate	The first value gives the percentage of the lifetime of the particle that the particle will be colored with Color Start, between the first and second values the colors will cross-fade, and the second value gives the percentage of the lifetime after which the particle is colored Color Goal.	Color Rate=0.00, 0.00
	Extrude	Extrusions are generally effects of great length, such as wakes and contrails. Extrusions work, but they can be very processor intensive. For the best results, start with very long extrusion lengths and short times, and then tweak as necessary.
	Extrude Length	The length of each portion of an extruded effect..	Extrude Length=0.00
	Extrude Pitch	The pitch angle at which point the extrusion creates a new section. The smaller the number, the smoother the curves of your extrusions.	Extrude Pitch Max=0.00
	Extrude Heading	The heading angle at which point the extrusion creates a new section.	Extrude Heading Max=0.00
	Facing Pitch, Bank, Heading	The direction that the particles face. Pitch, bank, and heading are the constraints for the particles’ facing movement. These are on/off switches because the particles either move in the corresponding direction, or they do not. To have the particles face the user, set these to 1,1,1. If one of the values is 0, then the particles will be constrained in the corresponding axis. To have the particles remain perpendicular to the ground but still turn and face the user, set them to 0,0,1.	Ground Normal=0 Face=1,1,1
	Align to ground	If this is checked the particle will be rendered parallel to the ground surface. This is for such effects as wake, rotor wash, burn marks, and similar ground effects. If this box is checked the Facing options become inactive (Pitch, Bank and Heading).	Ground Normal=1
	Bounce	The reaction of a particle when it collides with the ground. The larger the number, the greater the bounce. If the Bounce parameter is set to 0, no reaction occurs. If it is set to 1.0 then it will come off the ground at the same velocity that it hit it. Use a value less than 1.0 to simulate the loss of energy due to the impact.	Bounce=0.00
	Drag	Drag defines the effect of wind and gravity on the particles. Negative numbers impart more drag. For positive numbers, don’t use a value greater than 1.00. For a reasonable effect of wind on dust particles use a value around -0.5	Drag=0.00, 0.00
	Rotation	The rotation of a particle. It is best to use a negative number first and then a positive number to get the most variation in the amount of rotation.	Rotation=0.00, 0.00
	Jitter Dist	The distance that the particles jitter. If you don't want the particles to jitter, set the parameter to 0.	Jitter Distance=0.00
	Jitter Time	The length of the delay before particles start to jitter. Measured in seconds.	Jitter Time=0.00
	Temp	The temperature of the particles, which defines how fast they rise or sink. To approximate room temperature, where particles neither rise nor sink, set Temp to 107 degrees. To make the particles rise, specify a temperature greater than 107; to make the particles sink, specify a temperature less than 107.	TempK=0.00
	Temp Rate	The rate at which the particles cool or heat up. A negative value represents temperatures that are cooling. The faster particles cool, the sooner they fall back to the ground. A positive value represents temperatures that are rising. The faster particles heat up, the sooner they accelerate into the sky.	TempRate=0.00
	Emits Light	Check this if the particle emits light, such as fire, lights or fireworks.	Light=1
	Shaded at night	Check this if the particle is darkened at night. It is used for night shading.	Shade=1
	Turn off in distance	Check this if the particle is small and should be turned off at a distance (to help improve performance).	LOD=1
	Static	If this is checked, makes the particle attach itself to the emitter and shuts off the emitter after the first particle. This parameter was used extensively in creating the lights for the planes. Use this parameter when you need one particle that must stay in a fixed location relative to the emitter (for example, signs and lights). Particle offsets do not work on static particles, use emitter offsets instead.	Static=1
	Emit Effect	Check this if the particle initiates another special effect. This second effect will be initiated and have the same parameters (velocity etc.) as if it were a particle being emitted.
	Effect Name	The name of the effect file to run.	EmittedEffectName=filename.fx
	Texture	The texture file to use with the particle. This file should reside in the effects\texture folder.	Texture=filename.bmp
	Animate	Check this if the effect is to cycle through a series of images in a texture file. If this is checked, then UV co-ordinates are not entered.
	uv1 u, v	The location of the lower-left corner of the texture on the texture page (X, Y) expressed as a value between 0.0 and 1.0.	uv1=0.00, 0.50
	uv2 u, v	The location of the upper-right corner of the texture lies on the texture page (X, Y) expressed as a value between 0.0 and 1.0. See diagram above.	uv2=0.50, 1.00
	fps	The frames per second at which the animation changes textures. For example, a value of 8 means that every eight of a second the animation will advance from one texture cell to the next.	FPS=0.00
	cycle	Two integers. The first is the location of the first frame of animation on your texture. The code parses your texture from lower left to upper right (horizontally) stepping by the size of the cell. The value of 0 defines the absolute lower left cell of the texture. The second value is the location of the last frame of animation on your texture. For example, if you specify a texture size of 256 and a cell size of 64, the texture is broken into 16 cells. In this case, a value of 7 defines the cell that is halfway up the texture and all the way to the right. A value of 15 defines the cell that is in the upper right. For a four-frame animation set texture size to 256 and cell size to 128. Typically a 16 cell animation would be used, using the following layout:	CellStart=0 CellEnd=15
	tex size	The size of the texture (in pixels) that is used for animation. Textures must be square and their size must be a power of two, for example, 256, 512, or 1024. Larger sizes should be avoided because of the lack of support in graphics cards.	TextureSize=256
	cell size	The size of each frame of animation (for example 64 would mean each cell of the texture is 64 by 64 pixels).	CellSize=64
	Alpha blending	Specifies which blending mode to use to display the texture, one of: No Alpha, Alpha, Additive or Multiply.   No Alpha is the default.   Alpha textures are full color and include a transparency mask (alpha channel). Additive textures, on the other hand, have no alpha channel. The transparency of an additive texture is based off of color values within the texture. Color values in the texture are added to the background color. If an additive texture is triggered against pure white, nothing happens because the values are already maximized at 255, 255, 255, which represents the RGB value for white. Any part of the texture that you want to be invisible must be pure black (or else you’ll just get expanding squares). Additive textures are best used when the effect is simulating something bright—like fire or a light.	Blend Mode=0 (valid entries are 0,1,2,3)
	Fade In	The moment during its lifetime that a particle fades in. Expressed as a percentage of total lifetime.	Fade In=0.00, 0.00
	Fade Out	The moment during its lifetime that a particle fades out. Expressed as a percentage of total lifetime.	Fade Out=0.00, 0.00
	Active	Set this check box to see the effects from this emitter. Uncheck it to turn off the emitter. This is to assist with the testing of effects.
	Lifetime	The length of time that an emitter emits particles. Measured in seconds. If zeros are entered here the particles will have an infinite life.	Lifetime= 0.00, 0.00
	Delay	The length of delay before the emitter begins emitting particles. Measured in seconds	Delay= 0.00, 1.00
	Rate	The rate at which particles are emitted. Measured in particles per second.	Rate=1.00, 2.00
	Don't Interpolate	If this is checked, interpolation code is not used. Interpolation code attempts to avoid the graphics anomaly of a continuous stream appearing as a sequence of puffs, because the emitter of the stream is moving much faster than the frame rate. Sometimes this interpolation makes the effect appear detached from the emitter, so checking Don't Interpolate is one way of “attaching” an effect to an object securely. The default is to interpolate.	No Interpolate=1
	Emitter Velocity x, y, z	The movement of the emitter in meters per second, in the x, y and z directions.	X Emitter Velocity=0.00, 0.00 Y Emitter Velocity=0.00, 0.00 Z Emitter Velocity=0.00, 0.00
	Particle Velocity x, y, z	The initial velocity of the particles (in meters per second) produced by the emitter, in the x, y, and z directions.	X Particle Velocity=0.00, 0.00 Y Particle Velocity=0.00, 0.00 Z Particle Velocity=0.00, 0.00
	Offset x, y, z	The distance that the emitter is offset from its point of origin, in meters..	X Offset=0.00, 0.00 Y Offset=0.00, 0.00 Z Offset=0.00, 0.00
	Rotation x, y, z	The rotation of the emitter in degrees per second. To create particles that rotate around a center, combine these Rotation parameters with the Offset parameters. The greater the offset and the greater the rotation, the more dramatic the effect. For example, some of the spectacular fireworks effects in ESP were created making use of these two parameters.	X Rotation=0.00, 0.00 Y Rotation=0.00, 0.00 Z Rotation=0.00, 0.00
	Orientation p, b, h	The initial orientation of the emitter, given as degrees, from the axes of pitch, bank and heading.	Pitch=0.00, 0.00 Bank=0.00, 0.00 Heading=0.00, 0.00
	Drag	Drag defines the affect of wind and gravity on the emitter. Negative numbers impart more drag	Drag=0.00, 0.00
	Bounce	If this is set to zero the emitter will remain at ground level if it comes into contact with the ground. If this is set to a higher value that zero, the emitter will bounce if it impacts the ground.	Bounce=0.00
	Use min/max temperatures	Set the check box if outside temperature is a factor. If so, the particles will only be emitted if the outside temperature is within the min/max range. This can be used to prevent, for example, steam appearing when the outside temperature is too warm for it to be visible.	TemperatureRangeC=0.00, 0.00

Notes

• If an edit box in the tool appears in red, it means that this value must be changed from the value shown for the effect to work.

Effects File Format

Effects files can be opened and edited in Notepad or another editor that reads and saves plain text files. You will usually create a separate .fx file for each special effect that you want to create, though one special effect can contain any number of emitters.

A Simple .fx File

The structure of a simple .fx file is as follows:

• [Library Effect] This section contains general information about the effect.
• [sound] This sections contains a reference to a single sound file.
• [Properties] This section just contains properties concerning which views (cockpit, spot-plane etc.) the effect should be visible from.
• [Emitter.0] This section contains properties (position, velocity, rate of particle emission etc.) of the emitter.
• [Particle.0] This section contains properties (lifetime, scaling, rotation etc.) of the particles.
• [ParticleAttribues.0] This section contains more properties (texture, coloring, animation etc.) of the particles.

Comments

To add comments to a special effects file use the notation “//” to start a comment line. For example:

// comment text

More Complex fx Files

With multiple emitters the structure of the .fx file is as follows:

[Library Effect]

[sound]
[Properties]
[Emitter.0]
[Particle.0]
[ParticleAttribues.0]
[Emitter.1]
[Particle.1]
[ParticleAttribues.1]
[Emitter.2]
[Particle.2]
[ParticleAttribues.2]

There is no limit to the number of emitters that can be added to an effect.

The Controller File Format

The Controller is a powerful feature that lets you create sequences of various effects that can be triggered from one place. Essentially, a controller sets up a series of effects (or other controllers), and then it either repeatedly cycles through the effects or randomly selects and triggers some of them. Because controllers are effects themselves, you can spawn controllers from within controllers (just like any other effect). You can use this feature to create a great randomization effect or huge sequences of events that last over long time periods. The only limitation is how many particles you can render onscreen before affecting the frame rate.

There is no tool to create controllers, you will have to create them in a text editing tool, such as Notepad or Visual Studio.

Controller File Format

The format of a controller file is:

[Library Effect]

[Properties]

[Controller.0]

...

[Controller.n]

How to Place Effects in ESP

Like all scenery placement in the simulated world, effects placement is now handled by an XML file and BGLComp.  BGLComp is a tool that will parse an XML stream and extract relevant data such as Latitude and Longitude and create a placement file (BGL file) that will place an object or effect in the world.

As an example, we will place a small forest fire near Seattle.  Before you can place the effect, make sure it is copied to the correct folder. Copy the fx_ForestFire.fx file from the Special Effects SDK/samples folder to the Microsoft ESP/1.0/effects folder.

Note: In the simulation some special effects such as smoke and haze will be rendered behind clouds regardless of their actual relative location. This is a known issue.

Testing Effects

To test an effect place it at a location that is viewable at the very start of a flight. For example, if the flight you select starts at Seattle-Tacoma (Sea-Tac) airport, then the Lat/Long of the starting position of the plane is usually Lat N 47 25.89 Long W 122 18.48. If you place the effect you want to test just a little offset from this, then you can quickly view it and then make adjustments accordingly.

A good place to view an effect is just off the runway to the north of the default aircraft location:

• Latitude = 47.432
• Longitude = -122.308

Step 1: Create an XML file for the effect

The effects\samples folder contains one XML file required for this tutorial: ForestFire.XML. Placing an effect requires BGLComp.exe and BGLComp.xsd.  These are located in the BGLComp SDK.  Copy BGLComp.exe and BGLComp.xsd into the samples folder next to the ForestFire.XML. The BGLComp.exe application allows you to place an effect in the simulated world. BGLComp requires an XML file in order to place an effect.  Double-click on ForestFire.XML file, its contents should look like this:

The XML file is case sensitive.  If you are editing the file be sure to follow the structure of the XML in the sample exactly. The only XML parameters that we will be dealing with are those located within the SceneryObject tag and those within the Effect tag.  Here is what each of the parameters means:

The SceneryObject section:

• lat=  The latitude where you want to place the effect.  This can be in decimal degrees (as it is above) or degrees minutes seconds (N47 25.92).
• lon=  The longitude where you want to place the effect.  This can be in decimal degrees (as it is above) or degrees minutes seconds (W122 18.50).
• alt=  The altitude at which you want the effect to spawn (in meters).
• pitch= The pitch of the effect (in degrees).
• bank= The bank of the effect (in degrees).
• heading= The heading of the effect (in degrees).

Notes
The value of the Pitch field is expressed in degrees, from 0-360. Use this field with effects that have a directional alignment along the x-axis.

The value of the Bank field is expressed in degrees, from 0-360. Use this field with effects that have a directional alignment along the z-axis.

The value of the Heading field is expressed in degrees, from 0-360, with 0 degrees being true north. Use this field with effects that have a directional alignment along the y-axis.

altitudeIsAgl = Whether the altitude is represented in AGL (actual ground level) or MSL (median sea level).  “true” is AGL. “false” is MSL.  If you want the object to snap to the ground, make “Alt=0” and “Altitude is AGL=true”. Almost all scenery effects will use AGL. 

imageComplexity= The minimum scenery complexity in the display settings for this object to show up.  They are: “Very Sparse”, “Sparse”, “Normal”, “Dense”, “Very Dense” and “Extremely Dense”.

The Effect section:

effectName=  The name of the effect to be placed at this location.  (This is the full effect name minus the .fx suffix).

effectParams=  The parameters of the effect.  For example, the following effect will appear at midnight on January 1st every year and exist for 20 minutes:

<Effect effectName="fx_ForestFire" effectParams="MOY=01,01;DOM=01,01;HOD=00,00;MOH=00,20;"/>

The following parameters can be specified in the Effect section of the XML file:

Notes: Parameter Precedence

• "RANDOM" takes highest precedence, then periods of the day (for example, "DAWN")., and then times of the day (for example, "HOD”).
• "RANDOM" is determined when the scenery is first loaded. If the random check fails, the effect will not occur at all until the scenery is completely reloaded (at which point it may fail the random check again).
• It is possible to set up an effect's parameters such that the effect never occurs. If any of the "DAWN," "DAY," etc. parameters are specified, they take precedence over "HOD," "MOH," and "SOM." Therefore if you set "NIGHT=0;" and "HOD=22;", the effect will not show at 10:00PM because it should not appear at night.

Multiple Effects

You can add many different effects to one XML file.  Just create multiple SceneryObject tags, for example (creating two forest fires):

Step 2: Create a BGL File for the Effect

After you have created the ForestFire.XML file, you must run it through the BGLComp compiler to create a new file, ForestFire.bgl.

To compile the BGL

1. Navigate to the Effects_placement folder on your C:\ drive.
2. Select the ForestFire.XML file and drag it onto the bglcomp.exe.
3. bglcomp.exe will compile the .XML file into a new .BGL file called ForestFire.BGL.

If you are having troubles getting your XML to successfully create a BGL file, you might want to do it in the Command Prompt window in order to see the errors generated.  Do this by opening a Command Prompt window and navigating to the folder in which you have placed the ForestFire.XML and the BGLComp.exe.  Then simply type:  “bglcomp ForestFire.XML” at the command prompt.  The command-line BGLComp application will warn you if any of the tags in the XML file are invalid.

Step 3: Move the BGL File into ESP

Before you can see the effect, you must move the compiled ForestFire.BGL file to the proper folder.

To move the BGL File into ESP:

1. Navigate to the folder ...\Special Effects SDK\Samples.
2. Copy ForestFire.BGL.
3. Paste ForestFire.BGL into the scenery area add-on folder named ...Microsoft ESP\1.0\Addon Scenery\scenery. 
4. Copy the fx_ForestFire.fx file to the Microsoft ESP\1.0\effects folder. 
5. Fly from Sea-Tac airport (KSEA) to view the effect.