Basic Scripting (not so basic)

This is too shoddy to present as a document, but since a couple individuals recently expressed an interest in scripting here's a bunch of stuff, mostly off the top of my head:



here's the script that taught me everything I know about scripting:

void main()
{
}


void is a return type. Every function needs a return type, even if it's void - a null return.

main() is the name of a function. It can be thought of as the entry point of the script. The engine enters the script at main(). The only other entry point function that NwScript allows is:

int StartingConditional()
{
}


Note that it returns an int, an integer value. The engine will interpret this as a TRUE or FALSE value - FALSE=0, TRUE=anythingelse. A StartingConditional() script is useful only in dialogs, where they can be used to determine conversation flow (think of it as start/show the dialog-node, the node that the script is placed as a Condition to).

So, main() scripts are far more common. The engine is designed with hookpoints called events; it can be told to handle an event by putting the name of a valid, compiled, accessible script in an object's event slot, using the toolset. Many if not all IG objects other than Items (see Appendix B) have hookable events.

Scripts are plain textfiles with extension .NSS
Compiling a script creates a binary file with extension .NCS, typically in the same directory with the .NSS file.

Different types of objects have different sets of events. For example, the module-object has an OnAcquireItem event, while a placeable-object has an OnSpellCastAt event. Note that both of those object-types also have an OnHeartbeat event, which is checked by the engine every 6 seconds by default (this can be changed for an object, but usually a pseudo-heartbeat* is implemented instead of mucking with the default 6 seconds).

*not covered.


The set of module-level events can be found under View|ModuleProperties|Scripts, and events for other objects are under their Properties|Scripts.


In general, object is a concept that can denote anything from an integer to a module. It basically means, a bunch of bits held together by the language that created it. But since object is also a very specific technical term in NwScript, let's talk about types.

NwScript implements the following types:

int
float
string
vector
effect
event
location
talent
itemproperty
object
struct
 

In order for a compiler to know what the heck is going on, all variables need to be declared with a type ASAP (see Appendix F). This is a declaration of variable i as type integer:

int i;

This is the definition of i with a value:

int i = 10;

Once declared, a variable can have a value assigned to it:

i = 0;


Functions can also be used to assign values to variables:

object oNearest = GetNearestObject();

So ... you've got an object. Now let's check if it's a player-controlled creature:

if (GetIsPC(oNearest))
{
}

If it is a player-controlled creature, the engine will run any code between the curly braces. If it's not, then the engine will skip it and move on through the rest of a script. Code-flow in NwScript is always sequential: one thing happens after another in the order they appear in a script.

However, there are exceptions to sequential code-flow. When a function is wrapped in a DelayCommand() function, even if the delay is 0 seconds, it will be postponed till after the script finishes. The function DestroyObject() also takes a delay parameter, and will be postponed till after the script that it was called by finishes.


Most functions have parameters that take arguments, that are passed into a function call, to better hone in on what you want the function to do. For example, the declaration of GetNearestObject() looks like this:

object GetNearestObject(int nObjectType=OBJECT_TYPE_ALL, object oTarget=OBJECT_SELF, int nNth=1);

To get the 2nd-nearest creature to an object with tag "table", the definition of oNearest looks like so:

object oNearest = GetNearestObject(OBJECT_TYPE_CREATURE, GetObjectByTag("table"), 2);

To make things read more clearly, that is the same as this:

object oTable = GetObjectByTag("table");
object oNearest = GetNearestObject(OBJECT_TYPE_CREATURE, oTable, 2);

If you're unsure whether a table will exist at the time your script runs, it can be checked for validity:
- note that this uses the 1st-nearest table, and uses a hardcoded function that combines the two previous functions

object oTable = GetNearestObjectByTag("table");
if (GetIsObjectValid(oTable))
{
    // it exists, so let's do something silly with the table:

    effect eFire = EffectVisualEffect(VFX_HIT_AOE_FIRE);
    ApplyEffectToObject(DURATION_TYPE_INSTANT, eFire, oTable);

    DestroyObject(oTable);
}

[aside] Comments:
// this is a comment.
/* this is
   also a comment */

Okay. You may have noticed that the table that caught fire and got destroyed was defined as the nearest object. This begs the question, the nearest object to WHAT exactly. Answer: the table is the nearest object to the object that ran the script. The object that runs a script can be found by using

OBJECT_SELF

For example, in a trigger's OnEnter script, the trigger-object itself can be defined as:

object oTrigger = OBJECT_SELF;

To get the table nearest to the trigger:

object oTrigger = OBJECT_SELF;
object oTable = GetNearestObjectByTag("table", oTrigger);

But wait. The second parameter of GetNearestObjectByTag() has a default value of OBJECT_SELF already:

