FX System

[Dragofer]

[Just posted this on Discord, but I think it'd also be good to post here since the FX system seems to be almost unknown.]

I've just (again) come across the fx system, which is quite a neat way of coordinating a sequence of particles, sounds, lights etc. to appear without having to script or make a cascade of trigger_relays. All it takes is an fx definition like this:

fx fx/sparks
{

	{
		delay 0
		duration 0.5
		restart 0
		light "lights/sparks_sound", 1, 1, 1, 96
		offset	0, 0, 0
	}
	{
		delay 0
		sound "security_camera_spark"
		duration 2.5

	}
	{
		delay 0
		duration 2.5
		restart 0
		model "sparks.prt"
		//fadeout 1.5
		//particle "sparks.prt"
	}		   
}

This goes into an .fx file (renamed from .txt) in the fx/ folder. A func_fx entity with an "fx" "fx/sparks" spawnarg can be triggered ingame to play it.

Oddly, TDM only has a total of 11 fx (+1 if you also count all FMs), of which half are thunder-related. The system has barely been used for anything else than thunder, even though there are in fact quite a few entities, other than func_fx, that support calling fx:

- moveables can have an fx_collide spawnarg
- AIs can have fx_on_death and fx_on_ko
- func_fracture entities can have fx
- security cameras can have fx_damage and fx_destroyed
- anims can trigger fx on specific frames with the fx keyword
- respawning items can have fxRespawn (might be a Doom3-exclusive thing)
- the player's view can have fx applied via script, i.e. an fx with a shaking effect

There's seemingly no documentation of fx on the TDM domain and no real support for fx in DR. But documentation can be found in this article on iddevnet, and in a way this post could be considered a nucleus for TDM-specific documentation.

Edit: iddevnet.com has gone down, but you can find a backup on the TDM server: http://ftp.thedarkmod.com/backup/iddevnet.zip

P.S.: what probably goes well with fx_collide on moveables is the script_collide spawnarg. Could maybe be used to make a fragile object?

More examples of fx in the spoiler:

Spoiler

fx fx/smallsparks
{
    {
        restart 1
        random 0.5, 3.5
        duration 5
        rotate 0.1
        model "particles/smallfiresparks.prt"
        fire blue
    }           
    {
        delay 1000000
        name blue
        duration 5
        rotate 0.1
        model "particles/smallbluesparks.prt"
    }           
}


fx fx/tdm_smallfire
{
        bindto "Head"
    {
        delay 0
        duration 10
        restart 0
        light "lights/roundfire", 0.74, 0.58, 0.25, 250
        offset    0, 0, 10
        //fadeIn  2
                fadeOut 3
                trackorigin 1
    }


    {
        delay 0.2
        duration 10
        restart 0
        rotate 0.1
        model "sparks.prt"
        trackorigin 1
        offset    0, 0, 96
    }

    {
        delay 0
        duration 10
        restart 0
        rotate 0.1
        model "sparks.prt"
        trackorigin 1
        offset    0, 0, 96
    }           

    {
        delay 0.3
        duration 10
        restart 0
        rotate 0.1
        model "sparks.prt"
        trackorigin 1
        offset    0, 0, 96
    }           


}


fx fx/tdm_flame
{

    bindto "Head"
        {
        delay 0
        duration 10
        restart 0
        light "lights/roundfire", 0.2, 0.6, 0.3, 300
        offset    0, 0, 5
        //fadeIn  2
                fadeOut 3
              
    }


}

fx fx/smallsparks1
{    
    bindto "RightHand"
    {
        restart 0
        //random 0.5, 3.5
        duration 1
        rotate 0.1
        model "sparks.prt"

    }           
}

fx fx/thunder
{
    {    //creates light
        delay 0
        name "thunderlight1"
        duration 0.4
        restart 0
        light "lights/biground1", 0.35, 0.35, 0.7, 99999
    }
    
    {    //removes light
        delay 0.4
        name "thunderlight1off"
        duration 0.3
        restart 0
        uselight "thunderlight1"
        fadeOut 0.05
    }
    
    {    //creates light
        delay 0.3
        name "thunderlight2"
        duration 0.4
        restart 0
        light "lights/biground1", 0.35, 0.35, 0.7, 99999
    }
    
    {    //removes light
        delay 0.4
        name "thunderlight2off"
        duration 2.5
        restart 0
        uselight "thunderlight2"
        fadeOut 0.05
    }
    
    { // sound
        delay 1.5
        name "thundersound"    
        sound "thunder"
        duration 10
    }
}

fx fx/thunder_skylight
{
    {    //creates light
        delay 0
        name "thunderlightsky1"
        duration 0.4
        restart 0
        light "lights/biground1", 1, 1, 1, 250
    }
    
    {    //removes light
        delay 0.4
        name "thunderlightsky1off"
        duration 0.3
        restart 0
        uselight "thunderlightsky1"
        fadeOut 0.05
    }
    
    {    //creates light
        delay 0.3
        name "thunderlightsky2"
        duration 0.4
        restart 0
        light "lights/biground1",1, 1, 1, 250
    }
    
    {    //removes light
        delay 0.4
        name "thunderlightsky2off"
        duration 2.5
        restart 0
        uselight "thunderlightsky2"
        fadeOut 0.05
    }
}


fx fx/thunder_distant
{
    {    //creates light
        delay 0
        name "thunderlight1"
        duration 0.4
        restart 0
        light "lights/biground1", 0.2, 0.2, 0.3, 99999
    }
    
    {    //removes light
        delay 0.4
        name "thunderlight1off"
        duration 0.3
        restart 0
        uselight "thunderlight1"
        fadeOut 0.05
    }
    
    {    //creates light
        delay 0.3
        name "thunderlight2"
        duration 0.4
        restart 0
        light "lights/biground1", 0.2, 0.2, 0.3, 99999
    }
    
    {    //removes light
        delay 0.4
        name "thunderlight2off"
        duration 2.5
        restart 0
        uselight "thunderlight2"
        fadeOut 0.05
    }
    
    { // sound
        delay 2.5
        name "thundersound"    
        sound "thunder_distant"
        duration 10
    }
}

fx fx/thunder_skylight_distant
{
    {    //creates light
        delay 0
        name "thunderlightsky1"
        duration 0.4
        restart 0
        light "lights/biground1", 1, 1, 1, 150
    }
    
    {    //removes light
        delay 0.4
        name "thunderlightsky1off"
        duration 0.3
        restart 0
        uselight "thunderlightsky1"
        fadeOut 0.05
    }
    
    {    //creates light
        delay 0.3
        name "thunderlightsky2"
        duration 0.4
        restart 0
        light "lights/biground1",1, 1, 1, 150
    }
    
    {    //removes light
        delay 0.4
        name "thunderlightsky2off"
        duration 2.5
        restart 0
        uselight "thunderlightsky2"
        fadeOut 0.05
    }
}
fx fx/thunder_close
{
    {    //creates light
        delay 0
        name "thunderlight1"
        duration 0.4
        restart 0
        light "lights/biground1", 0.5, 0.5, 0.8, 99999
    }
    
    {    //removes light
        delay 0.4
        name "thunderlight1off"
        duration 0.3
        restart 0
        uselight "thunderlight1"
        fadeOut 0.05
    }
    
    {    //creates light
        delay 0.3
        name "thunderlight2"
        duration 0.4
        restart 0
        light "lights/biground1", 0.5, 0.5, 0.8, 99999
    }
    
    {    //removes light
        delay 0.4
        name "thunderlight2off"
        duration 2.5
        restart 0
        uselight "thunderlight2"
        fadeOut 0.05
    }
    
    { // sound
        delay 0.5
        name "thundersound"    
        sound "thunder_close"
        duration 10
    }
}

fx fx/thunder_skylight_close
{
    {    //creates light
        delay 0
        name "thunderlightsky1"
        duration 0.4
        restart 0
        light "lights/biground1", 1, 1, 1, 400
    }
    
    {    //removes light
        delay 0.4
        name "thunderlightsky1off"
        duration 0.3
        restart 0
        uselight "thunderlightsky1"
        fadeOut 0.05
    }
    
    {    //creates light
        delay 0.3
        name "thunderlightsky2"
        duration 0.4
        restart 0
        light "lights/biground1",1, 1, 1, 400
    }
    
    {    //removes light
        delay 0.4
        name "thunderlightsky2off"
        duration 2.5
        restart 0
        uselight "thunderlightsky2"
        fadeOut 0.05
    }
}

 

 

[grayman]

Is all of this in the Wiki?

[Dragofer]

@graymanNo, I'm not aware of anything dedicated specifically to the fx system on the wiki. I've just written this not long after seeing that the security camera code looks for "fx_damage" and "fx_destroyed" spawnargs (which don't exist in the current entityDef).

Several search functions later it turned out that several other entity types also have code to trigger fx in specific situations (like the "fx_collide" spawnarg on moveables), and that only very few fx exist so far across core assets and all FMs. The main one is thunder.

The iddevnet article will pass as documentation until we have the fx system wikified.

[grayman]

Cool, thanks. Is there a link in the wiki to that article?

[Goldwell]

That's very helpful Dragofer! Thanks for this!

[Dragofer]

Wellingtoncrab wrote about his experiences with fx on Discord, reposting it here so it doesn't get buried:

Quote

The fx system does seem like it has a lot of potential. Couple of hurdles I ran into messing around with writing one is I couldn't find any success with setting  the "restart" keyword to 1 actually making the fx action loop in game - the would only ever play once. There is a "repeat" spawn arg you can put on the func_fx entity which does make it loop at a fixed interval, but once the fx was triggered I couldn't get it to then turn off when targeted from a switch like separate speakers/emitters/lights would. I think I might still be too lizard brained for this one.

Looks like there are some flaws in the system. Would be good to know what they are, maybe they can be fixed. Making the func_fx repeat at random intervals and stop repeating when triggered is probably something I can do.

[HMart]

Looking at the c++ code the restart only seems to set a new delay and set the time to the current time then continue is called to go to the top of the for loop.

if ( fxaction.restart ) 
{
    if ( fxaction.random1 || fxaction.random2 ) {
    	totalDelay = fxaction.random1 + gameLocal.random.RandomFloat() * (fxaction.random2 - fxaction.random1);
    } else {
    	totalDelay = fxaction.delay;
    }

    laction.delay = totalDelay;
    laction.start = time;
}

continue;

perhaps this continue triggers when restart is used? Is called before the code above in the for loop

//
// see if it's delayed
//
if ( laction.delay ) 
{
	if ( laction.start + (time - laction.start) < laction.start + (laction.delay * 1000) ) 
	{
		continue;
	}
}

The logic that I read in that is, if the amount of time that passed, is less than, total of delay, don't do the FX effect.

So if you want to restart the effect, you set delay to zero?

Also looking at the Doom 3 fx files, I have yet to see one, where restart is set to 1, could be a unfinished feature, why, because all Doom 3 fx effects that I saw, seem to be a do once forget effects, mostly used for the monster teleport/spawn effect.

Also searching through all the Doom 3 scripts the only place where startFx() is used is in the ai_character.script and ai_monster_base.script, again only for the teleport effect. 

Edited February 17 by HMart

[VanishedOne]

I've used FX before: the priest in ITB has a melee attack involving a hammer of holy fire, which briefly spawns a dynamic light. I agree the system is surprisingly little used.

One of my ideas (inspired by the footprints in Down By the Riverside) was for an invisible monster that would leave decal footprints via frame commands for FX bound to the foot joints. I ran into a minor drawback when I discovered the decal command applies a random rotation, so it would have to be a generic blob instead of a footprint shape. But with a big blob, and some sparks, and maybe a screen shake, I think it could still be effective.

[Dragofer]

iddevnet.com has gone down at long last, so anyone wanting to learn about the FX system has the following options until we have our own documentation:

Use the Wayback Machine:
https://web.archive.org/web/20200613234848/https://www.iddevnet.com/doom3/

Download the website as a .zip from moddb:
https://www.moddb.com/downloads/iddevnet-archive

Download the website as a .zip from the TDM server:
http://ftp.thedarkmod.com/backup/iddevnet.zip