Tables: Lua's one flexible container

Watch

What a table is

A table is a container that holds many values under one variable name. Up to now each variable you made held a single thing: one number, one string, one true-or-false. A table is different. You make one variable, and inside it you can store as many values as you like.

Think of a variable like a single labelled box on a shelf. A table is a box that has many smaller compartments inside it. You still grab the one box by its name, then reach into whichever compartment you want.

You write a table with curly braces. Everything you put between the { and the } lives inside that one table:

local fruits = { "apple", "banana", "cherry" }

That single line creates one table and stores it in a variable called fruits. The table holds three values.

Tables as lists (arrays)

When a table holds a plain ordered list, we call it an array. Each value sits at a numbered position, and you reach a value by writing the table name followed by its position in square brackets.

Here is the single most important fact in this entire lesson, and the one that catches more beginners than anything else:

Look at how you read a value back out:

local fruits = { "apple", "banana" }
 
print(fruits[1])    -- prints apple, the first item
print(fruits[2])    -- prints banana, the second item

The square brackets are how you say "reach into this table and give me the value at this position." fruits[1] means "the value at position 1 of fruits."

See it run

Press RUN to execute this on real Lua 5.4 right in your browser. No FiveM and no server needed, just plain Lua.

Press RUN to execute.

The first line printed apple because that is the value at index 1, the front of the list.

The second line printed 3. That came from #fruits. The # symbol in front of a table gives you its length, meaning how many values are in the list. Our table holds three fruits, so #fruits is 3. You will use this constantly to ask "how many items are in here," for example to check whether a list is empty before you loop over it.

Try changing a value, adding a fourth fruit, or printing fruits[2] and run it again. Watching the output change is how the rule sinks in.

Tables as labelled data (dictionaries)

A table does not have to be a numbered list. It can also store values under word labels instead of numbers. When you do that, people often call it a dictionary, because like a real dictionary you look something up by its name rather than by its position.

Here the keys are words, not numbers:

local player = {
    name = "Quasar",
    level = 5,
}

This one table holds two pieces of data about a player: a name and a level. Now you reach a value by its label, and there are two ways to write it that do exactly the same thing:

print(player.name)        -- prints Quasar, dot notation
print(player["name"])     -- prints Quasar, bracket notation, same result

The dot form, player.name, is the one you will see most often because it is shorter and cleaner. The bracket form, player["name"], is handy when the key is stored in another variable, but for everyday code reach for the dot.

This is exactly why we said almost everything in FiveM is a table. A player in a real script is just a bigger version of this: one table holding a name, a level, an amount of cash, a job, and so on, each under its own label.

Press RUN to execute.

Looping over a table

Reading one value at a time is fine when you know exactly what you want. But often you have a whole table and you want to do something with every value in it. That is a loop: code that runs once for each item in the table. Lua gives you two loop helpers, and which one you use depends on whether your table is a list or labelled data.

ipairs for arrays in order

For an array, use ipairs. It walks the table in order, from index 1 upward, and on each pass it hands you two things: the index and the value at that index.

local fruits = { "apple", "banana", "cherry" }
 
for i, fruit in ipairs(fruits) do
    print(i, fruit)
end

Read the first line as "for each index i and value fruit in fruits, do the following." The word do opens the body of the loop, and end closes it, the same end you met with functions. The body runs once per item.

Press RUN to execute.

Notice the loop counted from 1, in order, just like the array itself. That is what ipairs is for: ordered lists.

pairs for key/value data

For labelled data, use pairs. It walks every key in the table and hands you the key and its value. The one catch is that pairs does not promise any particular order, because labelled data has no natural front-to-back the way a list does.

local player = { name = "Quasar", level = 5 }
 
for key, value in pairs(player) do
    print(key, value)
end

This prints both pairs, name with Quasar and level with 5, but do not count on which one comes first. When order matters, you have a list, so reach for an array and ipairs. When you just need to visit every labelled field, pairs is your tool.

Common beginner mistakes

Try it yourself

What you can do now

You can read and write the core of Lua, and you understand the world it runs in. That is the part most beginners never get past, and it is behind you now.

• You understand what FiveM is and how a server is put together from resources.
• You know the split between the client (each player's game) and the server (the shared brain everyone connects to).
• You can read and write basic Lua: variables, strings, numbers, true-or-false values, conditions, and functions you can reuse.
• You can build and read tables, both as ordered lists and as labelled data, and loop over them with ipairs and pairs.
• You know the trap that catches everyone: Lua arrays start at 1.

You did not just watch tutorials. You learned the ideas underneath them. That is the whole difference between someone who copies code and someone who builds.

So far everything has run inside your browser. Next you leave the sandbox: you install FiveM, set up a real editor, and learn where your code lives, so the Lua you just learned can run on an actual server.

REFERENCES

Lua 5.4 reference manual ↗FiveM docs ↗