Quest System - Ubivis/UbiDungeon GitHub Wiki

Quest System

Overview

The Quest System adds RPG-like progression elements to the AI Dungeon Generator plugin. Players are assigned themed quests when entering dungeons, providing goals, direction, and rewards for dungeon exploration.

Quest Types

The plugin supports three quest types, each offering different gameplay experiences:

Kill Quests

Players must defeat a specific number of enemies or a dungeon boss.

Example:

  • Boss Slayer: Defeat the dungeon boss
  • Monster Hunter: Defeat 15 zombies in the dungeon

Kill quests encourage combat and are generally the most straightforward. Boss kill quests are particularly challenging and rewarding.

Collection Quests

Players must find and collect specific items placed throughout the dungeon.

Example:

  • Treasure Hunter: Collect 3 lost artifacts (emeralds)
  • Arcane Collector: Gather 5 magical essence crystals (amethyst shards)

Collection quests encourage thorough exploration of the dungeon, as quest items are placed in chests and hidden areas.

Exploration Quests

Players must discover specific marked locations within the dungeon.

Example:

  • Dungeon Explorer: Discover 2 hidden treasure chambers
  • Cartographer: Map out 3 secret areas of the dungeon

Exploration quests have special markers (signs or glowing blocks) that players must find and interact with.

Quest Mechanics

Quest Assignment

Quests are automatically assigned when a player enters a dungeon:

  1. The system checks if the player already has a quest for this dungeon
  2. If not, it selects an appropriate quest based on the dungeon's biome and theme
  3. The quest is assigned to the player with a notification
  4. Quest-related items and markers are spawned in the dungeon

Players can have multiple quests from different dungeons simultaneously, up to a configurable maximum (default: 5).

Quest Progress

Progress is tracked automatically as players complete objectives:

  • Kill quests update when matching monsters are defeated
  • Collection quests update when quest items are used (right-clicked)
  • Exploration quests update when markers are discovered

Progress is saved between sessions and persists even if the player leaves the dungeon.

Quest Completion

When all objectives are completed:

  1. The player receives a completion notification
  2. The quest is marked as completed
  3. Rewards become available to claim

Quest Rewards

Rewards can include:

  • Items (configurable in the quest template)
  • Experience points
  • Custom command execution
  • Custom messages

Rewards are claimed using the /quests claim <id> command.

Commands

The quest system provides several commands for managing quests:

  • /quests or /quest - Shows your active quests
  • /quests list - Alternative command to list quests
  • /quests claim <id> - Claim rewards for a completed quest
  • /quests abandon <id> - Abandon a quest (progress will be lost)
  • /quests reload - Reload the quest system (admin only)

Configuration

Main Quest Settings

quests:
  enabled: true
  max_quests_per_player: 5
  show_claimed: false
  • enabled - Turn the entire quest system on/off
  • max_quests_per_player - Maximum number of quests a player can have simultaneously
  • show_claimed - Whether to show claimed quests in the list command

Quest Templates

templates:
  boss_slayer:
    name: Boss Slayer
    description: Defeat the dungeon boss to claim your reward
    type: KILL
    required_amount: 1
    target_entity: BOSS
    reward_commands:
      - give %player% diamond 5
      - xp add %player% 500
    reward_messages:
      - You have defeated the dungeon boss!
      - The cursed spirits can now rest.
    reward_items:
      - DIAMOND:5
      - EXPERIENCE_BOTTLE:10

Each template defines:

  • name - Display name of the quest
  • description - Description shown to players
  • type - Quest type (KILL, COLLECT, EXPLORE)
  • required_amount - Number of objectives to complete
  • target_entity - For KILL quests, the entity type to kill (or "BOSS" for boss mobs)
  • target_item - For COLLECT quests, the item type to collect
  • reward_commands - Commands to execute upon claiming rewards
  • reward_messages - Messages to show when claiming rewards
  • reward_items - Items to give as rewards (format: MATERIAL:amount)

Biome-Specific Quests

biome_quests:
  DESERT:
    - boss_slayer
    - treasure_hunter
  FOREST:
    - monster_hunter
    - dungeon_explorer
  default:
    - monster_hunter
    - boss_slayer

This section determines which quests can be assigned in which biomes. The default entry is used for biomes not explicitly listed.

Technical Implementation

Core Classes

  • QuestSystem: Main handler class that manages quests
  • Quest: Represents an individual quest assigned to a player
  • QuestTemplate: Blueprint for creating quests
  • QuestType: Enum defining the types of quests
  • QuestCommand: Handles the quest commands

Data Storage

Quest data is stored in the plugin's configuration file under the quests.player_quests section, with the following structure:

quests:
  player_quests:
    player-uuid:
      quest-id:
        template_id: boss_slayer
        dungeon_id: world:123:456
        progress: 1
        completed: true
        reward_claimed: false

This allows quest progress to persist between server restarts.

Integration Points

The quest system integrates with other plugin systems through:

  1. Player Movement: Detects dungeon entry to assign quests
  2. Combat System: Tracks monster kills for kill quests
  3. Interaction System: Detects item usage and marker discovery
  4. Dungeon Generation: Spawns quest items and markers in dungeons

Examples

Example Kill Quest

templates:
  zombie_hunter:
    name: Zombie Hunter
    description: Cleanse the dungeon of the undead menace
    type: KILL
    required_amount: 10
    target_entity: ZOMBIE
    reward_commands:
      - give %player% gold_ingot 5
      - xp add %player% 200
    reward_messages:
      - You've purged the undead from this dungeon!
    reward_items:
      - GOLDEN_APPLE:1

Example Collection Quest

templates:
  lost_jewelry:
    name: Lost Jewelry
    description: Find the royal jewels scattered throughout the dungeon
    type: COLLECT
    required_amount: 4
    target_item: EMERALD
    reward_commands:
      - give %player% diamond 3
      - xp add %player% 250
    reward_messages:
      - You've recovered the royal jewels!
      - The kingdom will reward your service.
    reward_items:
      - GOLDEN_HELMET:1
      - DIAMOND:3

Example Exploration Quest

templates:
  ancient_knowledge:
    name: Ancient Knowledge
    description: Discover the forgotten knowledge chambers
    type: EXPLORE
    required_amount: 3
    reward_commands:
      - give %player% experience_bottle 10
      - xp add %player% 300
    reward_messages:
      - You've uncovered the ancient knowledge!
      - Your wisdom has increased.
    reward_items:
      - BOOK:5
      - ENCHANTED_BOOK:1

Extending the Quest System

Developers can extend the quest system by:

  1. Adding New Quest Types: Create a new QuestType enum value and implement handlers
  2. Creating Custom Rewards: Extend the reward system with new types of rewards
  3. Adding Theme-Specific Quests: Create quests that tie into specific dungeon themes

See the Developer API documentation for more information on extending the plugin.