Introduction

Please note: Writing a good documentation takes a lot of time and I did not decide to publish this project until recently. Therefore many things are still missing. If you have any question please create a ticket on GitLab.


The following paragraphs provide a detailed description of the basic plugin structure. Read this, if you want to understand how the plugin works. If you just want to get started ASAP, you can skip to the quick start guide.

The data managed by the software consists of two basic components, quests and saved progresses. A quest describes a task for the player to fulfill and is set up by the server admin. The other component is used to track the progress tracks player has made on such a quest.

Quests consist of four basic customizable parts: triggers, requirements, objectives and rewards. They may contain multiple of each, some are mandatory for the quest to work. While triggers and requirements are set per quest, the other two customizables can be set for each quest stage. Stages are used to subdivide a quest into multiple smaller tasks that have to be fulfilled sequentially. Obviously each quest must contain at least one stage and each stage should contain an objective.

A trigger is used to describe how the quest is advertised to/started by the player. Although triggers are not mandatory to a quest, each quest normally contains at least one. If not, the quest would have to be started by an admin using commands. Examples for triggers are talking to an NPC or clicking a specific block.

After triggering a quest the user is (normally¹) shown a message in chat that allows him to accept the quest. This is called advertising the quest to the player. He can then click the text in the chat to accept and start the quest.

Before starting the quest, its requirements are checked. If a player does not fulfill all requirements that are set for the quest, he is shown a corresponding message² and the quest is not started. Examples for requirements are items which have to be inside the players inventory or a specific location at which the quest can be started.

When the quest is finally started, the progress for the player is set up. This is done by setting his current stage to the first stage of the quest and initializing the memory for the corresponding objectives. This is also the first time the fulfillment of the objectives is checked.

An objective describes the task the player has to fulfill to finish a quest stage, receive the stages rewards and progress to the next stage or finish the quest. Good examples for objectives are an amount of items that have to be collected or a location that has to be reached by the player. Additionally so-called anti-objectives can be defined. Those are requirements that have to be fulfilled during the stage. If any of those is offended, the quest is cancelled and the player failed to finish it. Examples for anti-objectives are regions that may not be left or NPCs/mobs that may not die during a stage.

Finally, when the stage is completed, the player is given the stages rewards. Those are meant to reward the player for finishing the task he was given but can also be used to trigger various actions at the end of each stage. Rewards can for example be items or a currency that are given to the player or a command that is executed when the stage is finished.

¹ A trigger can also be configured to automatically start the quest without asking the player beforehand.
² This message can be configured or disabled, too.