Skip to content

Migration 2.X to 3.X

This guide explains how to migrate from the latest BetonQuest 2.X version to BetonQuest 3.X.

The majority of changes will be migrated automatically. However, some things must be migrated manually.

Warning

Before you start migrating, you should back up your server!

Info

You need to set legacy as version in your package.yml (for both QuestPackages and -Templates) to automatically migrate from "not versioned".

Required version
package:
  version: legacy

Changes🔗

Note

  • ☀ Fully automated migration – These steps are reliably migrated without issues in most cases. You usually don’t need to take any action. However, certain rarely used or non-standard formats (e.g., run events or math variables) may not migrate correctly if they deviate from the common structure.
  • 🌥 Automated migration with known limitations – These steps are generally migrated automatically, especially for straightforward cases. However, there are known edge cases that cannot be detected or handled automatically. You should review these steps and be prepared to make manual adjustments where needed.
  • ⛈ Manual migration required – These steps are not migrated at all. Either the structure is too complex to detect automatically, or the new format requires additional information. You will need to fully rewrite or convert these steps yourself.

3.0.0-DEV-58 - Delete messages.yml ⛈🔗

The messages.yml file has been removed. All messages are now stored in the lang folder, you can also customize them there and add new languages. If you still have the old messages.yml file, you get a warning in the console. If you don't have any custom messages, you can delete the file safely otherwise you should move the messages to the new location.

3.0.0-DEV-65 - Delete menuConfig.yml ⛈🔗

The menuConfig.yml file has been removed. If you had the option default_close configured, you can now find this option in the config.yml file. All translations in the config where also moved to the lang folder, so also here you need to move your custom translations.

3.0.0-DEV-71 - Renamed Translation Keys ☀🔗

Automated Migration

The migration is automated. You shouldn't have to do anything.

All translations where moved from the messages.yml file to individual files in the lang folder. Also all keys for the langusges have been renamed to match the new lang-region format, where lang and region are always two letters.
So the mapping of the old to the new keys is as follows:

Old Key New Key Old Key New Key Old Key New Key Old Key New Key
en en-US de de-DE es es-ES fr fr-FR
hu hu-HU it it-IT nl nl-NL pl pl-PL
pt-br pt-BR pt-pt pt-PT ru ru-RU vi vi-VN
cn zh-CN

If you have custom translations, you need to move them to the new lang folder. Because the keys have been renamed, you need to rename the keys in some parts of config files and scripts.

new config.yml
    language: en-US
Old Syntax Events
events:
  notify: notify {en} English text {de} Deutscher text
New Syntax Events
events:
  notify: notify {en-US} English text {de-DE} Deutscher text

And the most complicated change is everywhere you used multiple languages in sections, here is only one example:

Old Conversation
conversations:
  unkown:
    quester:
      en: Jane Doe
      de: Erika Mustermann
New Conversation
conversations:
  unkown:
    quester:
      en-US: Jane Doe
      de-DE: Erika Mustermann

The same applies to all other sections where you used multiple languages, this should be a complete list:

  • conversations.*.quester
  • conversations.*.NPC_options.*.text
  • conversations.*.player_options.*.text
  • compass.*.name
  • cancel.*.name
  • journal.*
  • journal_main_page.*.text
  • menus.*.items.*.text

3.0.0-DEV-114 - Npc Rework ⛈🔗

To support more Npc plugins than just Citizens the system got a rework.

Npcs are now addressed with IDs and defined in the npcs section. Starting conversations with Npc interaction is moved inside the npc_conversations section.

Also, the teleportnpc event got renamed to npcteleport. That change is automated, when updating to version 3.0.0-DEV-299 or newer.

In addition, the npc variable to get the quester name of the current conversation got changed to quester. That change is automated.

You can keep most of the syntax when you use the Citizens Npc id as their BetonQuest identifier, but changing the "name" makes the difference more clear.

Also, the citizens_npcs_by_name configuration option was removed in favor of the byName argument.

Old Syntax
npcs:
  '0': "HansConv" #(1)!
  '1': "HansConv"
events:
  teleportNpc: teleportnpc 0 100;200;300;world #(2)!
conditions:
  nearNpc: npcdistance 0 10 #(2)!
  nearNpcTwo: npcdistance 1 10
conversations:
  HansConv: #(3)!
    quester: Hans
    first: Hello
    NPC_options:
      Hello:
        text: Hello Adventurer!
  1. The conversation the interaction with the Npc will start.
  2. The 0 is here the citizens npc id.
  3. The conversation name as used in the npcs section.
New Syntax
npcs:
  0: "citizens 0" #(1)!
  HansTwo: "citizens 1" #(2)!

npc_conversations:
  0: HansConv #(3)!
  HansTwo: HansConv #(4)!
events:
  teleportNpc: npcteleport 0 100;200;300;world #(3)!
conditions:
  nearNpc: npcdistance 0 10 #(3)!
  nearNpcTwo: npcdistance HansTwo 15 #(4)!
conversations:
  HansConv:
    quester: Hans
    first: Hello
    NPC_options:
      Hello:
        text: Hello Adventurer!
  1. The 0 before the ':' is now the BetonQuest ID, where the citizens 0 defines the Npc with id "0" from the Citizens integration.
  2. Here we use a name for the id to make the difference more clear.
  3. The 0 is here the BetonQuest NpcID but stays the same.
  4. An example of a "renamed" reference.
  5. The Npcs that start this conversation.

3.0.0-DEV-135 - Citizens Adaption to NpcID ⛈🔗

To streamline usage of Npcs the Citizens specific events and objective now also use the NpcID introduced in 3.0.0-DEV-114.

Also, the movenpc and stopnpc events are renamed into npcmove and npcstop. These renames are automated, when updating to version 3.0.0-DEV-299 or newer.

As in the migration above stated you can either use a descriptive name as the id or use the numeric Citizens id of the Npc.

Old Syntax
events:
  move: movenpc 0 100;200;300;world #(1)!
  stop: stopnpc 0
objectives:
  kill: npckill 1 amount:5 events:reward
  1. The 0 is here the citizens npc id.
New Syntax
npcs:
  0: "citizens 0" #(1)!
  thief: "citizens thief byName"

events:
  move: npcmove 0 100;200;300;world
  stop: npcstop 0 #(2)!
objectives:
  kill: npckill thief amount:5 events:reward
  1. The 0 before the ':' is now the BetonQuest ID, where the citizens 0 defines the Npc with id "0" from the Citizens integration.
  2. The 0 is here the BetonQuest NpcID but stays the same.

3.0.0-DEV-142 - Conversation Sounds ⛈🔗

The start and stop sound in the configuration for conversations were removed in favor of the notification system, that now also has the two new build in categories conversation_start and conversation_end. Also the messages it self are now printed in every conversation and can now be configured with the notification system.

To get the previous sounds back, you need to configure it now like the following in any quest package:

Old Syntax (config.yml)
sounds:
  start: ENTITY_VILLAGER_AMBIENT
  end: ENTITY_VILLAGER_YES
New Syntax
notifications:
  conversation_start:
    sound: ENTITY_VILLAGER_AMBIENT
  conversation_end:
    sound: ENTITY_VILLAGER_YES

If you want to disable the the start and end message, now you can configure the following:

Disable Messages
notifications:
  conversation_start:
    io: suppress
  conversation_end:
    io: suppress

and if you only want sounds and no message, you use sound instead of suppress as io.

3.0.0-DEV-217 - Item Type ☀🔗

Automated Migration

The migration is automated. You shouldn't have to do anything.

To allow usage of 3rd-party items in QuestItems the standard definition is now prefixed with simple.

Old Syntax
items:
  blizz: "DIAMOND_SWORD name:The_Blizz lore:Made_of_Ice"
New Syntax
items:
  blizz: "simple DIAMOND_SWORD name:The_Blizz lore:Made_of_Ice"

3.0.0-DEV-232 - Singular to Plural ☀🔗

Automated Migration

The migration is automated. You shouldn't have to do anything.

BetonQuest allows a lot of lists (comma separated values) to reference for example events and conditions. In the past the key of those lists was always event or condition. Then someone introduced the first plural events and conditions, and so the project supported both. As this leads into a lot of bad code and confusion, we decided to remove the singular version. Therefore the follorwing changes were made:

  • objectives - event and condition are now events and conditions
  • events - condition is now conditions
  • menus - condition is now conditions
  • conversations - options condition, event, pointer and extend are now conditions, events, pointers and extends
Old Syntax
objectives:
  action: action LEFT ANY global persistent event:notify condition:sneak
New Syntax
objectives:
  action: action LEFT ANY global persistent events:notify conditions:sneak

3.0.0-DEV-233 - pickrandom event ☀🔗

Automated Migration

The migration is automated. You shouldn't have to do anything.

To allow a list of events also containing variables in any form, it is not possible anymore to use the percentage, instead the tilde ~ is used to separate the chance from the event.

Old Syntax
events:
  pickRandom: pickrandom 1%pickRandom1,2%pickRandom2,3%pickRandom3
New Syntax
events:
  pickRandom: pickrandom 1~pickRandom1,2~pickRandom2,3~pickRandom3

