From 91b6d615bf421725ff50a63239dad6fd57b47d02 Mon Sep 17 00:00:00 2001
From: PiggyPiglet <noreply@piggypiglet.me>
Date: Sun, 8 Feb 2026 22:57:53 +0800
Subject: [PATCH] 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<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>>)`
\ 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