Este guia aborda a solução avançada de problemas com mods em servidores Project Zomboid hospedados na Legion Hosting. Se você ainda não instalou mods, comece pelo guia básico de instalação de mods primeiro. Este artigo aborda os problemas mais comuns relacionados a mods vistos nos tickets de suporte da Legion Hosting, incluindo corrupção do WorldDictionary, erros de formato de mods, conflitos de ordem de carregamento e incompatibilidade de versões entre servidor e cliente.

Antes de Começar

• Faça login no GPanel e selecione seu servidor Project Zomboid.
• Pare seu servidor antes de fazer qualquer alteração na configuração ou nos arquivos.
• Faça backup da pasta de salvamento do mundo (/.cache/saves/multiplayer/) via SFTP ou GPanel antes de tentar qualquer correção. Consulte o guia de SFTP se você não estiver familiarizado com transferência de arquivos.
• Tenha o caminho do arquivo .ini do seu servidor em mãos: /.cache/server/<servername>.ini (ex.: servertest.ini).

1. Erros de Formato de Mods (B42 vs B41)

O motivo mais comum para mods não carregarem é um formato incorreto na linha Mods= do arquivo .ini do seu servidor. Build 42 e Build 41 usam sintaxes diferentes, e misturá-las fará com que seus mods falhem silenciosamente ao carregar.

Formato B42 (Padrão Atual)

Build 42 requer um prefixo de barra invertida antes de cada Mod ID na linha Mods=:

Mods=\ModID1;\ModID2;\ModID3;

O formato DLMP combina Workshop IDs e Mod IDs com um separador de barra invertida:

Mods=2392987841\ModID1;1550458773\ModID2;2786383654\ModID3;

A linha WorkshopItems= usa o mesmo formato separado por ponto e vírgula em ambas as builds:

WorkshopItems=2392987841;1550458773;2786383654

Formato B41 (Legado)

Build 41 usa Mod IDs separados por ponto e vírgula simples, sem barra invertida:

Mods=ModID1;ModID2;ModID3

Como Corrigir

1. Abra /.cache/server/<servername>.ini no Gerenciador de Arquivos do GPanel.
2. Encontre a linha Mods= e verifique o formato comparando com os exemplos acima.
3. Se o formato estiver errado para a versão da sua build, corrija-o. Use o Organizador de Mods da Legion Hosting para gerar linhas formatadas corretamente de forma automática.
4. Salve o arquivo e inicie o servidor.

2. Corrupção do WorldDictionary

O WorldDictionary é um arquivo (WorldDictionary.bin) que mapeia nomes de itens para IDs numéricos internos. Quando mods são adicionados ou removidos, o dicionário pode ficar corrompido, fazendo com que o servidor trave na inicialização com um WorldDictionaryException.

Sintomas

• O console ou debug.log mostra WorldDictionaryException ou erros de WorldDictionary.
• O servidor trava imediatamente durante a inicialização, especificamente durante o carregamento do mundo.
• A falha começou após adicionar, remover ou atualizar mods.

Entendendo o Risco

Etapas de Recuperação

1. Pare seu servidor no GPanel.
2. Faça backup de toda a sua pasta de salvamento via SFTP: baixe o diretório completo /.cache/saves/multiplayer/<YourWorldName>/ para sua máquina local.
3. Primeiro, tente simplesmente reverter a alteração de mod que causou o erro. Se você acabou de adicionar um mod, remova-o tanto de Mods= quanto de WorkshopItems= no arquivo .ini. Se você acabou de remover um mod, adicione-o de volta. Inicie o servidor e veja se a falha foi resolvida.
4. Se reverter a alteração de mod não funcionar, conecte via SFTP e navegue até /.cache/saves/multiplayer/<YourWorldName>/.
5. Exclua WorldDictionary.bin.
6. Inicie o servidor. Project Zomboid regenerará o dicionário na inicialização.
7. Entre no servidor e inspecione o mundo em busca de itens corrompidos, veículos faltando ou inventários quebrados. Se o mundo estiver severamente danificado, restaure a partir do backup que você criou na etapa 2.

3. Conflitos do Mod Authentic Z

Authentic Z é uma das coleções de mods mais populares do Project Zomboid, mas é uma fonte frequente de tickets de suporte porque contém múltiplos sub-mods que conflitam entre si.

