Configuração

Três arquivos/pastas principais:

• plugins/KGInfoServs-QuestsTrack/config.yml — Configuração geral do plugin
• plugins/KGInfoServs-QuestsTrack/quests_config.yml — Textos, etapas e objetivos das quests
• plugins/KGInfoServs-QuestsTrack/lang/<locale>.yml — Arquivos de tradução da interface

---

config.yml — Referência completa

Aqui está a estrutura completa do arquivo config.yml com todas as opções disponíveis.

Categoria padrão (defaultCategory)

defaultCategory: "other"

Categoria usada para as quests que não especificam questParameters.questCategory em sua configuração do BetonQuest. O valor deve corresponder à chave YAML de uma categoria (configKey), não ao seu displayName.

Categorias do menu (menuItems.categories)

As categorias organizam as quests no menu GUI. Você pode definir até 4 categorias. Cada categoria é totalmente personalizável e seu displayName pode ser multilíngue.

menuItems:
  categories:
    story:                       # configKey — usado para o matching com questCategory
      displayName:               # Formato multilíngue (recomendado)
        fr-FR: "Histoire"
        en-US: "Story"
      material: WRITABLE_BOOK
      customModelData: 0
      autoTrack: true
    secondary:
      displayName:
        fr-FR: "Secondaires"
        en-US: "Secondary"
      material: BOOK
      customModelData: 0
      autoTrack: false
    dailyQuests:
      displayName:
        fr-FR: "Journalieres"
        en-US: "Daily"
      material: CLOCK
      customModelData: 0
      autoTrack: false
    other:
      displayName: "Other"       # Formato simples — sempre suportado
      material: BOOKSHELF
      customModelData: 0
      autoTrack: false

Propriedades de uma categoria

Propriedade	Obrigatória	Padrão	Descrição
displayName	Não	configKey	Nome exibido no menu GUI. Suporta o formato simples ou multilíngue (veja abaixo).
material	Sim	—	Material do Minecraft para o ícone (ex: WRITABLE_BOOK, CLOCK)
customModelData	Não	0	Custom model data para resource pack
autoTrack	Não	false	Se true, as quests dessa categoria são automaticamente adicionadas ao acompanhamento do scoreboard quando são ativadas

configKey vs displayName

O configKey (a chave YAML, ex: story) é o identificador estável da categoria:

• É ele que você usa em questCategory do lado do BetonQuest (questCategory: story)
• Também serve para indexar as quests internamente e identificar a categoria no código

O displayName é usado apenas para exibição no menu GUI. Você pode alterá-lo (ou traduzi-lo) sem quebrar o matching com seus pacotes do BetonQuest.

Migração a partir de uma versão anterior

Antes desta versão, questCategory precisava corresponder ao displayName (ex: questCategory: "Story"). Agora, ele deve corresponder ao configKey (ex: questCategory: story).

Se você está atualizando a partir de uma versão antiga, precisa modificar seus package.yml do BetonQuest:

• questCategory: "Story" → questCategory: story
• questCategory: "Daily" → questCategory: dailyQuests
• questCategory: "Other" → questCategory: other

Sem essa migração, todas as suas quests cairão na categoria padrão.

displayName multilíngue

O campo displayName aceita dois formatos:

Formato simples — um único idioma (formato antigo, ainda suportado):

displayName: "Story"

Formato multilíngue — um texto por idioma:

displayName:
  fr-FR: "Histoire"
  en-US: "Story"
  de-DE: "Geschichte"

O idioma exibido é escolhido de acordo com o jogador que abre o menu (veja Idioma por jogador).

Subcategorias

Cada categoria pode ter subcategorias para uma organização mais detalhada:

menuItems:
  categories:
    dailyQuests:
      displayName:
        fr-FR: "Journalieres"
        en-US: "Daily"
      material: CLOCK
      customModelData: 0
      autoTrack: false
      subcategories:
        monsters:                  # configKey da subcategoria
          displayName:
            fr-FR: "Monstres"
            en-US: "Monsters"
          material: ZOMBIE_HEAD
        farming:
          displayName:
            fr-FR: "Agriculture"
            en-US: "Farming"
          material: NETHERITE_HOE
        mining:
          displayName: "Mining"    # Formato simples também aceito
          material: NETHERITE_PICKAXE

