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).
- 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 por 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 um retorno
addOneAndTwo() -- 3
Parâmetros
Parâmetros são variáveis que você disponibiliza para a função e são usadas apenas no escopo da função. As 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 faltantes.
-- 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 termina a execução da função, e Luau espera que a palavra-chave end siga as instruções return, portanto, 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 objeto em si (self) como o primeiro argumento. Ao chamar 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 de uso comum, incluindo Instance:Destroy(), Instance:Clone(), e Instance:FindFirstChild().
A instrução table:Method() é funcionalmente idêntica a table.Method(table), e ao definir um método, function table:Method() é idêntico a function table.Method(self). Esse comportamento se estende aos métodos de Instance, uma vez que eles também são derivados de tabelas.
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, 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 refere-se à 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() utiliza 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. Os callbacks amplamente utilizados incluem:
- MarketplaceService.ProcessReceipt, que lida com as compras de produtos para desenvolvedores.
- 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 a ele, e pode chamar (invocar) essa função chamando o método :Invoke() no callback. Os argumentos que você passa para :Invoke() são enviados ao callback, e o valor de retorno da função callback retorna ao 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 evento
Você pode atribuir uma função, conhecida como manipulador de evento, 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 evento. 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 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 evento 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 evento
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.
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 deve ser confundido com .., o operador de concatenação). Você pode colocar os valores de ... em uma tabela para facilitar o uso.
O token variádico ... só pode ser usado dentro de funções definidas como variádicas; funções ou callbacks definidos dentro de uma função variádica não podem usar o mesmo ..., mesmo que sejam variádicas por si mesmas.
... não se comporta como uma variável normal e só pode ser passado para outras funções, retornado ou colocado em uma tabela.
local function variadic(named, ...)
local arguments = {...} -- empacota 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")
--[[ Resultado:
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)
--[[ Resultado:
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.