We use cookies on this site to enhance your user experience

Intro to Dictionaries


Hero with lua dictionary including health and money properties

Intro to Dictionaries

Dictionaries are tables that use a key to identify values instead of numbered indexes. Each key has a custom label, like “playerName” or “itemName”. Values store data related to that key. Keys and values can be any data type – including strings, numbers, and variable names.

Use dictionaries when you need to label values, not just list them in order as an array does. For example, when storing how many points each player has by name.

Dictionaries - can use names or other identifiers

Key "Alex!" "Bobby" "Cait"
Value 1500 600 3000

Arrays - Only use numbered indexes

Value 1 2 3
Index 1500 600 3000

Coding a Dictionary

Like arrays, dictionaries are created using curly brackets {}. Key value pairs are stored between brackets on seperate lines separated by commas. Below is a dictionary using strings as keys and numbers as values.

Create a Character

A common use for dictionaries is organizing information for a character or playable class. Keys are used to label properties like character name or health points. This examples uses a dictionary to do exactly that.

  1. Create a new Script.
  2. Type local hero = { and then press Enter to autocomplete the dictionary.
  1. Inside square brackets [], use a string data-type as a key.
  1. Set the key’s value and end the line with a comma.
  1. Add a second key value pair for health.
Don't mix dictionaries and arrays

Using Dictionary Values

To use individual dictionary values in code, type the name of the dictionary followed by the key in brackets. Example: dictionaryName[key]

  • Print the hero’s name and then playtest the code.
Use Unique Key Names

Lua won’t stop you from trying to reuse the same key. If this code is run, the second value for the key [“name”] will be printed.

Adding and Removing from Dictionaries

You’ll often need to add key-value pairs to an existing dictionary. For instance, adding players to a dictionary when they join the game, and then starting them off with 0 points.

To add a key and value pair to a dictionary:

  1. Type the name of the dictionary, followed by the name of the key in brackets.
      Example: `playerPoints["name"]`
  2. On the same line, set the value.
      Example : `playerPoints["name"] = 0`

To remove a key from a dictionary , set the value to nil. This deletes the key.

    Example: `playerPoints["name"] = nil`

Variables as Dictionary Keys

Keys can also use variables. This example uses a variable to add a player’s name as a key when they join the game and then sets their points value to 0.

  1. In ServerScriptService, create a new script named PlayerPoints.
  2. Get the Players service and create an empty dictionary.
  1. Create a custom function with a parameter for a new player. Connect that function to the Players.PlayerAdded event.
  1. In the function, add a variable to get the player’s name and a print statement for testing.
  1. For the key, use the variable getting the players name and set the value to 0.

Here are other things you can try to do with dictionaries:

  • 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 word dictionary with definitions for a made-up language or your favorite slang