Quests

Quest files are located in plugins/SpContentQuests/quests/. Each .yml file can contain one or more quests. The quest ID (the YAML key) is a unique identifier used in commands.

Basic Structure

QUEST_ID:
  category: overworld
  slot: 23
  page: 1

  requirements:
    - type: QUEST
      quest: ANOTHER_QUEST
      display: '&cRequires <quest>'

  icon:
    item: DIAMOND
    amount: 1
    model: 0
    skullvalue: ''
    display: '&bQuest Name'
    desc:
      - '&7Description here.'

  objective:
    - type: BREAK_BLOCK
      amount: 10
      required:
        - DIAMOND_ORE
      display: '&fMine Diamonds'
      desc:
        - '&7Go to the mine and break'
        - '&710 diamond ore blocks.'
      command:
        - '[player] warp mine'
        - '[close]'
      icon:
        item: DIAMOND_ORE
        skullvalue: ''
        modeldata: 0
        amount: 1

  objective-command:
    - '[player] warp mine'
    - '[close]'

  reward-display:
    - '&f5x Diamond'
  reward-command:
    - '[console] give %player% diamond 5'

Fields

Field	Required	Description
category	Yes	Category ID (must match a filename in category/)
slot	Only if manual layout	GUI slot position (0–53)
page	Only if manual layout	GUI page number
requirements	No	Prerequisites to unlock this quest
icon	Yes	The quest's display item
objective	Yes	List of objectives the player must complete
objective-command	No	Command(s) run when left-clicking the quest
reward-display	No	Text shown in the reward section
reward-command	Yes	Command(s) run when claiming the reward

Icon

icon:
  item: DIAMOND           # Minecraft material name
  amount: 1                # Stack size
  model: 0                 # Custom model data (for resource packs)
  skullvalue: ''           # Base64 texture (for PLAYER_HEAD items)
  display: '&bQuest Name'  # Display name (supports & colors)
  desc:                    # Lore/description lines
    - '&7Description here.'

Note: For player heads, use item: PLAYER_HEAD and provide a Base64 texture value in skullvalue.

Requirements

Requirements are optional. If omitted, the quest is always available. See the Requirements page for details.

requirements:
  - type: QUEST
    quest: ANOTHER_QUEST
    display: '&cRequires <quest>'
  - type: PERMISSION
    permission: myplugin.vote
    display: '&cRequires permission: <permission>'
  - type: PLACEHOLDER
    data-type: string
    operator: '=='
    input: '%some_placeholder%'
    output: 'value'
    display: '&cRequires condition'

Objectives

Each quest can have one or more objectives. See the Objective Types page for a complete list.

objective:
  - type: BREAK_BLOCK
    amount: 10
    required:
      - DIAMOND_ORE
    display: '&fMine Diamonds'
    desc:
      - '&7Description here.'
    command:
      - '[player] warp mine'
    icon:
      item: DIAMOND_ORE
      skullvalue: ''
      modeldata: 0
      amount: 1

Per-Objective Icon Override

Each objective can optionally include an icon section to override the default objective-item appearance from gui-objective.yml:

objective:
  - type: CRAFT
    amount: 10
    icon:
      item: BREAD
      skullvalue: ''
      modeldata: 0
      amount: 1

If no icon is defined, the default from objective-item in gui-objective.yml is used.

Objective Commands

objective-command:
  - '[player] warp mine'
  - '[close]'

These commands run when the player left-clicks the quest in the category GUI. Useful for teleporting the player to where they need to go.

Objective Per-Objective Commands

objective:
  - type: BREAK_BLOCK
    amount: 10
    command:
      - '[player] warp mine'
      - '[close]'

These commands run when the player clicks the individual objective in the objective GUI.

Rewards

reward-display:
  - '&f5x Diamond'
reward-command:
  - '[console] give %player% diamond 5'

The reward-display is text shown in the GUI. The reward-command is executed when the player claims the reward.

Reward Command Prefixes

Prefix	Description
[console] <cmd>	Runs as console
[player] <cmd>	Runs as the player
[close]	Closes the GUI
[redirect]	Reopens the quest objective GUI after closing current GUI
%player%	Replaced with the player's name

Note: The [redirect] prefix is useful when a command opens an external GUI (e.g., a recipe book) — when the player closes it, the quest objective GUI will reopen.

Multiple Quests Per File

You can define multiple quests in a single .yml file:

QUEST_ONE:
  category: overworld
  icon:
    item: DIAMOND
    display: '&bQuest One'
  objective:
    - type: BREAK_BLOCK
      amount: 10
      required: [DIAMOND_ORE]
  reward-command:
    - '[console] give %player% diamond 1'

QUEST_TWO:
  category: overworld
  icon:
    item: IRON_INGOT
    display: '&fQuest Two'
  objective:
    - type: CRAFT
      amount: 5
      required: [IRON_INGOT]
  reward-command:
    - '[console] give %player% iron_ingot 3'

Or split them across multiple files — both approaches work.