tables

add( table , value )

This function inserts the given value to a table under the next available numbered key.

Example

We can create a table that is a list of color strings first and add values immediately like this:

colors = { "red", "blue", "pink", "yellow" }

Then if we want to add more values to the table, we can add another color to the list like this:

add( colors, "purple" )

del( table, value )

This function will remove an entry from a table that matches the value given. If you have more than one entry holding the same value, only the first entry that is found to match will be removed.

Example

We can create a table that is a list of color strings first and add values immediately like this:

colors = { "red", "blue", "pink", "yellow" }

Then if we want to remove a value from the table, we can do this:

del( colors, "blue" )

Notice that "blue" was the value stored at key #2. Deleting "blue", also updated the rest of the list's keys.

This happens for tables that have numbered keys, but it does not change tables that have named keys.

Return Value

This function will return the deleted value. If the function did not delete anything, then it will return nil.

table = { "a", "b", "c" }
returned = del(table,"a")

print(returned) --prints a

print(table[1]) --prints b

deli( table, index )

This function will remove an entry from a table that matches the index given. This only works for tables that have numbered keys, but it does not change tables that have named keys.

We can create a table that is a list of color strings first and insert values immediately like this:

colors = { "red", "blue", "pink", "yellow" }

These values are automatically indexed (given numbered keys) so we can use those indexes to remove an entry like this:

deli( colors, 2 )

Notice that "blue" was the value stored at index 2. Deleting "blue", also updated the rest of the list's keys so that there isn't a gap at index 2.

Return Value

This function will return the deleted item. If the function did not delete anything, then it will return nil.

table = { "a", "b", "c" }
returned = deli(table,1)

print(returned) --prints a

print(table[1]) --prints b

count( table )

This function will return the highest number key in a table. To accurately return the total count, the table must be numbered and without any gaps.

Example

We can create a table that is a list of color strings first and add values immediately like this:

colors = { "red", "blue", "pink", "yellow" }

Then if we want to count the number of entries in the table, we can do this:

count( colors ) --returns 4

Shorthand

#colors --returns 4

A table is a way to store and organize sets of data in a flexible and dynamic way. 

Think of a table as a collection of related information, like a list of groceries or a directory of phone numbers. You can imagine these tables like data tables: sets of information placed into rows and columns.

You can collect and organize your game information easily into tables. You can't view the tables in PICO-8, so you will have to imagine them, and we will display our examples here as data tables, such as:

Tables are a powerful tool for programmers, not just for organizing data for easy use, but also to make more efficient and dynamic code (More on that below). Tables and loops often go hand in hand, so having a good understanding of both is necessary to planning how to organize your data into tables well.

Terms Related to Tables

Key

The first column's data. A number or string used to find the data stored in Column 2.

Value

The second column's data. A number, string, boolean, table, or function that you want to store.

Index

When a table has numbered keys (like the shopping list above), these numbers are referred to as indexes.

Sorting

The process of arranging the entries of the table in a specific order. A numbered table in Lua and PICO-8 is automatically sorted in ascending order, starting at 1 (note that most programming languages start at 0, so if Lua is not your first language, this may take some getting used to).

Count / Length

The "count" or "length" of a table is the total number of entries in the table. See count function.

Lookup

A table lookup is the process of searching for and getting a specific value or element within a table. The lookup process involves specifying a key or index, which is used to identify the desired element in the table. See "How to get a value from a Table" (coming soon).

Iteration

To iterate means to cycle through something one at a time. We can iterate through the values of a table easily using Loops. This is useful when you want to check or do something for every entry in a table.

Advanced Table Terms

Nested Tables

It is possible to have tables inside of other tables. When multiple things are organized inside of each other, we call them "nested". You can think of these like folders on your computer; you can store files inside of folders and also have folders inside of folders ("nested folders"). You can have as many nested tables (tables inside of other tables) as you want.

Parent & Child

When you have nested tables, we refer to the outer table as the parent and the inner table as the child.

enemies = {}

enemies[1] = { 
	name="goblin", 
	health=5, 
	attack=3 
}
enemies[2] = {
	name="ogre",
	health=10,
	attack=6 
}

Tables are "Efficienct and Dynamic"

Efficiency refers to how well a program uses system resources (such as memory, processing power, and input/output operations). An efficient program is one that can achieve its goals with minimal resource usage, while avoiding unnecessary operations. 

Here is a comparison of code that is organized with and without tables.

--item variables
item_sprite = 1
item_x = 10
item_y = 20

--get value
print(item_sprite) --prints 1

--draw item
spr(item_sprite, item_x, item_y)

--17 tokens

--item table
item = { sprite=1, x=10, y=20 }

--get value
print(item.sprite) --prints 1

--draw item
spr(item.sprite, item.x, item.y)

--24 tokens

So far, these don't look too different. And if we compare the tokens, the one without tables looks more efficient. However, this example is only for a single item in the entire game. So imagine if we add just 2 more items.

Well without tables, we have to write 3 new unique variables for every item. But thanks to tables, those variables turn into keys, and you can use the same key in different tables without getting their values confused. This also makes looping through the tables much easier because you can lookup the same exact key name such as sprite and simply change the table that is being looked up to get the different sprite value for the different items. 