Para colocar uma quest em uma subcategoria, use o formato hierárquico com um ponto no BetonQuest, usando as configKey:

# No package.yml da quest do BetonQuest
questParameters:
  questCategory: dailyQuests.monsters

O formato é: configKey_categoria.configKey_subcategoria

Formato histórico

Antes desta versão, o formato era displayName.displayName (ex: Daily.Monsters). Agora é preciso usar as configKey (ex: dailyQuests.monsters).

Navegação no menu

1. O jogador abre /quests
2. Seleciona a categoria "Daily"
3. Vê as subcategorias (Monsters, Farming, Mining)
4. Seleciona uma subcategoria
5. Vê as quests dessa subcategoria

Cada subcategoria exibe automaticamente uma barra de progresso indicando a porcentagem de quests concluídas.

Botões do menu

menuItems:
  toggleCompleted:
    visible:
      material: LIME_DYE
      customModelData: 0
    hidden:
      material: GRAY_DYE
      customModelData: 0
  nextPage:
    material: PAPER
    customModelData: 0
  prevPage:
    material: PAPER
    customModelData: 0
  closeButton:
    material: BARRIER
    customModelData: 0

Botão	Descrição
toggleCompleted.visible	Ícone quando as quests concluídas estão visíveis
toggleCompleted.hidden	Ícone quando as quests concluídas estão ocultas
nextPage	Botão de próxima página
prevPage	Botão de página anterior
closeButton	Botão para fechar o menu

Arquivos de idioma (lang/)

As traduções da interface (menus, comandos, scoreboard, mensagens de acompanhamento, logs do console) são gerenciadas por arquivos de idioma individuais localizados em:

plugins/KGInfoServs-QuestsTrack/lang/<locale>.yml

Idiomas incluídos

O plugin inclui 5 idiomas por padrão:

Arquivo	Idioma
lang/fr-FR.yml	Francês
lang/en-US.yml	Inglês
lang/de-DE.yml	Alemão
lang/pt-BR.yml	Português (Brasil)
lang/pl-PL.yml	Polonês

Seleção do idioma

O QuestsTracker resolve o idioma por jogador baseando-se no sistema nativo do BetonQuest.

Idioma por jogador

Cada jogador pode escolher seu próprio idioma com o comando BetonQuest /questlang:

/questlang fr-FR
/questlang en-US
/ql de-DE

O BetonQuest persiste essa escolha em PlayerData. O QuestsTracker lê esse valor a cada abertura do menu, atualização do scoreboard ou atualização do diário.

Atualização automática

Quando um jogador executa /questlang, o plugin detecta o comando e atualiza imediatamente:

• O scoreboard do jogador (com os novos textos traduzidos)
• O menu de quests aberto (se houver um)

Nenhuma outra ação é necessária — tudo passa para o novo idioma instantaneamente.

Idioma padrão (fallback)

Se um jogador nunca executou /questlang, o plugin usa o idioma global do servidor:

# No plugins/BetonQuest/config.yml
language: fr-FR

Se o arquivo de idioma correspondente não existir em lang/, o plugin usa o primeiro arquivo disponível.

Campos com suporte a multilíngue

Os seguintes campos suportam automaticamente o formato multilíngue:

Arquivo	Campo
config.yml	menuItems.categories.<key>.displayName
config.yml	menuItems.categories.<key>.subcategories.<key>.displayName
quests_config.yml	title, locked_description, finished_text
quests_config.yml	Steps: text, objetivos inprogress / completed
package.yml (BetonQuest)	questParameters.questReward

Todos esses campos aceitam ou uma string simples, ou um mapa {lang-code: texto}.

Categorias de chaves

Cada arquivo de idioma contém as seguintes categorias:

Prefixo	Descrição
command.*	Mensagens dos comandos (/quests, /kgquests, etc.)
tracking.*	Mensagens relacionadas ao acompanhamento das quests (adição, remoção, limites)
menu.*	Textos da interface GUI (títulos, status, botões, formato do lore)
scoreboard.*	Textos do scoreboard (título, separador, mensagens vazio/desativado)
console.*	Mensagens de inicialização e logs do console