object GetNearestObjectByTag(string sTag, object oTarget=OBJECT_SELF, int nNth=1);

Default values are assigned to function parameters with an equals sign followed by a constant. A constant is a variable that doesn't change. I'll let you figure that one out ....

Hardcoded constants are defined in the file 'nwscript.nss' along with all the hardcoded functions. When the compiler sees a scripted constant it replaces it with its literal value automatically.

A function parameter that has a default value does not have to be specified as an argument as long as no subsequent argument is passed in after it. That is, this is not allowed:

object oTable = GetNearestObjectByTag("table", , 2);

This is allowed:

object oTable = GetNearestObjectByTag("table", OBJECT_SELF, 2);

A note on GetNearestObjectByTag() vs. GetObjectByTag() - the latter searches the entire currently loaded module, while the former searches only the area that the object that runs the script (OBJECT_SELF) resides in. And GetNearestObject*() will not return itself btw.



right, fine. Let's talk code-flow ....

object oTable = GetObjectByTag("table");
if (GetIsObjectValid(oTable))
{
}
else // what to do if a table is not valid ->
{
}


if/else conditions can be strung together:

if (GetIsDay())
{
    // debug
    SendMessageToPC(GetFirstPC(), "it is Day");
}
else if (GetIsDusk())
{
    // debug
    SendMessageToPC(GetFirstPC(), "it is Dusk");
}
else if (GetIsNight())
{
    // debug
    SendMessageToPC(GetFirstPC(), "it is Night");
}
else //if (GetIsDawn()) // this check is redundant since it's the only possibility left
{
    // debug
    SendMessageToPC(GetFirstPC(), "it is Dawn");
}


The above method of debugging is *highly* effective. When you get a problem with a script the first thing to do is check if it's even running:

void main()
{
    SendMessageToPC(GetFirstPC(FALSE), "Run your_script by " + GetName(OBJECT_SELF) + " (" + GetTag(OBJECT_SELF) + ")");

    // code follows ->
    if (GetLocalInt(OBJECT_SELF, "local_int"))
    {
        SendMessageToPC(GetFirstPC(FALSE), ". value of local_int= " + IntToString(GetLocalInt(OBJECT_SELF, "local_int")));
    }
    else
        SendMessageToPC(GetFirstPC(FALSE), ". local_int is 0");
}


Notice I left the curly braces off of the else-block. This is allowed but is NOT recommended for n00bs since complicated code-sequences can really screw up and you won't have a clue what went wrong.

Another screw up is using = (assignment of a value to a variable) instead of == (equivalence check if two values are identical), or vice versa. DON'T DO IT. read: you will. So don't


for-loops

int i;
for (i = 0; i != 10; ++i)
{
    // this code will loop 10 times.
}

i starts at 0, is checked that it does not equal 10, then is incremented *after* the first pass, when it is again checked that it does not equal 10 *before* the second pass. This procedure repeats until i does equal 10, at which the for-loop exits immediately.


while-loops

int i = 0;
while (i != 10)
{
    ++i;
    // this code will loop 10 times.
}

Notice that the while keyword is merely a looped if statement. The engine would deal with an infinite loop by throwing a TMI error (Too Many Instructions).

[aside] A keyword is a reserved word in the language. They cannot be used as labels of variables or functions. Examples are int, object, if, while, void ....


[aside] do/while loops are not covered here. (hint: They always do at least one pass through their code-block, then the loop-condition is evaluated only *after* the first pass.)


Note that the iterator does not have to be an integer:

object oPlayerPC = GetFirstPC();
while (GetIsObjectValid(oPlayerPC))
{
    // this code will loop over all true PCs (ie. Owned Characters) that are
    // currently in the module.
    
    oPlayerPC = GetNextPC();
}


Note on incrementing by 1, all these result in the same thing:

int i;
i = i + 1;
i += 1;
++i; // the variable is incremented by one, then used in the expression
i++; // the variable is used in the expression, then incremented by 1

Decrementing by 1 works the same way, except it uses the - operator.


Multiplication and division operations have similar shortcuts:

int i, j;

i = i * j;
i *= j;

i = i / j;
i /= j;

The standard algebra rules apply: multiplication and division happens before addition and subtraction (unless bracketed ofc), and divide by zero is not allowed (although NwScript is forgiving).


switches

int iLocal = GetLocalInt(OBJECT_SELF, "local_int");
switch (iLocal)
{
    case 0:
        // run code here if the local is 0
        break;
    case 1:
        // run code here if the local is 1
        break;
    case 2:
        // run code here if the local is 2
        break;
    default:
        // run code here if (iLocal != 0 && iLocal != 1 && iLocal != 2)
        break;
}


