Wikia

NWNWiki

Introduction to struct

Talk0
3,653pages on
this wiki


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

Structure Edit

The word "struct" is short for "structure", which is defined as:

  • 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 close to what a struct is in programming: it is a data type that aggregates one or more values of other data types as a single unit.

Let us take a look at a struct that you are probably familiar with already, location, such as returned by function GetLocation(). This function returns the location of an object, which consists of 3 parts: the area in which the object is situated, the coordinate vector denoting the position of the object, and the direction to which the object is facing. So a value of type location returned by GetLocation() contains a variable of data type object, a variable of data type vector, and a variable of data type float. In addition to that, a vector itself is a struct consisting of 3 parts, which are its coordinates x, y, and z - all of type float.

To put it a simply way, a struct is nothing more than several variables placed into a single variable called a struct. These variables are typically called fields of that struct.

To make our own struct, we first need to declare the fields used within the struct just as we declare normal variables. 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 player's Name, player's CD Key and player's current Level. So let's layout our blueprint.

Open the script editor and comment out void main() and the braces. 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 keyword indicating that it is a structure, PCInfo is the name of the structure. The 3 fields inside the braces - name, key, and level - are bits of information that we are going to include in this single struct. Also notice the semicolon after the closing brace - it is required.

Now that we have our blueprint, 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;

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

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;

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

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.

Around Wikia's network

Random Wiki