Absolute beginner's guide to scripting

Up one category:
Tutorials

Outdated Page This article has outdated information. Please update this page to fit our current standards! Specifically: Windows XP screenshots.

Introducing ROBLOX Lua

This tutorial shows you how to do some basic scripting, or programming. However, you must follow instructions exactly.

Please Note: In order to learn scripting, you must do the actions. Reading will not help that much. Actually FOLLOW the instructions.

What is scripting?

Scripting is a way to tell the computer what to do. However, computers can only understand commands to do things if you tell them exactly what to do, in a specific code or language. ROBLOX Scripts are commands in a coding language called Lua. Lua is not-so-hard to understand, depending on the way you want to use it. Lua was made to be simple to read and easy to understand, along with being simple to put into games. Lua was not specifically designed for ROBLOX. Instead, it was designed to be put into games like ROBLOX. The Lua in ROBLOX is a version of 'normal' Lua that has been modified for ROBLOX. We will be learning this modified version.

Please note: It's "Lua", not "LUA", because Lua is not an acronym.

A key addition to ROBLOX Lua is the ability to navigate a tree of objects in your game using a parent-child relationship between objects (sometimes called 'Instances' in ROBLOX Lua)

Your first program

You are about to make your very first script - a script to kill yourself. There is multiple ways to execute (or run) code in ROBLOX, but you will be executing the script from a place in ROBLOX Studio called the command bar. The command bar allows you to execute a single line of script instantly in a blank place. The command bar will only run one line of code at a time. The first thing we want to do, is to open up the command bar, which is in ROBLOX Studio.

How do I open Studio, and how do I enable the command bar?

• Novetus
  1. Open "NovetusBootstrapper", located in the root of your Novetus directory.
  2. Click "PLAY NOVETUS".
  3. If you're editing an existing place, select your place from the place box. Otherwise, ignore this step.
  4. Click the "Build" button.
  5. You should then see this prompt pop up. If you're editing an existing place, click "Yes", otherwise, click no.

• Enabling the Command Bar

You can enable the command bar by going to: View > Toolbars > Command (if there is no check mark next to it). A text box will appear at the bottom of the software. You can insert code in there and it will execute.

Being specific

When you first create a script, you have to know what it is meant to do at exactly what time and under what conditions. For a script that kills your character it's pretty obvious what it needs to do: it kills you. Scripting is just giving commands to the computer, so you just need a line of code to do something to kill your character.

Remember that scripts can break with just one letter or symbol being wrong.

How do you kill your character? You need to set the Humanoid's health to zero. A Humanoid is one of the types of objects in ROBLOX Lua that controls player's health. There's many ways to set the health to zero, such as removing the character's head or specifically setting the health to zero. For now, we'll just remove the head.

ROBLOX won't remove anything until told, so we need to navigate the tree structure of ROBLOX games to find the character's head and remove it. The structure of a ROBLOX game is like a tree, and the trunk is a DataModel object called game. There is a "branch" (known as a child) called Workspace. Think of all the bricks in your game children on the Workspace children. bricks are organized as more children of the workspace. Your character is a child of the Workspace, and the Workspace is a child of game.

Note that children of game are known as game services, which provide functionality for your game automatically. When you enter any place, you have a Player object named after you inside the Players game service and a model named after you in the Workspace (called a character). Your character holds your head, torso, limbs and other visual stuff. The player object does other things that won't be covered right now.

ROBLOX Studio has a nice tool that lets you view the family tree visually. It is called the Explorer#The_Explorer_and_Properties_Bar,Explorer window. To open it, click View > Explorer. It is very self explanatory.

Writing Lua code

The ultimate trick to being a scripter is to mastering how to make code that does what you want, when you want it. Since you are a beginner, you will be walked through the steps to making your code do what you want starting from English to Lua code. Do not think of scripting as translating to a language; think of scripting as giving orders on what to do.

Here's our starting command. It's what we want to happen, and it has been written in plain English.

Remove USERNAME's head.

