Introdução a scripts de módulo

À medida que os projetos se tornam complexos, é importante pensar em como os scripts estão organizados. Boas práticas de organização podem garantir que o código não seja duplicado entre scripts ou se torne difícil de gerenciar.

Uma maneira melhor de organizar e reutilizar código é com scripts de módulo, um tipo exclusivo de script que armazena um conjunto de funções e variáveis projetadas para atender a um propósito compartilhado, como gerenciar dinheiro de jogadores ou inimigos. O código dentro dos scripts de módulo pode ser utilizado por outros scripts. Assim, você pode chamar a mesma função que dá moedas de vários scripts diferentes sempre que um jogador termina uma missão ou encontra um item.

Ao armazenar código comumente usado em scripts de módulo, a manutenção e a organização do código se tornam mais fáceis, uma vez que as alterações precisam ser feitas apenas em um script de módulo, em vez de atualizar vários scripts.

Noções básicas do script de módulo

Os scripts de módulo são, na verdade, seus próprios objetos separados em comparação com os objetos de script. No Roblox, os scripts de módulo podem ser identificados com um ícone roxo.

Criar um script de módulo

Os ModuleScripts são comumente colocados no ServerScriptService quando usados por scripts do lado do servidor e no ReplicatedStorage quando usados por scripts locais do lado do cliente (como interações de GUI).

1. Crie um ModuleScript em ServerScriptService.

Estrutura dos scripts de módulo

Quando criados, todos os scripts de módulo começam com o código abaixo:

local Module = {}

return Module

A linha local Module = {} cria uma tabela, ou contêiner de código, onde as funções e variáveis compartilhadas do módulo podem ser armazenadas. Esta tabela deve ser renomeada para o propósito do módulo, como RewardManager ou ParticleController. Ao contrário de outras variáveis que são em camel case (myVariable), as tabelas de módulo são recomendadas para usar pascal case e começar com letra maiúscula (MyModule).

local RewardManager = {}

return RewardManager

Para que outros scripts possam usar as funções ou variáveis não locais de um módulo, cada módulo termina com return MyModule. Sempre que outro script tenta obter código do módulo, o return permite que esse script acesse o código armazenado dentro da tabela do módulo.

Adicionar aos scripts de módulo

Para adicionar uma função ou variável ao módulo que pode ser utilizada em outro script, digite o nome da tabela do módulo, seguido de um ponto, e o nome da função ou variável, como em TestModule.myVariable. Usar o operador de ponto é outra maneira de adicionar código em uma tabela, permitindo que outros scripts acessem esse código sempre que a tabela do módulo for retornada.

local TestModule = {}

-- Adiciona uma variável à tabela 'TestModule'
TestModule.myVariable = 100

-- Adiciona uma função à tabela 'TestModule'
function TestModule.doTask(player)
	-- Código de exemplo
end

return TestModule

Escopo em scripts de módulo

Para que uma função ou variável de módulo seja usada em um script externo, não digite local.

Digitar local na frente de variáveis e funções significa que elas são apenas utilizáveis naquele script. Embora esta seja uma boa prática para a maioria dos scripts para reduzir erros e facilitar a solução de problemas, você não pode tornar funções e variáveis de scripts de módulo locais.

Qualquer código usado apenas por aquele script de módulo deve ainda incluir local. Por exemplo, o código abaixo inclui a variável local difficultyModifier, que só pode ser usada naquele script de módulo, e a função getCoinReward(), que pode ser usada em scripts fora do módulo.

local RewardManager = {}

-- Usável apenas no script de módulo
local rewardCoins = 50

-- Usável apenas no script de módulo
local difficultyModifier = {
	easy = 0.5,
	normal = 1,
	hard = 2
}

-- Usável em outros scripts
function RewardManager.getCoinReward(difficulty)
	local coins = difficultyModifier[difficulty] * rewardCoins
	return coins
end

return RewardManager

Usar módulos em outros scripts

Sozinho, um script de módulo não pode executar código — ele precisa ser carregado em outro script usando a palavra-chave require(). A função require() aceita um argumento, o local do script de módulo no Explorer.

Para usar um módulo, em um script separado, defina uma variável igual a require(moduleScript).

local MyModule = require(ServerStorage.ModuleScript)

Agora, a variável MyModule contém a tabela do módulo criada naquele script de módulo. Para usar funções e variáveis dessa tabela, digite o nome da variável, seguido de um ponto, e o nome exato do que usar naquele script de módulo, como MyModule.myFunction(). Quando o script é executado e chega a essa linha, ele acessa aquela função ou variável específica armazenada na tabela do módulo.

local MyModule = require(ServerStorage.ModuleScript)

MyModule.myFunction()

Exemplo RewardManager

ModuleScript - RewardManager
local RewardManager = {}

-- Usável apenas no script de módulo
local rewardCoins = 50

-- Usável apenas no script de módulo
local difficultyModifier = {
 easy = 0.5,
 normal = 1,
 hard = 2
}

-- Usável em outros scripts
function RewardManager.getCoinReward(difficulty)
 local coins = difficultyModifier[difficulty] * rewardCoins
 return coins
end

return RewardManager

Script - TreasureChestScript
local ServerStorage = game:GetService("ServerStorage")

-- Carrega o script de módulo
local RewardManager = require(ServerStorage.RewardManager)

-- Chama a função do script de módulo
local coins = RewardManager.getCoinReward("easy")
print("Deve recompensar " .. coins .. " moedas")

Solução de problemas geral

Algumas das dicas aqui abordam problemas comuns ao trabalhar com scripts de módulo. Lembre-se de que os scripts de módulo podem ser um tópico complicado com mais nuances. Para mais detalhes, consulte este guia mais técnico sobre Scripts de Módulo.

Problema: Recebo uma mensagem de erro incluindo: "Infinite yield possible" ou "not a valid member".

• Verifique a ortografia do script de módulo onde está sendo carregado. require() deve incluir o caminho exato e a ortografia do script de módulo, que pode ter um nome diferente da tabela do módulo.

Problema: Recebo uma mensagem de erro incluindo: "attempt to index global".

• Em qualquer script que utilize um script de módulo, certifique-se de que ele está carregado usando a função require(). Caso contrário, esse script não poderá usar funções e variáveis do script de módulo.

Resumo

Scripts de módulo no Roblox são um método que codificadores usam para organizar e reutilizar código. Um script de módulo é frequentemente armazenado no ServerStorage (ou ReplicatedStorage para interações baseadas em cliente). A partir daí, outros scripts conseguem chamar funções e variáveis armazenadas naquele script de módulo.

Por exemplo, uma experiência pode recompensar jogadores por coletar objetos. Um script de módulo pode lidar com o código para dar pontos. Assim, scripts para diferentes tipos de objetos podem apenas chamar a função do script de módulo. Isso reduz a necessidade de reutilizar código entre scripts, tornando o código mais fácil de entender e manter.