SEAMLESS AREA TRANSITIONS v1.1
Copyright © 2013 Aaron Parr
[email protected]

COPYRIGHT NOTICE
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see .
___________________________________________________________________________


SEAMLESS AREA TRANSITIONS

WHAT IS THIS?
Back in 2002 Jaga Te'lesin released v1.1 of the ALL-IN-ONE SEAMLESS AREA TRANSITIONER . SEAMLESS AREA TRANSITIONS is written as a replacement of Jaga's script with major improvements.
"Huh?" you might say.
Alright, those that need more explanation should read on.
Jaga's work allowed you to arrange your areas on a grid according to coordinates and link them up edge to edge. To use it, the builder creates areas with special tags, creates a custom trigger using Jaga's script, and then draws these custom triggers on the full length of each edge of an area. Thats it. The trigger's script linked the areas together, and position at the moment of transition is used to determine position in the new area. It is this last bit that lead to the "seamless" part of the name.
This release of Seamless Area Transitions is designed to do the same, and is backwards compatible with Jaga's script. It however makes three notable improvements:
(1) Copyright - you may modified and release this work freely as long as you maintain the GNU GPL. See Copyright Notice above.
(2) Variable Area Size - Area's may be of different sizes and link to one another. The script has two ways of handling this which you may configure. More on this below.
(3) Better Tag Handling - A tag may if you wish contain more information than just the 9 character coordinate code. Only the last 9 characters of your tag must contain the coordinates. The preceding portion of the tag - if it exists - defines the "region" which the area belongs to. More on this below.


