Scripted waypoints

Overview
Scripted waypoints builds on the current waypoints system by making the arrival at each waypoint call a script. There are no special requirements for preparing this – it will work with any NPC using the regular default scripts and any new or previously placed set of walkway points.

Quick refresher of the standard waypoint system: Creatures will automatically walk along a sequence of waypoints that are tagged according to the following convention: “WP__##”. The NPC will begin the journey at waypoint 1 and continue traveling sequentially to waypoint n, and then back again in reverse.

Basic Useage
In the new “scripted waypoint” system, whenever a creature reaches a waypoint, it calls a script that is named very similarly to the tag used for the waypoints, like this: “wp_”. Notice there is just one script for the entire set of waypoints. If the script does not exist, then nothing additional happens and the NPC simply walks back and forth through the set of waypoints.

Below are some examples of “scripted waypoints” scripts:

Example 1. This script tells the NPC to stop at every waypoint and face in the direction the waypoint is facing and pause 1 second before continuing to the next waypoint. Notice the inclusion of “ginc_wp” which has a number of helpful functions such as FaceAndPause.

void main {   int iCurrentWP = GetCurrentWaypoint; FaceAndPause(iCurrentWP, 1.0f); }
 * 1) include "ginc_wp"

Note how we call GetCurrentWaypoint which returns the waypoint we have just reached. This will typically always be the first thing called in a “scripted waypoints” script.

Example 2. This is a more complex script that completely overrides the normal waypoint behavior and demonstrates how each waypoint can be individually scripted. It accomplishes the following: When the NPC reaches waypoint 1, he will sit down for a few seconds, and then randomly travel to one of the other waypoints in the set other than the first. When the NPC reaches waypoint 2, he will play a “get low” animation, and then proceed to waypoint 1. When the NPC reaches waypoint 3, he will simply head back to waypoint 1. If there are more than 3 waypoints in the set, then when the NPC reaches one of those he will behave in the default way.

void main {   int iCurrentWP = GetCurrentWaypoint; int iNextWP; switch (iCurrentWP) {       case 1: iNextWP = Random(GetNumWaypoints-1) + 2; SetNextWaypoint(iNextWP); ActionPlayAnimation(ANIMATION_LOOPING_SIT_CROSS, 1.0, 7.0); break; case 2: SetNextWaypoint(1); ActionPlayAnimation(ANIMATION_LOOPING_GET_LOW, 1.0, 4.0); break; case 3: SetNextWaypoint(1); break; } }
 * 1) include "ginc_wp"

Note in this example the use of SetNextWaypoint. The “next” waypoint is the one the NPC is enroute to. SetNextWaypoint allows us to override this and redirect the NPC to an alternate waypoint.

The script template “wp_tag” is available in the script templates directory in source safe. Simply copy and paste it with the proper script name, replacing the word “tag” with the tag of the creature that will be walking waypoints.

Advanced Usage
How to have two or more creatures with different tags walk the same set of waypoints: To override the initial waypoint set a creature uses, simply set a local string variable “WP_TAG” on the creature with the value of the desired waypoint set to use. So, if you have a bear waypoint set for a creature tagged “bear”, you could get a chicken to also walk these waypoints by setting the chicken's local variable WP_TAG to “bear”. Note that this variable is only checked when the creature is first spawned, so changing this value via script will have no effect.

How to change the set of waypoints a creature walks dynamically: You can change the set of waypoints a creature walks at any time via script using this function: object SetWWPController(string sWalkWayPointsTag, object oCreature=OBJECT_SELF);

So from the previous example, we could have our chicken walk the bear’s waypoints by calling this function in script: SetWWPController(“bear”);

How to pause/restart a creature walking waypoints. To stop a creature from walking waypoints, use: SetWalkCondition(NW_WALK_FLAG_PAUSED, TRUE);

You may also want to clear all actions, otherwise, the creature will still complete his pending actions which will take him to whatever the next waypoint is.

To Restart a creature walking waypoints, use: SetWalkCondition(NW_WALK_FLAG_PAUSED, TRUE);

The creature should get started on his next heartbeat.

How to create a road network: The basic outline for a script like this is available in the script template “wp_road_walker” and reads as follows:

const int REDIRECTOR_WP = 1; void main {   int iCurrentWP = GetCurrentWaypoint;// where we are int iNextWP; switch (iCurrentWP) {       case 1: // Node 1 should be placed off somewhere out of the way. This is where the creatures // will hang out in between reaching the end of the path and starting on a new path. // Creatures will change their appearance in between travels. // 1st param is the list of nodes they may reappear at. Must follow the pattern XX,YY,ZZ... // 2nd param is the length of time to wait before reappearing. StandardRedirectorNode("02,03", 5.0f); break; case 2: // Nodes 2 on up define the network the road walkers travel. They will never return to the node // they just came from. When they reach an end node (typically a door or a route out of the area) // they will be be "redirector node" - typically node 1. // 1st param is the list of nodes they may travel to. Must follow the pattern XX,YY,ZZ... //               (end nodes are those with only 1 element in the list) // 2nd param is the redirector WP                 StandardRoadNetworkNode("03", REDIRECTOR_WP); break; case 3: StandardRoadNetworkNode("02", REDIRECTOR_WP); break; } }
 * 1) include "ginc_wp"

Where can I learn more about other thing I can do? Many useful functions are listed in the prototypes of the include file “ginc_wp”.