NWScript Basics

Before we can really being discussing the actual contents of the NWScript Compiled Script (NCS) file, we first must go over some of the basic concepts of the NWScript engine.

NWScript is a small instruction set byte code engine.  This means that instead of compiling the script into x86 machine instructions, the compiler generates a series of platform independent commands.  Languages such as Forth or Java use similar techniques to store their compiled source.  When a script needs to be executed, current byte code is fetched from the compiled script and then depending on the value of the byte code, the script engine executes some predefined operation.

NWScript Stack Basics

In a real machine code program, local variables can be stored in specific memory locations, memory relative to a stack pointer, or even in the CPU registers.  Byte code engines don't have the luxury of using CPU registers.  Thus they are limited to variables being stored in specific memory locations or relative to a stack pointer.  In the case of NWScript, all variables are accessed relative to a stack pointer.  Global variables don't exist in the traditional sense.

Since variables are all accessed off the stack without CPU registers, then operators such as addition must operate differently.  In machine code, if you wished to add two values, the values would be loaded into registers and then the operator is executed.  (Note: That is a drastic simplification)  With NWScript, operators always use the top most variable or variables on the stack.  Once the operation is complete, the variables are removed and the result is placed on the stack.  Thus, if you have a variable called "nValue" that you wished to negate but not lose "nValue" on the stack, you would first have make a copy of the variable onto the top of the stack and then invoke the operator.

Let us look at an example program:

void main ()

{

    int i = 12;

    int j = 1;

    i = i + j;

}

The first two lines of the program declare two variables "i" and "j".  Once these two statements are complete, the stack looks as follows:

It is important to note that the NWScript stack builds up in increments of 4.  Thus when accessing values on the stack, they must be referenced using negative offsets where "-4" points to the top most element on the stack.

The next step is to make a copy of "i" so that we can operate on it.

Next, we need to make a copy of "j".

Now that we have the two values on the top of the stack, we can invoke the operator to compute the results.

The final step is the assignment.  To do this, we copy the top of the stack down to the variable and then remove the top of the stack.

The current top of stack is also known as the stack pointer (SP).

NWScript Global Variables

As stated previously, NWScript does not have global variables in the tradition sense where the values a stored in a known region of memory.  In NWScript, global variables are placed onto the stack by a dummy shell routine.  This routine wraps the "main" or "StartingConditional" routine.  So when a script is executed with global variables, "main" and "StartingConditional" are not the first routines to be invoked.  The "#globals" routine is invoked to place the globals onto the stack and then it invokes "main" or "StartingConditional".

However, placing global variables on the stack is only half the problem.  Routines inside the script must be able to know how to reference the variables.  For a routine such as "main" that is invoked directly from "#globals", it knows how deep down in the stack the global variables would be.  If it had two local variables and needed to access the top global variable, it could use an offset of -12 (3 variables down time -4).  However, subroutines called by "main" would have no idea how deep down the stack the global variables exist. 

To solve this problem, Bioware created a second stack pointer called "BP" which is traditionally called base pointer for Intel processors.  Inside the "#globals" routine just prior to invoking "main" or "StartingConditional", the current stack pointer (SP) is saved and becomes the new value of BP.  Then when "main" or and subroutine needs to access a global variable, it just needs to access them relative to BP.

For simplicity, there are not many operations that can be done to a variable relative to BP.  A copy of a variable can be placed on the top of the stack.  The current top of stack can be assigned to a variable relative to BP.  And a variable relative to BP can be incremented or decremented.

Calling Subroutines and Engine Routines (ACTIONS)

Invoking subroutines or engine routines is done basically in the same manner.  Arguments are placed on the stack in reverse order.  The call is then made and the callee removes all the arguments from the stack prior to returning.

However, return values are handled differently.  In the case of a script subroutine that returns a value, space for the return value is reserved, then the arguments are placed on the stack and finally the subroutine is invoked.  In the case of an engine routine, it is the job of the engine routine to place the return value on the stack after the calling arguments are removed.

Here is an example of a call to a subroutine:

int j = DoSomeScriptSubroutine (12, 14); 

