GhastMaster - Making Happy Ghasts more useful

GhastMaster: The Ultimate Happy Ghast Enhancement Plugin

Transform your Minecraft server's aerial transportation with the most advanced Happy Ghast plugin ever created.

---
Overview

GhastMaster is a comprehensive Minecraft Spigot plugin that revolutionizes Happy Ghast gameplay by introducing sophisticated speed management, ownership
systems, aerial building capabilities, and innovative community features. Designed for servers of all types, GhastMaster transforms simple ghast riding into
an engaging, multi-layered experience that enhances both individual gameplay and server community interaction.

---
Core Features

🏗️ Aerial Building System

Build while you fly - GhastMaster's building system allows players to place blocks directly on Happy Ghasts while sneaking. This feature opens
up entirely new possibilities for aerial construction projects.

Technical Details:
- Block Placement: Right-click with blocks while sneaking on a Happy Ghast
- Full Compatibility: Integrates seamlessly with other building and protection plugins through proper BlockPlaceEvent handling
- Block Support: Works with all placeable blocks, including directional blocks like stairs, logs, and slabs
- Game Mode Support: Functions in both Survival and Creative modes
- Hand Support: Works with both main hand and offhand placement

Use Cases:
- Mobile base construction during exploration
- Aerial bridge and platform building
- Sky cities and floating structures
- Large-scale creative projects requiring mobility

⚡ Advanced Multi-Tier Speed System

Five-level speed progression that transforms Happy Ghasts from simple mounts into customizable vehicles with distinct performance characteristics.

Speed Tiers:
1. Base Speed: Configurable idle speed when no passengers are aboard
2. Passenger Scaling: Dynamic speed adjustment based on 1-4 passengers
3. Speed Levels 1-4: Temporary speed boosts achieved by feeding snowballs
4. Boost Mode: Extreme speed burst activated by feeding fire charges
5. Cooldown Management: Sophisticated timing system prevents speed abuse

Feeding Mechanics:
- Snowballs: Stackable speed increases with individual duration timers
- Fire Charges: High-speed boost mode with server-configurable cooldowns
- Passenger Control: Configurable permissions for who can feed ghasts
- Visual Feedback: Particle effects and HUD indicators during speed changes

Configuration Examples:
# Percentage-based speed system (100% = default ghast speed)
idle-happy-ghast-speed-percent: 100.0
1-passenger-happy-ghast-speed-percent: 150.0
2-passenger-happy-ghast-speed-percent: 130.0
speed-level-4-percent: 200.0
boost-speed-percent: 500.0

# Duration and cooldown management
speed-level-1-duration: 30
boost-duration: 5
boost-cooldown: 60

👑 Comprehensive Ownership System

Claim, protect, and manage your Happy Ghasts with a robust ownership system that prevents griefing while maintaining multiplayer accessibility.

Ownership Features:
- Claiming Process: Place harnesses on unclaimed Happy Ghasts to gain ownership
- Access Control: Only owners can be the primary (first) passenger
- Shared Riding: Additional passengers can join regardless of ownership
- Persistent Storage: Ownership data survives server restarts and chunk unloading
- Transfer System: Owners can remove harnesses to release ownership

Security Measures:
- Unauthorized Access Protection: Automatic sound effects and knockback for unauthorized users
- Visual Feedback: Clear messaging system with owner identification
- Configurable Intensity: Adjustable knockback strength and audio feedback
- Smart Detection: Distinguishes between primary and secondary passenger attempts

💖 Revolutionary Free Ghast System

Community-oriented feature that allows servers to create public transportation networks using "free" Happy Ghasts that remain permanently unclaimable.

Free System Features:
- Community Access: Free ghasts can be harnessed and ridden by anyone
- Visual Identification: Heart particle effects continuously mark free ghasts
- Persistent Status: Free status survives all server operations
- Easy Creation: Simple command-based system for marking ghasts as free
- Flexible Control: Server administrators can control who can create free ghasts

Free Mode Process:
1. Execute /freeghast or /ghastmaster free command
2. 30-second timer activates (configurable)
3. Right-click any eligible Happy Ghast to mark as free
4. Automatic particle effects begin
5. Ghast becomes permanently community-accessible

---
Technical Implementation

Performance Optimization

- Asynchronous Processing: All timed effects use Bukkit's scheduler system
- Memory Management: Automatic cleanup of expired tasks and player data
- Chunk Loading: Smart particle effect management across chunk boundaries
- Thread Safety: Proper concurrent access handling for entity modifications

Plugin Integration

- Event System: Proper BlockPlaceEvent integration for seamless plugin compatibility
- bStats Integration: Anonymous usage statistics for development insights
- Cross-Version Support: Designed for Minecraft 1.21+ with backward compatibility considerations
- API Friendliness: Clean event handling that doesn't interfere with other plugins

Data Persistence

- Entity NBT Storage: Ownership and free status stored directly in entity data
- Session Management: Player-specific data (free mode, cooldowns) managed in memory
- Restart Survival: All persistent data survives server restarts and reloads

---
Command System

Primary Commands

| Command | Permission | Default | Function |
|---------------------|--------------------|---------|---------------------------------|
| /ghastmaster reload | ghastmaster.reload | OP | Reloads plugin configuration |
| /ghastmaster free | ghastmaster.free | OP | Enters free mode for 30 seconds |
| /freeghast | ghastmaster.free | OP | Shorthand for free mode |

Advanced Features

- Tab Completion: Intelligent command completion based on player permissions
- Permission Integration: Commands only appear if players have appropriate permissions
- Error Handling: Comprehensive error messages for invalid usage
- Help System: Built-in help text for all commands

---
Configuration System

Message Customization

Complete control over all player-facing messages with support for:
- Color Codes: Full Minecraft color code support using & notation
- Prefix System: Consistent messaging with %PREFIX% placeholder
- Variable Replacement: Dynamic content like player names and actions
- Multi-language Ready: Easy localization support

Granular Settings

Config:
Settings:
# Core features
build-on-happy-ghast-enabled: true
ownership-system-enabled: true
free-system-enabled: true

# Speed management
idle-happy-ghast-speed-percent: 100.0
1-passenger-happy-ghast-speed-percent: 150.0
boost-speed-percent: 500.0
boost-cooldown: 60

# Visual effects
show-speed-hud: true
hud-update-interval-ticks: 20
free-ghast-particle-chance: 0.3

# Access control
any-passenger-can-feed: true
ownership-knockback-strength: 1.5

---
Server Applications

Survival Servers

- Personal Transportation: Players can claim and customize their own flying mounts
- Progression System: Speed upgrades provide gameplay goals and rewards
- Protection: Ownership system prevents mount theft and griefing
- Resource Management: Feeding requirements create resource sinks

Creative Servers

- Aerial Building: High-speed flying with block placement for large projects
- Collaborative Building: Multiple passengers can work on projects together
- Quick Transportation: Boost mode for rapid movement across large builds
- Building Competitions: Speed and building features enable aerial building contests

Community Servers

- Public Transportation: Free ghasts at spawn points and major locations
- Server Events: Racing competitions using the speed system
- Community Projects: Shared aerial vehicles for group activities
- Social Features: Multi-passenger system encourages cooperation

RPG/Adventure Servers

- Mount Progression: Tiered speed system fits RPG advancement mechanics
- Quest Integration: Ownership and free systems can be integrated into quest lines
- Transportation Networks: Free ghasts can serve as fast travel points
- Player Interaction: Shared riding promotes social gameplay

---
Installation & Setup

Requirements

- Server Software: Spigot 1.21+ or Paper 1.21+ (recommended)
- Java Version: Java 21 or higher
- Dependencies: None - completely standalone plugin

Installation Process

1. Download the latest GhastMaster JAR file
2. Place in your server's plugins folder
3. Restart your server
4. Configure permissions and settings as desired
5. Use /ghastmaster reload to apply configuration changes

Initial Configuration

The plugin works out-of-the-box with sensible defaults, but servers can customize:
- Speed percentages for different scenarios
- Particle effect frequency and appearance
- Message text and colors
- Permission requirements
- Cooldown timers and durations

---