BetonQuest Integration

QuestsTracker integrates deeply with BetonQuest. This page explains how to configure your quests so they appear in the menu and tracking.

How it works

1. A quest must use the trackedQuest template to appear in the menu
2. The status (locked/active/completed) is managed by custom events
3. Progress is tracked via the nextStep and kgcomplete events

trackedQuest template

For a quest to appear in the QuestsTracker menu, its BetonQuest package must use the trackedQuest template.

Defining the template

In your quest's package.yml file:

templates:
  - trackedQuest

questParameters:
  questCategory: story  # Must match the configKey of a category in config.yml

Template required

Without the trackedQuest template, the quest is invisible in the menu, even if all the events are correctly configured.

BetonQuest tags

The status of each quest is determined by internal tags managed automatically by the plugin's events:

Tag	Role
{questId}.questTrackable	The quest is unlocked (visible in the menu)
{questId}.tracked	The quest is in progress (Active status)
{questId}.finished	The quest is completed (Completed status)

Internal tags

These tags are managed automatically by the plugin's events. You never need to manipulate them manually. Use the activeQuest, finishQuest and lockQuest events instead.

Quest lifecycle

Locked  →  Active  →  Completed
 (no tag)    (.questTrackable + .tracked)    (.questTrackable + .finished)

1. The quest is locked by default (no tag)
2. The activeQuest event adds the .questTrackable and .tracked tags → the quest becomes active
3. The player can then track it in the scoreboard (up to 3 simultaneous quests)
4. The finishQuest event removes .tracked and adds .finished → the quest is completed
5. The lockQuest event removes all tags → the quest goes back to locked

Custom events

QuestsTracker registers 5 events in BetonQuest:

activeQuest

Activates a quest — makes it visible and available in the menu.

events:
  activer_quete: "activeQuest ma_quete"

Effects:

• Adds the ma_quete.questTrackable and ma_quete.tracked tags
• The quest switches to Active status
• It appears in the player's menu
• If the category has autoTrack: true, the quest is automatically tracked in the scoreboard (up to 3 slots). If all 3 slots are occupied, a non-autoTrack quest is replaced first.

lockQuest

Locks a quest — makes it unavailable in the menu.

events:
  verrouiller_quete: "lockQuest ma_quete"

Effects:

• Removes the ma_quete.questTrackable, ma_quete.tracked and ma_quete.finished tags
• The quest switches to Locked status
• It appears as locked in the menu (or is hidden, depending on the player's preferences)

finishQuest

Completes a quest.

events:
  terminer_quete: "finishQuest ma_quete"

Effects:

• Removes the ma_quete.tracked tag and adds ma_quete.finished
• The quest switches to Completed status
• It remains visible in the menu if the player shows completed quests
• It is removed from scoreboard tracking and its progress is cleared

nextStep

Advances a quest to its next step.

events:
  etape_suivante: "nextStep ma_quete"

Effects:

• Increments the quest's step number
• Updates the scoreboard in real time with the new objectives
• Resets the completed objectives from the previous step

kgcomplete

Marks a specific objective as completed in the current step.

events:
  objectif_fait: "kgcomplete ma_quete mon_objectif"

Two parameters required

The kgcomplete event requires two parameters: the package ID and the objective ID. The objective ID must match the id field in the objectives section of quests_config.yml.

Effects:

• Marks the mon_objectif objective as completed
• Updates the display in the scoreboard (inprogress text → completed text)
• Useful for steps with several independent objectives

Quest parameters (questParameters)

The questParameters block in package.yml configures how the quest appears in the menu:

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

Parameter	Required	Description
questCategory	No	Menu category (default: defaultCategory from config.yml)
questReward	No	Reward text displayed in the menu lore (multilingual, \n for line breaks)

Category

The value of questCategory must match exactly the configKey (the YAML key) of a category defined in config.yml.

Category mapping

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

Why the configKey?

The configKey is the stable identifier of the category. It does not change if you translate the displayName or modify it. Your BetonQuest packages stay functional even if the menu display changes.

Migrating from an older version

Before this version, questCategory had to match the displayName (e.g. "Story"). If you are upgrading, update your packages:

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

Without this migration, all your quests will fall back to the default category (other in most cases).

Subcategories

To place a quest in a subcategory, use the dotted format combining the configKeys:

questParameters:
  questCategory: dailyQuests.monsters

The format is: configKey_category.configKey_subcategory

Default category

If questCategory is not specified, the quest is placed in the category defined by defaultCategory in config.yml.

Complete example

BetonQuest file (package.yml)

templates:
  - trackedQuest

questParameters:
  questCategory: story

conversations:
  guide_intro:
    quester: "Guide"
    first: "start"
    NPC_options:
      start:
        text: "Welcome! Are you ready for your first quest?"
        pointer: accepter,refuser
    player_options:
      accepter:
        text: "Oui, je suis pret !"
        events: activer_quete
      refuser:
        text: "Pas encore..."

events:
  # Activate the quest
  activer_quete: "activeQuest premiere_quete"

  # Move to step 2
  etape2: "nextStep premiere_quete"

  # Mark an objective as completed (2 params: package + objective)
  objectif_forge: "kgcomplete premiere_quete visiter_forge"

  # Complete the 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

Corresponding quests_config.yml file

The file supports the multilingual format (recommended) and the old simple format. The language is determined by the language parameter in the BetonQuest config.

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>✔"

info

The old format (plain text without language keys) remains functional. See the quests_config.yml documentation for all the details on the multilingual format.

Workflow for creating a quest

1. Create the BetonQuest package with the trackedQuest template
2. Set the category with questCategory (must match the configKey of a category in config.yml)
3. Add the events (activeQuest, nextStep, kgcomplete, finishQuest)
4. Configure the texts and steps in quests_config.yml
5. Reload: /bq reload then /questsreload
6. Test in-game

Interaction with /bq reload

When you run /bq reload, QuestsTracker automatically detects the reload and:

• Re-indexes quests by category
• Invalidates the cache
• Updates the scoreboard

You do not need to run /questsreload after a /bq reload for changes to BetonQuest packages.

See also

• Configuration — Categories, subcategories and quests_config.yml
• Commands — Reload commands
• Troubleshooting — Issues related to BetonQuest