Friday, January 2, 2009

Siege FX Reference Script Architecture/Terminology

Siege FX Tutorial #1

By: Aaron 'Jomdom' Ransley, and Trailstorm Radeem.
Created: 1/10/003


This document will cover script structure and terminology, invented by myself and Trailstorm Radeem. We feel that the Dungeon Siege community has no real terminology to use in conversations relating to Siege FX scripts. We will list terminology and structure for an entire Siege FX script, start to finish. Proper indentation practices are also shown as the script progresses. Also, keep in mind that this is meant to be a reference more than a tutorial, so not every aspect of Siege mentioned will be explained with great detail.

Note: Some Siege FX commands already have names, or don’t need any. We will be covering mostly uncharted territory, although you might see a few little tidbits that we decided to rename. We hope this doesn’t cause any confusion.

We really hope this reference will become a standard, so if you enjoy it, please do your best to pass it on to anyone that is interested in Siege FX. If you need to link to the .zip file on my site, please use the following URL:

- Script Architecture -

Here, we are going to go over the names of the different sections of a Siege FX script.

Script Header

The script header comprises of this section on code:



name = example_script; //Define the name of the script.

script =[[ //Open the script.


In the declaration section, we create variables for use in the script:

set $color0 1,1,.3; //Store the value 1,1,.3 inside the variable, $color0 for use in the script later on.
set $size [0];
//Get the first p-param in the parameter string, whatever that may be.

Effect Block: Pre-Block

In the pre-block section, we will declare the base effect, and it’s location like so:

create fire #TARGET //Create a fire base effect at #TARGET.

Effect Block: Parameters

In the parameter block, we define all the parameters for base effect it is paired with:

instant()color0($color0)scale($size)ts(3)”; //Use these parameters in the parameter block.

Effect Block: Post-Block

In the post-block, we set out targets, store our completed effect in a variable, and anything else that is required before you start the effect:

sfx rat #PEEK; //Remove all targets from the fire’s memory.
sfx target #PEEK ap_trace01 target;
//Redefine the target, creating the fire to attach to the end of the weapon the script is called on.
set $fire #PEEK; //Store the effect in a variable. Not actually needed, just explaining how to do it.
sfx start #POP;
//Start the effect.

Script Footer

In the script footer, we wrap up the script:

]]; //Close the script.


Take note of the block pre and post notations. All the data from the pre-block to the end of the post-block is considered an effect block. This script comprises of 1 effect block.

- Further Terminology -

Now that we have covered the architecture of a Siege FX script in detail, let’s break it down further with terminology.

Passed Variables

Variables passed between/into scripts using this method are called pass-parameters, or p-params. Using this method won’t be explained here, but is a very good way to optimize your scripts. Think of creating a script that looks for a p-param for it’s color, speed, scale, ect. Think of being able to call the script from a template, putting data into those p-params to be passed. You could use the script over and over again and get different looks each time, because your p-params are different. Trailstorm Radeem, a close friend of mine, and the co-author of this reference, is a true pioneer of utilizing this method.

Here is syntax example of grabbing a p-param after its data has been defined in the template:

set $scale [0]; //Store the first value that was passed into the script from the template in the variable named $scale.

Repeater Scripts

A repeater script is something that I have used, and plan to continue using them, in my Cosmetics line of mods. There really isn’t an analogy I can use to explain it, so I have to get technical. A repeater script works like so:

· The repeater script is initially started.

· The script then calls what is to be repeated.

· Then the repeater script calls itself over again and repeats the process.

Lets built on this, and take a look at a script that uses this method:




name =abr_mag_staff;

script =[[



pause .5; //Pause the script for half a second.

call mag_curve; //Call the script that is to be repeated.

call abr_mag_staff; //Call this same script over again.






name =mag_curve;

script =[[

sfx create curve #TARGET



sfx target #PEEK target;

sfx attach_point #PEEK ap_trace01 target;

sfx attach_point #PEEK ap_trace02 source;

sfx start #POP;



There isn’t much explaining to do… The script ends up repeating over and over again with a half second delay. The reason we don’t just call ‘mag_curve’ over and over again from itself is simply because the repeater script acts as a great hub if you wish to control many repeating scripts from there. There are times that you do not need a repeater script, though.


These are various resources I find very useful.

· Dungeon Siege's Main Site (Take a look around. Contains various mod resources, as well as the Dungeon Siege Toolkit)

· Dungeon Siege Forums (If you plan of modifying Dungeon Siege, this is the place to be. Make sure to make use of the search function.)

· Siege FX Siege University Course (Contains a list of the 22 base effects, a list of all possible parameters for those 22 base effects, and more. A great resource indeed.)

· Dungeon Siege Cosmetics (Home of this tutorial.)

· Jomdom's E-mail (Feel free to e-mail me with any questions you have about this tutorial.)

In the Future

Although this reference doesn’t really fit into the progression of the tutorials I am doing, it isn’t meant to. More tutorials are on their way, so hold tight.


· Icemage - Thanks for the input on the terminology.

· Trailstorm Radeem - It was a great idea to make such a reference!

· Gas Powered Games - You make a killer effects engine! Great job! Can’t wait for Dungeon Siege 2's version of Siege FX.



My Blog List