> ## 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.

# How to Install LiricHomes on Your Paper 1.21 Server

> Step-by-step guide to installing LiricHomes, satisfying the EssentialsX dependency, and verifying the plugin works correctly on first start.

Installing LiricHomes takes only a few minutes. The plugin generates all of its configuration files on first start, so the only thing you need to decide upfront is which storage backend to use. SQLite is the default and requires no extra database setup, making it ideal for getting started quickly.

## Requirements

| Requirement     | Version                                          |
| --------------- | ------------------------------------------------ |
| Paper (or fork) | 1.21                                             |
| Java            | 17 or newer                                      |
| EssentialsX     | Latest stable                                    |
| PlaceholderAPI  | Optional — enables `%lirichomes_*%` placeholders |

<Warning>
  EssentialsX is a **hard dependency**. LiricHomes will not load without it. Install EssentialsX before adding LiricHomes to your server.
</Warning>

## Installation Steps

<Steps>
  <Step title="Download LiricHomes">
    Grab the latest `LiricHomes-x.x.x.jar` from the official release page. Always download from the official source to ensure you get a build that matches this documentation.
  </Step>

  <Step title="Install EssentialsX">
    If EssentialsX is not already running on your server, download the `Essentials.jar` and `EssentialsXSpawn.jar` (recommended) from the EssentialsX releases page and drop them into your `plugins/` folder.

    <Note>
      LiricHomes declares EssentialsX as a hard dependency in `plugin.yml`. The server will refuse to enable LiricHomes if EssentialsX is absent or fails to load.
    </Note>
  </Step>

  <Step title="Add LiricHomes to your plugins folder">
    Copy the LiricHomes JAR into your server's `plugins/` directory:

    ```bash theme={null}
    cp LiricHomes-1.3.5.jar /your/server/plugins/
    ```

    Your `plugins/` folder should now contain both `Essentials.jar` and `LiricHomes-1.3.5.jar`.
  </Step>

  <Step title="Start or restart the server">
    Perform a full server restart (not `/reload`). On first start, LiricHomes creates the following files automatically:

    ```
    plugins/
    └── LiricHomes/
        ├── config.yml
        ├── messages.yml
        └── menus/
            └── homes.yml
    ```

    Check your console for a line confirming that LiricHomes has enabled successfully. If you see errors, verify that EssentialsX loaded without issues first.
  </Step>

  <Step title="Configure your storage type">
    Open `plugins/LiricHomes/config.yml`. The default storage type is `SQLITE`, which stores all data in `plugins/LiricHomes/database.db` — no additional setup required.

    If you prefer MySQL, MariaDB, or PostgreSQL, change the `type` field and fill in your connection details:

    ```yaml theme={null}
    storage:
      type: MYSQL          # MYSQL | MARIADB | POSTGRESQL | SQLITE | YAML
      host: "127.0.0.1"
      port: 3306
      database: "minecraft"
      username: "root"
      password: "yourpassword"
    ```

    <Note>
      SQLite is zero-setup and works perfectly for most servers. Switch to MySQL or MariaDB only if you need a shared database across multiple server instances or prefer a dedicated database server.
    </Note>

    After editing `config.yml`, restart the server or run `/adminhomes reload` to apply the changes.
  </Step>

  <Step title="Install PlaceholderAPI (optional)">
    If you want to display home counts and limits on scoreboards, tab headers, or holograms, install PlaceholderAPI and drop its JAR into your `plugins/` folder. LiricHomes automatically registers its placeholder expansion with PlaceholderAPI on startup — no eCloud download or manual registration step is needed.

    Once PlaceholderAPI is present, the `%lirichomes_count%`, `%lirichomes_max%`, and `%lirichomes_available%` placeholders will be available to any compatible plugin. See the [Placeholders](/homes/placeholders) page for full details.
  </Step>
</Steps>

## Verifying the Installation

After restarting, join the server and run `/homes`. You should see the homes GUI open — it will be empty for a new player. Use `/sethome <name>` (via EssentialsX) or the in-game GUI to create your first home, then open `/homes` again to confirm it appears.

<Tip>
  If the GUI does not open or you see a permission error, ensure your permissions plugin has granted `liric.homes.use` to players. This permission is set to `default: true` in `plugin.yml`, so it should work automatically unless your permissions plugin overrides defaults.
</Tip>