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

L'interfaccia vanilla dei progressi limita la visualizzazione delle schede. La finestra standard ha una larghezza e un'altezza fisse, calcolate solo per sei schede. Se si installa un grande pacchetto di modifiche, in cui ogni mod importante aggiunge il proprio ramo di progressione, le nuove schede iniziano a uscire dai bordi dello schermo, a sovrapporsi tra loro o a scomparire del tutto dall'interfaccia. La modifica Paginated Advancements & Custom Frames amplia la finestra standard del menu dei progressi, aggiungendo una navigazione a pagine, un sistema per fissare i rami prioritari, uno strumento di debug integrato e il supporto per cornici completamente nuove per le icone tramite pacchetti di risorse o pacchetti di dati.

Principio tecnico di funzionamento e soluzione dei limiti dell'interfaccia vanilla

La classe vanilla AdvancementsScreen utilizza coordinate codificate in modo fisso per il rendering della finestra dei progressi (le dimensioni sono di 252 per 140 pixel). Gli elementi di controllo, come la griglia delle schede e il rendering dello sfondo, sono vincolati a dimensioni della finestra statiche, il che rende impossibile il ridimensionamento per le alte risoluzioni del monitor. Anche la classe AdvancementTab ha limiti rigidi per il disegno delle icone delle schede lungo il perimetro del frame principale.

Paginated Advancements & Custom Frames introduce modifiche direttamente nella logica di rendering dell'interfaccia grafica del client tramite iniezioni Mixin nelle classi MixinAdvancementsScreen e MixinAdvancementTab. Invece di usare costanti codificate in modo fisso, la modifica intercetta l'inizializzazione dell'interfaccia e legge le dimensioni attuali della finestra di gioco. Sulla base di questi dati viene calcolata la dimensione ottimale del frame dei progressi, che si espande in modo adattivo occupando la maggior parte dello schermo.

Il sistema raggruppa automaticamente tutte le schede registrate in pagine separate (paginazione). L'algoritmo calcola il numero massimo di schede che possono rientrare nei limiti dei pannelli superiore e inferiore della finestra secondo una formula che tiene conto della larghezza della finestra e dei margini impostati. Se il numero di rami dei progressi supera il limite della pagina, la modifica crea pagine virtuali aggiuntive e aggiunge pulsanti freccia interattivi nella parte inferiore dell'interfaccia. Durante il cambio di pagina, il renderer nasconde le schede delle pagine inattive, prevenendo il sovraccarico della memoria RAM con oggetti grafici ed eliminando i conflitti di sovrapposizione degli elementi.

Funzionalità principali e funzioni

La funzione principale di Paginated Advancements & Custom Frames è la riorganizzazione del menu grafico dei progressi. La modifica offre diversi strumenti pratici per la navigazione:

·        Paginazione dinamica: Aggiunge le frecce per cambiare pagina nell'angolo inferiore della finestra dei progressi. I giocatori possono sfogliare un numero qualsiasi di schede, anche se nel pacchetto sono attivate più di cinquanta modifiche con le proprie catene di compiti.

·        Fissaggio delle schede: L'utente può aggiungere qualsiasi scheda all'elenco dei preferiti. A tale scopo è previsto un pulsante speciale a forma di stella su ogni scheda. Una scheda fissata viene spostata automaticamente sulla prima pagina e visualizzata all'inizio dell'elenco, indipendentemente dal suo ordine di ordinamento alfabetico o interno al gioco.

·        Conservazione dello stato della sessione: La mod ricorda l'ultima scheda dei progressi aperta. In caso di chiusura del menu e di sua riapertura tramite il tasto L, l'interfaccia mostrerà la stessa scheda su cui il giocatore si era fermato, invece di tornare alla prima scheda standard.

·        Debugger dei progressi (Advancement Debugger): Una modalità speciale per gli sviluppatori di pacchetti e gli autori di missioni. Si attiva nella configurazione o all'attivazione dei suggerimenti avanzati (tasti F3 + H). Passando il cursore su un'icona di progresso, viene visualizzata una finestra di suggerimento aggiuntiva con informazioni tecniche: l'identificatore interno (ad esempio, minecraft:adventure/arbalistic) e l'elenco dei trigger (condizioni) necessari per il completamento. La combinazione di tasti Ctrl + C copia l'identificatore del progresso selezionato negli appunti.

