Integracao BetonQuest

O QuestsTracker se integra profundamente com o BetonQuest. Esta pagina explica como configurar suas quests para que aparecam no menu e no acompanhamento.

Principio de funcionamento

1. Uma quest deve usar o template trackedQuest para aparecer no menu
2. O status (bloqueado/ativo/concluido) e gerenciado por events personalizados
3. O progresso e acompanhado pelos events nextStep e kgcomplete

Template trackedQuest

Para que uma quest apareca no menu QuestsTracker, seu pacote BetonQuest deve utilizar o template trackedQuest.

Definir o template

No arquivo package.yml da sua quest:

templates:
  - trackedQuest

questParameters:
  questCategory: "Story"  # Deve corresponder ao displayName de uma categoria

Template obrigatorio

Sem o template trackedQuest, a quest e invisivel no menu, mesmo que todos os events estejam corretamente configurados.

Tags BetonQuest

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

Tag	Papel
{questId}.questTrackable	Quest desbloqueada (visivel no menu)
{questId}.tracked	Quest em andamento (status Ativo)
{questId}.finished	Quest concluida (status Concluido)

Tags internas

Essas tags sao gerenciadas automaticamente pelos events do plugin. Voce nunca precisa manipula-las manualmente. Use os events activeQuest, finishQuest e lockQuest.

Ciclo de vida de uma quest

Bloqueada  →  Ativa  →  Concluida
 (nenhuma tag)    (.questTrackable + .tracked)    (.questTrackable + .finished)

1. A quest esta bloqueada por padrao (nenhuma tag)
2. O event activeQuest adiciona as tags .questTrackable e .tracked → a quest se torna ativa
3. O jogador pode entao acompanha-la no scoreboard (ate 3 quests simultaneas)
4. O event finishQuest remove .tracked e adiciona .finished → a quest esta concluida
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 visivel e disponivel no menu.

events:
  activer_quete: "activeQuest ma_quete"

Efeitos:

• Adiciona as tags ma_quete.questTrackable e ma_quete.tracked
• A quest passa para o status Ativo
• Ela aparece no menu do jogador
• Se a categoria tem autoTrack: true, a quest e automaticamente acompanhada no scoreboard (ate 3 slots). Se os 3 slots estiverem ocupados, uma quest nao-autoTrack e substituida primeiro.

lockQuest

Bloqueia uma quest — a torna indisponivel 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 para o status Bloqueado
• Ela aparece como bloqueada no menu (ou e oculta de acordo com as preferencias 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 para o status Concluido
• Ela permanece visivel no menu se o jogador exibir as quests concluidas
• Ela e removida do acompanhamento do scoreboard e os dados de progresso sao apagados

nextStep

Avanca para a proxima etapa de uma quest.

events:
  etape_suivante: "nextStep ma_quete"

Efeitos:

• Incrementa o numero da etapa da quest
• Atualiza o scoreboard em tempo real com os novos objetivos
• Reinicia os objetivos concluidos da etapa anterior

kgcomplete

Marca um objetivo especifico como concluido na etapa atual.

events:
  objectif_fait: "kgcomplete ma_quete mon_objectif"

Dois parametros obrigatorios

O event kgcomplete requer dois parametros: o ID do pacote e o ID do objetivo. O ID do objetivo deve corresponder ao campo id na secao objectives do quests_config.yml.

Efeitos:

• Marca o objetivo mon_objectif como concluido
• Atualiza a exibicao no scoreboard (texto inprogress → texto completed)
• Util para etapas com varios objetivos independentes

Parametros da 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"

Parametro	Obrigatorio	Descricao
questCategory	Nao	Categoria do menu (padrao: defaultCategory do config.yml)
questReward	Nao	Texto de recompensas exibido no lore do menu (multilingue, \n para quebras de linha)

Categoria

O valor de questCategory deve corresponder exatamente ao displayName de uma categoria definida no config.yml.

Correspondencia de categorias

config.yml (chave)	config.yml (displayName)	BetonQuest (questCategory)
story	"Story"	questCategory: "Story"
secondary	"Secondary"	questCategory: "Secondary"
dailyQuests	"Daily"	questCategory: "Daily"

Sensivel a maiusculas/minusculas e acentos

"Story" ≠ "story" ≠ "STORY". Use exatamente o mesmo texto que o displayName da sua categoria.

Subcategorias

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

questParameters:
  questCategory: "Daily.Monsters"

O formato e: displayName_categoria.displayName_subcategoria

Categoria padrao

Se questCategory nao for especificada, a quest e colocada na categoria definida por defaultCategory no config.yml.

Exemplo completo

Arquivo BetonQuest (package.yml)

templates:
  - trackedQuest

questParameters:
  questCategory: "Story"

conversations:
  guide_intro:
    quester: "Guide"
    first: "start"
    NPC_options:
      start:
        text: "Bienvenue ! Etes-vous pret pour votre premiere quete ?"
        pointer: accepter,refuser
    player_options:
      accepter:
        text: "Oui, je suis pret !"
        events: activer_quete
      refuser:
        text: "Pas encore..."

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

  # Avancar para a etapa 2
  etape2: "nextStep premiere_quete"

  # Marcar um objetivo como concluido
  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

quests:
  premiere_quete:
    title: "<gold>Le Reveil du Heros</gold>"
    locked_description: "Parlez au guide du village pour commencer."
    finished_text: "Vous avez fait vos premiers pas !"
    steps:
      '1':
        - "Parlez au guide du village"
        - "Acceptez la quete"
      '2':
        text:
          - "Visitez la forge"
        objectives:
          - id: "visiter_forge"
            inprogress: "Se rendre a la forge"
            completed: "<st>Forge visitee</st>"
      '3':
        objectives:
          - id: "battre_mannequins"
            inprogress: "Battre des mannequins (%betonquest_premiere_quete:objective.battre_mannequins.amount%/3)"
            completed: "<st>Mannequins battus (3/3)</st>"

Fluxo de criacao de uma quest

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

Interacao com /bq reload

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

• Re-indexa as quests por categoria
• Invalida o cache
• Atualiza o scoreboard

Voce nao precisa executar /questsreload apos um /bq reload para as mudancas nos pacotes BetonQuest.

Veja tambem

• Configuracao — Categorias, subcategorias e quests_config.yml
• Comandos — Comandos de recarga
• Solucao de problemas — Problemas relacionados ao BetonQuest