GroupeZ Docs
Configurations

Quest Configuration

Learn how to configure quests in zQuests

This page explains how to configure quests in zQuests. Each quest is defined using YAML configuration with various options to customize behavior, objectives, and rewards.

Basic Structure

Quests are defined in YAML files located in the plugins/zQuests/quests/ folder. You can organize quests into multiple files for better management.

quests:
  - type: BLOCK_BREAK
    name: "stone-breaker-1"
    display-name: "Stone Breaker"
    description: "Break 500 stone blocks"
    thumbnail: STONE
    goal: 500
    auto-accept: true
    actions:
      - material: STONE
      - material: COBBLESTONE
    rewards:
      - type: message
        messages:
          - "&aYou completed the Stone Breaker quest!"
      - type: console_command
        commands:
          - "give %player% diamond 5"

Configuration Options

type

Specifies the type of quest. This determines how progress is tracked.

  • Required: Yes
  • Default: None
type: BLOCK_BREAK

See Quest Types for all available types.

name

A unique identifier for the quest. This value is used internally to track player progress and must never change once players have started the quest.

  • Required: Yes
  • Default: None
name: "stone-breaker-1"

Important

The quest name must be unique across all quest files. Changing this value after players have started the quest will reset their progress!

display-name

The name shown to players in inventories and messages. Supports color codes and placeholders.

  • Required: No
  • Default: Uses name value
display-name: "&6Stone Breaker"

description

A description of the quest shown to players. Supports color codes.

  • Required: No
  • Default: "no description"
description: "Break 500 stone blocks to complete this quest"

placeholder-description

An alternative description that supports dynamic placeholders. Useful for showing remaining progress.

  • Required: No
  • Default: Uses description
placeholder-description: "Break %quest-remaining% more stone blocks"

Available placeholders:

  • %quest-remaining% - Remaining amount to complete
  • %quest-progress% - Current progress
  • %quest-goal% - Quest goal

thumbnail

The material used as the quest icon in inventories.

  • Required: No
  • Default: None
thumbnail: DIAMOND_PICKAXE

Uses Bukkit Material names.

goal

The target amount to complete the quest.

  • Required: Yes
  • Default: 1
goal: 500

auto-accept

Whether the quest automatically starts when available to the player.

  • Required: No
  • Default: false
auto-accept: true

use-global-rewards

Whether to include global rewards when the quest is completed.

  • Required: No
  • Default: true
use-global-rewards: true

Set to false if you only want the quest-specific rewards to be given.

favorite

Whether the quest is marked as favorite when started.

  • Required: No
  • Default: false
favorite: true

can-change-favorite

Whether players can toggle the favorite status of this quest.

  • Required: No
  • Default: true
can-change-favorite: true

unique

When enabled, progress on this quest prevents progress on other quests of the same type. Useful for story quests where only one quest should advance at a time.

  • Required: No
  • Default: false
unique: true

hidden

Whether the quest is hidden from the ZQUESTS_HISTORY button.

  • Required: No
  • Default: false
hidden: true

custom-model-id

Custom model ID for resource pack integration, available via the %quest-model-id% placeholder.

  • Required: No
  • Default: 0
custom-model-id: 1001

actions

Defines what counts toward quest progress. The format depends on the quest type.

  • Required: Depends on quest type
  • Default: Empty list
# For BLOCK_BREAK quests
actions:
  - material: STONE
  - material: COBBLESTONE
  - tag: LOGS  # Bukkit tags

# For ENTITY_KILL quests
actions:
  - entity: ZOMBIE
  - entity: SKELETON

rewards

Actions executed when the quest is completed. Supports all zMenu actions.

  • Required: No
  • Default: Empty list
rewards:
  - type: message
    messages:
      - "&aQuest completed!"
  - type: console_command
    commands:
      - "give %player% diamond 10"
  - type: sound
    sound: ENTITY_PLAYER_LEVELUP

See zMenu Actions for all available action types.

start-actions

Actions executed when the quest starts.

  • Required: No
  • Default: Empty list
start-actions:
  - type: message
    messages:
      - "&eQuest started! Good luck!"
  - type: sound
    sound: ENTITY_EXPERIENCE_ORB_PICKUP

permissible-rewards

Bonus rewards given only if the player meets certain requirements.

  • Required: No
  • Default: Empty list
permissible-rewards:
  - requirements:
      - type: permission
        permission: quests.vip
    actions:
      - type: message
        messages:
          - "&6VIP Bonus: Extra rewards!"
      - type: console_command
        commands:
          - "give %player% diamond 5"

action-requirements

Requirements that must be met for quest progress to count. If the player doesn't meet these requirements, their actions won't advance the quest.

  • Required: No
  • Default: Empty list
action-requirements:
  - type: permission
    permission: quests.can-progress
  - type: world
    world: survival

hologram

Display a hologram when the quest is active. Can reference a global hologram by name or define inline.

  • Required: No
  • Default: None

