Tasks Documentation

Tasks

Reward players for doing actions. Highly configurable, with daily and weekly tasks, a quest-like progression system, a levelling curve, and unlocks granted at milestone levels.

Download Tasks on SpigotMC

Installation

  1. Add the Tasks jar into your plugins folder.
  2. Restart your server.
  3. Edit config.yml, tasks.yml and unlocks.yml to your liking.
  4. Type /ta reload.

Commands

User Commands

  • /tasks — List your current tasks.
  • /tasks skip <number> — Skip a task.
  • /tasks color <color> — Change the color of your personal task related messages.
  • /quests — List your active quests.
  • /quests info <quest> — Show a quest's status, rewards, and steps.
  • /quests available — List quests you can pick up with /quests accept.
  • /quests accept <quest> — Accept an available quest.
  • /quests abandon <quest> — Abandon an active quest (its progress is lost).
  • /quests completed — List the quests you have completed.
  • /quests gui — Open the quest menu.
  • /level — Check your level and experience.
  • /unlocks — List your unlocks.

Admin Commands

Use the /tasksadmin (/ta) command for admin things.

  • /ta help — Show the help message.
  • /ta reload — Reload the plugin.
  • /ta task list <player> — List a player's tasks.
  • /ta task give <player> <task> — Give a player a task.
  • /ta task remove <player> <task> — Remove a task from a player.
  • /ta task addprogress <player> <task> <amount> — Add progress to a task.
  • /ta xp give <player> <amount> — Give a player XP (Tasks plugin XP, not Minecraft XP).
  • /ta xp take <player> <amount> — Take XP from a player.
  • /ta xp set <player> <amount> — Set a player's XP.
  • /ta unlock list <player> — List a player's unlocks.
  • /ta unlock give <player> <unlock> — Give a player an unlock.
  • /ta skips give <player> <amount> — Give a player skips.
  • /ta skips take <player> <amount> — Take skips from a player.
  • /ta skips set <player> <amount> — Set a player's skips.

Use the /questsadmin (/qa) command for quest admin things.

  • /qa help — Show the help message.
  • /qa reload — Reload the plugin.
  • /qa quest list <player> — List a player's quests.
  • /qa quest give <player> <quest> — Give a player a quest.
  • /qa quest remove <player> <quest> — Remove a quest from a player.
  • /qa quest addprogress <player> <quest> <amount> — Add progress to a quest.
  • /qa quest abandon <player> <quest> — Abandon a player's active quest.
  • /qa quest reset <player> <quest> — Reset a player's progress, completion, decline, and cooldown for a quest.
  • /qa quest cleardeclined <player> [quest] — Clear declined quests so they auto-track again.

Permissions

  • tasks.color (default) — Allows the player to change the color of their tasks.
  • tasks.admin — Allows the player to use admin commands.
  • tasks.admin.reload — Allows the player to reload the plugin.
  • tasks.admin.task — Allows the player to alter players' tasks.
  • tasks.admin.xp — Allows the player to alter players' XP.
  • tasks.admin.unlock — Allows the player to alter players' unlocks.
  • tasks.admin.skips — Allows the player to alter players' skips.
  • tasks.admin.quest — Allows the player to alter players' quests.

Config

levels:
  enable: true # Enable or disable the leveling system.
  display-level-in-chat: true # Display the player's level in chat messages. You may need to set paper-chat-events: false in essentials config.yml for this to work if you are using EssentialsXChat.
  chat-prefix-format: '&f[{color}{level}&f] ' # The format for chat messages.
  xp-curve:
    base: 10 # The base amount of XP required to level up.
    multiplier: 1.02 # The xp increase each level (exponential).
tasks:
  allow-skipping: true # Allow players to skip tasks.
  max-tasks: 8 # Maximum number of tasks to give a player at one time.
  reward-xp-multiplier: 1.0 # Multiplier for task XP rewards, use this to rebalance xp without changing every task.
  reward-money-multiplier: 1.0 # Multiplier for task money rewards, use this to rebalance money without changing every task. Set to 0 to disable money rewards.
