NWNX:EE  8193.36.12
Util

Readme

Provide various utility functions that don't have a better home

Environment Variables

Variable Name Value Default Notes
NWNX_UTIL_PRE_MODULE_START_SCRIPT string Unset Allows you to set a NWScript that runs before the OnModuleLoad event
NWNX_UTIL_PRE_MODULE_START_SCRIPT_CHUNK string Unset Allows you to set a NWScript Chunk that runs before the OnModuleLoad event

Files

file  nwnx_util.nss
 

Classes

struct  NWNX_Util_WorldTime
 A world time struct. More...
 
struct  NWNX_Util_HighResTimestamp
 A high resolution timestamp. More...
 

Functions

string NWNX_Util_GetCurrentScriptName (int depth=0)
 Gets the name of the currently executing script. More...
 
string NWNX_Util_GetAsciiTableString ()
 Gets a string that contains the ascii table. More...
 
int NWNX_Util_Hash (string str)
 Gets an integer hash of a string. More...
 
int NWNX_Util_GetModuleMtime ()
 Gets the last modified timestamp (mtime) of the module file in seconds. More...
 
string NWNX_Util_GetModuleFile ()
 Gets the module short file name. More...
 
string NWNX_Util_GetCustomToken (int customTokenNumber)
 Gets the value of customTokenNumber. More...
 
itemproperty NWNX_Util_EffectToItemProperty (effect e)
 Convert an effect type to an itemproperty type. More...
 
effect NWNX_Util_ItemPropertyToEffect (itemproperty ip)
 Convert an itemproperty type to an effect type. More...
 
string NWNX_Util_StripColors (string str)
 Strip any color codes from a string. More...
 
string NWNX_Util_GetEnvironmentVariable (string sVarname)
 Retrieves an environment variable. More...
 
int NWNX_Util_GetMinutesPerHour ()
 Gets the module real life minutes per in game hour. More...
 
void NWNX_Util_SetMinutesPerHour (int minutes)
 Set module real life minutes per in game hour. More...
 
string NWNX_Util_EncodeStringForURL (string str)
 Encodes a string for usage in a URL. More...
 
string NWNX_Util_GetFirstResRef (int nType, string sRegexFilter="", int bModuleResourcesOnly=TRUE)
 Get the first resref of nType. More...
 
string NWNX_Util_GetNextResRef ()
 Get the next resref. More...
 
object NWNX_Util_GetLastCreatedObject (int nObjectType, int nNthLast=1)
 Get the last created object. More...
 
string NWNX_Util_AddScript (string sFileName, string sScriptData, int bWrapIntoMain=FALSE, string sAlias="NWNX")
 Compiles and adds a script to the UserDirectory/nwnx folder, or to the location of sAlias. More...
 
int NWNX_Util_AddNSSFile (string sFileName, string sContents, string sAlias="NWNX")
 Adds a nss file to the UserDirectory/nwnx folder, or to the location of sAlias. More...
 
int NWNX_Util_RemoveNWNXResourceFile (string sFileName, int nType, string sAlias="NWNX")
 Remove sFileName of nType from the UserDirectory/nwnx folder, or from the location of sAlias. More...
 
void NWNX_Util_SetInstructionLimit (int nInstructionLimit)
 Set the NWScript instruction limit. More...
 
int NWNX_Util_GetInstructionLimit ()
 Get the NWScript instruction limit. More...
 
void NWNX_Util_SetInstructionsExecuted (int nInstructions)
 Set the number of NWScript instructions currently executed. More...
 
int NWNX_Util_GetInstructionsExecuted ()
 Get the number of NWScript instructions currently executed. More...
 
int NWNX_Util_RegisterServerConsoleCommand (string sCommand, string sScriptChunk)
 Register a server console command that will execute a script chunk. More...
 
void NWNX_Util_UnregisterServerConsoleCommand (string sCommand)
 Unregister a server console command that was registered with NWNX_Util_RegisterServerConsoleCommand(). More...
 
