// Teleport Functions
// Author: Malachai Moonshadow (aka Brian S Jones)
// 7/14/2002
// Save this script as tp_functions and then you can include them in
// your scripts for any area in the module.
// oPC - The player object to teleport
// ToLocation - The Tag name of the waypoint you are teleporting too
// intGraphicExit - The Visual Effect to use when the player teleports out
// intGraphicEnter - The Visual Effect to use when the player teleports in
// fDelay - How long to wait to teleport the player after activating teleport
void Teleport(object oPC, string ToLocation, int intGraphicExit, int intGraphicEnter, float fDelay)
   {
     // Gets the location as location of the waypoint with the tag ToLocation
     location lLoc = GetLocation(GetObjectByTag(ToLocation));
     // Sets up the Area Transition - only needed if going to another area.  Doesn't hurt to
     // have it in their if ToLocation waypoint is in the same area.
     SetAreaTransitionBMP(AREA_TRANSITION_RANDOM);
     // Applies the graphic to the location where the player activated the portal
     ApplyEffectAtLocation(DURATION_TYPE_INSTANT,EffectVisualEffect(intGraphicExit),GetLocation(oPC));
     // Waits fDelay seconds before jumping the player to location
     DelayCommand(fDelay, AssignCommand(oPC,JumpToLocation(lLoc)));
     // These commands make sure all companions follow the teleport.
     AssignCommand(GetAssociate(ASSOCIATE_TYPE_ANIMALCOMPANION,oPC),JumpToLocation(lLoc));
     AssignCommand(GetAssociate(ASSOCIATE_TYPE_DOMINATED,oPC),JumpToLocation(lLoc));
     AssignCommand(GetAssociate(ASSOCIATE_TYPE_FAMILIAR,oPC),JumpToLocation(lLoc));
     AssignCommand(GetAssociate(ASSOCIATE_TYPE_HENCHMAN,oPC),JumpToLocation(lLoc));
     AssignCommand(GetAssociate(ASSOCIATE_TYPE_SUMMONED,oPC),JumpToLocation(lLoc));
     // Applies the graphic to the location where the player is teleported too
     ApplyEffectAtLocation(DURATION_TYPE_INSTANT,EffectVisualEffect(intGraphicEnter),lLoc);
   }

// This function returns a string of a waypoint that is used to pass into the Teleport function.
// This function was created to make matching up teleports and wayports easier.
// Before you can use this function, you need to create your teleports and waypoints.
// I have tested this function with placeables as the teleport.  You can have multiple teleports
// or just one
//
// Place an object in your area with the tag TP_1_2
// Place a waypoint with the tag WP_2_1.  This is the destination point
// If you want the player to be able to teleport back and forth, you need two teleports and two
// waypoints.  Use the format TP_#1_#2 and WP_#2_#1.  It doesn't matter if they are in sequence or not
// just as long as the teleport and waypoint destination numbers are reversed.
//
// Example:
// Teleport   Waypoint
// TP_1_2     WP_2_1
// TP_3_4     WP_4_3
// TP_9_8     WP_8_9
//
// I haven't tested with anything other than single digits.
//
// The string strTP that is being passed in is the Tag name of the object calling this function.
// In the example above strTP would equal WP_2_1.
//
// I added the integer intRandom to simulate random teleporting.  I have a total of 12 teleporters
// in one area, named TP_1_2, TP_2_1, TP_2_3, TP_3_2 etc up to TP_5_6, TP_6_5 with matching
// waypoints.  When I pass in the number 6 (the last sequence in my TP tag names) it will select
// a random waypoint as a destination.  If you are going to use the random function, make sure
// all numbers in the sequence are represented.  For example, if you wanted to teleport between
// two random locations, make sure you have two waypoints labeled WP_1_2 and WP_2_1.  If a random
// number is selected that doesn't have a waypoint to match nothing will happen.
string GetTeleportWayPoints(string strTP, int intRandom)
{
       // String variables
       string strWayPoint;
       string strTo;
       string strFrom;
       // If the random function is not used
       if (intRandom == 0)
          {
          //Get the numbers in the TP tag.
          //   First create strCoor as a substring of strTP, taking off the first three characters.
          //   If we passed in TP_1_2 strCoor would equal 1_2 after this command.
          string strCoor = GetSubString(strTP, 3, (GetStringLength(strTP) - 3));
          //   Search through strCoor and return the position of the '_' character.  This will
          //   return 2.
          int intUnder = FindSubString(strCoor, "_");
          //   Now get the numbers that were passed in.  If TP_1_2 is passed in, we would get
          //   2 and 1.
          strTo = GetSubString(strCoor, 2, intUnder);
          strFrom = GetSubString(strCoor, intUnder - 1, (GetStringLength(strCoor) - intUnder - 1));
          //   We now set the waypoint variable to "WP_" plus the second number of the TP tag name
          //   plus another "_" and then the first number of the TP tag name.
          //   If we passed in TP_1_2, strWayPoint would contain WP_2_1.
          strWayPoint = "WP_" + strTo + "_" + strFrom;

          }
       else
       // else if the random function is used.
          {
          // Generate a random integer between 1 and the number passed in.
          int intTelTo = Random(intRandom - 1 ) + 1;
          int intTelFrom = Random(intRandom -1) + 1;
          // Convert the values into strings
          strTo = IntToString(intTelTo);
          strFrom = IntToString(intTelFrom);
          // Now just concatenate the values together to get a valid waypoint.
          strWayPoint = "WP_" + strTo + "_" + strFrom;
         }
     // We return the generated waypoint as a string.
     return  strWayPoint;
   }
// End of the include script