quests:
  reward-xp-multiplier: 1.0 # Multiplier for quest XP rewards.
  reward-money-multiplier: 1.0 # Multiplier for quest money rewards. Set to 0 to disable money rewards.
  max-active: 0 # Maximum active quests per player. 0 = unlimited. Auto-tracked quests stop being added at the cap.
  reset-hour: 0 # Hour (0-23, server local time) that daily/weekly repeatable quests reset at.
  gui-enabled: true # Enable the /quests gui menu.
notifications:
  enable-sounds: true # Master toggle for notification sounds.
  sounds: # Per-event sound, volume (0-10), and pitch (0-2). Use sound "none" to silence an event.
    new-quest: { sound: entity.experience_orb.pickup, volume: 1.0, pitch: 1.0 }
    step-completed: { sound: entity.player.levelup, volume: 1.0, pitch: 1.5 }
    quest-completed: { sound: ui.toast.challenge_complete, volume: 1.0, pitch: 1.0 }
    # ...also: quest-removed, new-task, task-removed, task-expired, level-up, generic
titles: # On-screen titles. Use & color codes; {quest} and {level} are substituted.
  fade-in-ticks: 10
  stay-ticks: 40
  fade-out-ticks: 10
  quest-complete: { enabled: true, title: '&6&lQuest Complete!', subtitle: '&f{quest}' }
  level-up: { enabled: false, title: '&6&lLevel Up!', subtitle: '&fLevel {level}' }
lists:
  page-size: 8 # Number of entries shown per page in the /tasks and /quests lists (1-50).

Task Parameters

Task parameters are used to configure tasks in tasks.yml.

Example:

task1:
    triggers:
        - break_block
    block-materials:
        - diamond_ore
    amount: 10

This example task (task1) will require the player to break 10 diamond ore blocks.

Behavior

  • amount — The number of times the task action must be completed.
  • time-limit-minutes — The time the player has to complete the task.
  • reset-on-death — If true, progress resets when the player dies.
  • skippable — If true, the player can skip the task.

Display

  • message — The message shown to the player when the task is active.
  • actionbar — If true, task progress is displayed in the action bar.
  • progress-display — Controls how progress is formatted (STANDARD, PERCENT, TIME).

Start Requirements

  • repeatable — If true, the task can be completed multiple times.
  • min-level — The minimum player level required to start the task.
  • max-level — The maximum player level allowed to start the task.
  • prerequisite-tasks — List of tasks that must be completed before this one.
  • incompatible-tasks — List of tasks that cannot be active at the same time.
  • permission — The permission node required to access the task.

Rewards

  • reward-money — Amount of in-game currency awarded on completion.
  • reward-xp — Amount of experience points awarded on completion.
  • reward-skips — Number of task skips awarded on completion.
  • reward-unlocks — List of unlocks given upon completion. See the Unlock Parameters section below.
  • reward-console-commands — Console commands executed when the task is completed. Use the variable {player} to insert the player's username.
  • reward-player-commands — Commands executed by the player when the task is completed. Use the variable {player} to insert the player's username.
  • reward-messages — Messages sent to the player as a reward. Use the variable {player} to insert the player's username.

Triggers

  • triggers — List of trigger types that progress the task. For a full list of available triggers, see the Trigger Types section below.

Location Filters

  • worlds — Worlds where the task can be completed.
  • environments — Allowed environments (e.g. NETHER, OVERWORLD).
  • biomes — Allowed biomes for task progress.
  • min-x — Minimum X coordinate where the task can be completed.
  • max-x — Maximum X coordinate where the task can be completed.
  • min-y — Minimum Y coordinate where the task can be completed.
  • max-y — Maximum Y coordinate where the task can be completed.
  • min-z — Minimum Z coordinate where the task can be completed.
  • max-z — Maximum Z coordinate where the task can be completed.

Entity Filters

  • entity-in-water — If true, only counts entities in water.
  • entity-on-ground — If true, only counts entities on the ground.
  • entity-names — List of entity names to match for the task.
  • entity-types — List of entity types to match for the task.
  • entity-categories — List of entity categories to match for the task.

