Tables, Part 1

Written: 2026-10-14

Learning objectives

• You build arrays and read them with 1-based positions.
• You build dictionaries with named keys.
• You nest tables inside tables.
• You measure arrays with # and grow or shrink them with table.insert and table.remove.
• You visit every entry with for k, v in t, change values, and delete keys with nil.

Prerequisites

• Read First Script. You can run a Script and read output.
• Read Variables and Values. You create variables with local.
• Read Operators and Logic. You use # and comparisons.
• Read Conditionals and Loops. You count with numeric for.
• Read Functions and Scope. You call functions with arguments.

Arrays keep an ordered list

A table is a container that holds many values at once. An array is a table used as an ordered list: first item, second item, third item. You build one with curly braces and commas.

Luau counts from one. The first item lives at position 1, not 0. This is called 1-based indexing, and it is the first thing programmers from other languages get wrong.

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local fruits = { "apple", "pear", "plum" }
print(fruits[1])
print(fruits[2])
print(fruits[3])

apple
pear
plum

Walkthrough:

1. Line 1 turns on strict mode.
2. Line 2 builds an array of three strings and stores it in fruits.
3. Line 3 prints position 1, the first item, "apple".
4. Line 4 prints position 2, "pear".
5. Line 5 prints position 3, "plum".

