Guide: Siege University - 206: Elevators

==Introduction==
In Dungeon Siege, an elevator is a moving node. Any node can be an elevator; it just needs an elevator gizmo to control it. The elevator gizmo contains information about the nodes and connections needed to move the elevator to the destination and back. When the elevator gizmo receives a we_req_activate message, it will move the elevator node. After the elevator reaches its destination, the next time the elevator gizmo receives a we_req_activate, it will move again. 
==Different Types of Elevators==
There are different types of elevator gizmos, depending on how the nodes involved with the elevator are connected. We have broken up the description of the connections involved into three terms: states, connections, and nodes. 
States refer to the number of different places where the elevator will stop moving. This is usually two; most elevators simply go back and forth between two places. 
Connections refer to the number of doors that the elevator node will need to use to establish a union at each destination. If an elevator node lands in a space between two nodes, both of the nodes next to the elevator will need to establish a connection to allow the player to walk to them. In this case, we would want to use a two-connection elevator gizmo. 
Nodes are designated blocks of distance that the elevator will be moving between. Sometimes an elevator goes between two different doors of the same node; in this case we would want a one-node elevator gizmo. Other times an elevator travels between totally separate nodes; in this case we would want to use a two-node elevator gizmo. 
When viewing the elevators, make sure that you are using the "development name" view (under View | Preferences, in the "Content Display" field). Then you will see elevators named with the "2-state, 2-connection, 1-node elevator" style names. 
===Elevator Template Property Field Names And What They Mean===
These field names have been taken from the 2-state, 2-connection, 2-node elevator. Depending on which elevator you use, you may have more or less fields to fill out, but these fields should serve to show how elevators work. If there are extra fields in the elevator you use, they will be similar to these. Often the node being used as an elevator is referred to as "elevator_node," and the node that will be used for a connection to the elevator is "connect_node". Level1 is the term used to identify the origin of the elevator, and level2 is the destination. 
:elevator_node: The GUID of the node being used as an elevator 
:elevator_door_level1: The first door that the elevator will use to connect when it returns to its original position 
:elevator_door_level2: The first door that the elevator will use to connect at its destination 
:elevator_additionaldoor_level1: The second door that the elevator will use to connect when it returns to its original position 
:elevator_additionaldoor_level2: The second door that the elevator will use to connect at its destination 
:connect_node_level1: The GUID of the node that begins connected to the elevator node 
:connect_door_level1: This is the door that the connect_node_level1 will use to connect to the elevator node when the elevator node returns to its original position 
:additional_node_level1: The GUID of the second node that begins connected to the elevator node 
:additional_door_level1: The door that the additional_node will use to connect to the elevator node when the elevator node returns to its original position 
:connect_node_level2: The GUID of the first destination node 
:connect_door_level2: The door that the connect_node will use to connect to the elevator at the destination 
:additional_node_level2: The GUID of the second node at the destination 
:additional_door_level2: The door that the additional_node will use to connect to the elevator at its destination 
(The more complicated elevators may have more connections that need to be filled in, but they are named with names that make sense, and these fields have helpful instructions in the "documentation" field in the template properties on the same line as the field.) 
:duration: This important field describes how long (in seconds) it will take the elevator to move from one state to another. If this is set near 0, the node will appear to teleport, and unpredictable things can happen. This can cause bad things to occur with multiplayer games and lag, so always keep the duration on elevators at 2 seconds or more. 
:oneshot_nowait: Set to true if you want 'waitfortrigger = false' to happen only once; essentially making the elevator move once on its own (when it comes into the frustum) 
:Moving1ActionInfo and Moving2ActionInfo: These fields can be used to fade nodes or change moods for characters on the elevator. This is a very useful thing to do. If someone is inside a cave or building, and they are taking an elevator to a lower floor, it may be required to fade out the upper floor. This field would be used to apply the correct fade to the characters on the elevator. Instructions for doing this are explained in detail in Siege U: 205 - Fades.
:level1_waitfortrigger: Defaults to true; set to false if you want the elevator to move without receiving a we_req_activate message when it arrives at level 1 
:level2_waitfortrigger: Defaults to true; set to false if you want the elevator to move without receiving a we_req_activate message when it arrives at level 2 
:level1_connectpaths: Defaults to true; set to false if you want keep the elevator from connecting to adjacent nodes at level 1. This would make it so that actors can NOT walk off of the elevator at this level. 
:level2_connectpaths: Defaults to true; set to false if you want keep the elevator from connecting to adjacent nodes at level 2. This would make it so that actors can NOT walk off of the elevator at this level. 
:level1_trans2_hint: Elevators can rotate on any axis when they move. This can be fun to play with...don't be afraid to try out some of these values. If you want them to rotate, specify one of these values here:
 AH_NONE
 AH_XAXIS_POSITIVE
 AH_XAXIS_NEGATIVE
 AH_YAXIS_POSITIVE
 AH_YAXIS_NEGATIVE
 AH_ZAXIS_POSITIVE
 AH_ZAXIS_NEGATIVE
