Extensions

A comprehensive and extensible Minecraft plugin suite providing essential server utilities with a modular addon architecture. All player data is stored in a unified SQLite database for optimal performance and easy management.

Table of Contents

• Features
• Project Structure
• Installation
• Official Addons
• Database
• Commands & Permissions
• Developer API
• Building
• Configuration
• Support

---

Features

Core Plugin

• 🗄️ Unified Database - SQLite storage for all player data (homes, warps, cooldowns, kit usage)
• 🏠 Home System - Set multiple homes with permission-based limits
• 🌍 Warp System - Server-wide teleportation points
• 📦 Kit System - Customizable item kits with cooldowns (definitions in config, usage in database)
• 📧 Mail System - Send and receive messages between players
• ⚡ Admin Tools - Vanish, gamemode, sudo, item management
• 🔧 Utilities - Repair, anvil, crafting table, grindstone access
• ✨ Quality of Life - Fly, god mode, back teleport, hat command
• 🎯 Teleport System - TPA requests, spawn teleportation

ExtensionsEconomy Addon

• 💰 Built-in Economy - Custom currency system (no Vault required)
• 🏪 Shop Signs - Player-created buy/sell shops
• 💳 Transactions - Pay other players (minimum $1), admin commands (minimum $0.01)
• 📊 Storage Options - YAML, SQLite, or MySQL with connection pooling
• 🔗 Integration - Optional costs for homes, kits, warps
• ✅ Validation - Price minimums ($0.01), balance rounding, negative amount protection

ExtensionsNpc Addon

• 🤖 NPC Shops - Create villager NPC shop vendors
• 🎯 Quest Givers - NPCs for quests and interactions
• 📂 Categories - 13 categories for shop items (Blocks, Nether, End, Weapons, Tools, Armor, Food, etc.)
• 📄 Pagination - Automatic multi-page support for large inventories
• 💎 Visual GUI - Interactive shopping interface
• 🔒 Confirmations - Double-click confirm for expensive items (>$1000)

ExtensionsGui Addon

• 📋 Visual Menus - GUI for homes, kits, warps, and mail
• 🎨 Intuitive Design - Easy navigation for players
• 🔌 Optional - Core works without GUIs, falls back to text

---

Project Structure

This is a multi-module Gradle project with modular addon architecture:

Extensions/
├── core/                     # Required - Core plugin with API and database
└── addons/
    ├── chat/                 # Optional - Chat formatting and private messaging
    ├── piglins/              # Optional - Piglin zombification immunity
    ├── economy/              # Optional - Economy addon with shop signs
    ├── npc/                  # Optional - NPC shops & quest givers
    ├── gui/                  # Optional - GUI addon
    ├── vaults/               # Optional - Player vaults
    ├── fishing/              # Optional - Custom fishing mechanics
    └── npcjobs/              # Optional - NPC job system

core (Required)

The foundation providing:

• All essential commands and features
• Unified SQLite database for player data
• Complete addon API (ExtensionsAPI)
• Event system for inter-addon communication
• Data management (homes, kits, warps, mail)
• No configuration file needed (truly minimal)

addons/chat (Optional)

Chat enhancement addon:

• Custom public chat formatting
• Join/leave message formatting
• Private messaging (/msg, /reply, /tell, /whisper)
• Social spy for staff
• Player muting system
• Message toggle for players
• Config: plugins/Extensions/chat.yml

addons/piglins (Optional)

Quality of life addon:

• Makes piglins immune to zombification in overworld
• Configurable enable/disable
• Config: plugins/Extensions/piglins.yml

addons/economy (Optional)

Economy addon featuring:

• Custom economy (no EssentialsX/Vault dependency)
• Sign-based shop system (item and command shops)
• Player-to-player transactions
• Admin economy commands
• Multiple storage backends (YAML/SQLite/MySQL)
• Configurable costs for homes, kits, warps
• Price validation and balance protection
• Config: plugins/Extensions/economy.yml

addons/vaults (Optional)

Player storage addon:

• Personal vaults for extra storage
• Configurable vault size and rows
• GUI interface
• Auto-save functionality
• Config: plugins/Extensions/vaults.yml

addons/gui (Optional)

Visual interface addon:

• Interactive GUIs for homes, kits, warps
• Mail viewing interface
• Item-based navigation
• Automatic fallback if not installed
• No config required

addons/fishing (Optional)

Custom fishing mechanics addon:

• Enhanced fishing rewards
• Rarity system
• Custom fish types
• Statistics tracking
• Config: plugins/Extensions/fishing.yml

addons/npc (Optional)

NPC shop system addon:

• Create villager NPC shop vendors
• 13 item categories for organization
• Categorized browsing with filters
• Automatic pagination for large shops
• Economy integration (requires ExtensionsEconomy)
• Persistent storage across restarts
• Quick item addition with /additem command
• Double-click confirmation for expensive items
• Config: plugins/Extensions/npc.yml

---

Installation

Basic Setup (Core Only)

1. Download or Build

   git clone https://github.com/MatesMediaDev/Extensions.git
   cd Extensions
   ./gradlew build
   

2. Install Core Plugin

   • Copy compiled/Extensions.jar to your plugins/ folder
   • Restart your server
   • Core plugin requires NO configuration!

With Addons

3. Install Optional Addons (choose any you want):

   • compiled/ExtensionsChat.jar - Chat formatting and private messaging
   • compiled/ExtensionsPiglins-1.0.0.jar - Piglin immunity
   • compiled/ExtensionsEconomy.jar - Economy system with shop signs
   • compiled/ExtensionsNpc.jar - NPC shops & quest givers (requires Economy)
   • compiled/ExtensionsVaults.jar - Player vaults
   • compiled/ExtensionsGui.jar - Visual interfaces
   • compiled/ExtensionsFishing.jar - Custom fishing

4. Configure Addons

   • All addon configs follow the pattern: plugins/Extensions/{addon-name}.yml
   • Chat: plugins/Extensions/chat.yml
   • Piglins: plugins/Extensions/piglins.yml
   • Vaults: plugins/Extensions/vaults.yml
   • Economy: plugins/Extensions/economy.yml
   • Fishing: plugins/Extensions/fishing.yml
   • NPC: plugins/Extensions/npc.yml
   • GUI: No config required

5. Restart and enjoy!

---

Database

Extensions uses a unified SQLite database for optimal performance and reliability.

What's Stored in Database

plugins/Extensions/database.db contains:

• player_homes - All player home locations
• warps - Server warp points
• spawns - Spawn locations per group
• warp_cooldowns - Warp cooldown tracking
• kit_usage - Kit usage timestamps
• economy_balances - Economy data (if ExtensionsEconomy installed)

What's Still in Config

• plugins/Extensions/kits.yml - Kit definitions (items, cooldowns)
• Addon configs in plugins/Extensions/{addon-name}.yml

Benefits

• ✅ Fast - SQLite is highly optimized
• ✅ Reliable - ACID compliant, no corruption
• ✅ Clean - One file instead of dozens of YAMLs
• ✅ Portable - Easy to backup and restore
• ✅ Scalable - Handles large player counts efficiently

---

Official Addons

ExtensionsChat

Chat formatting and private messaging system

Config: plugins/Extensions/chat.yml

Features

• Custom public chat formatting
• Configurable join/leave messages
• Private messaging with multiple aliases
• Social spy for staff monitoring
• Player muting system
• Per-player message toggles

Commands

Command	Aliases	Description	Permission
/msg <player> <msg>	/m, /pm, /tell, /whisper, /w	Send private message	extensions.msg
/reply <message>	/r	Reply to last PM	extensions.reply
/socialspy	/ss	Toggle social spy	extensions.socialspy
/mute <player>	-	Mute/unmute player	extensions.mute
/rtoggle	-	Toggle receiving PMs	extensions.rtoggle

Configuration

Config file: plugins/Extensions/chat.yml

chat:
  # Public chat
  enable-chat-format: true
  chat-format: '§7{player}§8: §f{message}'
  
  # Join/Leave
  enable-join-messages: true
  join-format: '§8[§a+§8] §7{player} joined the game'
  leave-format: '§8[§c-§8] §7{player} left the game'
  
  # Private messages
  enable-socialspy: false
  msg-format-sender: '§8[§6To §r{receiver}§8] §7{message}'
  msg-format-receiver: '§8[§2From §r{sender}§8] §f{message}'

ExtensionsPiglins

Piglin zombification immunity

Config: plugins/Extensions/piglins.yml

Features

• Prevents piglins from zombifying in the overworld
• Lightweight and configurable
• No performance impact

Configuration

Config file: plugins/Extensions/piglins.yml

piglin:
  immunity: true  # Set to false to disable

ExtensionsEconomy

Custom economy system with item and command shops

Config: plugins/Extensions/economy.yml

Features

• Built-in currency (no Vault/EssentialsX dependency)
• Player-to-player payments
• Admin economy commands (give/take/set)
• Item shops - Buy and sell items with signs
• Command shops - Sell ranks, kits, and permissions
• Database support (YAML/SQLite/MySQL) for scalability

Shop Signs

Item Shops - Buy and sell items:

Line 1: [Shop]
Line 2: DIAMOND
Line 3: B:100
Line 4: S:50

• Left-click to buy items
• Right-click to sell items
• Sneak + click for 64x quantity

Command Shops - Purchase commands:

Line 1: [CmdShop]
Line 2: VIP Rank
Line 3: 5000
Line 4: /lp user {player} parent set vip

• Left-click to purchase
• Command executes from console
• {player} replaced with buyer name
• Perfect for ranks, kits, permissions
• Minimum price: $0.01

Validation & Safety

• Payment minimum: $1 for /pay
• Admin minimum: $0.01 for /eco commands
• Shop minimums: $0.01 for all shop prices
• Balance rounding: 2 decimal places to prevent floating-point errors
• Negative protection: Cannot use negative amounts

Storage Options

Configure in plugins/Extensions/economy.yml:

storage:
  type: YAML  # or SQLITE, MYSQL
  
  # For MySQL (optional)
  mysql:
    host: localhost
    port: 3306
    database: extensions
    username: root
    password: password

Performance:

• YAML - Good for <100 players
• SQLITE - Good for 100-500 players
• MYSQL - Best for 500+ players or networks

ExtensionsNpc

NPC system for shops and quest givers

Config: plugins/Extensions/npc.yml

Features

• Create villager NPC shop vendors (invulnerable, no AI)
• 13 item categories - Blocks, Overworld, Nether, End, Weapons, Tools, Armor, Food, Potions, Redstone, Decoration, Misc
• Category filtering - Browse by specific item types
• Automatic pagination - Handles shops with hundreds of items
• Price validation - Minimum $0.01 per item
• Confirmation system - Double-click for purchases >$1000
• Persistent storage - Shops saved across restarts
• Requires ExtensionsEconomy

Commands

Command	Description	Permission
/npc create <name>	Create NPC	extensions.npc.create
/npc delete	Delete NPC (look at it)	extensions.npc.delete
/npc list	List all NPCs	extensions.npc.*
/additem <price> <category> [amt]	Add item to shop	extensions.npc.edit

Aliases: /npcs, /shopnpc

Categories: all, blocks, overworld, nether, end, weapons, tools, armor, food, potions, redstone, decoration, misc

Usage Example

# Create shop
/npc create Materials Shop

# Add items (hold item, look at NPC)
/additem 1000 blocks 64     # 64 diamonds for $1000
/additem 500 nether 16      # 16 netherite ingots for $500
/additem 200 weapons 1      # 1 diamond sword for $200

# Players: Click NPC → Filter by category → Purchase

Configuration

Config file: plugins/Extensions/npc.yml

npc:
  name-format: "&e[SHOP] &f%name%"
  
transactions:
  confirm-threshold: 1000.0  # Confirm for purchases >$1000
  purchase-sound: ENTITY_EXPERIENCE_ORB_PICKUP

ExtensionsGui

Visual interfaces for player convenience

No configuration required - automatic integration with core plugin.

Features

• GUI for /homes - Visual home selection
• GUI for /kits - Visual kit claiming
• GUI for /warps - Visual warp teleportation
• GUI for /mail - Visual mail reading
• Automatic integration (no config needed)
• Seamless fallback to text-based commands if not installed

---

Commands & Permissions

Core Commands

Social

Command	Description	Permission	Default
/mail <send/read>	Send and receive mail	extensions.mail	true

Note: Chat commands moved to ExtensionsChat addon (see ExtensionsChat section)

Teleportation

Command	Description	Permission	Default
/tp <player>	Teleport to player	extensions.tp	op
/tpa <player>	Request teleport	extensions.tpa	true
/tpahere <player>	Request teleport here	extensions.tpahere	op
/tpaccept	Accept TP request	extensions.tpaccept	true
/tpdeny	Deny TP request	extensions.tpdeny	true
/back	Return to last location	extensions.back	op
/spawn [group]	Go to spawn	extensions.spawn	true

Homes

Command	Description	Permission	Default
/home [name]	Teleport to home	extensions.home	true
/sethome [name]	Set a home	extensions.home.set	true
/delhome [name]	Delete home	extensions.home.delete	true
/homes	List homes	extensions.home	true

Warps

Command	Description	Permission	Default
/warp <name>	Teleport to warp	extensions.warp	true
/warps	List warps	extensions.warp	true
/setwarp <name>	Create warp	extensions.warp.set	op
/delwarp <name>	Delete warp	extensions.warp.delete	op

Kits

Command	Description	Permission	Default
/kit <name>	Claim kit	extensions.kit	true
/kits	List kits	extensions.kit	true
/createkit <name> <cd>	Create kit	extensions.kit.create	op
/delkit <name>	Delete kit	extensions.kit.delete	op

Essentials

Command	Description	Permission	Default
/fly [player]	Toggle flight	extensions.fly	op
/god [player]	Toggle god mode	extensions.god	op
/heal [player]	Restore health	extensions.heal	op
/feed [player]	Restore hunger	extensions.feed	op
/gm <mode> [player]	Change gamemode	extensions.gamemode	op
/vanish	Toggle vanish	extensions.vanish	op
/repair [all]	Repair items	extensions.repair	op
/hat	Wear item as hat	extensions.hat	op
/nick <name>	Set nickname	extensions.nick	op

Utilities

Command	Description	Permission	Default
/anvil	Open anvil	extensions.anvil	op
/craft	Open crafting	extensions.craft	op
/echest [player]	Open enderchest	extensions.echest	op
/grindstone	Open grindstone	extensions.grindstone	op
/invsee <player>	View inventory	extensions.invsee	op
/trash	Open trash	extensions.trash	op
/top	Teleport to top	extensions.top	op

Economy Commands

Command	Description	Permission	Default
/balance [player]	Check balance	extensions.economy.balance	true
/pay <player> <amt>	Pay player	extensions.economy.pay	true
/eco <give/take/set>	Admin commands	extensions.economy.admin	op
/createshop	Shop creation help	extensions.economy.shop.create	op

Shop Permissions:

• extensions.economy.shop.create - Create item and command shops (op)
• extensions.economy.shop.admin - Edit/break any shop sign (op)
• extensions.economy.shop.use - Use shop signs (true)
• extensions.economy.bypass - Bypass all economy costs (op)

Permission Wildcards

• extensions.social.* - All social commands
• extensions.kit.use.* - Use all kits
• extensions.economy.bypass - Bypass economy costs

---

Developer API

Extensions provides a comprehensive API for creating addons.

Quick Start

1. Add Dependency

build.gradle.kts:

dependencies {
    compileOnly("io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT")
    compileOnly(project(":core"))
}

paper-plugin.yml:

dependencies:
  server:
    Extensions:
      load: BEFORE
      required: true
      join-classpath: true

2. Implement ExtensionAddon

public class MyAddon extends JavaPlugin implements ExtensionAddon {
    
    private ExtensionsAPI api;
    
    @Override
    public void onEnable() {
        Extensions extensions = (Extensions) getServer()
            .getPluginManager().getPlugin("Extensions");
        api = Extensions.getAPI();
        api.getAddonManager().registerAddon(this);
    }
    
    @Override
    public void onLoad(ExtensionsAPI api) {
        // Your addon initialization here
        getLogger().info("MyAddon loaded with Extensions API!");
        
        // Register commands
        api.registerCommand("mycommand", new MyCommand());
        
        // Listen to events
        getServer().getPluginManager().registerEvents(new MyListener(), this);
    }
    
    @Override
    public void onUnload() {
        getLogger().info("MyAddon unloaded!");
    }
    
    @Override
    public String getAddonId() { return "my-addon"; }
    
    @Override
    public String getAddonName() { return "My Addon"; }
    
    @Override
    public String getAddonVersion() { return "1.0.0"; }
    
    @Override
    public Plugin getPlugin() { return this; }
}

API Methods

Home Management

// Get all homes for player
Map<String, Location> homes = api.getHomes(player);

// Get specific home
Location home = api.getHome(player, "homeName");

// Set/delete homes
api.setHome(player, "homeName", location);
api.deleteHome(player, "homeName");

Kit Management

// Get all kits
List<String> allKits = api.getAllKits();

// Get available kits for player
List<String> playerKits = api.getAvailableKits(player);

// Check if player can use kit (cooldown)
boolean canUse = api.canUseKit(player.getUniqueId(), "kitName");

// Give kit to player
boolean success = api.giveKit(player, "kitName");

Warp/Spawn Management

// Spawn
Location spawn = api.getSpawn();
api.setSpawn(location);

// Warps
List<String> warps = api.getWarps();
Location warp = api.getWarp("warpName");
api.setWarp("warpName", location);
api.deleteWarp("warpName");

Vanish System

boolean vanished = api.isVanished(player);
api.setVanished(player, true);
List<UUID> vanishedPlayers = api.getVanishedPlayers();

Events

@EventHandler
public void onHomeSet(HomeSetEvent event) {
    Player player = event.getPlayer();
    String homeName = event.getHomeName();
    Location location = event.getLocation();
    
    // Cancel to prevent home creation
    event.setCancelled(true);
}

@EventHandler
public void onKitClaim(KitClaimEvent event) {
    Player player = event.getPlayer();
    String kitName = event.getKitName();
    // Log or modify kit claims
}

@EventHandler
public void onAddonLoad(ExtensionAddonLoadEvent event) {
    ExtensionAddon addon = event.getAddon();
    // React to addon loading
}

Example: Custom Home Limit

@EventHandler
public void onHomeSet(HomeSetEvent event) {
    Player player = event.getPlayer();
    Map<String, Location> homes = api.getHomes(player);
    
    if (homes.size() >= 5 && !player.hasPermission("myaddon.unlimited")) {
        event.setCancelled(true);
        player.sendMessage("§cYou can only have 5 homes!");
    }
}

See the source code of existing addons (extensions-chat, extensions-piglins, extensions-vaults) for implementation examples.

---

Building

Build All Modules

./gradlew build

Build Specific Module

./gradlew :core:build
./gradlew :addons:economy:build
./gradlew :addons:gui:build

Clean Build

./gradlew clean build

All built JARs are output to the compiled/ directory.

---

Configuration

Core Plugin

Core plugin uses a database for all player data and requires minimal configuration.

Kit Definitions (kits.yml)

Kit definitions (what items they contain) are still in YAML for easy editing:

kits:
  starter:
    delay: 0  # Cooldown in seconds
    items:
      - material: DIAMOND_SWORD
        amount: 1
        enchantments:
          minecraft:sharpness: 5
      - material: COOKED_BEEF
        amount: 64

Addon Configurations

Chat Addon

See ExtensionsChat section above.

Piglins Addon

See ExtensionsPiglins section above.

Vaults Addon

Config file: plugins/Extensions/vaults.yml

vault-size: 6  # Number of rows (1-6)
auto-save-interval: 300  # Seconds between auto-saves

vault-cost:
  enabled: false  # Charge to open own vault
  amount: 0

messages:
  vault-opened: "&aVault opened!"
  insufficient-funds: "&cYou need ${amount} to open your vault!"

Fishing Addon

Config file: plugins/Extensions/fishing.yml

treasure-chance: 5.0  # Percentage chance for treasure

fish:
  COMMON:
    - COD
    - SALMON
  RARE:
    - PUFFERFISH
    - TROPICAL_FISH
  LEGENDARY:
    - ENCHANTED_GOLDEN_APPLE

messages:
  rare-catch: "&b&lRare catch! &7You caught a {fish}!"
  legendary-catch: "&6&lLegendary catch! &7You caught a {fish}!"

Economy Addon

Config file: plugins/Extensions/economy.yml

storage:
  type: YAML  # YAML, SQLITE, or MYSQL
  mysql:
    host: localhost
    port: 3306
    database: extensions
    username: root
    password: password

economy:
  starting-balance: 1000.0
  currency-symbol: "$"
  
  # Costs (set to 0 to disable)
  home-cost: 100.0
  warp-cost: 50.0
  kit-cost: 0.0

messages:
  insufficient-funds: "&cYou don't have enough money!"
  payment-sent: "&aYou sent %amount% to %player%"
  payment-received: "&aYou received %amount% from %player%"

---

Support

Getting Help

• Documentation: This README and source code of official addons
• Issues: GitHub Issues
• Source Code: Review plugin source for implementation details

Requirements

• Paper 1.21+ (Spigot not supported)
• Java 21 or higher
• Permissions Plugin (LuckPerms recommended)

Common Issues

Q: Commands not working in economy addon?
A: Paper plugins require programmatic command registration. This is already implemented.

Q: Shop signs not responding to clicks?
A: Ensure you have the latest build. Item shops: left-click buys, right-click sells. Command shops: left-click purchases.

Q: How do I give players multiple homes?
A: Grant extensions.home.multiple permission.

Q: Database connection errors?
A: Check MySQL credentials in economy config. Use YAML for small servers.

---

Architecture

Modular Design:

• Core provides robust API and feature foundation
• Addons register via ExtensionAddon interface
• Automatic addon discovery and lifecycle management
• Event-driven inter-addon communication
• Clean separation of concerns

Hook-Based Features:

• GUI system is fully optional via GuiProvider interface
• Commands check for providers before falling back to text
• No functionality breaks when addons are removed
• Server owners choose exactly what they need

Unified Database:

• SQLite database for all player data
• Automatic migration from legacy YAML files
• Clean separation: player data in database, definitions in config
• Optimal performance for servers of all sizes
• Single file backup/restore

---

License

Custom license - see repository for details.

Author

MatesMediaDev
GitHub: @MatesMediaDev

---

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Test thoroughly
4. Submit a pull request

---

Extensions - Making Minecraft servers better, one addon at a time.