Editing 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=
<source lang="papyrus">
 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
</source>

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:
<source lang="papyrus">
 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
</source>

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

Example:
<source lang="papyrus">
 QuestStage Property MyQuestStage Auto
</source>

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:
<source lang="papyrus">
 Point[] LotsOfPoints = new Point[100]
 int i = 0
 while i < LotsOfPoints.Length
    LotsOfPoints[i] = new Point
    i += 1
 endWhile
</source>

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:
<source lang="papyrus">
 Function MyPointFunction(Point myPoint, float amountToAdd)
   myPoint.x += amountToAdd ; Changes value passed in!
   myPoint.y += amountToAdd
 EndFunction
</source>

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

Example:
<source lang="papyrus">
 Point Function MyReturnPointFunction()
   Point somePoint = new Point
   somePoint.X = 10.0
   somePoint.Y = 20.0
   return somePoint
 endFunction
</source>

=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:
<source lang="papyrus">
 new Point
 new QuestStage
</source>

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

Example:
<source lang="papyrus">
 MyPointFunction(new Point)
</source>

=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:
<source lang="papyrus">
 myPoint.X = 1.0
 TheQuest = MyQuestStage.QuestToSet
</source>

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

Example:
<source lang="papyrus">
 MyQuestStage.QuestToSet.SetStage(MyQuestStage.StageToSet)
</source>

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:
<source lang="papyrus">
 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
</source>

=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 an 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:
<source lang="papyrus">
 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
</source>
[[Category: Papyrus]]
[[Category: Papyrus Tutorials]]


= 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 [[Script File Structure#Imports|Import]], just like with global functions.

=== Examples ===
<source lang="papyrus">
; Assume Point struct is defined in MyScript
MyScript:Point myPoint = new MyScript:Point
</source>