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 único de script que armazena um conjunto de funções e variáveis projetadas para atender a um propósito compartilhado, como gerenciar o dinheiro dos jogadores ou inimigos. O código dentro dos scripts de módulo pode ser usado 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, torna-se mais fácil manter e organizar o código, 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 sobre scripts de módulo

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

Criar um script de módulo

Os ModuleScripts são comumente colocados em ServerScriptService quando usados por scripts do lado do servidor e 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 escritas 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 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 a scripts de módulo

Para adicionar uma função ou variável ao módulo que pode ser usada 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 a 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 por aquele script. Embora essa seja uma boa prática para a maioria dos scripts para reduzir erros e 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 ainda deve 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

Por si só, 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, a localização 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 acessará aquela função ou variável específica armazenada na tabela do módulo.

local MyModule = require(ServerStorage.ModuleScript)

MyModule.myFunction()

Exemplo de 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

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 premiar " .. coins .. " moedas")

Solução de problemas gerais

Algumas das dicas aqui abordam problemas comuns ao trabalhar com scripts de módulo. Lembre-se de que 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: Receber uma mensagem de erro incluindo: "Possível yield infinito" ou "não é um membro válido".

• Verifique a ortografia do script de módulo onde ele é 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: Receber uma mensagem de erro incluindo: "tentativa de indexar global".

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

Resumo

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

Por exemplo, um jogo pode premiar pontos aos jogadores por coletar objetos. Um script de módulo pode lidar com o código para dar pontos. Então, 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.