Merge pull request #1172 from PlaceholderAPI/feat/add-more-hytale-api-docs

Feat/add more hytale api docs

docs/developers/configuration-api-hytale.md

@@ -0,0 +1,69 @@
+---
+description: How to create configurable expansions in Hytale.
+---
+
+# The Configurable<T> 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<CoolExpansionConfig>`, you'll then need to also implement the 2 required methods.
+
+```java { .annotate title="CoolExpansion.java" }
+public final class CoolExpansion extends PlaceholderExpansion implements Configurable<CoolExpansionConfig> {
+	@Override
+	public Class<CoolExpansionConfig> 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<T>.getExpansionConfig(Class<T extends Configurable<T>>)`

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
     
     ----

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

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.
+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 */);
+})
+```

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