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:
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 text nodes. The three required texts are 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: Formatting Questing Text
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. For example, you can use this to give gear to the player when accepting the quest. 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 Reward 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.
To aid with generic objective design, each objective can use one of a common set of variables:
- amount
- string
- materialid
- location
- item
- npcdestination (destination NPC ID)
See also: List of Objective node types
Basic objective structure
objectives:
'0':
'0':
type:
'1':
type:
'2':
type:
'1':
'0':
type:
In the above 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. 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
'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.
finishhere: False # Quest will be finished elsewhere.
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.
finishhere: True # Quest is completed at this step if all other required objectives are complete.
message: "Slimeballs delivered." # Message displayed when second sub-objective is completed.
A reward inside a sub-objective
As mentioned in the section above, rewards can also trigger at the completion of a sub-objective. They should be nested inside 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:
A Basic Example Quest is a very basic quest 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.