# 🔌 PlaceholderAPI Expansion

This expansion allows backend plugins such as scoreboards, tab plugins, menus, and holograms to display NexusProxy data.

{% hint style="warning" %}
The main NexusProxy plugin runs on Velocity.

The PlaceholderAPI expansion must be installed on backend Paper, Spigot, or Purpur servers.
{% endhint %}

***

### What It Does

The NexusProxy PlaceholderAPI expansion allows backend servers to access NexusProxy data through PlaceholderAPI.

It can be used to show:

* Real backend online count
* Global network online count
* Current proxy online count
* Specific backend server online count
* Specific proxy online count
* Friends total count
* Online friends count
* Offline friends count
* Pending friends count
* Friend limit

***

### When To Use It

Use the PlaceholderAPI expansion if you want to display NexusProxy placeholders in backend plugins.

Common use cases include:

* Lobby scoreboards
* TAB plugins
* Menus
* Holograms
* NPC displays
* Lobby information boards
* Friend count displays
* Network online count displays

{% hint style="info" %}
If you only need placeholders inside NexusProxy proxy-side messages, use the proxy-side Placeholders module instead.
{% endhint %}

***

### Requirements

| Dependency                          | Required                             | Where To Install                    |
| ----------------------------------- | ------------------------------------ | ----------------------------------- |
| NexusProxy                          | Yes                                  | Velocity proxy                      |
| PlaceholderAPI                      | Yes                                  | Backend server                      |
| NexusProxy PlaceholderAPI Expansion | Yes                                  | Backend server                      |
| Redis                               | Recommended                          | Velocity proxy and expansion config |
| MySQL or MongoDB                    | Recommended for friends placeholders | Velocity proxy and expansion config |

***

### Important Installation Rule

The expansion jar does not go inside the Velocity plugins folder.

Correct location:

```
backend-server/
└── plugins/
    └── PlaceholderAPI/
        └── expansions/
            └── expansion-nexusproxy.jar
```

Incorrect location:

```
velocity/
└── plugins/
    └── expansion-nexusproxy.jar
```

{% hint style="danger" %}
Do not install `expansion-nexusproxy.jar` on Velocity.

It must be installed inside the backend server's PlaceholderAPI expansions folder.
{% endhint %}

***

### Installation Steps

#### Step 1: Install PlaceholderAPI

Install PlaceholderAPI on the backend lobby server.

Download:

