Scripting | Documentation - Roblox Creator Hub (2024)

Scripts are plain text files that let you add custom, dynamic behavior to your experiences. You can use scripts to trigger in-game events, respond to player input, save player data, create leaderboards, spawn enemies, control NPC behavior, and much, much more.

Luau

Roblox scripts use the Luau programming language, which is derived from Lua 5.1.

• Compared to Lua 5.1, Luau adds performance enhancements and many useful features, including an optional typing system, string interpolation, and generalized iteration for tables.

• All valid Lua 5.1 code is valid Luau code, but the opposite is not true.

Most books and online resources for Lua are still broadly applicable to Luau. For a detailed summary of differences, see Compatibility in the Luau documentation. For language syntax, see the Luau Reference.

Luau Basics

Luau is gradually typed, so you don't need to specify a type when you create a variable. You can use type() to check object type:

logMessage = "User has more than 10 items!"
print(logMessage) --> User has more than 10 items!
print(type(logMessage)) --> string

Luau has global and local scopes, but it's almost always better to declare variables and functions locally with the local keyword:

local logMessage = "User has more than 10 items!"
local function printMessage()
 print(logMessage)
end
printMessage() --> User has more than 10 items!

Lua uses nil to represent nonexistence or nothingness, which evaluates as false in conditional statements:

local messageToUser
print(messageToUser) --> nil
print(type(message)) --> nil
if messageToUser then
 -- statement evaluates to false
end
See Also
Script Editor | Documentation - Roblox Creator HubCreating a Script | Documentation - Roblox Creator HubBeginner guide to scriptingRoblox Scripting Tutorial: Getting Started

As you might have noticed, -- starts a one-line comment. --[[]] creates a block comment:

--[[
 Shuts off the cosmic moon ray immediately.
 Should only be called within 15 minutes of midnight Mountain Standard
 Time to avoid damage to the cosmic moon ray.
]]
local function stopCosmicMoonRay()
 -- add this later, it might prove important
end

Tables are the generic term for arrays and dictionaries. Arrays are one-based rather than zero-based, so the first item is [1]. You declare arrays and dictionaries with a single set of curly braces:

local myArray = {"chips", "sparkling water", "salsa"}
local myDictionary = {
 snack = "chips",
 drink = "sparkling water",
 dip = "salsa"
}
print(myArray[1]) --> chips
See Also
Scripting | Documentation - Roblox Creator Hub
print(myDictionary.dip) --> salsa

You can iterate over tables using for loops with the ipairs() function for arrays and the pairs() function for dictionaries, but Luau also lets you omit these functions for cleaner syntax:

for index, value in ipairs(myArray) do -- standard Lua
 print(index, value)
end
for key, value in pairs(myDictionary) do -- standard Lua
 print(key, value)
end
for key, value in myDictionary do -- Luau generalized iteration
 print(key, value)
end

Your First Script

1. In Roblox Studio, hover over ServerScriptService in the Explorer window and click +.

2. Select Script to add a new script.

3. Right-click the script and rename it to HelloScript.

4. Double-click the script to open it in the Script Editor.

5. Add the following code to the file:

   local helloArray = {'h', 'e', 'l', 'l', 'o'}
   local worldArray = {'w', 'o', 'r', 'l', 'd'}
   for index, value in helloArray do
    print(value)
   end
   print(table.concat(worldArray))

6. Ensure that the Output window is open.

7. Click Play to run your experience.

8. Note the output:

   h
   e
   l (x2)
   o
   world

Getting Comfortable

A big part of adapting to a new development environment is configuring it to meet your needs and understanding the tools at your disposal:

• The Script Editor section of Studio Settings lets you adjust quality of life features like font, colors, indentation, autocomplete, brackets, and tooltips. You might also want to enable dark mode in the Studio section.

• Holding Ctrl or Command and clicking on a function or variable takes you to its declaration in your codebase (or its online documentation). Using Find and Find All can help you navigate larger projects.

• The Output window is the most basic tool for understanding the behavior of your scripts. Use the ⋯ menu to enable Show Context and Show Source.

• The Script Analysis window shows a summary of errors and warnings, but you might find its utility limited; the Script Editor already highlights these issues as you type.

• Logging capabilities are minimal, with no concept of log levels like DEBUG or FATAL. Use print() and warn().

For more information about configuring Studio for scripting, see Script Editor. For information on using your favorite text editor and version control system, see External Tools.

Your Second Script

1. In Roblox Studio, add a script to ReplicatedStorage in the Explorer window and rename it to OhNo.

2. Add the following code to the file:

   print("Hello script types and locations!")

3. Click Play to run your experience.

4. Note how the output is no different than when you ran your first script.

To understand why the script didn't run, see Script Types and Locations.