这一部分描述了 /plugins/QuestCreator/ 内的文件结构。
The main configuration file is /config.yml, it contains a few useful settings. Everything is explained inside that file with comments.
You can configure user, server and global variables in their respective .yml files.
You can download the default configuration files to take a look.
All elements (quest models, quest pools, GUIs, global branches, global objects, …) are stored in their own folders :
在每个文件夹里，每个元素都是一个 .yml格式的为文件。比如，/quest_models/my_quest.yml 是id为my_quest的任务模型。Id对于大小写敏感（须小写）。
If you’re using JSON as a back-end for data boards, data files will be saved under /plugins/QuestCreator/data_v6/. Removing that folder will discard all current user data (active quests, history, user variables, etc). It should be noted that quest points are stored in GCore’s statistics system, located with JSON under /plugins/GCore/data_v8/statistics/.
The first thing to note is the difference between “quests” and “quest models”.
A “quest model” is a configuration file that contain all the configuration and possibilities that will (or might) happen during the quest. They’re located under /quest_models/.
A “quest” represents an active quest model. Each player (or group of players for cooperation) might or might not have a “quest” instance with different choices and progression.
A running quest has always at least one active “branch” with an active object inside. Each branch can be seen as a “container of objects”.
A quest object represents either :
- An objective that the player must complete (typically, to progress to the next part of the quest)
- Or an action the server must do (for instance, sending messages, playing sounds, manipulating entities, stuff like that).
In a quest, there is only one active object per branch at a time, but you can have multiple running branches.
Here’s a scheme (not actual config) of one possible structure of an active quest :
my_active_quest: branch_1: *active - object_1 - object_2 - *object_3 - object_4 branch_2: *active - *object_1 - object_2 branch_3: not active - object_1 - object_2 - object_3
In the quest model, there are 3 available branches, but only 2 of them are active in the player’s quest. In each of those two branches, there are many possible objects, but only one is currently active in each branch.
Let’s translate our example into the actual configuration settings of a quest model :
branches: branch_1: starts_directly: true starts_at: object_3 objects: object_1: # ... object settings go here object_2: # ... object settings go here object_3: # ... object settings go here object_4: # ... object settings go here branch_2: starts_directly: true starts_at: object_1 objects: object_1: # ... object settings go here object_2: # ... object settings go here branch_3: starts_directly: false starts_at: object_2 objects: object_1: # ... object settings go here object_2: # ... object settings go here object_3: # ... object settings go here
Lot of information here, it mixes the different concepts we’ve seen so far.
Each branch under the branches configuration section represents a possible branch, with an identifier (branch_1, branch_2, …) that must be unique.
The starts_directly boolean setting for each branch is used to indicate whether this branch should start automatically when the quest starts, or not (like we did for branch branch_3) if you would like to start it later manually.
The objects section is a list of available objects for this branch, with an identifier that must be unique to the branch. But you can have multiple objects named object_1 as long as they’re in different branches (like in our example).
Even though a branch has a ‘list’ of available objects, those objects might not follow the list order. For instance, in example above branch_1, you might decide that the branch will first run object_3 and then go to object_2.
The starts_at setting for each branch is used to indicate to the plugin at which object the branch should begin when started.
You could also repeat objects as many times as you want, for instance : object_3 > object_2 > object_1 > object_4 > object_1 > object_4 > ... and stop looping until a certain condition is met.
So, from what we’ve seen until here, to put it simply, let’s just say the plugin is not ‘smart enough’ to detect what object it should run next, because you’re actually freed from the ‘fixed list order’. You’ll have to indicate to the plugin what object it should run next, or more generally ‘what goto it should perform’.
So, let’s add goto’s to our branch branch_1 :
object_1: # ... object settings go here goto: OBJECT object_4 object_2: # ... object settings go here goto: OBJECT object_1 object_3: # ... object settings go here goto: OBJECT object_2 object_4: # ... object settings go here goto: OBJECT object_1
This respects the order of our example : object_3 > object_2 > object_1 > object_4 > object_1 > object_4 > ..., even though here the loop between object 1 and 4 will never stop because we didn’t set any conditions. Conditions and logic are explained further in this documentation, but this example is given to clearly explain the power of goto’s.
So here, you indicate with the OBJECT goto type that you wish to run an object of the same branch when the current object is completed. But goto’s can actually trigger more than objects, they can start or stop branches, complete the quest, manipulate other quests and stuff. See a list of goto types here
For instance, we have in our example a branch named branch_3 that doesn’t start automatically. At some point in our quest, we might want to start that branch ! We could do that at the end of the second branch :
branch_2: starts_directly: true starts_at: object_1 objects: object_1: # ... object settings go here goto: OBJECT object_2 object_2: # ... object settings go here goto: BRANCH branch_3
Once object 2 is completed, the goto will start our branch_3 branch. And since the goto of branch_2 did not call an object from the same branch, branch_2 will be stopped because it wouldn’t know what to do next in the same branch. Don’t worry, there are ways to start other branches without stopping the current one, but again, this is just for example’s sake.
And finally, note that if there are no active branches (due to a missing goto somewhere), the quest stops because it doesn’t know what to do next.
I’ve used kind of complicated examples until here so you could visualize the different concepts. Here’s a practical example of a simple NPC farm quest.
branches: unique_branch: # this is a simple quest, so we just need one branch starts_directly: true # this is actually true by default starts_at: START_NPC_DIALOG # we start the quest by talking to the NPC objects: START_NPC_DIALOG: # ... our dialog settings go here goto: OBJECT FARM_STONE FARM_STONE: # ... our farming settings go here goto: OBJECT DELIVER_ITEMS_TO_NPC DELIVER_ITEMS_TO_NPC: # ... our NPC delivery settings go here goto: OBJECT END_NPC_DIALOG END_NPC_DIALOG: # ... our dialog settings go here goto: QUEST_SUCCESS # this will stop the quest and mark is as successfully completed
Note : I know the goto’s system can be seen as annoying at first glance. Practically, especially for such simple quests, you’ll have your first object be the first of the list and your goto’s will actually follow the order of the list. But for more advanced quests, the goto’s brings the essential freedom you need to truly be able to perform dialogs, loops, logic, etc. QuestCreator wasn’t designed to be simple, but powerful. Don’t worry, you can easily get the hand of it with some patience :D
Obviously, there aren’t just branches and objects configured in our quest model, there are many others settings.
A detailed list of objects settings can be found here.
A detailed list of model settings can be found here.
Now, you have a quest, right ? But how can the player start it ?
If you want, you can give them the permission to start quests via the /quest start [quest] command. You could also configure a GUI so they can see all the quests and manage it there.
But you could also want the quest to start when talking to a Citizens NPC, or when they enter a certain area, or just automatically.
That’s the main purpose of activators : to activate quests under certain conditions. They’re located under /quest_activators/.
It’s pretty simple to add an activator to a quest : just create the activator and the settings for it, and then add the activator to your quest model :
activators: - my_activator
If my_activator is a physical activator, the quest will start when the player interacts with it. Otherwise, it’ll just start when the activator’s conditions are respected.
Read more about activators and their settings here.
You might want to make it so some of your quests are available daily or weekly, and change it every day/week.
This is where quest pools are useful. They’re located under /quest_pools/.
A quest pool doesn’t have direct control on the starting of quests. What it does is ‘processing’ the quests for each period (a period is ‘the current day/week/…’) : calculating which quests will be available during the period.
When the player connects, the pool will check if it has already processed its quests for the player during the current period. For instance, let’s say you have a daily period and GuillaumeVDN connects for the first time that day at 15:30. The pool will not yet have processed the quests for him ; however, player Notch who connected at 14:00 will already have his quests processed for the day.
Once the pool processed a player for the active period, it doesn’t do it again it until the next day (or until it’s manually reset through a command).
Unlike regular quest management, quest pools work with a ‘token’ feature for quests. When a pool processes its quests for a said period, it gives them tokens.
Then, when the player wants to start the quest (through an activator or a gui, for instance), the plugin detects if the quest is in a pool and if it has remaining tokens.
When the player starts the quest once, one token is ‘consumed’ (taken from the player). Once the player doesn’t have any tokens left, they won’t be able to start the quest until the pool reprocesses, in the next period.
For instance, for a daily period, if the token is consumed today at 18:30, no new tokens will be available until reprocessing when the next day starts, at midnight (or later tomorrow if the player is not online then).
Read more about pools and their settings here.
Even though I personally like editing through YAML files (because of how you can have a more global view), you can edit almost everything with the in-game editor (open it with /qc edit).
However, I do advise you to read through the documentation once to get a general understanding of the plugin. The in-game editor just contains all the settings and provide tools to edit them, but it does not actually ‘explain’ anything (‘what are quest models’, ‘what are activators’, ‘how to do this’, etc). So it’s just better to understand all of this before getting into it !
All the settings are the exact same as editing through files. Everytime the depth increases (the amount of indentation in YAML), it’s another submenu that opens.
Every basic value will have an icon in the GUI and different click types are available. Everything specific to that setting, and all the actions you can do with it, are explained there.
Most enumeration settings (Citizens NPC, click type, block type, enchantments, etc) can be selected in a menu or quickly imported.
I advise you to try it out by yourself to get a general feel of it ^_^
Because of my custom YAML reader, the original file settings order and comments will be kept when the in-game editor overwrites the file, so you could also configure most of it through files and use the editor to import stuff, for instance items or locations.