Funções

Funções são blocos de código que você pode executar várias vezes sob comando. Você também pode conectá-las a eventos ou atribuí-las como callbacks.

Funções básicas

Uma definição de função inclui:

• O escopo da função: global ou local (ou const para uma função local cujo nome você não pode reatribuir).
• A palavra-chave function.
• O nome da função em camelCase.
• Os parâmetros da função entre parênteses (()).
• O bloco de código, ou "corpo", da função.
• A palavra-chave end.

O corpo da função é executado quando você chama a função. Para chamar uma função, digite seu nome seguido de parênteses. Você pode definir uma variável para aceitar o valor de retorno ou usar o valor de retorno no lugar de uma variável.

-- Esta função não tem parâmetros e retorna nil
local function addOneAndTwo()
	local result = 1 + 2
	print(result)
end
-- Chamando uma função sem retorno
addOneAndTwo() -- 3

Parâmetros

Parâmetros são variáveis que você torna disponíveis para a função e são usadas apenas no escopo da função. Funções não têm parâmetros por padrão. Se você chamar uma função com mais parâmetros do que ela espera, Luau ignora os parâmetros extras. Se você chamar uma função com menos parâmetros do que ela espera, Luau passa nil para todos os parâmetros ausentes.

-- Esta função tem dois parâmetros: num1 e num2
local function addNumbers(num1, num2)
	print(num1 + num2)
end

addNumbers(2, 3) -- 5
addNumbers(5, 6, 7) -- 11
addNumbers(9) -- tentativa de realizar aritmética (adição) em número e nil

Retorno

No corpo da função, a palavra-chave return retorna um resultado de um cálculo. Você pode retornar múltiplos valores de uma função. return encerra a execução da função, e Luau espera que a palavra-chave end siga as instruções return, então escrever código entre o comando return e o comando end gera um erro.

-- Esta função retorna um valor de retorno
local function addNumbers(num1, num2)
	local result = num1 + num2
	return result
end

print(addNumbers(1, 2)) -- 3
local seven = addNumbers(3, 4)
print(seven) -- 7

-- Esta função retorna múltiplos valores: soma e diferença
local function addAndSubtract(num1, num2)
	local sum = num1 + num2
	local difference = num1 - num2
	return sum, difference
end

-- Chamando uma função e esperando múltiplos valores de retorno
local sum, difference = addAndSubtract(2, 3)
print(sum) -- 5
print(difference) -- -1

Métodos

Métodos são funções que são membros de um objeto, como uma classe ou tabela. Eles esperam o próprio objeto (self) como o primeiro argumento. Quando você chama um método, use a notação de dois pontos (:) em vez da notação de ponto (.) para passar self como o primeiro argumento automaticamente.

Todos os objetos no Roblox descendem de Instance e têm métodos comumente usados, incluindo Instance:Destroy(), Instance:Clone(), e Instance:FindFirstChild().

local Workspace = game:GetService("Workspace")

-- Destruindo uma parte com notação de ponto (função)
local firstPart = Instance.new("Part")
firstPart.Parent = Workspace
print(firstPart.Parent) -- Workspace
firstPart.Destroy(firstPart)
print(firstPart.Parent) -- nil

-- Destruindo uma parte com notação de dois pontos (método)
local secondPart = Instance.new("Part")
secondPart.Parent = Workspace
print(secondPart.Parent) -- Workspace
secondPart:Destroy()
print(secondPart.Parent) -- nil

Definir métodos

Para criar um método em uma tabela, use o nome do método como a chave e a função do método como o valor. Na definição do método, o parâmetro self refere-se à tabela pai do método. Quando você chama um método usando a notação de dois pontos, você passa a tabela em si como o primeiro argumento. Você pode definir parâmetros para um método, mas precisa listá-los após o parâmetro self.

No exemplo a seguir, a tabela testButton tem um método como o valor da chave changeEnabled. Você pode verificar que self se refere à tabela pai do método imprimindo o valor de self.enabled.

local testButton = {
	enabled = true,
	changeEnabled = function(self, isEnabled)
		self.enabled = isEnabled
		print(self.enabled)
	end
}

print(testButton.enabled) -- true
-- Chame o método
testButton:changeEnabled(false) -- false

Callbacks

Callbacks são funções que são executadas em resposta a outra função ou processo.

Callbacks básicos

Funções podem ser passadas para outras funções, por exemplo, uma função anônima pode ser usada para implementar um callback que table.sort() então usa para classificar uma lista de Players de Players.GetPlayers().

local Players = game:GetService("Players")
local sortedPlayers = Players:GetPlayers()

table.sort(sortedPlayers, function(a, b)
	-- Use um callback anônimo para classificar jogadores por nome
	return a.Name < b.Name
end)