switch w/ fall-through:

int iLocal = GetLocalInt(OBJECT_SELF, "local_int");
switch (iLocal)
{
    case 0:
        // run code here if (iLocal == 0)
    case 1:
        // run code here if (iLocal == 0 || iLocal == 1)
    case 2:
        // run code here if (iLocal == 0 || iLocal == 1 || iLocal == 2)
        break;

    default:
        // run code here if (iLocal != 0 && iLocal != 1 && iLocal != 2)
        break;
}

Note: switch/case statements (in NwScript) only work with integers. They are similar to but generally faster than (large) if/else blocks.


break and continue keywords

break; is used to immediately stop and exit a loop, or simply to exit a switch/case block.

string sRoster = GetFirstRosterMember();
while (sRoster != "")
{
    object oRoster = GetObjectFromRosterName(sRoster);
    if (GetIsObjectValid(oRoster) && !GetIsDead(oRoster))
    {
        // an instantiated roster-member is not dead
        SetLocalInt(GetModule(), "isRosterAlive", TRUE);
        break;
    }

    sRoster = GetNextRosterMember();
}


continue; is used to go back to the top of a loop, bypassing any code that's within the loop-block below it, typically causing the iterator to advance and get re-checked against the stop-condition.

string sRoster = GetFirstRosterMember();
while (sRoster != "")
{
    object oRoster = GetObjectFromRosterName(sRoster);
    if (!GetIsObjectValid(oRoster) || GetIsDead(oRoster))
    {
        // roster-member is either invalid or is already dead
        sRoster = GetNextRosterMember();
        continue;
    }

    // the roster-member is instantiated and not dead here, kill it
    effect eDeath = EffectDeath();
    ApplyEffectToObject(DURATION_TYPE_INSTANT, eDeath, oRoster);

    sRoster = GetNextRosterMember();
}

note: There are better ways to do that - it's just an example.


The return keyword:

return; causes a script to immediately exit - program execution returns to the engine. A void-returning function infers this at its final curly brace, but functions that specify any other return type require something to be returned explicitly.

int GetIsRosterAlive()
{
    if (GetLocalInt(GetModule(), "isRosterAlive"))
    {
        return TRUE;
    }
    return FALSE;
}


Operators (in no particular order):

=   assign value
==  equivalent to
!=  not equivalent to
>   greater than
<   less than
>=  greater than or equal to
<=  less than or equal to
&&  boolean AND
&   bitwise AND (both bits true)
&=  bitwise AND and assign
||  boolean OR
|   bitwise OR (either bit true)
|=  bitwise OR and assign
^   bitwise XOR (either bit true but not both)
^=  bitwise XOR and assign
~   bitwise NOT (invert bits)
.   dot-accessor
!   boolean NOT
+   addition or string concatenation
++  pre or post increment
+=  addition or string concatenation and assign
-   subtraction
--  pre or post decrement
-=  subtraction and assign
*   multiplication
*=  multiplication and assign
/   division
/=  division and assign
%   modulo
%=  modulo and assign
>>  bitwise shift right
>>= bitwise shift right and assign
<<  bitwise shift left
<<= bitwise shift left and assign
?:  ternary conditional operator

(hint: do a Google for a C-like tutorial) Be careful with operator precedence, and bracket (especially bitwise) operations accordingly.


The ternary operator. In the following definition of oPC, if the expression before the question-mark evaluates TRUE, oPC will be the value before the colon; if FALSE, the value after the colon is assigned instead:

object oPC = (GetPCSpeaker() == OBJECT_INVALID) ? OBJECT_SELF : GetPCSpeaker();

It's a different way of doing this:

object oPC = GetPCSpeaker();
if (!GetIsObjectValid(oPC))
{
    oPC = OBJECT_SELF;
}


Note that conditional expressions can be grouped together to test what you want:

object oCreature = GetNearestObject();
if ((GetObjectType(oCreature) == OBJECT_TYPE_CREATURE && GetCreatureSize(oCreature) >= CREATURE_SIZE_LARGE)
    || GetTag(oCreature) == "big_bad_boss")
{
    // this code will run if either of these conditions evaluated TRUE:
    // 1) the object-type is OBJECT_TYPE_CREATURE of CREATURE_SIZE_LARGE or CREATURE_SIZE_HUGE
    // 2) the object has tag "big_bad_boss"
}

Notice that parentheses should be used to subgroup distinct sets of conditions.


Tags are Case Sensitive! So are identifiers (ie. variables and functions).


The equivalence operators (==, !=) can evaluate variables of the same type only; eg, an int against an int, or an object against an object. The compiler will throw an error if there's a type mismatch.



Speaking of compilers: Please use Skywing's Advanced Script Compiler for NWN2