> ## Documentation Index
> Fetch the complete documentation index at: https://pumpkings.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# LiricHomes: GUI-Based Home Management for Paper 1.21

> LiricHomes brings a visual inventory GUI to EssentialsX home management on Paper 1.21, with SQL or flat-file storage and automated backups.

LiricHomes is an advanced, zero-hardcode home management plugin built for Paper 1.21 servers. It wraps EssentialsX's home system with a fully interactive inventory GUI, giving your players a visual way to teleport, manage, and personalise their homes — all without typing a single command beyond `/homes`. Every menu is defined in YAML, so you can tailor the look and feel without touching any code.

## Key Features

<CardGroup cols={2}>
  <Card title="Inventory GUI" icon="house">
    Every home appears as a player head or custom icon inside a paginated chest GUI. Players teleport, delete, and configure homes directly from the menu — no extra commands required.
  </Card>

  <Card title="Per-Rank Home Limits" icon="layer-group">
    Assign home limits through permission nodes such as `liric.homes.vip.5`. The plugin automatically picks the highest limit a player holds, with a configurable server-wide default as the fallback.
  </Card>

  <Card title="Flexible Storage" icon="database">
    Choose from MySQL, MariaDB, PostgreSQL, SQLite, or YAML flat-file storage. SQLite works out of the box with zero setup, while SQL backends are available for servers that need a shared or centralised database.
  </Card>

  <Card title="Automated Backups" icon="clock-rotate-left">
    The built-in backup system creates snapshots on a configurable interval and automatically removes the oldest backup once the maximum count is reached — your data stays safe without manual effort.
  </Card>

  <Card title="Admin GUI" icon="shield-halved">
    Server administrators can open a global home database GUI via `/adminhomes`, browse every player's homes with pagination, and manage or delete entries in real time.
  </Card>

  <Card title="PlaceholderAPI Support" icon="tag">
    Three ready-made `%lirichomes_*%` placeholders expose home counts, limits, and available slots to scoreboards, tab headers, holograms, and any other PlaceholderAPI-compatible plugin.
  </Card>

  <Card title="EssentialsX Integration" icon="link">
    LiricHomes listens to EssentialsX home events, so homes created or deleted with `/sethome` and `/delhome` are reflected in the LiricHomes database instantly and automatically.
  </Card>

  <Card title="Data Migration" icon="arrow-right-arrow-left">
    The built-in migration command imports all existing homes from EssentialsX into LiricHomes' own storage in one step, making it easy to switch backends without losing player data.
  </Card>
</CardGroup>

## GUI Interaction Reference

Inside the homes GUI, every home icon responds to multiple click types so players can do everything without leaving the menu:

| Interaction         | Action                                                  |
| ------------------- | ------------------------------------------------------- |
| Left Click          | Teleport to the home                                    |
| Shift + Left Click  | Delete the home (confirmation required)                 |
| Middle Click        | Set the home icon to the item you are holding           |
| Shift + Right Click | Open per-home settings (rename, display name, relocate) |

<Tip>
  Middle Click to change a home's icon requires the `liric.homes.icon` permission, which is granted to all players by default.
</Tip>

## Version

LiricHomes **1.3.5** targets Paper **1.21** and requires **Java 17** or newer. EssentialsX is a hard dependency; PlaceholderAPI is optional but recommended for scoreboards and holograms.