Paginated Advancements & Custom Frames — Minecraft Java Edition 1.18.1 - 26.1+

A interface vanilla das conquistas limita a exibição de abas. A janela padrão tem largura e altura fixas, calculadas apenas para seis abas. Se for instalado um grande pacote de modificações, em que cada grande mod adiciona o seu próprio ramo de progressão, as novas abas começam a sair dos limites da tela, a sobrepor-se umas às outras ou a desaparecer completamente da interface. A modificação Paginated Advancements & Custom Frames amplia a janela padrão do menu de conquistas, adicionando navegação por páginas, um sistema para fixar os ramos prioritários, uma ferramenta de depuração integrada e suporte a molduras totalmente novas para os ícones por meio de pacotes de recursos ou pacotes de dados.

Princípio técnico de funcionamento e solução das limitações da interface vanilla

A classe vanilla AdvancementsScreen usa coordenadas codificadas de forma fixa para renderizar a janela de conquistas (o tamanho é de 252 por 140 pixels). Os elementos de controle, como a grade de abas e a renderização do plano de fundo, estão vinculados a dimensões de janela estáticas, o que impossibilita o dimensionamento para uma alta resolução de monitor. A classe AdvancementTab também tem limites rígidos para desenhar os ícones das abas ao longo do perímetro do quadro principal.

Paginated Advancements & Custom Frames introduz alterações diretamente na lógica de renderização da interface gráfica do cliente por meio de injeções Mixin nas classes MixinAdvancementsScreen e MixinAdvancementTab. Em vez de usar constantes codificadas de forma fixa, a modificação intercepta a inicialização da interface e lê as dimensões atuais da janela do jogo. Com base nesses dados, calcula-se o tamanho ideal do quadro de conquistas, que se expande de forma adaptativa, ocupando a maior parte da tela.

O sistema agrupa automaticamente todas as abas registradas em páginas separadas (paginação). O algoritmo calcula o número máximo de abas que podem caber dentro dos limites dos painéis superior e inferior da janela por meio de uma fórmula que leva em conta a largura da janela e as margens definidas. Se o número de ramos de conquistas exceder o limite da página, a modificação cria páginas virtuais adicionais e adiciona botões de seta interativos na parte inferior da interface. Durante a troca de páginas, o renderizador oculta as abas das páginas inativas, evitando a sobrecarga da memória RAM com objetos gráficos e eliminando os conflitos de sobreposição de elementos.

Principais recursos e funcionalidades

A função principal do Paginated Advancements & Custom Frames é a reorganização do menu gráfico de conquistas. A modificação oferece várias ferramentas práticas para a navegação:

·        Paginação dinâmica: Adiciona setas para trocar de página no canto inferior da janela de conquistas. Os jogadores podem percorrer qualquer número de abas, mesmo que no pacote estejam ativadas mais de cinquenta modificações com as suas próprias cadeias de tarefas.

·        Fixação de abas: O usuário pode adicionar qualquer aba à lista de favoritas. Para isso, há um botão especial em forma de estrela em cada aba. Uma aba fixada é automaticamente movida para a primeira página e exibida no início da lista, independentemente da sua ordem de classificação alfabética ou interna do jogo.

·        Preservação do estado da sessão: O mod memoriza a última aba de conquistas aberta. Em caso de fechamento do menu e da sua reabertura por meio da tecla L, a interface mostrará a mesma aba em que o jogador parou, em vez de retornar à primeira aba padrão.

·        Depurador de conquistas (Advancement Debugger): Um modo especial para desenvolvedores de pacotes e autores de missões. Ele é ativado na configuração ou ao habilitar as dicas avançadas (teclas F3 + H). Ao passar o cursor sobre um ícone de conquista, é exibida uma janela de dica adicional com informações técnicas: o identificador interno (por exemplo, minecraft:adventure/arbalistic) e a lista de gatilhos (condições) necessários para o cumprimento. A combinação de teclas Ctrl + C copia o identificador da conquista selecionada para a área de transferência.

