From 91b6d615bf421725ff50a63239dad6fd57b47d02 Mon Sep 17 00:00:00 2001 From: PiggyPiglet Date: Sun, 8 Feb 2026 22:57:53 +0800 Subject: [PATCH 1/4] add hytale configurable docs --- docs/developers/configuration-api-hytale.md | 69 +++++++++++++++++++++ docs/developers/index.md | 8 +++ docs/index.md | 1 + 3 files changed, 78 insertions(+) create mode 100644 docs/developers/configuration-api-hytale.md diff --git a/docs/developers/configuration-api-hytale.md b/docs/developers/configuration-api-hytale.md new file mode 100644 index 0000000..6ee3e32 --- /dev/null +++ b/docs/developers/configuration-api-hytale.md @@ -0,0 +1,69 @@ +--- +description: How to create configurable expansions in Hytale. +--- + +# The Configurable Interface + +Unlike in spigot, in Hytale PAPI does not forward through Hytale's configuration API and instead implements its own. Effectively you'll be required to create a class representing your configuration section in PlaceholderAPI's main config.yml, and PAPI will handle the rest. + +## Create Your Config Class + +```java { .annotate title="CoolExpansionConfig.java" } +public final class CoolExpansionConfig { + private String test; + private String dateFormat; + + public CoolExpansionConfig(String test, String dateFormat) { + this.test = test; + this.dateFormat = dateFormat; + } + + public String test() { + return test; + } + + public String dateFormat() { + return dateFormat; + } +} +``` + +Your config class needs to represent your config structure exactly. The only difference is in naming, in the above example, dateFormat will be converted to snake case (date_format) when reading the yaml. The above class will look like this in PAPI's config: + +```yaml { .annotate title="HelpChat_PlaceholderAPI/config.yml" } +expansions: + coolexpansion: + test: wew + date_format: "dd/mm/yyyy" +``` + +## Using Your Config Class + +Once created, we need to tell PAPI about it. In your PlaceholderExpansion class, implement `Configurable`, you'll then need to also implement the 2 required methods. + +```java { .annotate title="CoolExpansion.java" } +public final class CoolExpansion extends PlaceholderExpansion implements Configurable { + @Override + public Class provideConfigType() { + return CoolExpansionConfig.class; + } + + @Override + public CoolExpansionConfig provideDefault() { + return new CoolExpansionConfig("wew", "dd/mm/yyyy"); + } + + @Override + public String onPlaceholderRequest(PlayerRef player, String params) { + final CoolExpansionConfig config = getExpansionConfig(CoolExpansion.class); + + return switch(params) { + case "test" -> config.test(); + case "date_format" -> config.dateFormat(); + default -> null; + }; + } +} +``` + +That's pretty much it. PAPI will generate the default yaml from the values you provide in `provideDefault()` and write it to the PAPI config, then whenever your expansion starts it'll read the values from the config and put them into a CoolExpansionConfig object accessible via `PlaceholderExpansion.getExpansionConfig(Class>)` \ No newline at end of file diff --git a/docs/developers/index.md b/docs/developers/index.md index 5d048b4..ce80ea2 100644 --- a/docs/developers/index.md +++ b/docs/developers/index.md @@ -26,6 +26,14 @@ The pages listed under this section are meant for developers of plugins who want - [:octicons-chevron-right-16: Go to Page](creating-a-placeholderexpansion.md) +- ### Using the Hytale Configuration API + + ---- + + How to create a configurable expansion for Hytale + + - [:octicons-chevron-right-16: Go to Page](configuration-api-hytale.md) + - ### eCloud ---- diff --git a/docs/index.md b/docs/index.md index 82f0d9c..38fa8d2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -32,6 +32,7 @@ It also has a community-curated list of all available Placeholder expansions and - [:octicons-chevron-right-16: Using PlaceholderAPI](developers/using-placeholderapi.md) - [:octicons-chevron-right-16: Creating a PlaceholderExpansion](developers/creating-a-placeholderexpansion.md) + - [:octicons-chevron-right-16: Using the Hytale Configuration API](developers/configuration-api-hytale.md) - [:octicons-chevron-right-16: eCloud](developers/expansion-cloud.md) - ### :material-alert-circle-outline: Common Issues From c86e51b5808c432e76577816c50a94d1d7147dc2 Mon Sep 17 00:00:00 2001 From: PiggyPiglet Date: Sun, 8 Feb 2026 23:01:52 +0800 Subject: [PATCH 2/4] Add info about player concurrency issues --- docs/issues/index.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/issues/index.md b/docs/issues/index.md index 743c3f6..c285140 100644 --- a/docs/issues/index.md +++ b/docs/issues/index.md @@ -44,4 +44,17 @@ In such a case, contact the developer of the expansion and inform them about thi This error is given whenever the expansion cannot be loaded, which often happens due to a missing dependency (required plugin) or because creating an expansion instance failed. -The only thing you can do is to provide the full error so that we can check if the issue is caused by PlaceholderAPI (More unlikely) or by the expansion. \ No newline at end of file +The only thing you can do is to provide the full error so that we can check if the issue is caused by PlaceholderAPI (More unlikely) or by the expansion. + +## Some player placeholders aren't working on Hytale + +Due to Hytale's concurrency setup and PlaceholderAPI design choices, certain player placeholders require a particular parsing implementation on the dev side. If you're a plugin user and placeholders like %player_health% aren't working, but work fine when using `/papi parse me %player_health%`, chances are the plugin you're using has incorrectly implemented PlaceholderAPI support. + +To access certain player data, placeholders need to be parsed in the world thread of the player. + +```java +final World world = player.getWorld(); +world.execute(() -> { + PlaceholderAPI.setPlaceholders(/* set placeholders here */); +}) +``` \ No newline at end of file From ec59f46c21be762b69f7e150b646576951070209 Mon Sep 17 00:00:00 2001 From: PiggyPiglet Date: Mon, 9 Feb 2026 00:54:12 +0800 Subject: [PATCH 3/4] Update docs/developers/configuration-api-hytale.md Co-authored-by: Andre_601 <11576465+Andre601@users.noreply.github.com> --- docs/developers/configuration-api-hytale.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/developers/configuration-api-hytale.md b/docs/developers/configuration-api-hytale.md index 6ee3e32..2e18452 100644 --- a/docs/developers/configuration-api-hytale.md +++ b/docs/developers/configuration-api-hytale.md @@ -32,9 +32,9 @@ Your config class needs to represent your config structure exactly. The only dif ```yaml { .annotate title="HelpChat_PlaceholderAPI/config.yml" } expansions: - coolexpansion: - test: wew - date_format: "dd/mm/yyyy" + coolexpansion: + test: wew + date_format: "dd/mm/yyyy" ``` ## Using Your Config Class From d88155a6c1225486ed2f0788e87b1f34b0bddb74 Mon Sep 17 00:00:00 2001 From: PiggyPiglet Date: Mon, 9 Feb 2026 00:54:34 +0800 Subject: [PATCH 4/4] update mkdocs --- mkdocs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/mkdocs.yml b/mkdocs.yml index 4f57bd5..fe66d8e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -90,6 +90,7 @@ nav: - developers/index.md - developers/using-placeholderapi.md - developers/creating-a-placeholderexpansion.md + - developers/configuration-api-hytale.md - developers/expansion-cloud.md - Common Issues: - issues/index.md