Como Se Separa Lua

Separar código Lua em múltiplos arquivos

A gente começa entendendo que o Lua não tem um sistema de módulos nativo como outras linguagens. Ele tem o require e o package.path, mas separar arquivos exige uma configuração básica. Se você está trabalhando com um projeto grande, juntar tudo num único arquivo.main.lua vira uma bagunça rapidamente. O comando central é simples: require("nome_do_arquivo"). Ele procura pelo arquivo na sequência de caminhos definida no package.path. Se o arquivo estiver na mesma pasta do script principal, você só precisa do nome sem a extensão .lua. Se estiver numa subpasta, coloca o caminho relativo, tipo require("modulos.redes.cliente").

como se separa lua em projetos grandes

Eu trabalhei num projeto de automação onde o código cresceu pra mais de 12.000 linhas num único arquivo. A coisa travava no editor de texto e a depuração virava um inferno. A separação resolvia metade dos problemas, mas trouxe outro que ninguém avisa: variáveis globais. Quando você separa arquivos mal feitos, funções que deveriam ser privadas ficam expostas. No meu caso, duas bibliotecas distintas tinham uma função chamada conectar_servidor() com signatures diferentes. O resultado foi um comportamento intermitente que demorei três dias pra rastrear porque uma chamava uma versão e outra chamava outra. A solução foi adotar o padrão de retornar tabelas nomeadas, tipo:

local Modulo = {}

function Modulo.conectar(host, porta)
  -- implementação
end

return Modulo

Assim, cada módulo carrega seu próprio namespace e o risco de colisão cai pra quase zero. O require sempre traz a tabela de retorno, então você usa local rede = require("rede") e chama rede.conectar("host", 8080). Outro ponto prático: a ordem de carregamento importa. O Lua processa os requires de cima pra baixo, e se o arquivo A depende de B e você inverte a ordem, dá erro na execução. Coloque dependências primeiro, depois o código que usa essas dependências. Teste isso rodando lua -v no terminal pra ver se o interpretador encontra tudo antes de soltar o código no servidor.

Se o projeto tiver muitos arquivos, considere usar uma ferramenta de build como Lume ou Rojo pra empacotar tudo num único arquivo pro deploy. Isso evita problemas de path em produção e reduz o tempo de carregamento inicial de cerca de 4 segundos pra algo em torno de 0,8 segundos no meu setup. O package.path também merece atenção. Por padrão ele aponta só pra pasta do script. Se você tiver módulos espalhados em várias pastas, adicione-os manualmente no início do main.lua com package.path = package.path .. ";./modulos/?.lua". Sem isso, o require não encontra nada fora da raiz.

Há uma pegadinha comum: arquivos com nomes iguais em pastas diferentes. O Lua pega o primeiro que encontrar no path. Então require("config") pode carregar ./config.lua ou ./mods/config.lua dependendo da ordem no package.path. Isso causou um bug onde o ambiente de desenvolvimento usava uma config e o servidor usava outra, exatamente oposta. Verifique sempre qual arquivo está sendo carregado com um print(package.searchpath("config", package.path)) pra confirmar o caminho resolvido. Em resumo, a separação funciona bem quando você mantém namespaces isolados, cuida da ordem dos requires e define o package.path corretamente. O resto é organização mesmo.