Introdução ao Ecossistema ModTheSpire

O ModTheSpire (MTS) atua como o carregador de mods e gerenciador de patches fundamental para o jogo Slay the Spire. Ele opera como uma camada de abstração que permite a inserção de novos conteúdos e modificações na lógica do jogo sem a necessidade de alterar permanentemente os arquivos binários originais. Sua arquitetura é baseada em Java e utiliza técnicas avançadas de manipulação de bytecode em tempo de execução.

Mecanismos de Inicialização e Carregamento

O processo de inicialização do MTS é dividido em fases críticas que garantem a integridade do ambiente de execução. Ao iniciar o carregador, o sistema executa os seguintes passos:

1. Detecção de Versão: Através do componente GameVersionFinder, o carregador identifica a versão exata do executável do jogo para garantir compatibilidade.
2. Isolamento de Classe: O MTSClassLoader gerencia o carregamento de JARs externos, evitando conflitos de nomes de classes entre diferentes modificações.
3. Resolução de Dependências: O sistema analisa os metadados de cada mod para estabelecer uma ordem de carregamento hierárquica, garantindo que bibliotecas base sejam carregadas antes das extensões que dependem delas.

Configuração do Ambiente de Execução

Para garantir a estabilidade do jogo ao utilizar múltiplos mods complexos, é essencial realizar uma configuração adequada do ambiente Java e da estrutura de diretórios.

Estrutura Organizacional Sugerida

Manter uma hieraruqia de arquivos organizada facilita a depuração e a manutenção do ambiente:

/SlayTheSpire_Root/
│
├── ModTheSpire.jar          # Executável principal do carregador
├── MTS_Launcher.bat         # Script de inicialização customizado
└── mods/                    # Repositório de extensões
    ├── 01_core_libraries/   # Mods base (ex: ModHelper, StSLib)
    ├── 02_content_packs/    # Novos personagens e cartas
    └── 03_utilities/        # Melhorias de interface e ferramentas

Otimização de Memória via JVM

Mods que adicionam muitos ativos gráficos ou processamento lógico intenso exigem mais recursos. É possível ajustar os parâmetros da Máquina Virtual Java (JVM) no script de inicialização para evitar erros de OutOfMemory:

java -Xms512M -Xmx2G -jar ModTheSpire.jar

Neste exemplo, definimos o heap inicial em 512MB e o limite máximo em 2GB.

Fundamentos da Injeção de Código (Patching)

A tecnologia central do ModTheSpire é a biblioteca Javassist, que permite modificar o comportamento de classes compiladas. O MTS utiliza anotações específicas para definir onde e como o código original deve ser alterado:

• @SpirePatch: Define a classe e o método alvo que receberão a modificação.
• @SpireField: Permite injetar novas variáveis e estados em classes existentes do jogo.
• @SpireEnum: Utilizado para estender tipos enumerados nativos, como novos tipos de cores de cartas ou raridades.

Exemplo de Implementação de Patch

Abaixo, um exemplo conceitual de como um patch é estruturado para modificar o dano base de uma ação:

@SpirePatch(
    clz = DamageAction.class,
    method = "update"
)
public class ModificadorDanoCustom {
    public static void Prefix(DamageAction __instance) {
        // Lógica injetada antes da execução do método original
        if (__instance.amount > 0) {
            __instance.amount += 5; 
        }
    }
}

Diagnóstico de Falhas e Logs de Sistema

O monitoramento do arquivo ModTheSpire.log é a principal ferramenta para desenvolvedores e usuários avançados. O carregador registra detalhadamente:

• Falhas de verificação de integridade de bytecode.
• Exceções de runtime causadas por incompatibilidade entre mods.
• Conflitos de assinatura em métodos que recebem múltiplos patches simultâneos.

Caso o jogo feche inesperadamente, deve-se buscar pela última entrada de FATAL ou ERROR no log, que geralmente aponta para a classe exata onde a injeção de código falhou ou onde ocorreu uma violação de acesso.