Functions

< Scripting | Data Types

Introduction

Functions perform specific tasks. Some functions are already predefined, and some functions you create yourself. Methods are also an example of functions for specific objects. The idea behind most functions is either to check or modify something, or to save yourself some time by avoiding repeating code. functions are also used to define code that you don't want to call immediately.

Using Functions

The basics of writing a function is actually pretty easy.

function twoPlusTwo() -- Function name
	x = 2 + 2          -- Variable
	print(x)           -- Print variable's value
end                   -- End

twoPlusTwo()          -- This is how you call a function. Once called it will run your block of code from before.

Everything between function and end sets what your function will do. Here, you are:

• Declaring a function by the name of TwoPlusTwo. You can name a function anything you want, but typically, you'll want to give it a name relevant to its purpose.
• Assigning a value of 2+2 to x
• Printing x

It's important to note that your function won't run/execute until you specifically call it. That's what the last line - TwoPlusTwo() - does. If you delete this line, nothing will get printed to your screen, because, as previously stated, the function won't run.

When calling a function, the code bookmarks where you started and returns to the bookmark after the function executes. For example, examine this code:

function firstfunction()
	print("We are in 'firstfunction'")
end

function secondfunction()
	print("We are in 'secondfunction'")
end

function main()
	firstfunction()
	print("We are in 'main'")
	secondfunction()
end

main()

We are in 'firstfunction' We are in 'main'

We are in 'secondfunction'

If you check your output, notice how it will execute main(), then put a bookmark where you called firstfunction(), execute firstfunction(), print "We are in 'main'", bookmark it where you called secondfunction(), and lastly, execute secondfunction().

Using Arguments and Parameters

Main article: Arguments and Parameters

When a function is called, the caller can set some variables within the function. Properly, these variables are called "parameters", although they are often referred to as arguments as well. The values that these variables are set to are called "arguments". The parameters in a function are always local to the function and are only used in the function's scope and its descending scopes. For a nice example, I'll demonstrate a short little function that adds its arguments together, and displays the result in the output.

-- num1 and num2 are the parameters
function add(num1, num2)
	print(num1 + num2) 
end

-- 3 and 4 are the arguments
add(3, 4)

7

If you call a function and enter too many arguments, the excess ones will be ignored, on the other hand, if you forget any, the value of nil will be given to all missing arguments.

Using Return

Sometimes when using functions, you'll want to get a value out of them. Let's take another look at the Add function before, but this time, instead of printing the sum, we'll use return.

function add(num1, num2)
	print("Finding sum.") 
	return num1 + num2 
	print("Sum found") 
end

x = add(5, 2) 
print(x)

Finding sum.

7

When return is called, a couple things happen:

• The function stops executing; notice how "Sum Found" wasn't printed. This is useful for preventing execution of code in a function.
• The function becomes somewhat like a variable, holding the value(s) returned. Examine this code to understand this idea better:

function addNumbers(num1, num2)
    return num1 + num2
end

a = addNumbers(3, 5)
print(a)

8

Functions as Variables

In Lua, functions are first class objects. This means that they are treated as an expression, like "Testing", and can be stored in a variable. For example:

local myPrint = print
myPrint("test")

test

Similarly, they can be passed as arguments to other functions.

This can also be done to custom made functions. Examine this code:

addNumbers = function(x, y)
	return x + y
end

print(type(addNumbers))

function

Event Triggered Functions

Functions don't have to be called by writing out a command. They can be called by an action known as an event. For example, say you want your function to be called when a player enters a game. The event that corresponds to this scenario is the PlayerAdded event. You would write your function as usual. But then instead of calling it the same way as before, you'd treat it as an event handler, and bind it to an an event - typically referred to as a connection line.

function PlayerAdded(p) 
	print(p.Name) 
end
  
game.Players.PlayerAdded:connect(PlayerAdded)

Notice how although I set an argument when writing the function, I didn't include it when setting the function to be called. That's because we don't want the function to be called when we bind the event handler - we want the function to be called when the event happens. In this case, the function is being treated as a variable. Most events call their event handlers with arguments. In the case of the PlayerAdded event, the handler is called with a single argument - the player who joined the game.

Anonymous Functions

Main article: Anonymous Functions

Functions can also be created anonymously, that is, without assigning them a name. These are occasionally known as lambda expressions.

For example, the following syntax is a function expression

function() print("hi") end

This isn't a valid statement by itself, but is instead a value that can be used in place of a function name.

For example:

hi = function() print("hi") end

Is the same as:

function hi() print("hi") end

Anonymous functions are often used as a shorthand where a function is passed as an argument to another function. A good example of this is the Delay function;

Delay(1, function()
	print("I've waited 1 second now")
end)

Notice the Delay function's closing parenthesis is after the "end" for the function.

Another common place where anonymous functions are used is when connecting event handlers

game.Players.PlayerAdded:connect(function(p)
	print(p.Name) 
end)

Recursion

Main article: Recursion

Recursion, in programming, is the process of repeatedly calling the same function from the bottom up. Recursion is often used in place of loops. An advantage to using recursion over loops is its simplicity and the main disadvantage is that large recursions could cause heavy use of memory, and on ROBLOX, lag.

Functions Within Tables

Since a function is just another type, they can be stored in table like other types.

tab = {}
function tab.func( arg )
	print "I'm in a table"
end
tab.func(1)

This is the same as:

tab = {
	func = function( arg )
		print "I'm in a table"
	end
}
tab.func(1)

Methods

See also: Object-Oriented Programming

A method is a special function that operates on the table that contains it. This is what Roblox uses for its objects. Lua provides a special syntax for methods:

tab:method(args)

This is equivalent to:

tab.method(tab, args)

Notice that the table is used both to get the function and as an argument.

You can declare methods directly:

tab = {}
function tab:method( args )
	print( "I'm a method from " .. tostring(self) .. " with args " .. tostring( args ) )
end

Which is the same as:

tab = {}
tab.method = function( self, args )
	print( "I'm a method from " .. tostring(self) .. " with args " .. tostring( args ) )
end

See Also

• Function Dump
• Functions in-depth
• In-Depth Scripting Guide