ButtomHome

ButtonHome 🏠✨

A premium, modern, and highly interactive native home management system built exclusively for modern Paper servers (1.21.x – 1.22.x / Paper 26.2.x). By abandoning traditional, outdated chest inventories and chat-based buttons, ButtonHome leverages modern Paper Native Dialog UIs, rich Kyori MiniMessage formatting, integrated 3D sounds, and a state-of-the-art Searchable, Paginated Icon Picker to provide an unmatched, premium player experience.

---

🌟 Overview

ButtonHome is a next-generation home management plugin designed for server administrators who want to offer their players a polished, modern, and immersive gameplay experience. It completely replaces the classic, clunky inventory-based chest GUI systems with sleek, client-side native Dialog interfaces.

No client mods, texture packs, or complex resource-pack overlays are required. ButtonHome uses Paper's high-performance native UI packets to render direct interactable prompts, inputs, and selection menus in the center of the player's screen.

---

✨ Features

🖥️ Native Paper Dialogs UI

By leveraging Paper's native dialogue window system, ButtonHome displays a modern, distraction-free user interface directly inside the Minecraft client:

• The Homes Grid (Stage 1): An elegant paginated grid displaying all set homes, clickable vacant slots, and locked expansion slots. Emojis and visual Minecraft item icons are shown directly on this first page inside the slots, allowing players to instantly identify their homes without needing to drill down.
• Minimalist Inspect Panel (Stage 2): A detailed home management window offering quick actions to Teleport, Rename, Change Icon, or Delete the selected home. Coordinates are cleanly hidden from the UI to minimize clutter, ensuring a high-end, uncluttered aesthetic.
• Set Home Prompt & Rename: Beautiful modal text input fields that let players type their home name directly inside the client dialogue, with automatic validation (A-Za-z0-9_-).
• Deletion Confirmation: Two-stage verification menus to prevent accidental home deletions.
• Direct Exit Option: Beautifully styled, highly accessible direct "Exit" buttons located on all major screens (Stage 1 Grid, Stage 2 Management, and Stage 4 Icon Picker) for seamless, single-click closure.

🔍 Interactive Searchable Icon Picker

Customize how each home appears in the grid with an advanced icon selector:

• Lists all valid Minecraft items as selectable icons with visual emoji mappings on the client-side.
• Features a built-in search filter where players can type material names directly to instantly narrow down selection lists.
• Includes robust pagination to effortlessly browse thousands of items alphabetically.

⏳ Advanced Teleport Warmups & Cooldowns

• Action Bar Warmup HUD: Warmup count downs are rendered on the player's live Action Bar (simulated Minecraft UI bar) to prevent chat box spam and maintain full gameplay visibility.
• Movement & Damage Check: Teleportation automatically aborts if the player moves from their block position or takes damage during the warmup phase.
• Cooldowns: Per-player cooldown periods to prevent teleport spamming.

🔊 Immersive Sound Cues

Satisfying audio feedback on successful warmups, cancellations, and teleports, using built-in synthesized sound schemes (e.g., Enderman Teleport, Level Up Chimes, Experience Chimes).

👑 Premium Admin Commands

Server administrators can use /adminhome <player> to open a real-time, native administrative grid displaying all homes set by a target player, complete with coords tooltips and instant administrative teleportation.

---

🖥️ AI Studio Interactive Web Simulator

The included AI Studio companion web application simulates a live Paper server environment with high-fidelity visual elements:

1. Minecraft Dialog Screen Simulator: Replicates client-side Dialog windows, button clicks, set home modals, delete popups, and the Icon Picker menu.
2. Live Action Bar Notification: Renders active teleport countdowns in a high-contrast Minecraft HUD action bar component that pulses in real time.
3. Active Configuration Panel: Displays the live config.yml settings to test sound profiles, warmup delays, and home slot configurations.
4. Live Console Logs & Terminal actions: Outputs realistic server startup and player action logs, mimicking actual plugin log messages in real-time.

---

🛠️ Command Reference

ButtonHome exposes a comprehensive suite of commands for players, administrators, and internal UI mechanics:

