Categories

Categories group related quests together in their own GUI. Each .yml file in plugins/SpContentQuests/category/ becomes a separate category with its own unique ID (the filename without .yml).

Example

category/overworld.yml:

gui-name: '&nQuests&8 -> Overworld'
gui-rows: 6

sound:
  click:    { id: ITEM_BOOK_PAGE_TURN, pitch: 1.0, volume: 1.0 }
  complete: { id: ENTITY_PLAYER_LEVELUP, pitch: 1.0, volume: 1.0 }
  claim:    { id: BLOCK_NOTE_BLOCK_PLING, pitch: 1.0, volume: 1.0 }
  no:       { id: ENTITY_VILLAGER_NO, pitch: 1.0, volume: 1.0 }

message-complete: { enable: true, message: '&aQuest Completed: &e{quest}' }
title-complete:   { enable: true, title: '%quest%', subtitle: '&fQuest Completed!', fadein: 10, stay: 40 }

quests-automatic-layout: true
quests-slots: [2, 3, 4, 5, 6, 7, 8, 11, 12, 13, 14, 15, 16, 17, ...]

Fields

Field	Required	Description
gui-name	Yes	GUI title (supports & colors and <#HEX> hex colors)
gui-rows	Yes	GUI height in rows (1–6)
sound	No	Sounds for click/complete/claim/no actions
message-complete	No	Chat message sent on quest completion
title-complete	No	Title/subtitle shown on quest completion
quests-automatic-layout	No	true = auto-arrange quests, false = manual slot/page (default: true)
quests-slots	Only if automatic	Slots available for auto-arrangement
item-page	No	Next/previous page navigation buttons
quests-item	Yes	How quests appear at each stage
item-custom	No	Decorative/navigation items at specific slots

Sounds

Each sound has three properties:

• id — Minecraft namespaced sound ID
• pitch — Sound pitch (0.5–2.0)
• volume — Sound volume

Sound Event	When It Plays
click	Clicking a quest or GUI element
complete	Completing all objectives in a quest
claim	Claiming a quest reward
no	When an action is denied (locked quest, etc.)

Completion Messages & Titles

message-complete:
  enable: true
  message: '&aQuest Completed: &e{quest}'

title-complete:
  enable: true
  title: '%quest%'
  subtitle: '&fQuest Completed!'
  fadein: 10    # Ticks to fade in
  stay: 40      # Ticks to stay visible
  fadeout: 10   # Ticks to fade out

• {quest} is replaced with the quest's display name
• %quest% is replaced with the quest ID (useful for title animations)

Quest Layout

Automatic Layout

When quests-automatic-layout: true, quests are placed in the order they appear in quest files into the slots listed in quests-slots. This is the easiest way to set up your GUI.

Manual Layout

When quests-automatic-layout: false, each quest must specify slot and page in its configuration:

MY_QUEST:
  category: overworld
  slot: 23     # GUI slot (0-53)
  page: 1       # GUI page number
  # ...

Quest Item Display

The quests-item section defines how quests look at each progress stage:

quests-item:
  ongoing:
    name: '&f<display>'
    lore:
      - ''
      - '<desc>'
      - ''
      - '&6Objective:'
      - '<objective>'
      - ''
      - '&6Reward:'
      - '<reward>'
      - ''
      - '&e➥ Click to show objective'
  complete:
    item: CHEST_MINECART   # Optional: override quest icon item
    name: '&f<display>'
    lore: [ ... ]
  claimed:
    item: MINECART
    name: '&f<display>'
    lore: [ ... ]
  locked:
    item: BARRIER
    name: '&f<display>'
    lore:
      - ''
      - '<desc>'
      - ''
      - '<requirements>'
      - ''
      - '&4&lLOCKED'
  objective-ongoing: '&8- &f<objective-display> &7(<objective-value>/<objective-max-value>) &4❌'
  objective-complete: '&8- &f<objective-display> &7(<objective-value>/<objective-max-value>) &2✔'

Quest Item Placeholders

Placeholder	Description
<display>	Quest display name
<desc>	Quest description lines
<objective>	All objectives formatted with objective-ongoing/objective-complete
<objective-display>	Individual objective display name
<objective-value>	Player's current progress for an objective
<objective-max-value>	Maximum progress needed for an objective
<reward>	Reward display text
<requirements>	Requirement display text (shown when locked)

Custom Items

Decorative or navigation items placed at fixed positions in the GUI:

item-custom:
  pane1:
    slots: [1, 10, 19, 28, 37, 46]
    item: BLACK_STAINED_GLASS_PANE
    enchanted: false
    skullvalue: ''
    modeldata: 0
    amount: 1
    name: ' '
    lore: []
    commands: []

  overworld_nav:
    slot: 9
    item: GRASS_BLOCK
    enchanted: false
    name: '<#89E7CC>Overworld'
    lore:
      - '&7Click to open Overworld quests'
      - ''
      - '&f➥ Click'
    commands:
      - '[console] spcontentquests open overworld %player%'

Command Prefixes for Custom Items

Prefix	Description
[console] <cmd>	Runs as console
[player] <cmd>	Runs as the player
[close]	Closes the GUI
%player%	Replaced with the player's name