Este guia aborda a resolução avançada de problemas com mods para servidores de Project Zomboid alojados na Legion Hosting. Se ainda não instalou mods, comece pelo guia básico de instalação de mods primeiro. Este artigo aborda os problemas mais comuns relacionados com mods encontrados nos tickets de suporte da Legion Hosting, incluindo corrupção do WorldDictionary, erros de formato de mods, conflitos de ordem de carregamento e incompatibilidades de versão entre servidor e cliente.

Antes de Começar

• Inicie sessão no GPanel e selecione o seu servidor de Project Zomboid.
• Pare o seu servidor antes de fazer quaisquer alterações de configuração ou ficheiros.
• Faça uma cópia de segurança da pasta do seu mundo (/.cache/saves/multiplayer/) via SFTP ou GPanel antes de tentar qualquer correção. Consulte o guia de SFTP se não estiver familiarizado com transferências de ficheiros.
• Tenha o caminho do ficheiro .ini do seu servidor pronto: /.cache/server/<servername>.ini (ex.: servertest.ini).

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

A razão mais comum para os mods não carregarem é um formato incorreto na linha Mods= do ficheiro .ini do seu servidor. A Build 42 e a Build 41 utilizam sintaxes diferentes, e misturá-las fará com que os mods não carreguem silenciosamente.

Formato B42 (Padrão Atual)

A 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= utiliza o mesmo formato separado por ponto e vírgula em ambas as builds:

WorkshopItems=2392987841;1550458773;2786383654

Formato B41 (Legado)

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

Mods=ModID1;ModID2;ModID3

Como Corrigir

1. Abra /.cache/server/<servername>.ini no Gestor de Ficheiros do GPanel.
2. Encontre a linha Mods= e verifique o formato comparando com os exemplos acima.
3. Se o formato estiver errado para a sua versão de build, corrija-o. Utilize o Legion Hosting Mod Organizer para gerar linhas formatadas corretamente de forma automática.
4. Guarde o ficheiro e inicie o servidor.

2. Corrupção do WorldDictionary

