Guide: Siege University - 205: Fades

==Introduction==
Fading is the act of making nodes visible or invisible. It is an important part of a world that never has a loading screen - anytime you go into a house, cave, dungeon, etc., certain pieces of the terrain will need to disappear to allow the player to continue playing. Likewise, when players leave a dungeon or house, the terrain will need to re-appear. All objects and actors that are on terrain that is faded out will also be faded out. An important rule to remember is to never allow player characters to stand on faded out terrain, as they will no longer see their own characters, or be able to interact with their surroundings. 
==What You Need For This Tutorial==
*Dungeon Siege, updated to version 1.09B or later 
*Siege Editor, updated to version 1.09B.313 or later 
*A text editor 
==What This Tutorial Assumes You Have Already Learned==
*Guide: Siege University - 100: Tutorial
*Guide: Siege University - 200: Concepts and Terminology
*Guide: Siege University - 203a: Triggers I
*Guide: Siege University - 203b: Triggers II
*Guide: Siege University - 204: Moods
==What This Tutorial Will Teach You==
*How nodes are faded 
*How wildcards are used 
*How the Siege Engine tracks fades 
*How fades are manipulated in Siege Editor 
*Examples of common and advanced fades 
==Overview of Fades==
=== How Nodes Are Faded ===
Fades can be done three different ways: node flags, triggers, and elevators. 
====Node Flags====
The first method is very simple: a flag on the node can be set so that it will fade away if the node comes between the camera and the player's character. This is done by opening up the node properties when a node is selected, and making sure the checkbox "camera fade" is checked (under the "General" tab). The most common uses for this are doorway arches, or rock arches at cave entrances. If you use this, you should uncheck both "bounds camera" and "occludes camera" so that the node simply fades away and does not force the camera to move. 
====Fade Triggers====
The most commonly used method of fading is a fade trigger. By using triggers, we can fade as many or as few nodes as we want to, and they can be anywhere in the world; the player does not necessarily have to be close to the nodes being faded. 
A fade trigger needs to have a condition that is satisfied by a party member. There are three main conditions used for this: "party member within node", "party member within bounding box", and "party member within sphere". There are also conditions that deal with "trigger groups" that can be used, but "trigger groups" do not need to be used for fade triggers (refer to Siege U: 203B - Triggers II). You may see many examples of fade trigger groups in the Dungeon Siege maps, but changes near the end of the project rendered this an obsolete method of fading, and we just didn't have the time to convert them all to a more efficient method. 
The fade trigger's action can be fade_nodes or fade_nodes_global. Fade_node_outer_local_party will apply the fade to everyone who was not detected by the trigger, but is otherwise identical to fade_nodes. This was added as a feature during the design process, but ended up unused. Since it has not been used and tested thoroughly, it may not work as intended. Fade_node (not to be confused with fade_nodes) is legacy and will probably be removed from Siege Editor in the future. 
Fade_nodes is the most common method of fading because it is so powerful and applies only to the party members who were detected by the trigger (Result of Condition - see Siege U 203A). This is what the designer wants most of the time. Consider the entrance to a dungeon: anyone who walks down the stairs to the dungeon should see the terrain above the dungeon fade out. We do not want the party members who are still standing on that terrain outside the dungeon to have the fade applied to them - they would then be standing on faded-out terrain (a Bad Thing). 
Fade_nodes_global is like fade_nodes, except that it works for everyone, even people who join the game later. This exists for one specific situation: inside a dungeon, when a player walks near an unexplored room that has node caps on it. Node caps are black nodes which, when placed over a room, prevent the player from seeing into the room before they enter it. We usually place fade triggers near the entrances to these rooms to fade off the node caps when the player's in-game character approaches them. Unlike other fades, we want these nodes to fade away for everyone, forever--even if they join in the middle of the game, or if they are standing on the other side of the world. When these other characters go into that dungeon, they should see the revealed room, and not see node caps over it as if it had not yet been discovered. 
The parameters for fade_nodes_global are the same as fade_nodes. Be careful when you use fade_nodes_global; we use this for fading off node caps over dungeon rooms, and not much else. (Just FYI: The only way to undo a global node fade-out is with a global node fade-in.) 
====Elevators====
Elevators are covered later, after more terms are defined and examples are given. 
===Fade Fields In Siege Editor===
When you add a fading Action to a trigger in Siege Editor, there are five parameters to that Action: region GUID, Section, Level, Object, and Fade Type. 
====Region GUIDs====
Region GUIDs are 8-digit hexadecimal numbers that are unique to each region within the map. You can see the current region's GUID by looking at "region" under the "settings" menu. You can also find a region GUID in the main.gas file under world\maps\<map name>\regions\<region name>. 
====Section/Level/Object====
All nodes have three fading terms associated with them: Section, Level, and Object. To fade a node in or out, we have to refer to the region that the node is in (via the region GUID) and these three numbers. The labels (Section/Level/Object) are meaningless - the only thing important about them is that they give us a place to assign values to nodes, and refer back to them later. Since the names don't mean anything, when referring to these values, we simply refer to them by the three numerical values that they hold. Throughout this document, there will be sets of numbers listed like this: (5, 15, -1). This is simply an abbreviation for Section 5, Level 15, Object -1. The default setting for nodes is (1, -1, -1). While region GUIDs use hexadecimal; Section, Level, and Object values are decimal only. 
====Fade Type====
Fade Type has several options. Fade "out:black" will fade nodes completely out. Fade "out:alpha" will fade nodes out most of the way, leaving the nodes almost transparent. Fade "in" will cause nodes that have been faded out to fade back in. The "out:instant" setting is just like "out:black" except that the nodes do not fade smoothly away, they disappear instantly. "In:instant" works the same way, fading in nodes instantly. 
===A Simple Example Of A Fade===
A region with GUID 0x88993344 has many nodes, most of which are flagged as (1, -1, -1). There is one house in the region, and it has a roof flagged (1, 2, -1). A fade trigger could be set down in the doorway of the house with a condition of "party member within bounding box" and the action "fade_nodes." The bounding box would need to be rotated and sized appropriately (refer to Siege U: 203A - Triggers I), and fade nodes would need the following values: 
 Region GUID: 0x88993344
 Section: 1
 Level: 2
 Object: -1
 Fade Type: out:black 
