As of late 2021, we are in the process of updating Stencylpedia and fixing up outdated & broken content. Thanks for your patience!








by Jon (Updated on 2015-10-18)


  • 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

As you'd expect, lists are best used to store collections of things. You can use lists for things like:

  • Inventory
  • Character stats
  • Status effects
  • Selecting random monsters to spawn

In general, lists can be a good option any time you want to keep track of lots of information.

Aside: 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!

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

List Structure

A list is an ordered collection of items. Each item in a 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.

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

index value
0 eggs
1 bacon
2 cheese
3 apples
4 oranges
5 salmon

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, and so forth.

  • 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, but it is common practice to do so. If you mix up data types, 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.


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

The Future: We don't yet support reversing, combining or sorting lists, though these are all supported in a 3rd party extension. We do, however, support Maps/Dictionaries.

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.


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

Disclaimer: This challenge is just an exercise for practicing what you've learned. Part of what we're doing with Stencylpedia is getting you to think about the underlying concepts. Please do not regard this as best practice - it's just an exercise.

Looking for a 2D list extension?

A veteran Stencyler has created a handy extension for 2D lists.

Print Article Edit Article How to Edit an Article
Disclaimer: 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!


kade 101
i use lists as a save file part in my game as it has 3 game save files witch are all different so you can restart and still see your other 2 saves in the load/save menu for more then one person to play.
have 3 lists named save file 1 -3 as a number after
then write a list on how your information will be stored like this
index number
0 = 100 = health = health i have at save
1 = 50 = amo for gun = amo i have at save
2 = 12 = a sene number teller =code some think that tells what that number = sene name

store the[ basic information ]like amo health and so on and then get it to load the list file in to a [separate list name loaded save] so you can use that one instead when in game not the proper save file then when you what to save then save the list loaded save and make the list replace over to the proper save file
this will help with with more then one save file for most games in this case i have done this my self and its dose work give it a try your self and see

1 7 years, 5 months ago
Mad Bomber
One handy tip I just came across: if you're getting a random item from your list using the "random number between" block, set the upper limit to "number of items in [list] minus 1". Otherwise, it will occasionally try to hit a slot outside your list and return "null".
1 7 years, 10 months ago
Do lists apply to when you're making multiple save slots in your game?
0 9 years, 4 months ago
Pixel8ed dev
if anyone is looking for 2d list , then take a look at these extensions php/topic,23821.0.html php/topic,28081.0.html

0 9 years, 12 months ago
Invin K
Data aspects are very hard to work with Stencyl. Phew.. It would be much better with Java or C
-1 10 years, 2 months ago
Invin K
murphymen /// ooOOOOooorrrrggghhh Very Good Idea LOL

I've been wasted too much time for this Very Stupid List within List.

Seems that Finally I got very simple solution.

damn.... phew...

-1 10 years, 2 months ago
Why using list of lists to make 2d array? You can easly use only one 1d list, like video memory is organised.
When you want eg. 3x3 array then you can create 9 element list(say array). When want access X,Y index:
array[index] = (Y * num_of_rows) X;

1 2 3
2d list 4 5 6 in 1d list array{1,2,3,4,5,6,7,8,9}
7 8 9

Sorry for language :)

1 10 years, 2 months ago
You can no longer create a list with in a list in Stencyl 3?
0 10 years, 3 months ago
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 10 years, 5 months ago
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 10 years, 8 months ago

Sign In to Comment