Tutorial de Criação de MOD e API Lua

1. Início Rápido

1.1 O que é um MOD?

Um MOD é um pacote de conteúdo criado por jogadores que modifica os atributos, habilidades, skins e propriedades de hitbox das criaturas. O jogo inclui dois MODs de exemplo — DemoCharacterMod e DemoSkinsMod — localizados no diretório de MODs do jogo (veja o caminho acima). Copie e modifique-os para começar rapidamente.

1.2 Localização do Diretório de MODs

1.3 Estrutura do Diretório de MODs

Mods/
├── DemoCharacterMod/           ← Exemplo completo (atributos+habilidades+hitbox+skin)
│   ├── mod.json                ← Manifesto do MOD
│   ├── preview.jpg             ← Imagem de pré-visualização
│   ├── CharacterAsset/
│   │   └── allo.txt            ← Configuração do Alossauro (todos os 4 tipos)
│   └── SkinsAsset/
│       └── Crooked mouth.png   ← Textura da skin
│
├── DemoSkinsMod/               ← Exemplo de MOD somente de skin
│   ├── mod.json
│   ├── preview.jpg
│   └── SkinsAsset/
│       ├── allo_deser_allo.txt ← Script de skin
│       └── deser_allo.png      ← Textura da skin
│
└── MyFirstMod/                 ← Diretório raiz do seu MOD
    ├── mod.json
    └── CharacterAsset/
        └── allo.txt

1.4 Criando o mod.json

{
  "Name": "MyFirstMod",
  "Author": "Seu Nome",
  "Version": "1.0",
  "SupportedVersion": "0.6.*",
  "Priority": 0,
  "Description": "Meu primeiro MOD",
  "PreviewImagePath": "preview.jpg",
  "Tags": "Character"
}

1.5 A Interface de MOD no Jogo em Resumo

Na tela de login, clique em Gerenciamento de MOD para abrir a interface de MOD. Ela tem três abas — MODs Locais, Workshop, Gerenciar MODs — além dos botões Criar MOD e Definir Diretório, cobrindo toda a jornada do autor, da criação ao teste.

1.6 Crie Seu MOD (Recomendado para Iniciantes)

O jogo tem uma ferramenta integrada de criação de MOD — sem criar pastas manualmente:
① Faça login (criar um MOD exige login; o MOD fica vinculado à sua conta).
② Gerenciamento de MOD → clique em Criar MOD.
③ Preencha o nome (apenas letras/dígitos/sublinhado/hífen, 1–64 caracteres), autor, versão, versão suportada, descrição, tags, e escolha um modelo.
④ Clique em Criar — o sistema gera a estrutura do diretório (mod.json mais a pasta de script de exemplo do modelo).
⑤ O MOD aparece então na aba Gerenciar MODs como rascunho, ainda não na lista de carregamento local.

1.7 Editar e Pré-visualizar

