Intro to Dictionaries | Documentation

Dictionaries are tables that associate names or keys with a value instead of an index.

Example:

Lua dictionary syntax
local pet = {
   Name = "Bobbie",
   Type = "Dog",
}

Use dictionaries when you need to label values, not just list them in order as an array does. Practice using dictionaries in this tutorial by manipulating values associated with a player.

Dictionary Syntax

Like arrays, dictionaries are assigned to a variable with curly brackets {}. Key-value pairs are stored on separate lines followed by a comma. Keys and values can be any data type, including strings, numbers, and variable names.


local playerNames = {
	player1 = "Zap",
	player2 = "Kel",
}
print(playerNames["player1"])

To reference parts or other instanced objects as keys, use brackets.


local greenPart = workspace.GreenPart
local redPart = workspace.RedPart

local partList = {
	[greenPart] = true,
	[redPart] = false,
}
print(partList[redPart])

Use consistent data types for dictionary keys. Mixing data types, such as using both strings and variables for keys, can lead to inconsistent results when manipulating the array and confuse other coders.

Creating a Dictionary

One everyday use of dictionaries is organizing player or character information. These steps explore how a theoretical enemy character's information can be stored and accessed.

In a new script, create a dictionary named enemy.
```
local enemy = {

}
```
The first key in the dictionary will track the enemy's name with a variable called Name.
```
local enemy = {
	Name
}
```

Assign an enemy name to the key, followed by a comma.


local enemy = {
	Name = "Spike",
}

Add a second key-value pair for how much health the enemy should have. Remember, keys should always use the same data type, but values don't have to.


local enemy = {
	Name = "Spike",
	Health = 1000,
}

Using Dictionary Values

There are two ways to access dictionary values:

tableName["keyName"] (importantly, note the quotations)
tableName.keyName


local enemy = {
	Name = "Spike",
	Health = 1000,
}

print("The villain " .. enemy["Name"] .. " approaches!")
print("The villain " .. enemy.Name .. " approaches!")

Which style to use usually depends on the purpose of the table. For tables holding a collection of values like a list of players in a server, coders will usually use tableName["keyName"]. For a dictionary used to describe an object, coders are more likely to use tableName.keyName.

Changing a Dictionary Value

Changing a key's value is the same as any other variable; use the equal = operator.

Beneath the enemy table, set the enemy's name to something else.


local enemy = {
	Name = "Spike",
	Health = 1000,
}

enemy.Name = "Rana"

print("The enemy's name is " .. enemy.Name)

Playtest and check the Output window.

Pre-existing Variables as Keys

Dictionaries can interact with pre-existing variables declared in other parts of a script. The following coding example uses a variable to add a player's name as a key when they join the experience and then sets their points value to 0.

In ServerScriptService, create a new script named PlayerPoints. In the script, get the Players Service and create an empty dictionary named playerPoints.


local Players = game:GetService("Players")

local playerPoints = {

}

Code a local function for setting player points with a parameter for a new player variable. Connect the function to the Players.PlayerAdded event.


local playerPoints = {

}

local function setPoints(newPlayer)

end

Players.PlayerAdded:Connect(setPoints)

In the function, add a variable to get the player's Name, a property in every Player object, and a print statement for testing.


local function setPoints(newPlayer)
	local name = newPlayer.Name
	print("hello " .. name)
end

Insert name into the playerPoints dictionary as a key, and set the value, the player's points, to 0.


local function setPoints(newPlayer)
	local name = newPlayer.Name
	print("hello " .. name)
	playerPoints[name] = 0
end

Since name was created as a variable, it can be accessed with the actual variable name. If name were a key name, it would need to be accessed the same as other strings: playerPoints["name"].

Use name to print the name of the player and playerPoints[name] to print the value of the key matching the variable.


local function setPoints(newPlayer)
	local name = newPlayer.Name
	print("hello " .. name)
	playerPoints[name] = 0
	print(name .. " has " .. playerPoints[name] .. " points.")
end

Run the project and observe the output.

Finished script
local Players = game:GetService("Players")

local playerPoints = {

}

local function setPoints(newPlayer)
   local name = newPlayer.Name
   print("hello " .. name)
   playerPoints[name] = 0
   print(name .. " has " .. playerPoints[name] .. " points.")
end

Players.PlayerAdded:Connect(setPoints)

Optional Challenges

Below are some challenges that apply to using dictionaries in different ways. See if you can build out the code for these.

Create a trap part that does damage over time to a player. Once a player touches the trap, damage them, wait, then allow them to be damaged again.
Create a function that checks which of two players has the most points by accessing a dictionary.
Create a cipher, a system of swapping one string for another to create a "secret" code. For example, the letter "A" can be swapped with "G," or the word "apple" can be swapped with "orange."

Dictionaries and pairs()

pairs() is a function that's often used to iterate through dictionaries. An example is seen below.


local myDictionary = {
	["Blue Player"] = "Ana",
	["Gold Player"] = "Binh",
	["Red Player"] = "Cate",
}

for key, value in pairs(myDictionary) do
	print(key .. " is " .. value)
end

pairs() can be used to work with a dictionary element's key, value, or both. In the for loop below, the first variable is the key. The second variable is the value. The dictionary that you want to work with is passed in to pairs().


local inventory = {
	["Gold Bricks"] = 43,
	Carrots = 3,
	Torches = 2,
}

print("You have:")

for itemName, itemValue in pairs(inventory) do
	print(itemValue, itemName)
end

When executed, the code will print the following:


You have:
43 Gold Bricks
3 Carrots
2 Torches

Summary

Dictionaries are tables that use key-value pairs instead of indexed values. Dictionaries and arrays start similarly by assigning curly brackets to a variable. Keep entries separated with commas.

All keys within a dictionary should use the same data type, but the values can mix data types without issue.

The way in which a dictionary is accessed can convey its purpose. A dictionary of enemy properties will likely be accessed with the dot operator, while a list of names will likely use tableName[keyName].

When using brackets, be careful; key names created within the table must be treated as strings: tableName["keyName"]. However, when referencing objects like parts, the quotations are not needed: tableName[keyName].

Many scripts need to go through dictionaries or arrays, but you may not always know the start and end of these data structures. For example, a dictionary of players may be changing, or players may have an array inventory of varying sizes.

In these situations, you can use pairs() and ipairs() in a for loop to go through each element without known start and end points. You can also use general iteration through the in keyword to loop through elements without the need for pairs() or ipairs().