Configurazione, compatibilità ed ecosistema

L'utente può modificare i parametri di visualizzazione del menu dei progressi tramite il file di configurazione. La posizione e il formato del file dipendono dal loader delle modifiche:

·        Fabric e Quilt: Affinché le impostazioni funzionino, è necessaria l'installazione della libreria Cloth Config API. I parametri vengono scritti nel file paginatedadvancements.json (o paginatedadvancements.json5) nella cartella config.

·        NeoForge: Le versioni della mod a partire dalla 2.8.0 utilizzano il sistema di configurazione integrato di NeoForge, il che elimina la necessità di librerie aggiuntive. Il file viene generato con il nome paginatedadvancements-client.toml nella cartella config.

Nel file di configurazione sono disponibili i seguenti parametri chiave:

·        showDebugTooltips – un valore booleano (true o false) che controlla la visualizzazione delle informazioni tecniche per il debug dei progressi.

·        maxDebugLines – un numero intero che limita il numero massimo di righe di trigger nella finestra dei suggerimenti, impedendo che il testo esca dai bordi dello schermo in caso di un gran numero di requisiti.

·        disableBackgroundFade – un parametro per disattivare l'oscuramento dello sfondo di gioco durante la visualizzazione del menu dei progressi.

·        spacing – il passo in pixel per regolare la distanza tra le schede adiacenti sul pannello.

·        enablePinning – consente o vieta ai giocatori di fissare le schede selezionate.

La modifica supporta un sistema di personalizzazione delle icone tramite il meccanismo Custom Frames (cornici personalizzate). Per impostazione predefinita, Minecraft offre tre tipi di cornici: task (compito ordinario), goal (obiettivo) e challenge (sfida). La mod consente di creare nuovi tipi tramite pacchetti di dati.

Per aggiungere una nuova cornice è necessario creare un file JSON nel pacchetto di dati nel seguente percorso:

assets/<identificatore_della_mod>/advancement_frame_types/<nome_della_cornice>.json

Esempio del contenuto del file:

Le texture per la cornice vengono collocate nei seguenti percorsi:

·       assets/<identificatore_della_mod>/textures/gui/sprites/advancements/<nome_della_cornice>_unobtained.png – aspetto della cornice prima del completamento del progresso.

·      assets/<identificatore_della_mod>/textures/gui/sprites/advancements/<nome_della_cornice>_obtained.png – aspetto della cornice dopo il completamento.

Per associare la cornice creata a un progresso specifico si utilizza un file di mappatura nel pacchetto di dati nel percorso assets/<identificatore_della_mod>/advancement_frames/<nome_del_file>.json:

La mod è stata sviluppata come un'utilità puramente lato client, pertanto non richiede l'installazione sul server. È pienamente compatibile con le grandi mod industriali e magiche (come Create, Ender IO, Botania) che aggiungono complessi sistemi di missioni e numerose schede di progressi. Per gli utenti del vecchio loader Forge è disponibile un adattamento non ufficiale della mod con il nome di ForgedPaginatedAdvancements. Per avviare le ultime versioni della mod sulla piattaforma NeoForge 26.1+ è obbligatorio l'uso dell'ambiente di runtime Java 25.

Conclusione

Paginated Advancements & Custom Frames risolve in modo efficace il problema dello spazio limitato dell'interfaccia vanilla dei progressi, che diventa critico nei grandi pacchetti di modifiche. A differenza del suo analogo Better Advancements, che principalmente ridimensiona la finestra senza aggiungere pagine, questa mod offre una chiara suddivisione in pagine e un comodo fissaggio delle schede. La modifica semplifica il lavoro degli sviluppatori di pacchetti modificati grazie al debugger integrato e al flessibile sistema di registrazione di nuovi tipi di cornici tramite le strutture JSON dei pacchetti di dati. L'unico limite degno di nota è la necessità di creare pacchetti di risorse aggiuntivi del client per la corretta visualizzazione delle cornici grafiche personalizzate.