[PlaceholderAPI on Modrinth](https://modrinth.com/plugin/placeholderapi)

The backend server should have:

```
plugins/PlaceholderAPI/
```

***

#### Step 2: Install the NexusProxy expansion

Copy the NexusProxy expansion jar to:

```
plugins/PlaceholderAPI/expansions/
```

Example:

```
plugins/
└── PlaceholderAPI/
    └── expansions/
        └── expansion-nexusproxy.jar
```

***

#### Step 3: Start the backend server

Start or restart the backend server.

You can also reload PlaceholderAPI with:

```
/papi reload
```

***

#### Step 4: Configure the expansion

After the expansion loads, configure:

```
plugins/PlaceholderAPI/expansions/NexusProxy/config.yml
```

This file must use the same Redis and database settings as NexusProxy.

{% hint style="warning" %}
If the expansion uses different Redis or database settings, placeholders may return `0` or incorrect values.
{% endhint %}

***

### Redis Configuration

Redis is recommended for online count placeholders.

The expansion should use the same Redis settings as NexusProxy.

Velocity NexusProxy example:

```yaml
storage:
  redis:
    enabled: true
    host: "127.0.0.1"
    port: 6379
    password: ""
    database: 0
    channel_prefix: "nexusproxy"
```

PlaceholderAPI expansion example:

```yaml
redis:
  enabled: true
  host: "127.0.0.1"
  port: 6379
  password: ""
  database: 0
  channel_prefix: "nexusproxy"
```

{% hint style="info" %}
The Redis `channel_prefix` must match between NexusProxy and the PlaceholderAPI expansion.
{% endhint %}

***

### Database Configuration

Database storage is recommended for friends placeholders.

The expansion should use the same database settings as NexusProxy.

Velocity NexusProxy MySQL example:

```yaml
storage:
  database:
    type: "mysql"
    mysql:
      host: "127.0.0.1"
      port: 3306
      database: "nexusproxy"
      username: "root"
      password: "password"
      use_ssl: false
      allow_public_key_retrieval: true
```

PlaceholderAPI expansion MySQL example:

```yaml
database:
  type: "mysql"
  mysql:
    host: "127.0.0.1"
    port: 3306
    database: "nexusproxy"
    username: "root"
    password: "password"
    use_ssl: false
    allow_public_key_retrieval: true
```

***

### Available Placeholders

| Placeholder                           | Description                                                                                             |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `%nexusproxy_real_online%`            | Shows real online players on the current backend server.                                                |
| `%nexusproxy_global_online%`          | Shows the global network online count known by NexusProxy through Redis presence snapshots.             |
| `%nexusproxy_proxy_online%`           | Shows players on the source player's current proxy.                                                     |
| `%nexusproxy_server_<server>_online%` | Shows players on a specific backend server.                                                             |
| `%nexusproxy_proxy_<proxy>_online%`   | Shows players on a specific proxy ID.                                                                   |
| `%nexusproxy_friends_total%`          | Shows the player's total friends from the shared database.                                              |
| `%nexusproxy_friends_online%`         | Shows online friends according to Redis presence.                                                       |
| `%nexusproxy_friends_offline%`        | Shows total friends minus online friends.                                                               |
| `%nexusproxy_friends_pending%`        | Shows pending friend requests. Currently returns `0` because pending requests are kept in proxy memory. |
| `%nexusproxy_friends_limit%`          | Shows the player's friend limit based on expansion config permissions.                                  |

***

### Online Placeholder Examples

#### Real backend online

```
%nexusproxy_real_online%
```

Example usage:

```
Players on this server: %nexusproxy_real_online%
```

***

#### Global network online

```
%nexusproxy_global_online%
```

Example usage:

```
Network online: %nexusproxy_global_online%
```

***

#### Current proxy online

```
%nexusproxy_proxy_online%
```

Example usage:

```
Proxy online: %nexusproxy_proxy_online%
```

***

#### Specific backend server online

```
%nexusproxy_server_<server>_online%
```

Example:

```
%nexusproxy_server_lobby_online%
```

Example usage:

```
Lobby online: %nexusproxy_server_lobby_online%
```

{% hint style="warning" %}
The server name must match the backend server name configured in Velocity.
{% endhint %}

***

#### Specific proxy online

```
%nexusproxy_proxy_<proxy>_online%
```

Example:

```
%nexusproxy_proxy_Proxy-1_online%
```

Example usage:

```
Proxy-1 online: %nexusproxy_proxy_Proxy-1_online%
```

{% hint style="warning" %}
The proxy name must match the `cluster.proxy_id` configured in `nexusproxy.yml`.
{% endhint %}

***

### Friends Placeholder Examples

#### Total friends

```
%nexusproxy_friends_total%
```

Example usage:

```
Friends: %nexusproxy_friends_total%
```

***

#### Online friends

```
%nexusproxy_friends_online%
```

Example usage:

```
Online friends: %nexusproxy_friends_online%
```

***

#### Offline friends

```
%nexusproxy_friends_offline%
```

Example usage:

```
Offline friends: %nexusproxy_friends_offline%
```

***

#### Pending friend requests

```
%nexusproxy_friends_pending%
```

{% hint style="info" %}
This placeholder currently returns `0` because pending friend requests are stored in proxy memory.
{% endhint %}

***

#### Friend limit

```
%nexusproxy_friends_limit%
```

Example usage:

```
Friends: %nexusproxy_friends_total%/%nexusproxy_friends_limit%
```

***

### Example Scoreboard Usage

Example scoreboard lines:

```yaml
lines:
  - "&6&lNexus Network"
  - ""
  - "&fOnline: &e%nexusproxy_global_online%"
  - "&fLobby: &a%nexusproxy_server_lobby_online%"
  - ""
  - "&fFriends: &b%nexusproxy_friends_online%&7/&b%nexusproxy_friends_total%"
  - ""
  - "&estore.example.net"
```

***

### Example TAB Usage

Example TAB placeholder usage:

```yaml
header:
  - "&6&lNexus Network"
  - "&fOnline: &e%nexusproxy_global_online%"

footer:
  - "&fFriends Online: &b%nexusproxy_friends_online%"
  - "&7play.example.net"
```

***

### PlaceholderAPI Reload

After installing or editing the expansion configuration, reload PlaceholderAPI:

```
/papi reload
```

If placeholders still do not update correctly, restart the backend server.

***

### Testing Placeholders

You can test PlaceholderAPI placeholders on the backend server with PlaceholderAPI commands.

Example:

```
/papi parse me %nexusproxy_global_online%
```

Example:

```
/papi parse me %nexusproxy_friends_total%
```

{% hint style="info" %}
Run PlaceholderAPI test commands from the backend server where the expansion is installed.
{% endhint %}

***

### Common Issues

#### Placeholder returns 0

Check that:

* The expansion is installed on the backend server.
* PlaceholderAPI is installed on the backend server.
* The expansion jar is inside `plugins/PlaceholderAPI/expansions/`.
* The backend server was restarted or `/papi reload` was executed.
* Redis settings match NexusProxy.
* Database settings match NexusProxy if using friends placeholders.
* The required NexusProxy module is enabled.

***

#### Global online returns 0

Check that:

* Redis is enabled in NexusProxy.
* Redis is enabled in the expansion config.
* Both use the same host, port, password, database, and channel prefix.
* Every Velocity proxy has a unique `cluster.proxy_id`.
* `/nexusproxy storage` shows Redis as connected.

***

#### Server online placeholder returns 0

Check that:

* The backend server name is typed correctly.
* The server name matches Velocity exactly.
* Redis is configured correctly.
* Players are actually connected to that backend server.
* The placeholder format is correct.

Example:

```
%nexusproxy_server_lobby_online%
```

***

#### Proxy online placeholder returns 0

Check that:

* The proxy ID is typed correctly.
* The proxy ID matches `cluster.proxy_id`.
* Redis is enabled and connected.
* The target proxy is online.
* The expansion uses the same Redis channel prefix.

Example:

```
%nexusproxy_proxy_Proxy-1_online%
```

***

#### Friends placeholders return 0

Check that:

* The Friends module is enabled.
* Database storage is enabled in NexusProxy.
* The expansion uses the same database settings.
* Friend data exists in the database.
* Redis is enabled if checking online friends.
* The player actually has friends.

***

#### PlaceholderAPI does not detect the expansion

Check that:

* `expansion-nexusproxy.jar` is inside `plugins/PlaceholderAPI/expansions/`.
* PlaceholderAPI is installed correctly.
* The backend server was restarted.
* `/papi reload` was executed.
* The expansion jar is not inside the Velocity plugins folder.

***

#### Placeholder works on one lobby but not another

Check that:

* The expansion is installed on every backend lobby server that needs it.
* Every backend lobby has PlaceholderAPI installed.
* Every expansion config uses the same Redis and database settings.
* Every backend server was restarted or PlaceholderAPI was reloaded.

***

### Setup Tips

* Install the expansion only on backend servers.
* Do not install the expansion on Velocity.
* Use the same Redis settings as NexusProxy.
* Use the same database settings as NexusProxy for friends placeholders.
* Use exact Velocity server names in server placeholders.
* Use exact `cluster.proxy_id` values in proxy placeholders.
* Restart the backend server after installing the expansion.
* Use `/papi parse me <placeholder>` to test values.
* Use `/nexusproxy storage` on Velocity to confirm Redis and database status.

***

### Summary

The PlaceholderAPI expansion allows backend lobby plugins to display NexusProxy data.

It is recommended for scoreboards, TAB plugins, menus, holograms, and other backend systems that need network online counts, proxy counts, server counts, or friends data.


---

# 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://nexusproxy.nemesismc.net/placeholderapi-expansion.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.