Adicionar um novo idioma

1. Copie um arquivo existente (por exemplo lang/en-US.yml)
2. Renomeie-o com o código de idioma desejado (por exemplo lang/es-ES.yml)
3. Traduza todos os valores no arquivo
4. Na configuração do BetonQuest, defina language: es-ES
5. Recarregue o plugin com /questsreload

Formato MiniMessage

As chaves menu.* suportam o formato MiniMessage. Exemplos:

• <gold>Texto dourado</gold>
• <#55C4FF>Cor hex</#55C4FF>
• <gradient:#800080:#D33D22>Gradiente</gradient>
• <b>Negrito</b>, <st>Tachado</st>, <i>Itálico</i>

Scoreboard

O scoreboard exibe em tempo real os objetivos das quests acompanhadas pelo jogador.

scoreboard:
  enabled: true
  title: "<gradient:#800080:#D33D22>◈KGInfoServs Quests◈</gradient>"
  separator: "<gradient:#800080:#D33D22>--------------</gradient>"

Propriedade	Padrão	Descrição
enabled	true	Ativa/desativa o scoreboard globalmente para todos os jogadores. Se false, nenhum scoreboard é criado.
title	Gradiente roxo-vermelho	Título do scoreboard (formato MiniMessage)
separator	Gradiente roxo-vermelho	Separador entre as quests no scoreboard (formato MiniMessage)

Desempenho

Quando scoreboard.enabled: false, nenhum recurso é usado para o scoreboard (sem ticks, sem pacotes de rede, sem memória em cache). Esse é o método recomendado se você usa um plugin de scoreboard externo como o TAB.

Scoreboard orientado a eventos

O scoreboard não gera nenhum tick. Ele é atualizado apenas quando ocorre um evento (ativação de quest, progresso, mudança de etapa). Mesmo ativado, tem praticamente nenhum impacto no desempenho.

PlaceholderAPI

placeholders:
  enabled: true

Propriedade	Padrão	Descrição
enabled	true	Ativa/desativa os placeholders %kgquetes_*%

Desative se você não usa o PlaceholderAPI para reduzir as chamadas Redis/BDD.

Placeholders disponíveis

Prefixo: %kgquetes_

Placeholder	Descrição
%kgquetes_title%	Título da quest atualmente acompanhada
%kgquetes_objective_1%	Primeira linha de objetivo da quest acompanhada
%kgquetes_objective_2%	Segunda linha de objetivo
%kgquetes_objective_N%	N-ésima linha de objetivo

Pool de conexão do banco de dados (database)

database:
  pool:
    maxSize: 30
    minIdle: 5
    connectionTimeoutMs: 10000
    idleTimeoutMs: 300000

Propriedade	Padrão	Descrição
maxSize	30	Número máximo de conexões no pool do HikariCP
minIdle	5	Número mínimo de conexões inativas mantidas
connectionTimeoutMs	10000	Tempo máximo de espera para obter uma conexão (10s)
idleTimeoutMs	300000	Fecha as conexões inativas após 5 minutos

Dimensionamento de acordo com o número de jogadores

• ~100 jogadores: valores padrão (maxSize: 30)
• 500+ jogadores: aumente maxSize para 50
• 1000+ jogadores: aumente maxSize para 80-100

Atualização automática (updater)

updater:
  auto-download: false

Propriedade	Padrão	Descrição
auto-download	false	Se true, baixa automaticamente as novas versões em plugins/update/. O JAR será aplicado na próxima reinicialização do servidor.

A verificação de atualização é feita automaticamente na inicialização. Se uma nova versão estiver disponível, uma mensagem é exibida no console e os administradores são notificados ao entrar.

Você também pode forçar a verificação com /kgquests update.

Redis

redis:
  enabled: true
  host: "127.0.0.1"
  port: 6379
  password: ""

Propriedade	Padrão	Descrição
enabled	true	Ativa/desativa a sincronização Redis
host	"127.0.0.1"	Endereço do servidor Redis
port	6379	Porta do servidor Redis
password	""	Senha do Redis (vazio se nenhuma)