Naturally, ROBLOX will not like that very much because it's in English! You have to figure out how to express what you want to happen in Lua code.

In game, find Workspace, find USERNAME, find his Head, and remove it.

game is the root of all things in your game. We need to "go down" the family tree and find the right brick to remove. To get an object that is a child of another object this, you use a period (.) after the parent object, then the child object's name. Going through the family tree, we get this:

Delete game.Workspace.USERNAME.Head

This is almost a working ROBLOX Lua statement! Now, to actually remove the head, a method must be used. Methods are functions that do specific things in ROBLOX for you by calling them. Methods are functions of objects in ROBLOX Lua. To call a method on an object in Lua, you use a colon (:) after the object. You then state the name of the method, then two parenthesis with nothing in them. Methods and functions take arguments, which are values given to the function to change how it works. The "Destroy" method takes no arguments, so we place the parenthesis there to show that there's nothing else we have to give to the Destroy method.

workspace.USERNAME.Head:Destroy()

The above statement is syntactically correct Lua code. However, your name isn't USERNAME, so substitute your name in. If your name was "AwesomeSocks", then you would use the following:

workspace.AwesomeSocks.Head:Destroy()

To compare this to English, it would be like saying "The sky has trees". It is grammatically correct English, but an untrue statement. If you state the name of things that do not exist, your script won't work and an error will occur.

Testing the script

To test your fine script, enter any normal ROBLOX place in solo mode (or build mode) so that you can walk around with your character. Open up Roblox Studio and open the command bar. Type your one-lined wonder in, and hit enter to run it.

NOTE: You must open build mode or solo mode from the studio, if you open it from the browser, you will not be able to open the command bar.

If your head just disappeared and you heard an "Oughh!" sound because your character just died, then you have succeeded. Your script works.

If your script does not work and nothing happens, expect this to happen a lot. Scripters (and programmers alike) run into the problem of their scripts not doing something right because their code has bugs in it. Not to worry, though - there is the output, a key tool that can help you debug your scripts and get them working.

Setting Values in ROBLOX Lua

What about changing values of objects in ROBLOX Lua? There is a way to do that, and it's more of the same. To set your health to zero (rather than going "Off with your head!") you need to set the Health property of your humanoid to zero. To set properties of objects, you use a period (.), the property's name, an equals sign and the value.

workspace.USERNAME.Humanoid.Health = 0

You will learn specifics about what is what in ROBLOX Lua later (such as "What does the equals sign really do?"). For now, you can consider yourself a really basic scripter that can call methods and change property values.

Pro tip: The Workspace is a special game service. Since it is used a lot in scripting, ROBLOX Lua has a built-in constant (just like game) called Workspace rather than game.Workspace. You'll learn about constants and variables later, but know that the Workspace is the only object in ROBLOX Lua that has it's own built in constant.

workspace.USERNAME.Humanoid.Health = 0

Inserting a Script object

To add a new script in ROBLOX Studio, just click Insert > Object... > Script. You'll find a blank script that has been added to the Workspace.

Try modifying it to do different things. It is exactly like the command bar we have been using, but now you can have multiple lines of code.

Editing a script in ROBLOX Studio

To open a script object's source (the code in the script object) for editing in ROBLOX Studio, you can double-click it in the Explorer window and a text editor will open where you can change your script's source. Whatever you add, remove or change in this text editor is permanent, and besides the "undo" button, these changes cannot be undone once the editor is closed.

Starting and Stopping your script

Script objects run their code under the following conditions:

• The script is added to the game (Select the script in the Explorer window and cut it (CTRL+X), then paste it back into the game (CTRL+V, or right click Workspace and click "Paste Into").
• The script's disabled property is changed to false (select the script in the Explorer window and toggle it's Disabled property in the Properties window).

Script Creation

There are 5 topics that will be answered here:

• Creating the script
• Storing references to objects
• Listening to events
• Functions
• Modifying objects