A Regra

Erros Comuns

• Adicionar tanto Authentic Z - Current quanto Authentic Z - Litemode ao mesmo tempo.
• Adicionar sub-mods do Authentic Z que são projetados para singleplayer junto com a versão multiplayer.
• Não perceber que diferentes sub-mods do Authentic Z compartilham o mesmo Workshop ID mas possuem Mod IDs diferentes, então o download do Workshop funciona mas o servidor carrega arquivos de mod conflitantes.

Como Corrigir

1. Abra /.cache/server/<servername>.ini no Gerenciador de Arquivos do GPanel.
2. Procure na linha Mods= por toda entrada contendo Authentic ou AuthenticZ.
3. Mantenha apenas um sub-mod do Authentic Z (recomendado: Authentic Z - Current). Remova todas as outras entradas do Authentic Z tanto das linhas Mods= quanto WorkshopItems=.
4. Salve o arquivo e reinicie o servidor.

4. Problemas de Diferenciação de Maiúsculas/Minúsculas no Linux

Os servidores da Legion Hosting rodam em Linux, onde nomes de arquivos e pastas são sensíveis a maiúsculas e minúsculas. Um arquivo chamado MyMod.lua e mymod.lua são tratados como dois arquivos completamente diferentes. Isso causa problemas quando autores de mods desenvolvem no Windows (que não diferencia maiúsculas/minúsculas) e seus mods contêm referências de arquivo com nomes incompatíveis.

Sintomas

• Um mod funciona perfeitamente no singleplayer no seu PC Windows, mas falha no servidor.
• O console ou debug.log mostra erros FileNotFoundException ou can't find file referenciando um script Lua ou textura dentro de um mod.
• O erro aponta para um arquivo que existe na pasta do mod, mas com capitalização diferente (ex.: o código referencia Items.txt mas o arquivo real se chama items.txt).

Como Diagnosticar

1. Verifique o console ou os arquivos de log em /.cache/Logs/ para o caminho exato do arquivo mencionado no erro.
2. Conecte via SFTP e navegue até a pasta do mod em /steamapps/workshop/content/108600/<WorkshopID>/.
3. Compare os nomes dos arquivos no disco com o nome do arquivo referenciado na mensagem de erro. Procure por diferenças de capitalização.

Como Corrigir

• Se você puder renomear o arquivo: Conecte via SFTP e renomeie o arquivo para corresponder à capitalização esperada pelo código do mod. Note que essa correção será sobrescrita se o mod for atualizado na Steam Workshop.
• Se o problema estiver no próprio mod: Reporte o bug ao autor do mod na página da Steam Workshop. Mencione que a referência do arquivo tem uma incompatibilidade de capitalização e que falha em servidores Linux. Muitos autores de mods não estão cientes da sensibilidade a maiúsculas/minúsculas do Linux.
• Como alternativa: Verifique os comentários na página da Workshop do mod — outros operadores de servidores Linux podem ter postado uma correção ou um fork compatível do mod.

5. Problemas de Ordem de Carregamento de Mods

Project Zomboid carrega os mods na ordem em que aparecem na linha Mods=. Alguns mods dependem de outros mods sendo carregados primeiro. Se uma dependência for carregada depois do mod que a requer, o mod dependente pode falhar silenciosamente ou causar erros.

Sintomas

• Funcionalidades do mod estão parcialmente funcionando — alguns itens ou sistemas de um mod estão presentes mas outros estão faltando.
• O console mostra erros NullPointerException ou attempt to index a nil value referenciando scripts Lua de um mod.
• Erros só aparecem quando uma combinação específica de mods está instalada, mas cada mod funciona bem individualmente.

Como Corrigir