Item Filters

  • item-names — List of item names to match for the task.
  • item-materials — List of item materials to match for the task.

Block Filters

  • block-materials — List of block materials to match for the task.

Quest Parameters

Quests are goals made of ordered steps that players complete in sequence. Quest parameters are used to configure quests in quests.yml. Each step takes the same trigger, filter, display, and reward parameters as a task (see Task Parameters); the parameters below are set at the quest level.

Example:

exampleQuest:
  name: First Steps
  auto-track: true
  reward-xp: 100
  steps:
    1:
      message: Mine 10 stone
      triggers:
        - break_block
      block-materials:
        - stone
      amount: 10
    2:
      message: Craft a wooden pickaxe
      triggers:
        - craft_item
      item-materials:
        - wooden_pickaxe
      amount: 1
      reward-xp: 25 # Optional per-step reward, granted when this step is finished.

Display

  • name — Short name of the quest.
  • message — Display text shown for the quest (falls back to name, then the quest id).
  • icon — Optional material shown for the quest in the /quests gui menu.

Acquisition

  • auto-track — If true (default), the quest is added automatically when the player becomes eligible. If false, players pick it up with /quests accept. Players can drop an active quest with /quests abandon; an abandoned auto-track quest is not re-added until accepted again (or cleared by an admin).

Repetition

  • repeatable — If true, the quest can be completed more than once (one-time by default). Completed quests still count toward prerequisite-quests.
  • cooldown-minutes — For repeatable quests, a relative cooldown (in minutes) after each completion before it can be done again.
  • reset-period — For repeatable quests, none, daily, or weekly. Daily/weekly resets occur at the quests.reset-hour configured in config.yml.

Start Requirements

  • min-level — The minimum player level required to start the quest.
  • max-level — The maximum player level allowed to start the quest.
  • prerequisite-quests — List of quests that must be completed before this one.
  • incompatible-quests — List of quests that cannot be active at the same time.
  • permission — The permission node required to access the quest.

Rewards

Quest-level rewards (granted when the whole quest is completed) use the same keys as task rewards: reward-money, reward-xp, reward-skips, reward-unlocks, reward-console-commands, reward-player-commands, and reward-messages. Each step may also carry its own rewards, granted when that step is finished.

Steps

  • steps — A numbered map of objectives, completed in numeric order. Each step accepts amount, message, actionbar, progress-display, the trigger/filter keys, and optional per-step rewards — exactly like a task.

Unlock Parameters

Unlocks are rewards that can be given to players at certain levels or as rewards for completing certain tasks. Unlock parameters are used to configure unlocks in unlocks.yml.

Example:

exampleMessageUnlock:
  name: Example Message Unlock # The display name of this unlock
  messages: # The messages sent by this unlock
  - You got the example message unlock!
  - Line 2!
  - Line 3!
  level: 1 # The level the player gets this unlock

examplePermissionsUnlock:
  name: Example Permissions Unlock # The display name of this unlock
  permissions: # The permissions granted by this unlock
  - example.permission.node
  - example.permission.node2
  level: 500 # The level the player gets this unlock

exampleCommandsUnlock:
  name: Example Commands Unlock # The display name of this unlock
  console-commands: # The commands executed by this unlock
  - say {player} got the example commands unlock!
  - eco give {player} 100
  player-commands:
  - say I got the example commands unlock!
  level: 500 # The level the player gets this unlock

Display

  • name — The display name of the unlock.

Behavior

  • level — The level the unlock is given at.

Rewards

  • permissions — Permissions given to the player when unlocked.
  • console-commands — Console commands to run when unlocked. Use the variable {player} to insert the player's username.
  • player-commands — Commands for the player to run when unlocked. Use the variable {player} to insert the player's username.
  • messages — Messages to send to the player when unlocked. Use the variable {player} to insert the player's username.

Trigger Types

Triggers control when tasks get triggered. Each time a player triggers a task it will increment the task by the amount in Associated Data.

Entity Triggers

INTERACT_ENTITY

  • Description: Triggered when a player right clicks an entity.
  • Associated Data:
    • Location: The location of the entity
    • Entity: The entity interacted with
    • Item: The item in the player's hand
    • Amount: 1