:level2_trans1_hint: See level1_trans2_hint 
Elevators are capable of sending messages just like triggers. The four times that they can do this are labeled Level1, Moving1, Level2, and Moving2. 
:Level1: When the elevator returns to its origin.
:Moving1: When the elevator begins moving from its original position to its destination.
:Level2: When the elevator arrives at its destination.
:Moving2: When the elevator begins moving back to its origin. 
Each of these events has three fields associated with it: Message, Scid, and Message_Delay. 
:Message: the type of world event message to send. (see Siege U: 203A - Triggers I)
:Scid: the receiver of the message
:Message_Delay: this is the delay in seconds before the message will be sent. We put in a default value of -1 that can be used to wait for the MCP delay. This delay is roughly equivalent to the amount of time that needs to pass in a multiplayer game before the server is sure that everyone made it on or off of the elevator platform. Lag can vary this time, but it is usually around 0.5 seconds. 
Material: this allows you to reference elevator sound calls listed in sounddb.gas in the elevator section. When the elevator moves, it will play this sound.
===An Example===
This example is taken from region ce_r2 in map_world. There is an elevator in the castle that allows the party to descend to the dungeon. A 2-state, 1-connection, 2-node elevator is used here. Two states: the elevator will either be connected to the castle (at the top), or the dungeon (at the bottom). One connection: the elevator will only connect to one node at the top, and one node at the bottom. Two nodes: the node that the elevator will connect to at the top is different than the node that the elevator will connect to at the bottom. Now it is just a matter of filling in the required values, which look like this: 
 elevator_node = 0x20B459F4
 elevator_door_level1 = 1
 elevator_door_level2 = 2
 connect_node_level1 = 0x2B47E614
 connect_door_level1 = 3
 connect_node_level2 = 0xF0613FE4
 connect_door_level2 = 4
 duration = 5
 material = sd_large
