Function

< Scripting | Data Types

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.

Definition[edit]

Functions can be confusing from a conceptual standpoint. These analogies may help you.

A function as a subroutine - You can think of a function as a "subroutine" a block of code that can be executed again and again. Why do we want this? Because it reduces copying and pasting.

function YouCanRepeatMe()
	print("Hi.!")
	print("I like saying hi!")
	print("Hi there!")
end
 
YouCanRepeatMe()
YouCanRepeatMe()
YouCanRepeatMe()
YouCanRepeatMe()

You can see here, that, instead of repeating the lines inside of the function 12 times, you can repeat it only 4 times, each time you call it. This is a subroutine. You gave it a name, YouCanRepeatMe, and you told it what to do. Programming is all about automating repetitive tasks! I'm sure you can divide 234.351 to 23.1225234, but it's much easier to type it into a calculator! That's what this is all about!

A function as a, well, function - If you know functions in algebra f(x) = x*2, then functions in Lua may make a bit more sense. You input something (x), and you get an output (y). Functions on Roblox work the same way. You input something, and then you output something.

Using Functions[edit]

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. Note that the name must follow the same conventions as variables.
  • 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[edit]

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[edit]

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; also note that you cannot have any statements immediately after return or you will receive an error.
  • The function becomes somewhat like a variable, holding the value(s) returned. Like this you can "set" a variable to what the function returns.
  • 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[edit]

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[edit]

Main article: Events

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[edit]

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[edit]

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[edit]

Since a function is just another type, they can be stored in tables 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[edit]

Main article: Method
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[edit]


Practice[edit]

Exercise 1

Instructions

Create a function that takes a number and generates (and outputs) a song line from the “99 Bottles of Soda” song.

Solution
Select
--this function is optional - it just makes it so that it's "2 bottles" and "1 bottle"
function bottleString(number)
  if number == 1 then
    return "bottle"
  else
    return "bottles"
  end
end
 
function bottlesOfSoda(number)
  local noun = bottleString(number)
  print(number .. " " .. noun .. " of soda on the wall, " .. number .. " " .. noun .. " of soda!")
  number = number - 1
  noun = bottleString(number)
  print("Take one down, pass it around, " .. number .. " " .. noun .. " of soda on the wall!")
  print("")
end


Exercise 2

Instructions

Create a function that determines if a number is even and returns true or false.

Solution
Select
function isEven(number)
  return (number % 2 == 0)
end