Structs (Papyrus)

Description

Structs are special kinds of variables that can hold several named values of differing types. You access the members of a struct just like you'd access the properties of a script.

Declaring Structs

 Struct Point
   float X = 1.0
   {This is the X coordinate of the Point}
   float Y = 1.0
   {This is the Y coordinate of the Point}
 EndStruct

 Point MyPoint

 Struct QuestStage
   Quest QuestToSet
   int StageToSet
 EndStruct

 Struct OtherStruct
   float VisibleFloat
   int InivisibleInt Hidden
 EndStruct

 OtherStruct Property MyOtherStruct Auto

 Function MyFunction()
   MyPoint = new Point
   QuestStage MyQuestStage = new QuestStage
 EndFunction

Point is a struct that contains two float variables, X and Y, both of which default to 1.0. We then make a MyPoint variable that is of Point type, but it will start with the value of None, because it is uninitialized. We then give it a value inside MyFunction using the new command.

QuestStage is a struct that contains a Quest and an integer. Like MyPoint, we create a MyQuestStage variable, and give it a new value inside MyFunction.

OtherStruct is a struct containing an integer and a float, but only the float is visible in the editor UI.

Note that structs cannot contain other structs, arrays, Var variables, or const variables.

You can add documentation strings to struct variables, which will show up in the editor in the tooltips (just like documentation strings on properties).

Example:

 Struct MyBadStruct
   int[] BadArray ; BAD - cannot have arrays
   Point BadPoint ; BAD - cannot have structs
   Var BadVar ; BAD - cannot have Var types
   float BadFloat const ; BAD - cannot have const variables
 EndStruct

You can, of course, make a property that is a struct. The editor will show a special UI for it that allows you to edit it.

Example:

 QuestStage Property MyQuestStage Auto

You can also make arrays of structs. Note that when first created, the array will be nothing but NONE - in order to use an array element, you have to assign it to a struct or create a new struct.

Example:

 Point[] LotsOfPoints = new Point[100]
 int i = 0
 while i < LotsOfPoints.Length
    LotsOfPoints[i] = new Point
    i += 1
 endWhile

The new call must be done inside a function. You cannot use it on an object variable outside of a function. If you want a variable to start with an value, then you can make the struct inside the OnInit event.

Function Parameters

To accept a struct as a parameter to a function, use the same syntax as for passing a variable. Structs are passed by reference, just like arrays and scripts, so changes made to them are made to the original.

Example:

 Function MyPointFunction(Point myPoint, float amountToAdd)
   myPoint.x += amountToAdd ; Changes value passed in!
   myPoint.y += amountToAdd
 EndFunction

Returning from Function

To return a struct from a function, again, use the same syntax.

Example:

 Point Function MyReturnPointFunction()
   Point somePoint = new Point
   somePoint.X = 10.0
   somePoint.Y = 20.0
   return somePoint
 endFunction

Creating Structs

To create a struct, use the "new" keyword, followed by the struct's type. Each variable in the array will get the appropriate default value, according to the struct definition.

Example:

 new Point
 new QuestStage

Usually you'll be assigning these directly to new struct variables, but if a function wants a struct, you can make the new struct in the function call, like so:

Example:

 MyPointFunction(new Point)

Getting/Setting Members

To get a variable from an array, or to set it, use a dot with the name of the struct member after the variable name, just like accessing a property or function on a script.

Example:

 myPoint.X = 1.0
 TheQuest = MyQuestStage.QuestToSet

If the struct members are other scripts, you can access properties and functions in the same way.

Example:

 MyQuestStage.QuestToSet.SetStage(MyQuestStage.StageToSet)

Note that, since structs are passed and assigned by reference, that any modifications to a struct's elements will be reflected in any other variables looking at that struct.

Assigning/Passing Structs

Assigning one struct to another struct, or passing a struct to a function, is done just like any other variable. However, note that structs are passed/assigned by reference, just like objects (and unlike some other languages). In other words, if you assign one struct to another, both are looking at the same struct - and modifications made to one, will be reflected in the other.

Example:

 Point Point1 = new Point
 Point Point2 = Point1     ; Point1 and Point2 now look at the same struct!
 Point1.X = 10.0
 Debug.Trace(Point2.X)    ; Traces out "10.0", even though you modified the value on Point1

Casting Structs

Structs can be cast to strings, bools, or vars. If you cast a struct to a string, it will put each member in the struct inside brackets, separated by commas, prefixed by the member name, in the order they were specified in the script. If the struct is especially large, it may trim the string a little early and put an ellipsis on the end. If you cast a struct to a bool, it will be true if the variable is pointing at any non-none value, and false if it is none.

Example:

 Debug.Trace(MyPoint)    ; Traces out "[x = 1.00000, y = 1.00000]"
 if (MyPoint)
   Debug.Trace("Struct is pointing at a non-None value!")
 else
   Debug.Trace("Struct is None!")
 endIf

Accessing Struct Types in Other Scripts

You can access a struct type defined in another script by prefixing the name of the struct with the name of the script containing the struct, separating them with a colon. If you don't want to type in the script name all the type, you can use Import, just like with global functions.

Examples

; Assume Point struct is defined in MyScript
MyScript:Point myPoint = new MyScript:Point