It takes five seconds to move from the top connection node (0x2B47E614) to the bottom connection node (0xF0613FE4). If you look at the elevator in the Siege Editor, you can turn on Door Numbers under View Preferences and see why it made sense to use these doors for the connection in this case. (This example does not provide the Moving 1 or 2 ActionInfo, as the fades involved with the castle can be kind of complicated.) 
==Practical Exercise: Create A Simple Elevator==
This example is provided to give you a step-by-step set of instructions that you can use to create an elevator in a test map. The nodes used will be a 24-meter high ledge with an elevator going from the base straight up to the top.
===Place The Nodes===
These nodes are found under Terrain Nodes/generic/ledge in SE.
# Fire up your test map and place this node on the side somewhere: t_xxx_ledg_24-ele-top-a. 
# Connect t_xxx_ledg_24-ele-bottom-a Door 5 to Door 1 of the first node. If you want, you can place t_xxx_ledg_24-ele-wheels-a on Door 11 of t_xxx_ledg_24-ele-top-a to make it look better. File:SEU206-01.JPG
# Connect t_xxx_ledg_ele-platform-a Door 2 to t_xxx_ledg_24-ele-bottom-a Door 8. You may want to tile out some t_xxx_flr_04x04-v0 or t_xxx_flr_08x08-v0 nodes at the top or bottom just to have more room to walk around. File:SEU206-02.JPG
===Place The Gizmos And Levers===
# Place a 2-state, 1-connection, 2-node elevator gizmo (Game Objects/gizmos/elevator) on the elevator platform node. File:SEU206-03.JPG
# Place use_points (Game Objects/gizmos/special) on the ground next to the elevator, both at the top and bottom. File:SEU206-04.JPG
# Place a third use_point on the elevator platform.
# Place a lever_on_off_01 (Game Objects/gizmos/interactive_tools) on the ground at the top, and rotate its x-axis 270 degrees (Object Properties | Rotation tab), so that it is resting on the ground. File:SEU206-05.JPG
# Copy this lever to the node at the bottom. File:SEU206-06.JPG
===Set Up The Elevator Gizmo===
Now we are going to hook up the elevator gizmo with the actual elevator nodes. First, select the elevator platform node, then click on Node Menu | Properties and copy the Node GUID from the General tab. 
Select the elevator gizmo on the platform and open its properties. Select the "Template Properties" tab and scroll down to the elevator_2s_1c_1n_act_deact section.
Fill in the blanks! 
:elevator_node: Paste the Node GUID you copied here.
To make things simple, since the elevator can use Door 1 to connect to both the top and bottom nodes, that's what I'll use. 
:elevator_door_level1: 1
:elevator_door_level2: 1
Switch away from the Object Properties window (Alt-Tab will work) and copy the bottom elevator node's GUID. Switch back to the gizmo's properties and continue filling in the fields.
NOTE: Sometimes leaving a Properties window open and switching the focus away can cause erratic behavior (such as the Properties window not accepting text entry) when the focus returns to it. If this happens, simply close the window and reopen it.
The elevator is starting at the bottom, so the bottom node is at "level 1". It uses Door 7 to connect to the elevator node's Door 1. 
:connect_node_level1: Paste the new Node GUID you copied here.
:connect_door_level1: 7
Go grab the upper elevator node's GUID.
The upper node is the destination of the elevator, so it's "level 2". It uses Door 9 to connect to the elevator node's Door 1. 
:connect_node_level2: Paste the new Node GUID you copied here.
:connect_door_level2: 9
The upper node is the destination of the elevator, so it's "level 2". It uses Door 9 to connect to the elevator node's Door 1.
What we have just done is wire the elevator gizmo to move the elevator platform from the bottom ("level1") of the cliff to the top ("level2"). We specified which doors to move between, picking the logical doors on each node.
File:SEU206-07.PNG
(don't forget - GUIDs won't match since they are unique per map)
Back to the blanks...the elevator's duration can be whatever you feel like, so I'll set it to five seconds. That tells the gizmo to take five seconds to transition between the bottom and top. 
:duration: 5
Close the gizmo's properties -- we're done configuring it. 
===Set Up The Levers===
Now we need to set up the levers at the top and bottom of the elevator to activate it. The settings below need to be mirrored on both levers, unless specified otherwise. Go ahead and open the bottom lever's properties and scroll down to the on_off_level section. 
First, let's set the reset time to be slightly longer than the elevator ride. The duration is 5 seconds, so let's set these to 5.5 seconds. That means that after you use the lever, you won't be able to use the lever for another 5.5 seconds. This should make sure that the elevator is ready to travel again. Something to keep in mind is that if you are designing a multiplayer map with levers at the top and bottom, you may want a longer delay on the levers - this would keep one player from pulling the lever so often that another player can never get off of the elevator. 
:reset_time: 5.5
:reset_time_2: 5.5
The levers simply need to send a we_req_activate message to the elevator when they are clicked on...but they keep track of whether you are turning the lever "on" or "off". To force them to just send the same message in both states, just make sure that on_message and off_message are both set to the same message. Also fill in the Scid of the elevator gizmo so that the levers send to the correct recipient. 
:On_Scid: 0x00000009 On_Message: we_req_activate Off_Scid: 0x00000009 Off_Message: we_req_activate 
So far, both levers are configured the same.
File:SEU206-08.PNG
(don't forget - Scids won't match since they are unique per map)
===Wire use_points to the levers===
The levers should have use points specified to make them easier to use. We use use_points with elevators to ensure that the when the player is standing ON the elevator and throws the switch to activate it, they don't run OFF the elevator. You can have multiple use_points per object and multiple objects per use_point. If that is confusing, it should become clear after this next section. 
# Copy the bottom use_point's (not on the elevator platform) Scid.
# Open the bottom lever's Properties and scroll down to the "Placement" section of the "Template Properties" tab.
# Paste the use_point's Scid into the use_point_scid field value.
# Copy the elevator platform's use_point Scid.
# Paste the second Scid into the same field, with a comma between them.
File:SEU206-09.PNG
What you should see now is the bottom lever wired to both use_points (labeled as "use point # 0" and "use point # 1"). Now that this lever has two use_points, the player's character will move to the closest use_point when the player clicks on the lever. If he is standing on the elevator, he'll move to the elevator point; if he is not on the elevator, he will stay off of it.
File:SEU206-10.JPG
Repeat this for the upper lever, using the upper use_point and the same elevator platform use_point. 
===Test Your Elevator!===
You have wired a simple elevator! Save and tank your map and test it out in Dungeon Siege. A couple of answers for questions you will probably have after testing your map:
# If you placed the wheel contraption (t_xxx_ledg_24-ele-wheels-a), the wheel is constantly spinning. That is because we didn't tie the elevator gizmo into its animation activation/deactivation. We didn't cover that since it was an optional feature.
# Using one off-the-elevator use_point for the lever can result is a silly look. If you stand on the opposite side of the lever from the use_point and click on the lever, your character will run AROUND the lever before activating it. The solution is to add more use_points to the lever to cover likely directions that the player will approach the elevator from.
==Special Elevators==
There are three special types of elevators that are different than the rest of the generic elevators: act_deact (pressure plate) elevators, hidden stair elevators, and instant (hub) elevators. 
===act_deact (Pressure Plate)===
Pressure plate elevators are also named act_deact elevators because they take a we_req_activate to move to their destination, and a we_req_deactivate to move back to their origin. These were developed for pressure-plate-triggered elevators, where there could conceivably be a large number of conflicting messages going to the elevator while it is in transit (someone could be walking on and off the pressure plate rapidly.) Most elevators will ignore messages while they are moving, but these elevators will remember the last message sent to them. If the message is telling the elevator to move to where it is already going, it will ignore the message. If the message is telling the elevator to move back to where it came from, it will do that after it gets to its destination. 
===Hidden Stairs===
Stairwell elevators (listed as "specialty hidden stairwell") have a very large number of connections in the elevator gizmo; this is intended to be used for a few very specific nodes. The nodes involved always have their doors labeled in a consistent manner. Even though there are a lot of fields in this elevator gizmo, since it was set up for one particular node, it will always use the same door connections. The best way to set this up is to copy from an example. There are examples in regions "path2crypts" and "cr_r1" in the "map_world" map. The only things you would change are duration, messaging, and node guids. 
===Instant (Hub)===
Instant elevators (Hub/Displacer Elevators) are worthy of a 300-level Siege U doc. They incorporate fading, moods, and elevators. The designer is required to be familiar with much more of the engine than is required for a 200-level course. If enough demand (and time) is there, a 300-level document may be called for and created. 
==Conclusion==
We have covered how elevators work, the types of elevators, and defined the fields associated with them. We walked through building a simple elevator. Finally, we briefly discussed special elevators, though not in much detail. Elevators are fairly straight-forward, so practice is the best way to learn more about them.
Happy modding! 
The Gas Powered Team 
==Appendix A: Tips==
*If you want your elevators to be easy to use, consider placing a lever on the elevator itself, as well as a "call button/lever" at each place the elevator stops. This will ensure that any player that gets access to the elevator will be able to move the elevator. 
*When setting up fades in the elevator, remember that most elevators should remain faded in at all times for all players, so that they can see where the elevator is, even when they are not riding it. 
*Rotating elevators are often more interesting than elevators that just move straight up and down. Either use the rotation hint fields, or enter the door connection information so that the elevator node will be forced to rotate as it moves. That is, if the elevator has Door 1 on the left, and Door 2 on the right, try connecting them in reverse order at the destination. The elevator node will spin as it moves so that the doors line up correctly when it arrives. 
*If you want to have several nodes move at the exact same time, you can set up an elevator gizmo for each node, and send them we_req_activate messages all at the same time. However, you might notice that they are out of sync sometimes. This can be fixed by moving them more than once: the first time that an elevator moves, the engine creates an internal data structure that tells it where and how to move the elevator. If the engine does many of these at the same time, it could mean that it finishes with some of them earlier than others, and starts moving some elevators earlier than others. This is where the oneshot_nowait field can come in handy. If you set this to true, as soon as the elevator enters the frustum, it will move. So if you have several elevator nodes at location 1 that need to move to location 2 at the same time, consider starting them at location 2 with oneshot_nowait = true. They will move to location 1 as soon as they enter the frustum (normally at a distance too far away for the player to see). Their next transition (back to location 2) should have no problems synchronizing. 
*If you are ever working with a very tall elevator shaft, the destination of the elevator node might be out of the frustum. Consider changing to a mood with a larger vertical frustum before the player reaches the elevator, to stream in the destination. As the player walks away from the elevator, you can have them walk through a mood trigger that changes the frustum back to the normal size.
Category:Dungeon Siege Editor