Useful information, Switches and Scripts

This is Advanced WalkWaypoints (AWW) by Meaglyn.



Overview of features:

Cleans up WP handling not to skip and not to react on every perception event.
Allows linear, random and circular walk patterns.
Allows WPs to have animations the NPC will perform at each, before moving on.
Allows any custom script to be executed at WP arrival.
Allows WP walking to be paused (picking up where left off when resumed and disabled (re-initializing when re-enabled).
Provides for Dusk/Dawn, Morning, Afternoon, Evening, Night and default waypoint sets to allow for more interesting schedules.
Works with existing waypoint setups as is (uses WP_, WN_, POST_, NIGHT_ etc).
Supports virtual tags on NPC, allowing an NPC to use a different set of waypoints for a while or under different conditions and then revert when needed.
Provides a basic activity system where an NPC can be made to sleep, sit, putter or do something else, for a time or until the WP schedule changes.
Has stuck walker detection.

There are two erfs included. To try out the system and not effect anything else start with aww.erf. This will not overwrite any files. Import the erf, setup a creature with the three anw_c2_default scripts in place of the default ones (heartbeat, perception and on spawn). If the creature will have a conversation set the current file for end and abort to aww_walk_wp.

If you want to use the system by default for most creatures import the aww_overwrite.erf. file as well. This contains modified nw_c2_default[1,2,9] files and nw_walk_wp. Or you can just copy the anw_c2_default files over their counterparts and aww_walk_wp to nw_walk_wp (or make similar edits to your versions of these files etc). You wIll want to rebuild at that point.

Try out the demo module. Because there is so much flexibility it really just shows some of the features. It's by no means designed to show all you can do with AWW.




Advanced Walk Waypoints (AWW) README
by Meaglyn.

Beta release version 0.9


Overview of features;

Cleans up WP handling not to skip and not to react on every perception event.

Allows linear, random and circular walk patterns.

Allows WPs to have animations the NPC will perform at each, before moving on.

Allows any custom script to be executed at WP arrival.

Allows WP walking to be paused (picking up where left off when resumed)
and disabled (re-initializing when re-enabled).

Provides for Dusk/Dawn, Morning, Afternoon, Evening, Night and default waypoint sets
to allow for more interesting schedules.

Works with existing waypoint setups as is (uses WP_, WN_, POST_, NIGHT_ etc).

Supports virtual tags on NPC, allowing an NPC to use a different set of waypoints for a while
or under different conditions and then revert when needed.

Provides a basic activity system where an NPC can be made to sleep, sit, putter or do something else,
for a time or until the WP schedule changes.

Has stuck walker detection.



Nothing is created in a vacuum however so thanks to :

Some concepts and ideas (and possibly a few remaining small code snippets) are from Axe Murderer's KWW system:
nwvault.ign.com/View.php?view=Hakpaks.Detail&id=16716&id=7066

The activities system was inspired by Carcerian's Ultima activities:
nwvault.ign.com/View.php?view=Scripts.Detail&id=3480

ts_putter support is by Tesramed, and is unmodified. You may download that from the vault and include
the ts_putter.nss file in your module. It's not included in the erf (but is in the test module):
nwvault.ign.com/View.php?view=Scripts.Detail&id=1744

The concept of a vTag is from NPC Activities.
nwvault.ign.com/View.php?view=Scripts.Detail&id=2483


This is re-written walkway points mechanism that is much more powerful than the original.
FIrst it fixes a few idosyncracies of the bioware version. Primarily it does not skip waypoints
when interrupted or when called multiple times (like when entering a new area). The NPC will
continue to it's current target WP when it restarts walking after a conversation for example.
It also throttles calls to walkwaypoints triggered by the perception event. This keeps all
the NPCs from getting messed up when a characted enters the area.

The system is designed to work with existing placed waypoints. To use it you simply add the
main scripts to your module. And change NPC HB,perception, and spawn in scripts to call
aww_WalkWayPoints() everywhere WalkWayPoints() is called. Modified versions of the default
Bioware AI files are included in the overwrite erf. Use anw_c2_default1 and anw_c2_default2
for HB and Perception events. Use anw_c2_default9 (or make similar changes to your onspawn
handler.)Be sure to #include "aww_inc_walkway" in each file modified. You may either change
conversations to end with aww_walk_wp, or copy it to nw_walk_wp (included in the overwrite
version), to call aww_WalkWayPoints(). Then rebuild your module. Things should function
pretty much exaclty as before, with the main difference described above. The system respects
X2_SWITCH_CROSSAREA_WALKWAYPOINTS and X2_L_WAYPOINT_SETFACING, and X2_S_SLEEP_AT_NIGHT_SCRIPT,
although the latter is better implemented using the sleep activity.


New features and benefits :

Each NPC can have up to 6 sets of waypoints instead of the normal 2. This is NOT dependent on
the spawn flag NW_FLAG_DAY_NIGHT_POSTING, unlike WN_ and NIGHT_. If you don't paint WPs
other "WP" or "POST" you don't get other postings. NW_FLAG_DAY_NIGHT_POSTING causes some of
the HB scripts to skip calling walkwaypoints when we'd really like it to be called.
Aww_walkwaypoints can disable this setting so that things work better.

There are now morning (WM_), afternoon (WA_), evening (WE_) and dawn/dusk (WD_) waypoints
along with the original WP_ and WN_ waypoints. POST_ and NIGHT_ behave as before.
The definition of those time periods can be tuned below. Morning is defined to be
from AWW_MORNING_START (inclusive) to AWW_AFTERNOON_START (exclusive)
(e.g. morning is >= 6 and < 12, so 6 through 11). The effect of POST and NIGHT_ can be
achieved for the other times of day by simply having only one valid WP in the set.
If other times are not found the search falls back to basic WP_ just as it does with WN_.

There is also a WD_ set which applies at both dawn and dusk (as defined by the module settings).
This generally will be a post (i.e. single waypoint) which is placed at or near the place
where the NPC will be sleeping at night. This allows the system to move the NPC to the right
place before night kicks in and the NPC drops to sleep.

NPCs can have a virtual tag set on them. This effects which waypoints they use.
Changing the vritual tag causes the NPC to re-initialize WPs with the new tag and
start walking new points. This can be a really powerful feature. You can now share
waypoints. You can make people walk on the same path to get from one place to another.
You can make any NPC who enters the area start marching around the room...

Waypoint walking can be paused or disabled on a NPC. Both have the effect of stopping the NPC
from walking points. When a Paused NPC is unpaused it will try to pick up where it left off.
When a disabled walker is re-enabled it will re-initialize it's walking and start over (usually
with the nearest way point in the current set).