DAMAGE_ENTITY

  • Description: Triggered when a player damages an entity.
  • Associated Data:
    • Location: The location of the entity
    • Entity: The entity damaged
    • Item: The item in the player's hand
    • Amount: The damage amount

KILL_ENTITY

  • Description: Triggered when an entity is killed by a player.
  • Associated Data:
    • Location: The location of the entity
    • Entity: The entity killed
    • Item: The item in the player's hand
    • Amount: 1

BUCKET_ENTITY

  • Description: Triggered when a player buckets an entity.
  • Associated Data:
    • Location: The location of the entity
    • Entity: The entity targeted
    • Item: The bucket
    • Block: The block the entity is in
    • Amount: 1

SHEAR_ENTITY

  • Description: Triggered when a player shears an entity.
  • Associated Data:
    • Location: The location of the entity
    • Entity: The entity sheared
    • Item: The item used
    • Amount: 1

TAME_ENTITY

  • Description: Triggered when a player tames an entity.
  • Associated Data:
    • Location: The location of the entity
    • Entity: The entity tamed
    • Item: The item in the player's hand
    • Amount: 1

MANIPULATE_ARMORSTAND

  • Description: Triggered when a player interacts with an armor stand.
  • Associated Data:
    • Location: The location of the armorstand
    • Entity: The armor stand
    • Item: The item held by the player
    • Amount: 1

THROW_EGG

  • Description: Triggered when a player throws an egg.
  • Associated Data:
    • Location: The location of the egg entity
    • Entity: The egg entity
    • Item: The egg item
    • Amount: 1

PICKUP_ARROW

  • Description: Triggered when a player picks up an arrow.
  • Associated Data:
    • Location: The location of the arrow entity
    • Entity: The arrow entity
    • Block: The block the arrow is attached to
    • Amount: 1

Item Triggers

CRAFT_ITEM

  • Description: Triggered when a player crafts an item.
  • Associated Data:
    • Location: The location of the block
    • Entity: The player crafting the item
    • Item: The crafted item
    • Block: The block used to craft the item
    • Amount: The amount crafted

ENCHANT_ITEM

  • Description: Triggered when a player enchants an item.
  • Associated Data:
    • Location: The location of the enchanting table
    • Entity: The player enchanting the item
    • Item: The enchanted item
    • Block: The enchanting table
    • Amount: 1

CONSUME_ITEM

  • Description: Triggered when a player consumes an item.
  • Associated Data:
    • Location: The location of the player
    • Entity: The player
    • Item: The consumed item
    • Amount: The quantity of the item consumed

HARVEST_ITEM

  • Description: Triggered when a player harvests an item from a block.
  • Associated Data:
    • Location: The location of the block
    • Entity: The player
    • Item: The harvested item
    • Block: The block harvested from
    • Amount: The amount harvested

SMELT_ITEM

  • Description: Triggered when a player smelts an item.
  • Associated Data:
    • Location: The location of the block
    • Item: The smelted item
    • Block: The block used to smelt
    • Amount: The amount smelted

BREAK_ITEM

  • Description: Triggered when a player breaks an item.
  • Associated Data:
    • Location: The location of the player
    • Entity: The player breaking the item
    • Item: The broken item
    • Amount: The stack size of the broken item

DAMAGE_ITEM

  • Description: Triggered when a player's item takes damage.
  • Associated Data:
    • Location: The location of the player
    • Entity: The player whose item is damaged
    • Item: The damaged item
    • Amount: The damage amount

MEND_ITEM

  • Description: Triggered when a player's item is mended.
  • Associated Data:
    • Location: The location of the player
    • Entity: The player whose item is mended
    • Item: The mended item
    • Amount: The amount mended

DROP_ITEM

  • Description: Triggered when a player drops an item.
  • Associated Data:
    • Location: The location of the item entity
    • Entity: The dropped item entity
    • Item: The dropped item
    • Amount: The amount dropped