Na API do Roblox, callbacks referem-se a um membro de função somente para escrita, callbacks aguardam até retornarem. Callbacks amplamente utilizados incluem:

• MarketplaceService.ProcessReceipt, que lida com compras de produtos de desenvolvedor.
• BindableFunction.OnInvoke, que chama a função quando um script chama BindableFunction:Invoke(...).
• RemoteFunction.OnClientInvoke, que chama a função quando o servidor chama RemoteFunction:FireClient(player, ...) ou RemoteFunction:FireAllClients(...).
• RemoteFunction.OnServerInvoke, que chama a função quando um cliente chama RemoteFunction:InvokeServer(...).

Para definir um callback, atribua uma função a ele. Por exemplo, BindableFunction.OnInvoke é um callback de BindableFunction. Você pode definir uma função nomeada ou anônima para ele, e você pode chamar (invocar) essa função chamando o método :Invoke() no callback. Os argumentos que você passa para :Invoke() são encaminhados para o callback, e o valor de retorno da função callback retorna para o chamador de :Invoke().

local bindableFunction = Instance.new("BindableFunction")

bindableFunction.OnInvoke = function(number)
	return 2 * number
end

print(bindableFunction:Invoke(42)) -- 84

Técnicas de função

Manipuladores de eventos

Você pode atribuir uma função, conhecida como manipulador de eventos, para ser executada quando um evento é disparado. Por exemplo, você pode criar uma função chamada onPlayerAdded() para o evento Players.PlayerAdded para imprimir o nome de qualquer jogador que entrar. Para mais informações, veja Eventos.

local Players = game:GetService("Players")

local function onPlayerAdded(player)
	print(player.Name .. " entrou no jogo!")
end

Players.PlayerAdded:Connect(onPlayerAdded)

Funções anônimas

Você pode criar funções sem nomes, conhecidas como funções anônimas, para usar como callbacks e manipuladores de eventos. Assim como funções nomeadas, funções anônimas precisam começar e terminar com as palavras-chave function e end, mas você não precisa da palavra-chave local para indicar o escopo local porque elas sempre têm escopo local.

No exemplo a seguir, o callback para a função task.delay() e o manipulador de eventos para o evento Players.PlayerAdded são ambas funções anônimas.

-- Função anônima em um callback para task.delay()
task.delay(2, function(exactTimeElapsed)
	print(exactTimeElapsed) -- 2.0064592329945
end)

-- Função anônima em um manipulador de eventos
local Players = game:GetService("Players")
Players.PlayerAdded:Connect(function(player)
	print(player.Name .. " entrou no jogo!")
end)

Funções em scripts de módulo

Você pode reutilizar funções em vários scripts armazenando-as em ModuleScripts. Funções são um tipo de dado Luau, então você pode armazená-las em tabelas com outros dados.

Funções variádicas

Uma função variádica aceita qualquer número de argumentos. Por exemplo, Globals.LuaGlobals.print() é uma função variádica.

print(2, "+", 2, "=", 2 + 2) --2 + 2 = 4
print(string.format("O %s é um %s!", "bolo", "mentira")) -- O bolo é uma mentira!
print(string.char(115, 101, 99, 114, 101, 116)) -- secreto

Definir funções variádicas

Para definir uma função variádica, você usa o token ... como o último ou único parâmetro (não confundir com .., o operador de concatenação). Você pode colocar os valores ... em uma tabela para facilitar o uso.

local function variadic(named, ...)
	local arguments = {...} -- empacotar os argumentos extras em uma tabela
	print("Argumento nomeado =", named)
	for i, value in arguments do
		print("Entrada No.", i, "=", value)
	end
end

variadic(10, "Oi", 20, "Função Variádica")
--[[ Saída resultante:
Argumento nomeado = 10
Entrada No. 1 = Oi
Entrada No. 2 = 20
Entrada No. 3 = Função Variádica
]]

Encaminhar argumentos

Você pode definir funções variádicas como wrappers em torno de outras funções para passar, ou encaminhar, argumentos do wrapper para as outras funções.

local function printAround(functionToPrintAround, ...)
	print("Antes")
	functionToPrintAround(...)
	print("Depois")
end

local function addNumbers(x, y, z)
	print("x =", x)
	print("y + z =", y + z)
end

printAround(addNumbers, 1, 2, 3)
--[[ Saída resultante:
Antes
x = 1
y + z = 5
Depois
]]

Chamar uma função variádica com arrays

Se você quiser passar uma tabela de valores para uma função variádica global, como print(), você pode usar a função global unpack() para passar os valores da tabela em vez da tabela em si.

local squares = {1, 4, 9, 16, 25}
print("Os primeiros 5 números quadrados são:", unpack(squares))
-- Os primeiros 5 números quadrados são 1 4 9 16 25