Waypoint walkers can go in a circular or random order along with the usual up and then back down.

On reaching a waypoint an NPC can execute a WP defined script, play a WP defined animation, or just
use a WP defined or argument defined pause and move on. The script can do anything it needs to. It may
pause waypoints and have the NPC do who knows what before restarting his/her walk.

waypoints can be indivually disabled/re-enabled. A disabled waypoint will not be selected as a walking target.
an NPC which currently has the waypoint as a destination will continue to it. But deisabled waypoints do not
do normal waypoint arrival processing, so he/she will just move on.

The system should not be messed up by calls the regular WalkWayPoints although they will not do anything
once aww_WalkWayPoints has been called for an NPC. However, it is cleaner to use modified spawn/perception
and HB scripts, as well as conversation end/abort scripts, which call AWW directly. Basic versions of these
are included in the demo module.

AWW includes two mechanisms to ensure walkers don't get stuck. The first and simplest is to use force move
for the walking. This can be done globally by making sure AWW_USE_FORCEMOVE is set to TRUE in aww_inc_walkway.
The timeout is controlled by AWW_FORCEMOVE_TIMEOUT and defaults to 30.0. You can also set the timeout on a
per NPC basis using a float variable X2_L_WALKWAY_FORCE_MOVE specifying the timeout. Setting this to > 0.0
will cause that NPC to use force move with the given timeout even when AWW_USE_FORCEMOVE is FALSE.

The other method, which is not needed if using force, is stuck detection. This is enabled globally only, with
AWW_STUCK_DETECTION = TRUE in aww_inc_walkway. This will detect when a walker has not made progress an attempt
to move around a bit and try again to reach the next WP. If this moving around fails the NPC is finally jumped
to the WP. This may make things a little more realistic than using force move, but when really stuck there will
still be jumps. Both force and stuck detection are not needed at the same time. The stuck detection usually
prevents any forcemove timeouts (unless set really low).

AWW also includes an activity driver script which is started by arrival at a waypoint by setting
the waypoint's script to aww_start_act. This will pause the waypoint walking for either given time
or until the NPCs waypoint set changes (e.g. morning becomes afternoon). While running the activity
normal calls to aww_walkwaypoints will instead execute an activity script. There are a few
activities like sleeping, sitting, playing mobile ambient animations etc. As well as support for
ts_puttering by Tseramed. Other scripts like one of the Heartbeat base barmaid scripts would also work.

