Integração com o BetonQuest

O QuestsTracker se integra profundamente com o BetonQuest. Esta página explica como configurar suas quests para que apareçam no menu e no acompanhamento.

Princípio de funcionamento

1. Uma quest deve usar o template trackedQuest para aparecer no menu
2. O status (bloqueada/ativa/concluída) é gerenciado por events personalizados
3. O progresso é acompanhado pelos events nextStep e kgcomplete

Template trackedQuest

Para que uma quest apareça no menu do QuestsTracker, seu pacote BetonQuest deve usar o template trackedQuest.

Definir o template

No arquivo package.yml da sua quest:

templates:
  - trackedQuest

questParameters:
  questCategory: story  # Deve corresponder ao configKey de uma categoria do config.yml

Template obrigatório

Sem o template trackedQuest, a quest fica invisível no menu, mesmo que todos os events estejam corretamente configurados.

Tags do BetonQuest

O status de cada quest é determinado por tags internas gerenciadas automaticamente pelos events do plugin:

Tag	Função
{questId}.questTrackable	A quest está desbloqueada (visível no menu)
{questId}.tracked	A quest está em andamento (status Ativo)
{questId}.finished	A quest está concluída (status Concluído)

Tags internas

Essas tags são gerenciadas automaticamente pelos events do plugin. Você nunca precisa manipulá-las manualmente. Use os events activeQuest, finishQuest e lockQuest em vez disso.

Ciclo de vida de uma quest

Bloqueada  →  Ativa  →  Concluída
 (nenhuma tag)    (.questTrackable + .tracked)    (.questTrackable + .finished)

1. A quest fica bloqueada por padrão (nenhuma tag)
2. O event activeQuest adiciona as tags .questTrackable e .tracked → a quest se torna ativa
3. O jogador pode então acompanhá-la no scoreboard (até 3 quests simultâneas)
4. O event finishQuest remove .tracked e adiciona .finished → a quest fica concluída
5. O event lockQuest remove todas as tags → a quest volta a ficar bloqueada

Events personalizados

O QuestsTracker registra 5 events no BetonQuest:

activeQuest

Ativa uma quest — a torna visível e disponível no menu.

events:
  activer_quete: "activeQuest ma_quete"

Efeitos:

• Adiciona as tags ma_quete.questTrackable e ma_quete.tracked
• A quest passa ao status Ativo
• Ela aparece no menu do jogador
• Se a categoria tiver autoTrack: true, a quest é acompanhada automaticamente no scoreboard (até 3 slots). Se os 3 slots estiverem ocupados, uma quest não-autoTrack é substituída com prioridade.

lockQuest

Bloqueia uma quest — a torna indisponível no menu.

events:
  verrouiller_quete: "lockQuest ma_quete"

Efeitos:

• Remove as tags ma_quete.questTrackable, ma_quete.tracked e ma_quete.finished
• A quest passa ao status Bloqueado
• Ela aparece como bloqueada no menu (ou fica oculta, dependendo das preferências do jogador)

finishQuest

Conclui uma quest.

events:
  terminer_quete: "finishQuest ma_quete"

Efeitos:

• Remove a tag ma_quete.tracked e adiciona ma_quete.finished
• A quest passa ao status Concluído
• Ela permanece visível no menu se o jogador exibir as quests concluídas
• Ela é removida do acompanhamento no scoreboard e o progresso é apagado

nextStep

Avança para a etapa seguinte de uma quest.

events:
  etape_suivante: "nextStep ma_quete"

Efeitos:

• Incrementa o número da etapa da quest
• Atualiza o scoreboard em tempo real com os novos objetivos
• Reinicia os objetivos concluídos da etapa anterior

kgcomplete

Marca um objetivo específico como concluído na etapa atual.

events:
  objectif_fait: "kgcomplete ma_quete mon_objectif"

Dois parâmetros obrigatórios

O event kgcomplete requer dois parâmetros: o ID do pacote e o ID do objetivo. O ID do objetivo deve corresponder ao campo id na seção objectives do quests_config.yml.

Efeitos:

• Marca o objetivo mon_objectif como concluído
• Atualiza a exibição no scoreboard (texto inprogress → texto completed)
• Útil para etapas com vários objetivos independentes

Parâmetros de quest (questParameters)

O bloco questParameters no package.yml configura como a quest aparece no menu:

questParameters:
  questCategory: story
  questReward:
    fr-FR: "100 pieces d'or\nEpee en diamant"
    en-US: "100 gold coins\nDiamond sword"

Parâmetro	Obrigatório	Descrição
questCategory	Não	Categoria do menu (padrão: defaultCategory do config.yml)
questReward	Não	Texto das recompensas exibido no lore do menu (multilíngue, \n para quebras de linha)

