SkyeBlock Plugin

A comprehensive SkyeBlock plugin for Paper/Spigot servers that allows players to create and manage their own skyblock islands with advanced features and a flexible dual command system.

Features

Core Functionality

🎯 Dual Command System: Use both direct commands (/island, /visit) and unified sub-commands (/sb island, /sb visit) - NEW!
🏝️ Multiple Island Types: Choose from Classic, Desert, or Nether-themed islands with clean single-word identifiers
📋 Custom Schematic System: YAML-based island templates with detailed block placement and chest contents
🌍 Individual Island Worlds: Each island gets its own dedicated world (with SlimeWorldManager support)
⚙️ Island Settings Management: Full gamerule control system with interactive GUI interface
🔐 Advanced Permissions: LuckPerms-style permission system for granular gamerule control
🏠 Hub Integration: Seamless teleportation between hub and islands
👥 Visitor System: Visit other players' islands with protection and settings
🤝 Cooperative Play: Island cooperation system with member management

Island Types Available

🌿 Classic SkyBlock (classic) - Traditional dirt platform with tree, chest, and basic supplies
🏜️ Desert Island (desert) - Sand-based island with cactus and desert survival items
🔥 Nether Island (nether) - Challenging netherrack island with nether-themed resources

Advanced Features

⚡ Dual Command Interface: Choose between direct commands (/island) or unified sub-commands (/sb island) with full backward compatibility
🚀 Smart World Management: SlimeWorldManager integration with fallback to standard Bukkit worlds
🎮 Island Settings GUI: Interactive interface for managing 31 different gamerules
🔑 Granular Permissions: Individual permissions for each gamerule with admin bypass system
🎯 Single-Word Island Types: Clean, simple island type identifiers (classic, desert, nether)
📝 Smart Tab Completion: Intelligent command completion for all commands and island types
🛠️ Comprehensive Admin Tools: Island listing, deletion, status monitoring, and management
🌐 Safe Teleportation: Proper spawn point calculation and world-specific teleportation
🎨 MiniMessage Support: Modern text formatting with Adventure API integration
💾 Optimized Storage: SlimeWorld integration for reduced disk usage and better performance

Commands

🎯 Dual Command System (NEW!)

The plugin supports both direct commands and unified sub-commands for maximum flexibility:

Direct Commands (Original)

/island create <type>        # Create a new island (classic, desert, nether)
/island home                 # Teleport to your island
/island settings             # Open island settings GUI
/island types                # Show available island types
/island delete               # Delete your island with confirmation
/island list                 # List all islands (admin only)
/island status               # Show server status (admin only)

/visit <player>              # Visit another player's island
/delete [player]             # Delete island with two-step confirmation
/hub                         # Return to hub world
/is                          # Alias for /island

Sub-Commands (NEW!)

/sb island create <type>     # Create a new island (classic, desert, nether)
/sb island home              # Teleport to your island
/sb island settings          # Open island settings GUI
/sb island types             # Show available island types
/sb island delete            # Delete your island with confirmation
/sb island list              # List all islands (admin only)
/sb island status            # Show server status (admin only)

/sb visit <player>           # Visit another player's island
/sb delete [player]          # Delete island with two-step confirmation
/sb hub                      # Return to hub world
/skyblock                    # Alias for /sb

Help & Information

/sb                          # Show all available sub-commands with descriptions
/island help                 # Show island command help

🔑 Permission-Based Commands

Commands are filtered based on permissions:

Basic Users: create, home, settings, types, delete (own island)
Admins: All commands including list, status, and delete others' islands

Installation & Setup

1. Prerequisites

Paper/Spigot server (1.20+)
Optional: SlimeWorldManager (ASWM/SWM) for optimized world management
Optional: LuckPerms for advanced gamerule permissions

2. Quick Installation

# Clone or download the plugin
git clone <repository-url>
cd SkyeBlock

# Build the plugin
./build.sh

# Copy to your server
cp target/skyeblock-1.0.0.jar /path/to/your/server/plugins/