3.0.0-DEV-244 - Menu Item move ☀🔗

Automated Migration

The migration is automated. You shouldn't have to do anything.

To use a Menu Item in multiple Menus they are now defined in their own menu_items section.

Old Syntax
menus:
  questMenu:
    height: 4
    title: "&6&lQuests"
    bind: "openMenuItem"
    command: "/quests"
    slots:
      4: "reputation"
      5-8: "filler,filler,filler,filler"

    items:
      reputation:
        item: "xpBottle"
        amount: 1
        text:
            - "&2Quest Level: &6&l%point.quest_reputation.amount%"
        close: true
      filler:
        text: "&a "
        item: "filler"
New Syntax
menus:
  questMenu:
    height: 4
    title: "&6&lQuests"
    bind: "openMenuItem"
    command: "/quests"
    slots:
      4: "reputation"
      5-8: "filler,filler,filler,filler"

menu_items:
  reputation:
    item: "xpBottle"
    amount: 1
    text:
        - "&2Quest Level: &6&l%point.quest_reputation.amount%"
    close: true
  filler:
    text: "&a "
    item: "filler"

3.0.0-DEV-267 - MoonPhase rename ☀🔗

Automated Migration

The migration is automated. You shouldn't have to do anything.

The mooncycle condition was renamed to moonphase and instead of numbers, which stood for the mood phases, the names of the moon phases are now used directly.

Old Syntax
conditions:
  mooncycle: mooncycle 1
  otherMooncycle: mooncycle 2 world:world
New Syntax
conditions:
  moonphase: moonphase NEW_MOON
  otherMoonphase: moonphase FULL_MOON world:world

3.0.0-DEV-274 - String List remove ☀🔗

Automated Migration

The migration is automated. You shouldn't have to do anything.

All string lists (lists that are new lines with dashes) at unusual places are now replaced with a comma separated list. This includes:

  • npcs in the npc_holograms section
  • npcs, conditions and locations in the effectlib section
Old Syntax
effectlib:
  effect1:
    class: VortexEffect
    npcs:
      - NPC1
      - NPC2
      - NPC3
New Syntax
effectlib:
  effect1:
    class: VortexEffect
    npcs: NPC1,NPC2,NPC3

3.0.0-DEV-277 - Rename Constants 🌥🔗

Automated Migration

The migration is automated. You shouldn't have to do anything.

"Global Variables" have been replaced by "Constants" to better reflect their purpose and also to integrate them into the existing variable system.

Old Syntax
variables:
  MyVariable: Hello
  MyCustomVariable: $MyVariable$ World
events:
  sendNotify: notify $MyCustomVariable$
New Syntax
constants:
  MyVariable: Hello
  MyCustomVariable: %constant.MyVariable% World
events:
  sendNotify: notify %constant.MyCustomVariable%

3.0.0-DEV-284 - Change Head Owner ☀🔗

Automated Migration

The migration is automated. You shouldn't have to do anything.

To allow pre-parsing of constant variables in simple Quest Items the owner:%player% has been replaced with owner:.

Old Syntax
items:
  head: simple PLAYER_HEAD owner:%player%
New Syntax
items:
  head: 'simple PLAYER_HEAD owner:'

3.0.0-DEV-299 - NPC events rename ☀🔗

Automated Migration

The migration is automated. You shouldn't have to do anything.

Some NPC events were renamed in the versions 3.0.0-DEV-114 - Npc Rework and 3.0. 0-DEV-135 - Citizens Adaption to NpcID. These renames are automated now.

3.0.0-DEV-306 - MMOItems Item Type ⛈🔗

MMOItems is now integrated into the item system.

Instead of using mmo specific pickup objectives or item conditions and events it now uses the standard implementations. The following obsolete implementations were removed:

  • mmoitem condition
  • mmohand condition
  • mmoitemgive event
  • mmoitemtake event
  • mmoitemcraft objective
Old Syntax
conditions:
  hand: mmohand ARMOR SKELETON_CROWN
  inventory: mmoitem ARMOR SKELETON_CROWN
events:
  give: mmoitemgive ARMOR SKELETON_CROWN
  take: mmoitemtake ARMOR SKELETON_CROWN
objectives:
  craft: mmoitemcraft ARMOR SKELETON_CROWN
New Syntax
items:
  crown: mmoitem ARMOR SKELETON_CROWN
conditions:
  hand: hand crown
  inventory: item crown
events:
  give: give crown
  take: take crown
objectives:
  craft: craft crown

The mmoitemupgrade and mmoitemapplygem objectives exist unchanged.