BREAK_BLOCK_DROP_ITEM

  • Description: Triggered when a player breaks a block and it drops an item.
  • Associated Data:
    • Location: The location of the block
    • Entity: The player breaking the block
    • Item: The dropped item
    • Block: The broken block
    • Amount: The amount dropped

KILL_ENTITY_DROP_ITEM

  • Description: Triggered when a player kills an entity and it drops an item.
  • Associated Data:
    • Location: The location of the killed entity
    • Entity: The killed entity
    • Item: The dropped item
    • Amount: The amount dropped

Block Triggers

BREAK_BLOCK

  • Description: Triggered when a player breaks a block.
  • Associated Data:
    • Location: The location of the block
    • Entity: The player breaking the block
    • Item: The item held by the player
    • Block: The broken block
    • Amount: 1

PLACE_BLOCK

  • Description: Triggered when a player places a block.
  • Associated Data:
    • Location: The location of the block
    • Entity: The player placing the block
    • Item: The item in the player's hand
    • Block: The placed block
    • Amount: 1

HARVEST_BLOCK

  • Description: Triggered when a player harvests a block (e.g. berries).
  • Associated Data:
    • Location: The location of the block
    • Entity: The player harvesting the block
    • Item: The item in the player's hand
    • Block: The harvested block
    • Amount: 1

TAKE_LECTERN_BOOK

  • Description: Triggered when a player takes a book from a lectern.
  • Associated Data:
    • Location: The location of the lectern
    • Entity: The player taking the book
    • Item: The book
    • Block: The lectern
    • Amount: The amount of the book

FILL_BUCKET

  • Description: Triggered when a player fills a bucket.
  • Associated Data:
    • Location: The location of the source block
    • Entity: The player filling the bucket
    • Item: The filled bucket
    • Block: The source block
    • Amount: 1

EMPTY_BUCKET

  • Description: Triggered when a player empties a bucket.
  • Associated Data:
    • Location: The location of the target block
    • Entity: The player emptying the bucket
    • Item: The bucket
    • Block: The target block
    • Amount: 1

ENTER_BED

  • Description: Triggered when a player enters a bed.
  • Associated Data:
    • Location: The location of the bed
    • Entity: The player entering the bed
    • Block: The bed
    • Amount: 1

LEAVE_BED

  • Description: Triggered when a player leaves a bed.
  • Associated Data:
    • Location: The location of the bed
    • Entity: The player leaving the bed
    • Block: The bed
    • Amount: 1

Player Triggers

RIPTIDE

  • Description: Triggered when a player launches themself with riptide.
  • Associated Data:
    • Location: The location of the player
    • Entity: The player using the trident
    • Item: The trident
    • Amount: 1

TELEPORT_TO

  • Description: Triggered when a player teleports to a location.
  • Associated Data:
    • Location: The destination
    • Entity: The player teleporting
    • Item: The item in the player's hand
    • Amount: 1

TELEPORT_FROM

  • Description: Triggered when a player teleports from a location.
  • Associated Data:
    • Location: The origin
    • Entity: The player teleporting
    • Item: The item in the player's hand
    • Amount: 1

PORTAL_TO

  • Description: Triggered when a player enters a portal to a location.
  • Associated Data:
    • Location: The destination
    • Entity: The player entering the portal
    • Item: The item in the player's hand
    • Block: The block portaled to
    • Amount: 1

PORTAL_FROM

  • Description: Triggered when a player leaves a portal from a location.
  • Associated Data:
    • Location: The origin
    • Entity: The player entering the portal
    • Item: The item in the player's hand
    • Block: The block portaled from
    • Amount: 1

DEATH

  • Description: Triggered when a player dies.
  • Associated Data:
    • Location: The location of the player who died
    • Entity: The player who died
    • Item: The item in hand
    • Amount: 1

RESPAWN

  • Description: Triggered when a player respawns.
  • Associated Data:
    • Location: The respawn location
    • Entity: The player respawning
    • Item: The item in the player's hand
    • Amount: 1

TIMER

  • Description: Executes once per second.
  • Associated Data:
    • Location: The location of the player
    • Entity: The player with the task
    • Item: The item in the player's hand
    • Amount: 1