🚀 ApxHome v1.0.0 — The Modern Paper Dialogs Update!

ApxHome is a modern, high-performance, and feature-rich Minecraft home management plugin built for Survival, SMP, and Network servers (1.20+ - 1.21+).

This update brings native Paper Dialog API (Minecraft 1.21+) support, giving players clean client-side popup screens while maintaining 100% backward compatibility with classic Chest & Hopper GUIs!

📢 Version Changelog (v1.0.0)

• ✨ Modern Paper Dialogs UI (Minecraft 1.21+):
  • Replaced clunky inventory chests with clean, native client popup dialogs.
  • Compact View: Fast 3-home pagination for quick teleportation.
  • Expanded View: Click "Show More" to open a massive 90-slot home browser.
  • Interactive action buttons for Teleport, Rename, Icon Selection, and Safe Deletion.
  • Added high-definition Minecraft item sprites and custom font rendering (item_sprites.properties).
• 🛡️ Smart Hybrid Fallback:
  • Added automatic runtime detection via DialogSupport.
  • Older versions (1.20+) and servers without Dialog API automatically switch to the classic Chest GUI without any errors or crashes.
• ⚙️ New Config Options:
  • Added GUI.USE-DIALOGS: true/false to easily toggle between Dialogs and Inventory GUIs.
  • Added GUI.dialog-expanded-slots: 90 to customize expanded screen capacity.
• 🐛 Improvements & Fixes:
  • Optimized database query speed during bulk home loading.
  • Fixed cooldown desync during rapid menu navigation.

Video

✨ Full Feature Overview

• 📱 Dual UI Engine (Dialogs & Chest GUIs):
  • Modern native Dialog popups on Paper 1.21+.
  • Classic paginated Inventory GUI on 1.20+ or Spigot.
• ⚙️ Complete In-Game Home Management:
  • ⚡ Teleport: Instant warmup countdown with real-time ActionBar timer.
  • 📍 Relocate: Update home location to your current position with a confirmation screen.
  • ✏️ Rename: Rename homes in-game with regex validation.
  • 🎨 Change Icon: Select custom icons from a menu or set to your currently held item.
  • 🗑️ Safe Deletion: Two-step confirmation screen prevents accidental home deletion.
• ⏳ Smart Teleport Mechanics:
  • Real-time ActionBar timer (Teleporting in 3s...).
  • Cancels on player movement (movement-threshold: 0.2) or damage taken.
  • Built-in safe location checker (prevents teleporting into lava or suffocating in walls).
  • Immersive sound effects (NOTE_BLOCK, ENDERMAN_TELEPORT) and particle effects (PORTAL, REVERSE_PORTAL).
• ⚔️ Combat Log Integration:
  • Blocks players from teleporting while tagged in active PvP combat.
• 🔐 Dynamic LuckPerms Limits:
  • Native hook into LuckPerms API 5.4.
  • Home limits adjust automatically in real-time when player ranks change.
• 💾 Dual Async Storage Engine:
  • SQLite: Instant plug-and-play, zero external setup (plugins/ApxHome/homes.db).
  • MySQL / MariaDB: Multi-threaded HikariCP connection pooling for server networks.
  • 100% Asynchronous — zero server lag or TPS drops.
• 🧩 PlaceholderAPI Support:
  • Full integration with scoreboards, tablists, actionbars, and chat formatters.

🔢 Home Limit System (LuckPerms Setup)

ApxHome calculates home limits using permission nodes. It automatically detects the highest permission assigned to the player and updates their GUI slots immediately.

Permission Nodes:

• apxhome.limit.<number> — Sets maximum allowed homes (e.g., apxhome.limit.3)
• apxhome.limit.unlimited — Gives infinite homes
• apxhome.bypass.limit — Bypasses all home limits

Example Rank Structure:

Default  ──► 3 Homes   (Permission: apxhome.limit.3)
VIP      ──► 5 Homes   (Permission: apxhome.limit.5)
MVP      ──► 10 Homes  (Permission: apxhome.limit.10)
Elite    ──► 15 Homes  (Permission: apxhome.limit.15)
Owner    ──► Unlimited (Permission: apxhome.limit.unlimited)

LuckPerms Setup Commands:

/lp group default permission set apxhome.limit.3
/lp group vip permission set apxhome.limit.5
/lp group mvp permission set apxhome.limit.10
/lp group elite permission set apxhome.limit.15
/lp group owner permission set apxhome.limit.unlimited

📜 Commands & Permissions

Player Commands

Administrator Commands

Bypass Permissions

🧩 PlaceholderAPI Placeholders

⚙️ Configuration (config.yml)

# ==============================================================================
# ApxHome Main Configuration
# ==============================================================================

general:
  default-home-limit: 3
  max-name-length: 16
  name-regex: "^[a-zA-Z0-9_ -]+$"
  date-format: "dd/MM/yyyy HH:mm"
  default-sort: "NAME"

teleport:
  warmup: 3
  cooldown: 5
  cancel-on-movement: true
  movement-threshold: 0.2
  cancel-on-damage: true
  safe-teleport: true
  combat:
    enabled: true
    duration: 10
  actionbar:
    enabled: true

# ==============================================================================
# GUI & Dialog Configurations
# ==============================================================================
GUI:
  # true = Modern Paper Dialogs (Minecraft 1.21+ Paper)
  # false = Classic Inventory Chest GUI
  USE-DIALOGS: true

  # Total slots shown in expanded dialog view (Show More)
  dialog-expanded-slots: 90

# ==============================================================================
# Database Configuration
# ==============================================================================
database:
  type: "SQLITE" # Options: SQLITE or MYSQL
  sqlite:
    file: "homes.db"

📦 Installation & Setup

1. Stop your Minecraft server.
2. Put ApxHome-1.0.0.jar into your server's plugins/ directory.
3. Required / Recommended Plugins:
   • Install PlaceholderAPI into plugins/ (Recommended for placeholders).
   • Install LuckPerms into plugins/ (Recommended for rank-based limits).
4. Start your server.
5. Customize settings inside plugins/ApxHome/config.yml and run /apxhome reload!

📌 Requirements & Compatibility

• Minecraft Version: 1.20 - 1.21.x+
• Server Software: Paper, Purpur (Recommended for Dialogs), or Spigot.
• Java Version: Java 21+

💬 Support & Community

Need help, found a bug, or want to suggest a new feature? Join our official community:

• 👾 Discord Support: https://discord.gg/kagXtuVD7u

Crafted with ❤️ by APX Plugins.