Taro94's NWScript libraries

These are NWScript libraries I've written for my module. Two of them can be used in NWN 1.69, whereas one, the "instances_inc" lib, will only work with NWN:EE.

Each of these libraries is rather thoroughly documented internally, but here are the descriptions of each of them.

arrays_inc - this is (yet another) implementation of pseudo-arrays in NWScript. Although reinventing the wheel is not among my hobbies, I felt that similar libraries available were not simple to use enough and did not provide enough functionality. 

This library allows creation of arrays either on objects or globally (logically, because global arrays are still technically stored on the module object). Global arrays are mostly meant to be used as temporary arrays within a single script, similar to variables declared in scripts.

Arrays can also be used as lists. The library includes functions for adding elements (which increases the size of the array) and  removing them (which decreases the size). They can also, obviously, be used like regular arrays, instead.

Arrays of any locally settable variable type can be created, including integer, string, float, object and location.

In total, the library contains 45 functions (clear, create, get size, set element, get element, add and delete functions for each of the five supported variable types).

v1.2: added 10 new functions (i.e. two per variable type, making the total equal to 45) - Copy[Var]Array (duplicates an array on another object, under a different name, or both) and Get[Var]ArrayIndexByValue (returns the index of a specified value stored in an array, optionally returning index of the n-th occurence), also added a constant ARRAY_INDEX_INVALID, which may be returned by the aforementioned function in case the desired value was not found in the array.

persvars_inc - as opposed to arrays_inc, this lib does not reinvent the wheel, as I believe it's the first NWScript library that allows persistent storage of variables (integers, strings and floats only) on items and PCs, even in case of local vault characters. This means it can successfully be utilized instead of databases as long as data to be stored it only integers, strings and floats. Example of usage would be storage campaign-related data, such as player's decision, to be transferred between modules. Storing such data in the character's BIC file instead of an external database is much more elegant and simple. As another example, it could be used to create an override with modified sequencer scripts that would allow sequencer items to keep stored spells between character exports.

There are some limitation. In addition to the aforementioned fact that only integers, strings and floats can be stored, the library utilizes an item's unmodified description as a buffer for data. Because of this, it's not advised to store any persistent variables on items that are unidentified (or may become unidentified). The PC persistent data is, similarly, stored actually on an item - in this case the PC skin. This means that the module needs to make sure PCs have skins equipped and not replaced at any time, because this would result in the loss of any persistent data stored on such a PC. Another consideration is data size: only descriptions of size equal to 8KB (128KB in NWN:EE) can be set on items.

The library contains 18 functions in total (set, get and delete functions for each supported variable type and for items and PCs).

instances_inc - this library is for NWN:EE only. Its purpose is allowing simple management of area instances (similar to what is featured in many MMORPGs). The most exciting addition in NWN:EE for me was probably the new NWScript functions for area creation and deleting. This made it possible to have area instances in NWN, but using the new functions as they are to achieve this would be rather difficult, so I've decided to create an instance management library.

instances_inc contains only 7 functions, but requires arrays provided by arrays_inc. The most important function is CreateInstance, which takes an array of area resrefs as an argument and creates their... well, instances, returning an "instance" object upon completion (which is technically one of the created areas, but the one on which all instance data is stored). This instance object can then be used in other provided functions. An optional argument of CreateInstance makes it possible to automatically delete any empty (that is, with no PCs in any of its areas) instance.

The other functions are: GetInstance (returns an instance the PC is currently in), GetIsInstanceEmpty, DestroyInstance and one last important function.

GetInstanceWaypoint is basically a GetWaypointByTag function, but only returning waypoints found in areas of a given instance. This should be used to make sure a PC doesn't end up in the wrong instance if they jump to a waypoint (or even worse, in the instance's blueprint).

v1.1: Added two new functions: SetInstanceDestroyWhenEmpty (can be set to true or false) and JumpToInstanceWaypoint (recommended to use now instead of utilizing GetInstanceWaypoint - also, using this function to move between areas can also optionally not let PCs with horses move to a new area)

I hope somebody finds these useful. :) And please inform me of any bugs or other issues you encounter.