Configuração, compatibilidade e ecossistema

O usuário pode alterar os parâmetros de exibição do menu de conquistas por meio do arquivo de configuração. A localização e o formato do arquivo dependem do carregador de modificações:

·        Fabric e Quilt: Para que as configurações funcionem, é necessária a instalação da biblioteca Cloth Config API. Os parâmetros são gravados no arquivo paginatedadvancements.json (ou paginatedadvancements.json5) na pasta config.

·        NeoForge: As versões do mod a partir da 2.8.0 usam o sistema de configuração integrado do NeoForge, o que elimina a necessidade de bibliotecas adicionais. O arquivo é gerado com o nome paginatedadvancements-client.toml na pasta config.

No arquivo de configuração estão disponíveis os seguintes parâmetros principais:

·        showDebugTooltips – um valor booleano (true ou false) que controla a exibição das informações técnicas para a depuração de conquistas.

·        maxDebugLines – um número inteiro que limita o número máximo de linhas de gatilhos na janela de dicas, evitando que o texto saia dos limites da tela em caso de um grande número de requisitos.

·        disableBackgroundFade – um parâmetro para desativar o escurecimento do plano de fundo do jogo durante a visualização do menu de conquistas.

·        spacing – o passo em pixels para ajustar a distância entre abas vizinhas no painel.

·        enablePinning – permite ou proíbe que os jogadores fixem as abas selecionadas.

A modificação oferece suporte a um sistema de personalização de ícones por meio do mecanismo Custom Frames (molduras personalizadas). Por padrão, o Minecraft oferece três tipos de molduras: task (tarefa comum), goal (meta) e challenge (desafio). O mod permite criar novos tipos por meio de pacotes de dados.

Para adicionar uma nova moldura é necessário criar um arquivo JSON no pacote de dados no seguinte caminho:

assets/<identificador_do_mod>/advancement_frame_types/<nome_da_moldura>.json

Exemplo do conteúdo do arquivo:

As texturas da moldura são colocadas nos seguintes caminhos:

·       assets/<identificador_do_mod>/textures/gui/sprites/advancements/<nome_da_moldura>_unobtained.png – aparência da moldura antes do cumprimento da conquista.

·      assets/<identificador_do_mod>/textures/gui/sprites/advancements/<nome_da_moldura>_obtained.png – aparência da moldura após o cumprimento.

Para vincular a moldura criada a uma conquista específica, utiliza-se um arquivo de mapeamento no pacote de dados no caminho assets/<identificador_do_mod>/advancement_frames/<nome_do_arquivo>.json:

O mod foi desenvolvido como um utilitário puramente do lado do cliente, por isso não requer instalação no servidor. Ele é totalmente compatível com grandes mods industriais e mágicos (como Create, Ender IO, Botania), que adicionam complexos sistemas de missões e numerosas abas de conquistas. Para os usuários do antigo carregador Forge está disponível uma adaptação não oficial do mod com o nome de ForgedPaginatedAdvancements. Para executar as versões mais recentes do mod na plataforma NeoForge 26.1+ é obrigatório o uso do ambiente de execução Java 25.

Conclusão

Paginated Advancements & Custom Frames resolve de forma eficaz o problema do espaço limitado da interface vanilla de conquistas, que se torna crítico nos grandes pacotes de modificações. Ao contrário do seu análogo Better Advancements, que principalmente dimensiona a janela sem adicionar páginas, este mod oferece uma divisão clara em páginas e uma cômoda fixação de abas. A modificação simplifica o trabalho dos desenvolvedores de pacotes modificados graças ao depurador integrado e ao flexível sistema de registro de novos tipos de molduras por meio das estruturas JSON dos pacotes de dados. A única limitação notável é a necessidade de criar pacotes de recursos adicionais do cliente para a correta exibição das molduras gráficas personalizadas.