Guide: Siege University - 302: Teleporters & Displacers

== Introduction ==
Teleporters are really an advanced elevator type. A strong word of caution is in order: the Siege Engine was never intended to allow teleporting, and this elevator bends that rule pretty far. The explanation for these elevators assumes that the reader has experience with other elevator types. Not all aspects of these elevators will be spelled out in this section, since there is significant similarity to the simpler elevators. The large differences will be covered, and guidelines will be given for their use. 
=== What You Need For This Tutorial ===
* Dungeon Siege, updated to version 1.09B or later
* Siege Editor
* A test map
=== What This Tutorial Assumes You Have Already Learned ===
* Siege U: 204 - Moods: Understanding how to use moods is a requirement for setting up teleporters.
* Siege U: 206 - Elevators: Teleporters are really just specialized elevators. You should have some practice with normal elevators before attempting to build a functional teleporter.
=== What This Tutorial Will Teach You ===
* Building Advanced Elevators
* Preserving System Performance
* Elevator Restrictions
* Field Definitions
== Overview - Instant Elevators (Hub/Displacer Elevators) ==
=== No Loading Screens Means Constant Loading, But In Small Chunks ===
We have an engine that does away with loading times by constantly loading new stuff on the edge of the frustum as the player moves along. If they were able to move very fast (or teleport), there would suddenly be a whole lot of stuff to load. Far too much; especially in a multiplayer environment where the server would take a massive performance hit. If the frustum were much, much smaller, then this would be plausible. A very small frustum (a 5 meter radius frustum, as opposed to the default 45 meter radius frustum) means that very little content is loaded, so having the player teleport somewhere would not load much-maybe just the nodes adjacent to them, and the objects in those nodes. This is acceptable even on low-end machines. 
=== A Tiny Frustum Is The Answer ===
So how could we get away with having a small frustum? If the frustum was very small, the player could easily see the edge of the world, breaking their immersion in the game. The answer is to pull the fog in even farther. With the fog pulled in to mask the edge of the world, the player now can't really see anything but their own character. To keep the player from feeling too frustrated by this, we put them in a situation where they can't move around anyway: an elevator ride. Now they can't go anywhere, and we can play special effects as we bring the fog and frustum in to explain why the environment is changing around them. After they teleport, we use a mood with a very long transition time (over 20 seconds) that will push the frustum back out to 45 meters. 
=== States Involved ===
When these elevators move, they go between 4 states. We created these specifically to function as the hub and displacer platforms in multiplayer_world. State 1 is on the ground at location 1, state 2 is in the air at location 1, state 3 is in the air at location 2, and state 4 is on the ground at location 2. The duration of the moves from state 1 to state 2, and from state 3 to state 4 is something that you can set in the elevator gizmo. However, the transition from state 2 to state 3 happens instantly. 
== Restrictions To Keep In Mind ==
=== There MUST Be A Player On The Elevator ===
A player has to be on the elevator if it is going to continue to function after it teleports. Otherwise, the elevator leaves all active frustums and stops getting updates. (This typically results in the companion elevator not completing its transition from state 3 to state 4 - it just stays "stuck" up in the air at state 3.) So a very important restriction to keep in mind is that for instant elevators to function correctly, a player must actually ride the elevator. 
=== Elevators Can't Connect To The Same Door At The Same Time ===
Normally this situation doesn't come up, but now that we have two elevators using the same nodes, it's important to point out. When you move an elevator, it connects to the door of the node that you specified. If there is another node already connected there, it will be unloaded, which is scary and bad. If you are standing on a node when it is unloaded, suddenly you will be completely disconnected from the rest of the game world, floating in void. To avoid this possibility, we have two doors on each of the nodes used in the teleport process. Each teleport pad has two doors; one will use door 1 for each connection along its path, and the companion teleport pad will use door 2 for each connection. 
== Explanation Of The Fields ==
The fields in the instant elevator are rather numerous, but they are similar to the simpler elevators. One of the major differences is that the elevator gizmo needs to know how to move both elevator plates. These elevators were meant to work in pairs. When you activate one elevator, the companion elevator is also going to move - they are going to swap places. They each have their own elevator gizmo. This means there are quite a few fields to fill out (each gizmo needs to know all of the nodes and doors involved). Not all fields are listed below, due to their similarity to regular elevators. Remember, location 1 refers to where the elevator node starts. Location 2 refers to the destination for the elevator. Elevator node is the teleport pad itself (the elevator gizmo should be associated with this node). Elevator 2 (or e2) is the companion elevator node, which starts at the destination of the current elevator node. 
=== Important Note About Messaging ===
When the elevator gizmo moves from state 1 to state 2, it calls that location 1 moving to level 2. It moves from state 2 to state 3 without providing any "hooks" for messaging. When it goes from state 3 to state 4, it calls that location 2 moving to level 1. On the return trip, state 4 to 3 is location 2 moving to level 2, and state 2 to state 1 is location 1 moving to level 1. If you are going to be using the messaging fields, this is important to understand. other_elevator: the SCID of the elevator gizmo controlling the other displacer node. Entering this information allows both elevators to switch places simultaneously. Otherwise only one elevator would move, and then there would be overlapping nodes, something that the engine was never designed for. (read: Very Bad) up_effect: the name of a special effect script to play when the elevator moves from state 1 to 2. (see Siege U: 212 - SiegeFX for special effects information) down_effect: the name of a special effect script to play when the elevator moves from state 3 to 4. For an example of the values for every field (except the messaging fields), refer to Appendix A. 
== How To Keep It From Slowing The Game Down Too Much ==
Make sure that the player has a mood with a small frustum by the time they teleport to their new location. This is totally necessary. Things that can help system performance beyond this involve keeping the destination area clear of all extraneous clutter. The idea is to reduce the amount of loading when they arrive at their new location, so try to keep the number of textures/actors/meshes/etc. that will be loaded down to an absolute minimum. For an example of a good area, look at the hub elevator in region "des_r1" in the multiplayer_world map. When they get a mood that pushes the frustum back to a normal radius, you can make it take longer than the elevator ride. In most cases, the player will be more concerned with being able to move around than waiting for the fog to get pushed back to its full distance. 
== Conclusion ==
Congratulations! You now know how to set up the most complicated elevator we created. You should also now understand how to keep system performance in mind when creating a teleporter. An example has been provided in Appendix A. If you are having trouble setting up a working teleport elevator, try following the example as closely as you can. 
== Appendix A: An Example ==
The following are some sample values for nodes, and how each field would be filled out in the appropriate elevator gizmos. If you have never set up a teleport elevator before, fire up SiegeEditor, plunk down these nodes in a region, and follow along. Hopefully this will help answer remaining questions that you might have. 
The base node for the example will be t_th01_teleport-hub-bottom-plate-a. The elevator node will be t_th01_teleport-hub-elevator-a. 
Elevator gizmo: elevator_instant_4s_1c. 
Location A:
t_th01_teleport-hub-bottom-plate-a node GUID: 0xa0001111.
t_th01_teleport-hub-elevator-a node GUID: 0xa0002222.
elevator_instant_4s_1c SCID: 0xaaaa1111.
Location B:
t_th01_teleport-hub-bottom-plate-a node GUID: 0xb0008888.
t_th01_teleport-hub-elevator-a node GUID: 0xb0009999.
elevator_instant_4s_1c SCID: 0xbbbb2222.
Here is how the elevator gizmo at location A would be set up:
other_elevator: 0xbbbb2222
elevator_node: 0xa0002222
elevator_door_location1_level1: 1
elevator_door_location1_level2: 1
elevator_door_location2_level1: 1
elevator_door_location2_level2: 1
This elevator will use door 1 to connect to the nodes along the way, the companion will use door 2. This we avoid any possibility that they will try to connect to the same node at the same time via the same door.
duration_location1_moving_to_lv1: 16
duration_location1_moving_to_lv2: 3
duration_location2_moving_to_lv1: 16
duration_location2_moving_to_lv2: 3
The times for the duration aren't set in stone, they just need to keep the game feeling smooth. You could have the durations for "moving to level 1" take longer, to give yourself more time to transition to a new mood. The reason for "moving to level 2" being 3 seconds: it doesn't need to take a long time to bring the fog/frustum close to the player, but 2 seconds seemed to be a bit too fast for slower systems. Sometimes they would only show a frame or two while moving up, and couldn't really tell what was going on until they had already teleported.
e2_elevator_node: 0xb0009999
e2_elevator_door_location1_level1: 2
e2_elevator_door_location1_level2: 2
e2_elevator_door_location2_level1: 2
e2_elevator_door_location2_level2: 2
connect_node_location1: 0xa0001111
connect_door_location1_level1: 9
connect_door_location1_level2: 11
e2_connect_door_location1_level1: 10
e2_connect_door_location1_level2: 12
connect_node_location2: 0xb0008888
connect_door_location2_level1: 9
connect_door_location2_level2: 11
e2_connect_door_location2_level1: 10
e2_connect_door_location2_level2: 12
up_effect: hub_plate_up
down_effect: hub_plate_down
Material
Material is provided just like the normal elevators (in case you want to use it).
location1_moving_to_lv2_ActionInfo: moodname_1
location1_moving_to_lv1_ActionInfo: moodname_teleport
location2_moving_to_lv2_ActionInfo: moodname_2
location2_moving_to_lv1_ActionInfo: moodname_teleport
The mood named moodname_teleport should be a mood with a short transition time (around 1 or 2 seconds) that brings in the frustum and fog to a very small radius. Moodname_1 and 2 are moods that should have long transition times (at least 10 seconds, though more than 20 seconds would be preferable in most situations) that will push the frustum back out to a normal radius.
Here is how the elevator gizmo at location B would be set up:
other_elevator: 0xaaaa1111
elevator_node: 0xb0099999
elevator_door_location1_level1: 2
elevator_door_location1_level2: 2
elevator_door_location2_level1: 2
elevator_door_location2_level2: 2
duration_location1_moving_to_lv1: 16
duration_location1_moving_to_lv2: 3
duration_location2_moving_to_lv1: 16
duration_location2_moving_to_lv2: 3
e2_elevator_node: 0xa0022222
e2_elevator_door_location1_level1: 1
e2_elevator_door_location1_level2: 1
e2_elevator_door_location2_level1: 1
e2_elevator_door_location2_level2: 1
connect_node_location1: 0xb0008888
connect_door_location1_level1: 10
connect_door_location1_level2: 12
e2_connect_door_location1_level1: 9
e2_connect_door_location1_level2: 11
connect_node_location2: 0xa0001111
connect_door_location2_level1: 10
connect_door_location2_level2: 12
e2_connect_door_location2_level1: 9
e2_connect_door_location2_level2: 11
up_effect: hub_plate_up
down_effect: hub_plate_down
Material
location1_moving_to_lv2_ActionInfo: moodname_2
location1_moving_to_lv1_ActionInfo: moodname_teleport
location2_moving_to_lv2_ActionInfo: moodname_1
location2_moving_to_lv1_ActionInfo: moodname_teleport
The elevator gizmos are triggered via a we_req_activate message, just like normal elevators.
==Appendix B: Tips==
*Place use_points for the lever/button that will activate your teleporter, and make sure that they are on the elevator node. This will help ensure that somebody rides the elevator (which is mandatory for it to work correctly).
*Keep the terrain in a landing zone simple.
*Allow yourself 2 or 3 "shrubbing" objects to help spruce up the terrain in a landing zone, but no more. Make sure they don't use many textures.
*If there is an expensive object or texture that must exist at the destination, place a copy of it at the origin, perhaps out of sight of the player. That way it will already be loaded before they even use the teleport.