ProQuests

Feb 2, 2017
ProQuests
  • [​IMG]
    [​IMG]

    Materials:
    If there are any specific sections that ask for a material you must use a valid value and it does not support numeric ids. A list of valid materials can be found at the following link (some may be different/unique per spigot version):
    https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html

    Entities:
    If you have a section that requires a specific entity type a list of valid values can be found at the following link (some may be different/unique per spigot version):
    https://hub.spigotmc.org/javadocs/spigot/org/bukkit/entity/EntityType.html

    Sounds:
    If there are sections that require a sound value you can use the list of valid sounds that can be found at the following link (some may be different/unique per spigot version):
    https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Sound.html

    Potion Types:
    If there are sections that require a potion type value you can use the list of valid types that can be found at the following link (some may be different/unique per spigot version):
    https://hub.spigotmc.org/javadocs/spigot/org/bukkit/potion/PotionEffectType.html

    Dye Colors:
    If there are sections that require a color value you can use the list of valid colors that can be found at the following link (some may be different/unique per spigot version):
    https://hub.spigotmc.org/javadocs/spigot/org/bukkit/DyeColor.html

    Statistics:
    If there are sections that require a statistic type you can use the list of valid statistics that can be found at the following link (some may be different/unique per spigot version):
    https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Statistic.html

    [​IMG]

    [​IMG]

    ProQuests is a unique plugin designed to give players objectives and reward them for completing them accordingly. There is a large list of quests within the plugin and it is always growing. If you have any suggestions for new quests (could hook into other plugins as well) be sure to message me @JC_Plays_MC with a description of the quest you want added.

    Any quest you make can have the following general attributes:
    Code (Text):
    type: BREAK_QUEST //The specific quest type
    duration: <int> //The time the player has to complete it
    repeat_delay: <int> //The duration before the quest can be repeated
    repeatable: <boolean> //Whether or not players can repeat the quest
    cancelable: <boolean> //Whether or not players can cancel the quest
    command_start: <boolean> //Whether or not players can start the quest via command
    cancel_after_timer: <boolean> //Whether or not to execute the end actions or complete actions when the timer ends
    start_npc: <npc id> //The NPC which the quest can be started from
    end_npc: <npc id> //The NPC the player must return to, to complete the quest
    start_balance: [] //A list of required balances to start the quest
    start_cost: [] //A list of required costs to start the quest
    complete_balance: [] //A list of required balances to complete the quest
    complete_cost: [] //A list of required costs to complete the quest
    complete_permissions: //A list of permissions required to complete the quest
    required_quests: [] //A list of required quests before this can be started
    blacklisted_quests: [] //A list of quests which cannot be active when starting
    allowed_worlds: [] //A list of allowed worlds for progressing in the quest
    blacklisted_worlds: [] //A list of blacklisted worlds for progressing in the quest
    allowed_regions: [] //A list of regions which progress can be made (requires World Guard)
    blacklisted_regions: [] //A list of regions which progress cannot be made (requires World Guard)
    start_actions: [] //A list of actions to be executed upon starting the quest
    progress_actions: [] //A list of actions to be executed when a player requests their progress
    cancel_actions: [] //A list of actions to be executed upon canceling the quest
    complete_actions: [] //A list of actions to be executed upon completion

    in_hand: //An item the player must have in their hand to contribute to the quest
      material: <material> //The material of the item
      data: <int> //The data value of the item
      name: <string> //The name of the item
      effects: [] //Specific potion effects of the item (Format: <PotionType>;<Amplifier>;<Duration>
      lore: [] //The lore of the item
      enchants: [] //The enchants of the item (Format: <Enchant>;<Level>)
    Balance Requirements:
    For each quest you can specify start balances, start costs, end balances, and end costs. These are all setup in a list so you can specify multiple requirements which are balance based.

    Balance & Cost Types:
    • PLAYER_EXP - Players EXP
    • PLAYER_LEVEL - Players level
    • PLAYER_FOOD_LEVEL - Players food level
    • PLAYER_HEALTH - Players health
    • PLAYER_SATURATION - Players saturation
    • VAULT - Players Vault economy balance
    • WEEKLY_QUEST_POINTS - Players weekly quest points
    • MONTHLY_QUEST_POINTS - Players monthly quest points
    • TOTAL_QUEST_POINTS - Players total quest points
    • PLAYER_POINTS - Player Points economy balance
    • GANGS_PLUS_GANG - Players gangs balance
    • TOKEN_ENCHANT - Token Enchant token balance
    • TOKEN_MANAGER - Token Manager token balance

    Balance Types (Not valid for cost requirements):
    • ACTIVE_QUESTS - Players total active quests
    • COMPLETED_QUESTS - Players total completed quests
    • ASKYBLOCK_LEVEL - Players ASkyblock island level
    • USKYBLOCK_LEVEL - Players USkyblock island level
    • PRO_VOTES_WEEKLY - Players ProVotes weekly votes
    • PRO_VOTES_MONTHLY - Players ProVotes monthly votes
    • PRO_VOTES_TOTAL - Players ProVotes total votes
    • PLACEHOLDER - Numeric value of a placeholder using PlaceholderAPI
    • PLAYER_STATISTIC - Player specific in-game statistic
    • GANGS_PLUS_PLAYER_KDR - Player Gangs+ KDR
    • GANGS_PLUS_PLAYER_KILLS - Player Gangs+ kills
    • GANGS_PLUS_PLAYER_ASSISTS - Player Gangs+ assists
    • EZ_BLOCKS_BROKEN - Players EZBlocks broken blocks
    Below is an example of a quest with a balance and a cost requirement. You can specify as many requirements as you wish for each. In the example it is also demonstrated how to use a Placeholder balance type.

    Code (Text):
    example_quest:
      type: BREAK_QUEST
      duration: 0
      repeat_delay: 0
      cancelable: true
      start_balance:
      - PLACEHOLDER;10;%playerpoints_points%
      complete_cost:
      - VAULT;500
    So the above example not only shows you how you can specify specific requirements but also demonstrates how to use a Placeholder balance type. The format for Placeholder balance types is as follows:

    PLACEHOLDER;<amount>;<placeholder>

    So from the quest we can see that once the player wants to start the quest they must have at least 10 player points otherwise they won't be able to proceed. Also as you can see once the player is ready to complete the quest they must have and be able to pay $500 from their vault balance (cost types are automatically taken from the players account).

    Statistic balance types allow you to specify specific Minecraft based statistic stats that are required to begin quests such as jumps. A list of valid statistics can be found in the link found in the general section at the top.

    - PLAYER_STATISTIC;<amount>;<statistic type>

    The type itself works rather similarly to the placeholder type, however instead of a placeholder you specify a statistic type. Below is an example that would require the players jump stat to be above 500.

    - PLAYER_STATISTIC;500;JUMP

    Quest Types:
    Below is a full list of all the quests in the plugin and their unique attributes for each

    Internal Quests | External Quests

    Time Types:
    For both quest 'duration' and 'repeat_delay' you can optionally use specific time formats to have adapting formats. This allows for uses such as daily durations, monthly, and for many other uses. These types may be used more throughout the plugin later on.

    • HOURLY - Time until the next hour
    • SEMI_DAILY - Time until noon/midnight
    • DAILY - Time until the next day
    • WEEKLY - Time until the next week
    • BI_WEEKLY - Time until 2 weeks
    • MONTHLY - Time until the next month
    • BI_MONTHLY - Time until 2 months
    • QUARTERLY - Time until 3 months
    • SEMI_ANNUALLY - Time until July 1st/January 1st
    • ANNUALLY - Time until the end of the year

    Creating a quest with multiple stages is a lot easier than it seems and i'll quickly walk you thorough how to make your own stage based quests. In our example we'll use 3 different quests and a stage quest type to link them all together.

    Code (Text):
    break_quest:
      type: BREAK_QUEST
      duration: 0
      repeatable: false
      cancelable: false
      total: 20
      complete_actions:
      - '[StartQuest] chat_quest'

    In the above example you'll notice a couple things. First of all you'll notice that the duration is set to '0' so that the quest won't be canceled during the first stage. Secondly and the most important thing to notice is that once the player has broken the total '20' blocks then it initializes the next quest or 'stage' with the quest identifier of 'chat_quest' which we will define next.

    Code (Text):
    chat_quest:
      type: CHAT_QUEST
      duration: 0
      repeatable: false
      cancelable: false
      response: 'I wanna keep on going'
      complete_actions:
      - '[StartQuest] ezrankup_quest'

    Now we have defined our second quest or "stage" which is started once the player has completed the first 'break_quest'. As you can see most of the values are the same however this one will advance the player to the last stage being the 'ezrankup_quest' once the player says 'I wanna keep in going' in chat.

    Code (Text):
    ezrankup_quest:
      type: EZRANKUP_QUEST
      duration: 0
      repeatable: false
      cancelable: false
      rank: C
      complete_actions: []

    Finally we have defined our last stage which requires the player to rankup to the 'C' rank using EZRanksPro to complete the stage. Now you'll notice we don't have to define any complete actions for this one as its the last stage. All thats left to do is define the stage quest to link all of these together.

    Code (Text):
    stage_quest:
      type: STAGE_QUEST
      duration: 600
      repeatable: false
      cancelable: true
      linked_quests:
      - 'break_quest'
      - 'chat_quest'
      - 'ezrankup_quest'
      start_actions:
      - '[StartQuest] break_quest'
      complete_actions:
      - '[Title] &aYou completed the quest!'
      - '[VaultGive] 5000'

    So what we have defined here is the main quest that links all of these individual stages together. As you can see this gives the player 600 seconds to complete all of the stages linked to the quest, if for some reason it isn't finished and ends partially through it will automatically remove the linked quests that the player has active.

    As can bee seen above the 'linked_quests' are all of the stages built into the overall quest. These must be defined as they let the stage quest know when all of the linked quests have been completed.

    Another thing you will notice is that that the start actions have been defined to start the initial 'break_quest'. This is crucial as it adds the initial quest stage for the player.

    Finally, the complete actions are the actions that will be executed once every single stage has been completed. These actions will not be run until the 'break_quest', 'chat_quest', and 'ezrankup_quest' have been completed, and once they are the player will be greeted with a title and be rewarded with $5000.

    Faction linked quests are very simple to create and allow for some unique team based quest goals. They allow factions to work together to complete a single quest and everyone is rewarded equally. First we'll define the quest that we want everyone to work together on.

    Code (Text):
    break_quest:
      type: BREAK_QUEST
      duration: 0
      repeatable: false
      cancelable: false
      total: 300
      complete_actions: []

    As you'll see theres not too much to it, the only thing you have to worry about are the quest specific factors so in this case it would be the amount of blocks the player has to break, and if we wanted the specific material that would be counted towards the quest. We dont need to define any complete actions here as they need to be defined in the Factions quest to ensure every player is rewarded for completion.

    Code (Text):
    factions_quest:
      type: FACTIONS_QUEST
      duration: 600
      repeatable: false
      cancelable: false
      linked_quest: break_quest
      complete_actions:
      - '[VaultGive] 10000'
    So now after defining our Factions quest framework any faction can now start the quest using the 'factions_quest' identifier. It doesnt require any other action to start the linked quest as its handled automatically unlike the Stage quest. This quest will require the entire faction to complete the 'break_quest' in 600 seconds and in collaboration. Once they have broken a total of 300 blocks all together every player will be rewarded with $10000.

    [​IMG]

    Within the plugin you can create immersive quest menus to make the overall experience more extensive and also easier to use/understand. This section will give you examples of menus and also explain easily how to create you own.

    Menu Features:
    - Shift-Right-Click active quest to cancel

    Actions:
    As of version 1.5.0.2 any menu item can have unique actions defined to execute when clicked. It can simply be added as a list of executes that will execute, here is an example:

    Code (Text):
    menu:
      menu_1:
        name: '&8Quests'
        size: 9
        break:
          slot: 4
          completed:
            item: EMERALD;1;0
            name: '&aBreak Quest'
            glow: false
            lore:
            - '&7You completed the quest!'
            actions:
            - '[Message] &cThe quest has already been completed!'

    Placeholder Items:
    If while working in your menu you want to add an item that is not linked to a specific quest type you can do so by specifying a "placeholder item" which can have its own actions when clicked.

    Each placeholder item must have a unique identifier (otherwise it won't load). If you have 2 placeholder items with the same identifier it will not load both, and other issues may arise. Placeholder items identifier must start with 'placeholder_item_' and then you must add a unique character sequence to follow.

    Valid identifier: placeholder_item_1
    Invalid identifier: placeholder_item1

    Below is an example of how to define a placeholder item in a menu:
    In this example we are going to define 2 placeholder items that will appear in the "general" menu. One item when clicked will teleport the player to spawn, and the other will not have any actions assigned (will do nothing).

    Code (Text):
    menu:
      general: //The menu identifier
        name: '&8General'
        size: 9
        placeholder_item_1: //The first placeholder item identifier
          slot: 0
          item: IRON_BLOCK;1;0
          name: '&aFirst Item'
          lore:
          - '&7First item lore'
          actions:
          - '[PlayerCommand] spawn'
        placeholder_item_2: //The second placeholder item identifier
          slot: 1
          item: DIAMOND_BLOCK;1;0
          name: '&bSecond Item'
          lore:
          - '&7Second item lore'
    So as you can see above we created a quest menu with the 'general' identifier and also assigned 2 placeholder items within the menu ('placeholder_item_1' & 'placeholder_item_2'). As for every other item you must specify a name, and a slot for the item. Optionally you can define a lore and actions for placeholder items.

    For the first placeholder item you can see that we have set it to place in the first slot of the menu and that we have defined a [PlayerCommand] action. This action will execute once clicked, also prior to any actions being executed the menu will close (to prevent errors if opening other menus). The actions section will support any of the listed actions within the plugin.

    Finally for the second placeholder item you can see it will appear in the second slot, and has no actions assigned to it. This means that when clicked it will simply cancel and return to normal. This type of item can be used to create borders etc.

    And thats it, this is how you create a placeholder item!

    Code (Text):
    # ======================================================
    #
    # ProQuests Version: 1.3.7
    # Created by: JC_Plays_MC
    #
    # ======================================================
    #
    # Menu File
    #
    # This is the menu file where all of the items which will be displayed in
    # the quests menus will be defined. Each item has 5 states which will display
    # differently based on the players relation to the quest. You can create as many quest
    # menus as you wish.
    #
    # ======================================================
    #
    # Menu Example:
    #
    # menu:
    #   <menu identifier>:
    #     name: '&8Quests'
    #     size: 54
    #     <quest identifier>:
    #       slot: 0
    #       waiting:
    #         item: EMERALD_BLOCK;1;0
    #         name: '&aWaiting'
    #         glow: false
    #         lore:
    #         - '&7Waiting for quest'
    #       completed:
    #         item: EMERALD_BLOCK;1;0
    #         name: '&aCompleted'
    #         glow: false
    #         lore:
    #         - '&7Completed quest'
    #       active:
    #         item: STONE;1;0
    #         name: '&aIn Progress'
    #         glow: true
    #         lore:
    #         - '&7%quest_remaining_duration%'
    #       available:
    #         item: STONE;1;0
    #         name: '&aStart now!'
    #         glow: false
    #         lore:
    #         - '&7Click to start!'
    #       unavailable:
    #         item: COAL_BLOCK;1;0
    #         name: '&cUnavailable'
    #         glow: false
    #         lore:
    #         - '&7Quest is unavailable'
    #
    # ======================================================
    #
    # Item Format:
    # All menu items are formatted in the following way for defining items for the menu. Items use
    # the following format <Material>;<Amount>;<Data>
    #
    # A list of valid materials can be found here:
    # https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html
    #
    # Placeholders:
    # There are a bunch of placeholders built into the plugin that can be used in messages or
    # item names, lore etc. These can all be found on the plugin page.
    #
    # ======================================================

    menu:
      menu_1:
        name: '&8Quests'
        size: 54
        break_quest_1:
          slot: 0
          waiting:
            item: EMERALD_BLOCK;1;0
            name: '&aCompleted!'
            glow: false
            lore:
            - '&7You have completed this quest, and'
            - '&7can repeat it in %quest_repeat_delay%'
          completed:
            item: EMERALD_BLOCK;1;0
            name: '&aCompleted!'
            glow: false
            lore:
            - '&7You have completed this quest, why'
            - '&7not start another one!'
          active:
            item: STONE;1;0
            name: '&eBlock Breaker!'
            glow: true
            lore:
            - '&7You only have %quest_remaining_duration%'
            - '&7to complete this quest'
            - ''
            - '&6Goal: &fBreak 15 blocks'
            - '%quest_progress_bar%'
            - '&8&m-------------------'
            - '&e&lREWARD:'
            - '&7- &a$5000'
          available:
            item: STONE;1;0
            name: '&6Block Breaker!'
            glow: false
            lore:
            - '&7You are eligble to begin this quest!'
            - '&7Click to start now!'
            - ''
            - '&6Goal: &fBreak 15 blocks'
            - '&8&m-------------------'
            - '&e&lREWARD:'
            - '&7- &a$5000'
          unavailable:
            item: COAL_BLOCK;1;0
            name: '&cBlock Breaker!'
            glow: false
            lore:
            - '&7You are ineligable to begin this quest,'
            - '&7as you have not completed the required quests'
        chat_quest_1:
          slot: 1
          waiting:
            item: EMERALD_BLOCK;1;0
            name: '&aCompleted!'
            glow: false
            lore:
            - '&7You have completed this quest, and'
            - '&7can repeat it in %quest_repeat_delay%'
          completed:
            item: EMERALD_BLOCK;1;0
            name: '&aCompleted!'
            glow: false
            lore:
            - '&7You have completed this quest, why'
            - '&7not start another one!'
          active:
            item: STONE;1;0
            name: '&eWord Speaker!'
            glow: true
            lore:
            - '&7You only have %quest_remaining_duration%'
            - '&7to complete this quest'
            - ''
            - '&6Goal: &fSay ''im awesome!'''
            - '&8&m-------------------'
            - '&e&lREWARD:'
            - '&7- &a64x Diamonds'
          available:
            item: STONE;1;0
            name: '&6Word Speaker!'
            glow: false
            lore:
            - '&7You are eligble to begin this quest!'
            - '&7Click to start now!'
            - ''
            - '&6Goal: &fSay ''im awesome!'''
            - '&8&m-------------------'
            - '&e&lREWARD:'
            - '&7- &a64x Diamonds'
          unavailable:
            item: COAL_BLOCK;1;0
            name: '&cWord Speaker!'
            glow: false
            lore:
            - '&7You are ineligable to begin this quest,'
            - '&7as you have not completed the required quests'

    Potion Effects:
    If you wish to use a "POTION" as an item within your menu you can optionally define the effects which it has attributed to it. The format is rather simple as an example is below:

    Code (Text):
          unavailable:
            item: POTION;1;0
            effects:
            - JUMP;2;1200
            name: '&cExample!'
            glow: false
            lore:
            - '&7You are ineligable to begin this quest,'
            - '&7as you have not completed the required quests'

    So as you can see it is a list of effects you wish to apply to the item in the following format <PotionType>;<Amplifier>;<Duration>.


    [​IMG]

    NPC's are a vital aspect to getting an immersive quest experience and with ProQuests there are plenty of features to make your ideas possible. You can set NPC's to open quest menus where players can easily choose a quest they want to start or even view their progress. There are also 'Quest' NPC's which allow you to have a number of quests specific to certain NPC's in which they must start or end the quest by visiting them.

    NPC Features:
    - Shift-Right-Click to cancel active quest
    - Right-Click to receive the progress actions

    How do you create an NPC?
    Creating a NPC is rather simple, first you need to decide what type of NPC you wish to create either a "Menu", "Leader", or "Quest" NPC. Once you know which one you wish to create enter the corresponding command filling in the other required arguments such as the NPC identifier.

    Menu NPC:
    /proquests npccreate menu <npc identifier> <menu identifier>

    Leader NPC: (Requires Citizens)
    /proquests npccreate leader <npc identifier> <leaderboard type> <position>

    If you have created a 'Leader' NPC there are a few other options you have to configure it to your liking. If you have HolographicDisplays on your server you can specify hologram lines that will be displayed above the NPC.

    Example:
    Code (Text):
    npcs:
      leader_monthly:
        npc_type: LEADER
        leaderboard_type: MONTHLY
        location: world,0,0,0,180,0
        position: 1
        actions:
        - '[PlayerCommand] quest leaderboard monthly'
        hologram_lines:
        - '&bMONTHLY POINTS LEADER'
        - '&7(&a%monthly_points% points&7)'
    Quest NPC:
    /proquests npccreate quest <npc identifier>

    If you have created a 'Quest' NPC you will have to do some additional configuration to get it working as you wish. The first thing you need to do is open the npc.yml file and define the quests you wish to link to the specific NPC.

    Example:
    Code (Text):
    npcs:
      example:
        npc_type: QUEST
        location: Free,122,63,-84
        entity_type: VILLAGER
        out_of_quests_actions:
        - '[Message] &8&m-----------------------------'
        - '[Message] &cSorry, I have no other quests to offer'
        - '[Message] &8&m-----------------------------'
        linked_quests:
        - <1st quest identifier>
        - <2nd quest identifier>
        ...
    For each quest NPC you must specify quests in which are connected to this specific NPC. The NPC's can be used to start or end the quest and must be specified for each quest individually as well (Start/End NPC). The order for starting and completing quests from the NPC's are ordered from top to bottom in the list and you can specify as many linked quests as you wish. Below is a completed example of a quest.yml and a npc.yml that will require the player to start and finish the quest via the specific NPC.

    npc.yml:
    Code (Text):
    npcs:
      example:
        npc_type: QUEST
        location: Free,68,66,-69
        entity_type: VILLAGER
        name: Test
        out_of_quests_actions:
        - '[Message] &8&m-----------------------------'
        - '[Message] &cSorry, I have no other quests to offer'
        - '[Message] &8&m-----------------------------'
        linked_quests:
        - break1
    quests.yml:
    Code (Text):
    quests:
      break1:
        type: BREAK_QUEST
        duration: -1
        repeat_delay: 0
        start_cost: 0
        start_npc: example
        end_npc: example
        repeatable: false
        cancelable: true
        command_start: false
        complete_balance: 0
        complete_cost: 0
        total: 10
        complete_actions:
        - '[Title] &aQuest Completed!'

    [​IMG]

    (Work in progress)

    [​IMG]

    Question: The plugin won't work/load!
    Answer: Check to make sure you're using Java 8 on your server. If you're not or if you are unsure contact your service provider (don't ask me).

    Question: What is a data value?
    Answer: http://minecraft.gamepedia.com/Data_values


    Question: I created a NPC but it doesn't work anymore, why?
    Answer: NPC's are created based off of locations so you must use a plugin such as Citizens which handles spawning of entities. You would then create your NPC with an external plugin and assign it using ProQuests commands/selection system.

    Question: Players have permission to cancel the quest but still can't?

    Answer: If you have given the players the 'proquests.cancel' and they still cannot cancel the quest you probably have 'cancelable' set to false for the specific quest. To allow for players to cancel a specific quest 'cancelable' must be set to true

    Question: I tried to start a quest but got the following message 'You cannot start this quest as you are in operator mode'

    Answer: By default OP players cannot start quests, you can allow OP players to start quests by setting 'allow_op_quest' to true in the config.yml

    Question: How do I return to the editor while its requesting a value?

    Answer: If you are editing/creating a quest and you want to return to the editor menu you can always just enter '[cancel]' into chat and it will re-open the editor, cancelling the request for a entry.

    Question: Players can take items from the menus, why?

    Answer: Make sure you are closing any menus/guis prior to attempting to open another. So if you are using CustomGUI for example you need to close the open gui prior to executing the command to open the quest menu. This is required in 1.9

    Question: Im receiving an error in console when players try to open a menu, what did I do wrong?
    Answer: If your error contains the following you have specified a quest placeholder that does not exist for the quest type specified. For example you can't use '%quest_progress_bar%' for a CHAT_QUEST
    Code (Text):
    Caused by: java.lang.NullPointerException
        at me.jacobculley.proquests.Messages.questSpecificPlaceholders(Messages.java:463) ~[?:?]
  • Loading...
  • Loading...