① Encontre seu MOD em Gerenciar MODs. Se você usou "Definir Diretório", o MOD é sincronizado para essa pasta externa e pode ser aberto direto em um editor de texto; caso contrário, edite os scripts Lua (CharacterAsset/*.txt, etc.), PNGs de skin e o preview.jpg dentro da pasta dele no diretório de MOD do jogo.
② Use o botão Editar na linha para mudar versão, versão suportada, descrição e tags (o nome fica bloqueado).
③ Ao terminar, clique em Pré-visualizar para enviar o rascunho à lista de carregamento de MODs Locais.

1.8 Testar no Jogo (Ciclo de Desenvolvimento do Autor)

1. Criar: Gerenciamento de MOD → Criar MOD → escolha um modelo → Criar (gera um rascunho; veja 1.6).
2. Editar: edite os scripts e metadados em Gerenciar MODs (veja 1.7).
3. Pré-visualizar: clique em Pré-visualizar para mover o rascunho à lista de carregamento de MODs Locais.
4. Ativar: mude para MODs Locais, confirme que o status é "Ativado" (verde) e "Versão Suportada" está verde (vermelho significa incompatível com a versão atual do jogo — ajuste SupportedVersion).
5. Testar: entre no modo single-player ou crie uma sala — os atributos/habilidades/skins modificados entram em vigor imediatamente.
6. Iterar: volte a Gerenciar MODs e edite os scripts → crie uma sala Host local para atualizar a cópia de prévia com o rascunho mais recente → volte à partida para verificar. Depois de ativar a Prévia Sincronizada uma vez, não é preciso reiniciar o jogo nem ativá-la novamente.
7. Distribuir: quando satisfeito, use Exportar para gerar um arquivo .mod e compartilhar; no Steam você também pode Enviar ao Workshop para publicar.

1.9 Modo de Prévia Sincronizada (teste de desenvolvimento)

Prévia Sincronizada em Gerenciar MODs cria uma cópia de execução separada do rascunho e a registra na lista de carregamento local. A fonte de autoria continua no diretório de Gerenciar MODs; a prévia sincronizada não publica nem envia o MOD ao Workshop.

1.10 Exportar .mod (compartilhamento e instalação)

Exportar empacota a cópia de trabalho atual de Gerenciar MODs em um arquivo compactado .mod e abre o seletor de local de salvamento do sistema. O pacote tem como raiz o diretório que contém mod.json e inclui scripts, imagens e os demais arquivos do MOD. Exportar não ativa a prévia, não altera o rascunho, não torna o MOD público nem o envia ao Workshop.

1. Autor: em Gerenciar MODs, clique em Exportar, salve o arquivo .mod pelo seletor do sistema e envie-o aos testadores ou jogadores.
2. Destinatário: na aba MODs Locais, clique em Importar MOD, selecione o .mod recebido (ou um .zip compatível) e confirme que ele aparece e está ativado na lista de carregamento local.
3. Multijogador: antes de entrar ou criar uma sala com MOD, todos devem usar o mesmo conteúdo, versão e estado de ativação do MOD. Um pacote exportado não substitui a publicação no Workshop.

2. MOD de Atributos de Personagem

Crie um arquivo .txt no diretório CharacterAsset/ e defina uma tabela CharacterAsset para modificar os atributos das criaturas. Campos omitidos mantêm os valores originais. Abaixo está o allo.txt completo do DemoCharacterMod incluído, mostrando todos os campos disponíveis.

2.1 Exemplo Completo (allo.txt do DemoCharacterMod)

-- Configuração completa de atributos do Alossauro (*não exclua os itens abaixo)
CharacterAsset = {
    name    = "Alossauro",      -- Nome de exibição
    enable  = true,            -- Ativar criatura
    jump    = false,           -- Permitir salto (requer animação correspondente)
    race    = "allo",          -- Tag de raça (*obrigatório, chave única de correspondência)
    ropoda  = 0,               -- Tipo de ninho (-1=nenhum, 0=terópode, 1=saurópode, 2=ornitísquio)
    ropode  = 0,               -- Tipo de ovo (-1=nenhum, 0=terópode, 1=saurópode, 2=ornitísquio)
    volume  = 2,               -- Classe de tamanho 0~5 (leve→super)
    rank    = 7,               -- Classificação por estrelas 0~12 (nível S1~SS)
    branch  = 3,               -- Classificação de família 0~25
    habit   = 0,               -- Hábito (0=terrestre, 1=hidrófilo, 2=réptil marinho, 3=aquático, 4=anfíbio, 5=voador)
    type    = 0,               -- Categoria (0=carnívoro, 1=herbívoro, 2=aquático, 3=artrópode, 4=mamífero, 5=voador)
    taste   = 0,               -- Dieta (0=carnívoro, 1=flores, 2=folhas, 3=onívoro)
    spawn   = 0,               -- Reprodução (0=ovíparo, 1=vivíparo)
    health  = 26503.0,         -- Vida máxima
    hunger  = 12227.0,         -- Fome máxima
    water   = 3128.0,          -- Água máxima
    oxygen  = 474.0,           -- Oxigênio máximo
    stamina = 100.0,           -- Estamina máxima
    attack  = 2802.0,          -- Dano de ataque base
    defend  = 779.0,           -- Defesa base
    pen     = 5,               -- Nível de penetração 0~10
    ten     = 3,               -- Nível de tenacidade 0~10
    restore = 266.0,           -- Taxa de recuperação natural
    consume = 100.0,           -- Consumo de cruzeiro
    weight  = 3600.0,          -- Peso corporal (kg)
    speed   = 27.01,           -- Velocidade de caminhada (km/h)
    swim    = 13.5,            -- Velocidade de natação (km/h)
    flying  = 0.0,             -- Velocidade de voo (km/h)
    runSpeed    = 54.01,       -- Velocidade de corrida (km/h)
    turnSpeed   = 0.61,        -- Taxa de giro (graus/seg)
    growtime    = 1560.0,      -- Tempo para atingir a fase adulta (segundos)
    ovumtime    = 1080.0,      -- Intervalo de geração de ovos (segundos)
    hatching    = 2210.0,      -- Tempo de incubação (segundos)
    safe        = 1800.0,      -- Período de proteção juvenil (segundos)
    skill   = "LifeDrain,3;",  -- Habilidade EX inata
    gene    = "",              -- Gene inato
}

2.2 Classificação e Identidade

2.3 Sobrevivência e Combate

2.4 Velocidade de Movimento (km/h)

2.5 Parâmetros de Tempo

2.6 Eficiência dos Órgãos (0.0 ~ 1.0)

2.7 Dimensões Corporais e Características Inatas

3. MOD de Habilidades

Use a tabela CharacterSkill para modificar as habilidades de ataque das criaturas. Cada habilidade é definida como um par chave-valor (as chaves podem ser nomeadas livremente). Pode ser combinada com CharacterAsset no mesmo arquivo .txt.

3.1 Exemplo Completo (do DemoCharacterMod)

CharacterSkill = {
    attack1 = {
        Race         = "allo",      -- *Obrigatório* tag de raça
        AttackOrder  = 1,           -- Índice do slot de ataque (1=boca1, 2=boca2...)
        AttackType   = 0,           -- Tipo de ataque 0~7 (veja enum abaixo)
        DamageMode   = 0,           -- Modo de dano 0~2 (veja enum abaixo)
        Area         = nil,         -- Áreas permitidas: nil=qualquer, {0,1}=apenas terra+raso
        AttackRange  = 1.0,         -- Raio de colisão (metros)
        Modify       = 2.0,         -- Multiplicador de dano (1=sem alteração)
        UseStamina   = 0.01,        -- Porcentagem de custo de estamina (0=padrão)
        TriggerSkill = "Scars,2;",  -- Habilidade acionada ao acertar (formato: "Nome,Nível;")
    },
    attack2 = {
        Race         = "allo",
        AttackOrder  = 2,
        AttackType   = 1,           -- Cauda
        DamageMode   = 1,           -- AOE (dano em área)
        AttackRange  = 3.0,
        Modify       = 0.8,
        UseStamina   = 0.03,
        TriggerSkill = "Blood,2;",
    },
}

3.2 Enum AttackType (Tipo de Ataque)

3.3 Enum DamageMode (Modo de Dano)

3.4 Enum Area (Área)

4. MOD de Hitbox

Use a tabela CharacterHitGroup para modificar a taxa de penetração de armadura e o multiplicador de dano de cada parte do corpo — crie pontos fracos ou armadura reforçada.

4.1 Constantes de Partes do Corpo

4.2 Exemplo (do DemoCharacterMod)

CharacterHitGroup = {
    head = {
        Race              = "allo",
        PartType          = BODY_HEAD,
        PenetrationRate   = 0.6,    -- 0~1 (maior = mais fácil de penetrar)
        DamageMultiplier  = 1.5,    -- 0.5~2 (>1 = mais dano recebido)
    },
    body = {
        Race              = "allo",
        PartType          = BODY_BODY,
        PenetrationRate   = 0.05,   -- Quase impenetrável
        DamageMultiplier  = 0.8,    -- Redução de dano de 20%
    },
    belly = {
        Race              = "allo",
        PartType          = BODY_BELLY,   -- Barriga (valor=7)
        PenetrationRate   = 0.9,    -- Penetração muito alta
        DamageMultiplier  = 1.8,    -- Grande bônus de dano recebido
    },
}

5. MOD de Gene BUFF

O MOD de Gene BUFF sobrescreve os valores e a config de genes/habilidades/BUFFs existentes via a tabela global CharacterGeneBuff. Como o CharacterAsset, o script é XLua (.txt) e pode ficar no mesmo arquivo ou numa subpasta GeneBuff/ dedicada.

5.1 Estrutura de Configuração (CharacterGeneBuff)

CharacterGeneBuff = {
    -- Chave = a tag do gene existente a sobrescrever (obtenha TAGs na página lista de Habilidades e Genes)
    Bleed = {
        Repeat  = "COVER",   -- Opcional: regra de sobrescrita
        Upgrade = "EXP",     -- Opcional: modo de evolução
        With    = "",        -- Opcional: DSL de efeito anexado, formato tag,nível;
        Copes   = "",        -- Opcional: tag do alvo de contra-ataque
        Effects = {          -- *Obrigatório* tabela por nível (substitui os valores por nível originais)
            { Level = 1, Probability = 0.55, Effect = 0.03, Duration = 5 },
            { Level = 2, Probability = 0.65, Effect = 0.05, Duration = 7 },
        }
    }
}

5.2 Campos de Nível Superior Modificáveis

5.3 Campos de Effects por Nível

5.4 Enums disponíveis

5.5 Exemplo Completo (DemoCharacterMod/GeneBuff/gene_buff.txt incluído)

CharacterGeneBuff = {
    -- ① Sobrescrever os valores por nível do gene existente Metabolism
    Metabolism = {
        Effects = {
            { Level = 1, Effect = 0.12, Skillful = 0   },
            { Level = 2, Effect = 0.18, Skillful = 100 },
        }
    },
    -- ② Sobrescrever a probabilidade de disparo, valores e duração do gene de habilidade existente Bleed
    Bleed = {
        Effects = {
            { Level = 1, Probability = 0.55, Effect = 0.03, Duration = 5 },
            { Level = 2, Probability = 0.65, Effect = 0.05, Duration = 7 },
        }
    }
}

5.6 Conceder Genes Inatos a uma Criatura

-- No script CharacterAsset da criatura, use o campo gene para conceder genes inatos. Formato: NomeDoGene,Nível;
CharacterAsset = {
    race = "allo",
    gene = "Metabolism,2;",
}

5.7 Carregamento e Restrições

• Aplica-se de imediato: após a sobrescrita ter sucesso, nascimento / disparo / execução leem os valores sobrescritos.
• Validação estrita de referências: With deve ser tag,nível, sem autorreferência, a tag referenciada deve existir e o nível deve estar na faixa; Copes deve existir e não se autorreferenciar. Qualquer falha rejeita a sobrescrita (nunca falha silenciosamente).
• Sem Effects válidos → essa sobrescrita falha.
• Restauração por sessão: sair / desativar / redefinir o MOD restaura automaticamente os genes sobrescritos, evitando resíduos entre partidas.
• Paridade entre os dois lados: o servidor deve carregar o mesmo MOD via GAME_MODS; os hashes devem coincidir para entrar; /modReload recarrega os valores de genes a quente.

6. MOD de Skin

Use a tabela CharacterSkin para adicionar skins personalizadas. Cada arquivo .txt define uma skin. Os arquivos de textura vão na pasta SkinsAsset/ dentro do diretório do seu MOD. Veja o DemoSkinsMod incluído para um exemplo completo.

6.1 Script de Skin

CharacterSkin = {
    Race = "allo",                              -- *Obrigatório* tag de raça
    Name = "Crooked mouth",                      -- *Obrigatório* nome único da skin
    Path = "SkinsAsset/Crooked mouth.png",       -- *Obrigatório* caminho da textura (relativo à raiz do MOD)
}

6.2 Requisitos de Textura

• Formato: PNG ou JPG.
• Resolução: corresponda à textura original (normalmente 2048×2048 ou 4096×4096).
• O caminho deve ser relativo à raiz do MOD — não use caminhos absolutos.

6.3 Exemplo de Diretório com Múltiplas Skins

MySkinMod/
├── mod.json
├── preview.jpg
└── SkinsAsset/
    ├── allo_crooked.txt   ← CharacterSkin { Race="allo", Name="Crooked mouth", ... }
    ├── crooked_allo.png   ← Arquivo de textura
    ├── rex_volcano.txt    ← Múltiplas raças em um MOD são permitidas
    └── volcano_rex.png

7. Avançado: Gerenciamento e Distribuição

7.1 Sistema de Prioridade

Quando vários MODs modificam o mesmo campo da mesma raça, o valor de Priority maior executa depois e prevalece. O padrão é 0. MODs com a mesma prioridade executam em ordem alfabética.

7.2 Segurança da Sandbox Lua

• os, io: comandos de sistema e E/S de arquivos são bloqueados.
• dofile, loadfile, package: execução arbitrária de arquivos e carregamento de bibliotecas dinâmicas são bloqueados.

7.3 Empacotando como Arquivo .mod

Compacte todos os arquivos da pasta do seu MOD como ZIP e renomeie a extensão para .mod. Certifique-se de que o mod.json esteja na raiz do arquivo. Tanto .mod quanto .zip são reconhecidos.

7.4 MODs de Servidor

Servidores especificam MODs pela variável de ambiente GAME_MODS (separados por vírgula):
GAME_MODS=DemoCharacterMod,MySkinMod
Todos os MODs exigidos pelo servidor devem estar instalados e ativados nos clientes para entrar. MODs extras ativados apenas no cliente não terão efeito nesse servidor. Administradores podem usar /modReload para recarregar a configuração dos MODs a quente.