Pular para o conteúdo principal

Quest Codex

Menus de diário de missões com categorias, rastreamento múltiplo, pontos de GPS, conquistas e ícones do BlueMap.

Gratuitasv2.16Missões e narrativa
RequerTypeWriter0.9QuestGUI0.18+BlueMapopcional
BaixarCódigo-fonteSuporte

Visão geral​

O Quest Codex dá aos jogadores um livro de quests. Um menu principal lista categorias (História principal, Missões secundárias, Dungeons...), cada categoria abre uma lista das suas quests e clicar em uma quest ativa a rastreia. As quests em si são as que você cria com a extensão oficial Quest do TypeWriter: o Quest Codex apenas as organiza e exibe.

Você desenha cada tela por conta própria. Um menu é um layout da extensão GUI no qual você coloca itens marcadores: um marcador QUEST_SLOT é substituído pelas quests do jogador, um marcador CATEGORY_SLOT pelas categorias e um marcador SORT_SLOT pelo botão de ordenação. Tudo ao redor dos marcadores (bordas, títulos, botões, rolagem, páginas) é conteúdo comum do GUI.

Além do menu, a extensão adiciona rastreamento de várias quests que sobrevive a reconexões, recuperação de um diálogo ou cinemática interrompido, waypoints de GPS e pontos da locator bar no cliente, advancements personalizados do Minecraft concedidos a partir de uma page e ícones de quest no BlueMap.

Recursos​

  • Categorias — categorias aninhadas com ordem, ícone, visibilidade e criteria de conclusão, e mensagens por status.
  • Atribuição de quests — coloque quests em uma categoria, defina a ordem delas e sobrescreva ícone, nome, lore e visibilidade por status.
  • Pools de layouts — você desenha cada menu com layouts do GUI; o codex preenche os marcadores QUEST_SLOT, CATEGORY_SLOT, TRACKED_QUEST_SLOT e SORT_SLOT.
  • Botão de ordenação — alterna entre All, Not started, In progress e Completed, com rótulo, ícone e lore por modo.
  • Rastreamento múltiplo — rastreie várias quests ativas ao mesmo tempo; a última é a quest principal do rastreador oficial do HUD.
  • Menu de quests rastreadas — um menu dedicado às quests que o jogador está rastreando.
  • Waypoints — camadas de texto, bloco e beacon feitas apenas de pacotes que apontam para um objetivo, uma posição ou uma entidade, além de uma variante para a locator bar vanilla.
  • Recuperação de interações — restaura o diálogo ou a cinemática ativos após uma desconexão.
  • Advancements — defina abas de advancements do Minecraft no painel e conceda-os com uma ação.
  • Ícones no BlueMap — coloque um ícone de quest com um popup no BlueMap.

Instalação​

  1. Instale o TypeWriter em um servidor Paper ou Folia, com a extensão oficial Quest, que define as quests exibidas pelo Quest Codex.
  2. Instale a extensão GUI (versão 0.18 ou mais recente).
  3. Opcional: instale o PacketEvents (já exigido pelo TypeWriter) para os waypoints e o BlueMap para os ícones no mapa.
  4. Baixe o JAR do Quest Codex nas releases do GitHub (o botão no painel de resumo acima), coloque-o em plugins/Typewriter/extensions/ e reinicie o servidor.
  5. Conceda aos seus jogadores a permissão typewriter.codex.open; veja Permissões abaixo.

Primeiros passos​

Monte um diário de quests com uma categoria:

  1. Em uma page static, adicione uma entry Quest Codex Tracking Data. É aqui que as quests rastreadas são salvas.
  2. Em uma page manifest, adicione uma entry Quest Codex Global Settings. Defina trackingArtifact como o artifact e revise maxTrackedQuests e os sons.
  3. Adicione uma entry Quest Category com category main_quests, um title como <gold>Main Story e um icon.
  4. Adicione uma entry Quest Assignment com category main_quests e suas quests em questRefs. orders é opcional.
  5. Crie duas entries Open GUI usadas apenas como contêineres de layouts. Na primeira, main_gui, adicione um layout simple com o id main, defina mainLayoutId como main, guiType como CUSTOM e size como SIZE_36. Adicione um item com buttonPrefix codex_button:, buttonType CATEGORY_SLOT, x 1, y 1, count 7 e direction right. Na segunda, quests_gui, faça o mesmo com o marcador QUEST_SLOT e adicione um item CLOSE na linha inferior.
  6. Adicione um Category Menu com category vazio, rows 4 e menu definido como main_gui. Este é o menu principal.
  7. Adicione um segundo Category Menu com category main_quests, rows 4 e menu definido como quests_gui.
  8. Publique e depois execute /tw codex no jogo. Clique na categoria e depois clique em uma quest ativa para rastreá-la.
