Como fazer seu primeiro mod de Project Zomboid (B42)

Vamos fazer um mod pequeno, mas completo: uma sopaipilla (um salgado frito de massa típico do Chile) que dá para comer, com ícone e nome em espanhol e inglês, e que aparece nas geladeiras do mapa. É a mesma receita que usamos em mods reais como Melón con Vino, então o que você aprender aqui serve de verdade.

1. A estrutura de pastas

Dentro da sua pasta Zomboid/Workshop/ crie isto (os nomes importam, inclusive maiúsculas e minúsculas):

Zomboid/Workshop/
└── Sopaipillas/                      <- a pasta do projeto
    ├── workshop.txt                  <- dados para a Steam (passo 7)
    ├── preview.png                   <- imagem da Workshop
    └── Contents/
        └── mods/
            └── Sopaipillas/          <- o ID do mod
                └── 42/               <- arquivos para o Build 42
                    ├── mod.info
                    └── media/
                        ├── scripts/items/Sopaipillas.txt
                        ├── textures/Item_Sopaipilla.png
                        └── lua/
                            ├── server/Items/SopaipillasLoot.lua
                            └── shared/Translate/
                                ├── ES/ItemName.json
                                └── EN/ItemName.json

A pasta 42/ diz ao jogo que esses arquivos são para o Build 42. Alguns mods também têm uma pasta common/ para arquivos que servem em qualquer versão, mas ela não é obrigatória: nosso mod Terremoto funciona sem ela.

2. mod.info: a ficha do mod

name=Sopaipillas
id=Sopaipillas
description=Sopaipillas para comer en el apocalipsis. Build 42.
author=TuNombre
modversion=1.0.0
versionMin=42.0.0

• O id tem que ser único e igual ao nome da pasta que fica dentro de mods/.
• versionMin é a versão mínima do jogo que o seu mod precisa.
• Você pode adicionar poster=poster.png e icon=icon.png (dentro de 42/) para ele ficar bonito no menu de mods.

3. O item

media/scripts/items/Sopaipillas.txt:

module Sopaipillas
{
    imports
    {
        Base,
    }

    item Sopaipilla
    {
        DisplayName = Sopaipilla,
        DisplayCategory = Food,
        ItemType = base:food,
        Icon = Sopaipilla,
        Weight = 0.1,
        HungerChange = -12,
        UnhappyChange = -5,
        DaysFresh = 3,
        DaysTotallyRotten = 6,
        Calories = 250,
        Carbohydrates = 30,
        Lipids = 12,
        Proteins = 4,
    }
}

O que significa cada parte:

• module Sopaipillas é o sobrenome dos seus itens. Este vai se chamar Sopaipillas.Sopaipilla no jogo inteiro. Use um nome próprio e curto para não conflitar com outros mods.
• ItemType = base:food faz dele uma comida. Para um objeto qualquer, use base:normal.
• Icon = Sopaipilla procura a imagem textures/Item_Sopaipilla.png. O jogo coloca o Item_ na frente sozinho.
• HungerChange negativo tira fome. UnhappyChange negativo melhora o humor.
• DaysFresh e DaysTotallyRotten controlam quando ela fica velha e quando apodrece.

4. O ícone

Desenhe um PNG de 32×32 pixels com fundo transparente e salve como media/textures/Item_Sopaipilla.png. Se você não colocar um modelo 3D, o jogo também usa esse ícone para mostrar o item largado no chão.

5. O nome em cada idioma

Desde o Build 42, as traduções são arquivos JSON. media/lua/shared/Translate/ES/ItemName.json:

{
    "Sopaipillas.Sopaipilla": "Sopaipilla"
}

E EN/ItemName.json:

{
    "Sopaipillas.Sopaipilla": "Sopaipilla (fried dough)"
}

A chave é sempre Modulo.Item. Se quiser, crie também um PTBR/ItemName.json com o mesmo formato para os jogadores brasileiros. Mais detalhes em Traduções no B42.

6. Fazer aparecer no mundo (loot)

media/lua/server/Items/SopaipillasLoot.lua:

require "Items/ProceduralDistributions"

local function agregarLoot()
    local ok, err = pcall(function()
        local function meter(lista, peso)
            local dist = ProceduralDistributions.list[lista]
            if not dist or not dist.items then return end   -- se a lista não existir, não quebramos nada
            table.insert(dist.items, "Sopaipillas.Sopaipilla")
            table.insert(dist.items, peso)
        end
        meter("FridgeGeneric", 2)
        meter("FridgeTrailerPark", 3)
        meter("FridgeBreakRoom", 1)
    end)
    if not ok then print("[Sopaipillas] error en el loot: " .. tostring(err)) end
end

Events.OnPostDistributionMerge.Add(agregarLoot)

Cada contêiner do mapa tem uma lista de loot com pares de item e peso. Aqui adicionamos a sopaipilla a três listas de geladeiras. Tudo fica dentro de pcall para que, se algo der errado, o mod não derrube o carregamento do jogo. Explicação completa em Loot.

7. Testar no jogo

1. Abra o jogo com -debug (veja o guia anterior).
2. Em Mods, ative "Sopaipillas".
3. Comece um jogo novo.
4. No menu debug, abra Items List, procure "Sopaipilla" e adicione ao inventário.
5. Confira se ela tem ícone e nome, e coma.
6. Se algo não aparecer, abra Zomboid/console.txt e procure "Sopaipillas" ou "ERROR".

8. workshop.txt e publicação

version=1
title=Sopaipillas [B42]
description=Sopaipillas para comer en el apocalipsis.
tags=Build 42;Food
visibility=public

Coloque também um preview.png na pasta do projeto (quadrado, com menos de 1 MB). Depois, o envio é feito pelo próprio jogo: Publicar na Workshop.

E agora?

• Dê a ela um modelo 3D e uma receita para cozinhar: Itens e receitas.
• Se não funcionar: Erros comuns.