# PlaceholderAPI

{% hint style="info" %}
All text between the less-than and greater-than signs (**<>**) is a placeholder/variable, replace it with the requested value without the less-than and greater-than signs (**<>**).
{% endhint %}

## What's PlaceholderAPI?

[**PlaceholderAPI**](https://www.spigotmc.org/resources/6245/) is a popular plugin that allows plugins to communicate via placeholders. Every plugin that supports it can use placeholders from other plugins, and it includes a built-in system to download placeholder expansions from [**eCloud**](https://api.extendedclip.com/home/).

## Installation

The expansion is built into **zHomes** itself. As long as you have PlaceholderAPI installed, the placeholder expansion will automatically register—no need to download anything from eCloud.

## Placeholder Syntax

PlaceholderAPI uses the `%identifier_key_args%` format. Arguments are separated by underscores (`_`).

### Standard Placeholders

These placeholders use the viewing/command-executing player as context.

| Placeholder                    | Description                                       | Output Example        |
| ------------------------------ | ------------------------------------------------- | --------------------- |
| `%zhomes_version%`             | Returns the current version of zHomes             | `1.0.0`               |
| `%zhomes_hashome_<home>`       | Check if the player has a home with name `<home>` | `True` \| `False`     |
| `%zhomes_set%`                 | Number of homes the player has                    | `10`                  |
| `%zhomes_numberofhomes%`       | Number of homes the player has (alias)            | `10`                  |
| `%zhomes_homes%`               | All homes the player has                          | `home1, home2, home3` |
| `%zhomes_limit%`               | The limit of homes the player can have            | `15`                  |
| `%zhomes_max%`                 | The limit of homes the player can have (alias)    | `15`                  |
| `%zhomes_set/max%`             | Homes set vs limit, or "Disabled" if no limit     | `10/15` \| `Disabled` |
| `%zhomes_numberofhomes/limit%` | Homes set vs limit (alias)                        | `10/15` \| `Disabled` |

### Home-Specific Placeholders

These placeholders retrieve information about a specific home by index number (1-based).

| Placeholder                               | Description                                   | Output Example  |
| ----------------------------------------- | --------------------------------------------- | --------------- |
| `%zhomes_home_<number>%`                  | Name of the player's home at index `<number>` | `home1`         |
| `%zhomes_home_<number>_world%`            | World name of the home                        | `world_the_end` |
| `%zhomes_home_<number>_x%`                | X coordinate (rounded)                        | `123`           |
| `%zhomes_home_<number>_y%`                | Y coordinate (rounded)                        | `64`            |
| `%zhomes_home_<number>_z%`                | Z coordinate (rounded)                        | `-456`          |
| `%zhomes_home_<number>_pitch%`            | Pitch (rounded)                               | `15`            |
| `%zhomes_home_<number>_yaw%`              | Yaw (rounded)                                 | `90`            |
| `%zhomes_home_<number>_x_full%`           | X coordinate (full precision)                 | `123.456789`    |
| `%zhomes_home_<number>_y_full%`           | Y coordinate (full precision)                 | `64.000000`     |
| `%zhomes_home_<number>_z_full%`           | Z coordinate (full precision)                 | `-456.123456`   |
| `%zhomes_home_<number>_pitch_full%`       | Pitch (full precision)                        | `15.234567`     |
| `%zhomes_home_<number>_yaw_full%`         | Yaw (full precision)                          | `90.123456`     |
| `%zhomes_home_<number>_x_<decimals>%`     | X coordinate with `<decimals>` decimal places | `123.45`        |
| `%zhomes_home_<number>_y_<decimals>%`     | Y coordinate with `<decimals>` decimal places | `64.00`         |
| `%zhomes_home_<number>_z_<decimals>%`     | Z coordinate with `<decimals>` decimal places | `-456.12`       |
| `%zhomes_home_<number>_pitch_<decimals>%` | Pitch with `<decimals>` decimal places        | `15.23`         |
| `%zhomes_home_<number>_yaw_<decimals>%`   | Yaw with `<decimals>` decimal places          | `90.12`         |

### Player-Targeted Placeholders

These placeholders let you query information about a **different player** by specifying their name.

Use the format: `%zhomes_player_<playername>_<key>_<args>%`

| Placeholder                                  | Description                                  | Output Example      |
| -------------------------------------------- | -------------------------------------------- | ------------------- |
| `%zhomes_player_<name>_hashome_<home>%`      | Check if `<name>` has a home called `<home>` | `True` \| `False`   |
| `%zhomes_player_<name>_set%`                 | Number of homes `<name>` has                 | `5`                 |
| `%zhomes_player_<name>_homes%`               | All homes `<name>` has                       | `spawn, base, farm` |
| `%zhomes_player_<name>_home_<number>%`       | Name of `<name>`'s home at index `<number>`  | `spawn`             |
| `%zhomes_player_<name>_home_<number>_world%` | World of `<name>`'s home                     | `world`             |
| `%zhomes_player_<name>_home_<number>_x%`     | X coordinate of `<name>`'s home              | `100`               |

**Example:**

```
%zhomes_player_Steve_home_1%           → Steve's first home name
%zhomes_player_Alex_set%               → Number of homes Alex has
%zhomes_player_Notch_home_2_world%     → World of Notch's second home
```

## Notes

{% hint style="success" %}
Even without PlaceholderAPI installed, all placeholders still work inside zHomes' own configuration files.
{% endhint %}

{% hint style="info" %}
For MiniMessage/MiniPlaceholders support, see the [MiniPlaceholders](/zhomes/hooks/miniplaceholders.md) page.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.yleoft.me/zhomes/hooks/placeholderapi.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.