Veja Multi-servidor para a configuração detalhada.

---

quests_config.yml — Textos e etapas das quests

Este arquivo define o conteúdo textual, as etapas e os objetivos de cada quest exibida no menu e no scoreboard.

Suporte multilíngue

Todos os campos de texto (title, locked_description, finished_text, textos de etapas, inprogress/completed dos objetivos) suportam dois formatos:

Formato simples (um único idioma):

title: "<gold>O Tesouro Perdido</gold>"

Formato multilíngue (estilo BetonQuest):

title:
  fr-FR: "<gold>Le Tresor Perdu</gold>"
  en-US: "<gold>The Lost Treasure</gold>"

O idioma é lido a partir da configuração do BetonQuest (language: fr-FR no config.yml do BetonQuest). O fallback é: idioma configurado → primeiro idioma disponível → valor padrão.

Retrocompatibilidade

O formato antigo (texto simples sem chaves de idioma) permanece totalmente funcional. Você pode migrar progressivamente suas quests para o formato multilíngue.

Estrutura de uma quest

quests:
  ma_quete:
    title:
      fr-FR: "<gold>Le Tresor Perdu</gold>"
      en-US: "<gold>The Lost Treasure</gold>"
    locked_description:
      fr-FR: "Trouvez l'indice pour debloquer cette quete."
      en-US: "Find the clue to unlock this quest."
    finished_text:
      fr-FR: "Felicitations ! Vous avez trouve le tresor !"
      en-US: "Congratulations! You found the treasure!"
    steps:
      '1':
        text:
          fr-FR:
            - "Parlez au marchand du village"
            - "Achetez une carte au tresor"
          en-US:
            - "Talk to the village merchant"
            - "Buy a treasure map"
      '2':
        text:
          fr-FR:
            - "Suivez la carte jusqu'a la foret"
            - "Trouvez l'entree de la grotte"
          en-US:
            - "Follow the map to the forest"
            - "Find the cave entrance"

Referência das chaves

Chave	Obrigatória	Descrição
title	Sim	Título da quest (suporta MiniMessage, multilíngue)
locked_description	Não	Texto exibido quando a quest está bloqueada (multilíngue)
finished_text	Não	Texto exibido quando a quest está concluída (multilíngue, suporta | para multiline)
steps	Sim	Etapas da quest com objetivos

Formato das etapas (steps)

As etapas são numeradas a partir de 1. Três formatos são possíveis:

Formato simples (lista de textos)

steps:
  '1':
    - "Fale com o mercador"
    - "Compre um mapa"

Formato com seção text (multilíngue)

steps:
  '1':
    text:
      fr-FR:
        - "Parlez au marchand"
        - "Achetez une carte"
      en-US:
        - "Talk to the merchant"
        - "Buy a map"

Formato text simples

A seção text também aceita uma lista simples (sem chaves de idioma):

text:
  - "Fale com o mercador"
  - "Compre um mapa"

Formato com objetivos rastreáveis

Esse formato permite acompanhar o progresso individual de cada objetivo:

steps:
  '1':
    text:
      fr-FR:
        - "Parlez au marchand"
      en-US:
        - "Talk to the merchant"
    objectives:
      - id: "kill_zombies"
        inprogress:
          fr-FR: "Tuer des zombies (%betonquest_ma_quete:objective.kill_zombies.amount%/10)"
          en-US: "Kill zombies (%betonquest_ma_quete:objective.kill_zombies.amount%/10)"
        completed:
          fr-FR: "Tuer <green>10/10 Zombies <white>✔"
          en-US: "Kill <green>10/10 Zombies <white>✔"
      - id: "collect_wood"
        inprogress:
          fr-FR: "Collecter du bois (%betonquest_ma_quete:objective.collect_wood.amount%/20)"
          en-US: "Collect wood (%betonquest_ma_quete:objective.collect_wood.amount%/20)"
        completed:
          fr-FR: "Collecter <green>20/20 Bois <white>✔"
          en-US: "Collect <green>20/20 Wood <white>✔"