This allows for a fairly simple way to have NPCs do interesting things.

The system also is the framework for a larger movement system. The NPC can have a destination WP
and destination WP script set on her. If the NPC ever arrives at that waypoint it will execute
the destination WP script instead of normal arrival code. This would be used to have the NPC move
from one place to another using waypoints (of some other tag like road1) down the middle of a road
to get to the destination and then revert to reat tag and enter the temple or whatever. That system is
under development, but the hooks to set the destination and react to it are in place in AWW.

HOWTO:

WayPoint Variables :

AWW_DISABLE : int (as boolean) When set the waypoint is skipped when selecting next waypoint and won't
execute any arrival script (if disabled while NPC already heading for it).
Can use aww_SetWPDisabled(object oWay, int bSet = TRUE) to toggle this as well.
AWW_WP_SCRIPT : string name of script to execute (as the creature) on arrival at this WP.
AWW_PAUSE : float override the pause setting given given when the creature called aww_WalkWayPoints.



AWW_WP_ANIMATION: int animation to play instead of just pausing - use only looping or fireforget
animations (1-31 or 101-117). If fPause is > 0.0 will pause, play animation, pause
before moving to next WP.

AWW_WP_ANIMATION_SPEED: float speed to use with animation
AWW_WP_ANIMATION_DURATION: float duration to play animation


NPC variables :

AWW_WALK_TYPE : optional int on creature to define what walk type to use. Can be set to one of
AWW_WALK_TYPE_NORMAL , AWW_WALK_TYPE_CIRCULAR or AWW_WALK_TYPE_RANDOM. Otherwise
the NPC will use AWW_WALK_TYPE_NORMAL by default. This can also be set by using SetWalkCondition
and AWW_WALK_FLAG_CIRCULAR or AWW_WALK_FLAG_RANDOM (neither one of these set means use normal).
Whenever the NPC re-inits way points (which happens if the vTag is changed) this variable
is used so any manual SetWalkCondition changes are overwritten.

AWW_NOWP_SCRIPT : optional script to execute when the creature has no waypoint to move to.

AWW_DEST_WP : object, a "final" destination WP. The system will execute AWW_DEST_SCRIPT
when this dest is reached instead of normal wp arrival processing.
use aww_SetWalkDestination to set this up on the NPC.
AWW_DEST_SCRIPT: string scriptname

AWW_LAX_POST: optional int on NPC. By default an NPC with a single waypoint in a set (i.e. a POST)
will move to that post and stay right on it, moving back if he/she moved off of it.
If this is set to non-zero, the NPC will move to his/her post the initial time, but then
not move back to it when dragged away for something else. This is useful for NPCs who
will be doing things at the waypoint area but are not running an activity or pausing aww.
(i.e. they want to still use aww's mechanism to move among timebased waypoint sets but not
to stand right on top of or keep moving back to the current "post").

AWW_POST_DISTANCE : float, if AWW_LAX_POST is not set, this controls how far away the NPC can get from
the current post before aww will move him/her back. Default is 2.0. Putting in a large number
has the same effect as AWW_LAX_POST, but is a bit more CPU intensive.

NOTE: a "post" is really just any waypoint set with only one currently enabled WP in it.

X2_L_WALKWAY_FORCE_MOVE : float. if set to > 0.0 the NPC will use force move with this value as the timeout
This will ensure the NPC gets to the destination.


Activity Subsystem:
On the WP:
set AWW_WP_SCRIPT to aww_start_act.

On the NPC or the waypoint - the NPC settings override the waypoint settings:
AWW_CUSTOM_ACTIVITY_SCRIPT controls the script to run. If unset either
ts_putter or aww_do_activity will be used depending on the value of AWW_CUSTOM_ACTIVITY.

AWW_CUSTOM_ACTIVITY : int. Which activity to perform. If unset and the script is "" ts_putter is used instead
Otherwise this should be one of the valid AWW_ACTIVITY_* constants.

AWW_CUSTOM_ACTIVITY_DURATION: float, duration to use the script instead of walking waypoints. If unset
the script is used until the NPCs waypoint set changes (e.g. morning becomes afternoon).


------------------------------------

Included are modified versions of default AI scripts which normally call walkwaypoints.
nw_c2_default1.nss
nw_c2_default2.nss
nw_c2_patrol1.nss
nw_walk_wp.nss

anw_c2_default9.nss



#include "aww_inc_walkway"

void main()
{
SetLocalInt(OBJECT_SELF, "AWW_WALK_TYPE", AWW_WALK_TYPE_CIRCULAR);
aww_ConfigureWalkType();
}