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 ({}):

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

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.

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

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]):

-- Construct an array with three items
local testArray = {"A string", 3.14159, workspace.Camera}

print(testArray[1]) -- A string
print(testArray[2]) -- 3.14159
print(testArray[3]) -- Camera

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:

local testArray = {"A string", 3.14159, workspace.Camera}

testArray[2] = 12345
testArray[4] = "New string"

print(testArray[2]) --12345
print(testArray[4]) -- New string

Iterating over Arrays

To iterate over an array, you can use 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).

local testArray = {"A string", 3.14159, workspace.Camera, "New string"}

-- Loop using general iteration
for index, value in testArray do
	print(index, value)
end

-- Iterate using the array length operator (#)
for index = 1, #testArray do
	print(index, testArray[index])
end

--[[ Resulting output:
1 A string
2 3.14159
3 Camera
4 New string
1 A string
2 3.14159
3 Camera
4 New string
]]

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.

local testArray = {"A string", 3.14159}

table.insert(testArray, "New string")
testArray[#testArray+1] = "Another new string"

print(testArray[3]) -- New string
print(testArray[4]) -- Another new string

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.

local testArray = {"First item", "Next item"}

table.insert(testArray, 2, "NEW ITEM #2")

print(testArray[1]) -- First item
print(testArray[2]) -- NEW ITEM #2
print(testArray[3]) -- Next item

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.

local testArray = {"First item", "Next item", "Last item"}

table.remove(testArray, 2)

print(testArray[1]) -- First item
print(testArray[2]) -- Last item

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:

local testDictionary = {
	FruitName = "Lemon",
	FruitColor = "Yellow",
	Sour = true
}

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]):

local part = Instance.new("Part")

local testDictionary = {
	PartType = "Block",
	[part] = true
}

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]).

local part = Instance.new("Part")

local testDictionary = {
	PartType = "Block",
	[part] = true
}
-- Include quotes for string keys
print(testDictionary["PartType"]) -- Block
-- Omit quotes for non-string keys
print(testDictionary[part]) -- true

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:

local testDictionary = {
	FruitName = "Lemon",
	Sour = true
}

-- Change value of existing keys
testDictionary["FruitName"] = "Cherry"
testDictionary["Sour"] = false

-- Insert new key-value pair
testDictionary["FruitCount"] = 10

print(testDictionary["FruitName"]) -- Cherry
print(testDictionary["Sour"]) -- false
print(testDictionary["FruitCount"]) -- 10

Iterating over Dictionaries

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

local testDictionary = {
	FruitName = "Lemon",
	FruitColor = "Yellow",
	Sour = true
}

for key, value in pairs(testDictionary) do
	print(key, value)
end

--[[ Resulting output:
FruitName Lemon
Sour true
FruitColor Yellow
]]

Removing Key-value Pairs

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

local testDictionary = {
	FruitName = "Lemon",
	FruitColor = "Yellow",
	Sour = true
}

testDictionary["Sour"] = nil

for key, value in pairs(testDictionary) do
	print(key, value)
end
--[[ Resulting output:
FruitName Lemon
FruitColor Yellow
]]

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:

local originalArray = {10, 20}

local arrayReference = originalArray

print("Original:", originalArray[1], originalArray[2])
print("Reference:", arrayReference[1], arrayReference[2])

-- Change values in original array
originalArray[1] = 1000
originalArray[2] = 2000

print("Reference:", arrayReference[1], arrayReference[2])

--[[ Resulting output:
Original: 10 20
Reference: 10 20
Reference: 1000 2000
]]

Cloning Tables

Shallow Clones

To copy a table without any nested tables, Luau offers the table.clone() method.

local original = {
	key = "value",
	engine = "Roblox",
	playerID = 505306092
}

local clone = table.clone(original)

Deep Clones

To copy a more complex table with nested tables inside it, you'll need to use a recursive function similar to the following:

-- The function used for deep copying a table
local function deepCopy(original)	
	-- Define the new table for the copy
	local copy = {}
	
	-- Loop through the original table to clone
	for key, value in original do
		-- If the type of the value is a table, deep copy it to the key (index)
		-- Else (or) the type isn't a table, assign the default value to the index instead
		copy[key] = type(value) == "table" and deepCopy(value) or value
	end
	
	-- Return the finalized copy of the deep cloned table
	return copy
end

With the function in place, you can make a deep copy as follows:

local original = {
	key = "value",
	playerInfo = {
		playerID = 505306092,
		playerName = "PlayerName"
	},
	otherInfo = {
		{
			{1, 3, 5, 7, 9}
		}
	}
}

local clone = deepCopy(original)

Freezing Tables

Freezing a table makes it read-only. This means that its keys can't be written to, but can be read. New keys can't be created after a table is frozen. You can check if a table is frozen by using the table.isfrozen() method. This feature is used to create constant values which you don't want to change.

Shallow Freezes

To freeze a table without any nested tables, Luau offers the table.freeze() method.

local target = {
	key = "value",
	engine = "Roblox",
	playerID = 505306092
}

table.freeze(target)
target.playerID = 1 --> attempt to modify a readonly table

Deep Freezes

To freeze a more complex table with nested tables inside it, you'll need to use a recursive function similar to the following:

local function deepFreeze(target)
	-- Shallow freeze the table
	table.freeze(target)

	-- Check each key of the table and freeze it if it's a table
	for _, v in target do
		if type(v) == "table" then
			deepFreeze(v)
		end
	end
end

With the function in place, you can deep freeze a table as follows:

local target = {
	key = "value",
	playerInfo = {
		playerID = 505306092,
		playerName = "PlayerName"
	},
	otherInfo = {
		{
			{1, 3, 5, 7, 9}
		}
	}
}

deepFreeze(target)
target.playerInfo.playerID = 1 --> attempt to modify a readonly table