Then when the player walks into the trigger, the roof should fade away completely, letting the player see the interior of the house. 
==Wildcards==
===Defining Wildcards===
So far in our discussion of fades, the "-1"value hasn't been explained. It's a little bit complicated because it has a double meaning. When nodes are flagged with -1, that value stands for "no value". So the default node flags of (1,-1,-1) really could be seen as (1,nothing,nothing). But -1 means something completely different when used in a fade trigger. When fading nodes, -1 is a wildcard. It can be read as "anything". This can be pretty powerful. 
===Using Wildcards, or Why Nodes Have 3 Fade Values===
Using wildcards can save a lot of time, and allow you to fade a large number of differently flagged nodes with a drastically reduced number of fade triggers. 
Here is an illustrative example:
A region has five houses near each other, and one of those houses has a dungeon in the basement. Most of the surface nodes in the region are flagged (1, -1, -1), and the dungeon nodes are flagged (2,-1,-1). The house roofs are flagged (1, 1, -1), (1, 2, -1), (1, 3, -1), (1, 4, -1), and (1, 5, -1). Each time a player walks into a house, they walk through a trigger that fades off the roof, and that looks how you would expect: (1, 1, -1) for the first one, (1, 2, -1) for the second, etc. When the player walks down into the dungeon, they walk through a trigger that looks a little different: (1, -1, -1). This means that the game will fade all nodes in that region that have (1, anything, anything). So with just one fade action, all of the house roofs fade away along with the rest of the nodes in the region. The dungeon doesn't fade away because it has a Section value of 2, not 1 (2, -1, -1). 
However, with the power of wildcards, there are some things to watch out for. Avoid overlapping fades. This can occur when you have one group of nodes faded out (example: (1, 4, 1)), then you fade out a second group with a wildcard that contains the first group (1, -1, -1). When you fade the second group back in (1, -1, -1), the first group will also do the smooth fade-in transition, then instantly go back to being faded out. This looks bad, and can be avoided by flagging the first group differently or using a different fade that doesn't include the first group. 
Wildcards can be used to group nodes together for fade purposes. Most of the time we leave all nodes within a region with a value of 1 for the <section>. That way if we add a dungeon entrance, and the player is going to go under the region, we can fade all nodes in the region with a fade trigger that fades out nodes that match (1, -1, -1). 
This begs the question, "Why don't we ever use (-1, -1, -1) to fade in or out all nodes in a region?" Using all wildcards in the fade values for a region is an easy way to fade out everything in a region, even if some nodes have very weird values that you stuck in there and forgot about later. 
So it appears to be a handy tool for fading...so why didn't we use it that way? Well, sometimes we do want to fade in all nodes in a region, but we can't fade them in with (-1, -1, -1) unless we also faded them out that way. We used to do this, but often an elevator or staircase would take us to the next region, and we would want to fade everything except the transition nodes, so we couldn't use (-1, -1, -1). 
Other times we were dealing with regions that could be entered from multiple directions. Leaving and entering the region from one direction might work just fine with (-1, -1, -1), but entering from the other side we might only want to fade in nodes that match (2, -1, -1). In this case we would first have to fade in (-1, -1, -1), then fade out everything except (2, -1, -1) if they had gone out the first direction, and that's just not what we wanted to do. With all of the region changes that we kept doing, we eventually switched to use (1, -1, -1) to refer to the bulk of the nodes in the region, because it was more flexible. 
More examples and possible uses for wildcards are given under Advanced Fading Scenarios. 
==How The Siege Engine Keeps Track Of It All==
The way that the engine handles fades isn't completely intuitive. By default, all nodes are visible. The engine maintains a list of nodes that are faded out for each player. Every time that a player walks into a trigger that fades OUT some nodes, the engine ADDS that group of nodes to the list. Every time a player walks through a trigger that fades IN some nodes, the engine REMOVES that group of nodes from the list. This can cause some unexpected behavior when using wildcards. The nodes that are faded out and the nodes that are faded in must match Section, Level, and Object values exactly, including wildcards. Here are a couple of examples to illustrate: 
* Half of the nodes are flagged as (1, -1, -1) 
* The other half are flagged as (2, -1, -1) 
* The player walks through a trigger that fades OUT (1, -1, -1) 
* The player walks through a trigger that fades IN (1, -1, -1) 
In this case, everything is fine. The nodes marked (1, -1, -1) are visible. Here is where expectations can cause confusion: 
* The player walks through a trigger that fades OUT (1, -1, -1) 
* The player walks through a trigger that fades IN (-1, -1, -1) 
Some of the nodes in the region are faded out, and then the player walks through a trigger that looks like it will fade in all nodes in the entire region. But since the fade out was done with (1, -1, -1), the engine doesn't find a match for (-1, -1, -1) and ignores that fade. So the end result of this situation is that the nodes are still faded out, which is probably not what the designer intended. 
==Fading Tools In The Siege Editor==
===An Easy-To-Use SE Fading Tool===
Select a node in Siege Editor and look at its Node Properties. Under the Fade Settings tab are the fields for Section, Level, and Object. There are also three buttons: Show, Hide, and Select. These buttons will perform their functions on all nodes in the region that match the fade values of the current node. This can be a great way to see what your fades will look like in-game without leaving the editor. 
Example: you have built a two-story inn, and you have flagged all nodes on the second floor as (1, 4, -1). Select a node that is part of the second floor of your inn, and press the "Hide" button, and you will get to see all nodes flagged the same as that node (presumably the whole second floor of the inn) fade away, showing what the player would see after entering the front door. You can make those nodes visible again by pressing the "Show" button. We commonly use this tool to fade away a large number of nodes quickly, so that we can check the fade values on the nodes that are still visible. The "Show All Nodes" command (accessed under the Node Menu) can also be very helpful when working with fades. 
There is a button on the toolbar that will hide/show all node caps in the region. This saves the designer from having to fade each group of caps separately when they want to edit the dungeon without the caps getting in the way. For those that are interested, the "Hide Caps" button simply references a node mesh list and hides all node meshes that match the "caps" list. This list is visible under the Node Menu, in Mesh List. "Caps" is one of the available groups, and node meshes can be added or subtracted on the Mesh List window. 
===A More Advanced SE Fading Tool===
"Node Fade Groups" (under the Node Menu) can be a powerful tool for an advanced user. Using this screen is a little complicated, but can make managing your fades a lot easier in the long run. The first thing to do on the Node Fade Groups screen is to create a new group with the "New Group" button on the right. The name doesn't matter; this is something that will stay local on your machine only. Once you have made a group, select it down at the bottom from the pull-down menu "groups". Type in any value you want for section, level, or object, and check the box next to any of the fields that you entered values for. Anything unchecked will function as a wildcard, matching on any value. You can then use the "add" button to add these values to the "fade settings" window. Any time that you select "hide," "show," or "select," all nodes that match the fade settings in the window will be hidden/shown/selected. So you could have a fade group for "castle interior" and another for "castle first floor," etc. This comes in handy when you have a lot of different fade values on nodes in a region, but want to toggle the visibility of those nodes easily. 
==Elevator Fades==
===Why Are Fade Triggers On Elevators Different?===
This is fairly complicated. Fade triggers work by noticing when a party member crosses the boundary of the trigger. This is true whether the trigger is "party member within node/sphere/bounding box", or even "party member entered trigger group". When players click to go somewhere, the engine figures out all of the steps that they will take to get there. The engine knows when they will cross into the trigger, even before they get there. It even sends this information to other player's computers in a multiplayer environment, as this keeps everything looking smooth for each player. 
When your character is going to walk through a trigger boundary, there is a point when your computer sends out information that your character will cross the trigger boundary. At that point, you will cross that trigger boundary no matter what. If you tell your character to stop or do something else, it will first cross the trigger boundary and then follow the new commands that they have been given. This means that if we set up fade/mood triggers on elevators as per normal (like with a "party member within node" condition), the trigger boundary would be on the edge of the elevator node. So when somebody gets close to getting on the elevator, they eventually cross the point of no return, and they WILL get on the elevator...even if it leaves just before they get on it. 
Why is it so bad to have someone jump on or off of an elevator just as it leaves? One case could be this: a fade trigger fades away all nodes around the elevator for all players who are currently on the elevator. If someone was just leaving the elevator, they could possibly get this fade, then make it off of the elevator on to the faded out nodes. They would then be stuck on faded-out terrain, which is very, very bad. There are similar cases where someone could jump ONTO an elevator, only to have missed some important fades, so that when he arrives at the destination, all nodes at the destination are still faded out for him. These types of situations could actually be game-breaking experiences (forcing them to reload)--something that should be avoided at all costs. 
===How Do You Set Fades (Or Moods) On Elevators?===
Elevators have two special lines in their "Template Properties" to allow the designer to trigger fades or moods when the elevator moves. Moving1ActionInfo is used for triggering fades and moods when the elevator from its original position to its destination. Moving2ActionInfo is used when the elevator moves back to its original position. The syntax for these lines is this: 
 [region GUID],[section],[level],[object],[fade type];
 [region GUID],[section],[level],[object],[fade type],[delay];
 [mood name];
 [mood name],[delay]; 