# Restart your server

3. Optional Enhancements

Install SlimeWorldManager for individual island worlds (highly recommended)
Install LuckPerms for granular gamerule permission control
Both plugins provide automatic fallback if not available

4. Quick Test & Validation

# Test the installation
./test-setup.sh

# Validate dual command system
./validate-dual-commands.sh

# Test all functionality
./test-functionality.sh

5. Ready to Use!

Plugin auto-creates necessary configurations
Includes built-in island templates
Works out-of-the-box with smart defaults

Configuration

The plugin creates a config.yml file with the following settings:

# World settings
world:
  name: "skyblock_world"
  environment: "NORMAL"

# Hub settings (optional)
hub:
  enabled: true
  world: "world"
  spawn:
    x: 0
    y: 100
    z: 0

# Island settings  
island:
  distance: 1000             # Distance between islands (for fallback shared world)
  start-x: 0                # Starting X coordinate
  start-z: 0                # Starting Z coordinate

# Messages (fully customizable)
messages:
  prefix: "&8[&6SkyeBlock&8] &r"
  island-created: "&aIsland created successfully! Teleporting you there..."
  island-already-exists: "&cYou already have an island!"
  island-not-found: "&cYou don't have an island yet!"
  island-deleted: "&aYour island has been deleted!"
  teleported: "&aTeleported to your island!"
  no-permission: "&cYou don't have permission to use this command!"
  invalid-command: "&cInvalid command! Use /island help for available commands."
  # ... additional customizable messages

Island Settings System

Gamerule Management

The plugin features a comprehensive gamerule management system accessible via /island settings:

Available Gamerules

Survival & Damage Control:

Keep Inventory, Fall Damage, Fire Damage, Drowning Damage
Natural Regeneration, Immediate Respawn

World Mechanics:

Day/Light Cycle, Weather Cycle, Fire Spread
Mob Spawning, Mob Griefing, Insomnia (Phantoms)

Game Features:

Announce Advancements, Show Death Messages
Entity/Tile Drops, Mob Loot, Limited Crafting

Technical Settings:

Random Tick Speed, Spawn Radius
Max Entity Cramming, Command Chain Length
Players Sleeping Percentage

GUI Interface

Interactive Menus: Click-based interface for easy gamerule management
Visual Indicators: Clear on/off states for boolean gamerules
Value Input: Chat-based input for integer gamerules
Permission Awareness: Only shows gamerules the player has permission to modify
Real-time Application: Changes apply immediately to the island world

Permission System

Default Access: All gamerules visible to island owners by default
LuckPerms Integration: Use LuckPerms to hide specific gamerules
Admin Bypass: Staff can access all gamerules regardless of restrictions
Granular Control: Individual permissions for each of the 31 supported gamerules

Custom Island Templates

The plugin includes a sophisticated YAML-based schematic system. Island templates are stored in src/main/resources/schematics/ and include:

Template Structure

name: "Island Name"
description: "Island description"
size:
  width: 9
  height: 5  
  length: 9
spawn_offset:
  x: 4
  y: 1
  z: 4
structure:
  - level: 0
    blocks:
      - "air air dirt dirt dirt air air air"
      # ... more block rows
chest_contents:
  - location: [4, 2, 3]
    items:
      - "ice:2"
      - "lava_bucket:1"

Creating Custom Templates

Create a new YAML file in the schematics format
Add it to src/main/resources/schematics/
Update CustomSchematicManager.java to load your new template
Rebuild the plugin

Messages (customizable)

messages: prefix: "&8[&6SkyeBlock&8] &r" island-created: "&aIsland created successfully! Teleporting you there..."

... more messages


## Creating Island Templates

1. Build your island template in a world
2. Select the area with WorldEdit wand (`//wand`)
3. Copy the selection (`//copy`)
4. Save as schematic (`//schem save island-normal`)
5. Move the schematic file to `plugins/SkyeBlock/schematics/`