int NWNX_Util_PluginExists (string sPlugin)
 Determines if the given plugin exists and is enabled. More...
 
string NWNX_Util_GetUserDirectory ()
 Gets the server's current working user folder. More...
 
int NWNX_Util_GetScriptReturnValue ()
 Get the return value of the last run script with a StartingConditional. More...
 
object NWNX_Util_CreateDoor (string sResRef, location locLocation, string sNewTag="", int nAppearanceType=-1)
 Create a door. More...
 
void NWNX_Util_SetItemActivator (object oObject)
 Set the object that will be returned by GetItemActivator. More...
 
struct NWNX_Util_WorldTime NWNX_Util_GetWorldTime (float fAdjustment=0.0f)
 Get the world time as calendar day and time of day. More...
 
void NWNX_Util_SetResourceOverride (int nResType, string sOldName, string sNewName)
 Set a server-side resource override. More...
 
string NWNX_Util_GetResourceOverride (int nResType, string sName)
 Get a server-side resource override. More...
 
int NWNX_Util_GetScriptParamIsSet (string sParamName)
 Get if a script param is set. More...
 
void NWNX_Util_SetDawnHour (int nDawnHour)
 Set the module dawn hour. More...
 
void NWNX_Util_SetDuskHour (int nDuskHour)
 Set the module dusk hour. More...
 
struct NWNX_Util_HighResTimestamp NWNX_Util_GetHighResTimeStamp ()
 
string NWNX_Util_GetTTY ()
 
void NWNX_Util_SetCurrentlyRunningEvent (int nEventID)
 Set the currently running script event. More...
 
int NWNX_Util_GetStringLevenshteinDistance (string sString, string sCompareTo)
 Calculate the levenshtein distance of two strings. More...
 
void NWNX_Util_UpdateClientObject (object oObjectToUpdate, object oPlayer=OBJECT_INVALID)
 Sends a full object update of oObjectToUpdate to all clients. More...
 
int NWNX_Util_CleanResourceDirectory (string sAlias, int nResType=0xFFFF)
 Clean a resource directory, deleting all files of nResType. More...
 
string NWNX_Util_GetModuleTlkFile ()
 Return the filename of the tlk file. More...
 

Function Documentation

◆ NWNX_Util_GetCurrentScriptName()

string NWNX_Util_GetCurrentScriptName ( int  depth = 0)

Gets the name of the currently executing script.

Note
If depth is > 0, it will return the name of the script that called this one via ExecuteScript().
Parameters
depthto seek the executing script.
Returns
The name of the currently executing script.

Definition at line 268 of file nwnx_util.nss.

◆ NWNX_Util_GetAsciiTableString()

string NWNX_Util_GetAsciiTableString ( )

Gets a string that contains the ascii table.

Note
The character at index 0 is a space.
Returns
A string that contains all characters at their position (e.g. 'A' at 65).

Definition at line 276 of file nwnx_util.nss.

◆ NWNX_Util_Hash()

int NWNX_Util_Hash ( string  str)

Gets an integer hash of a string.

Parameters
strThe string to hash.
Returns
The hashed string as an integer.

Definition at line 283 of file nwnx_util.nss.

◆ NWNX_Util_GetModuleMtime()

int NWNX_Util_GetModuleMtime ( )

Gets the last modified timestamp (mtime) of the module file in seconds.

Returns
The mtime of the module file.

Definition at line 291 of file nwnx_util.nss.

◆ NWNX_Util_GetModuleFile()

string NWNX_Util_GetModuleFile ( )

Gets the module short file name.

Returns
The module file as a string.

Definition at line 297 of file nwnx_util.nss.

◆ NWNX_Util_GetCustomToken()

string NWNX_Util_GetCustomToken ( int  customTokenNumber)

Gets the value of customTokenNumber.

Parameters
customTokenNumberThe token number to query.
Returns
The string representation of the token value.

Definition at line 303 of file nwnx_util.nss.

◆ NWNX_Util_EffectToItemProperty()

itemproperty NWNX_Util_EffectToItemProperty ( effect  e)

Convert an effect type to an itemproperty type.

Parameters
eThe effect to convert to an itemproperty.
Returns
The converted itemproperty.

Definition at line 311 of file nwnx_util.nss.

◆ NWNX_Util_ItemPropertyToEffect()

effect NWNX_Util_ItemPropertyToEffect ( itemproperty  ip)

Convert an itemproperty type to an effect type.

Parameters
ipThe itemproperty to convert to an effect.
Returns
The converted effect.

Definition at line 319 of file nwnx_util.nss.

◆ NWNX_Util_StripColors()

string NWNX_Util_StripColors ( string  str)

Strip any color codes from a string.

Parameters
strThe string to strip of color.
Returns
The new string without any color codes.

Definition at line 327 of file nwnx_util.nss.

◆ NWNX_Util_GetEnvironmentVariable()

string NWNX_Util_GetEnvironmentVariable ( string  sVarname)

Retrieves an environment variable.

Parameters
sVarnameThe environment variable to query.
Returns
The value of the environment variable.

Definition at line 335 of file nwnx_util.nss.

◆ NWNX_Util_GetMinutesPerHour()

int NWNX_Util_GetMinutesPerHour ( )

Gets the module real life minutes per in game hour.

Returns
The minutes per hour.

Definition at line 343 of file nwnx_util.nss.

◆ NWNX_Util_SetMinutesPerHour()

void NWNX_Util_SetMinutesPerHour ( int  minutes)

Set module real life minutes per in game hour.

Parameters
minutesThe minutes per hour.

Definition at line 350 of file nwnx_util.nss.

◆ NWNX_Util_EncodeStringForURL()

string NWNX_Util_EncodeStringForURL ( string  str)

Encodes a string for usage in a URL.

Parameters
strThe string to encode for a URL.
Returns
The url encoded string.

Definition at line 357 of file nwnx_util.nss.

◆ NWNX_Util_GetFirstResRef()

string NWNX_Util_GetFirstResRef ( int  nType,
string  sRegexFilter = "",
int  bModuleResourcesOnly = TRUE 
)

Get the first resref of nType.

Parameters
nTypeA Resref Type.
sRegexFilterLets you filter out resrefs using a regexfilter. For example: nwnx_.* gets you all scripts prefixed with nwnx_ when using the NSS resref type.
bModuleResourcesOnlyIf TRUE only custom resources will be returned.
Returns
The first resref found or "" if none is found.

Definition at line 367 of file nwnx_util.nss.

◆ NWNX_Util_GetNextResRef()

string NWNX_Util_GetNextResRef ( )

Get the next resref.

Returns
The next resref found or "" if none is found.

Definition at line 379 of file nwnx_util.nss.

◆ NWNX_Util_GetLastCreatedObject()

object NWNX_Util_GetLastCreatedObject ( int  nObjectType,
int  nNthLast = 1 
)

Get the last created object.

Parameters
nObjectTypeDoes not take the NWScript OBJECT_TYPE_* constants. Use NWNX_Consts_TranslateNWScriptObjectType() to get their NWNX equivalent.
nNthLastThe nth last object created.
Returns
The last created object. On error, this returns OBJECT_INVALID.

Definition at line 388 of file nwnx_util.nss.

◆ NWNX_Util_AddScript()

string NWNX_Util_AddScript ( string  sFileName,
string  sScriptData,
int  bWrapIntoMain = FALSE,
string  sAlias = "NWNX" 
)

Compiles and adds a script to the UserDirectory/nwnx folder, or to the location of sAlias.

