Packages & Templates

Packages🔗

All quests you create are organized into packages. A single package can contain one or multiple quests - it's up to your liking. It is very important to have a good understand of packages. Read the packages chapter carefully.

Structure🔗

A package is a folder with a "package.yml" file. It must be placed inside the "BetonQuest/QuestPackages" directory.
Additionally, you can create extra files or sub-folders inside a package to organize your quest the way you want. Sub-folders of packages that contain a "package.yml" are separate packages, they do not belong to the surrounding package in any way.

Let's take a look at a few examples:

Structure Examples

Every quest package is surrounded with a blue box.

Simple PackageComplex PackageNested Packages

A very simple package. It's defined by the package.yml and has two additional files.

The package storyLine is defined by the package.yml. It contains two sub-folders, both of them (including their files) are part of the package.

The package weeklyQuests is defined by the package.yml. It contains two sub-folders, they are not part of the package weeklyQuests. This is the case because they have their own package.yml files. Because of that they are separate packages.

Defining features🔗

You can freely define features (events, conversations, items etc.) in all files of a quest package. However, they need to be defined in a section that defines their type.

The names of these features must be unique in that package, no matter which file they are in.

Example

events:
  teleportPlayer: "..."

conditions:
  hasDiamondArmor: "..."

objectives:
  killCrepper: "..."

items:
  legendarySword: "..."

conversations:
  bobsConversation:
    quester: Bob
    #...

menus:
  homeMenu:
    height: 3
    #...

Working across Packages🔗

Accessing features from other packages can be very helpful to link quests together. All events, conditions, objectives, items and conversations can be accessed.

You never need to access a specific file since feature names are unique within a package.

Top-Level Packages🔗

You can access top-level packages (placed directly in "QuestPackages") by prefixing the feature's name with a greater than (>) and the package name.

Example

Let's assume you have a rewards package that contains player reward events.
Let's run the easyMobObjective event of the rewards package from another package:

Add a greater than (>) before the event name >easyMobObjective
Add the package name in front of the greater than rewards>easyMobObjective

An example usage could look like this:

zombieObjective: "mobkill ZOMBIE 5 events:rewards>easyMobObjective"

Note that this only works for top-level packages (the rewards package is placed directly in the QuestPackages folder). Check the next paragraph to see how it's done for other packages.

Packages in Sub-folders🔗

You can access packages in sub-folders by prefixing the feature's name with the package name and the path from the "QuestPackages" folder to the package.

Example

One Nested PackageMultiple Nested Packages

Let's assume you have a dailyQuests package that contains a dailyQuestOne package. The dailyQuests package is located in the QuestPackages folder. Let's run the startDailyQuest event of the dailyQuestOne package from a third package:

Combine the event name with the package name dailyQuestOne>startDailyQuest
Add the path from the QuestPackages folder to the dailyQuestOne package seperated by dashes (-). dailyQuests-dailyQuestOne>startDailyQuest

An example usage could look like this:

zombieObjective: "mobkill ZOMBIE 5 events:dailyQuests-dailyQuestOne>startDailyQuest"

Let's assume you have a dailyQuests package that contains a dailyQuestOne package. The dailyQuests package is contained inside a folder called repeatable which is located in the QuestPackages folder. Let's run the startDailyQuest event of the dailyQuestOne package from a third package:

Combine the event name with the package name dailyQuestOne>startDailyQuest
Add the path from the QuestPackages folder to the dailyQuestOne package seperated by dashes (-). repetable-dailyQuests-dailyQuestOne>startDailyQuest

An example usage could look like this:

zombieObjective: "mobkill ZOMBIE 5 events:repetable-dailyQuests-dailyQuestOne>startDailyQuest"

Relative paths🔗

You can specify relative paths to a package instead of full paths. The underscore (_) means "one folder up" from the current packages "package.yml". In turn, a leading dash (-) combined with a folder name navigates "one folder down" into the given folder. Each package in the path must be separated by a dash.

This can be useful when distributing or moving packages. Instead of rewriting every package path to match the current location, relative paths will still work.

Example

Going UpwardsGoing Downwards

Let's assume you have a weeklyQuests folder that contains a weeklyQuestOne and a weeklyQuestTwo package. Let's run the startQuestTwo event of the weeklyQuestTwo package from the weeklyQuestOne package.

Combine the event name with the package name weeklyQuestTwo>startQuestTwo
Add the path from the current package.yml to the folder the package of interested lies in. This is done using underscores ("go one folder up"). A dash must be added after each underscore (-). _-weeklyQuestTwo>startQuestTwo

An example usage could look like this:

zombieObjective: "mobkill ZOMBIE 50 events:_-weeklyQuestTwo>startQuestTwo"

Let's assume you have a weeklyQuests package that contains a weeklyQuestTwo package which contains another package called subQuest. Let's run the startQuest event of the subQuest package from the weeklyQuests package.

Combine the event name with the package name subQuest>startQuest
Add the path from the current package.yml to the folder the package of interest lies in. Package names must be seperated by dashes (-). The path must also be started with a dash to signal "from the current package downwards". -weeklyQuestTwo-subQuest>startQuest

An example usage could look like this:

zombieObjective: "mobkill ZOMBIE 50 events:-weeklyQuestTwo-subQuest>startQuest"

Disabling Packages🔗

Packages are enabled by default, you can disable a package if you don't want it to be loaded. Set enabled inside the package section to true or false to enable or disable the package.

package:
  ## Optionally add this to the package.yml
  enabled: false

Package Version🔗

Each package has a version inside the package section that is used by the automatic migrator. When no version is set the newest version will be set on loading. Any new package section will be added at the end of the file, so you probably want to move that to the file's top.

Info

When updating from a version before versioning see Migration to BQ 3.0.

package:
  version: 3.0.0-QUEST-1 # Don't change this! The plugin's automatic quest updater handles it.

Templates🔗

You should have experience creating and using packages before you start using templates. Templates are a way to create packages that can be used as a base for other packages to reduce the amount of repetitive work. Therefore, they are a great way to centralize logic or create utilities.

Using Templates🔗

Templates work exactly like packages, except that they are placed in the "BetonQuest/QuestTemplates" folder instead of the "BetonQuest/QuestPackages" folder and that they are not loaded as a ready to use package. Instead, they are used as a base for other packages by referring to them in the templates section inside the package section.

package:
  templates:
    - MyTemplate
    - SecondTemplate

If you use the above in a package, the MyTemplate and SecondTemplate templates would be used as a base for the package. This means that all the events, objectives, conditions, etc. from the templates would be added to the package. If the package already contains an event/objective/condition with the same name as one from the template, the package's events, objectives, conditions, etc. will be used instead of the one from the template.

If the same events, objectives, conditions, etc. is defined in multiple templates, the one from the lists first template will be used.

You can also use templates in templates. Also in this case, the events, objectives, conditions, etc. that are defined in the current template will be used instead of the ones from the template that is being used as a base.