BetonQuest Integration

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

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 displayName of a category

Required template

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

BetonQuest tags

The status of each quest is determined by tags:

Tag	Meaning
{questId}.questTrackable	Quest unlocked (visible in menu)
{questId}.tracked	Quest in progress (Active)
{questId}.finished	Quest completed

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
4. The finishQuest event removes .tracked and adds .finished -- the quest is completed
5. The lockQuest event removes all tags -- the quest returns to locked

Custom events

QuestsTracker registers 5 events in BetonQuest:

activeQuest

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

events:
  activate_quest: "activeQuest my_quest"

Effects:

• Adds the my_quest.questTrackable and my_quest.tracked tags
• The quest changes 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:
  lock_quest: "lockQuest my_quest"

Effects:

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

finishQuest

Completes a quest.

events:
  finish_quest: "finishQuest my_quest"

Effects:

• Removes the my_quest.tracked tag and adds my_quest.finished
• Progress data is cleared
• The quest changes to Completed status
• It remains visible in the menu if the player shows completed quests
• It is removed from scoreboard tracking

nextStep

Advances to the next step of a quest.

events:
  next_step: "nextStep my_quest"

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:
  objective_done: "kgcomplete my_quest my_objective"

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 objective my_objective as completed
• Updates the scoreboard display (inprogress text changes to completed text)
• Useful for steps with multiple independent objectives

Quest parameters (questParameters)

Each quest can specify parameters in its BetonQuest package.yml:

questParameters:
  questCategory: "Story"
  questReward:
    fr-FR: "100 gold coins\nDiamond sword"
    en-US: "100 gold coins\nDiamond sword"

Parameter	Required	Default	Description
questCategory	No	Default category from config.yml	Category in which the quest appears in the menu. Must match exactly the displayName of a category defined in config.yml.
questReward	No	--	Reward text displayed in the menu lore. Supports multilingual format. Use \n for line breaks.

Category mapping

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

Case-sensitive and accent-sensitive

"Story" is not the same as "story" or "STORY". Use exactly the same text as the displayName of your category.

Subcategories

To place a quest in a subcategory, use the dot format:

questParameters:
  questCategory: "Daily.Monsters"

The format is: category_displayName.subcategory_displayName

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: "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:
  # Activate the quest
  activer_quete: "activeQuest premiere_quete"

  # Advance to step 2
  etape2: "nextStep premiere_quete"

  # Mark an objective as completed
  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

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

Quest creation workflow

1. Create the BetonQuest package with the trackedQuest template
2. Define the category with questCategory (must match the displayName)
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 BetonQuest package changes.

See also

• Configuration -- Categories, subcategories, and quests_config.yml
• Commands -- Reload commands
• Troubleshooting -- BetonQuest-related issues