Siege FX Reference Script Architecture/Terminology

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

Introduction

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:

http://dsc.conflict-imminent.com/dlcounter/odtrack.php?url=http://dsc.conflict-imminent.com/tutorials/sfx/term_reference.zip

- 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:

[efect_script*]

{

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

script =[[ //Open the script.

Declaration

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:

//MAGNETO STAFF\\

[effect_script*]

{

name =abr_mag_staff;

script =[[

if(!#WEAPON_TYPE_STAFF)
{

exit;
}

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.

]];

}

//MAGNETO STAFF CURVE\\

[effect_script*]

{

name =mag_curve;

script =[[

sfx create curve #TARGET

"curvature(1)model(0)scale(.1)color0(1,.5,.8)

ts(2)tlength(20)";

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.

Resources

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)

· Game-Editing.net 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.

Credits

· 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.

Siege FX Tutorial #3

Targets

By: Aaron 'Jomdom' Ransley
Created: 1/15/2003

Introduction

In this installment, we will be discussing targets. How do you get your effects to go where you want them to? Shout at the code and mash the keyboard? That works, but very rarely. Instead, I will attempt to teach you the correct way to assign effects to targets. You will need to be familiar with the Stack, so if you haven’t read that tutorial yet, go ahead and do that now.

Notes: You might notice the lack of the Lingo section in this tutorial. The formatting is also a bit smaller than the last few tutorials. I hope it isn’t too dramatic of a change.

Taking a Peek

Please note this script is very un-optimized, it is being used because it is a good example of how targets work.

Let’s take a look:

[effect_script*]

{

name = halo;

script =[[

sfx create orbiter #TARGET

"radius(2.5)phi(0)iphi(40)itheta(0)color0(1,1,0)

offset(0,.3,0)scale(.05)invisible()";

sfx attach_point #PEEK bip01_head target;

set $orb1 #PEEK;

sfx start #POP;

sfx create fire #TARGET

"flamesize(3)color0(1,.3,1)color1(0,0,0)

scale(1)velocity(0,0,0)alphafade(.3)

count(100)accel(0,0,0)";

sfx rat #PEEK;

sfx target #PEEK $orb1 target;

sfx start #POP;

]];

}

Break it Down

Let’s go to the most important part of the script first; where the effect goes:

sfx create orbiter #TARGET

#TARGET and #SOURCE macros can yield different results depending on how the script is called into existence, and what it is run on. In this case, #TARGET is the player.

The next important thing in the script is where on the player the effect goes:

sfx attach_point #PEEK bip01_head target;

This tells the Siege FX engine (sfx) to attach (attach_point) the effect (#PEEK) to the players head (bip01_head) using the effect’s target (target).

Then, we have attaching the fire to the orbiters:

sfx rat #PEEK;

sfx target #PEEK $orb1 target;

It’s confusing isn’t it? Why do we use the (target) command on one effect, and the (attach_point) command on the other? You can think of it as a hierarchy.

First, we have the player (#TARGET). The player has a bunch of special bones to attach to. We use (attach_point) to get a certain bone we need (bip01_head) and hook the effect to it.

Secondly, we have the player again (#TARGET). We don’t want the player this time though. Let’s tell the Siege FX engine (sfx) to remove all targets (rat) from the effect (#PEEK).

Now that we have a clean slate, we can reassign targets. This time, we don’t want to go any further than just assigning a target, because an orbiter doesn’t have any special bones to attach to. We tell the Siege FX engine (sfx) to use the command (target) on the effect (#PEEK) assign a new target ($orb1) on the effect’s target (target). Since there are no special bones to attach to, we are done assigning targets.

In the end, we have an orbiter rotating around the player’s head, with fire attached to it that fades out slowly, so it looks as though we have a halo above the players head. Like I said earlier, it isn’t needed. You could easily just use a fire base effect using the radius parameter to achieve almost the exact same thing.

That wraps it up for now!

Resources

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)
• Game-Editing.net 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

Expect the next tutorial to cover some sneaky tricks with the Siege FX engine.

Credits

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

Siege FX Tutorial #2

The Stack

By: Aaron 'Jomdom' Ransley
Created: 1/6/2003

Introduction

In this tutorial, we will be discussing the Stack. As always, any code will be in red and in a different font. I will try to keep code from within a text-heavy paragraph to a minimum, and save it for its own paragraph.

Lingo

- Stack: The stack is the device that Siege FX uses to store effect data. I can’t think of any way to explain better than Icemage once did.

“You can think of this like a stack of plates - as we create effects, we put each effect onto the stack, the same way you would put plates that have been dried in a stack.” - Icemage

The Stack

As Icemage said, “...as we create effects, we put each effect onto the stack…”

Let me elaborate. Say we create an orbiter, one of the 22 base effects. It would automatically be entered into the stack (if it doesn’t have any errors that is). Here is an example:

[effect_script*]

{

name =orbs;

script =[[

sfx create orbiter #TARGET

"color0(1,1,1)scale(.25)radius(0)";

set $orb1 #PEEK;

sfx start #POP;

sfx create orbiter #TARGET

"color0(1,1,1)scale(.25)radius(0)";

set $orb2 #PEEK;

sfx start #POP;

sfx create orbiter #TARGET

"color0(1,1,1)scale(.25)radius(0)";

set $orb3 #PEEK;

sfx start #POP;

sfx create orbiter #TARGET

"color0(1,1,1)scale(.25)radius(0)";

set $orb4 #PEEK;

sfx start #POP;

]];

}

“Eh?” you say? No kidding.

Alright, first off, understand that this effect doesn’t actually do anything, and if it did, it wouldn’t consist of anything more than creating 4 white orbiters at its target, directly on top of each other.

So, lets break it down.

You see that after I create the orbiter, define it’s location of creation, and it’s parameters, I go on to say:

set $orb1 #PEEK;

sfx start #POP;

Let’s break this down further… By writing:

set $orb1 #PEEK;

I tell the Siege FX engine to create a variable (something to contain the effect for quick referencing) out of whatever is on top of the stack. It effectively peeks at the top of the stack to check what’s there… Since we just created an orbiter, it is currently king of the stack. While we are talking about variables, I might as well mention that whenever you define a variable, it should be structured like so:

set ;

This means that if you want to create a variable to store a color, you can do this:

set $green .3,1,.3;

And it will store that color value inside the variable for later use in the script.

Getting back on track... Next we have this line:

sfx start #POP;

This is telling the Siege FX engine to ‘start’ what ever is on top of the stack, but ‘pop’ it off so it’s not on the stack anymore. If we then tried to use another command to look for the effect, you wouldn’t find it, because someone knocked it off the stack, and made a huge mess! Some people!

Here is an example of an invalid way of using the #POP and #PEEK commands.

set $orb1 #POP;
sfx start #PEEK;

We create a variable by using the data from the top of the stack, currently the data from the last effect we created, but ‘pop’ it off at the end, because we are supposedly done using it… Wrong.

The next line tries to start whatever is currently in the stack, but there is nothing there! Jeepers! It must be because someone made a mistake and knocked the effect off the stack too soon.

Slick Stack Slingin’

Think your hot stuff? Try this on for size:

[effect_script*]

{

name =technicolor_orbs;

script =[[

set $color4 .5,.5,.5;

set $color3 0,1,0;

set $color2 0,0,1;

set $color1 1,0,0;

sfx create orbiter #TARGET

"color0($color4)scale(2)radius(0)";

sfx create orbiter #TARGET

"color0($color3)scale(2)radius(0)";

sfx create orbiter #TARGET

"color0($color2)scale(2)radius(0)";

sfx create orbiter #TARGET

"color0($color1)scale(2)radius(0)";

set $orb3 #POP;

set $orb2 #POP;

sfx start $orb2;

sfx start $orb3;

]];

}

What color will the pile of orbs be when the script is complete? If you can figure that out, you’re done with the tutorial. If you can’t, just keep decoding it, because everything here has been covered so far.

See you next time!

Resources

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)

· Game-Editing.net 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

Expect more and more advanced tutorials in the future. Enough said J

Credits

· Icemage - You have really helped me with the more advanced aspects of Siege FX. I thank you, Icemage.

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