-**This page and the following explain how to configure quests from file configuration. It is interesting to read it, even if you plan to use the in-game editor, so you can understand how the plugin and the quest files are structurated.**
**Quests can REALLY be different from a player to another ! Since QuestCreator v4, this is almost scripting** :
-***EVERY*** setting of a quest, branch, object, condition, location, block, material, etc, can be a "raw" value and you can specify global variables (`{gvariable:global_variable_name}`), QuestCreator variables (`{variable:variable_name}`) and PlaceholderAPI placeholder (`%my_placeholder%`). Those last two depend on the player, and will be parsed in-real-time when needed. (as the quest leader if it's a coop quest)
- For example, you can set `base: world,%player_x%,50,%player_y%` as a location setting, or `amount: %heroes_level%` as an amount setting. Also works for goto, so for example `goto: OBJECT {variable_goto}` or `goto: QUEST_{variable:mood}` !
- Every number setting can contain math expressions, and other settings can contain {math:[expression]}. Combined with placeholders, this is the ultimate way of customizing settings for every player ! It supports `+`, `-`, `*`, `/`, `^X`, `sin(X)`, `cos(X)`, `tan(X)`, `log(X)`, `ceil(X)`, `floor(X)`, `rand(X)` and can contain parentheses. For example, `amount: %heroes_level% * (5 + log(10^3))`.
- Every setting can contain a trienal permission condition, such as {permission:my_permission,value_if_has,value_if_hasnt}. The result depends on the player permissions : if he has the specified permission, it'll use the first value, otherwise the second one. Those two available values can also contain placeholders !
- It's parsed in real-time, but there's a cache so it doesn't demand too much server resources. Plus, objects goals are parsed when they begin (will not change until completion).
- The `type: ...` settings for objects, conditions and activators are the only settings that **can NOT contain variables and will NOT be parsed**.
***
As said in the index page, all your quest configuration files will be in /plugins/QuestCreator/quests/.
Every file that you create in this folder, ending with .yml, will be considered as a quest (you can organize your quests into subfolders if you want). The name of the file, without extension (.yml), will be the quest id, it's better not to put non-alphanumerical characters in it. Spaces are not allowed in file names.
***
### Example quest
Here's the default example quest generated (the one for 1.13). You should take a quick look at it to try to understand the general idea of how it works.
The 'section' at the top of the file is for basics and misc settings.
The "gui" section is for the GUI items appearance.
The "start_conditions" are things that the player needs to have to start the quest.
The "branches" section is for the quest branches, the different paths and objects that the player can do through his progress during the quest.
The "success_objects" are objects that will be executed if the player succeeds the quest, useful to set a generic ending dialog or animation, or give rewards for example. (optional)
The "fail_objects" are objects that will be executed if the player fails the quest, useful to reset things for example. (optional)
The "cancel_objects" are objects that will be executed if the quest gets cancelled, useful to reset things for example. (optional)
**Some of those settings are detailed below in the comments, and some parts are detailed in other wiki pages.**
*If you create coop quests (so if max_coop_players is greater than 0), please take a look at those details :*
-*Every variable change/node in the quest will refer to the variable values of the quest leader.*
-*The choices will be sent to the quest leader.*
-*Some objects will be executed for all players (sending a message, playing a sound, teleporting player, etc) and others will only be executing one time (teleporting an entity, placing a block, etc).*
*There also are two farm quest examples at the bottom of the page.*
# Display settings (color codes are allowed in both but only recommended in description)
name: '{gvariable:quest_example_name}'
description:
- '&7Just a sample quest'
# Maximum different instances of this quest that can be run at the same time
# One instance = one running quest (so 2 players doing this quest cooperating is one instance, same goes for one player doing this quest on his own)
# It's definitely not a good idea to set it to more than 1 if the quest has Objects that affects Citizens NPCs. It might be messy if multiple instances of the quest are manipulating the same Citizens NPCs at the same time.
# Default : 1
max_concurrent_instances: -1
# Create a queue for starting this quest if 'max_concurrent_instances' is already reached when trying to start the quest.
max_concurrent_instances_queue: false
# Minimum/maximum players that can do the quest together (count the quest starter and additionnal coop players, so for instance it's 1 for a solo quest and 2 for a duo quest)
# Default : minimum 1, maximum 1
min_players: 1
max_players: 1
# Maximum times the player can complete the quest
# Default : 1
max_completions: 10
# Allow the quest leader to stop the quest ?
allow_stop: true
# Maximum time (in minutes) the player has to do the quest, otherwise the quest is cancelled
# Default : 0 (disabled)
time_limit: 0
# Time the player will have to wait between completions (will be effective if max_completions is greater than 1)
# Available options : 'DISABLED', 'ENABLED [minutes amount]', 'ENABLED_SUCCESS [minutes amount]' (so the cooldown will only apply if the player succeeds the quest)
# item_progress : will be shown when the quest status is 'in progress'
item_progress:
type: DIAMOND_SWORD
name: '&6{name} &6- IN PROGRESS'
lore:
- '&7{description}'
- '{detailed_progression}'
- '&bRight click to stop this quest'
# item_cooldown : will be shown when the quest status is 'completed' and the player hasn't reached max_completions and the cooldown is not over
item_cooldown:
type: DIAMOND_SWORD
name: '&8{name} &8- COOLDOWN'
lore:
- '&7{description}'
- '&7You choose to call yourself {variable:example_nickname}. Noice.'
- '&7&lYou have completed this quest {completions} time{plural}.'
- '&7&l{cooldown} remaining before you can start this quest again.'
# item_completed : will be shown when the quest status is 'completed' and the player has reached max_completions
item_completed:
type: DIAMOND_SWORD
name: '&8{name} &8- COMPLETED'
lore:
- '&7{description}'
- '&7You choose to call yourself {variable:example_nickname}. Noice.'
- '&7&lYou have completed this quest {completions} time{plural}.'
# item_unavailable : will be shown when all preconditions aren't okay (model validity, follow check, max players, max instances, permissions, world, start conditions, ...)
error_message: '&2[ExampleQuest] &aUh, I''m sorry, but you don''t have enough money to start the example quest. You need {gvariable:quest_example_moneyneeded}$ !'
# You could also set it like this :
#conditions:
# - registered_condition
# ... and register the condition in conditions.yml ; this one is really specific to this quest though so it's not really needed
- 'MESSAGE &2[ExampleQuest] &7Hi there &a{player}&7, this is a very simple quest example with multiple paths !'
- 'WAIT 2'
- 'SOUND VILLAGER_IDLE'
- 'MESSAGE &2[ExampleQuest] &7''kay, first of all, I''ll need you to tell me what your &anickname &7is. I wouldn''t want to call you something you don''t want !'
# ended : when this object is completed, we go to the next object
goto: OBJECT 2_NICKNAME
# '2_NICKNAME' : ask the player for a nickname and store it in a variable
2_NICKNAME:
# start
wait: 3
sound:
type: VILLAGER_IDLE
message: '&2[ExampleQuest] &7Please, &bwrite your nickname in the chat &7:'
# name
name: 'Tell me your nickname'
progress_name: 'Write your nickname in the chat'
# settings
type: PLAYER_CHAT_VARIABLE
variable: example_nickname
min_length: 5
max_length: 25
disallowed_words:
- 'umbrella'
- 'wesh'
cancel_event: true
# end
goto: OBJECT 3_SAVELOCATION
# '3_SAVELOCATION' : save the player's current location in a variable
3_SAVELOCATION:
# settings
type: SERVER_VARIABLE_CHANGE
variable: example_player_location
operation: SET
value: '{questcreator_player_location}' # this is a QuestCreator placeholder, it saves the location in the followed format : 'world,x,y,z,yaw,pitch'
# end
goto: OBJECT 4_COBBLESTONE
# '4_COBBLESTONE' : place 10 cobblestones in a specific area
4_COBBLESTONE:
# start
sound:
type:VILLAGER_IDLE
message: '&2[ExampleQuest] &7Okay, good. &a{variable:example_nickname}&7, huh ? I''ll remember it ! Okay, I''m gonna need you to &bplace 10 cobblestone blocks&7. Also, &bremember where you''re located&7, I might ask you to go back there at the end.'
# name
name: 'show off your building skills'
progress_name: 'place cobblestone'
# settings
type: PLAYER_BLOCK_PLACE
block_type: COBBLESTONE
amount: 10
# end
post_message: '&2[ExampleQuest] &7Congrats &a{variable:example_nickname} &7! That was placed carefully. Or maybe not ? I don''t know, I can''t see. I trust you !'
post_sound:
type: VILLAGER_IDLE
goto: OBJECT 5_CHOICE
# '5_CHOICE' : give a choice to the player
5_CHOICE:
# pre (wait 3 seconds)
wait: 3
message: '&2[ExampleQuest] &7So hey, you can choose what you want to do now.'
sound:
type: VILLAGER_IDLE
# name
name: 'choose an option'
progress_name: 'choose an option'
# settings
type: DIVERGE
repeat_delay: 30
choices:
1:
text: '&7I choose the fire.'
redo_text: '&8(I choose the fire.)'
goto: BRANCH 2_1_fire
2:
text: '&7I choose to build.'
redo_text: '&8(I choose to build.)'
goto: BRANCH 2_2_build
3:
text: '&7I choose to end the right here. I think I did well.'
redo_text: '&8(I choose to end the right here. I think I did well.)'
goto: QUEST_SUCCESS
4:
text: '&7I choose to end the right here but I think I didn''t succeed. I need to retry it.'
redo_text: '&8(I choose to end the right here but I think I didn''t succeed. I need to retry it.)'
message: '&2[ExampleQuest] &7Okay. Violence, I see. Welll, go ahead, &bput 5 of those cobblestones in fire&7.'
sound:
type: VILLAGER_IDLE
# name
name: 'burn those rocks'
progress_name: 'fire cobblestone'
# settings
type: PLAYER_BLOCK_FIRE
block_type: COBBLESTONE
amount: 5
# end
goto: OBJECT 3_GOBACK
# '3_GOBACK' : the player must go back to its original location
3_GOBACK:
# pre
message: '&2[ExampleQuest] &7Well done. By the way, remember when I told you to remember your location ? Yeah ? Well, &bgo back there&7.'
sound:
type: VILLAGER_IDLE
# name
name: 'Go back to where you were'
progress_name: 'Find your original location'
# settings
type: PLAYER_WALK
walk_type: WALK_TO
location:
base: '{variable:example_player_location}'
# end
goto: OBJECT 4_DROPMIC_PRE
# '4_DROPMIC_PRE' and '5_DROPMIC' : drop flint and steel
4_DROPMIC_PRE:
# settings - initialize an optional branch that will send hints to the player
type: SERVER_ACTION_LIST
actions:
- 'STARTBRANCH 2_1_fire_hint'
- 'SOUND VILLAGER_IDLE'
- 'MESSAGE &2[ExampleQuest] &7Looks like it''s time to &bdrop the mic&7, doesn''t it ?'
# end - then start the actual object
goto: OBJECT 5_DROPMIC
5_DROPMIC:
# name
name: 'drop the mic'
progress_name: 'drop the mic'
# settings
type: PLAYER_ITEM_DROP
item:
type: FLINT_AND_STEEL
enchants:
- DURABILITY,5
remove_after_action: true
# end
post_message: '&2[ExampleQuest] &7You choose violence, &c{variable:example_nickname}&7. For that, you won''t have any rewards. That''s how it works here. Later !'
post_sound:
type: VILLAGER_IDLE
goto: QUEST_SUCCESS
# this branch will give tips to the player if needed
2_1_fire_hint:
starts_directly: false
starts_at: HINTS
objects:
HINTS:
# settings
type: SERVER_ACTION_LIST
actions:
- 'WAIT 5'
- 'MESSAGE &2[ExampleQuest] &7*hmhm* drop the mic ?'
- 'WAIT 5'
- 'MESSAGE &2[ExampleQuest] &7I said... &ldrop &7the mic ?'
- 'WAIT 5'
- 'MESSAGE &2[ExampleQuest] &7Come on, dude ! Drop that flint and steel...'
# '1_GIVE' : give the player the wood he needs (5x 64 logs)
1_GIVE:
# settings
type: SERVER_ITEMS_GIVE
items:
1:
type: ACACIA_LOG
amount: 64
amount: 5
# end
goto: OBJECT 2_BUILD_GROUP
# '2_BUILD_GROUP' : this is a group that contains all the building objects
2_BUILD_GROUP:
# pre
message: '&2[ExampleQuest] &7Okay, that''s a good choice, &a{variable:example_nickname}&7. What about building a nice little house, with log corners, some air windows and a roof made of slabs ? I mean, I won''t be able to detect if you did well and you could literally drop that on the floor, but come on, be nice ! :)'
sound:
type: VILLAGER_IDLE
# name
name: 'do another building excercise'
# settings
type: GROUP
group_type: ALL_OBJECTS
group_objects:
- '2_1_CRAFT'
- '2_2_BUILD'
- '2_3_BUILD'
objects_required: 3
execution_order: false
# end
goto: OBJECT 3_GOBACK
# Those objects are the ones from the group, and they'll need to be all completed for the group to end. Order doesn't matter.
2_1_CRAFT:
# name
progress_name: 'craft wood'
# settings
type: PLAYER_ITEM_CRAFT
item:
type: ACACIA_PLANKS
amount: 64
2_2_BUILD:
# name
progress_name: 'place wood'
# settings
type: PLAYER_BLOCK_PLACE
block_type: ACACIA_PLANKS
amount: 32
2_3_BUILD:
# name
progress_name: 'place slabs'
# settings
type: PLAYER_BLOCK_PLACE
block_type: ACACIA_SLAB
amount: 10
# '3_GOBACK' : the player must go back to its original location
3_GOBACK:
# pre
message: '&2[ExampleQuest] &7Well done. By the way, remember when I told you to remember your location ? Yeah ? Well, &bgo back there&7.'
sound:
type: VILLAGER_IDLE
# name
name: 'Go back to where you were'
progress_name: 'Find your original location'
# settings
type: PLAYER_WALK
walk_type: WALK_TO
location:
base: '{variable:example_player_location}'
near: 5.0
# end
goto: OBJECT 4_REFUND
# '4_REFUND' : refund the money needed as a start condition
4_REFUND:
# pre
message: '&2[ExampleQuest] &7That''s a wonderful house. Keep building ! I mean, I can''t really see it because I''m just a voice in the wild, but I''m sure it''s great. You know what ? Take those dollars backs, you deserve that for choosing creation !'
# Display settings (color codes are allowed in both but only recommended in description)
name: 'Example Farm - I'
description:
- '&7Just a sample farm quest'
- '&7Farm {math:{gvariable:quest_example_farm_baseamount}} stones in this quest !'
# Maximum different instances of this quest that can be run at the same time
# One instance = one running quest (so 2 players doing this quest cooperating is one instance, same goes for one player doing this quest on his own)
# It's definitely not a good idea to set it to more than 1 if the quest has Objects that affects Citizens NPCs. It might be messy if multiple instances of the quest are manipulating the same Citizens NPCs at the same time.
# Default : 1
max_concurrent_instances: -1
# Create a queue for starting this quest if 'max_concurrent_instances' is already reached when trying to start the quest.
max_concurrent_instances_queue: false
# Minimum/maximum players that can do the quest together (count the quest starter and additionnal coop players, so for instance it's 1 for a solo quest and 2 for a duo quest)
# Default : minimum 1, maximum 1
min_players: 1
max_players: 1
# Maximum times the player can complete the quest
# Default : 1
max_completions: 1
# Allow the quest leader to stop the quest ?
allow_stop: true
# Maximum time (in minutes) the player has to do the quest, otherwise the quest is cancelled
# Default : 0 (disabled)
time_limit: 0
# Time the player will have to wait between completions (will be effective if max_completions is greater than 1)
# Available options : 'DISABLED', 'ENABLED [minutes amount]', 'ENABLED_SUCCESS [minutes amount]' (so the cooldown will only apply if the player succeeds the quest)
# item_progress : will be shown when the quest status is 'in progress'
item_progress:
type: DIAMOND_SWORD
name: '&6{name} &6- IN PROGRESS'
lore:
- '&7{description}'
- '{detailed_progression}'
- '&bRight click to stop this quest'
# item_cooldown : will be shown when the quest status is 'completed' and the player hasn't reached max_completions and the cooldown is not over
item_cooldown:
type: DIAMOND_SWORD
name: '&8{name} &8- COOLDOWN'
lore:
- '&7{description}'
- '&7&lYou have completed this quest {completions} time{plural}.'
- '&7&l{cooldown} remaining before you can start this quest again.'
# item_completed : will be shown when the quest status is 'completed' and the player has reached max_completions
item_completed:
type: DIAMOND_SWORD
name: '&8{name} &8- COMPLETED'
lore:
- '&7{description}'
- '&7&lYou have completed this quest {completions} time{plural}.'
# item_unavailable : will be shown when all preconditions aren't okay (model validity, follow check, max players, max instances, permissions, world, start conditions, ...)
# Display settings (color codes are allowed in both but only recommended in description)
name: 'Example Farm - I'
description:
- '&7Just a sample farm quest'
- '&7Farm {math:{gvariable:quest_example_farm_baseamount} * 2} stones in this quest !'
# Maximum different instances of this quest that can be run at the same time
# One instance = one running quest (so 2 players doing this quest cooperating is one instance, same goes for one player doing this quest on his own)
# It's definitely not a good idea to set it to more than 1 if the quest has Objects that affects Citizens NPCs. It might be messy if multiple instances of the quest are manipulating the same Citizens NPCs at the same time.
# Default : 1
max_concurrent_instances: -1
# Create a queue for starting this quest if 'max_concurrent_instances' is already reached when trying to start the quest.
max_concurrent_instances_queue: false
# Minimum/maximum players that can do the quest together (count the quest starter and additionnal coop players, so for instance it's 1 for a solo quest and 2 for a duo quest)
# Default : minimum 1, maximum 1
min_players: 1
max_players: 1
# Maximum times the player can complete the quest
# Default : 1
max_completions: 1
# Allow the quest leader to stop the quest ?
allow_stop: true
# Maximum time (in minutes) the player has to do the quest, otherwise the quest is cancelled
# Default : 0 (disabled)
time_limit: 0
# Time the player will have to wait between completions (will be effective if max_completions is greater than 1)
# Available options : 'DISABLED', 'ENABLED [minutes amount]', 'ENABLED_SUCCESS [minutes amount]' (so the cooldown will only apply if the player succeeds the quest)
# item_progress : will be shown when the quest status is 'in progress'
item_progress:
type: DIAMOND_SWORD
name: '&6{name} &6- IN PROGRESS'
lore:
- '&7{description}'
- '{detailed_progression}'
- '&bRight click to stop this quest'
# item_cooldown : will be shown when the quest status is 'completed' and the player hasn't reached max_completions and the cooldown is not over
item_cooldown:
type: DIAMOND_SWORD
name: '&8{name} &8- COOLDOWN'
lore:
- '&7{description}'
- '&7&lYou have completed this quest {completions} time{plural}.'
- '&7&l{cooldown} remaining before you can start this quest again.'
# item_completed : will be shown when the quest status is 'completed' and the player has reached max_completions
item_completed:
type: DIAMOND_SWORD
name: '&8{name} &8- COMPLETED'
lore:
- '&7{description}'
- '&7&lYou have completed this quest {completions} time{plural}.'
# item_unavailable : will be shown when all preconditions aren't okay (model validity, follow check, max players, max instances, permissions, world, start conditions, ...)
