Wait A Moment

Sometimes you don’t want everything to happen as fast as possible in your script. A delay between events can make it more usable, more understandable, more realistic, or simply nicer to look at. Roblox has a function to do just that, naturally called wait().

Core Function: wait()

The wait() function causes the script to pause for a particular amount of time. It accepts one argument, which tells it the amount of time to wait, in seconds. For example:

print(“This is before the wait…”)
wait(2.5)
print(“…and this is after.”)
wait(1)
print(“This appears a second after the after.”)

You can see that like most numeric values in Lua, the number you pass the function doesn’t have to be an integer (or whole number). It can, of course, also be a variable containing a numeric value. Realistically, there is a minimum amount of time that can be usefully given to the wait() function: about 1/30^th of a second. In fact, you can tell it to pause for the shortest possible amount of time by giving it no argument at all:

wait()

Just like in your daily life, the shortest wait happens when there is no argument.

Something that few people know, and fewer make use of, is that wait() also returns 2 values: the elapsed time and the current game time.

Functions Are A 2-Way Street

Wait, what was that? Returns values? Yes, indeed. Functions can do much more than run off to perform some task for you, and it’s time to get a bit deeper into that.

Functions are usually thought of as receiving instructions (in the form of arguments) and doing whatever they were made for. They can also bring back information for use by the script as a whole. This is called returning data, and in most computer languages, it is a function’s main… uh, function. Let’s look at another time-based function, time(), to see how this returning data thing works:

Core Function: time()

This extremely simple function returns the current game time. In Roblox terms, this means the amount of time, in seconds, that the game has been running. It takes no arguments, though as always you have to include the empty parentheses.

Here’s a short script you can try out to demonstrate its use:

timeEarly = time()
print(“Hang on. We’re going to wait a moment.”)
wait(4)
timeLate = time()
print(“Before the wait, the time was “,timeEarly, “. Afterward, it was “, timeLate, “.”)

That’s really all there is to it. What the example shows is time() being used, not to go alter some part of the game world or its contents, but to get a specific piece of information and put it into a variable. The example does it twice, and then makes use of the variables. Notice that assigning the game time to a variable looks pretty much like other variable assignments. When a function returns a value, you can use it in the right side of a variable assignment statement just like any other value or variable.

So now we know we can put information into a function (with arguments), and get information out of it (with returned data). But what if there is more than one value returned from the function? Most computer languages don’t handle that, only letting you return 1 value from a function, but Lua can do it with no problem. wait() returns 2 values, and print() can deal with it properly, so we’ll return to those now. In Roblox Studio, insert a script into the Workplace itself – it doesn’t have to be in a visible object, but it can be if you prefer – and replace the default code with this:

print(wait(1))

Run the script. It waits for 1 second, returns 2 numbers for print() to use, and prints them. The output will be something like this:

1.00483442157 212.44375832

The first number is the “elapsed time”, meaning the exact amount of time the wait() command waited for. The precision of the elapsed time value is far, far greater than the precision of the argument you can pass to the function. There is no point trying to include milliseconds when using wait(). But if you run the script multiple times you will see that while the extremely small amounts of time change a fair bit, the important parts – whole, tenths or hundredths of a second – are far more stable, so you can safely ignore the parts too small to use (and really, too small to detect when the thing is running). Try it a few times with an empty argument, that is, just wait() with nothing in the parentheses, to get an idea of the minimum amount of time it can handle.

The second number, separated from the first by a space, is the current game time at the end of the wait. It’s exactly the same as time(), described above.

Printing multiple values isn’t all that useful on its own, really. They are just numbers. What if you want to put those numbers into variables? All you have to do is list the variables you want to use, separated by commas, before the equals sign – in the place you normally put a single variable. We’ll assign the first returned value to elapsed and the second to gametime, and then print them in a way that makes sense to humans reading it.

elapsed, gametime = wait(1)
print(“After “, elapsed, ” seconds, the game time was “, gametime, “.”)

Make that your script (noting the spaces within the quotes) and run it, and your output should be something like this:

After 1.00483442157 seconds, the game time was 212.44375832.

Although multiple function results are both unusual and useful, to be honest most people don’t even know that wait() can return any values at all, and would have little idea of what to do with it if they did. We’ll make use of the function in more common ways after learning a couple of things that can demonstrate its usefulness.

Property: Parent

In the lesson The Foundation, in the section called The Root Of Things, we discussed how every object in the Workspace has a parent, and most can have child objects. Each of them can refer to its parent object by use of its Parent property. A script can refer to itself by means of the word script. You can combine these in your scripts with the usual dot notation to refer to things in different places in the object tree . It sounds complicated, but it’s easy to do. Find out by entering and running the following 1-line script in a brick of your choice:

print(“The script’s parent is called “,script.Parent.Name)

The dot notation reference went from the script, up by means of Parent to the brick it belongs to, then down to the brick’s Name attribute. If you have objects within other objects (such as bricks in a model within a model) you can use more than one Parent reference to move up more than one organizational level. In one of your later scripts, you might well have, for example, a reference to script.Parent.Parent.Parent.Name. In short, it’s a very useful system for moving around in an object tree.

Property: Name

Another property that exists in all Roblox objects is Name. We have used it already and will use it many more times. As your projects get larger, you will find that giving objects different names – or deliberately giving different objects the same name – will be very useful when identifying objects in your scripts.

Though by now you have a firm grasp of using and altering the Name property, here is an example in case you want it for future reference. It assumes that it is the contents of a script in an object. Any object would do.

print(“The script “,script.Name,” is in object “,script.Parent.Name,”.”)
script.Parent.Name = “NewObjName”
print(“The script “,script.Name,” is in object “,script.Parent.Name,”.”)

Property: Transparency

When building with Roblox Studio, you have most likely adjusted the Transparency setting for different objects. Now you’ll learn to do it in a script. Transparency has a range of 0 (completely opaque) to 1 (completely invisible). Not every Material setting is able to show partial transparency (between 0 and 1), so for the next example, make a brick that has Material set to Plastic. Then add a script to the brick with the following text, and run it:

par = script.Parent
par.Transparency = 0
wait(2)
par.Transparency = 0.3
wait(1)
par.Transparency = 0.5
wait(1)
par.Transparency = 0.7
wait(1)
par.Transparency = 1
wait(1)
par.Transparency = 0.7
wait(1)
par.Transparency = 0.5
wait(1)
par.Transparency = 0.3
wait(1)
par.Transparency = 0

Transparency can handle more than those settings, of course, but in the interests of not making the example too big, those will do.

Have a look at the first line. We’ve assigned constants, operations (like 25+4), variables and returned values of functions to our variables before, but this is new. Here, we make the variable a pointer to an object. Once that’s done, we can use the variable and not the whole reference to the object. par.Transparency now means the same as script.Parent.Transparency. This obviously saves time typing, and you will also find that this technique can help you keep your scripts understandable when object references get complicated.