Note
Will override existing scripts that are in the module.
Parameters
sFileNameThe script filename without extension, 16 or less characters.
sScriptDataThe script data to compile
bWrapIntoMainSet to TRUE to wrap sScriptData into void main(){}.
sAliasThe alias of the resource directory to add the ncs file to. Default: UserDirectory/nwnx
Returns
"" on success, or the compilation error.

Definition at line 399 of file nwnx_util.nss.

◆ NWNX_Util_AddNSSFile()

int NWNX_Util_AddNSSFile ( string  sFileName,
string  sContents,
string  sAlias = "NWNX" 
)

Adds a nss file to the UserDirectory/nwnx folder, or to the location of sAlias.

Note
Will override existing nss files that are in the module
Parameters
sFileNameThe script filename without extension, 16 or less characters.
sContentsThe contents of the nss file
sAliasThe alias of the resource directory to add the nss file to. Default: UserDirectory/nwnx
Returns
TRUE on success.

Definition at line 412 of file nwnx_util.nss.

◆ NWNX_Util_RemoveNWNXResourceFile()

int NWNX_Util_RemoveNWNXResourceFile ( string  sFileName,
int  nType,
string  sAlias = "NWNX" 
)

Remove sFileName of nType from the UserDirectory/nwnx folder, or from the location of sAlias.

Parameters
sFileNameThe filename without extension, 16 or less characters.
nTypeThe Resref Type.
sAliasThe alias of the resource directory to remove the file from. Default: UserDirectory/nwnx
Returns
TRUE on success.

Definition at line 424 of file nwnx_util.nss.

◆ NWNX_Util_SetInstructionLimit()

void NWNX_Util_SetInstructionLimit ( int  nInstructionLimit)

Set the NWScript instruction limit.

Parameters
nInstructionLimitThe new limit or -1 to reset to default.

Definition at line 436 of file nwnx_util.nss.

◆ NWNX_Util_GetInstructionLimit()

int NWNX_Util_GetInstructionLimit ( )

Get the NWScript instruction limit.

Definition at line 444 of file nwnx_util.nss.

◆ NWNX_Util_SetInstructionsExecuted()

void NWNX_Util_SetInstructionsExecuted ( int  nInstructions)

Set the number of NWScript instructions currently executed.

Parameters
nInstructionsThe number of instructions, must be >= 0.

Definition at line 453 of file nwnx_util.nss.

◆ NWNX_Util_GetInstructionsExecuted()

int NWNX_Util_GetInstructionsExecuted ( )

Get the number of NWScript instructions currently executed.

Definition at line 461 of file nwnx_util.nss.

◆ NWNX_Util_RegisterServerConsoleCommand()

int NWNX_Util_RegisterServerConsoleCommand ( string  sCommand,
string  sScriptChunk 
)

Register a server console command that will execute a script chunk.

Note
Example usage: NWNX_Util_RegisterServerConsoleCommand("test", "PrintString(\"Test Command -> Args: $args");");
Parameters
sCommandThe name of the command.
sScriptChunkThe script chunk to run. You can use $args to get the console command arguments.
Returns
TRUE on success.

Definition at line 470 of file nwnx_util.nss.

◆ NWNX_Util_UnregisterServerConsoleCommand()

void NWNX_Util_UnregisterServerConsoleCommand ( string  sCommand)

Unregister a server console command that was registered with NWNX_Util_RegisterServerConsoleCommand().

Parameters
sCommandThe name of the command.

Definition at line 481 of file nwnx_util.nss.

◆ NWNX_Util_PluginExists()

int NWNX_Util_PluginExists ( string  sPlugin)

Determines if the given plugin exists and is enabled.

Parameters
sPluginThe name of the plugin to check. This is the case sensitive plugin name as used by NWNX_CallFunction, NWNX_PushArgumentX
Note
Example usage: NWNX_Util_PluginExists("NWNX_Creature");
Returns
TRUE if the plugin exists and is enabled, otherwise FALSE.

