🚀 IonAPI Plugin Template

A production-ready Minecraft plugin template showcasing IonAPI v1.2.0 features and best practices.

✨ Features Demonstrated

💾 Database & Persistence

• ORM System - Entity mapping with @Table, @PrimaryKey, @Column annotations
• Caching - Automatic entity caching with @Cacheable for 10-50x performance boost
• Async Operations - Non-blocking database queries with CompletableFuture
• SQLite & MySQL - Switchable database backends via configuration

💰 Economy System

• Full Economy Provider - Complete implementation with transactions
• Vault Integration - Compatible with Vault-dependent plugins
• Transaction API - Fluent builder pattern for complex operations
• Async by Default - All economy operations are non-blocking

🎨 User Interface

• Main Menu GUI - Central hub for accessing all features
• GUI Framework - Inventory-based menus with click handlers
• Interactive Commands - All commands open beautiful GUIs
• Shop System - Item purchasing with economy integration
• Live Scoreboard - Auto-updating sidebar with placeholders (no flashing!)
• MiniMessage - Modern text formatting with colors and styles

⚡ Performance & Utilities

• Cooldown Manager - Thread-safe player cooldown tracking
• Rate Limiter - Spam prevention with sliding window algorithm
• Hot-Reload Config - Live configuration updates without restart
• Metrics Tracking - Built-in performance monitoring

🔗 Additional Features

• Redis Pub/Sub - Cross-server messaging (optional)
• Task Scheduler - Unified async/sync task API
• Warp System - Save and teleport to custom locations
• Leaderboards - Top players by kills, deaths, and K/D ratio
• BossBar Manager - Progress bars, health bars, and notifications
• Messages System - Externalized messages with MiniMessage support

📋 Commands

Command	Description	Permission
/menu	Open main menu GUI (hub for all features)	iontemplate.menu
/spawn	Teleport to spawn (30s cooldown)	iontemplate.spawn
/balance	Open balance GUI	iontemplate.balance
/pay <player> <amount>	Transfer money (5s cooldown)	iontemplate.pay
/shop	Open shop GUI	iontemplate.shop
/stats	Open stats GUI	iontemplate.stats
/scoreboard	Toggle scoreboard display	iontemplate.scoreboard
/warp [list|set|delete] [name]	Open warp GUI or manage warps	iontemplate.warp
/leaderboard	Open leaderboard GUI	iontemplate.leaderboard

Aliases:

• /menu → /gui, /mainmenu
• /balance → /bal, /money
• /leaderboard → /lb, /top

🛠️ Building

Prerequisites

• Java 21 or higher
• Gradle 8.0+ (wrapper included)
• IonAPI 1.2.0 (see build steps)

Build Steps

Option 1: Local Build (Recommended)

1. Clone both repositories

# Clone IonAPI
git clone https://github.com/mattbaconz/IonAPI.git
cd IonAPI
./gradlew publishToMavenLocal
cd ..

# Clone template
git clone https://github.com/mattbaconz/ion-plugin-template.git
cd ion-plugin-template

2. Build the plugin

./gradlew shadowJar

Output: build/libs/IonTemplatePlugin-1.0.0.jar (419KB)

Option 2: GitHub Actions

The repository includes a GitHub Actions workflow that automatically:

1. Checks out IonAPI from the main repository
2. Builds and publishes IonAPI to local Maven
3. Builds the template plugin
4. Uploads the JAR as an artifact

Simply push to main or develop branch to trigger the build.

Note: IonAPI must be available in the main repository for CI/CD builds to work.

🐳 Quick Start with Docker

Test the plugin with MySQL and Redis instantly:

# Start services
docker-compose up -d

# Build and deploy
./gradlew shadowJar
docker-compose restart paper

# View logs
docker-compose logs -f paper

See DOCKER.md for detailed Docker setup.

⚙️ Configuration

Edit plugins/IonTemplatePlugin/config.yml:

# Database settings
database:
  type: sqlite  # sqlite or mysql
  mysql:
    host: localhost
    port: 3306
    database: minecraft
    username: root
    password: ""

# Economy settings
economy:
  starting-balance: 1000.0
  currency-symbol: "$"

# Cooldowns (seconds)
cooldowns:
  teleport: 30
  pay: 5

# Rate limits
rate-limits:
  chat:
    max-messages: 5
    window-seconds: 10

# Redis (optional)
redis:
  enabled: false
  host: localhost
  port: 6379

Changes apply instantly via hot-reload!

📁 Project Structure

src/main/java/com/example/iontemplate/
├── IonTemplatePlugin.java          # Main plugin class
├── command/                        # Command handlers (9 commands)
│   ├── MenuCommand.java            # NEW: Main menu
│   ├── BalanceCommand.java         # Opens balance GUI
│   ├── PayCommand.java
│   ├── ShopCommand.java
│   ├── SpawnCommand.java
│   ├── StatsCommand.java           # Opens stats GUI
│   ├── ScoreboardCommand.java
│   ├── WarpCommand.java            # Opens warp GUI
│   └── LeaderboardCommand.java     # Opens leaderboard GUI
├── data/                           # Database entities
│   ├── PlayerData.java             # Player stats (@Cacheable)
│   ├── PlayerBalance.java          # Economy balances
│   └── Warp.java                   # Saved locations
├── economy/                        # Economy implementation
│   └── TemplateEconomyProvider.java
├── gui/                            # GUI menus (NEW: 6 GUIs!)
│   ├── MainMenuGui.java            # Central hub
│   ├── BalanceGui.java             # Balance viewer
│   ├── StatsGui.java               # Stats viewer
│   ├── LeaderboardGui.java         # Top players
│   ├── WarpGui.java                # Warp teleporter
│   └── ShopGui.java                # Shop system
├── listener/                       # Event listeners
│   └── PlayerListener.java
└── manager/                        # Feature managers
    ├── ScoreboardManager.java      # Fixed flashing issue
    └── BossBarManager.java         # BossBar API

🎯 Code Examples

Database Entity with Caching

@Table("player_data")
@Cacheable(ttl = 60, maxSize = 500)  // Cache for 60 seconds
public class PlayerData {
    @PrimaryKey
    private UUID uuid;
    
    @Column(name = "player_name", nullable = false)
    private String name;
    
    @Column(defaultValue = "0")
    private int kills;
    
    // Getters/setters...
}

Async Database Operations

database.findAsync(PlayerData.class, uuid).thenAccept(opt -> {
    if (opt.isPresent()) {
        PlayerData data = opt.get();
        data.addKill();
        database.saveAsync(data);
    }
});

Economy Transactions

IonEconomy.transaction(player.getUniqueId())
    .withdraw(BigDecimal.valueOf(100))
    .reason("Shop purchase")
    .commit()
    .thenAccept(result -> {
        if (result.isSuccess()) {
            player.sendMessage("Purchase complete!");
        }
    });

Main Menu GUI (Central Hub)

// Open the main menu - access all features from one place!
new MainMenuGui(plugin).open(player);

// Players can access:
// - Stats GUI (kills, deaths, K/D, playtime)
// - Balance GUI (view balance, top balances)
// - Shop GUI (purchase items)
// - Warp GUI (teleport to saved locations)
// - Leaderboard GUI (top kills, deaths, K/D)
// - Toggle scoreboard

Interactive GUI with Click Handlers

new IonGuiBuilder()
    .title("<gold><bold>Shop Menu")
    .rows(3)
    .item(10, diamondSword, click -> {
        purchaseItem(click.getPlayer(), "diamond_sword");
    })
    .build()
    .open(player);

📊 Performance

• Database: 10-50x faster with automatic caching
• JAR Size: 419KB (includes all dependencies + 6 GUI menus)
• Memory: ~5MB runtime footprint
• Startup: <100ms initialization
• Scoreboard: No flashing, smooth updates every second

🔧 Customization

Reduce JAR Size

Comment out unused modules in build.gradle.kts:

dependencies {
    // Remove Redis if not needed (-15KB + Jedis)
    // implementation("com.ionapi:ion-redis:1.2.0")
    
    // Remove database if not needed (-53KB + HikariCP)
    // implementation("com.ionapi:ion-database:1.2.0")
}

Enable Relocation (Production)

Uncomment in build.gradle.kts to avoid conflicts:

tasks.shadowJar {
    relocate("com.ionapi", "${project.group}.libs.ionapi")
}

🐛 Troubleshooting

IDE Shows Errors

The IDE may not see IonAPI dependencies. This is normal - the code compiles fine with Gradle.

Fix: Reload Gradle project or run:

./gradlew --refresh-dependencies build

Database Connection Issues

SQLite: Ensure plugins/IonTemplatePlugin/ folder exists
MySQL: Verify credentials and database exists

Redis Connection Failed

Redis is optional. Set redis.enabled: false in config if not using.

📚 Resources

• IonAPI Repository: github.com/mattbaconz/IonAPI
• IonAPI Documentation: View Docs
• Template Repository: github.com/mattbaconz/ion-plugin-template
• Discord Support: discord.com/invite/VQjTVKjs46
• Report Issues: GitHub Issues

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📄 License

This template is licensed under the MIT License - see LICENSE for details.

💖 Support the Project

If you find this template helpful:

• ⭐ Star the repository on GitHub
• 🐛 Report bugs via GitHub Issues
• 💬 Join our community on Discord
• ☕ Support development:
  • Ko-fi
  • PayPal

👨‍💻 Author

mattbaconz

• GitHub: @mattbaconz
• Discord: Join Server

---

Built with ❤️ using IonAPI