Square brackets with a position read one slot. You can also write through the same brackets to replace a slot or add a new one at the end.

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local fruits = { "apple", "pear", "plum" }
fruits[2] = "peach"
print(fruits[2])
print(#fruits)

peach
3

Walkthrough:

1. Line 1 turns on strict mode.
2. Line 2 builds the same three-item array.
3. Line 3 replaces position 2 with "peach". The old "pear" is gone.
4. Line 4 prints the new position 2, "peach".
5. Line 5 prints #fruits. The # operator counts array items, so this prints 3.

Dictionaries label each value

A dictionary is a table where each value has a named key instead of a position. You build one with key = value pairs inside the braces. You read values with a dot, as in player.name, or with brackets, as in player["name"].

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local player = { name = "Maya", level = 7, ready = true }
print(player.name)
print(player.level)
print(player.ready)

Maya
7
true

Walkthrough:

1. Line 1 turns on strict mode.
2. Line 2 builds a dictionary with three labeled values: name, level, and ready.
3. Line 3 prints the value behind the name key, "Maya".
4. Line 4 prints the value behind level, 7.
5. Line 5 prints the value behind ready, true.

Use arrays when order matters, like a lineup of winners. Use dictionaries when labels matter, like the stats of one player. One table can be both at once, but keep your tables one-shaped while you learn.

You add a new key by assigning to it and change a value by assigning to its key. Both use the same = you learned in Variables and Values.

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local player = { name = "Maya", level = 7 }
player.level = 8
player.team = "Falcons"
print(player.level)
print(player.team)

8
Falcons

Walkthrough:

1. Line 1 turns on strict mode.
2. Line 2 builds a dictionary with name and level.
3. Line 3 overwrites level with 8.
4. Line 4 creates a brand-new key, team, holding "Falcons".
5. Lines 5 and 6 print 8 and Falcons.

Tables nest inside tables

Values inside a table can be tables themselves. This is called nesting. A roster holds players, and each player holds stats. You reach inner values by chaining dots and brackets from the outside in.

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local team = {
	name = "Falcons",
	members = { "Maya", "Rio", "Sam" },
	captain = { name = "Maya", level = 8 },
}
print(team.name)
print(team.members[1])
print(team.captain.level)

Falcons
Maya
8

Walkthrough:

1. Line 1 turns on strict mode.
2. Lines 2 to 6 build team. Its name is a string, its members is an array, and its captain is a dictionary.
3. Line 7 prints team.name, the outer string "Falcons".
4. Line 8 dives into the inner array and prints position 1, "Maya".
5. Line 9 dives into the inner dictionary and prints its level, 8.

Read chains left to right. team.captain.level means: start at team, open captain, read level. When a chain prints nil, the break is usually one level up: some middle key is missing or misspelled.

Grow and shrink arrays

Two library functions resize arrays. table.insert adds an item. table.remove takes one away and pulls later items down to close the gap. Both shift positions, so print the array after each change while you learn.

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local fruits = { "apple", "pear" }
table.insert(fruits, "plum")
print(fruits[3])
print(#fruits)
table.remove(fruits, 1)
print(fruits[1])
print(#fruits)

plum
3
pear
2

Walkthrough:

1. Line 1 turns on strict mode.
2. Line 2 builds a two-item array.
3. Line 3 appends "plum" to the end.
4. Line 4 prints the new position 3, "plum".
5. Line 5 prints the new length, 3.
6. Line 6 removes position 1. "pear" slides from position 2 down to position 1, and "plum" slides to position 2.
7. Line 7 prints the new position 1, "pear".
8. Line 8 prints the new length, 2.

Give table.insert a position to wedge an item into the middle, as in table.insert(fruits, 2, "peach"). Everything from that position onward shifts up by one. With no position, table.remove pops the last item.

Visit every entry with a loop

A for k, v in t loop visits each entry once and hands you the key and the value. For arrays the key is the position. For dictionaries the key is the label. Dictionary order is not guaranteed, so never rely on it.

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local fruits = { "apple", "peach", "plum" }
for index, value in fruits do
	print(index)
	print(value)
end

1
apple
2
peach
3
plum

Walkthrough:

1. Line 1 turns on strict mode.
2. Line 2 builds a three-item array.
3. Line 3 starts the loop. Each round puts the position in index and the item in value.
4. Line 4 prints the position.
5. Line 5 prints the item.
6. Line 6 ends the loop body. Arrays visit in order, so the output runs 1 apple 2 peach 3 plum.

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local player = { name = "Maya", level = 8 }
for key, value in player do
	print(key)
	print(value)
end

name
Maya
level
8

Walkthrough:

1. Line 1 turns on strict mode.
2. Line 2 builds a two-key dictionary.
3. Line 3 starts the loop. Each round puts the label in key and the stored value in value.
4. Line 4 prints the key.
5. Line 5 prints the value.
6. Line 6 ends the loop body. Both entries print. Their order may vary, and that is normal for dictionaries.

You can change values mid-loop through the original table. Below, each round writes back through levels[index].

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local levels = { 1, 2, 3 }
for index, value in levels do
	levels[index] = value * 10
end
print(levels[1])
print(levels[2])
print(levels[3])

10
20
30

Walkthrough:

1. Line 1 turns on strict mode.
2. Line 2 builds { 1, 2, 3 }.
3. Line 3 loops with index and value.
4. Line 4 multiplies each value by 10 and writes it back into the same slot. This changes the table itself, not just the loop variable.
5. Line 5 ends the loop body.
6. Lines 6 to 8 print 10, 20, 30.

Delete dictionary keys with nil

Setting a dictionary key to nil erases the entry. The key disappears. Reading it afterward gives nil, which means "nothing here". Never store nil inside an array on purpose. It punches a hole that # and loops cannot count reliably.

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local player = { name = "Maya", title = "Rookie" }
print(player.title)
player.title = nil
print(player.title)

Rookie
nil

Walkthrough:

1. Line 1 turns on strict mode.
2. Line 2 builds a dictionary with name and title.
3. Line 3 prints "Rookie".
4. Line 4 assigns nil to title. This deletes the key entirely.
5. Line 5 prints nil because the key no longer exists.

Common mistakes

Reading position zero.

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local fruits = { "apple", "pear", "plum" }
print(fruits[0])

nil

This prints nil because arrays start at 1. Fix it by reading position 1 for the first item. Run the fix the same way.

--!strict
local fruits = { "apple", "pear", "plum" }
print(fruits[1])

apple

Trusting # on a table with holes.

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local scores = { 10, 20, 30 }
scores[2] = nil
print(#scores)

Unreliable: Luau may print 1 or 3 here because the hole in the middle breaks #.

The length is unreliable now because the middle is missing. Fix it by removing with table.remove, which closes the gap. Run the fix the same way.

--!strict
local scores = { 10, 20, 30 }
table.remove(scores, 2)
print(#scores)
print(scores[2])

2
30

Forgetting that table.remove shifts positions.

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local fruits = { "apple", "pear", "plum" }
table.remove(fruits, 1)
print(fruits[3])

nil

This prints nil because "plum" slid from position 3 to position 2. Fix it by reading the new positions after removal. Run the fix the same way.

--!strict
local fruits = { "apple", "pear", "plum" }
table.remove(fruits, 1)
print(fruits[1])
print(fruits[2])

pear
plum

Relying on dictionary order.

Run this: put it in a Script in ServerScriptService and press Play.

--!strict
local player = { name = "Maya", level = 8 }
for key, value in player do
	print(key)
	print(value)
end

name
Maya
level
8

You may see level first instead. Beginners expect name always first, but Luau makes no such promise for dictionaries. Treat dictionary order as random and never build logic on it. Your output above is correct as long as both entries print.

Exercises

Run every solution below in a Script in ServerScriptService and press Play. Try each exercise yourself before you open its solution.

1. Build an array of three game names. Print the first and the last with brackets.

Solution 1

--!strict
local games = { "Tag", "Obby", "Tycoon" }
print(games[1])
print(games[3])

Tag
Tycoon

2. Build a dictionary for a sword with keys name and damage. Print both values with dots.

Solution 2

--!strict
local sword = { name = "Ember", damage = 12 }
print(sword.name)
print(sword.damage)

Ember
12

3. Start from { "apple", "pear" }. Insert "plum" at the end and remove position 1. Print the two remaining items by position and the final length.

Solution 3

--!strict
local fruits = { "apple", "pear" }
table.insert(fruits, "plum")
table.remove(fruits, 1)
print(fruits[1])
print(fruits[2])
print(#fruits)

pear
plum
2

After removal, "pear" sits at position 1 and "plum" at position 2.

4. Build a nested team table with a name and a two-item members array. Print the team name, then loop over members with for k, v in t and print each member.

Solution 4

--!strict
local team = { name = "Falcons", members = { "Maya", "Rio" } }
print(team.name)
for index, member in team.members do
	print(index)
	print(member)
end

Falcons
1
Maya
2
Rio

Line 3 loops over the inner array team.members, not the outer table.

Summary

You built arrays with 1-based positions and dictionaries with named keys. You nested tables, measured arrays with #, resized them with table.insert and table.remove, visited entries with for k, v in t, changed values in place, and deleted dictionary keys by assigning nil.

Next: Strings, Numbers, and Nil.