Prior to the call, the stack looks as follows:

After the call, the stack looks as follows:

Here is an example of a call to an engine routine:

int j = DoSomeEngineRoutine (12, 14); 

Prior to the call, the stack looks as follows:

After the call, the stack looks as follows:

Byte Code Basics

All NWScript byte codes start with two bytes.  The first byte is the instruction such as "RETN" or "JSR".  The second byte is the type of the instruction such as an integer or floating point operation.

Following is a list of all the different types:

The value listed in parenthesis next to the type name is the short hand name used to identify different byte codes.  For example ADDII would add two integer values.

The TT opcode type is used to compare ranges of elements on the stack.  More specifically, it is used for structures and vectors.

Byte Codes

Following is a list and description of all the known byte codes. 

NOTE: All multi-byte values are stored in big endian order.

CPDOWNSP - Copy Down Stack Pointer

Copy the given number of bytes from the top of the stack down to the location specified.

The value of SP remains unchanged.

RSADDx- Reserve Space on Stack
RSADDI- Reserve Integer Space on Stack
RSADDF- Reserve Float Space on Stack
RSADDS- Reserve String Space on Stack
RSADDO- Reserve Object Space on Stack

Reserve space on the stack for the given variable type.

The value of SP is increased by the size of the type reserved.  (Always 4)

CPTOPSP - Copy Top Stack Pointer

Add the given number of bytes from the location specified in the stack to the top of the stack.

The value of SP is increased by the number of copied bytes.

CONSTI - Place Constant Integer Onto the Stack

Place the constant integer onto the top of the stack.

The value of SP is increased by the size of the type reserved.  (Always 4)

CONSTF - Place Constant Float Onto the Stack

Place the constant float onto the top of the stack.

The value of SP is increased by the size of the type reserved.  (Always 4)

CONSTS - Place Constant String Onto the Stack

Place the constant string onto the top of the stack.

The value of SP is increased by the size of the type reserved.  (Always 4)

CONSTO - Place Constant Object ID Onto the Stack

Place the constant object ID onto the top of the stack.

The value of SP is increased by the size of the type reserved.  (Always 4)

ACTION - Call an Engine Routine

Invoke the engine routine specified.  All arguments must be placed on the stack in reverse order prior to this byte code.  The arguments will be removed by the engine routine and any return value then placed on the stack.

The value of SP is increased by the size of the return value and decreased by the total size of the arguments.  It is important to note that the total size of the arguments might be different than the number of arguments.  Structures and vectors are take up more space than normal types.

LOGANDII - Logical AND Two Integers

Compute the logical AND of two integer values.

The value of SP is increased by the size of the result while decreased by the size of both operands.

LOGORII - Logical OR Two Integers

Compute the logical OR of two integer values.

The value of SP is increased by the size of the result while decreased by the size of both operands.

INCORII - Bitwise Inclusive OR Two Integers

Compute the inclusive OR of two integer values.

The value of SP is increased by the size of the result while decreased by the size of both operands.

EXCORII - Bitwise Exclusive OR Two Integers

Compute the exclusive OR of two integers.

The value of SP is increased by the size of the result while decreased by the size of both operands.

BOOLANDII - Boolean or Bitwise AND Two Integers

Compute the boolean AND of two integers.

The value of SP is increased by the size of the result while decreased by the size of both operands.

EQUALxx - Test for Logical Equality
EQUALII - Test for Logical Equality Two Integers
EQUALFF - Test for Logical Equality Two Floats
EQUALSS - Test for Logical Equality Two Strings
EQUALOO - Test for Logical Equality Two Object IDs

Test the two operand for logical equality.  This operator supports the comparison or all the basic types and then engine types as long as both operands have the same type.

The value of SP is increased by the size of the result while decreased by the size of both operands.

EQUALTT - Test for Logical Equality Two Structures

Test the two operand for logical equality.  This operator supports the comparison or all the basic types and then engine types as long as both operands have the same type.

The value of SP is increased by the size of the result while decreased by the size of both operands.