Definition at line 489 of file nwnx_util.nss.

◆ NWNX_Util_GetUserDirectory()

string NWNX_Util_GetUserDirectory ( )

Gets the server's current working user folder.

Returns
The absolute path of the server's home directory (-userDirectory)

Definition at line 495 of file nwnx_util.nss.

◆ NWNX_Util_GetScriptReturnValue()

int NWNX_Util_GetScriptReturnValue ( )

Get the return value of the last run script with a StartingConditional.

Returns
Return value of the last run script.

Definition at line 502 of file nwnx_util.nss.

◆ NWNX_Util_CreateDoor()

object NWNX_Util_CreateDoor ( string  sResRef,
location  locLocation,
string  sNewTag = "",
int  nAppearanceType = -1 
)

Create a door.

Parameters
sResRefThe ResRef of the door.
locLocationThe location to create the door at.
sNewTagAn optional new tag for the door.
nAppearanceTypeAn optional index into doortypes.2da for appearance.
Returns
The door, or OBJECT_INVALID on failure.

Definition at line 511 of file nwnx_util.nss.

◆ NWNX_Util_SetItemActivator()

void NWNX_Util_SetItemActivator ( object  oObject)

Set the object that will be returned by GetItemActivator.

Parameters
oObjectAn object.

Definition at line 530 of file nwnx_util.nss.

◆ NWNX_Util_GetWorldTime()

struct NWNX_Util_WorldTime NWNX_Util_GetWorldTime ( float  fAdjustment = 0.0f)

Get the world time as calendar day and time of day.

Note
This function is useful for calculating effect expiry times.
Parameters
fAdjustmentAn adjustment in seconds, 0.0f will return the current world time, positive or negative values will return a world time in the future or past.
Returns
A NWNX_Util_WorldTime struct with the calendar day and time of day.

Definition at line 538 of file nwnx_util.nss.

◆ NWNX_Util_SetResourceOverride()

void NWNX_Util_SetResourceOverride ( int  nResType,
string  sOldName,
string  sNewName 
)

Set a server-side resource override.

Parameters
nResTypeA Resref Type.
sOldNameThe old resource name, 16 characters or less.
sNewNameThe new resource name or "" to clear a previous override, 16 characters or less.

Definition at line 552 of file nwnx_util.nss.

◆ NWNX_Util_GetResourceOverride()

string NWNX_Util_GetResourceOverride ( int  nResType,
string  sName 
)

Get a server-side resource override.

Parameters
nResTypeA Resref Type.
sNameThe name of the resource, 16 characters or less.
Returns
The resource override, or "" if one is not set.

Definition at line 562 of file nwnx_util.nss.

◆ NWNX_Util_GetScriptParamIsSet()

int NWNX_Util_GetScriptParamIsSet ( string  sParamName)

Get if a script param is set.

Parameters
sParamNameThe script parameter name to check.
Returns
TRUE if the script param is set, FALSE if not or on error.

Definition at line 573 of file nwnx_util.nss.

◆ NWNX_Util_SetDawnHour()

void NWNX_Util_SetDawnHour ( int  nDawnHour)

Set the module dawn hour.

Parameters
nDawnHourThe new dawn hour

Definition at line 583 of file nwnx_util.nss.

◆ NWNX_Util_SetDuskHour()

void NWNX_Util_SetDuskHour ( int  nDuskHour)

Set the module dusk hour.

Parameters
nDuskHourThe new dusk hour

Definition at line 591 of file nwnx_util.nss.

◆ NWNX_Util_GetHighResTimeStamp()

struct NWNX_Util_HighResTimestamp NWNX_Util_GetHighResTimeStamp ( )
Returns
Returns the number of microseconds since midnight on January 1, 1970.

Definition at line 599 of file nwnx_util.nss.

◆ NWNX_Util_GetTTY()

string NWNX_Util_GetTTY ( )
Returns
Return name of a terminal, "" if not a TTY

