List Nodes
Creating a List
List Nodes are available in expert complexity mode.
Right-click on storyboarder under type and select list.
Right-click on empty parameter slot and select type of objects to be listed here we will create a list of models so under type->Scene->Model.
Click bottom handle and choose create value. You can add more list slots by pressing the plus in the bottom left corner. You can drag and drop models into these slots or use the context menu to select constants.
Adding an item to an existing list
There are two methods for adding an item to your existing list:
Add
The Add node is useful when you just want to add your item to the end of the list. With a list variable created you can just dereference the Add node and insert the item you want to add.
Insert
The insert node is useful when you want to add your item to a specific position in your list. After dereferencing the Insert node from your list variable, it takes two arguments:
- Index (int) : The position you want to add your item at.
- Item: The constant or variable you want to add to the list.
Adding/Inserting Multiple items at once
The above nodes are good for adding a single item to your list, but sometimes you may want to add a bunch of items at once. You can do this by using the AddRange and InsertRange Nodes.
Add Range
AddRange will allow you to add another list of items to the end of the dereferenced list.
- Collection: The list of items you want to add to your dereferenced list
Insert Range
InsertRange will allow you to insert a list of items into the dereferenced list.
- Index (int) : The starting position you want to add the first item of the list to. The rest of the existing list will follow the end of the inserted list.
- Collection: The list of items you want to insert into your dereferenced list.
Removing an item from a list
There are several methods to remove an item from a list.
Note: Once you remove an item from the list all the items that were in the list after it will have their index shifted down one.
Remove
- Item: The value/object you want to remove from the list. For example, if I want to remove the number 3 from my list I would insert the constant(int) 3 as my argument for item. The list would then no longer contain the number 3.
RemoveAt
The RemoveAt node will allow you to remove an item at a specified index value.
- Index (int): The position of the item you want to remove from the list.
RemoveRange
RemoveRange Allows you to remove a sublist of items from the dereferenced list.
- Index: The position of the first item you want to remove
- Count: Number of elements to be removed.
Changing an item in a list
Index
In order to access a certain position in your list you must dereference the Index node from your list variable.
- Index (int): The position in the list you want to make changes to.
To change the value stored at this position dereference a ChangeTo node and insert the new value as the argument.
Node
Retrieving a list item or index
GetItem
The GetItem node allows you to retrieve the value stored at a given position in the list.
- Index(int): The position in the list you want to retrieve the value for.
IndexOf
The IndexOf node allows you to retrieve the position a given item is stored at. It will return -1 if that item is not found in the list.
- Item: The value you are searching for in the list.
BinarySearch
The BinarySearch node is a more efficient way to search a list for the index of a given value. It does not need to search the entire list contents like indexOf does. It is recommended to use BinarySearch when you are searching very large lists.
- Item: The value you are searching for in the list.
Contains
If you just want to know if a value exists in a list you can use the contains method. It will return true if the value is in the list and false if it is not.
- Item: The value you want to check is in the list.
Iterating a through a List
LoopEach: will perform an action on each object in the list one at a time.
From bottom handle of list object click LoopEach.
From upper right handle (action argument) drag out a connector and select the begin node, this will act as a lambda function.
Add a begin parameter by clicking the plus button in the bottom left of the node and right-clicking on the empty parameter space, select variable -> new.
You can rename the variable to something more descriptive by clicking on the newly created variable and changing the name in the properties panel.
Compile the lesson.
Drag from the right handle of the begin node and search your variable name.
Click on bottom handle and select the action to perform on list objects. This example uses animate.
Node
ForkEach: will perform an action on all objects in the list at the same time.
It can be used in almost the same manner as the LoopEach node demonstrated in the above example except we need to add a wait node so that the rest of the lesson does not run until the ForkEach actions are complete.
Node
Click to download the sample asset used in demonstration.
Other List Functions
Count: Gets length of list.
The Count Node can be used to retrieve the number of values in the list. Just dereference it from the list variable.
Clear: Clears list content.
The Clear Node can be used to delete all values in the list. Just dereference it from the list variable.
PickRandom: Picks a random object from the list to perform an action on.
This Example will animate a random model from the list.
Left-click on bottom handle of list object and select PickRandom.
Left-click on bottom handle of pickRandom node and select action you want to perform on the randomly selected object.
Node
### Shuffle: Shuffles the order of the objects.
You must create a list variable in order for the shuffle function to be effective.
Create a list like normal (see beginning of article) and dereference a SaveTo node. Right-click in the empty parameter and select Variables > New. Click on the Unnamed variable and give it a name in the properties panel.
The values defined in the list object are now saved to the list variable and you can perform any list function directly from this variable in place of the list object.
Open the context menu and search your list variable.
Click the bottom handle and select shuffle.
Shuffle will mix the order of the values and therefore animating the list through the OneAtATime node after the shuffle can animate the objects in a different order than calling it before the shuffle. Shuffle mixes the objects randomly, so there is a slight chance the order will come out the same.
Node
Remove Random: Removes a random object from the list of objects.
The usage is identical to the shuffle node demonstrated above.
Sort: Sort the list alphabetically or numerically least to greatest depending on the list type.
The usage is identical to the shuffle node. Cannot be used on the SceneModel type.
Reverse: Reverses the order of of the list.
The usage is identical to the shuffle node.
Next Message Box