Introduction to struct

This tutorial assumes you have basic knowledge of scripting, functions, and include files. Structs are a more advanced topic and it is recommended you learn basic scripting before attempting to build a struct.

Structure
The Word Struct is short for "structure". By definition; strucâ€¢ture
 * Something built or erected; a building, bridge, framework, or other object that has been put together from many different parts
 * Orderly system of parts; a system or organization made up of interrelated parts functioning as an orderly whole

This is much how a struct is in coding, it is a data type (variables) that hold values of many other data types. It is a "structure" formed by many different variables.

Lets take a look at a struct that you are probably familiar with already, GetLocation. This function returns the location of an object, that location actually contains 3 parts. The Area of the location, the vector of the location, and the facing of the object you are getting the location from. So GetLocation contains a variable of data type object, a variable of data type vector, and a variable of data type float. But wait, a vector has 3 parts, x ,y, and z. This is because a vector is also a struct, containing 3 variables of data type float.

To put it a simply way, a struct is nothing more than several variables placed into a single variable called a struct.

To make our own struct, we first need to declare the variables used within the struct just as we declare normal variables in side a void main. Or similarly, we need to draw the blue print to build the structure.

For this tutorial, we will construct a struct variable to hold some data about the PC. For this we will need the Players Name, The Players CD Key and the Players current Level. So lets layout our blueprint.

Open the script editor and comment out the void main and the two {}â€™s. We wonâ€™t need those as this will become our include scripts. I say, comment instead of delete because of a trick Iâ€™ll show you later.

struct PCInfo {  string name; string key; int level; }; //void main //{}

Save the file as "my_struct". "Struct" is the data type, "PCInfo" is the variable name. The 3 variables inside the {} name, key, and level are the 3 bits of information that we are going to include in this single variable "PCInfo".

Notice the ";" after the last "}". This is important because remember, you are declaring a variable. So just as an int variable, int I = 1; you need a ; after a struct variable declaration as well.

Now that we have our blue print, we need a way to declare values for each variable inside the struct. For that we need a "structured function" or "Struct Funct" (say that 5 times fast ). Basically, a structured function is nothing more than a custom function that places the data we need into the struct.

For those that have built your own functions, this will look somewhat familiar to you. The sysntax for a normal function is; Return_value Function_Name [(parameters)] A structured function sysntax is; Return_Value Variable_Name Function_Name[(parameters)]

For example, a normal function might be; int My_Function(object oPC) int is the Return_Value, My_Function is the Function_Name, and (object oPC) is the parameters.

We have already defined the variable in the script above, so when making a struct function we need to include the variable name so nwscript knows which struct variable your talking about. Lets call the function GetData, so following the sysntax we would enter this; struct PCInfo GetData(object oPC) So struct is the Return_Value, PCInfo is the Variable_Name, GetData is the Function_Name and (object oPC) is the parameter.

In the same file we just created, add our structured function

struct PCInfo {   string name; string key; int level; }; struct PCInfo GetData(object oPC) { } //void main //{}

Before we can get any data we need, we must declare another variable name that will hold the information that we are going to return to the script, or a return value. Lets call this variable "ValToReturn". So add this line to your struct function;

struct PCInfo ValToReturn;

Now we need to plug in our values but before we do that, I need to introduce you to the dot operator. The dot or period "." Is used to tell the struct that there is more information after the ValToReturn variable. Think of it as a whole number with a remainder. For example, 1.5 is telling us that the value is more than 1, but less than 2. Lets plug in our values, then I will explain more. Add the following these lines, now your function should look like this;

struct PCInfo {   string name; string key; int level; }; struct PCInfo GetData(object oPC) {   struct PCInfo ValToReturn; ValToReturn.name = GetName(oPC); ValToReturn.key = GetPCPublicCDKey(oPC); ValToReturn.level = GetHitDice(oPC); }

//void main //{}

Look at the variable ValToReturn as the "whole number" and the ".name" as the remainder. Notice that the name, key, level, are the same variables that we laid out in our struct PCInfo blue print. What this does is make the variable ValToReturn equal to the name, key, and level, all at the same time.

Now to show you my little trick, click the "save" button. You should not get any compile error, in fact you shouldnâ€™t get any message at all. So did that file save correctly? We wonâ€™t know unless we compile it.

Now uncomment the void main and the 2 {}â€™s then click the save button again. You should get the following error: ERROR: NOT ALL CONTROL PATHS RETURN A VALUE The void main forces the struct function to compile as a normale script. This is a easy way to detect typos before you try to include the file in another script. The error produced is because we didnâ€™t enter a return for the function. Lets add that now,

struct PCInfo {   string name; string key; int level; }; struct PCInfo GetData(object oPC) {   struct PCInfo ValToReturn; ValToReturn.name = GetName(oPC); ValToReturn.key = GetPCPublicCDKey(oPC); ValToReturn.level = GetHitDice(oPC); return ValToReturn; }

void main {}

Resave the file and the error should go away. Donâ€™t forget to re-comment out the void main part and save the file again. We now have our struct include file and we will use it in a script.

Open a new script window and above the void main include the file we just created. We are also going to call the function in that file;

void main {   object oPC = GetEnteringObject; struct PCInfo sINFO = GetData(oPC); }
 * 1) include "my_struct"

Save it as "my_script". Everything at this point should compile without any errors. The struct PCInfo is telling the script which struct to use. In this case, the PCInfo structure. sINFO is the variable name we are calling this variable. Just like any other variable and that it is equal to our function GetData.

In our include file, we packed 3 variables into one called ValToReturn using the dot operator so to extract that information, we need to use the dot operator again, ie, sINFO.name, sINFO.key and sINFO.level. Lets send this information to the Player so we can see it. Add the following so your script looks like this;

void main {   object oPC = GetEnteringObject; struct PCInfo sINFO = GetData(oPC); SendMessageToPC(oPC,sINFO.name); SendMessageToPC(oPC,sINFO.key); SendMessageToPC(oPC,IntToString(sINFO.level)); }
 * 1) include "my_struct"

Remember that level is a int variable, so it must be converted to a string just as any other int variable before we send it as a message. Save the script and place it in the OnEnter of your starting area. Now test your module. In the chat window you should see your character name, your CD key, and your current level. Note: the CD key will only be valid if you load the module up in nwserver first, then enter the game. Other wise you will only see the character name and your current level.

Congratulations! You just made your first struct.