NEQUALxx - Test for Logical Inequality
NEQUALII - Test for Logical Inequality Two Integers
NEQUALFF - Test for Logical Inequality Two Floats
NEQUALSS - Test for Logical Inequality Two Strings
NEQUALOO - Test for Logical Inequality Two Object IDs

Test the two operand for logical inequality.  This operator supports the comparison or all the basic types and then engine types as long as both operands have the same type.

The value of SP is increased by the size of the result while decreased by the size of both operands.

NEQUALTT - Test for Logical Inequality Two Structures

Test the two operand for logical inequality.  This operator supports the comparison or all the basic types and then engine types as long as both operands have the same type.

The value of SP is increased by the size of the result while decreased by the size of both operands.

GEQxx - Test for Greater Than or Equal
GEQII - Test for Greater Than or Equal Two Integers
GEQFF - Test for Greater Than or Equal Two Floats

Test the two operand for logically greater than or equal.

The value of SP is increased by the size of the result while decreased by the size of both operands.

GTxx - Test for Greater Than
GTII - Test for Greater Than Two Integers
GTFF - Test for Greater Than Two Floats

Test the two operand for logically greater than.

The value of SP is increased by the size of the result while decreased by the size of both operands.

LTxx - Test for Less Than
LTII - Test for Less Than Two Integers
LTFF - Test for Less Than Two Floats

Test the two operand for logically less than.

The value of SP is increased by the size of the result while decreased by the size of both operands.

LEQxx - Test for Less Than or Equal
LEQII - Test for Less Than or Equal Two Integers
LEQFF - Test for Less Than or Equal Two Floats

Test the two operand for logically less than or equal.

The value of SP is increased by the size of the result while decreased by the size of both operands.

SHLEFTII - Shift the Integer Value Left

Shift the value left be the given number of bits.  Operand one is the value to shift while operand two is the number of bits to shift.

The value of SP is increased by the size of the result while decreased by the size of both operands.

SHRIGHTII - Shift the Integer Value Right

Shift the value right be the given number of bits.  Operand one is the value to shift while operand two is the number of bits to shift.

The value of SP is increased by the size of the result while decreased by the size of both operands.

USHRIGHTII - Unsigned Shift the Integer Value Right

Shift the value right be the given number of bits as if it was an unsigned integer and not a signed integer.  Operand one is the value to shift while operand two is the number of bits to shift.

The value of SP is increased by the size of the result while decreased by the size of both operands.

ADDxx - Add Two Values
ADDII - Add Two Integer Values
ADDIF - Add an Integer and Float Values
ADDFI - Add a Float and Integer Values
ADDFF - Add Two Float Values
ADDSS - Add Two String Values
ADDVV - Add Two Vector Values

Add the two operands.

The value of SP is increased by the size of the result while decreased by the size of both operands.

SUBxx - Subtract Two Values
SUBII - Subtract Two Integer Values
SUBIF - Subtract an Integer and Float Values
SUBFI - Subtract a Float and Integer Values
SUBFF - Subtract Two Float Values
SUBVV - Subtract Two Vector Values

Subtract the two operands. 

The value of SP is increased by the size of the result while decreased by the size of both operands.

MULxx - Multiply Two Values
MULII - Multiply Two Integer Values
MULIF - Multiply an Integer and Float Values
MULFI - Multiply a Float and Integer Values
MULFF - Multiply Two Float Values
MULVF - Multiply a Vector and Float Values
MULFV - Multiply a Float and Vector Values

Multiply the two operands.

The value of SP is increased by the size of the result while decreased by the size of both operands.

DIVxx - Divide Two Values
DIVII - Divide Two Integer Values
DIVLIF - Divide an Integer and Float Values
DIVFI - Divide a Float and Integer Values
DIVFF - Divide Two Float Values
DIVVF - Divide a Vector and Float Values

Divide the two operands.

The value of SP is increased by the size of the result while decreased by the size of both operands.

MODII- Compute the Modulus of Two Integer Values

Computes the modulus of two values.

The value of SP is increased by the size of the result while decreased by the size of both operands.

NEGx - Compute the Negation of a Value
NEGI - Compute the Negation of an Integer Value
NEGF - Compute the Negation of a Float Value

Computes the negation of a value.

The value of SP remains unchanged since the operand and result are of the same size.

COMPI - Compute the One's Complement of an Integer Value

Computes the one's complement of a value.

The value of SP remains unchanged since the operand and result are of the same size.

MOVSP - Adjust the Stack Pointer

Add the value specified in the instruction to the stack pointer.

The value of SP is adjusted by the value specified.

STORE_STATEALL - Store the Current State of the Stack (Obsolete)

Obsolete instruction to store the state of the stack and save a pointer to a block of code to later be used as an "action" argument.  This byte code is always followed by a JMP and then a block of code to be executed by a later function such as a DelayCommand.

The value of SP remains unchanged.

JMP - Jump to a New Location

Change the current execution address to the relative address given in the instruction.

The value of SP remains unchanged.

JSR - Jump to Subroutine

Jump to the subroutine at the relative address given in the instruction.  If the routine returns a value, the RSADDx instruction should first be used to allocate space for the return value.  Then all arguments to the subroutine should be pushed in reverse order.

The value of SP remains unchanged.  The return value is NOT placed on the stack.

JZ - Jump if Top of Stack is Zero

Change the current execution address to the relative address given in the instruction if the integer on the top of the stack is zero.

The value of SP is decremented by the size of the integer.

RETN - Return from a JSR

Return from a JSR.  All arguments used to invoke the subroutine should be removed prior to the RETN.  This leaves any return value on the top of the stack.  The return value must be allocated by the caller prior to invoking the subroutine.

The value of SP remains unchanged.  The return value is NOT placed on the stack.

DESTRUCT - Destroy Element on the Stack

Given a stack size, destroy all elements in that size excluding the given stack element and element size.

The value of SP decremented by the given stack size minus the element size.

NOTI - Compute the logical NOT of an Integer Value

Computes the logical not of the value.

The value of SP remains unchanged since the operand and result are of the same size.

DECISP - Decrement Integer Value Relative to Stack Pointer

Decrements an integer relative to the current stack pointer.

The value of SP remains unchanged.

INCISP - Increment Integer Value Relative to Stack Pointer

Increments an integer relative to the current stack pointer.

The value of SP remains unchanged.

JNZ - Jump if Top of Stack is Non-Zero

Change the current execution address to the relative address given in the instruction if the integer on the top of the stack is non-zero.

The value of SP is decremented by the size of the integer.

CPDOWNBP - Copy Down Base Pointer

Copy the given number of bytes from the base pointer down to the location specified. This instruction is used to assign new values to global variables.

The value of SP remains unchanged.

CPTOPBP - Copy Top Base Pointer

Add the given number of bytes from the location specified relative to the base pointer to the top of the stack.  This instruction is used to retrieve the current value of global variables.

The value of SP is increased by the number of copied bytes.

DECIBP - Decrement Integer Value Relative to Base Pointer

Decrements an integer relative to the current base pointer.  This instruction is used to decrement the value of global variables.

The value of SP remains unchanged.

INCIBP - Increment Integer Value Relative to Base Pointer

Increments an integer relative to the current base pointer.  This instruction is used to increment the value of global variables.

The value of SP remains unchanged.

SAVEBP  - Set a New Base Pointer Value

Save the current value of the base pointer and set BP to the current stack position.

The value of SP remains unchanged.

RESTOREBP - Restored the BP

Restore the BP from a previous SAVEBP instruction.

The value of SP remains unchanged.

STORE_STATE - Store the Current Stack State

Store the state of the stack and save a pointer to a block of code to later be used as an "action" argument.  This byte code is always followed by a JMP and then a block of code to be executed by a later function such as a DelayCommand.

The value of SP remains unchanged.

NOP - No-operation

Perform no program function.  This opcode is used as a placeholder for the debugger.

The value of SP remains unchanged.

T - Program Size

This byte code isn't a real instruction and is always found at offset 8 in the NCS file.

The value of SP remains unchanged.