__SET UP____________________________
1. Unpack the archive. (you've likely already done this. hooray.)
2. Open the "NWN" directory.
- note that the subdirectories of "NWN" are named according to the conventions used in your NWN installation.
3. Copy everything in the "erf" directory to NWN's "erf" directory
4. Copy everything in the "modules" directory to NWN's "modules" directory


__INSTALL____________________________
1. Import the [erf] into your module.
- Contents include:
a. area_trans (script)
b. area_trans (trigger)
2. The custom trigger will show up in the Custom palette under Transitions.
__Note__ The script is designed to replace the original area_trans, and is compatible with modules using Jaga's script. You can import it as is, and all of your transitions should still work using the scripts default configuration. You will however immediately gain the benefits of the system. More on this below.


__CONFIGURING AREA_TRANS_____________
Near the top of the area_trans script under the heading "GLOBALS" are constants and global variables which can be adjusted to configure the script for your use.
Note: the Directional Constants are NOT user configurable.
For details on each of these read on:

AREATRANS_DATA
- this is a variable object which can be set by a function. The default functioned used to set the object is GetModule(), but it is recommended that PW admins change this to a different object in order to improve performance.
- this object stores a number of labels which point to area tags. the label is the grid tag. You do not need to put any of the data on the object. this script does it for you.

AREATRANS_DEBUG
- TRUE: debug messages are delivered to the transitioning PC.
- FALSE: no debug messages.

AREATRANS_GRID_CARTESIAN
- TRUE: this script expects your grid to be Cartesian: numbers increase to the north and east.
- FALSE: the script will expect a grid as set up for Jaga's script: numbers increase to the south and east.

AREATRANS_DIAGONAL_OFFSET
- Distance out from any corner to sense diagonal movement.

AREATRANS_LANDING_OFFSET
- Distance out from edge in destination Area that PC will land

AREATRANS_DELAY
- Delay before zoning included to mimic original behavior. 0.0f however is recommended.

AREATRANS_REFACTORY_PERIOD
- Delay during which the transitioned PC will not be able to use a transition. This limits the ability for a PC to evade monsters by jumping back and forth between areas, AND more importantly limits the likelihood of a transitioned PC accidentally being bumped back to where they came from upon arrival.

AREATRANS_FLEXIBLE_GRID
- TRUE: each area regardless of size occupies only one grid coordinate. This is similar to how the original functioned except that each area can be a different size and shape. And thus each grid node is flexible in terms of size and shape.
- FALSE: Each grid node is a fixed size, but areas may contain more than one grid node depending on size and shape. (See AREATRANS_GRID_UNIT for setting the size of each grid node.)

AREATRANS_GRID_UNIT
- this value is only used for inflexible grids (ie AREATRANS_FLEXIBLE_GRID=FALSE)
- this float should be any value which is a multiple of 10.0, and no greater than 320.0.
- the value defines the number of meters between each grid node, and thus also defines the smallest size of an area allowed. Likewise all area dimensions should be multiples of this figure. I recommend that you use 20.0 or 40.0 or 80.0 because each of those divide evenly into the max area dimension of 320.0. Using 10.0 is possible, but may be unwieldy. (Note: it may be possible to use numbers like 15.0 or 25.0 but do so at your own risk as you are likely to get unusual results.)
- Example: if you set this at 20.0. The smallest area size you can have is 20.0 x 20.0 (2x2 in the area creation screen), and the dimensions of larger areas must be multiples of this number such as 20.0 x 80.0 (2x8) or 320.0 x 40.0 (32x4). (Note: It may be possible to have area dimensions which are not multiples of the grid unit, but you might get unexpected results.)


__AREA TAGS_____________
Just as with Jaga's work, areas will need special tags which identify the area's coordinates on the grid. The coordinates of a grid (or Region) are encoded in a 9 character string as follows:
p00p00p00
In Seamless Area Transitions, I enabled users to add up to 23 characters to the left of the 9 character coordinates. An area tag could thus read:
defaultregion_p00p00p00
The last nine characters describe the coordinates of an area within a grid identified by "defaultregion_". This means that you can have a different grid (or region) for a different part of your module rather than require you to use the same grid for all areas.
The X Y and Z coordinates within a particular grid or region are described from left to right in 3 character groups. The first 3 characters identify the x dimension (East-West), the next 3 identify the y dimension (North-South), and the last 3 identify the z dimension. The z-dimension is a special case that we can ignore for the time being as long as we don't change it. More on this later.
Some may have intuited that p00p00p00 describes the origin point on a grid, which is correct. The example above is equivalent to x = 0, y = 0, and z = 0. The first character of the 3 in a grouping may be either "p" or "n". "p" indicates a positive number, "n" a negative. Thus the value of each coordinate can range from -99 to +99.
An example:
Area A tag: defaultregion_p00p00p00
Area B tag: defaultregion_n01p01p00
Area C tag: defaultregion_n02p01p00
Area D tag: defaultregion_p01p00p00
Area E tag: defaultregion_p01n01p00
Area F tag: defaultregion_shadow_n02p01p00

A Flexible, Cartesian Grid would look like this:

CB
AD
E

A is at the origin.
C is west of B and unlinked with A.
B is east or C and north-west of A.
D is east of A and north of E.
E is south-east of A and south of D.
F is in another region entirely, but otherwise shares coordinates with C. I used the suffix "shadow_" to illustrate a shady possibility: adding the shadow suffix to a region name could transport a player to the shadow plane equivalent of the area they currently occupy. PC starts out in area C, plane shifts, and ends up in area F.

Likewise a Flexible, Non-Cartesian Grid:

E
AD
CB

Note that the east-west orientation is the same but north-south is flipped. I'm not sure why Jaga did this, since other coordinates within NWN are Cartesian, but I maintained this for backwards compatibility.

Now with Inflexible grids this gets very interesting. Lets take a look at the following illustration:

AABB FFF
AABBEEEEFFF
CCCBB FFF
CCCD

Groupings of letters show the grid nodes occupied by each area. So lets say that our Grid Unit is 40.0 meters. Area A is thus an 8x8 area (80 meters by 80 meters), and Area F 12x12. Some of the grid nodes do not have an area in them, and each area has a different shape.
How do you give an area a tag?
Take the south-west most corner of the area on the grid, and use that for your coordinates. So assuming that the south west corner of Area A is the origin point for the grid we'd have the following area tags:
Area A tag: reg_p00p00p00
contains: reg_p00p00p00, reg_p01p00p00, reg_p00p01p00, reg_p01p01p00
Area B tag: reg_p02n01p00
contains: reg_p02n01p00, reg_p03n01p00, reg_p02p00p00, reg_p03p00p00, reg_p02p01p00, reg_p03p01p00
Area C tag: reg_n01n02p00
contains: reg_n01n02p00, reg_p00n02p00, reg_p01n02p00, reg_n01n01p00, reg_p00n01p00, reg_p01n01p00
Area D tag: reg_p02n02p00
contains: reg_p02n02p00
Area E tag: reg_p04p00p00
contains: reg_p04p00p00, reg_p05p00p00, reg_p06p00p00, reg_p07p00p00
Area F tag: reg_p08n01p00
contains: reg_p08n01p00, reg_p09n01p00, reg_p10n01p00, reg_p08p00p00, reg_p09p00p00, reg_p10p00p00, reg_p08p01p00, reg_p09p01p00, reg_p10p01p00

Technical Notes:
It is possible to do some tricky things with this. My recommendation is to layout your areas edge to edge with no overlaps. But advanced users will discover ways to create areas which overlap or pass through one another. This will be very difficult to do effectively, and is not recommended. Do so at your own risk.
When a PC transitions from one area to another, they actually transition from their grid node to an adjacent grid node. Each grid node has a similar string identifier as an area tag. First the script determines whether the adjacent grid node's string ID is also an area tag. Failing that, it next uses the grid node string ID as a label for a local string stored on the appropriate AREATRANS_DATA object. Failing that it next starts crawling across all of the adjacent grid nodes to the south and west of the destination grid node looking for an area origin which contains the destination within the area's dimensions. It thus never looks further than 320 meters in any either direction.
You can turn on debugging to get a sense for how this works.


__TRANSITION TRIGGERS_____________
The default setup for the trigger associates the area_trans script with the OnClick event, and the trigger type is transition.
These transition triggers must be painted near the edge of an area. It is recommended that the trigger not contain the landing offset. You may make any number of these triggers in your area.
While it is not required to identify a waypoint as the transition target, it is recommended that you do so. The script will make use of it, and it will increase the likelihood that NPCs chasing the PC will be able to pursue them across the transition. The PC will land at the waypoint but the area_trans script jumps them so quickly to their proper position that the player will typically only notice this if the server is lagging.
Keep in mind that the position of the trigger within the area is important for its functioning. A trigger drawn along the eastern edge of an area assumes that the PC is traveling East into the destination area.




CHANGE LOG
v1.1
Changes to script area_trans:
- SetLocalInt(oPC, "AREATRANS_DIRECTION_BACKUP", nDir)
new local integer used in diagonal transitions
if the diagonal direction fails, the nearest cardinal direction (N, S, E, or W) is used in its place to find a transition area
- int AREATRANS_SQUARES_PER_GRID_UNIT
new global used to correct math error in FindAreaContainingGridTag()
- string GetDirectionName(int nDir)
new function to encapsulate code for generating name from direction integer