1. Verifique a página da Steam Workshop de cada mod para uma seção de "Required Mods" ou "Load Order". Muitos autores de mods especificam quais mods devem ser carregados antes do deles.
2. Abra /.cache/server/<servername>.ini e encontre a linha Mods=.
3. Reordene as entradas para que mods de dependência apareçam antes dos mods que os requerem. Por exemplo, se o Mod B requer o Mod A, a linha deve ser Mods=\ModA;\ModB; (formato B42).
4. Mods de framework e biblioteca (como ModFramework, TsarLib ou Shark's Mod Utils) devem sempre ser listados primeiro na linha Mods=.
5. Salve o arquivo e reinicie o servidor.

6. Servidor Trava Após Adicionar Mods

Se seu servidor estava funcionando bem e trava após adicionar um ou mais mods, o novo mod é provavelmente a causa. Esta seção orienta como isolar o mod problemático.

Isolamento Passo a Passo

1. Pare o servidor no GPanel.
2. Abra /.cache/server/<servername>.ini no Gerenciador de Arquivos.
3. Anote todos os mods que você acabou de adicionar. Remova todos eles tanto das linhas Mods= quanto WorkshopItems=.
4. Inicie o servidor. Se ele iniciar com sucesso, o problema está em um dos mods que você removeu.
5. Adicione os mods de volta um por vez, reiniciando o servidor após cada adição. Quando o travamento retornar, o último mod que você adicionou é a causa.
6. Uma vez identificado, verifique a página da Workshop do mod para:
   • Uma nota sobre compatibilidade com B42 — muitos mods de B41 não foram atualizados para B42.
   • Conflitos conhecidos com outros mods que você está usando.
   • Mods de dependência necessários que você pode não ter instalado.

Lendo o Log de Travamento

Antes de realizar o processo de isolamento, verifique o log de travamento — ele frequentemente aponta diretamente para o mod problemático:

1. No GPanel, abra a aba Console e role até o final da saída.
2. Procure por linhas STACK TRACE, Exception ou ERROR.
3. As linhas imediatamente acima do stack trace tipicamente referenciam um nome de arquivo ou Mod ID — isso indica qual mod causou o travamento.
4. Para mais detalhes, abra o arquivo de log completo via SFTP em /.cache/Logs/ e verifique o arquivo DebugLog-server.txt ou debug.log mais recente.

7. Incompatibilidade de Versão de Mods (Servidor vs Cliente)

Project Zomboid requer que o servidor e todos os clientes conectados tenham a mesma versão de cada mod. Se um mod é atualizado na Steam Workshop e o servidor baixa a nova versão mas um jogador ainda tem a versão antiga em cache (ou vice-versa), falhas de conexão ou travamentos ocorrerão.

Sintomas

• Jogadores recebem um erro de "Mod mismatch" ou "Version mismatch" ao tentar conectar.
• Alguns jogadores conseguem conectar mas outros não — os que não conseguem conectar têm uma versão diferente do mod em cache localmente.
• O servidor estava funcionando bem, então um mod foi atualizado na Steam Workshop e de repente alguns jogadores não conseguem entrar.
• Jogadores veem texturas faltando, itens ausentes ou elementos de interface quebrados de mods que foram atualizados recentemente.

Correção para Operadores de Servidor

1. Pare o servidor no GPanel.
2. Inicie o servidor novamente. Na inicialização, o servidor baixa novamente as versões mais recentes de todos os mods da Workshop. Isso garante que o servidor esteja executando a versão mais nova.
3. Se o servidor ainda tiver uma versão antiga em cache, conecte via SFTP e exclua a pasta de cache da Workshop do mod específico em /steamapps/workshop/content/108600/<WorkshopID>/. Reinicie o servidor para forçar um download limpo.

Correção para Jogadores

Jogadores que não conseguem conectar devido a incompatibilidades de versão de mods devem:

1. Abrir o Steam e navegar até Library → Project Zomboid.
2. Clicar com o botão direito em Project Zomboid, selecionar Properties → Local Files → Verify Integrity of Game Files.
3. Também navegar até a pasta da Steam Workshop para Project Zomboid em sua máquina local e excluir os arquivos de mod em cache para forçar um novo download.
4. Iniciar o jogo e conectar ao servidor novamente.

8. Limpando o Cache da Steam Workshop

Se múltiplos problemas com mods persistirem e você suspeitar que o cache de download da Workshop está corrompido, você pode forçar um novo download completo de todos os mods da Workshop.

1. Pare o servidor no GPanel.
2. Conecte via SFTP e navegue até /steamapps/workshop/.
3. Exclua toda a pasta workshop/ (ou seu conteúdo).
4. Inicie o servidor. O Steam baixará novamente todos os itens da Workshop do zero.
5. Observe o Console do GPanel para confirmar que todos os mods terminaram de baixar antes que o servidor comece a carregar o mundo.

Referência Rápida de Diagnóstico

Ainda Tendo Problemas com Mods?