Categoria

O valor de questCategory deve corresponder exatamente ao configKey (a chave YAML) de uma categoria definida em config.yml.

Correspondência de categorias

config.yml (configKey)	config.yml (displayName)	BetonQuest (questCategory)
story	"Histoire" / "Story"	questCategory: story
secondary	"Secondaires" / "Secondary"	questCategory: secondary
dailyQuests	"Journalieres" / "Daily"	questCategory: dailyQuests
other	"Autres" / "Other"	questCategory: other

Por que o configKey?

O configKey é o identificador estável da categoria. Ele não muda se você traduzir o displayName ou modificá-lo. Seus pacotes BetonQuest continuam funcionais mesmo que a exibição do menu evolua.

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

Antes desta versão, questCategory devia corresponder ao displayName (ex: "Story"). Se você atualizar, modifique seus pacotes:

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

Sem essa migração, suas quests cairão todas na categoria padrão (other na maioria das vezes).

Subcategorias

Para colocar uma quest em uma subcategoria, use o formato com ponto combinando os configKey:

questParameters:
  questCategory: dailyQuests.monsters

O formato é: configKey_categoria.configKey_subcategoria

Categoria padrão

Se questCategory não for especificado, a quest é colocada na categoria definida por defaultCategory em config.yml.

Exemplo completo

Arquivo BetonQuest (package.yml)

templates:
  - trackedQuest

questParameters:
  questCategory: story

conversations:
  guide_intro:
    quester: "Guide"
    first: "start"
    NPC_options:
      start:
        text: "Bem-vindo! Você está pronto para sua primeira quest?"
        pointer: accepter,refuser
    player_options:
      accepter:
        text: "Sim, estou pronto!"
        events: activer_quete
      refuser:
        text: "Ainda não..."

events:
  # Ativar a quest
  activer_quete: "activeQuest premiere_quete"

  # Avançar para a etapa 2
  etape2: "nextStep premiere_quete"

  # Marcar um objetivo como concluído (2 params: pacote + objetivo)
  objectif_forge: "kgcomplete premiere_quete visiter_forge"

  # Concluir a quest
  fin_quete: "finishQuest premiere_quete"

objectives:
  visiter_forge:
    type: location
    location: "100;64;200;world;5"
    events: objectif_forge,etape2

  battre_mannequins:
    type: mobkill
    mob: ZOMBIE
    amount: 3
    events: fin_quete

Arquivo quests_config.yml correspondente

O arquivo suporta o formato multilíngue (recomendado) e o antigo formato simples. O idioma é determinado pelo parâmetro language na configuração do BetonQuest.

quests:
  premiere_quete:
    title:
      fr-FR: "<gold>Le Reveil du Heros</gold>"
      en-US: "<gold>The Hero's Awakening</gold>"
    locked_description:
      fr-FR: "Parlez au guide du village pour commencer."
      en-US: "Talk to the village guide to begin."
    finished_text:
      fr-FR: "Vous avez fait vos premiers pas !"
      en-US: "You took your first steps!"
    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: "visiter_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>✔"
      '3':
        objectives:
          - id: "battre_mannequins"
            inprogress:
              fr-FR: "Battre des mannequins (%betonquest_premiere_quete:objective.battre_mannequins.amount%/3)"
              en-US: "Beat training dummies (%betonquest_premiere_quete:objective.battre_mannequins.amount%/3)"
            completed:
              fr-FR: "Battre <green>3/3 Mannequins <white>✔"
              en-US: "Beat <green>3/3 Dummies <white>✔"

informação

O formato antigo (texto simples sem chaves de idioma) continua funcional. Veja a documentação do quests_config.yml para todos os detalhes sobre o formato multilíngue.

Fluxo de criação de uma quest

1. Criar o pacote BetonQuest com o template trackedQuest
2. Definir a categoria com questCategory (deve corresponder ao configKey de uma categoria em config.yml)
3. Adicionar os events (activeQuest, nextStep, kgcomplete, finishQuest)
4. Configurar os textos e etapas em quests_config.yml
5. Recarregar: /bq reload seguido de /questsreload
6. Testar no jogo

Interação com /bq reload

Quando você executa /bq reload, o QuestsTracker detecta automaticamente o reload e:

• Reindexa as quests por categoria
• Invalida o cache
• Atualiza o scoreboard

Você não precisa executar /questsreload após um /bq reload para mudanças em pacotes BetonQuest.

Veja também

• Configuração — Categorias, subcategorias e quests_config.yml
• Comandos — Comandos de recarregamento
• Solução de problemas — Problemas relacionados ao BetonQuest