by Jon (Updated on 2014-01-26)
- What are Lists?
- What are Lists useful for?
- List Structure
- List Operations
- How to Create Lists
- Lists as Game Attributes
- Challenge: 2D Lists
What are Lists?
If you've ever written a grocery list, you're prepared to use lists in Stencyl.
- Corn Flakes
- Gallon of Water
Lists let you record pretty much anything in a predictable way. If you add apples to a list, and then add oranges, when you read the list apples will always come before oranges. However, lists are useful for more than just remembering what to pick up from the grocery store.
What are Lists useful for?
Lists are best used to store, well, collections of things. You can use lists for things like:
- Character stats
- Status effects
- Selecting random monsters to spawn
Lists can be a good option any time you want to keep track of lots of information.
A list is an ordered collection of items. Each item in list is made up of two parts:
- A numerical index - in other words, where an item resides
- A value
Think of a list as a 2-column table.
- The first column is the index.
- The second column is the value.
Indexes for lists start at 0, so the first item in a list starts at index 0, the second item is listed at index 1.
Don't work with indices beyond the maximum one (or below 0). Your game will crash if you do.
- Lists don't necesarily have to contain data all of the same type. However, it's your responsibility to keep track of this and process your data appropriately.
All blocks related to lists are located under Attributes > Lists.
- Add [ELEMENT] to [LIST]
- Insert [ELEMENT] at [INDEX] to [LIST]
- Replace item at [INDEX] with [ELEMENT] for [LIST]
- Remove [ELEMENT] from [LIST]
- Remove element at [INDEX] from [LIST]
- Remove all elements from [LIST]
- Get item at [INDEX] from [LIST]
- [LIST] contains [ELEMENT]
- Number of items in [LIST]
- [LIST] is empty?
- Create new list
- Create (shallow) copy of [LIST]
How to Create Lists
How do you create a List in the first place? Lists can be Attributes, so like any attribute, there are two ways of doing this.
- Configuring the attribute with initial data.
- Creating it at runtime inside a behavior and setting the attribute's value to that new list.
Assume that for both cases, we have created a List Attribute called "myList"
Method 1: Configuring a List Attribute
After attaching a behavior with a List attribute to either an Actor or a Scene, you'll see this neat interface for adding initial data to the list.
Method 2: Creating it on the Fly
Alternatively, you can create a new list on the fly and begin filling it up.
Lists as Game Attributes
Lists can be used as Game Attributes. This can be pretty useful for defining stat tables and other large collections of data to use throughout the game.
Creating a List as a Game Attribute
Lists can be created as Game Attributes and pre-populated the same way as other lists, namely only with Numbers and Text.
Setting the Value of a Game Attribute to a List
It should come as no surprise that you're able to set the value of a Game Attribute to a List.
Saving & Lists
As stated earlier, be careful when saving out lists as Game Attributes. They can only contain contain Numbers, Text and other Lists that follow the same rules.
- Lists store collections of data.
- Every item in a list has an index (number) that tells you where, in that list, that item resides.
- Indices start from 0.
- You can do lots of things to lists and change them after creation.
Challenge: Two-Dimensional Lists
Lists are great for storing sequential information, but if you need to store a "grid" of data? It turns out that lists are powerful enough that you store a List within a List, thereby bringing it up to 2 dimensions.
Come up with a scenario in which you need a 2D list and implement it.
Looking for a 2D list extension?
A veteran Stencyler has created a handy extension for 2D lists. We may fold this into Stencyl in the future.