id.sdk [FX]



Making DOOM 3 Mods : FX

FX decls, are relatively easy to write by hand. The hard part about fx files is trying to explain just what they are and how they are used. The simple way to think of them is as particle spawners (which is why they are listed under particles), but they can actually do quite a bit more. Robert originaly wrote the FX system because he needed a way to easily sequence special effects, mostly for the 'spawn in' effect. There is nothing that you can do with the FX system that can't be done some other way, but FX decls tend to execute faster, and tend to be easier to create.

An FX decl is made up of one or more FX Actions. The different types of FX Actions are:

Spawn or modify a Light
Spawn a particle, model, or entity
Start a sound
Drop a decal
Shake the Player
Launch a projectile

When an effect starts, it will start all the FX actions after the specified delay. So you could spawn a blue particle immediately, start a sound after half a second, spawn a light after a second, spawn some more particles after 3 seconds, and fade out the light after 4 seconds. Which is exactly what this file does:

fx fx/example {
    {
        delay 0
        duration 1.0
        particle "blue.prt"
    }
    {
        delay 0.5
        restart 0
        duration 1.0
        sound "randomsound"
    }
    {
        delay 1.0
        restart 0
        duration 5.0
        name "somelight"
        light "lights/somelight", 2, 2, 2, 500
        fadeIn 1
    }
    {
        delay 3.0
        restart 0
        duration 0.1
        particle "someparticle.prt"
    }
    {
        delay 4.0
        restart 0
        duration 5.0
        useLight "somelight"
        fadeOut 1
    }
}

All effects are attached to an entity, so anything it creates (lights, particles, sounds, etc) start at the origin of the entity (plus whatever offset is defined). It's is possible to instead attach the effect to a particular joint with the "bindto" keyword. This should be in the "global" section outside any FX actions. See "skulltrail.fx" for an example.

The most complicated set of effects are the ones that happen when a monster spawns in. That complex sequence with the lightning and sounds and lights is all done with fx declarations. The code simply says "create a spawn effect here." The specific fx that it uses is in the entityDef for the monster, and the code to spawn it is in monster_base.script, somewhere around line 480.

FX decl keywords

name <string>	The name of this action
delay <time>	How long (in seconds) after starting the effect before this action happens
shake <time> <amplitude> <distance> <falloff> <impulse>	Shake the player around a bit. Take a look at hkwalk.fx for a good example of this.
ignoreMaster	Don't shake the entity this effect is attached to
random <min>, <max>	A random time added to the delay.
fire <sibling>	Causes the sibling action to happen when this action does. This is a way of synching two random actions. See smallsparks.fx
duration <time>	How long the action lasts before it is killed or restarted
restart <bool>	Set to 1 if the action starts again after the 'duration' has run out
fadeIn <time>	Fade in the RGB of the light or model over <time> seconds
fadeOut <time>	Fade out the light/model. Ignored if fadeIn is set, you can use 2 seperate actions (tied together with uselight) if you want a light to fade in and out.
offset <x>, <y>, <z>	Offset from the origin of the entity (or bind point) this action is located at
axis <x>, <y>, <z>	Axis of the model, mutually exclusive with angle
angle <pitch>, <yaw>, <roll>	Alternate way of setting the axis of the model
rotate <angle>	Not used
light <material>, <red>, <green>, <blue>, <radius>	Create a light
noshadows	The light in this effect doesn't cast shadows
attachlight <light>	Attach to external light (a light not defined in the effect) for fading. This is what causes all the lights to fade in/out in alphalabs 2
attachentity <entity>	Attach to an external entity. Not actually used in Doom 3
launch <entity>	Launches a projectile. Not actually used in Doom 3, but I suppose it could be used to create a neat mario jumping lava effect.
uselight <sibling>	Modify the light values in a sibling action. Can be used to fade out a light that faded in earlier.
useModel <model>	Modify the model in a sibling action. Can be used to fade out a particle in a sibling.
model <model>	Creates (or fades in) a model
particle <model>	Same as model
decal <material>	Applies the specified decal to the ground (and anything else in the area)
size <int>	Size of the decal
trackorigin <bool>	Move around with the entity (vs stationary after spawning)
particleTrackVelocity	Not used
sound <sndshader>	Start a sound (on any channel)