Pular para o conteúdo principal

Codex

Códice de descobertas com categorias desbloqueáveis, livros de receitas e fragmentos colecionáveis.

Privadasv0.0.3Missões e narrativa
RequerTypeWriter0.9BasicGUIQuestopcionalQuest Codexopcional

Criada para a rede BornToCraft. Esta extensão é documentada como referência e não é distribuída.

Suporte

Visão geral​

O Codex é um registro de descobertas. Você define categorias (um bestiário, um livro de lore, uma lista de lugares) e os itens dentro delas, e cada item ou categoria é desbloqueado por criteria do TypeWriter: um fact, o estado de uma quest, uma permissão, qualquer coisa que um criteria possa verificar. As entradas bloqueadas continuam visíveis com sua própria lore, para que os jogadores vejam o que ainda falta descobrir. Você também pode adicionar categorias de receitas, que mostram uma receita de criação vanilla em uma pequena visão de mesa de criação quando o jogador clica em uma receita.

A extensão também contém um sistema de fragmentos: itens colecionáveis que os jogadores pegam, agrupados em conjuntos, com uma sequence que é disparada quando fragmentos suficientes são reunidos. Tudo é uma entry do TypeWriter, construída no painel web, e os menus são renderizados pela extensão GUI.

A extensão roda na build BTC do TypeWriter (BTC Core, Paper/Folia) e é documentada aqui como referência.

Recursos​

  • Categorias de descobertas — agrupe itens, com subcategorias aninhadas por meio de parentCategory.
  • Desbloqueio por criteria — categorias e itens são desbloqueados a partir de criteria; os bloqueados podem mostrar seu próprio item e lore.
  • Contadores de conclusão — desbloqueados, bloqueados, total e porcentagem estão disponíveis nos ícones de categoria e como placeholders.
  • Livros de receitas — mostre os ingredientes e o resultado de uma receita vanilla a partir de seu recipeKey.
  • Triggers de desbloqueio — dispare triggers na primeira vez que uma categoria, item ou receita é desbloqueada para um jogador, salvos para que nunca disparem duas vezes.
  • Quatro layouts de menu — PAGINATED, SCROLLABLE, FRAME ou SIMPLE para cada categoria.
  • Menu global do codex — um layout GUI em que os ícones de categorias são posicionados por marcadores, herdando uma base de menu compartilhada.
  • Fragmentos colecionáveis — pegue um item para coletar um fragmento, com um trigger quando um grupo é concluído.
  • Comando e action de abertura — abra uma categoria a partir de um comando, de um diálogo ou de qualquer trigger.

Instalação​

  1. Instale a extensão GUI (GuiAndDialogs na build BTC) e a extensão Basic do TypeWriter. O Codex não carrega sem elas.
  2. Opcionalmente, instale a extensão Quest e a extensão Quest Codex se quiser desbloquear entradas a partir do progresso de quests.
  3. Coloque o JAR do Codex em plugins/Typewriter/extensions/ e reinicie o servidor.
  4. Adicione um artifact Codex Unlock se usar triggers de desbloqueio e um artifact Fragment Storage se usar fragmentos.

Primeiros passos​

Construa uma categoria "Forest creatures" com dois itens:

  1. No painel web do TypeWriter, abra uma página de manifest e adicione uma entry Discovery Codex Category.
  2. Defina category com um identificador único como forest_creatures, um title, rows (por exemplo 3) e um icon.
  3. Defina itemSlotRange com os slots a preencher, por exemplo 10-16 (os números começam em 1), e escolha guiLayout.
  4. Em items, adicione um item: entryId wolf, um item exibido quando desbloqueado, um lockedItem exibido antes e, em criteria, o fact que significa "o jogador viu um lobo". Adicione unlockedLore e lockedLore.
  5. Adicione em uma página static ou sequence uma action Open Discovery Codex, defina definition com a sua categoria e dispare-a a partir de um NPC, de um item ou de uma opção de diálogo. Você também pode usar /tw codex open forest_creatures.
  6. Publique e abra o codex. Os itens cujos criteria não são atendidos permanecem bloqueados.