Propriedade	Descrição
id	Identificador do objetivo (deve corresponder ao objetivo do BetonQuest)
inprogress	Texto exibido quando o objetivo está em andamento (multilíngue, suporta placeholders)
completed	Texto exibido quando o objetivo está concluído (multilíngue)

Placeholders do BetonQuest nos objetivos

Use os placeholders do BetonQuest para exibir o progresso em tempo real:

• %betonquest_PACKAGE:objective.ID.amount% — Progresso atual
• %betonquest_PACKAGE:objective.ID.absoluteamount% — Total necessário
• %betonquest_PACKAGE:constant.KEY% — Constantes da quest

Exemplo: Matar zumbis (3/10) é atualizado automaticamente.

Exemplo completo

quests:
  histoire_chapitre1:
    title:
      fr-FR: "<gold>Le Reveil du Heros</gold>"
      en-US: "<gold>The Hero's Awakening</gold>"
    locked_description:
      fr-FR: "Commencez votre aventure en parlant au guide."
      en-US: "Start your adventure by talking to the guide."
    finished_text:
      fr-FR: |
        Vous avez fait vos premiers pas !
        Continuez votre aventure.
      en-US: |
        You took your first steps!
        Continue your adventure.
    steps:
      '1':
        text:
          fr-FR:
            - "Parlez au guide du village"
            - "Acceptez la quete"
          en-US:
            - "Talk to the village guide"
            - "Accept the quest"
      '2':
        text:
          fr-FR:
            - "Visitez la forge"
          en-US:
            - "Visit the forge"
        objectives:
          - id: "visit_forge"
            inprogress:
              fr-FR: "Se rendre a la forge"
              en-US: "Go to the forge"
            completed:
              fr-FR: "<green>- Forge visitee <white>✔"
              en-US: "<green>- Forge visited <white>✔"
          - id: "get_sword"
            inprogress:
              fr-FR: "Obtenir une epee"
              en-US: "Get a sword"
            completed:
              fr-FR: "<green>- Epee obtenue <white>✔"
              en-US: "<green>- Sword obtained <white>✔"
      '3':
        objectives:
          - id: "kill_dummies"
            inprogress:
              fr-FR: "Battre des mannequins (%betonquest_histoire_chapitre1:objective.kill_dummies.amount%/3)"
              en-US: "Beat training dummies (%betonquest_histoire_chapitre1:objective.kill_dummies.amount%/3)"
            completed:
              fr-FR: "Battre <green>3/3 Mannequins <white>✔"
              en-US: "Beat <green>3/3 Dummies <white>✔"

  daily_minerai:
    title:
      fr-FR: "<aqua>Collecte Quotidienne</aqua>"
      en-US: "<aqua>Daily Collection</aqua>"
    locked_description:
      fr-FR: "Disponible chaque jour."
      en-US: "Available every day."
    finished_text:
      fr-FR: "Beau travail, mineur !"
      en-US: "Good work, miner!"
    steps:
      '1':
        objectives:
          - id: "mine_iron"
            inprogress:
              fr-FR: "Miner du fer (%betonquest_daily_minerai:objective.mine_iron.amount%/32)"
              en-US: "Mine iron (%betonquest_daily_minerai:objective.mine_iron.amount%/32)"
            completed:
              fr-FR: "Miner <green>32/32 Fer <white>✔"
              en-US: "Mine <green>32/32 Iron <white>✔"
          - id: "mine_gold"
            inprogress:
              fr-FR: "Miner de l'or (%betonquest_daily_minerai:objective.mine_gold.amount%/16)"
              en-US: "Mine gold (%betonquest_daily_minerai:objective.mine_gold.amount%/16)"
            completed:
              fr-FR: "Miner <green>16/16 Or <white>✔"
              en-US: "Mine <green>16/16 Gold <white>✔"

Aplicar as alterações

1. Modifique config.yml, quests_config.yml ou os arquivos em lang/
2. Execute /questsreload
3. Verifique no jogo

Veja também

• Integração com o BetonQuest — Configurar eventos e tags
• Comandos — Comandos de recarregamento
• Multi-servidor — Configuração do Redis