Overview

SagaDungeons is a feature-rich Minecraft dungeon plugin for Paper 1.20.1 (Java 17), designed to allow server administrators and players to create, manage, and run instanced dungeon worlds. Create temporary, template-based副本 (dungeons) with integrated economy (Vault & PlayerPoints), custom mobs (MythicMobs), and dynamic placeholders (PlaceholderAPI).

Whether you want players to create their own private lairs or offer pre-defined server challenges, SagaDungeons provides the framework for epic adventures!



✨ Core Features

• ️ Dynamic World Management
  
  • Template System: Import and manage world templates from `plugins/SagaDungeons/templates/`.
    
  • Asynchronous World Copying: Uses Paper API for efficient, non-blocking world duplication.
    
  • Unique Naming Convention: Dungeons are named e.g., `sd_001-EvilLair` for easy identification.
    
  • Lifecycle Management: Create → Run → Timeout/Complete → Unload → Delete.
    
  • Startup Cleanup: Automatically cleans any orphaned dungeon worlds on server start.
    
  
  
• ️ Dungeon Instance Control
  
  • Instance Management: Track active dungeons, owners, allowed players, and state.
    
  • Configurable Timeouts: Set time limits for dungeons with warnings.
    
  • Safe Player Teleportation: Securely teleport players in and out of dungeons.
    
  • Public/Private Dungeons: Owners can control who can join their instance.
    
  • Invite System: Players can invite others to their private dungeons.
    
  
  
• ⚖️ Permissions & Conditions
  
  • Creation Requirements: Define costs for creating dungeons (Vault currency, PlayerPoints, Items, Player Level).
    
  • Cooldown System: Per-player and global cooldowns for dungeon creation. Cooldowns are reset on server restart.
    
  • Flexible Conditions: Enable/disable specific requirement types per template.
    
  
  
• MythicMobs Integration
  
  • Dynamic Spawner Management: Create, edit, and remove MythicMobs spawners within dungeons.
    
  • In-Game Editor Commands: `/sd setspawn <mobType> [groupName]` & `/sd removespawn <radius>`.
    
  • Spawner Persistence: Spawners can be pre-configured in templates or managed dynamically.
    
  • One-Time Spawners: Set spawners to activate only once by omitting cooldown time (defaults to a very long cooldown).
    
  
  
• PlaceholderAPI Support
  
  • Custom Placeholders: `%sd_world_name%`, `%sd_owner%`, `%sd_time_left%`, `%sd_player_count%`, and more.
    
  • Register your expansion with `/papi ecloud download SagaDungeons` and `/papi reload`.
    
  
  
• Commands & GUI
  
  • Intuitive Commands: Easy-to-use player and admin commands (see below).
    
  • Interactive GUIs:
    
    • Template Selection
      
    • Dungeon Management
      
    • Player Invitation
      
    • (Planned: Mob Editing GUI)
      
  
  
• Rewards & Completion
  
  • Customizable Completion Conditions: (e.g., kill all mobs, kill specific mob, reach area).
    
  • Versatile Reward System: (e.g., Vault currency, PlayerPoints, items, experience, commands).
    
  
  
• ☠️ Death Management
  
  • Death Limits: Configure maximum deaths before a player is ejected.
    
  • Custom Revival Items: Allow players to use specific items to revive.
    
  • Configurable Respawn Points.
    
  
  
• Item Serialization
  
  • Full ItemStack serialization/deserialization for item conditions, rewards, and revival items.
    

Dependencies

• Paper 1.20.1+ (Compiled with Java 17)
• Vault (Required for economy features)
• PlayerPoints (Required for PlayerPoints features)
• MythicMobs (Required for custom mob spawning)
• PlaceholderAPI (Required for placeholder support)

⌨️ Commands
Main alias: `/sd`




Permissions

• `sagadungeons.user` - Basic access to player commands.
• `sagadungeons.create.<templateName>` - Allows creating a dungeon from a specific template.
• `sagadungeons.create.all` - Allows creating dungeons from any template.
• `sagadungeons.join` - Allows joining dungeons.
• `sagadungeons.admin` - Grants access to all admin commands and features.
• `sagadungeons.command.setspawn` - Permission to use the setspawn command.
• `sagadungeons.command.removespawn` - Permission to use the removespawn command.

(More specific permissions may be available for granular control)

Placeholders (PlaceholderAPI)

• `%sd_world_name%` - Display name of the player's current dungeon.
• `%sd_owner%` - Owner of the player's current dungeon.
• `%sd_time_left%` - Time remaining in the player's current dungeon.
• `%sd_player_count%` - Number of players in the player's current dungeon.
• *... and more! Check `messages.yml` or use PAPI expansion features for a full list.*

⚙️ Configuration
SagaDungeons offers extensive configuration options:

• `config.yml`: Main plugin settings, debug mode, default behaviors.
• `messages.yml`: All user-facing messages, fully translatable with color & PAPI support.
• `debugmessage.yml`: Messages for debug output.
• `templates.yml`: (Potentially for global template settings, or templates are folder-based)
• `player_cooldowns.yml`: Stores player cooldowns (cleared on restart).
• `plugins/SagaDungeons/templates/[templateName]/config.yml`: Specific configuration for each dungeon template.
  
  • `displayName`: Custom name like "&6Evil Dragon's Lair".
    
  • `defaultTimeout`: Duration in seconds.
    
  • `worldPath`: Path to the world files for this template (including region folder).
    
  • `creationConditions`:
    
    • `money`: { enabled: true, amount: 1000 }
      
    • `playerpoints`: { enabled: true, amount: 100 }
      
    • `items`: { enabled: true, items: [serialized_item_1, ...] }
      
    • `level`: { enabled: true, level: 10 }
      
  • `mythicMobsSpawners`: Pre-defined MythicMobs spawners for the template.
    
  • `completionConditions`: Define how the dungeon is cleared.
    
  • `rewards`: Define rewards upon completion.
    
  • `deathSettings`: Death limits, revival items, etc.
    

Note: All user messages are in `messages.yml` for easy translation. Debug messages are in `debugmessage.yml` and controlled by `debug: true/false` in `config.yml`.


Installation

1. Ensure you have a Paper 1.20.1+ server running Java 17.
2. Install all required dependencies: Vault, PlayerPoints, MythicMobs, PlaceholderAPI.
3. Download the latest `SagaDungeons.jar` file.
4. Place `SagaDungeons.jar` into your server's `plugins` folder.
5. Restart your server.
6. Configure the plugin via files in `plugins/SagaDungeons/`.
7. Set up your dungeon templates in `plugins/SagaDungeons/templates/`.

Future Plans

• Dungeon Leaderboard System
• Multi-Stage Dungeons
• Adjustable Dungeon Difficulty
• Custom Dungeon Event Triggers
• Advanced Dungeon Statistics & Achievements
• Timed Challenge Modes
• GUI for Mob Spawner Editing