## Permissions

### Basic Permissions
- `skyeblock.*` - All permissions (default: op)
- `skyeblock.island` - Basic island commands (default: true)
- `skyeblock.hub` - Hub teleport command (default: true)
- `skyeblock.admin` - Admin commands (default: op)

### Gamerule Permissions (LuckPerms Integration)
- `skyeblock.gamerules.adminbypass` - Bypass all gamerule restrictions (default: op)
- `skyeblock.gamerule.*` - All individual gamerule permissions (default: true)

### Individual Gamerule Controls
The plugin provides granular control over 31 different gamerules:

**Boolean Gamerules:**
- `skyeblock.gamerule.keepinventory` - Keep inventory on death
- `skyeblock.gamerule.mobgriefing` - Mob block destruction
- `skyeblock.gamerule.dodaylightcycle` - Day/night cycle
- `skyeblock.gamerule.doweathercycle` - Weather changes
- `skyeblock.gamerule.domobspawning` - Natural mob spawning
- `skyeblock.gamerule.dofiretick` - Fire spread
- `skyeblock.gamerule.falldamage` - Fall damage
- `skyeblock.gamerule.firedamage` - Fire damage
- `skyeblock.gamerule.drowningdamage` - Drowning damage
- And 16 more boolean gamerules...

**Integer Gamerules:**
- `skyeblock.gamerule.randomtickspeed` - Random tick speed
- `skyeblock.gamerule.spawnradius` - Spawn radius
- `skyeblock.gamerule.maxentitycramming` - Entity cramming limit
- `skyeblock.gamerule.maxcommandchainlength` - Command chain limit
- `skyeblock.gamerule.playerssleepingpercentage` - Sleep percentage