O WorldDictionary é um ficheiro (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, causando o crash do servidor no arranque com um WorldDictionaryException.

Sintomas

• A consola ou o debug.log mostra WorldDictionaryException ou erros de WorldDictionary.
• O servidor crasha imediatamente durante o arranque, especificamente durante o carregamento do mundo.
• O crash começou após adicionar, remover ou atualizar mods.

Compreender o Risco

Passos de Recuperação

1. Pare o seu servidor no GPanel.
2. Faça uma cópia de segurança de toda a pasta de save via SFTP: descarregue o diretório completo /.cache/saves/multiplayer/<YourWorldName>/ para a sua máquina local.
3. Primeiro, tente simplesmente reverter a alteração de mod que causou o erro. Se acabou de adicionar um mod, remova-o tanto de Mods= como de WorkshopItems= no ficheiro .ini. Se acabou de remover um mod, adicione-o novamente. Inicie o servidor e verifique se o crash foi resolvido.
4. Se reverter a alteração de mod não funcionar, conecte-se via SFTP e navegue até /.cache/saves/multiplayer/<YourWorldName>/.
5. Elimine WorldDictionary.bin.
6. Inicie o servidor. O Project Zomboid irá regenerar o dicionário no arranque.
7. Entre no servidor e inspecione o mundo em busca de itens corrompidos, veículos desaparecidos ou inventários com problemas. Se o mundo estiver severamente danificado, restaure a partir da cópia de segurança criada no passo 2.

3. Conflitos do Mod Authentic Z

O 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 entram em conflito entre si.

A Regra

Erros Comuns

• Adicionar tanto Authentic Z - Current como Authentic Z - Litemode ao mesmo tempo.
• Adicionar sub-mods do Authentic Z que são destinados a singleplayer juntamente com a versão multijogador.
• Não perceber que diferentes sub-mods do Authentic Z partilham o mesmo Workshop ID mas têm Mod IDs diferentes, então o download do Workshop é bem-sucedido mas o servidor carrega ficheiros de mod em conflito.

Como Corrigir

1. Abra /.cache/server/<servername>.ini no Gestor de Ficheiros do GPanel.
2. Procure na linha Mods= todas as entradas que contenham 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 da linha Mods= como da linha WorkshopItems=.
4. Guarde o ficheiro e reinicie o servidor.

4. Problemas de Sensibilidade a Maiúsculas/Minúsculas no Linux

Os servidores da Legion Hosting funcionam em Linux, onde os nomes de ficheiros e pastas são sensíveis a maiúsculas/minúsculas. Um ficheiro chamado MyMod.lua e mymod.lua são tratados como dois ficheiros completamente diferentes. Isto causa problemas quando os autores de mods desenvolvem no Windows (insensível a maiúsculas/minúsculas) e os seus mods contêm referências de ficheiros com capitalização incorreta.

Sintomas

• Um mod funciona perfeitamente em singleplayer no seu PC Windows mas falha no servidor.
• A consola ou o 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 ficheiro que existe na pasta do mod, mas com capitalização diferente (ex.: o código referencia Items.txt mas o ficheiro real chama-se items.txt).

Como Diagnosticar

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

Como Corrigir

• Se puder renomear o ficheiro: Conecte-se via SFTP e renomeie o ficheiro para corresponder à capitalização esperada pelo código do mod. Note que esta correção será substituída se o mod for atualizado no Steam Workshop.
• Se o problema estiver no mod: Reporte o bug ao autor do mod na página do Steam Workshop. Mencione que a referência do ficheiro 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 da página do Workshop do mod — outros operadores de servidores Linux podem ter publicado uma correção ou um fork compatível do mod.

5. Problemas de Ordem de Carregamento de Mods

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

Sintomas

• As funcionalidades do mod estão parcialmente a funcionar — alguns itens ou sistemas de um mod estão presentes mas outros estão em falta.
• A consola mostra erros NullPointerException ou attempt to index a nil value referenciando scripts Lua de um mod.
• Os 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 do Steam Workshop de cada mod para uma secção de "Required Mods" ou "Load Order". Muitos autores de mods especificam quais mods devem ser carregados antes do seu.
2. Abra /.cache/server/<servername>.ini e encontre a linha Mods=.
3. Reordene as entradas para que os 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 ser sempre listados primeiro na linha Mods=.
5. Guarde o ficheiro e reinicie o servidor.

6. O Servidor Crasha Após Adicionar Mods

Se o seu servidor estava a funcionar bem e crasha após adicionar um ou mais mods, o novo mod é provavelmente a causa. Esta secção explica como isolar o mod problemático.

Isolamento Passo a Passo

1. Pare o servidor no GPanel.
2. Abra /.cache/server/<servername>.ini no Gestor de Ficheiros.
3. Anote todos os mods que acabou de adicionar. Remova todos eles tanto da linha Mods= como da linha WorkshopItems=.
4. Inicie o servidor. Se iniciar com sucesso, o problema está num dos mods que removeu.
5. Adicione os mods de volta um de cada vez, reiniciando o servidor após cada adição. Quando o crash voltar, o último mod que adicionou é a causa.
6. Uma vez identificado, verifique a página do 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 está a utilizar.
   • Mods de dependência necessários que pode não ter instalado.

Ler o Log de Crash

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

1. No GPanel, abra o separador Console e desloque-se até ao final do output.
2. Procure linhas com STACK TRACE, Exception ou ERROR.
3. As linhas imediatamente acima do stack trace tipicamente referenciam um nome de ficheiro ou Mod ID — isto indica qual mod provocou o crash.
4. Para mais detalhe, abra o ficheiro de log completo via SFTP em /.cache/Logs/ e verifique o ficheiro DebugLog-server.txt ou debug.log mais recente.

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

O Project Zomboid requer que o servidor e todos os clientes conectados tenham a mesma versão de cada mod. Se um mod for atualizado no Steam Workshop e o servidor descarregar a nova versão mas um jogador ainda tiver a versão antiga em cache (ou vice-versa), ocorrerão falhas de conexão ou crashes.

Sintomas

• Os jogadores recebem um erro de "Mod mismatch" ou "Version mismatch" ao tentar conectar-se.
• Alguns jogadores conseguem conectar-se mas outros não — os que não conseguem têm uma versão diferente do mod em cache localmente.
• O servidor estava a funcionar bem, depois um mod foi atualizado no Steam Workshop e de repente alguns jogadores não conseguem entrar.
• Os jogadores veem texturas em falta, itens em falta ou elementos de UI com problemas de mods que foram recentemente atualizados.

Correção para Operadores de Servidor

1. Pare o servidor no GPanel.
2. Inicie o servidor novamente. No arranque, o servidor volta a descarregar as versões mais recentes de todos os mods do Workshop. Isto garante que o servidor está a executar a versão mais recente.
3. Se o servidor ainda tiver uma versão antiga em cache, conecte-se via SFTP e elimine a pasta de cache do 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-se 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. Navegar também até à pasta do Steam Workshop para Project Zomboid na sua máquina local e eliminar os ficheiros de mods em cache para forçar um novo download.
4. Iniciar o jogo e conectar-se ao servidor novamente.

8. Limpar a Cache do Steam Workshop

Se múltiplos problemas de mods persistirem e suspeitar que a cache de downloads do Workshop está corrompida, pode forçar um novo download completo de todos os mods do Workshop.

1. Pare o servidor no GPanel.
2. Conecte-se via SFTP e navegue até /steamapps/workshop/.
3. Elimine toda a pasta workshop/ (ou o seu conteúdo).
4. Inicie o servidor. O Steam irá descarregar novamente todos os itens do Workshop do zero.
5. Observe a Consola do GPanel para confirmar que todos os mods terminaram de descarregar antes do servidor começar o carregamento do mundo.

Referência Rápida de Diagnóstico

Ainda Tem Problemas com Mods?