1.x/Quests.yml
< 1.x
Quests.yml
Quests are defined in the quests.yml file located in plugins/Citizens. Because of the power and flexibility of the quest system, it can be a bit of a finicky beast. Pay special attention to spacing and the use of special characters. Quests.yml should pass any YAML parser without any errors. Most problems that arise from setting up quests is result of invalid formatting.
Tool: [YAML Parser] allows the contents of your .yml file to be pasted into the left box. If formatted incorrectly, parse errors will show in the right panel indicating the problem.
- Note from aufdemrand: I noticed that upon paste, the page sometimes doesn't instantly parse. You either need to change the output type, or insert a character, such as a space or newline with the keyboard. If correctly parsed, there will be no error codes. Ignore output code for this situation as you are just using this tool for validation.
Example structure
Quests consist of different parts, as explained by this page. This is the basic flow of most quests.
"Title":
texts:
repeats:
delay:
requirements:
initial:
rewards:
objectives:
Note: Other arguments and nodes are required for sections for a complete quest. This is just an outline. More information, in depth below:
Quest Nodes
Title
Required.
Each root node in that file is a quest name. In the default quest.yml the two example quests are 'example' and 'example2'. This identification is what you will use in-game to identify each quest.
The title is the very first line of the quest, in quotes, followed by colon. If one word, quotes are not necessary.
"Title of quest":
Example: The command required in game to assign the quest to a quester utilizes this title.
/quester assign Title of quest
Texts
Required.
Inside the quest, there are three required texts: description, acceptance, and completion.
The description is sent to the player when being given the option to accept the quest. The acceptance is sent to the player when they accept the quest, and the completion when they finish.
texts:
description: "Description text."
acceptance: "Acceptance text."
completion: "Completion text."
Default text is white. Special character combinations can be used for formatting text. See: Message Formatting and Quest Text Formatting Tips
Repeats
Optional. If not set, default is 0.
The repeats: option allows you to set a limit for the number of times you can repeat the quest.
repeats: 6 # Quest can be repeated 6 times.
Use -1 for unlimited repeats, 0 for no repeats.
Delay
Optional. Default, if not set, is 0.
The delay: option allows you to specify the time (in minutes) before one is allowed to retake the quest.
delay: 10 # Allows the quest, if allowed, to be repeated 10 minutes after completing it.
Requirements
Optional.
The requirements: node checks for conditions before allowing a player to take a quest. Requirements types can be item, quest, time, money, health, rank, or permission.
See also: List of Requirement node types
- Note by aufdemrand: need to double check each type to confirm they work. I know for sure quest, money & item work. I am assuming on the others.
requirements:
'0':
type: item # Requires item(s) when accepting.
id: 15 # iron_ore
amount: 15
take: true # take the 15 iron_ore, set to false to leave items on player.
'1':
type: quest # Requires a quest be completed prior.
quest: "example1"
You may have multiple requirements, or just one.
Initial
- Note: Requires Citizens dev 1.1.4 or higher.
Optional.
The initial: node will trigger once conditions have been met allowing a player to take a quest. Many practical uses can be used for this, but among some of those may be:
- Giving the player some gear to start a quest.
- Giving an item to the player that is used in a quest.
- Giving special rank or permission to a player.
- Performing server commands.
- Spawning NPC bodyguards to assist the questee.
Initial types can be item, quest, time, money, health, rank, or permission.
See also: List of Initial node types
- Note by aufdemrand: need to double check each type to confirm they work. I know for sure money & item work. I am assuming on the others.
initial:
'0':
type: item # Gives an item when conditions are met.
id: 268 # wooden_sword
amount: 1
take: false # Optional. By default, take: is false.
You may have multiple entries, or just one.
Rewards
Optional.
The rewards: node is used to tell the quester what to reward the player with when conditions are met. If all the objectives are completed, the rewards: node is triggered.
See also: List of Rewards node types
rewards:
'0':
type: item # Rewards an item
id: 15 # iron_ore
amount: 30
'1':
type: quest # Rewards a quest. This quest will start immediately.
quest: "Part II"
You may have multiple rewards, or just one. Rewards can also be subset into objectives to reward the player as objectives are completed. The format is the same.
Objectives
This section is the meat of the quest file. Objectives tell the quester what needs to be accomplished in order to complete the quest. Available objectives include hunt, deliver, destroy, and more. They can be used together to make quests as simple, or as detailed as you want.
See also: List of Objective node types
Basic objective structure
Objectives are made of sub-objectives. In the below example, for the quest to be complete, objective 0 would have to have 3 sub-objectives complete before the player can attempt to complete objective 1. The quest would be complete when the sub-objective in objective 1 is complete.
objectives:
'0':
'0':
type:
'1':
type:
'2':
type:
'1':
'0':
type:
If your quest has merely one objective, it must still be nested as a sub-objective. Example below:
objectives:
'0':
'0':
type:
Note: The above 2 examples are only an outline of the objective structure. There are more nodes that need to be defined in order for a successful quest. Keep reading.
Breakdown of an objective
Sub-objectives contain types and their nodes. With the List of Objective node types, you can use various types to control the flow of the quest. Here's an example that uses a hunt objective and a delivery objective. Sub-objectives can be completed in any order.
'0':
'0':
type: hunt # Type set to hunt objective
string: 'slime' # Type of monster to hunt is set to slime.
amount: 2 # Amount of slimes required to hunt.
optional: False # Quest sub-objective is required to complete the quest.
message: "Pesky slimes slaughtered." # Message displayed when sub-objective is completed.
'1':
type: delivery # Type of second sub-objective set to delivery.
materialid: 341 # Slimeballs.
amount: 6 # 6 items must be on hand to complete sub-objective.
npcdestination: 2 # NPC # that the items must be taken to.
optional: True # Sub-objective not required, is optional.
message: "Slimeballs delivered." # Message displayed when second sub-objective is completed.
A reward inside a sub-objective
As mentioned in the rewards node section, rewards can also trigger at the completion of a sub-objective. They should be nested inside the sub-objective like the example following:
'0': type: move distance # Player must move specified amount of blocks amount: 6 # 6 blocks to be exact optional: False message: "You received a bow and some arrows! Sweet!" rewards: '0': type: item # Reward type set to item id: 261 # Bow amount: 1 '1': type: item # Second reward type also an item id: 262 # Arrow amount: 64 # 1 stack
See also
Basic Example Quests are very basic quests from start to finish, all commented.
A Two-Part Example Quest explores a two-part quest among two different NPCs.
More example quests will have a variety of quests, mostly ready to copy/paste into your world. Some variables may need to be changed.
Questing Cook-Book will contain copy & paste snippets nearly-ready to be combined.
Advanced Questing Ideas will explore the use of other plugins to supplement Citizens.