Mod:Creation Kit/Arrays (Papyrus)

=Description=

Arrays are special kinds of variables that can hold more than one value of the same type. You select which value you want via a numerical index that ranges from zero to the length of the array, minus one. More information on arrays can be found on the Array Reference.

=Declaring Arrays=

myFloatArray specifies an empty array of floats. It has a length of 0, and is equal to None. myObjectArray also starts that way, except it is an array of ObjectReference objects. It is then assigned a new array of ObjectReference objects, with 10 elements in it (all of which start with the default value of None). myFormArray is assigned a new array of Form objects, with the same number of elements as myObjectArray has.

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 empty array, then you can make the array inside the OnInit event.

Note that you cannot have an array of arrays, or a multi-dimensional array.

You can, of course, make an property that is an array. The editor will show a special UI for it that allows you to add, remove, and re-arrange the array items inside it.

Example:

Function Parameters
To accept an array as a parameter to a function, use the same syntax as for declaring an array.

Example:

Returning from Function
To return an array from a function, again, use the same syntax.

Example:

=Creating Arrays=

To create an array, use the "new" keyword, followed by the array's element type, and the size of the array in brackets. Arrays can be any size, up to 128 elements. Attempting to create an array larger then that will fail. Every element in the array will be set to the element's default value, be that 0, false, "", or None.

Note that if you create a new array of a type that extends ScriptObject or a struct that all the elements in the array will be None. In the case of structs, you will have to then either fill the items with structs from somewhere else, or by calling new on each element. For items that extend ScriptObject you'll have to get the items from somewhere else (like a function call or a filled property)

Example:

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

Example:

=Getting/Setting Elements=

To get a single value from an array, or to set it, use brackets with the index of the element you want between them after the variable name. The index can be an integer variable, raw integer, or the result of an expression. The range of valid values is from 0 (for the first element) to the length of the array, minus 1.

Example:

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

Example:

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

=Getting Length=

You can easily get the length of any array by calling the length property on it. If you assign None to an array, the length will be 0.

Example:

=Assigning/Passing Arrays= Assigning one array to another array, or passing an array to a function, is done just like any other variable. However, note that arrays are passed/assigned by reference, just like objects. In other words, if you assign one array to another, both are looking at the same array - and modifications made to one, will be reflected in the other.

Example:

=Casting Arrays= Arrays can to strings, or bools, as well as to another array type if the elements themselves would cast. If you cast an array to a string, it will put each element in the array inside brackets, separated by commas. If the array is especially long, it may trim the string a little early and put an ellipsis on the end. If you cast an array to a bool, it will be true if the length is non-zero, and false if the length is zero. If you cast an array to another array type, the array will be duplicated and the elements cast to the desired type. Any elements that fail to cast will be left as 0, None, or an equivalent. For example, if you cast a Form array to an ObjectReference array, any elements in the Form array that are not actually ObjectReferences will be empty in the duplicate created.

Example:

=Searching Arrays= Arrays can be searched using two different methods, called "find" and "rfind". Find searches the array from the element you give it (default is element 0) and goes forward through the array to the final element, or the first match it finds, whichever is first. RFind does the same thing, only backwards, starting at the element you give it (default is -1, which means the last element) and going towards element 0. If the item is not found, it will return a negative number for the index.

Examples:

If you want to search an array of structs for a struct with a particular value, you can do so with the FindStruct and RFindStruct functions. They work identically to find and rfind, except the first parameter is the name of the struct value to look for.

Examples:

Doing Something to Every Element
Frequently you may want to do something to every element in an array. This is easily done by setting up a while loop with a counter, and then doing something to each element, like so:

Example:

Note that the while loop will go as long as the element is less than the length of the array. This is because the valid elements are zero to length minus one. If you were to make a while loop using "<=" you would error on the last element, because you would be trying to get an element one past the end of the array.

Counting Certain Elements
Sometimes you might want to count how many of X is in an array. You can do this with Find and a while loop, making sure that each find starts at one after the location where the previous find located an element. Make sure it is one past the previous location, otherwise you'll get stuck looking at the same one every time.

Example: