mirror of
https://github.com/PlaceholderAPI/PlaceholderAPI
synced 2026-02-05 11:57:14 +01:00
Update Info
This commit is contained in:
Andre601
@@ -4,6 +4,13 @@ description: Comprehensive guide on how to create a PlaceholderExpansion for oth
|
||||
|
||||
# Creating a PlaceholderExpansion
|
||||
|
||||
/// warning | Important
|
||||
These pages cover the creation of a PlaceholderExpansion for both Spigot/Paper-based and Hytale Servers!
|
||||
|
||||
Unless mentioned otherwise the provided code examples function for both platform types.
|
||||
Please always check code blocks for :material-plus-circle: Icons with additional info!
|
||||
///
|
||||
|
||||
This page will cover how you can create your own [`PlaceholderExpansion`][placeholderexpansion] which you can either integrate into your own plugin (Recommended) or [upload to the eCloud](expansion-cloud.md).
|
||||
|
||||
It's worth noting that PlaceholderAPI relies on expansions being installed. PlaceholderAPI only acts as the core replacing utility while the expansions allow other plugins to use any installed placeholder in their own messages.
|
||||
@@ -74,6 +81,11 @@ public class SomeExpansion extends PlaceholderExpansion {
|
||||
public String onPlaceholderRequest(Player player, @NotNull String params) {
|
||||
// (5)
|
||||
}
|
||||
|
||||
@Override
|
||||
public String onPlaceholderRequest(PlayerRef player, @NotNull String params) {
|
||||
// (6)
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -108,6 +120,16 @@ public class SomeExpansion extends PlaceholderExpansion {
|
||||
- `player` - Nullable Player instance to parse placeholders against.
|
||||
- `params` - Non-null String representing the part of the placeholder after the first `_` and before the closing `%` (or `}` for bracket placeholders).
|
||||
|
||||
6. **Note:** Only exists for the Hytale Version of PlaceholderAPI!
|
||||
|
||||
Called by PlaceholderAPI through `onPlaceholderRequest(PlayerRef, String)` to have placeholder values parsed.
|
||||
When `null` is returned will PlaceholderAPI treat it as invalid placeholder and return it unchanged.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
- `player` - PlayerRef instance to parse placeholders against.
|
||||
- `params` - Non-null String representing the part of the placeholder after the first `_` and before the closing `%` (or `}` for bracket placeholders).
|
||||
|
||||
/// note
|
||||
Overriding `onRequest(OfflinePlayer, String)` or `onPlaceholderRequest(Player, String)` is not required if you [create relational placeholders](#making-a-relational-expansion).
|
||||
///
|
||||
@@ -133,16 +155,18 @@ You are also required to override and set `persist()` to `true`. This tells Plac
|
||||
attrs: { id: full-example-internal }
|
||||
type: example
|
||||
|
||||
//// note |
|
||||
Please see the [Basic PlaceholderExpansion Structure](#basic-placeholderexpansion-structure) section for an explanation of all common methods in this example.
|
||||
//// note | Important Notes
|
||||
- Please see the [Basic PlaceholderExpansion Structure](#basic-placeholderexpansion-structure) section for an explanation of all common methods in this example.
|
||||
- The below example is for a Spigot/Paper-based setup.
|
||||
For a Hytale server, replace `me.clip` imports with `at.helpch` and replace `OfflinePlayer` with `PlayerRef` (Including the import).
|
||||
|
||||
Tab the :material-plus-circle: icons in the code block below for additional information.
|
||||
////
|
||||
|
||||
```java { .annotate title="SomeExpansion.java" }
|
||||
package at.helpch.placeholderapi.example.expansion;
|
||||
package com.example.plugin.expansion;
|
||||
|
||||
import at.helpch.placeholderapi.example.SomePlugin;
|
||||
import com.example.plugin.SomePlugin;
|
||||
import me.clip.placeholderapi.expansion.PlaceholderExpansion;
|
||||
import org.bukkit.OfflinePlayer;
|
||||
import org.jetbrains.annotations.NotNull;
|
||||
@@ -206,19 +230,20 @@ public class SomeExpansion extends PlaceholderExpansion {
|
||||
6. Example of accessing data of the plugin's `config.yml` file.
|
||||
|
||||
7. Reaching this means that an invalid params String was given, so we return `null` to tell PlaceholderAPI that the placeholder was invalid.
|
||||
|
||||
///
|
||||
|
||||
### Register your Expansion
|
||||
|
||||
Due to the PlaceholderExpansion being internal, PlaceholderAPI does not load it automatically, we'll need to do it manually.
|
||||
This is being done by creating a new instance of your PlaceholderExpansion class and calling the `register()` method of it.
|
||||
This is being done by creating a new instance of your PlaceholderExpansion class and calling the `register()` method of it:
|
||||
|
||||
Here is a quick example:
|
||||
/// tab | Spigot, Paper, ...
|
||||
|
||||
```java { .annotate title="SomePlugin.java" }
|
||||
package at.helpch.placeholderapi.example;
|
||||
package com.example.plugin;
|
||||
|
||||
import at.helpch.placeholderapi.example.expansion.SomeExpansion;
|
||||
import com.example.plugin.expansion.SomeExpansion;
|
||||
import org.bukkit.Bukkit;
|
||||
import org.bukkit.plugin.java.JavaPlugin;
|
||||
|
||||
@@ -238,6 +263,29 @@ public class SomePlugin extends JavaPlugin {
|
||||
|
||||
2. This registers our expansion in PlaceholderAPI. It also gives the Plugin class as dependency injection to the Expansion class, so that we can use it.
|
||||
|
||||
///
|
||||
|
||||
/// tab | Hytale
|
||||
|
||||
```java { .annotate title="SomePlugin.java" }
|
||||
package com.example.plugin;
|
||||
|
||||
import com.example.plugin.expansion.SomeExpansion;
|
||||
import com.hypixel.hytale.server.core.plugin.JavaPlugin;
|
||||
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;
|
||||
|
||||
public class SomePlugin extends JavaPlugin {
|
||||
|
||||
public SomePlugin(JavaPluginInit init) {
|
||||
super(init)
|
||||
}
|
||||
|
||||
// TODO: Example of checking for PAPI and registering expansion
|
||||
}
|
||||
```
|
||||
|
||||
///
|
||||
|
||||
----
|
||||
|
||||
## Making an External Expansion
|
||||
@@ -257,8 +305,10 @@ Downsides include a more tedious setup in terms of checking for a required plugi
|
||||
attrs: { id: full-example-external-no-dependency }
|
||||
type: example
|
||||
|
||||
//// note |
|
||||
Please see the [Basic PlaceholderExpansion Structure](#basic-placeholderexpansion-structure) section for an explanation of all common methods in this example.
|
||||
//// note | Important Notes
|
||||
- Please see the [Basic PlaceholderExpansion Structure](#basic-placeholderexpansion-structure) section for an explanation of all common methods in this example.
|
||||
- The below example is for a Spigot/Paper-based setup.
|
||||
For a Hytale server, replace `me.clip` imports with `at.helpch` and replace `OfflinePlayer` with `PlayerRef` (Including the import).
|
||||
|
||||
Tab the :material-plus-circle: icons in the code block below for additional information.
|
||||
////
|
||||
@@ -266,7 +316,7 @@ Tab the :material-plus-circle: icons in the code block below for additional info
|
||||
This is an example expansion without any plugin dependency.
|
||||
|
||||
```java { .annotate title="SomeExpansion.java" }
|
||||
package at.helpch.placeholderapi.example.expansion;
|
||||
package com.example.expansion;
|
||||
|
||||
import me.clip.placeholderapi.expansion.PlaceholderExpansion;
|
||||
import org.bukkit.OfflinePlayer;
|
||||
@@ -314,8 +364,10 @@ public class SomeExpansion extends PlaceholderExpansion {
|
||||
attrs: { id: full-example-external-dependency }
|
||||
type: example
|
||||
|
||||
//// note |
|
||||
Please see the [Basic PlaceholderExpansion Structure](#basic-placeholderexpansion-structure) section for an explanation of all common methods in this example.
|
||||
//// note | Important Notes
|
||||
- Please see the [Basic PlaceholderExpansion Structure](#basic-placeholderexpansion-structure) section for an explanation of all common methods in this example.
|
||||
- The below example is for a Spigot/Paper-based setup.
|
||||
For a Hytale server, replace `me.clip` imports with `at.helpch` and replace `OfflinePlayer` with `PlayerRef` (Including the import).
|
||||
|
||||
Tab the :material-plus-circle: icons in the code block below for additional information.
|
||||
////
|
||||
@@ -323,9 +375,9 @@ Tab the :material-plus-circle: icons in the code block below for additional info
|
||||
This is an example expansion with a plugin dependency.
|
||||
|
||||
```java { .annotate title="SomeExpansion.java" }
|
||||
package at.helpch.placeholderapi.example.expansion;
|
||||
package com.example.expansion;
|
||||
|
||||
import at.helpch.placeholderapi.example.SomePlugin;
|
||||
import com.example.plugin.SomePlugin;
|
||||
import me.clip.placeholderapi.expansion.PlaceholderExpansion;
|
||||
import org.bukkit.Bukkit;
|
||||
import org.bukkit.OfflinePlayer;
|
||||
@@ -383,7 +435,9 @@ public class SomeExpansion extends PlaceholderExpansion {
|
||||
2. The name of the plugin this expansion depends on.
|
||||
It is recommended to set this, as it would result in PlaceholderAPI reporting any missing plugin for your expansion.
|
||||
|
||||
3. This does two things:
|
||||
3. **Note:** This only works on a Spigot/Paper-based server. A equivalent for Hytale servers is not yet known.
|
||||
|
||||
This does two things:
|
||||
|
||||
1. It sets the `plugin` instance to `SomePlugin` using Bukkit's PluginManager to retrieve a JavaPlugin instance that is cast to `SomePlugin`.
|
||||
2. It checks if the retrieved instance is not null. If it is will this result in `canRegister()` returning false, resulting in PlaceholderAPI not loading our expansion.
|
||||
@@ -399,8 +453,9 @@ public class SomeExpansion extends PlaceholderExpansion {
|
||||
|
||||
## Making a relational Expansion
|
||||
|
||||
/// note
|
||||
Relational Placeholders always start with `rel_` to properly identify them. This means that if you make a relational placeholder called `friends_is_friend` would the full placeholder be `%rel_friends_is_friend%`.
|
||||
/// note | Notes
|
||||
- Relational Placeholders always start with `rel_` to properly identify them. This means that if you make a relational placeholder called `friends_is_friend` would the full placeholder be `%rel_friends_is_friend%`.
|
||||
- For Hytale, replace any mention of `Player` with `PlayerRef` and update any Imports in the code to `at.helpch` and related Hytale ones.
|
||||
///
|
||||
|
||||
Relational PlaceholderExpansions are special in that they take two players as input, allowing you to give outputs based on their relation to each other.
|
||||
|
||||
@@ -6,42 +6,43 @@ description: Guide on how to use PlaceholderAPI in your own plugin.
|
||||
|
||||
This page is about using PlaceholderAPI in your own plugin, to either let other plugins use your plugin, or just use placeholders from other plugins in your own.
|
||||
|
||||
Please note, that the examples in this page are only available for **PlaceholderAPI 2.10.0 or higher**!
|
||||
Please note, that the examples in this page are only available for **PlaceholderAPI 2.10.0 (1.0.0 for Hytale version) or newer**!
|
||||
|
||||
## First steps
|
||||
|
||||
### Add PlaceholderAPI to your Project
|
||||
|
||||
Before you can actually make use of PlaceholderAPI, you first have to import it into your project.
|
||||
Use the below code example matching your dependency manager.
|
||||
Use the below code example matching your project type and dependency manager.
|
||||
|
||||
/// tab | :simple-apachemaven: Maven
|
||||
```{ .xml .annotate title="pom.xml" data-md-component="api-version" }
|
||||
/// tab | Minecraft (Spigot, Paper, ...)
|
||||
//// tab | :simple-apachemaven: Maven
|
||||
```{ .xml title="pom.xml" data-md-component="api-version" }
|
||||
<repositories>
|
||||
<repository>
|
||||
<id>placeholderapi</id>
|
||||
<url>https://repo.extendedclip.com/releases/</url>
|
||||
<url>https://repo.helpch.at/releases/</url>
|
||||
</repository>
|
||||
</repositories>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>me.clip</groupId>
|
||||
<artifactId>placeholderapi</artifactId>
|
||||
<version>{version}</version>
|
||||
<version>{papiVersion}</version>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
|
||||
<!-- Optional: Component support on Paper Servers (Since TBD) -->
|
||||
<!-- Optional: Component support on Paper Servers (Since 2.12.0) -->
|
||||
<dependency>
|
||||
<groupId>me.clip</groupId>
|
||||
<artifactId>placeholderapi-paper</artifactId>
|
||||
<version>{version}</version>
|
||||
<version>{papiVersion}</version>
|
||||
<scope>provided</scope>
|
||||
</dependencies>
|
||||
```
|
||||
///
|
||||
////
|
||||
|
||||
/// tab | :simple-gradle: Gradle
|
||||
//// tab | :simple-gradle: Gradle
|
||||
```{ .groovy title="build.gradle" data-md-component="api-version" }
|
||||
repositories {
|
||||
maven {
|
||||
@@ -50,18 +51,68 @@ repositories {
|
||||
}
|
||||
|
||||
dependencies {
|
||||
compileOnly 'me.clip:placeholderapi:{version}'
|
||||
compileOnly 'me.clip:placeholderapi:{papiVersion}'
|
||||
|
||||
// Optional: Component support on Paper Servers (Since TBD)
|
||||
compileOnly 'me.clip:placeholderapi-paper:{version}'
|
||||
// Optional: Component support on Paper Servers (Since 2.12.0)
|
||||
compileOnly 'me.clip:placeholderapi-paper:{papiVersion}'
|
||||
}
|
||||
```
|
||||
////
|
||||
///
|
||||
|
||||
/// details | What is `{version}`?
|
||||
/// tab | Hytale
|
||||
//// tab | :simple-apachemaven: Maven
|
||||
```{ .xml title="pom.xml" data-md-component="api-version" }
|
||||
<repositories>
|
||||
<repository>
|
||||
<id>hytale</id>
|
||||
<url>https://repo.codemc.io/repository/hytale/</url>
|
||||
</repository>
|
||||
<repository>
|
||||
<id>placeholderapi</id>
|
||||
<url>https://repo.helpch.at/releases/</url>
|
||||
</repository>
|
||||
</repositories>
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<!-- Replace {hytaleVersion} with the version you need -->
|
||||
<groupId>com.hypixel.hytale</groupId>
|
||||
<artifactId>Server</artifactId>
|
||||
<version>{hytaleVersion}</version>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>at.helpch</groupId>
|
||||
<artifactId>placeholderapi-hytale</artifactId>
|
||||
<version>{papiHytaleVersion}</version>
|
||||
<scope>provided</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
```
|
||||
////
|
||||
|
||||
//// tab | :simple-gradle: Gradle
|
||||
```{ .groovy title="build.gradle" data-md-component="api-version" }
|
||||
repositories {
|
||||
maven {
|
||||
url = 'https://repo.codemc.io/repository/hytale/'
|
||||
url = 'https://repo.helpch.at/releases/'
|
||||
}
|
||||
}
|
||||
|
||||
dependencies {
|
||||
// Replace {hytaleVersion} with the version you need.
|
||||
compileOnly 'com.hypixel.hytale:Server:{hytaleVersion}'
|
||||
compileOnly 'at.helpch:placeholderapi-hytale:{papiHytaleVersion}'
|
||||
}
|
||||
```
|
||||
////
|
||||
///
|
||||
|
||||
/// details | What is `{papiVersion}`/`{papiHytaleVersion}`?
|
||||
type: question
|
||||
|
||||
Using Javascript, `{version}` is replaced with the latest available API version of PlaceholderAPI.
|
||||
Using Javascript, `{papiVersion}` and `{papiHytaleVersion}` is replaced with the latest available API version of PlaceholderAPI for Minecraft and Hytale respectively.
|
||||
Should you see the placeholder as-is does it mean that you either block Javascript, or that the version couldn't be obtained in time during page load.
|
||||
|
||||
You can always find the latest version matching the API version on the [releases tab](https://github.com/PlaceholderAPI/PlaceholderAPI/releases) of the GitHub Repository.
|
||||
@@ -83,7 +134,7 @@ Tab the :material-plus-circle: icons in the code block below for additional info
|
||||
name: ExamplePlugin
|
||||
version: 1.0
|
||||
author: author
|
||||
main: your.main.path.Here
|
||||
main: com.example.plugin.ExamplePlugin
|
||||
|
||||
softdepend: ["PlaceholderAPI"] # (1)
|
||||
```
|
||||
@@ -101,7 +152,7 @@ Tab the :material-plus-circle: icons in the code block below for additional info
|
||||
name: ExamplePlugin
|
||||
version: 1.0
|
||||
author: author
|
||||
main: your.main.path.Here
|
||||
main: com.example.plugin.ExamplePlugin
|
||||
|
||||
depend: ["PlaceholderAPI"] # (1)
|
||||
```
|
||||
@@ -123,7 +174,7 @@ Tab the :material-plus-circle: icons in the code block below for additional info
|
||||
name: ExamplePlugin
|
||||
version: 1.0
|
||||
author: author
|
||||
main: your.main.path.Here
|
||||
main: com.example.plugin.ExamplePlugin
|
||||
|
||||
dependencies:
|
||||
server:
|
||||
@@ -146,7 +197,7 @@ Tab the :material-plus-circle: icons in the code block below for additional info
|
||||
name: ExamplePlugin
|
||||
version: 1.0
|
||||
author: author
|
||||
main: your.main.path.Here
|
||||
main: com.example.plugin.ExamplePlugin
|
||||
|
||||
dependencies:
|
||||
server:
|
||||
@@ -161,6 +212,42 @@ dependencies:
|
||||
|
||||
///
|
||||
|
||||
/// tab | manifest.json (Hytale)
|
||||
|
||||
//// tab | Optional dependency
|
||||
|
||||
```{ .json .annotate title="manifest.json" }
|
||||
{
|
||||
"Group": "com.example",
|
||||
"Name": "ExamplePlugin",
|
||||
"Version": "1.0",
|
||||
"Main": "com.example.plugin.ExamplePlugin",
|
||||
"OptionalDependencies": {
|
||||
"HelpChat:PlaceholderAPI": ">= 1.0.2"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
////
|
||||
|
||||
//// tab | Required dependency
|
||||
|
||||
```{ .json .annotate title="manifest.json" }
|
||||
{
|
||||
"Group": "com.example",
|
||||
"Name": "ExamplePlugin",
|
||||
"Version": "1.0",
|
||||
"Main": "com.example.plugin.ExamplePlugin",
|
||||
"Dependencies": {
|
||||
"HelpChat:PlaceholderAPI": ">= 1.0.2"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
////
|
||||
|
||||
///
|
||||
|
||||
## Adding placeholders to PlaceholderAPI
|
||||
|
||||
A full guide on how to create expansions can be found on the [Creating a PlaceholderExpansion](creating-a-placeholderexpansion.md) page.
|
||||
@@ -172,8 +259,8 @@ To use placeholders from other plugins in your own plugin, you simply have to [(
|
||||
|
||||
It is also important to point out, that any required plugin/dependency for an expansion has to be on the server and enabled, or the `setPlaceholders` method will just return the placeholder itself (do nothing).
|
||||
|
||||
/// info | New since TBD
|
||||
Starting with version TBD is it now possible to provide Components from the Adventure library to have placeholders parsed in.
|
||||
/// info | New since 2.12.0
|
||||
Starting with version 2.12.0 is it now possible to provide Components from the Adventure library to have placeholders parsed in.
|
||||
|
||||
In order to use this new feature are the following things required to be true:
|
||||
|
||||
@@ -182,11 +269,9 @@ In order to use this new feature are the following things required to be true:
|
||||
- You use `PAPIComponent` instead of `PlaceholderAPI` to parse Components.
|
||||
///
|
||||
|
||||
/// details | Example
|
||||
type: example
|
||||
/// tab | Spigot, Paper, ...
|
||||
|
||||
Let's assume we want to send a custom join message that shows the primary group a player has.
|
||||
To achieve this, we can do the following:
|
||||
The following is an example plugin that sends `%player_name% joined the server! They are rank %vault_rank%` as the Join message, having the placeholders be replaced by PlaceholderAPI.
|
||||
|
||||
//// note |
|
||||
The below example assumes a **soft dependency** on PlaceholderAPI to handle PlaceholderAPI not being present more decently.
|
||||
@@ -195,7 +280,7 @@ Tab the :material-plus-circle: icons in the code block below for additional info
|
||||
////
|
||||
|
||||
```{ .java .annotate title="JoinExample.java" }
|
||||
package at.helpch.placeholderapi;
|
||||
package com.example.plugin;
|
||||
|
||||
import me.clip.placeholderapi.PlaceholderAPI;
|
||||
|
||||
@@ -238,7 +323,47 @@ public class JoinExample extends JavaPlugin implements Listener {
|
||||
|
||||
Example output: `Notch joined the server! They are rank Admin`
|
||||
|
||||
//// info | New since TBD
|
||||
//// info | New since 2.12.0
|
||||
Using `placeholderapi-papi` and `PAPIComponents` instead of `PlaceholderAPI` allows you to parse placeholders inside Adventure Components.
|
||||
////
|
||||
///
|
||||
|
||||
/// tab | Hytale
|
||||
|
||||
The following is an example plugin that sends `Welcome %player_name%!` as the Join message, having the placeholders be replaced by PlaceholderAPI.
|
||||
|
||||
``` { .java .annotate title="JoinExample.java" }
|
||||
packate com.example.plugin;
|
||||
|
||||
import at.helpch.placeholderapi.PlaceholderAPI;
|
||||
|
||||
import com.hypixel.hytale.server.core.event.events.player.PlayerReadyEvent;
|
||||
import com.hypixel.hytale.server.core.Message;
|
||||
import com.hypixel.hytale.server.core.plugin.JavaPlugin;
|
||||
import com.hypixel.hytale.server.core.plugin.JavaPluginInit;
|
||||
|
||||
public class JoinExample extends JavaPlugin {
|
||||
|
||||
public JoinExample(JavaPluginInit init) {
|
||||
super(init)
|
||||
}
|
||||
|
||||
@Override
|
||||
protected void setup() {
|
||||
// (1)
|
||||
getEventRegistry().registerGlobal(PlayerReadyEvent.class, this::onPlayerReady);
|
||||
}
|
||||
|
||||
public void onPlayerReady(PlayerReadyEvent event) {
|
||||
Player player = event.getPlayer();
|
||||
// (2)
|
||||
player.sendMessage(PlaceholderAPI.setPlaceholders(Message.raw("Welcome %player_name%!"), player))
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. We tell the server to call `onPlayerReady` whenever a `PlayerReadyEvent` fires.
|
||||
2. PlaceholderAPI offers multiple `setPlaceholders` methods that can either return a `String` or a `Message` object, depending on your needs.
|
||||
Note that these methods require input of the same type: `setPlaceholders(String, PlayerRef)` for String and `setPlaceholders(Message, PlayerRef)` for Messages.
|
||||
|
||||
///
|
||||
|
||||
Reference in New Issue
Block a user