Homes

!Banner

---

A modern, feature-rich home teleportation plugin for Paper servers. Set, manage, and teleport to homes with style, features MiniMessage support, particle beacons, configurable GUIs, full multi-language support, and multiple storage backends.

---

!Features

Core

• Set unlimited homes per player (configurable)
• Teleport with warmup and cooldown timers
• Home info display (coordinates, set date, owner)
• Per-home custom icons in GUI menus
• Home sharing with other players
• Classic command aliases: /sethome, /delhome, /listhomes, /home <name> (configurable)

Visuals & Effects

• Animated particle beacons (13 customizable colors) visible only to the home owner
• Sound effects for teleportation (configurable)
• Real-time action bar countdown during warmup
• Dust particle effects at arrival

UI & Configuration

• Interactive GUIs entirely configured via YAML (menus/*.yml)
• Create, rename, and manage homes directly from the GUI
• MiniMessage color support throughout (no more § codes)
• Tab completion for homes, colors, and subcommands

Multi-Language & Localization

• Built-in languages: English, Italian, Spanish, French, German, Russian, Ukrainian
• Fully extensible lang system, drop in any new .yml file
• Auto-merge of new config/lang keys on plugin update (no more manual merging)
• All messages customizable via language files

Storage

• Multiple storage backends: YAML (flat-file), SQLite (embedded), MySQL/MariaDB (pooled)
• Automatic migration when switching between backends
• HikariCP connection pooling for SQL backends
• Atomic writes and safe concurrent data access

Permissions & Economy

• Granular permission nodes for every feature
• Vault economy integration (configurable teleport costs)
• Admin tools (delete any home, force-teleport players)
• Safe cost checks and error handling

Safety & Robustness

• Input validation on all player inputs
• Proper cleanup on logout/disconnect
• Retro-compatibility: old plugin data files are automatically detected and migrated
• Auto-merge of new keys when updating without breaking existing configs

---

!Installation

1. Download Homes-1.2.0.jar from Modrinth
2. Place it in your server's plugins/ folder
3. Restart your server
4. Configure storage backend and settings in plugins/Homes/config.yml
5. Customize GUIs in plugins/Homes/menus/*.yml
6. Customize messages in plugins/Homes/lang/*.yml

---

!Commands

/home                               View your homes (opens GUI)
/home set <name>                    Set a home at your current location
/home <name>                        Teleport to a home
/home info <name>                   View home information
/home remove <name>                 Delete a home
/home beacon <name> [color|off]     Toggle beacon or set color (13 colors)
/home share <name> <player>         Share a home with another player
/home unshare <name> <player>       Remove sharing from a home
/home admin delete <player> <name>  Delete any player's home (admin only)
/home admin tp <player> <home>      Force teleport a player to their home (admin only)
/home reload                        Reload config and language files (console & admin)

Classic aliases (configurable in config.yml)

/sethome [name] /delhome /listhomes

---

!Permissions

homes.use Base permission for the plugin homes.set Set homes homes.teleport Teleport to homes homes.remove Delete own homes homes.beacon Use beacon system homes.share Share homes with others homes.unshare Unshare homes homes.admin.delete Delete any player's home homes.admin.teleport Force-teleport players homes.admin.reload Reload configs (players and console) homes.bypass.cost Bypass teleport costs (Vault) homes.bypass.cooldown Bypass teleport cooldown

---

!Configuration

### Main Config (`config.yml`)

```yaml
# Storage Backend
storage:
  type: yaml            # Options: yaml | sqlite | mysql
  auto-migrate: true    # Automatically migrate data when switching backends

  # SQLite (used when type: sqlite)
  sqlite:
    file: homes.db

  # MySQL/MariaDB (used when type: mysql)
  mysql:
    host: localhost
    port: 3306
    database: homes
    username: root
    password: ""
    pool-size: 5

# Homes
max-homes: 10           # Maximum homes per player (-1 for unlimited)
max-name-length: 32     # Home name character limit

# Classic aliases
classic-commands:
  enabled: true
  sethome: true
  delhome: true
  listhomes: true

# Teleport System
teleport:
  warmup-seconds: 3
  cooldown-seconds: 30
  cancel-on-damage: true
  cancel-on-move: true

# Beacons
beacons:
  enabled: true
  beam-height: 256
  particle-size: 1.0
  refresh-ticks: 4

# Economy (Vault)
economy:
  enabled: false
  cost-per-teleport: 10.0

# Sounds
sounds:
  enabled: true
  teleport-start: ENTITY_ENDERMAN_TELEPORT
  teleport-end: ENTITY_GENERIC_EXPLODE
  beacon-color-change: ENTITY_EXPERIENCE_ORB_PICKUP

GUI Configuration (menus/homes.yml)

Fully customizable GUIs defined in simple YAML:

homes-gui:
  title: "<gold>✦ Your Homes ✦</gold>"
  rows: 5

  items:
    info-slot:
      slot: 0
      material: PAPER
      display-name: "<yellow>Home Info</yellow>"

---

!Reqs

• Server: Paper 1.21.11-R0.1 or compatible
• Java: 21 or higher
• Optional: Vault (for economy support)
• Optional: MySQL/MariaDB server (if using storage.type: mysql)

---

Upgrading from an older version

Homes automatically detects old plugin data and migrates it on first boot. Config and lang files are smart-merged, new keys added in updates are inserted automatically without overwriting your existing customizations. No manual config migration needed.

---