NOTE: All work, building and scripting, should be done in Edit Mode. All these lessons will be shown as if you are in Edit Mode. To open Edit Mode, on your desktop screen, hit Start>Programs>ROBLOX>ROBLOX Studio. Then go to your profile, then click "Edit". You can also press CTRL+N or click File>New to get a completely empty place.

Creating the Script

To get a script, go in Roblox Studio and then simply select Insert>Object. Now, a window will appear. In the newly appeared window, click on "Script" and OK. You should find the script inside "Workspace" in the explorer tab. If you don't see any explorer window up, go to View >Explorer.

Now to open the script, just double-click it. If you did it right, a window will cover the whole in-game screen. And you will find the line "print "Hello World!"" Before you start, just go ahead and delete that line.

Making References to Objects

Assuming the script is still under Workspace, that is where your script will run. Let's say you want a brick turning invisible/visible, back and forth when touched. The script needs to know where that brick is before modifying it.

Now, making references to objects is not necessary, but it can make scripting a lot less work. Here's an example of how you do it:

local brick = workspace.Brick

That will make `brick` refer to workspace.Brick. You can set the name to absolutely anything. This is an example of a variable. You can have as many variables as you want in a script.

If you didn't store it in a variable, every time you try making the script modify the object, you would have to put the line "workspace.Brick". Variables make it much simpler, since you only have to put the name you assigned. Name the brick desired to "Brick", and make a reference to it in the script by typing the example above. Note that making a reference to an object is the same as assigning a variable.

Event Listeners

Now we're getting into the meat of scripting. Sure, the script knows where the brick is, but that's all. It can't do anything else. Now we're jumping into a listening event.

An event listener watches what's going on, and waits for an event to happen. When it does, it tells the script to do something. This is one important part of the script, otherwise you couldn't really make scripts wait for anything.

You still should have the script with the variable in it. We're going to make the script listen for being touched (the Touched event). Here's an example:

brick.Touched:connect(onTouched)

When the brick is touched, it will execute the function named onTouched. Keep in mind that the name inside the parentheses is the name of the function.

This is not the only listener type. There are many more to use, some of which require some familiarity with scripting. Here is a very well-done reference page set up by MrDoomBringer.

This is where you can find more help in the future, when you begin to understand scripting more. Not only does it show Events, but also shows other scripting references need for other aspects of scripting.

Put the line

brick.Touched:connect(onTouched)

a line or two below the variable assignment

local brick = Workspace.Brick

Functions

Your script is getting better and better, but where is the function? Your script will break if it doesn't have one of those for the listener to refer the script to.

What is a function? It is where all your modifying work will be done. It is also an important part to your scripting. Without it, you could not make the script modify objects from listeners. Another example:

local function onTouched(part)

end

There is the function. As you can see, the word "function" is followed by "onTouched", the name of the function. The listener from last lesson is trying to refer to the function. The listener is going to tell the script to run through this function and do whatever is found inside. Notice the "(part)" after the function name. This is a reference to the object that the listener found that touched the brick. This is not always needed, especially for some event listeners.

But back to what we're looking at. The variable "part" is the object that touched the brick. You can play with this object for fun later. Now notice also two lines below the function: "end". You will need one of these for every function and other block structures in scripting, such as "if" statements. Always remember this when scripting.

Now, make the lines from first example, except put it two lines under the variable assignment, and one line above the listener.

Modifying Objects

The script knows the brick, will wait until it's touched, and has the function to use. But it doesn't know what to do to the brick.

This is where storing references to objects saves you time. We wanted it to flicker invisible/visible, so here's an example:

brick.Transparency = 1

wait(1)

brick.Transparency = 0

These lines will alter the brick as we wanted. The brick's transparency is changed to "1", which is completely invisible. The "wait(1)" line will make the script wait for one second before continuing, then the brick's transparency will be put back at 0, which is completely visible. You can alter "wait(1)" to any number inside the parentheses. Whatever number you put inside the parentheses will be the amount of time it will wait in seconds.

Put those 3 lines right under the line "local function onTouched(part)" and above the line "end".

Complete script

local brick = workspace.Brick -- Store a reference to the brick.

local function onTouched(part) -- The function that runs when the part is touched.
	brick.Transparency = 1

	wait(1)

	brick.Transparency = 0 
end 

brick.Touched:connect(onTouched) -- The line that connects the function to the event.

Advanced scripting techniques

Make your own functions

While scripting, you may want to make your own function to call later. This is easy enough, here is the syntax (grammar) for doing so: (NOTE: These functions are called without a colon [:])

local function <functionname>(<parameter>)
    <statements>
end

<functionname>(<parameters>)

A parameter is a way to give data to a function. An example of a parameter: a Humanoid has a TakeDamage() function. You have to tell it how much damage to take. You would type Humanoid:TakeDamage(100) to take 100 damage. (NOTE: the TakeDamage function will not take damage if the humanoid has a ForceField. Use this function for weapons instead of directly setting the health, to prevent spawn killers)

Functions can also return a value, which means they can be used instead of a constant (like a number) or a variable (covered below):

local function <functionname>(<parameters>)
    <statements>

    return <valueobtainedfromstatements>
end

<somevariable> = <functionname>(<args>)

Copy and paste these codes into a script for a better example:

Example 1

local function sayHello(name)
    print("Hello, " .. name .. "!")
end

sayHello("Bob")

Example 2

local function addNumbers(a, b)
    local answer = a + b
    return answer
end

local answer = addNumbers(1, 2)

print(answer) --> Prints in the output 3

Functions that return values Note the return statement in Example 2. The return statement automatically ends the function at that line, and then gives the value to the variable on the LEFT SIDE of the equals sign. Let's look at that again, this time with detailed comments:

-- Define a function called addNumbers with the arguments "a" and "b"
local function addNumbers(a, b)
    -- make a variable called "answer", and set it to the sum of a and b.
    answer = a + b
    -- Return the variable called answer. This ends the function.
    return answer
end

-- Set a variable called "answer" to the return value (answer) of addNumbers, with the arguments 1 and 2.
local answer = addNumbers(1, 2)

print(answer) -- Prints in the output 3

Flow control

Flow control, or Control statements basically means doing different things depending on the situation. They can also control the way the code is executed in the end. There are two main ways to do it in Lua, both involve conditions.

Conditions

A condition is a situation. A simple condition is this:

1 == 2

(Note the "==". Always use that, and not "=".) Of course 1 isn't 2! So that would be false.

1 < 2

That would be true, because 1 is less than 2.

These are all of the conditions that you can use:

== Is equal to
< Less than
> Greater than
<= Less than, or equal to
>= Greater than or equal to
~= Not equal to

A reminder about these conditions is you put the symbol first, and then the "=", although this doesn't apply to the less than, or greater than conditions.

If statements

The if statement does something only if a condition is true. Syntax:

if (<condition>) then
    <statements>
end

Example:

if (2 + 2 == 4) then
    print("All is right in the world")
end

That would always print "All is right in the world", because 2 + 2 is always equal to 4.

There is also an else statement, which executes if the condition is false:

 
if (<condition>) then
    <statements>
else
    <statements>
end

Example:

if (2 + 2 == 4) then
    print("All is right in the world")
else
    print("Warning! Warning! Computer Self-Destruction!")
end

While

while <condition> do
    <statements>
end

This does something over and over until the condition is false, or the break command is executed. People typically don't use this unless they want a never-ending loop, in which case their condition is true, and the loop will not terminate. Here is something very important: If this is an infinite loop, you MUST put a wait() function in your loop! Otherwise your computer/server will take every ounce of it's processing power to execute the code, because right when it's done, it wants to execute again. This WILL crash the server. This will make it wait so it has time to execute other things, and not crash.

Example:

while true do
    print("Lagging up your computer...")

    wait(0.5)
end

See also

• Scripting
• The Class Reference
• Edit
• Roblox Studio
• Script
• Workspace
• Scripting
• In-Depth Scripting Guide
• Tutorials