Variable

For a tutorial on variables, see Tutorial:Variables.

An assignment statement used after a local statement.

In Lua, a variable is a name that is associated with a value. It can be accessed either by an identifier or a table field. Variables have a value of nil by default.

Within the context of scopes, a local variable is different from a global variable in that if a variable associated with a name is declared local, an identifier of the given name within the variable's scope can only access that variable. Local variables also provide more performance than global variables.

Because Lua is a dynamically typed language, variables do not have types; the values do, and values can be set and re-set to any other type. Luau allows gradual typing where variables can be given types.

Data types

The data type of the value may be either a value type (set of values, one of which the variable directly contains) or a reference type (where a value, usually of a composite data type, is referenced by the variable rather than being contained, and the reference is the value being stored).

Value types allow an assignment to copy the value to another variable, while reference types do not; instead the assignment copies the reference. In other words, two reference type values created from the same constructor with the same given values are not equal since their references are different (the rawequal function will return false). Consequently, value types can be used to index a table via same values while reference types cannot; only references can be used.

The type function can determine a value's type and return one of the nine types (nil, boolean, number, string, function, table, thread, vector, and userdata) as a string. Value types include nil, boolean, number, string and vector. Reference types include function, table, thread and userdata. The typeof function includes Roblox types which are userdata.

Syntax

A value is assigned to a variable by an assignment statement. The notation is as follows: the variable (identifier or table field), followed by the equal sign (=), and then the expression which will be the value. Variables may also be used in the expression.

x = 100 -- number
foo = "bar" -- string
x2 = x + 1 -- arithmetic operator (addition) with operands x (variable) and 1 (number)

Several variables can be assigned in parallel, where the variables and the expressions are separated by commas.

x, y = 1, 2
x, y = y, x
x, y = -y, -x

Identifier

An identifier is a lexical token which is used to access variables. It can be any string of letters, digits, and underscores, but does not start with a digit. Identifiers are case-sensitive; foo and Foo are two different identifiers for example. Identifiers are also used in table fields, preceded by a period (.), and in table constructors as keys.

Local variables

A local variable can be declared using the local statement followed by an assignment statement or just the identifier itself. In contrast, a global variable is a variable that is not explicitly declared as local. The statement scopes the variable so that it can only be used from inside its scope. It may also be used as an upvalue, i.e., used in a function along with its local variables unless if another variable with the same name is declared local within the function.

There can only be 200 locals/upvalues at a time. Luau has 255 registers since an instruction only has 8 bits to refer to one, hence the limits. Because local variables require less instructions than global variables, using local variables provides faster performance than using global variables.

local x = 50
local y
y = 10

function getVector2()
    return Vector2.new(x, y)
end
print(getVector2())

Local variables are also initialized by function parameters.

function lerp(a, b, t)
    return a + (b - a) * t
end

Since named functions are already assigned to variables, a function can be stored in a local variable, which makes it a local function.

local function lerp(a, b, t)
    return a + (b - a) * t
end

-- which is the same as

local lerp = function(a, b, t)
    return a + (b - a) * t
end

Blocks

Blocks can be delimited explicitly with the keywords do and end, often used for local variables that are only used in a smaller set of tasks.

local distance do -- calculate the distance between Player1 and Player2 while ignoring the y axis
    local position1 = workspace.Player1.Torso.Position
    local position2 = workspace.Player2.Torso.Position
    local vector = (position2 - position1) -- calculate the vector from position1 to position2
        * Vector3.new(1,0,1) -- ignore y axis
    distance = vector.Magnitude -- obtain the length of the vector as a number
end
print("Distance: " .. distance)

Table fields

Table fields are also variables, though the key does not necessarily have to be an identifier and can also represent other data types. Consequently, an assignment statement can be used to assign a value to a table field.

local t = {}
t.x = 4
t["y"] = 5
t.z = 6
print(t.x, t.y, t["z"])

Methods

See also: Function § Methods

Like local variables, table fields can also store methods (functions).

local t = {}

function t.lerp(a, b, t)
    return a + (b - a) * t
end
-- is equivalent to
t.lerp = function(a, b, t)
    return a + (b - a) * t
end

Annotations

In Luau, local variables (along with function parameters and return values) can be given annotations using ":". However, the annotations do not work in the older Lua language where it will instead result in a syntax error.

--!strict

local x : number
x = 100
x = x + 50

External links

• Roblox Lua Style guide, the official Roblox style guide with rules for naming your variables