Definition at line 610 of file nwnx_util.nss.

◆ NWNX_Util_SetCurrentlyRunningEvent()

void NWNX_Util_SetCurrentlyRunningEvent ( int  nEventID)

Set the currently running script event.

Parameters
nEventIDThe ID of the event.

Definition at line 618 of file nwnx_util.nss.

◆ NWNX_Util_GetStringLevenshteinDistance()

int NWNX_Util_GetStringLevenshteinDistance ( string  sString,
string  sCompareTo 
)

Calculate the levenshtein distance of two strings.

Parameters
sStringThe string to compare with.
sCompareToThe string to compare sString to.
Returns
The number of characters different between the compared strings.

Definition at line 626 of file nwnx_util.nss.

◆ NWNX_Util_UpdateClientObject()

void NWNX_Util_UpdateClientObject ( object  oObjectToUpdate,
object  oPlayer = OBJECT_INVALID 
)

Sends a full object update of oObjectToUpdate to all clients.

Parameters
oObjectToUpdateThe object to update
oPlayerThe player for which the objects needs to update, OBJECT_INVALID for all players

Definition at line 636 of file nwnx_util.nss.

◆ NWNX_Util_CleanResourceDirectory()

int NWNX_Util_CleanResourceDirectory ( string  sAlias,
int  nResType = 0xFFFF 
)

Clean a resource directory, deleting all files of nResType.

Parameters
sAliasA resource directory alias, NWNX or one defined in the custom resource directory file.
nResTypeThe type of file to delete or 0xFFFF for all types.
Returns
TRUE if successful, FALSE on error.

Definition at line 645 of file nwnx_util.nss.

◆ NWNX_Util_GetModuleTlkFile()

string NWNX_Util_GetModuleTlkFile ( )

Return the filename of the tlk file.

Returns
The name

Definition at line 654 of file nwnx_util.nss.

Variable Documentation

◆ NWNX_UTIL_RESREF_TYPE_NSS

const int NWNX_UTIL_RESREF_TYPE_NSS = 2009

Definition at line 14 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_NCS

const int NWNX_UTIL_RESREF_TYPE_NCS = 2010

Definition at line 15 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_AREA_ARE

const int NWNX_UTIL_RESREF_TYPE_AREA_ARE = 2012

Definition at line 16 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_TWODA

const int NWNX_UTIL_RESREF_TYPE_TWODA = 2017

Definition at line 17 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_AREA_GIT

const int NWNX_UTIL_RESREF_TYPE_AREA_GIT = 2023

Definition at line 18 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_ITEM

const int NWNX_UTIL_RESREF_TYPE_ITEM = 2025

Definition at line 19 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_CREATURE

const int NWNX_UTIL_RESREF_TYPE_CREATURE = 2027

Definition at line 20 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_DIALOG

const int NWNX_UTIL_RESREF_TYPE_DIALOG = 2029

Definition at line 21 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_TRIGGER

const int NWNX_UTIL_RESREF_TYPE_TRIGGER = 2032

Definition at line 22 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_SOUND

const int NWNX_UTIL_RESREF_TYPE_SOUND = 2035

Definition at line 23 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_ENCOUNTER

const int NWNX_UTIL_RESREF_TYPE_ENCOUNTER = 2040

Definition at line 24 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_DOOR

const int NWNX_UTIL_RESREF_TYPE_DOOR = 2042

Definition at line 25 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_PLACEABLE

const int NWNX_UTIL_RESREF_TYPE_PLACEABLE = 2044

Definition at line 26 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_STORE

const int NWNX_UTIL_RESREF_TYPE_STORE = 2051

Definition at line 27 of file nwnx_util.nss.

◆ NWNX_UTIL_RESREF_TYPE_WAYPOINT

const int NWNX_UTIL_RESREF_TYPE_WAYPOINT = 2058

Definition at line 28 of file nwnx_util.nss.