Command	Syntax	Description	Default Permission
/home	/home [name]	Opens the native Dialog Grid or quick-selects/teleports to a home.	buttonhome.use
/sethome	/sethome [name]	Triggers the native sethome text dialog or saves the current location immediately.	buttonhome.use
/delhome	/delhome <name>	Deletes an existing home location permanently.	buttonhome.use
/homes	/homes [page|plain]	Displays the paginated Dialog Grid or prints a plain-text list (for accessibility).	buttonhome.use
/homecancel	/homecancel	Aborts an active, pending teleport warmup delay.	buttonhome.use
/adminhome	/adminhome <player> [home]	Admin tool to view, manage, or instantly teleport to any player's home.	buttonhome.admin
/buttonhome	/buttonhome <reload|help>	Reloads the configuration file or displays the help index.	buttonhome.admin

⚙️ Internal UI Commands (Automated)

These commands are seamlessly registered for backend button interactions, but can also be invoked manually if desired:

• /homeselect <home> — Opens the Manage Home Dialog for a specific home.
• /homesetprompt <home> — Launches the creation text dialog for a named home slot.
• /hometp <home> — Initiates the teleportation sequence (checks warmup, cooldown, and safety).

---

🔑 Permissions Hierarchy

The plugin employs a clean permission node structure compatible with LuckPerms and other modern permission managers:

• buttonhome.use (Default: true)
  • Grants access to standard home navigation, creation, deletion, and plain text listings.
• buttonhome.admin (Default: op)
  • Grants full access to administrative viewing (/adminhome), instant teleportation, and configuration reloading (/buttonhome reload).
• buttonhome.bypass.cooldown (Default: false)
  • Bypasses the teleportation cooldown timer.
• buttonhome.bypass.warmup (Default: false)
  • Bypasses the teleportation warmup delay for instant travel.

📊 Dynamic LuckPerms Limits (1 to 50)

Instead of static caps or rank groups, ButtonHome supports a flexible, granular rank structure. You can assign precise home slot limits directly in LuckPerms using the buttonhome.limit.<number> permissions node:

• buttonhome.limit.1 - Restricts player or group to exactly 1 home slot.
• buttonhome.limit.2 - Restricts player or group to exactly 2 home slots.
• buttonhome.limit.3 - Restricts player or group to exactly 3 home slots.
• ... goes all the way to:
• buttonhome.limit.50 - Unlocks the full grid of 50 home slots.

The plugin dynamically parses all active player permissions, extracts the numerical values from buttonhome.limit.<number>, and grants the highest matching index as the player's active home capacity. If a player does not possess any explicit limit node, they automatically fall back to the default-max-homes value specified in the configuration.

---

⚙️ Configuration (config.yml)

