> ## 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 PlaceholderAPI Variables for Scoreboards

> Reference for the three %lirichomes_*% PlaceholderAPI placeholders — count, max, and available — and how to use them in scoreboards and holograms.

LiricHomes registers three PlaceholderAPI placeholders that expose real-time home data for the requesting player. You can drop these variables into any PlaceholderAPI-compatible plugin — scoreboards, tab list headers and footers, holograms, action bars, chat formats, and progress bar plugins — without any additional configuration beyond installing PlaceholderAPI.

## Requirements

PlaceholderAPI is a **soft dependency** for LiricHomes, meaning the plugin loads successfully with or without it. Placeholders are only registered and functional when PlaceholderAPI is present on the server.

<Note>
  If you add PlaceholderAPI after LiricHomes is already running, perform a full server restart to ensure the expansion registers correctly. A hot `/papi reload` alone may not be sufficient.
</Note>

## Available Placeholders

| Placeholder              | Returns | Description                                                                              |
| ------------------------ | ------- | ---------------------------------------------------------------------------------------- |
| `%lirichomes_count%`     | Integer | The number of homes the player currently has saved.                                      |
| `%lirichomes_max%`       | Integer | The maximum number of homes the player is allowed to create, based on their permissions. |
| `%lirichomes_available%` | Integer | The number of remaining home slots the player can still create (`max` minus `count`).    |

### `%lirichomes_count%`

Returns the total number of homes the player has created. This number increases when a player sets a new home and decreases when one is deleted.

**Example output:** `3`

### `%lirichomes_max%`

Returns the player's current home limit. The value reflects the permission priority chain — `liric.homes.bypass` returns the server's unlimited cap, `liric.homes.vip.<N>` returns `N` for the highest held tier, and players with no VIP node receive the `default-home-limit` from `config.yml`.

**Example output:** `10`

### `%lirichomes_available%`

Returns the number of additional homes the player can still create. This is a simple computed value: `max - count`. It is useful for displaying remaining capacity in a progress bar or a heads-up display.

**Example output:** `7`

## Use Cases

<CardGroup cols={2}>
  <Card title="Scoreboard" icon="ranking-star">
    Show each player their current homes and remaining slots directly on the sidebar scoreboard using a plugin like FeatherBoard or CMI.
  </Card>

  <Card title="Tab Header / Footer" icon="table-list">
    Display server-wide home statistics in the tab list header or footer with TAB or a similar tab plugin.
  </Card>

  <Card title="Holograms" icon="circle-info">
    Place a hologram near a spawn portal showing `Homes: %lirichomes_count% / %lirichomes_max%` using DecentHolograms or HolographicDisplays.
  </Card>

  <Card title="Progress Bars" icon="chart-bar">
    Use a progress bar plugin to render a visual fill based on `%lirichomes_count%` out of `%lirichomes_max%`, giving players an at-a-glance view of their home capacity.
  </Card>
</CardGroup>

## Example Scoreboard Lines

The following lines show how you might wire the placeholders into a typical scoreboard configuration:

```yaml theme={null}
# Example scoreboard lines (plugin-agnostic syntax)
lines:
  - "&6&lHomes"
  - "&eUsed: &f%lirichomes_count% &7/ &f%lirichomes_max%"
  - "&aAvailable: &f%lirichomes_available%"
```

## Real-Time Updates

All three placeholders update in real time. When a player creates or deletes a home, the next time the scoreboard or hologram refreshes it will reflect the new values automatically. You do not need to restart the server, run `/adminhomes reload`, or issue any other command after changing a player's home limit — the change is picked up on the next placeholder evaluation.

<Tip>
  Placeholder values are kept up to date automatically. When a player creates or deletes a home, or when their permissions change, the next evaluation of any `%lirichomes_*%` placeholder will reflect the latest state — no server restart or reload required.
</Tip>