Mantenha rows e size iguais

O inventário é construído a partir de rows do Category Menu e não a partir de size do Open GUI. Se forem diferentes, os slots abaixo da menor altura são descartados e o console avisa você na inicialização.

Marcadores

Um slot de marcador mostra uma quest. Use count, direction, gap e repeatY para distribuir um marcador em uma grade: count 7, direction right e repeatY 3 resultam em 21 slots de quest. Sem direction, o marcador continua sendo um único slot. As quests preenchem os marcadores em ordem de leitura, e a página seguinte de quests é alcançada com um botão PAGE_NEXT.

Como funciona​

Na inicialização, a extensão carrega as categorias, os assignments e os menus. Quando um jogador abre um menu, ela reescreve cada marcador do layout como um marcador indexado (QUEST_SLOT#0, QUEST_SLOT#1, ...) antes de o layout ser interpretado, de modo que os marcadores se comportam como slots comuns dentro de layouts scrollable, paginated e frame. Na renderização, cada marcador é substituído pela n-ésima quest ou categoria.

Quais entries formam um menu​

Um Category Menu é a entry que você abre. Seu campo menu aponta para uma entry Open GUI que fornece apenas o pool de layouts, o layout principal, o tipo de janela e os sons. Não dispare esse Open GUI por conta própria.

category do Category MenuMenuMarcador que deve conter
vazioMenu principal listando as categorias raizCATEGORY_SLOT
o nome de uma categoriaQuests dessa categoriaQUEST_SLOT
@trackedQuests que o jogador está rastreandoTRACKED_QUEST_SLOT

Toda categoria definida precisa de um Category Menu; caso contrário, abri-la não faz nada e o console informa isso na inicialização.

Marcadores e botões​

Defina buttonPrefix como codex_button: e buttonType como um destes:

buttonTypeFunção
CATEGORY_SLOTO ícone de uma categoria, com seu título, progresso {completed}/{total}, dica de clique e mensagem de status. Clicar abre a categoria.
QUEST_SLOTUma quest. O ícone segue o status dela; o nome e a lore vêm da quest, do assignment e das entries Quest Lore. Clicar em uma quest ativa a rastreia ou deixa de rastreá-la.
TRACKED_QUEST_SLOTUma quest rastreada no menu @tracked. Um slot vazio mantém o seu próprio item e fica inerte, então é o seu estado vazio.
SORT_SLOTO botão de ordenação. Configure cada modo em sortDisplay do Category Menu.
PAGE_NEXT, PAGE_PREVVão para a página seguinte ou anterior de quests ou categorias.
SCROLL_UP, SCROLL_DOWN, SCROLL_LEFT, SCROLL_RIGHTRolam o menu.
BACKVolta ao menu principal quando existe um, senão à entry mainMenuTrigger, senão ao menu anterior, senão fecha.
CLOSEFecha o menu.
SORTUm botão de ordenação colocado como um slot de navegação comum.

Os botões de navegação mantêm o item, o nome e a lore que você configura; a seta, a barreira ou o funil embutido só é usado quando o slot não tem item.

Coloque os marcadores em layouts simple que pertençam ao Open GUI referenciado por menu. Marcadores em outros tipos de layout, ou nos layouts de um chassi compartilhado, não são indexados e ficam ocultos.

Chassi, views e abas​

Para montar um livro de quests com abas, defina baseMenuId no Category Menu como um shell Open GUI compartilhado e adicione views, defaultViewId e breadcrumbSeparator, exatamente como em Views, abas e herança. pushHistoryOnViewSwitch faz o botão Voltar retornar à aba anterior. Um chassi cujo layout raiz tem uma variante _extended recebe automaticamente o canvas de dez linhas.

Exibição das quests​

  • O ícone de uma quest é, por padrão, um livro, um relógio ou uma esmeralda para não iniciada, em andamento e concluída. Sobrescreva-o por status no Quest Assignment (notStartedItem, inProgressItem, completedItem).
  • notStartedName, inProgressName e completedName substituem o nome da quest, e os campos de lore correspondentes adicionam linhas. Oculte uma quest por status com hideWhenNotStarted, hideWhenInProgress e hideWhenCompleted.
  • Uma entry Quest Lore adiciona linhas por status a uma quest, em uma categoria ou em todas.
  • A ordem das quests segue primeiro orders e depois a ordem de questRefs. Uma categoria também lista as quests de suas subcategorias.
  • O menu principal lista apenas as categorias de nível superior (as sem parent). Uma subcategoria é aberta com /tw codex <category> ou com um botão que executa codex:open <category>.

Configuração​

A entry Quest Codex Global Settings guarda as opções que não estão ligadas a um menu. Crie apenas uma; sem ela, os padrões são usados.

  • Sons — soundOnOpen, soundOnSwitch, soundOnClick, soundOnTrack, soundOnUntrack.
  • Rastreamento — multiTrackingEnabled, maxTrackedQuests (pelo menos 1) e trackingArtifact. Sem um artifact, as quests rastreadas são mantidas apenas na memória e o console avisa na inicialização. O artifact é um arquivo que deve manter seu artifactId depois que os jogadores começam a usá-lo.
  • Recuperação — recoveryEnabled, recoveryArtifact, recoveryRetentionSeconds (10 a 86400) e recoveryRestoreDelayTicks (1 a 20). Quando um jogador sai durante um diálogo ou uma cinemática, o snapshot é armazenado e restaurado logo depois que o jogador volta. Sem um artifact, a recuperação fica desativada.
  • Mensagens — nowTrackingMessage, stoppedTrackingMessage, questInactiveMessage, questCompletedMessage, trackingLimitMessage ({quest}, {max}), categoryProgressMessage ({completed}, {total}) e as dicas da lore de categorias e quests.
  • Rótulos de navegação — navLabels define o nome de cada botão integrado (next, previous, up, down, left, right, back, close, sort). Só é usado quando o slot marcado não tem um item próprio: um slot que carrega um item mantém o próprio nome e lore.
  • Botão de ordenação — sortTexts define o rótulo de cada modo de ordenação (allLabel, notStartedLabel, activeLabel, completedLabel) e a linha de lore hint. Um Category Menu que define um label ou lore no seu sortDisplay para um modo mantém o seu próprio.
  • Títulos de menu — mainMenuTitle e trackedQuestsTitle são os títulos usados quando o Category Menu correspondente tem um title vazio.
  • Erro de comando — unknownCategoryMessage é o erro que /tw codex <category> mostra para uma categoria que não existe ({category}).
  • Alternativa do menu principal — mainMenuTrigger é disparado quando não há um Category Menu principal, por exemplo um Open GUI seu cujos botões executam codex:open <category>.

Waypoints e locator bar​

Quest Codex Waypoint é uma entry de audience: conecte-a a um filtro de audience para escolher quem a vê. Seu target é uma posição fixa, um objetivo localizável, o objetivo rastreado (seleção HIGHEST_PRIORITY, FIRST, CLOSEST, ALL ou ONE_PER_QUEST) ou uma entidade. Suas layers combinam uma camada de texto (placeholders {icon}, {distance}, {distance_m}, {distance_km}, {elevation}, {direction}, {vertical_direction}, {target}, {world_name}, {height_diff} e {eta}), uma camada de bloco e uma camada de beacon. displayMode é HUD_LOCKED (padrão), WORLD_DIRECTIONAL, TARGET_ANCHORED ou ADAPTIVE, e cada camada pode sobrescrevê-lo. Tudo é enviado por pacotes; nenhuma entidade é salva no mundo.

Quest Codex Locator Bar mostra os mesmos alvos como pontos na locator bar vanilla, que exige o Minecraft 1.21.6 ou mais recente, e combina com um waypoint 3D.

Advancements e BlueMap​

  • Advancement Definition descreve um advancement. Um sem parent vira uma aba. Eles são gravados na inicialização em um datapack chamado questcodex_advancements na pasta do mundo, e o servidor recarrega seus dados quando o conteúdo mudou, então uma nova definição exige reinício. O advancement só é obtido pela ação Grant Advancement.
  • BlueMap Icon coloca, na inicialização, um marcador com rótulo e popup nos mapas do BlueMap do seu mundo. Em description, <objectives> é substituído pelos objetivos da quest.

Comandos​

Todos os comandos são subcomandos de /typewriter, normalmente digitado como /tw, e exigem typewriter.codex.open.

ComandoDescrição
/tw codexAbre o menu principal: o Category Menu com category vazio, senão a entry mainMenuTrigger.
/tw codex trackedAbre o menu de quests rastreadas.
/tw codex <category>Abre uma categoria. O autocompletar lista as categorias definidas.

Os botões de menu também podem executar estes comandos internos: codex:open <category>, codex:tracked, codex:quest <quest_id> e codex:nav <action>. Use codex:open e codex:tracked nos botões dos seus próprios menus GUI.

Permissões​

PermissãoConcede
typewriter.codex.openTodos os comandos /tw codex. A extensão a declara com padrão apenas para operadores e ela aparece no seu plugin de permissões: conceda-a aos grupos que podem usar /tw codex.

Abrir um menu a partir de uma ação Category Menu ou de um botão de menu não exige permissão.

Placeholders​

Placeholders do PlaceholderAPI, com a expansão typewriter. Eles exigem um jogador.

PlaceholderRetorna
%typewriter_total_quests%Número de quests em todas as categorias.
%typewriter_total_completed%, %typewriter_total_in_progress%, %typewriter_total_not_started%Número de quests em cada status para o jogador.
%typewriter_total_progress%Concluídas sobre o total, por exemplo 15/42.
%typewriter_category_<name>%Número de quests na categoria.
%typewriter_category_<name>_completed%, _in_progress%, _not_started%Quests da categoria nesse status.
%typewriter_category_<name>_progress%Concluídas sobre o total da categoria.
%typewriter_codex_tracked_count%, _limit%Número de quests rastreadas e o máximo.
%typewriter_codex_tracked_multi_enabled%, _has_any%true ou false.
%typewriter_codex_tracked_ids%, _names%, _names_lines%Ids ou nomes das quests rastreadas, separados por vírgula ou um por linha.
%typewriter_codex_tracked_primary_id%, _primary_name%A quest principal exibida pelo rastreador oficial.
%typewriter_codex_tracked_has_<quest_id>%Se essa quest está rastreada.
%typewriter_codex_tracked_<n>_id%, _name%, _status%, _primary%Detalhes da n-ésima quest rastreada, a partir de 1. Vazio quando não há nenhuma.
%typewriter_codex_tracked_<n>_objective_count%, _objectives%, _objectives_lines%, _priority%Objetivos visíveis da n-ésima quest rastreada.

<name> é o nome da categoria, comparado sem diferenciar maiúsculas de minúsculas. Mais detalhes em Placeholders, Comandos e Permissões.

Entries​

12 entradas, geradas a partir do código-fonte da extensão.

Ações2
Audiências2
Artefatos2
Manifestos6

Solução de problemas​

/tw codex não faz nada. Não há nenhum Category Menu com category vazio e nenhum mainMenuTrigger. O console registra Main menu could not open com a causa. Para uma categoria, crie um Category Menu cujo category seja igual ao category da Quest Category.

Um menu abre vazio. O console informa isso na inicialização: nenhum slot do Open GUI referenciado tem o marcador de que o menu precisa (CATEGORY_SLOT, QUEST_SLOT ou TRACKED_QUEST_SLOT), menu está vazio ou não é um Open GUI, o pool de layouts está vazio ou mainLayoutId não está nele. Os marcadores precisam de buttonPrefix codex_button:.

Faltam slots nas linhas inferiores. O rows do Category Menu é menor que o size do Open GUI. Defina ambos com o mesmo número de linhas.

As quests aparecem com um slot de distância em vez de um slot vazio entre elas. gap é um passo: 1 é adjacente e 2 deixa um slot vazio. Os menus escritos antes do Quest Codex 0.3.0 usavam gap como espaçamento, então dobre o valor. Uma colisão com uma decoração é informada como um aviso Slot overlap.

Vários marcadores se empilham em uma célula. O marcador tem count mas não tem direction, ou a posição cai fora da grade. Defina uma direction.

Uma quest está faltando em uma categoria. A quest está oculta por uma opção hideWhen... para o status atual dela, o modo de ordenação atual a filtra, ou o assignment não conseguiu resolvê-la (Quest '...' could not be resolved no console).

Uma quest rastreada desaparece após um reinício. trackingArtifact está vazio, ou seu artifactId mudou. Uma quest que deixou de estar ativa é removida da lista de rastreadas.

Os waypoints não aparecem. A entry de waypoint deve estar dentro de uma audience à qual o jogador pertence, a quest deve estar rastreada e o objetivo deve ser localizável. Uma camada de texto com {icon} permanece vazia até que icon seja definido.

Um novo advancement é desconhecido para o servidor. As definições são gravadas na inicialização; reinicie depois de adicionar uma. Uma definição cujo ícone não é um item é ignorada com um aviso.

Extensões relacionadas​

  • GUI — layouts, marcadores, views e o chassi open_gui usado por todo menu do Quest Codex.
  • Shops — usa o mesmo mecanismo de marcadores para os menus de loja.