LilWorlds

️ CRITICAL BUG FIXES

Asynchronous Operations

• FIXED: Critical server errors and instability caused by performing Bukkit API calls (world loading, unloading, deletion) on asynchronous threads.
• FIXED: Potential server freezes when deleting worlds due to slow file operations blocking the main thread.
• IMPROVED: All world management operations are now fully thread-safe, preventing data corruption and unexpected crashes.

TECHNICAL IMPROVEMENTS

️ Architecture

• IMPROVED: Refactored WorldManager and LilWorldsAPI to correctly separate heavy, non-API tasks (like file deletion) from main-thread-only Bukkit calls.
• IMPROVED: The internal list of managed worlds now uses a ConcurrentHashMap to guarantee safe access from multiple threads.
• NEW: The deleteWorld process now returns a CompletableFuture, providing a more robust and modern asynchronous API for developers.

️ IMPLEMENTATION

⚙️ Correct Asynchronous Pattern

The API now safely handles threading, allowing developers to call asynchronous methods without worrying about server stability.

// Example: Asynchronously and safely deleting a world
lilWorldsAPI.deleteWorldAsync("world_to_delete").thenAccept(success -> {
    if (success) {
        player.sendMessage("World deleted successfully!");
    } else {
        player.sendMessage("Error: Could not delete the world.");
    }
});

COMPATIBILITY

️ Backward Support

• MAINTAINED: Fully backward compatible. No changes are required for existing code that uses the API.
• MAINTAINED: All command syntax and behavior remain identical for users.
• MAINTAINED: No configuration migrations are needed.

UPDATE SUMMARY

1. Fixed Critical Threading Issues: Resolved major stability problems by ensuring all Bukkit API calls run on the main server thread.
2. Eliminated Server Lag: Moved slow file deletion operations to a separate thread, preventing server freezes.
3. Enhanced Reliability: Made the plugin significantly more stable and safe for production environments.

🛠️ CRITICAL BUG FIXES

🚨 WorldEdit Compatibility

• FIXED: Startup crashes when WorldEdit missing (NoClassDefFoundError)
• FIXED: Portal system requiring WorldEdit for basic operation
• IMPROVED: Graceful fallback to manual coordinates

🌐 LOCALIZATION

📝 Portal Message System

• NEW: 50+ messages moved to messages.yml
• NEW: Consistent formatting and placeholders ({name}, {world})
• NEW: Multi-language support with easy customization

# Example Messages
portal-created-success: "&aPortal '{name}' created successfully!"
portal-worldedit-not-found: "&cWorldEdit required for visual selection"

🔧 TECHNICAL IMPROVEMENTS

🔄 Dependency Handling

• NEW: Reflection-based WorldEdit integration
• NEW: Runtime detection and feature toggling
• IMPROVED: Clean separation of optional/core features

🛡️ Architecture

• IMPROVED: Independent plugin initialization
• IMPROVED: Enhanced error handling with clear feedback
• IMPROVED: Better command system resilience

🎯 PORTAL ENHANCEMENTS

🌀 Creation Flexibility

• IMPROVED: Unified workflow (WorldEdit/manual modes)
• IMPROVED: Automatic detection of available features
• NEW: Clear guidance for both creation methods

🏗️ IMPLEMENTATION

⚙️ Reflection Example

// Safe dynamic WorldEdit loading
Class<?> worldEditClass = Class.forName("com.sk89q.worldedit.WorldEdit");

📦 Dependency Config

• MAINTAINED: WorldEdit as softdepend (plugin.yml)
• MAINTAINED: Full functionality without WorldEdit

🎯 USAGE EXAMPLES

Without WorldEdit:

/portal create myportal world_nether 10 64 10 15 70 15 0 64 0

With WorldEdit:

//wand
/portal create myportal world_nether

🔄 COMPATIBILITY

🛡️ Backward Support

• MAINTAINED: All existing functionality preserved
• MAINTAINED: Identical command syntax
• MAINTAINED: No config migrations needed

📋 HOTFIX SUMMARY

1. Fixed WorldEdit-related startup crashes
2. Implemented complete message localization

🚀 MAJOR NEW FEATURES

🌐 Complete Portal System

• NEW: Built-in portal system with WorldEdit integration (//wand support)
• NEW: Persistent storage in portals.yml and cooldown system
• NEW: Frame customization, API support, and portal management

🔧 WorldEdit Integration

• NEW: Visual boundary selection and automatic detection
• NEW: Fallback to manual coordinates when unavailable
• NEW: Enhanced UX with seamless plugin integration

📡 Portal Command System

• NEW: /portal create|delete|list|info|tp|reload - Full management suite
• NEW: Automatic destination handling and coordinate support

🔤 Intuitive Portal Creation

• NEW: Two-step workflow (select area → create portal)
• NEW: Smart validation and error prevention

🔧 Portal Features

🔄 Persistent Storage

• NEW: Auto-save to YAML with restart persistence
• NEW: Manual reload capability

🏗️ Advanced Portal Management

• NEW: Portal types (NETHER/END/CUSTOM) and frame materials
• NEW: Multi-world support with conflict prevention

🛡️ Security & Performance

• NEW: Granular permissions (lilworlds.portal.*)
• NEW: Cooldown system and world validation
• NEW: Efficient event handling with minimal impact

🎯 Developer API

• NEW: Full lifecycle methods (create/delete/teleport)
• NEW: Information retrieval and event integration

📚 Portal Documentation & Examples

📖 Complete User Guide

• NEW: Dedicated portals page with tutorials
• NEW: Permission examples and troubleshooting

🎯 Usage Examples

• NEW: WorldEdit/manual workflows + API samples
• NEW: Configuration structure documentation

🔧 Core Plugin Improvements

💬 Enhanced Command Structure

• IMPROVED: Tab completion and contextual feedback
• IMPROVED: WorldEdit status indicators

🛡️ Permission System

• NEW: Granular controls (create|delete|teleport|admin|bypass.cooldown)

📝 User Experience

• NEW: Real-time feedback and formatted info displays
• NEW: Command suggestions and error guidance

🔧 Technical Implementation

🏗️ Portal Architecture

src/main/java/org/hydr4/lilworlds/portals/
├── Portal.java                    # Core data structure
├── PortalManager.java             # Persistence layer
├── PortalListener.java            # Event handlers
└── PortalCommand.java             # WorldEdit integration

🔄 Event Integration

• NEW: Optimized PlayerMoveEvent/PlayerPortalEvent handling
• NEW: Custom WorldTeleportEvent triggering

📦 WorldEdit Compatibility

• NEW: Dynamic detection and selection API support
• NEW: Graceful fallback for all selection types

🔄 Backward Compatibility & Version Support

• NEW: Added Minecraft 1.21.6 support
• MAINTAINED: All existing functionality preserved
• MAINTAINED: Zero breaking changes to configurations
• MAINTAINED: Uncompromised performance standards

🌟 Portal System Highlights

• INTUITIVE: Visual two-step creation
• PERSISTENT: Restart-proof storage
• FLEXIBLE: WorldEdit + manual modes
• SECURE: Permissions + validation
• PERFORMANT: Low-impact detection
• EXTENSIBLE: Full API integration

🚀 MAJOR NEW FEATURES

🔧 Complete Developer API System

• NEW: Comprehensive API for developers with full world management capabilities
• NEW: LilWorldsAPI - Main API entry point with singleton pattern
• NEW: WorldBuilder - Fluent builder pattern for intuitive world creation
• NEW: WorldManager - Advanced world management operations with async support
• NEW: WorldInfo - Comprehensive world information wrapper
• NEW: WorldUtils - Utility functions for common world operations

📡 Event System

• NEW: Custom event system for world operations (all cancellable)
• NEW: WorldCreateEvent - Fired before world creation
• NEW: WorldCreatedEvent - Fired after successful world creation
• NEW: WorldDeleteEvent - Fired before world deletion
• NEW: WorldTeleportEvent - Fired before player teleportation

⚡ Teleport Command

• NEW: /world teleport <world> command (alias: /w tp <world>)
• NEW: Teleports players to spawn location of specified world
• NEW: Security validation and rate limiting
• NEW: Permission checking (lilworlds.world.teleport)
• NEW: Player-only command with appropriate error messages

🔤 Short Command Aliases

• NEW: /w i (info), /w cr (create), /w cl (clone)
• NEW: /w ld (load), /w ul (unload), /w rm (remove)
• NEW: /w imp (import), /w ls (list), /w ss (setspawn)
• NEW: /w sus (setuniversalspawn), /w cfg (config), /w tp (teleport)

🔧 API Features

🔄 Async Operations

• NEW: All I/O operations return CompletableFuture
• NEW: Non-blocking world loading, unloading, deletion, cloning
• NEW: Async world creation with callback support
• NEW: Thread-safe operations with proper main thread scheduling

🏗️ Builder Pattern

• NEW: Fluent world creation: api.createWorld("name").environment(NORMAL).build()
• NEW: Method chaining for intuitive API usage
• NEW: Callback support for success/failure handling
• NEW: Async and sync creation methods

🛡️ Advanced Features

• NEW: World size calculation and formatting
• NEW: World backup functionality
• NEW: Player evacuation from worlds
• NEW: Safe spawn location detection
• NEW: World existence checking (loaded/unloaded)

📚 Documentation & Examples

📖 Complete Documentation

• NEW: API_EXAMPLE.java - Complete example plugin
• NEW: Maven/Gradle dependency setup instructions
• NEW: Best practices and performance tips

🎯 Developer Support

• NEW: JitPack integration for easy dependency management
• NEW: Example implementations for common use cases

🔧 Core Plugin Improvements

💬 Enhanced Commands

• IMPROVED: All commands now support short aliases
• IMPROVED: Tab completion for all aliases
• IMPROVED: Help system shows available aliases
• IMPROVED: Teleport command with full validation

🛡️ Security & Performance

• IMPROVED: Enhanced world name validation
• IMPROVED: Rate limiting for teleport operations
• IMPROVED: Security logging for sensitive operations
• IMPROVED: Efficient caching of world information

📝 Messages & UX

• NEW: Teleport-specific messages in messages.yml
• IMPROVED: Command descriptions show aliases
• IMPROVED: Clear error messages for all scenarios
• IMPROVED: Consistent command structure

🔧 Technical Implementation

🏗️ API Architecture

src/main/java/org/hydr4/lilworlds/api/
├── LilWorldsAPI.java              # Main API class
├── events/                        # Event system
├── utils/                         # Utility classes
└── world/                         # World management

🔄 Async Pattern

• NEW: CompletableFuture-based async operations
• NEW: Proper thread management with Bukkit scheduler
• NEW: Error handling with callbacks and exceptions
• NEW: Thread-safe operations throughout

📦 Publishing Ready

• NEW: JitPack integration ready

🎯 Usage Examples

Basic API Usage:

LilWorldsAPI api = LilWorldsAPI.getInstance();
api.createWorld("myworld")
    .environment(World.Environment.NORMAL)
    .generator("superflat")
    .onSuccess(world -> System.out.println("Created!"))
    .buildAsync();

Event Handling:

@EventHandler
public void onWorldCreate(WorldCreateEvent event) {
    if (event.getWorldName().startsWith("temp_")) {
        event.setCancelled(true);
    }
}

🔄 Backward Compatibility

• MAINTAINED: All existing commands work unchanged
• MAINTAINED: Existing configurations remain valid
• MAINTAINED: No breaking changes to plugin behavior
• MAINTAINED: Same security and performance standards

🎯 Critical Bug Fix

• FIXED: WorldBorderCenterChangeEvent may only be triggered synchronously error
  • Fixed async world creation that was causing IllegalStateException
  • Implemented hybrid async/sync approach for optimal performance
  • World preparation (reflection, validation, logging) now runs asynchronously
  • Only the critical creator.createWorld() call runs synchronously (required by Bukkit API)
  • Maintains performance benefits while respecting Bukkit's threading requirements

🚀 Performance Improvements

• NEW: createWorldAdvancedAsync() method for better async handling
• IMPROVED: World creation now uses callback-based async pattern
• OPTIMIZED: Minimal main thread usage - only for world border events
• MAINTAINED: Legacy synchronous method for compatibility

🔧 Technical Changes

• Added Consumer<Boolean> callback pattern for async world creation
• Split world creation into async preparation and sync execution phases
• Added proper error handling for both async and sync phases
• Improved thread safety for world creation operations