Tables

The table data type can store multiple values of any type that isn't nil, including booleans, numbers, strings, functions, and other tables. Construct tables with curly braces ({}):


1-- Construct an empty table assigned to variable "t"
2local t = {}
3print(t) -- {}
4

You can use a table as an array or dictionary. Arrays use an ordered list of numbers as indices, but dictionaries can have numbers, strings, and objects as indices.

For more information on built-in functions for working with tables, see the table library.

Arrays

An array is an ordered list of values. Arrays are useful for storing collections of data, such as a group of players with special permissions.

Creating Arrays

To create an array using a Luau table, declare the values in sequential order, separated by commas.


1-- Construct an array with three items
2local testArray = {"A string", 3.14159, workspace.Camera}
3print(testArray)
4

Reading from Arrays

To read from an array, add a pair of square brackets after its reference and specify the index number of the element inside ([pos]):


1-- Construct an array with three items
2local testArray = {"A string", 3.14159, workspace.Camera}
3
4print(testArray[1]) -- A string
5print(testArray[2]) -- 3.14159
6print(testArray[3]) -- Camera
7

Writing to Arrays

To define or rewrite the value of an array at an index, declare the index number in square brackets ([index]) followed by = and the value:


1local testArray = {"A string", 3.14159, workspace.Camera}
2
3testArray[2] = 12345
4testArray[4] = "New string"
5
6print(testArray[2]) --12345
7print(testArray[4]) -- New string
8

Iterating over Arrays

To iterate over an array, use the global ipairs() function in a for loop. Because the arrays have numerical indices, you can also use a numeric for loop from 1 to the length of the array (#array).


1local testArray = {"A string", 3.14159, workspace.Camera, "New string"}
2
3-- Loop using "ipairs()"
4for index, value in ipairs(testArray) do
5 print(index, value)
6end
7
8-- Iterate using the array length operator (#)
9for index = 1, #testArray do
10 print(index, testArray[index])
11end
12
13--[[ Resulting output:
141 A string
152 3.14159
163 Camera
174 New string
181 A string
192 3.14159
203 Camera
214 New string
22]]
23

Inserting Items

There are two built-in ways to insert an item to the end of an array:

  • Pass a reference to the array and the item value to Luau's table.insert() function.
  • Add the new item to the array using the array[#array+1] syntax.

1local testArray = {"A string", 3.14159}
2
3table.insert(testArray, "New string")
4testArray[#testArray+1] = "Another new string"
5
6print(testArray[3]) -- New string
7print(testArray[4]) -- Another new string
8

To insert an item between the start and end of an array, include a position value as the second argument of table.insert(). This inserts the new item and pushes the following items up one index position.


1local testArray = {"First item", "Next item"}
2
3table.insert(testArray, 2, "NEW ITEM #2")
4
5print(testArray[1]) -- First item
6print(testArray[2]) -- NEW ITEM #2
7print(testArray[3]) -- Next item
8

Removing Items

To remove an item from an array, use table.remove(). This removes the item at the specified position and moves any following items back one index position.


1local testArray = {"First item", "Next item", "Last item"}
2
3table.remove(testArray, 2)
4
5print(testArray[1]) -- First item
6print(testArray[2]) -- Last item
7

Dictionaries

Dictionaries are an extension of arrays. Dictionaries store a set of key-value pairs, where the keys can be any number, string, or object.

Creating Dictionaries

To create a dictionary table, define each key followed by = and the value. Separate each key-value pair with a comma:


1local testDictionary = {
2 FruitName = "Lemon",
3 FruitColor = "Yellow",
4 Sour = true
5}
6

The keys for dictionaries can be numbers, strings, and objects. For example, a key may also be an Instance. To use objects as keys, declare the key in square brackets ([key]):


1local part = Instance.new("Part")
2
3local testDictionary = {
4 PartType = "Block",
5 [part] = true
6}
7

Reading from Dictionaries

To read from a dictionary, add a pair of brackets after its reference and specify the key name. Directly reference a string key using quotes (["key"]) or use a variable value ([key]).


1local part = Instance.new("Part")
2
3local testDictionary = {
4 PartType = "Block",
5 [part] = true
6}
7-- Include quotes for string keys
8print(testDictionary["PartType"]) -- Block
9-- Omit quotes for non-string keys
10print(testDictionary[part]) -- true
11

Writing to Dictionaries

To define or rewrite the value of a new or existing dictionary key, declare the key name in brackets ([key]) followed by = and the value:


1local testDictionary = {
2 FruitName = "Lemon",
3 Sour = true
4}
5
6-- Change value of existing keys
7testDictionary["FruitName"] = "Cherry"
8testDictionary["Sour"] = false
9
10-- Insert new key-value pair
11testDictionary["FruitCount"] = 10
12
13print(testDictionary["FruitName"]) -- Cherry
14print(testDictionary["Sour"]) -- false
15print(testDictionary["FruitCount"]) -- 10
16

Iterating over Dictionaries

To iterate over a dictionary, use the global pairs() function in a for loop:


1local testDictionary = {
2 FruitName = "Lemon",
3 FruitColor = "Yellow",
4 Sour = true
5}
6
7for key, value in pairs(testDictionary) do
8 print(key, value)
9end
10
11--[[ Resulting output:
12FruitName Lemon
13Sour true
14FruitColor Yellow
15]]
16

Removing Key-value Pairs

To remove or erase a key-value pair from a dictionary, set its value for a key to nil.


1local testDictionary = {
2 FruitName = "Lemon",
3 FruitColor = "Yellow",
4 Sour = true
5}
6
7testDictionary["Sour"] = nil
8
9for key, value in pairs(testDictionary) do
10 print(key, value)
11end
12--[[ Resulting output:
13FruitName Lemon
14FruitColor Yellow
15]]
16

Tables as References

If you store a table in a new variable, Luau doesn't create a copy of that table. Instead, the variable becomes a reference, or pointer, to the original table. Any reference to a table reflects any changes to the original table:


1local originalArray = {10, 20}
2
3local arrayReference = originalArray
4
5print("Original:", originalArray[1], originalArray[2])
6print("Reference:", arrayReference[1], arrayReference[2])
7
8-- Change values in original array
9originalArray[1] = 1000
10originalArray[2] = 2000
11
12print("Reference:", arrayReference[1], arrayReference[2])
13
14--[[ Resulting output:
15Original: 10 20
16Reference: 10 20
17Reference: 1000 2000
18]]
19