Any number of these fades and moods can be used, all on the same line. Just don't forget the semicolon at the end of each mood or fade. "Fade type" is just looking for values of "in", "out:black", etc., just like in the triggers. Both the fade and mood can have an optional delay (in seconds) afterwards. Here is an example: 
 Moving1ActionInfo = 0xA1000033,1,-1,-1,in;0xB1000012,3,4,-1,out:black,2.5;gpg_fh_r1_1; 
Here's what happens: as soon as the elevator leaves, the fade and mood that don't have delays specified get applied to all players on the elevator. So the nodes in region 0xA1000033 that are flagged (1, -1, -1) get faded in. Everyone on the platform gets mood gpg_fh_r1_1. Since the second fade has a delay of 2.5 seconds, after this time passes, everyone who was on the elevator when it started moving will get the nodes in region 0xB1000012 flagged (3, 4, -1) faded out. 
==Common Fading Scenarios==
A common fading situation is a set of stairs leading in and out of a dungeon. We usually place a fade trigger at the top of the stairs that will fade the dungeon out (no need to render a dungeon that you can't see, especially when you're leaving it), a fade trigger in the middle of the stairs to fade the dungeon in as well as the original region (to catch players going either direction), and a trigger at the bottom of the stairs to fade the original region out (for players entering the dungeon). This way the player can walk down the stairs and see the dungeon, or walk up the stairs and see the original region. 
Another common fading situation is a house. We went through several different methods of fading before we settled on a "best way," so if you look through the maps that shipped with the game, you might see several different methods in place. We didn't necessarily convert all the old fading methods to the newer methods if they still worked. The new way we ended up with is putting a small fade trigger around the doorway to the house. If a player walks through this trigger, the roof fades away. If there is a closed door in the way, we usually mark the trigger as initially inactive and make the door send a "we_trigger_activate" message to the fade trigger when it is opened. Farther away from the house, fade triggers are placed so that when the player walks through these triggers, the roof fades back in. 
That said, let's walk through setting up a two-story house to fade! 
==Practical Exercise: A Two-Story House Fade==
Open up a test region. Try placing some t_xxx_flr_08x08-v0 nodes down to get a nice area to walk around. Then place the house that we will use for our fading example: t_grs01_houses_generic-c-log-lv1. t_grs01_houses_generic-c-log-lv2 goes on top of this node, and t_grs01_houses_generic-b-roof-shingle makes a good roof. t_grs01_houses_generic-c-log-lv1-door-top can go in the doorway, and t_grs01_houses_generic-c-log-stairs will work for the stairs. 
Select the roof and look at its node properties. Under fade settings, set Section to 1 and Level to 2. Leave Object at -1 for all of the nodes in this example. Select the second floor and set it to (1, 1, -1). This example assumes that you don't have other nodes flagged as (1, 1, -1) or (1, 2, -1). If you have nodes flagged this way, simply substitute a different set of values for these nodes for this tutorial. Select the t_grs01_houses_generic-c-log-lv1-door-top node, open up the node properties, and go to the General tab. Turn off "occludes camera" and "bounds camera" and turn on "camera fade". Select each other house node in turn and turn off "bounds camera". 
Place a trigger_generic on the ground near the house. Go into the trigger properties, and click the "new" button in the lower left to add a new trigger to the gizmo. Select the new trigger by clicking on the text that says "trigger_0" under "trigger_generic" in the left panel. Click the "add condition" button on the right side and choose "party member within bounding box" from the drop-down list. Click the "add action" button on the lower-right and choose "fade_nodes" from the list. 
In the main Siege Editor window, select Region from the Settings menu, and copy the region GUID. Open the fade trigger back up and paste this value into the "region ID" field in the fade nodes action. Set Section and Level to 1, and the fade type to "out:black". Add another "fade nodes" action to the trigger, and copy the values from the other "fade nodes" action into it. Set the "level" field to 2, however, so that it will fade the roof. 
Now move the trigger into the doorway of the house. Make sure that your debug HUD settings allow you to see the bounding box around the trigger, and adjust the size of the bounding box to encompass the entrance to the house. Values of 1.5, 1, 1 for the "half diag x","half diag y", and "half diag z" fields should work. Leave the boundary check on "on_every_enter". Make sure that the trigger is rotated so that the box sticks out on to the stairs in front of the house. Now when the player comes up to the doorway of the house, the second floor and the roof will fade away, letting them navigate inside the house. 
Copy the entire trigger gizmo by clicking on it and choosing Edit->Copy (or pressing Ctrl-C), then paste (Ctrl-V) 3 new copies of it in front of the house. Set the "fade type" field in each of these triggers to "in", however, so that if the player walks through the bounding box, the second floor and roof will fade in. Now move the three triggers to form a "U"-shape around the entrance to the house, adjusting the size of the bounding boxes as necessary. If you don't want to bother with sizing them exactly, just set them to have dimensions of 5, 1, 0.25 each. You will have to move and rotate them so that as someone leaves the house, they have to pass through one of these bounding boxes before they have moved too far. Don't allow a "fade out" trigger to overlap a "fade in" trigger. 
Copy one of these trigger gizmos inside the house, and move it up on the landing halfway up the stairs. You will probably want to hide the roof and second floor nodes within the editor to make it easier to work inside the house. Open up the trigger properties and remove one of the fade nodes actions. Make sure that the remaining fade nodes action fades off (1, 1, -1) (the second floor). Now copy this trigger gizmo and place the copy next to it on the stairs. The idea is to have one trigger fade the second floor in (when you go up the stairs), and the other trigger fade it out (when you go down the stairs). 
This is accomplished by having both triggers be long enough to cover the stairs completely, but very thin (like .25 or .1 for their width). I used values of x = 1, y = .5, z = .1 for my triggers. Try placing the trigger that fades the second floor in right on the landing, and the trigger that fades the second floor out just slightly below the landing. Make sure that they cover all walkable area where they stretch across the stairs so that the player must walk through them. 
Try it out! You should have a fully fade-functional two-story house. 
==Advanced Fading Scenarios==
A castle is one of the most complex buildings to fade, as several things need to be taken into consideration. Whenever a player is on the outside of the castle, all they need to see is the outside of the castle. If the interior of the castle is faded in, the engine is doing a lot of unnecessary rendering. When a player goes into the castle, all floors above the player need to be faded away. However, the interior of each floor below them can be faded away as well, again to eliminate unnecessary rendering. With these issues in mind, this is how we divided up castles: 
* Each floor of the building should probably have all nodes flagged with the same [section], to make it easy to fade floors above the player's character. 
* On each floor, there will be "interior" areas that are far away from any outside windows or doorways. These should be flagged with their own [level] so that they are easy to fade away when the player is on a floor above them and can't possibly see these areas. The [object] flag can be set on a per-node basis when there is something like an archway on the interior of a floor of the castle that you might want to fade with a trigger. 
A large tower is another interesting case. Conceptually a tower is pretty easy to deal with. If the tower has five floors, then each floor can have all of its nodes flagged with a different Level, while keeping the same Section. So the floors could be something like this: (3, 1, -1), (3, 2, -1), (3, 3, -1), (3, 4, -1), (3, 5, -1). That way if you ever needed to fade the whole tower away, you could use (3, -1, -1). 
It should be noted that upon entering the tower, the trigger to fade off each floor above the player will actually need to have a separate fade_nodes action for each floor, rather than using a wildcard (when using this method). That way the fade triggers on each stairway can refer to the floor above them (fading in or out, depending on which way the player is moving), without having to deal with issues from overlapping fade values. 
There are some examples of tower fading in Dungeon Siege. Regions fh_r3 and path2dm in map_world (World.dsmap) have small towers, while mega_forest_r2 in multiplayer_world (MPWorld.dsmap) has a large tower with an elevator at the bottom. Region island in multiplayer_world has a medium-sized tower with an elevator at the top! 
==Conclusion==
Some of the concepts in this document are difficult to digest. I recommend experimenting with fades in a small, simple test map before trying anything too complicated. Setting up fade triggers in a 20-floor tower can take quite a while, even if you already have a lot of experience. Try starting with a simple field, where fade triggers will fade different pieces of the ground in and out when you walk through them. After that, try a few houses...maybe even a house with a second floor. Dungeons may or may not be difficult, depending on how many levels they have, and how many rooms have node caps. 
There are plenty of fading examples to look at in map_world (World.dsmap): 
* Examples of towns: bt_r1, path2dm, nt_r1, df_r0, and dc_r1 are all regions that have houses or dwellings in them. 
* Examples of dungeons: cr_r1 is a dungeon with a large number of capped rooms, sd_r1 and sd_r2 are both dungeon regions with two floors and elevators. 
There are plenty of examples in the other regions as well, but if you can understand and emulate the fading being done in these regions, you will be well on your way to becoming a Fading Master. 
Category:Dungeon Siege Editor