Reference global hologram:

hologram: MY_HOLOGRAM

Inline definition:

hologram:
  location: "world,100,65,200"
  texts:
    - "&aQuest location here!"
    - "&7Follow the path..."

See Waypoints & Holograms for full configuration.

waypoint

Display a waypoint guiding the player to a location. Can reference a global waypoint or define inline.

  • Required: No
  • Default: None

Reference global waypoint:

waypoint: QUEST_LOCATION

Inline definition:

waypoint:
  location: "world,100,65,200"
  texture: quest_marker
  color: gold

See Waypoints & Holograms for full configuration.

Complete Example

Here's a complete quest configuration showing most options:

quests:
  - type: BLOCK_BREAK
    name: "mining-master"
    display-name: "&6Mining Master"
    description: "Break 1000 ore blocks"
    placeholder-description: "Break %quest-remaining% more ore blocks"
    thumbnail: DIAMOND_ORE
    goal: 1000
    auto-accept: false
    use-global-rewards: true
    favorite: false
    can-change-favorite: true
    unique: false
    hidden: false
    custom-model-id: 0
    actions:
      - material: COAL_ORE
      - material: IRON_ORE
      - material: GOLD_ORE
      - material: DIAMOND_ORE
      - material: EMERALD_ORE
      - material: LAPIS_ORE
      - material: REDSTONE_ORE
      - material: COPPER_ORE
      - material: DEEPSLATE_COAL_ORE
      - material: DEEPSLATE_IRON_ORE
      - material: DEEPSLATE_GOLD_ORE
      - material: DEEPSLATE_DIAMOND_ORE
      - material: DEEPSLATE_EMERALD_ORE
      - material: DEEPSLATE_LAPIS_ORE
      - material: DEEPSLATE_REDSTONE_ORE
      - material: DEEPSLATE_COPPER_ORE
    action-requirements:
      - type: world
        world: survival
    start-actions:
      - type: message
        messages:
          - "&eYou started the Mining Master quest!"
          - "&7Break 1000 ore blocks to complete it."
    rewards:
      - type: message
        messages:
          - "&a&lQuest Completed!"
          - "&7You are now a Mining Master!"
      - type: console_command
        commands:
          - "give %player% diamond 64"
          - "eco give %player% 10000"
      - type: sound
        sound: UI_TOAST_CHALLENGE_COMPLETE
    permissible-rewards:
      - requirements:
          - type: permission
            permission: rank.vip
        actions:
          - type: message
            messages:
              - "&6&lVIP BONUS: +32 diamonds!"
          - type: console_command
            commands:
              - "give %player% diamond 32"
    hologram: MINING_AREA
    waypoint: MINING_AREA

File Organization

You can organize quests into multiple files:

plugins/zQuests/quests/
├── beginner/
│   ├── tutorial.yml
│   └── starter-quests.yml
├── daily/
│   ├── mining.yml
│   └── farming.yml
├── story/
│   └── main-storyline.yml
└── events/
    └── halloween.yml

Each file should contain a quests list:

# quests/beginner/tutorial.yml
quests:
  - type: BLOCK_BREAK
    name: "tutorial-1"
    # ... quest config

  - type: CRAFT
    name: "tutorial-2"
    # ... quest config

Next Steps

Installation

How to download, install, and configure zQuests on your Minecraft server

Quest Types

All available quest types in zQuests

On this page

Basic StructureConfiguration Optionstypenamedisplay-namedescriptionplaceholder-descriptionthumbnailgoalauto-acceptuse-global-rewardsfavoritecan-change-favoriteuniquehiddencustom-model-idactionsrewardsstart-actionspermissible-rewardsaction-requirementshologramwaypointComplete ExampleFile OrganizationNext Steps
GroupeZ MCP

Documentation in your AI

MCP lets your AI search GroupeZ documentation and read current examples to help you configure your plugins.

Read-only · No documentation API key needed

1. Copy the server URL

Transport: HTTP (Streamable HTTP). Authentication: none. Your tool uses its own model and subscription limits.

  1. Open Plugins in ChatGPT on the web, then + → Add custom MCP server.
  2. Name it ‘GroupeZ Documentation’, paste the URL above and choose ‘No authentication’. Create and install the plugin.
  3. In a conversation, type @ and select the plugin before asking. If needed, enable search, get_page and list_pages in its settings.
Official setup guide

3. Ask a question

Use GroupeZ MCP to help me create a zMenu inventory. Search relevant pages, read the examples and cite your sources.
Other clients and troubleshooting

For clients using mcpServers, adapt this example to their format:

{
  "mcpServers": {
    "groupez-docs": {
      "url": ""
    }
  }
}

Available tools are search, get_page and list_pages. Refresh the connector’s tools after updates. If your AI cannot access them, check that the connector is enabled in the conversation and your account allows custom MCP servers. Opening the URL in a browser is not an MCP test.