Here is how we could have 3 items:

--item variables
item1_sprite = 1
item1_x = 10
item1_y = 20
item2_sprite = 2
item2_x = 30
item2_y = 50
item3_sprite = 3
item3_x = 70
item3_y = 90

--get one value
print(item1_sprite) --prints 1

--draw each item
spr(item1_sprite,item1_x,item1_y)
spr(item2_sprite,item2_x,item2_y)
spr(item3_sprite,item3_x,item3_y)

--45 tokens

--items table of tables
items = {
	{ sprite=1, x=10, y=20 },
	{ sprite=2, x=30, y=50 },
	{ sprite=3, x=70, y=90 },
}

--get one value
print(items[1].sprite) --prints 1

--loop and draw each item
for item in all(items) do
	spr(item.sprite,item.x,item.y)
end

--50 tokens

Look how fast the tokens of the code without tables caught up to the code with tables; that's just 3 items. Your game is sure to have many more than that! Not just items but your game will probably have many enemies, bullets, particles and more. It would be crazy to write out enemy1_sprite, enemy1_x, enemy1_y for even just 10 enemies! And so, tables are efficient!

But what do we mean by tables being dynamic?

Dynamic refers to the way something can change or adapt while the program is running. Global variables are set one time, and they can be changed any time after that. But if we are talking about items that a player can pick up or enemies that can be killed, how do we handle those variables when the item or enemy should no longer be in the game at all?

Tables are dynamic because they can grow and shrink in size. We can add to and delete from a table at any time. This makes it easy to prepare a function for adding a new item or enemy to the game at certain parts of the game, and remove them from the game just as easily when they should no longer be there.

This dynamic organization of our game objects also makes it very easy for us to count how many of those objects there are by simply counting the table.

Empty Table

To create an empty table, use the opening and closing curly braces {}, like this:

mytable = {}

This is useful for preparing a variable to hold the table in your _init() function during set up. Then use add() to insert data into the table later.

List

To create a list type of table, you can write the values inside the curly braces, separated by commas, and let the table automatically number them.

mytable = { "superman", "spiderman", "ironman" }

You can also number them yourself, if you need to:

mytable = { [1]="spock", [2]="kirk", [3]="scotty" }

Or you can add numbered values to any table already created by using square brackets [] after the table name, mytable[key], like this:

mytable[1] = "picard"
mytable[2] = "laforge"
mytable[3] = "worf"

Object

To create an object type of table, you can name the keys and use any data type as the value; even other tables or functions.

mytable = { sprite=1, x=10, y=5, state="run" }

Another way to write this is vertically, so that it is more readable for more complex object tables:

mytable = {
	sprite = 1,
	x = 10,
	y = 5,
	state = "run"
}

When writing your table entries vertically like this, make sure you still separate each entry with a comma. Forgetting a comma is often the cause of the "unlcosed {" error.

Another way to write this type of table vertically that some people prefer is to create the empty object table first, then insert each entry separately by using square brackets [] after the table name, mytable[key], like this:

mytable = {}
mytable[sprite] = 1
mytable[x] = 10
mytable[y] = 5
mytable[state] = "run"

Notice that this way does not require commas and is less likely to cause confusing errors, however it costs more tokens and characters. So if you already know what should be inside the table, it is better to insert the entries at the same time as creating the table.

Collection of Objects

To create a collection type of table that holds multiple objects, you will want to use nested tables. (What is a Nested Table?)

mytable= { --open outer table 
	{} --inner table
} --close outer table

Nested tables can be hard to wrap your head around at first, but the more you work with them, the easier and more logical they will be to use. Here is what a single object table inside of a collection looks like, but they become more powerful and useful with more objects you store in the collection.

items= {
	{ name="sword", attack="5" }  --inner table 1
	{ name="sheild", armor="10" } --inner table 2
}

A collection of objects is a great way to create, store, and control multiple objects in your game such as bullets, items, enemies, and particles.

Collection of Bullets:

bullets={
	{ x=65, y=51 },
	{ x=22, y=25 },
	{ x=33, y=15 }
}

Collection of Items:

coins={
	{ sprite=1, x=10, y=5, name="copper" },
	{ sprite=2, x=20, y=25, name="silver" },
	{ sprite=3, x=30, y=15, name="gold" }
}

Collection of Enemies:

enemies={
	{ sprite=10, x=30, y=15, name="goomba" },
	{ sprite=11, x=40, y=35, name="koopa" },
	{ sprite=12, x=50, y=65, name="boo" }
}

These collections of objects can be easily updated and drawn in your game using loops.

Shorthand

You can use the shorthand . to refer to a table key instead of [], like this:

mytable = {}
mytable[sprite] = 1
mytable[x] = 10
mytable[y] = 5
mytable[state] = "run"

mytable = {}
mytable.sprite = 1
mytable.x = 10
mytable.y = 5
mytable.state = "run"

These two can also be used together to access inner table keys of nested tables, useful when you have a collection of objects (described above).

enemies[1].sprite

This will look at the enemies table, then find the first entry[1] inside of that, then it will look inside of that inner table and find the sprite key, and get the value stored there.