List
A list is a collection of values stored under one name. It is used for storing lots of values without creating lots of variables. It is what you call an "Array" in other programming languages.
Every value in a list is assigned an index. This value can then be retrieved from a list by providing its index.
To store a value in a list, connect the variable you want to store the list at, and an index at which to store the value to a List Element, then attach the output of List Element and a value to be stored to Set Reference.
To get the value from a list, simply connect the variable and an index to a List Element, and the output will be the value in a list at that index.
Notes
- The index ranges from 0 to 1,048,575, attempting to access a list at a higher index will result in a "List too big!" error. Negative indices return the default value, and cannot be overwritten.
- Every variable can be treated as a list or a scalar (non-list). When a variable is accessed as a scalar, it points to its value at index 0.
- A non-integer index number is rounded down to an integer.
- For experienced users: Plugging the Element output to the Variable of another List Element will add their indexes. This is similar to pointer arithmetic in languages like C. See the image below:
A problem that commonly arises is the creation of 2D lists.
Example
Here is the script for when a player shoots a bullet.
Explanation:
- We create a bullet, store it in a variable, and set its position to the player's position.
- Assuming that the player faces (0, 0, 1) if its rotation is 0°, we rotate that vector (0, 0, 1) by the player's rotation, and that gets us the player's direction, which should also be the bullet's velocity.
- We add the bullet's position with the velocity and set that to be the bullet's new position, that makes the bullet move.
So far so good, until the player shoots again adding another bullet. The variable can only store one value at a time, so the first bullet and its velocity are replaced with the second, the second bullet moves like it should, but the first bullet stop because it's no longer affected by the script. How do we fix that?
Lists are like variables, but they can store more values in one, so we just have to store the bullets and their velocities like so. We have to make sure to increment the index, otherwise the next bullet would be stored in the list with the same index giving us the same problem we had with the previous script.
Next thing we have to do is run the script for every bullet with a loop. We plug the Counter output of the loop into the Index input of our lists, so that we could access each index and the values one by one. The script runs for every bullet and our problem is solved!
Here is a simpler example that demonstrates how to create multiple objects and process them all at once:
By storing every object in a list to their respective indices, you can loop from 0 to the list's length amount of times, using the current index to get the current object from the list to be processed.