The config.yml configuration supports rich MiniMessage formatting, RGB Hex color tags (<#hex>), and full UI customizability:

# ==========================================
# ButtonHome Configuration File
# ==========================================

# Home limit for players without a specific permission node (buttonhome.limit.<n>)
default-max-homes: 2

# Warmup time (seconds) standing still before teleporting. Set to 0 for instant teleport.
warmup-seconds: 5

# Cancel teleport if the player moves from their block position
cancel-on-move: true

# Cancel teleport if the player takes damage
cancel-on-damage: true

# Cooldown (seconds) between successful teleports. Set to 0 for no cooldown.
teleport-cooldown-seconds: 0

# Player-facing messages (formatted with MiniMessage)
messages:
  menu-divider: "<#4b5563>▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬</#4b5563>"
  # General error messages
  no-permission: "<#ef4444>You do not have permission to use this command!</#ef4444>"
  player-only: "<#ef4444>Only players can use this command!</#ef4444>"
  invalid-name: "<#ef4444>Invalid home name! Names must be 1-16 characters long and use only letters, numbers, hyphens, and underscores (e.g. [A-Za-z0-9_-]).</#ef4444>"
  no-such-home: "<#ef4444>You don't have a home named <#fbbf24>%home%</#fbbf24>.</#ef4444>"
  usage-hint: "<#9ca3af>Usage: %usage%</#9ca3af>"
  
  # Home operations messages
  home-set: "<#10b981>Home <#f9fafb>%home%</#f9fafb> has been set at your current location!</#10b981>"
  home-deleted: "<#ef4444>Home <#f9fafb>%home%</#f9fafb> has been deleted.</#ef4444>"
  home-already-exists: "<#ef4444>A home named <#fbbf24>%home%</#fbbf24> already exists!</#ef4444>"
  limit-reached: "<#ef4444>You have reached your home limit of <#fbbf24>%limit%</#fbbf24>! Delete an existing home first.</#ef4444>"
  
  # Teleport status messages
  warmup-start: "<#f59e0b>⏳ Teleporting to %home% in %seconds% seconds. Do not move or take damage!</#f59e0b>"
  warmup-cancelled-move: "<#ef4444>✘ Teleport cancelled — you moved.</#ef4444>"
  warmup-cancelled-damage: "<#ef4444>✘ Teleport cancelled — you took damage.</#ef4444>"
  warmup-cancelled-manual: "<#ef4444>✘ Teleport cancelled.</#ef4444>"
  warmup-nothing-pending: "<#9ca3af>You don't have a pending teleport.</#9ca3af>"
  teleport-success: "<#10b981>✔ Teleported to %home%.</#10b981>"
  on-cooldown: "<#ef4444>You must wait <#fbbf24>%seconds%</#fbbf24> more seconds before teleporting again.</#ef4444>"
  world-not-loaded: "<#ef4444>✘ Teleport failed — the world <#f9fafb>%world%</#f9fafb> is not currently loaded.</#ef4444>"

  # Fallback plain homes list (e.g. for accessibility/compat)
  plain-list-prefix: "<#f59e0b>Your homes (%count%/%limit%): </#f59e0b>"

  locked-slot-clicked: "<#ef4444>This home slot is locked! Upgrade your rank or obtain permission <#fbbf24>buttonhome.limit.%index%</#fbbf24> to unlock more slots.</#ef4444>"
  no-homes: "<#9ca3af>You have no homes yet! Use <#fbbf24>/sethome <name></#fbbf24> to save your location.</#no-homes>"

# ==========================================
# Native Dialogs UI Configuration
# ==========================================
gui:
  settings:
    # Maximum number of homes to display per page in the grid
    homes-per-page: 7

  # Menu Titles
  stage1:
    title: "Homes Grid"
    admin-title: "%player%'s Homes"
  stage2:
    title: "Manage %home%"
  stage3:
    title: "Set home %home%?"

  # Interactive GUI Items configuration
  items:
    occupied:
      name: "<#f9fafb>%icon% %home%</#f9fafb>"
      lore:
        - "<#9ca3af>World: <#f9fafb>%world%</#f9fafb></#9ca3af>"
        - ""
        - "<#fbbf24>âš¡ Click to manage this home!</#fbbf24>"
    new:
      name: "<#9ca3af>✚ Slot %index% (Vacant)</#9ca3af>"
      lore:
        - ""
        - "<#10b981>Click to save your current</#10b981>"
        - "<#10b981>location to this slot.</#10b981>"
    locked:
      name: "<#ef4444>🔒 Locked Slot %index%</#ef4444>"
      lore:
        - "<#f59e0b>buttonhome.limit.%index%</#f59e0b>"
        - "<#9ca3af>or upgrade your server rank</#9ca3af>"
        - "<#9ca3af>to unlock this home slot.</#9ca3af>"

---

💾 Storage Architecture (homes.yml)

Homes are cleanly stored in a single flat file database called homes.yml inside the plugin's data folder. The database structure maps player homes to their respective unique Minecraft UUIDs, storing world names, XYZ coordinates, rotational yaw/pitch, chosen material icon, and assigned grid slot number:

# ==========================================
# ButtonHome Flat-File Database
# ==========================================

8f20349a-cf2a-4dbd-8151-54a8e0339a04:
  spawn:
    world: world
    x: 104.5
    y: 64.0
    z: -320.12
    yaw: 90.0
    pitch: 0.0
    icon: LIME_BED
    slot: 1
  base:
    world: world_nether
    x: -12.33
    y: 120.0
    z: 555.9
    yaw: -180.0
    pitch: 15.4
    icon: PORTAL
    slot: 2
  mine: