Scripting

Up one category:
Lua Help

So, you want to learn how to script? This should be the very first place to look. Be sure to read everything carefully, making sure that you understand what is being read. If you have any questions or comments feel free to ask them on the Forum.

Introduction

The ROBLOX scripting language is Lua 5.1, a concise and efficient scripting language used in games and embedded systems. Documentation on the language can be found at here.

Scripting requires the Script object which can control a number of things. For list of Lua objects that can be used, see the Class Reference.

This article is documentation for people slightly familiar with the language. If you have no idea what you're doing, you may want to look at these:

Intro to Scripting: Make a Dance Floor is a tutorial for beginners that shows how scripts can be used to control the color of parts. Also, when scripting it is also important to look at the Object Browser. Keep it open when you're making scripts in Edit mode. It can show where and why you've made a mistake.

Fundamentals

These are the basics. It is very important to understand these.

Defining Scripts

Script objects can be placed under the Workspace or under parts, models, values, etc.

Scripts can also be written and executed in the Command toolbar. To execute a script from the command bar:

Edit a place in ROBLOX Studio.
Select View-->Toolbars-->Command from the menu bar.
The Command toolbar will appear at the bottom of the screen.
Select View-->Output from the menu bar.
The Output panel will appear just above the Command toolbar.
In the Command toolbar's textbox type the following:
```
print("Hello World")
```
Press the 'Enter' key.
The text "Hello World" appears in the Output window

Script Execution

Script objects only run under certain conditions:

Scripts entered in the Command toolbar execute when you press Enter. This only applies if you're in either edit mode or Solo mode.

Scripts will run, as said before, if under the Workspace or general containers.

Scripts inside a Tool run when the Tool is activated.

Also, if you want a script to NOT run when the game is started, make sure that under the Properties for a script, the Bool 'Disabled', is set to true. A script will also not run if under the Lighting, Sound Service, or any Service besides the Workspace. If the script's property is under the DataModel, then it will also not run.

Environments and Libraries

Each Script has its own copy of the global Environment. This "sandboxes" each script. For instance another script cannot overwrite the global data defined in another script.

ROBLOX loads the following Lua standard libraries: Basic Functions, Coroutine Manipulation, String Manipulation, Table Manipulation, Mathematical Functions. For security purposes some functions have been removed to deny access to system resources. A list of these functions can be found in the Function Dump page of the wiki. In addition, some Roblox Lua Objects have been removed for the very same reason.

Math

One important feature that nearly all programming languages use is math. Here's what you need to know:

You can use the Output to view your solutions. You can use other types of output too, like messages and hints.
Roblox can perform complex probelms for you.
This can make things extremely simple.

Here's a sample of basic math. Open up Roblox Studio, goto File> New, insert a Script into the Workspace, make sure that the Output is open.

Example

a = 1 + 1 --'a' represents your math problem.
print(a) --This prints the result.

a = 5*5+1
print(a)

a = (9*9) + 19
print(a)

For more information, and usage, read the following articles:

Data Model

The DataModel is what you would define as 'game' in your scripts.

Here are Lua 'types' that can be used in a script

Basic Types

ROBLOX scripts use the basic Lua types nil, boolean, number, string, function, userdata, thread, and table. In addition, there are the following additional basic types:

Vector3

Vector3s are 3 ordinates put together. Kind of like a 2D graph with (x, y) coordinates, Vectors are three instead of two: (x, y, z). These are used for things like brick size, position and other information.

CFrame

Coordinate Frames, or CFrames, are data types that hold a position and a rotation. Read more about CFrames over here

Color3

Color3, sets color likely in Hex format (e.g. 1, 255, 98).

BrickColor

BrickColor is a type of color used in Parts and other objects. Read more about BrickColor here

Connection

Represents a connection to an Event

Globals

In addition to loading several Standard Libraries ROBLOX defines the following global variables:

game is the DataModel object that is the root of the tree for a Place.
workspace is the Workspace object that is a child of the DataModel.
script is the Script object that defines the script. (not applicable for the Command toolbar)
print() echoes each argument to the Output panel.
time() returns returns the current game time in seconds. (NOTE: THis function is scheduled for an upcoming release)
wait(t) yields the current thread after "t" seconds have elapsed. If t is not specified, then it yields for a very short period of time. The function returns 2 values: The elapsed time and the current game time.
delay(t,f) executes function "f" after "t" seconds have elapse. The function "f" is called with 2 arguments: The elapsed time and the current game time.

Roblox Objects

See Main List: RBX.lua Objects

Each object in the Explorer is accessible with scripting. ROBLOX Objects have Properties, Functions and Events. You can browse the member definitions by clicking Class Explorer under the Help menu.

Properties

Object properties are accessed with the “dot” notation:

script.Name = "Hello"
print(script.Name)

Some properties are Read-Only. Attempting to assign to a read-only property will throw an error.

Functions

Member functions are called using the "colon" operator:

copy = script:clone()
print(copy.Name)

Functions in Lua are first-class objects. Therefore you can reference a member function as follows:

f = script.clone
copy = f(script)
print(copy.Name)

Note: If you are used to other scripting languages you will need remember to use : instead of . when invoking a member function. script.clone() will not behave as you might expect.

Events

Events are fired by Objects. Scripts define code to be executed when an event is fired. Events can optionally send one or more arguments when fired.

There are two ways to handle an Event:

When a script calls wait(), the currently executing thread yields until the Event is fired. The return values from wait() are the Event arguments.
A script calls connect() passing in a function that the Event will call each time the Event is fired. connect() immediately returns a Connection object that can be used to disconnect the listener function.

Here is some sample code:

-- Get the Script's Parent object
part = script.Parent

-- Define a handler for the "Touched" Event
function onTouched(otherPart)
print(otherPart.Name .. " touched me!")
end

-- Listen for each time that "part" is touched
connection = part.Touched:connect(onTouched)

-- Put this thread to sleep until a property changes
propName = part.Changed:wait()
print("Property changed: " .. propName)
-- Stop listening to the Touched event
connection:disconnect()

This code listens for two events: The Part being touched and also for a Changed event. Since we connected to the Touched event, the function onTouched() will be called each time Part is touched. However, once the Changed Event fires and the wait() call returns, we won't listen for another Changed event. At that point we also disconnect from the Touched event.

You are not strictly required to disconnect every connection you make. If the Object owning the Event is collected, then the listening script will no longer get events. Similarly, if the Script Object that owns the listener is removed, then the connection is automatically broken, and any waiting threads can be collected.

Object Types

There are many different object types in Roblox, and in addition to adding them through the Roblox Studio, you can also define a new object in a script with the line Instance.new("className"), with className being the object's type. Following is a listing of many of the various object types.

Common Mistakes

The slightest misspelling, or even incorrect capitalization will result in your script failing to work. REMEMBER: Look at the Output to check for errors. If this doesn't help, back-track and make sure everything is perfect. If you think there is a problem, or you need help in general, report the problem to the Bugs article, and request help on the Forum. For more help, see the 'See Also' section at the bottom of the page.

Scripting

Contents