Itens sem criteria

Um item com uma lista criteria vazia está sempre desbloqueado. Adicione criteria a todo item que você quiser ocultar.

Como funciona​

Uma categoria mostra suas subcategorias e categorias de receitas (quando outras categorias a indicam como parentCategory) ou seus próprios itens. Os criteria da categoria e dos itens são avaliados cada vez que o menu é construído para o jogador.

Cada Discovery Codex Category é seu próprio menu de inventário com rows linhas (de 1 a 6). Os itens vão nos slots de itemSlotRange (por exemplo 1-25, contados a partir de 1), ou a partir de startSlot, preenchendo por linha ou por coluna. Os botões têm padrões: página anterior no slot 0, próxima página no slot 8, informações no slot 4 e voltar no slot 44. Eles usam setas e um livro por padrão e podem ser substituídos por previousButton, nextButton, infoButton e backButton. O botão de voltar só aparece quando a categoria foi aberta a partir de um pai. Um item background preenche todo slot livre.

O campo guiLayout escolhe como os itens são organizados quando não cabem em uma página: PAGINATED (botões de página), SCROLLABLE (botões de rolagem), FRAME (um frame por linha) ou SIMPLE (tudo em uma única tela).

O nome e a lore de um ícone de categoria (iconName, iconLore, lockedIconLore) podem usar {unlocked}, {locked}, {total} e {percent}, que são substituídos quando o ícone é exibido em uma categoria pai ou no menu global. Os demais campos de lore (itens, informações e botões de navegação) são exibidos como escritos, mesmo que seu texto de ajuda liste placeholders.

Um item folha cujo entryId corresponde ao entryId de uma Recipe Category abre a visão de receita ao ser clicado. A visão de receita mostra a grade de criação em craftingGridSlots e o resultado em resultSlot; uma receita que não está registrada no servidor mostra um item barreira chamado "Recipe not found".

A action Codex Global Menu abre um hub construído a partir de um pool de layouts do GUI. Coloque marcadores codex_button:CODEX_CATEGORY (com count, gap e direction para repeti-los) e cada marcador é preenchido com uma categoria de nível superior, ordenada por order. Uma categoria sem marcador correspondente não é exibida, e um marcador sem categoria fica vazio. CODEX_BACK volta, e CODEX_INFO, CODEX_PAGE_NEXT e CODEX_PAGE_PREV são itens puramente decorativos nesta versão.

Os marcadores CODEX_RECIPE exibem receitas: o N-ésimo marcador, na ordem de aparição no layout (como em CODEX_CATEGORY), exibe o ícone da N-ésima receita. As receitas de todas as Recipe Categories ficam em uma lista única, com as categorias ordenadas por order e as receitas na ordem da sua lista. Clicar em uma receita desbloqueada abre sua visualização de detalhes. Com mais receitas do que marcadores, as receitas excedentes não são exibidas; com mais marcadores do que receitas, os marcadores excedentes ficam vazios.

Espaçamento dos marcadores

Nos marcadores com count, gap é um passo, não um espaçamento: 1 posiciona os slots lado a lado e 2 deixa um slot vazio entre eles. O Codex usa a fórmula compartilhada do GUI. Essa é a mesma regra que se aplica aos marcadores do Quest Codex desde o Quest Codex 0.3.0, então um layout copiado de um menu antigo do Quest Codex pode precisar ter o gap dobrado. Veja a extensão GUI para a referência de layouts.

Os próprios menus de categoria podem abrir dentro de uma base compartilhada quando baseMenuId está definido (use rows de 3 ou menos para que caibam na área de conteúdo). A extensão UiCore também pode exibir o codex: sua tela Codex distribui as categorias de nível superior em quatro abas (Bestiário, Itens, Lugares e Fragmentos) procurando palavras-chave como fragment, place, region, item ou recipe no identificador e no nome da categoria, e coloca todo o resto no Bestiário.

Configuração​

A extensão não tem arquivo de configuração. O estado é mantido em dois artifacts, ambos salvos alguns segundos após uma alteração e quando o TypeWriter é descarregado:

  • Codex Unlock lembra quais triggers de desbloqueio já foram disparados para cada jogador.
  • Fragment Storage lembra os fragmentos que cada jogador coletou, por grupo.

Comandos​

ComandoDescrição
/tw codex open <category> [targets]Abre a categoria com esse identificador category para você ou para os jogadores selecionados. Alias: /tw dcx open.

O comando não tem verificação de permissão própria além do acesso ao comando do TypeWriter. Uma categoria cujos criteria não são atendidos responde "This codex is locked" e um identificador desconhecido responde "Unknown category".

A extensão também registra um comando interno /codexmenu usado pelos cliques dos menus (category, recipecat, recipe). Ele funciona apenas para jogadores e não foi feito para ser digitado manualmente.

Placeholders​

Estas são tags MiniPlaceholders da expansão discoverycodex, disponíveis em qualquer texto MiniMessage que suporte placeholders. Substitua cat pelo identificador category e item pelo entryId do item. Os identificadores podem conter sublinhados.

PlaceholderRetorna
<discoverycodex_category_unlocked:cat>Número de itens desbloqueados na categoria para o jogador.
<discoverycodex_category_total:cat>Número de itens na categoria.
<discoverycodex_category_locked:cat>Número de itens bloqueados para o jogador.
<discoverycodex_category_percent:cat>Porcentagem de itens desbloqueados, de 0 a 100.
<discoverycodex_category_name:cat>O nome da entry da categoria.
<discoverycodex_item_unlocked:item>true ou false para esse item.

Entries​

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

Ações2
Artefatos2
Manifestos6

Solução de problemas​

A extensão não carrega. O Codex exige as extensões Basic e GUI (GuiAndDialogs). Verifique o log de inicialização do TypeWriter em busca da dependência ausente.

Os triggers de desbloqueio nunca disparam. O log diz "No CodexUnlockArtifactEntry configured: skipping unlock triggers". Adicione um artifact Codex Unlock a uma página publicada. Sem ele, os triggers são ignorados de propósito, para que as recompensas não sejam entregues novamente após cada reinicialização.

Os triggers de desbloqueio dispararam uma vez e nunca mais. Isso é intencional: cada trigger dispara uma vez por jogador, e o registro é armazenado no artifact. Para testar de novo, use um novo jogador ou remova os dados dele do artifact.

Os itens caem nos slots errados ou o último slot fica vazio. itemSlotRange conta a partir de 1 (1-25 significa os slots de 0 a 24 do inventário). Os slots fora do tamanho do menu são ignorados, e os itens além do número de slots vão para a página seguinte.

Uma receita mostra "Recipe not found". recipeKey deve ser a chave com namespace de uma receita registrada no servidor, como minecraft:iron_pickaxe. As receitas adicionadas por outros plugins usam seu próprio namespace.

Um fragmento não é coletado. O jogador deve pegar o item: ele deve corresponder a customItem (ou a displayItem quando customItem está vazio), e o log não deve dizer "No FragmentArtifactEntry found". Adicione um artifact Fragment Storage. Um fragmento já coletado não é consumido novamente.

O grupo nunca é concluído. requiredCount tem como padrão 0, o que significa todos os fragmentos listados em fragments; um número acima do tamanho da lista é limitado ao tamanho da lista. O groupId do grupo deve ser o mesmo texto do fragmentGroup de seus fragmentos.

Os marcadores em um menu global estão distantes um slot. gap é um passo, então use gap 2 para deixar um slot vazio entre os marcadores.

Extensões relacionadas​

  • GUI — motor de menus, layouts e marcadores.
  • Quest Codex — menus de quests; o Codex é um complemento opcional.
  • UiCore — pode renderizar o codex em sua própria interface.