### LuckPerms Usage Examples
```bash
# Hide dangerous gamerules from default players
lp group default permission set skyeblock.gamerule.mobgriefing false
lp group default permission set skyeblock.gamerule.dofiretick false

# Allow VIP players access to restricted gamerules
lp group vip permission set skyeblock.gamerule.mobgriefing true

# Restrict technical gamerules to staff only
lp group default permission set skyeblock.gamerule.randomtickspeed false
lp group moderator permission set skyeblock.gamerule.randomtickspeed true

Note: All gamerules are visible by default. Set permissions to false to hide specific gamerules from players.

Technical Details

World Management

SlimeWorldManager Integration: Automatic detection and use of SWM/ASWM for optimized world handling
Individual Island Worlds: Each island gets its own world when SlimeWorldManager is available
Fallback Support: Graceful fallback to standard Bukkit worlds if SlimeWorldManager is not installed
World Cleanup: Proper world deletion and resource cleanup on island deletion

Island Management

Island Format: island-<type>-<player-uuid> for unique identification
Safe Teleportation: Smart spawn point calculation with template-based positioning
Schematic Support: Built-in YAML-based schematic system with chest population
Settings Persistence: Individual gamerule settings saved per island

GUI System

Interactive Settings: Full GUI interface for gamerule management
Permission Integration: Dynamic gamerule visibility based on LuckPerms permissions
Real-time Updates: Live updates when gamerule values are changed
Admin Bypass: Staff can see all gamerules regardless of individual restrictions

Performance Features

Optimized World Loading: Efficient world creation and management
Memory Management: Proper cleanup and resource management
Compressed Storage: SlimeWorld integration for reduced disk usage
Async Operations: Non-blocking world operations where possible

Usage Examples

🎯 Dual Command System Usage

Both command styles work identically - choose what feels natural!

# Creating Islands - Both methods work:
/island create classic       ↔️    /sb island create classic
/island create desert        ↔️    /sb island create desert  
/island create nether        ↔️    /sb island create nether

# Navigation - Both methods work:
/island home                 ↔️    /sb island home
/visit PlayerName            ↔️    /sb visit PlayerName
/hub                         ↔️    /sb hub

# Management - Both methods work:
/island settings             ↔️    /sb island settings
/island types                ↔️    /sb island types
/delete                      ↔️    /sb delete

# Using Aliases:
/is home                     ↔️    /skyblock island home

🏝️ Creating Islands

# Simple island creation
/island create classic
/island create desert
/island create nether

# Check available types first
/island types

⚙️ Managing Island Settings

# Open the interactive GUI
/island settings

# Players see gamerules based on their permissions
# Staff with adminbypass see all 31 gamerules

🛠️ Admin Management

# List all islands with details
/island list

# Check server and world manager status
/island status

# Delete any player's island (admin only)
/island delete PlayerName

🎮 Getting Help

# Show sub-command help
/sb

# Show island command help  
/island help

📚 Documentation

Core Guides

DUAL_COMMAND_SYSTEM.md - Complete guide to the new dual command system
LUCKPERMS_GAMERULE_PERMISSIONS.md - LuckPerms gamerule permission setup
ASWM_INTEGRATION_GUIDE.md - SlimeWorldManager integration details
ISLAND_SETTINGS_IMPLEMENTATION.md - Island settings and GUI system

Technical Documentation

GAMERULE_PERMISSIONS_UPDATE.md - Technical implementation details
DEPLOYMENT_GUIDE.md - Server deployment and debugging information
TESTING.md - Testing procedures and expected results
PROJECT_COMPLETE.md - Complete feature overview and status

Quick References

DEPLOYMENT_CHECKLIST.md - Pre-deployment validation checklist
COMMAND_TESTING.md - Command testing procedures
MINIMESSAGE_TESTING.md - Text formatting validation

🚀 Recent Updates

✨ Version 1.0.0 - Latest Release (May 2025)

🎯 NEW: Dual Command System

Direct Commands: /island, /visit, /delete, /hub (preserves existing usage)
Sub-Commands: /sb island, /sb visit, /sb delete, /sb hub (new unified interface)
Full Backward Compatibility: Existing users can continue using familiar commands
Smart Help System: /sb shows all available sub-commands with descriptions
Complete Tab Completion: Both command styles support intelligent tab completion

🏝️ Enhanced Island Management

Single-Word Island Types: Clean identifiers (classic, desert, nether)
Fixed Island Type Storage: Islands now store single-word types instead of display names
Improved Tab Completion: Smart completion for island types and commands
Two-Step Deletion: Enhanced confirmation system for island deletion

🔧 Core System Improvements

SlimeWorldManager Integration: Individual island worlds with automatic fallback
LuckPerms Permission System: Granular control over 31 island gamerules
Interactive Settings GUI: Real-time gamerule management with visual indicators
MiniMessage Support: Modern text formatting with Adventure API
Optimized Performance: Better world management and resource cleanup

🎮 Quality of Life Features

Admin Bypass System: Staff can access all gamerules regardless of restrictions
Dynamic Permission Filtering: GUI shows only accessible gamerules per player
Comprehensive Admin Tools: Enhanced monitoring and management capabilities
Safe World Operations: Proper cleanup and resource management
Hub System Integration: Configurable hub world with seamless teleportation

💡 Support & Contributing

Getting Help

Check the comprehensive documentation in the repository
Use the testing scripts to validate your setup
Review the configuration examples for common setups

Reporting Issues

Include server version and plugin configuration
Provide relevant console logs and error messages
Test with the included validation scripts

Development

Plugin follows modern Bukkit/Paper development practices
Uses Adventure API for text components and MiniMessage formatting
Includes comprehensive testing suite and validation tools
Supports both SlimeWorldManager and standard Bukkit worlds

Quality Assurance

✅ Full Test Coverage: Comprehensive testing scripts included
✅ Validation Tools: Multiple validation scripts for different components
✅ Backward Compatibility: Maintains compatibility with existing setups
✅ Performance Optimized: Efficient world management and resource usage

📄 License

SkyeBlock Plugin v1.0.0 - A comprehensive island management solution with dual command system, advanced permissions, and modern Minecraft server integration.