Start Here · Lua from zero

Variables: boxes that hold values

A variable is a labelled box. You put a value inside it, you give the box a name, and from then on you can read the value back or swap it for a new one by using that name. That is the whole idea. Most code you will ever read is just boxes being filled, read, and changed. This lesson makes that one idea solid before anything else is built on top of it.

You'll learn: What a variable is, the four data types you use most, how to change and combine values, and the two errors every beginner hits first.
Time: ~10 minutes
Difficulty: Beginner. No code experience needed.
You need: Nothing to install. You run real Lua right here in the browser.

BEFORE YOU START

What a variable is

When you write a value straight into your code, like the number 10, the computer uses it once and forgets it. A variable lets you keep that value, name it, and reach for it again later. You create one like this:

lua

local score = 10

Read it left to right. score is the name you chose. The = sign means "put this value into the box". 10 is the value going in. From this point on, anywhere you write score, Lua reads it as 10, until you decide to change it.

The = here does not mean "is equal to" the way it does in maths. It means "store the value on the right into the name on the left". That action has a name: assignment. You are assigning 10 to score.

The word local at the front matters. It tells Lua to keep this variable contained to the file or block you are writing it in, so it cannot accidentally collide with a variable of the same name somewhere else in your project. The opposite, leaving local off, creates a variable that is visible everywhere at once, which sounds handy but causes bugs that take hours to track down. The rule is simple: always write local in front of a new variable. Make it a habit now and you will never have to unlearn it.

Vocabulary

variable: A named box that holds a value you can read back or change later.
local: A keyword you put before a new variable to keep it contained to the current file or block. Always use it.
value: The actual data inside the box: a number, some text, true or false, or nothing.
assignment: The act of putting a value into a variable, written with the = sign. The name is on the left, the value goes on the right.

The data types you use most

Every value has a type, which is just the kind of thing it is. Lua has several, but four cover almost everything you will do at the start. Here is one line on each.

A number is any amount, whole or with a decimal point. Lua does not split these into separate kinds, a number is a number.

lua

local level = 10
local price = 3.5

A string is text. You wrap it in quotes so Lua knows where the text starts and stops. Single or double quotes both work, just stay consistent.

lua

local name = "Quasar"

A boolean is a yes-or-no value. It can only ever be true or false, nothing else.

lua

local isReady = true

Nil means nothing, an empty box. It is what you get from a variable that was never given a value. It is Lua's way of saying "there is no value here".

lua

local reward = nil

See it run

You do not need anything installed to run Lua. The box below holds real Lua 5.4 and runs in your browser. Press RUN, read the output, then change a value and run it again.

sandbox.luaLUA 5.4

OUTPUT

Press RUN to execute.

The print function (you met it in the last lesson) writes each value to the output on its own line. Here is exactly what you should see:

Notice that print(name) did not print the word "name". It printed Quasar, the value inside the box. That is the point of a variable: you use the name, Lua hands back the value.

Changing and combining values

Reassigning a variable

The whole reason a box is useful is that you can swap what is inside it. Assign a new value to a name you already created and the old value is replaced.

lua

local level = 5
level = level + 1
print(level)   -- 6

Read the middle line carefully, because it confuses everyone the first time. It is not a maths statement saying "level equals level plus one", which would be impossible. It is an instruction: take the current value of level, which is 5, add 1 to get 6, then store that result back into level. The right side runs first, then the answer goes into the box. Lua has no ++ or += shortcut, so you always write the name out in full like this.

Joining text with the `..` operator

To stick two strings together end to end, you use two dots: ... This is called concatenation, which is just a long word for "joining".

lua

local name = "Quasar"
print("Hello, " .. name)   -- Hello, Quasar

The .. glued the text "Hello, " onto the value of name. Notice the space inside the quotes, before the closing quote. Lua joins exactly what you give it, so if you want a gap between the words, you have to include it yourself.

Converting between text and numbers

Lua is helpful with numbers inside a ..: if you join a number onto text, Lua quietly turns the number into text for you.

lua

local level = 5
print("Level: " .. level)   -- Level: 5

That works. The trap is not numbers. The real trap is joining text onto a nil, an empty box. Lua cannot turn nothing into text, so it stops with an error. When you genuinely need to force a value into text yourself, use tostring. To go the other way, turning text like "5" into the number 5, use tonumber.

lua

local n = 5
print("Score is " .. tostring(n))   -- Score is 5
 
local text = "10"
print(tonumber(text) + 1)            -- 11

Run the joining yourself and watch the pieces come together:

sandbox.luaLUA 5.4

OUTPUT

Press RUN to execute.

Common beginner mistakes

These two errors are a rite of passage. Every Lua beginner sees them, and now you will know exactly what they mean the moment they appear.

Symptom	Fix
`attempt to concatenate a nil value`	You joined text with a variable that has no value (nil). Either give that variable a value before you use it, or wrap it in tostring(x) so it becomes text first.
`attempt to perform arithmetic on a string value`	You tried to do maths on text, for example "5" + 1. Convert the text to a number first with tonumber(x), then do the maths.

What is the value and the type of a variable you never gave a value to?

Its value is nil, and its type is nil. In Lua, an unset variable is not zero and not an empty string, it is nil, which means "nothing here". Reading it back gives you nil, and trying to join it onto text with .. is what produces the "attempt to concatenate a nil value" error above.

Try it yourself

TRY IT YOURSELF

Make two number variables, add them together, and print a line that reads Total: X, where X is the sum. Try it in the sandbox before you open the solution.

lua

local first = 7
local second = 5
local total = first + second
print("Total: " .. total)

Running this prints Total: 12. Walk through what happened: you stored 7 and 5 in two boxes, added them and stored the result in a third box called total, then joined the text "Total: " onto that result with ... Lua turned the number 12 into text for you inside the join, so no tostring was needed here.

What you can do now

Create a variable with local name = value, and explain that = means assignment, not equality.
Name the four types you use most: number, string, boolean, and nil.
Reassign a variable, including the level = level + 1 pattern, and explain why the right side runs first.
Join values with the .. operator and add your own spacing.
Read the two classic errors and know that the real concatenation trap is nil, not numbers.

You now have boxes that hold values, and you can fill, read, change, and combine them. Next you will make your code react to what is inside those boxes, running one piece of code when a value is one thing and a different piece when it is another. That is the lesson "Making decisions: if and else".

REFERENCES

Lua 5.4 reference manual ↗