21,546

Views

Intermediate

Level

18

Comments

Lists

by Jon (Updated on 2014-01-26)


Contents

  • What are Lists?
  • What are Lists useful for?
  • List Structure
  • Gotchas
  • 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.

  • Eggs
  • Broccoli
  • Bacon
  • Salmon
  • 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.

For Programmers: Lists are mutable lists. They are equivalent ArrayLists, Vectors, NSMutableArray or whatever you like to call them.

 

What are Lists useful for?

Lists are best used to store, well, collections of things. You can use lists for things like:

  • Inventory
  • 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.

Note: Internally Stencyl uses lists to keep track of created actors, what points in a collision actually collided, and so on. If you've used any block that begins with "for each" you've actually used a list already!

 

List Structure

A list is an ordered collection of items. Each item in list is made up of two parts:

  1. A numerical index - in other words, where an item resides
  2. A value

 

Think of a list as a 2-column table.

  1. The first column is the index.
  2. The second column is the value.

 

 

List Gotchas

  • 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.

 

List Operations

All blocks related to lists are located under Attributes > Lists.

Operations

  • 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]

Getters

  • Get item at [INDEX] from [LIST]
  • [LIST] contains [ELEMENT]
  • Number of items in [LIST]
  • [LIST] is empty?

Creators

  • Create new list
  • Create (shallow) copy of [LIST]

 

The Future: We don't yet support reversing, combining or sorting lists. These operations may be available in the future though! We're also looking into adding Dictionaries (also known as Maps), which map arbitrary keys to values.

 

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.

  1. Configuring the attribute with initial data.
  2. 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.

Note: The second icon (the one under the +) lets you import a List from a text file. One line per entry. All entries will be treated as text.

 

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.

Note: You are also allowed to dump in Lists into Lists at runtime as well as any other kind of data. If you plan to save your lists out (via Game Attributes), there are restrictions. Skip down to "Saving & Lists"


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.

Note: Assigning values simply gets the Game Attribute to "point" to your List. No copying is done, so modifying it modifies the one and only "copy" of that 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.

 

Summary

  • 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.

Note: Lists within Lists are subject to some restrictions, if you decide that you want to save them out. Like normal Lists being saved out, they must only contain, Numbers, Text or other Lists that are subject to the same restrictions.

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.

Disclaimer: All articles are geared towards Stencyl 3.0 and above. Use comments to provide feedback and point out issues with the article (typo, wrong info, etc.). If you're seeking help for your game, please ask a question on the forums. Thanks!

18 Comments

betofantasioso
You can no longer create a list with in a list in Stencyl 3?
0 2 weeks, 4 days ago
Jon
I've added a link to a pre-built 2D list extension that Photon created. That said, the exercise is still a good thought process to run through.
0 2 months, 3 weeks ago
Shinobody
@Corerupted
Wouldn't it be easier to just store list within a list, like in last paragraph? Each item of master list could be a small list with five Number items in it, representing stat values of a weapon.

0 5 months, 2 weeks ago
Corerupted
Is it possible to maybe make a Guide to clearly explain how to do string handling? for example in my rpg game i got a weapon stats list which contains values seperated by "," (no spaces) and each line represents a weapon.
The format of the weapon list:
Weapon Name, Slot Number

The format of the stats list
Str, Dex, Int, Vit, Luck

(No spaces)

What would be the best way to retrieve all the stats effectively for my weapon?

0 6 months, 1 day ago
MikeyPB
List Gotcha!

I've been trying to figure out why my list didn't work on iOS. I was sending and retrieving actor names as text to a global list, using the blue tags on the collision events blocks.

This worked in flash, but the name of the actor in iOS is "Actor: actor type". I was trying to compare actors to the list using the first letter of the actor type and was confused why everything was coming back as "A"!

Hope this info helps someone with the same problem.

0 11 months, 3 weeks ago
HannesRoets
What would the result of the 2d list be? Could you add a table to clarify ?
0 1 year, 3 months ago
SherwoodSoftware
There needs to be an example about looping through a list. Especially with "for each" flow icon in Attributes->List
0 1 year, 6 months ago
Satori
Lists can contain Text or Numbers, but Lists on their own don't do very much. Their major value is that they work with other aspects of Stencyl. Information, then, on how to actually use the content of a List with the other parts of Stencyl would be valuable. A common use case would be a List called InventoryItems. How would you use Text or Numbers successfully to refer to other Actors? You'd want to destroy an Actor (an inventory item) upon adding it to the List (picking it up), and recreate an instance of it upon removal (dropping it). But there's nothing here that tells me how to do that with Numbers or Text.
1 1 year, 7 months ago
72master
so different question could somebody explain in more detail how to add things to your list on the fly because that would be really helpfull
0 1 year, 8 months ago
72master
does anybody know where i could find a tutorial on making random text out of a list . for example i have made a list and set it so that when the main charc collides with another actor the actor produces all the text from the list over and over and over again so anybody feel like helping me out ? :)
0 1 year, 9 months ago

Sign In to Comment