fix hytale example

[Wiki] Add info on new Component support

.theme/partials/copyright.html

@@ -1,6 +1,6 @@
 <div class="md-copyright">
     <div class="md-copyright__highlight">
-      &copy; 2015 - 2024 PlaceholderAPI Team and Contributors.<br>
+      &copy; 2015 - 2025 PlaceholderAPI Team and Contributors.<br>
       All content is licensed under
       <a href="https://github.com/PlaceholderAPI/PlaceholderAPI/blob/master/LICENSE" target="_blank" rel="noopener">
           <span class="twemoji">{% include ".icons/octicons/law-16.svg" %}</span> GNU GPL v3.0

docs/assets/js/latest-release.js

@@ -2,20 +2,27 @@ document$.subscribe(async => {
     const api_code = document.querySelectorAll('[data-md-component="api-version"]');
     
     function loadAPIInfo(data) {
-        const version = data["version"];
-        const versionToken = "{version}";
+        const mcVersion = data["mcVersion"];
+        const hyVersion = data["hyVersion"];
+
+        const mcVersionToken = "{papiVersion}";
+        const hyVersionToken = "{papiHytaleVersion}"
         for (const codeBlock of api_code) {
-            codeBlock.innerHTML = codeBlock.innerHTML.replace(new RegExp(versionToken, 'g'), version);
+            codeBlock.innerHTML = codeBlock.innerHTML
+                .replace(new RegExp(mcVersionToken, 'g'), mcVersion)
+                .replace(new RegExp(hyVersionToken, 'g'), hyVersion);
         }
     }
     
     async function fetchAPIInfo() {
-        const release = await fetch("https://repo.extendedclip.com/api/maven/latest/version/releases/me/clip/placeholderapi").then(_ => _.json());
-        
-        console.log(release)
+        const [mcRelease, hyRelease] = await Promise.all([
+            fetch("https://repo.extendedclip.com/api/maven/latest/version/releases/me/clip/placeholderapi").then(_ => _.json()),
+            fetch("https://repo.helpch.at/api/maven/latest/version/releases/at/helpch/placeholderapi-hytale").then(_ => _.json())
+        ])
         
         const data = {
-            "version": release.version
+            "mcVersion": mcRelease.version,
+            "hyVersion": hyRelease.version
         }
         
         __md_set("__api_tag", data, sessionStorage);
@@ -24,7 +31,7 @@ document$.subscribe(async => {
     
     if(location.href.includes("/developers/using-placeholderapi")) {
         const cachedApi = __md_get("__api_tag", sessionStorage);
-        if ((cachedApi != null) && (cachedApi["version"])) {
+        if ((cachedApi != null) && (cachedApi["mcVersion"])) {
             loadAPIInfo(cachedApi);
         } else {
             fetchAPIInfo();

docs/developers/creating-a-placeholderexpansion.md

@@ -273,6 +273,9 @@ 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;
+import com.hypixel.hytale.common.plugin.PluginIdentifier;
+import com.hypixel.hytale.server.core.HytaleServer;
+
 
 public class SomePlugin extends JavaPlugin {
 
@@ -280,7 +283,12 @@ public class SomePlugin extends JavaPlugin {
         super(init)
     }
 
-    // TODO: Example of checking for PAPI and registering expansion
+    @Override
+    protected void start() {
+        if (HytaleServer.get().getPluginManager().getPlugin(PluginIdentifier.fromString("HelpChat:PlaceholderAPI")) != null) {
+            new SomeExpansion(this).register();
+        }
+    }
 }
 ```
 

docs/developers/using-placeholderapi.md

@@ -6,10 +6,12 @@ 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 project type and dependency manager.
 
@@ -26,10 +28,9 @@ Use the below code example matching your project type and dependency manager.
         <dependency>
             <groupId>me.clip</groupId>
             <artifactId>placeholderapi</artifactId>
-            <version>{version}</version>
+            <version>{papiVersion}</version>
             <scope>provided</scope>
         </dependency>
-    </dependencies>
 ```
 ////
 
@@ -42,7 +43,10 @@ repositories {
 }
 
 dependencies {
-    compileOnly 'me.clip:placeholderapi:{version}'
+    compileOnly 'me.clip:placeholderapi:{papiVersion}'
+
+    // Optional: Component support on Paper Servers (Since 2.12.0)
+    compileOnly 'me.clip:placeholderapi-paper:{papiVersion}'
 }
 ```
 ////
@@ -72,7 +76,7 @@ dependencies {
         <dependency>
             <groupId>at.helpch</groupId>
             <artifactId>placeholderapi-hytale</artifactId>
-            <version>{version}</version>
+            <version>{papiHytaleVersion}</version>
             <scope>provided</scope>
         </dependency>
     </dependencies>
@@ -91,16 +95,16 @@ repositories {
 dependencies {
     // Replace {hytaleVersion} with the version you need.
     compileOnly 'com.hypixel.hytale:Server:{hytaleVersion}'
-    compileOnly 'at.helpch:placeholderapi-hytale:{version}'
+    compileOnly 'at.helpch:placeholderapi-hytale:{papiHytaleVersion}'
 }
 ```
 ////
 ///
 
-/// details | What is `{version}`?
+/// 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.
@@ -243,10 +247,20 @@ A full guide on how to create expansions can be found on the [Creating a Placeho
 ## Setting placeholders in your plugin
 
 PlaceholderAPI offers the ability, to automatically parse placeholders from other plugins within your own plugin, giving the ability for your plugin to support thousands of other placeholders without depending on each plugin individually.  
-To use placeholders from other plugins in our own plugin, we simply have to [(soft)depend on PlaceholderAPI](#set-placeholderapi-as-softdepend) and use the `setPlaceholders` method.
+To use placeholders from other plugins in your own plugin, you simply have to [(soft)depend on PlaceholderAPI](#set-placeholderapi-as-softdepend) and use the `setPlaceholders` method.
 
 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 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:
+
+- You depend on `placeholderapi-paper` and not just `placeholderapi`
+- Your plugin runs on a Paper-based Server. Spigot-based servers will not work!
+- You use `PAPIComponent` instead of `PlaceholderAPI` to parse Components.
+///
+
 /// tab | Spigot, Paper, ...
 
 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.
@@ -301,11 +315,15 @@ public class JoinExample extends JavaPlugin implements Listener {
     
     Example output: `Notch joined the server! They are rank Admin`
 
+    //// 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 `%player_name% joined the server! They are rank %vault_rank%` as the Join message, having the placeholders be replaced by PlaceholderAPI.
+The following is an example plugin that sends `Welcome %player_name%!` as the Join message, having the placeholders be replaced by PlaceholderAPI.
+Keeping in mind the [Hytale Player Expansion](https://ecloud.placeholderapi.com/expansions/player-hytale/) needs to be installed to make use of `%player_<identifier>%` placeholders.
 
 ``` { .java .annotate title="JoinExample.java" }
 packate com.example.plugin;
@@ -316,6 +334,7 @@ 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;
+import com.hypixel.hytale.server.core.universe.Universe;
 
 public class JoinExample extends JavaPlugin {
 
@@ -326,19 +345,20 @@ public class JoinExample extends JavaPlugin {
     @Override
     protected void setup() {
         // (1)
-        getEventRegistry().registerGlobal(PlayerReadyEvent.class, this::onPlayerReady);
+        Universe.get().getWorlds().keySet().forEach(name -> getEventRegistry().register(PlayerReadyEvent.class, name, this::onPlayerReady));
     }
 
     public void onPlayerReady(PlayerReadyEvent event) {
         Player player = event.getPlayer();
         // (2)
-        player.sendMessage(PlaceholderAPI.setPlaceholders(Message.raw("Welcome %player_name%!"), player))
+        player.sendMessage(PlaceholderAPI.setPlaceholders(player.getPlayerRef(), Message.raw("Welcome %player_name%!")))
+        
     }
 }
 ```
 
 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.
+    Note that these methods require input of the same type: `setPlaceholders(PlayerRef, String)` for String and `setPlaceholders(PlayerRef, Message)` for Messages.
 
 ///

docs/index.md

@@ -40,7 +40,8 @@ It also has a community-curated list of all available Placeholder expansions and
     
     Common problems you may face while using PlaceholderAPI, and how to solve them.
     
-    - [:octicons-chevron-right-16: Go to Page](common-issues.md)
+    - [:octicons-chevron-right-16: Common Issues](issues/index.md)
+    - [:octicons-chevron-right-16: eCloud connection blocked](issues/ecloud-block.md)
 
 -   ### :material-chat-question: FAQ
     

docs/issues/ecloud-block.md

@@ -0,0 +1,74 @@
+---
+description: Fixing blocked connections to the PlaceholderAPI Expansion Cloud (eCloud).
+---
+
+# eCloud connection blocked
+
+If you cannot download expansions via PlaceholderAPI, your server may be unable to reach the PlaceholderAPI Expansion Cloud (eCloud). This is usually caused by a network restriction by your host, firewall, or ISP.
+
+## Symptoms
+
+Common signs include:
+
+- You were directed to this page via an in-game message.
+- `/papi ecloud download/update <expansion>` fails (timeouts, errors, connection refused, or similar).
+
+## Why it happens
+
+The download command requires outbound HTTPS access from your server to PlaceholderAPI’s eCloud API. Connections can be blocked by:
+
+- Your server host’s firewall / security policy
+- A local firewall on the machine
+- A network firewall (datacenter, router)
+- DNS filtering or an ISP block
+
+## Domains PlaceholderAPI uses
+
+Allow outbound HTTPS (TCP 443) to these domains:
+
+- PlaceholderAPI **< 2.12.0** uses `api.extendedclip.com`
+- PlaceholderAPI **>= 2.12.0** uses `*.placeholderapi.com`
+
+## Fix options
+
+### 1) Ask your host to unblock the eCloud
+
+If you use shared hosting or a managed host, you may not be able to change firewall rules yourself. Contact your host and ask them to allow outbound HTTPS requests to the domains listed above.
+
+### 2) Check firewalls / filters you control
+
+If you manage your own server, check any outbound filtering:
+
+- OS firewall rules (Windows Firewall / `ufw` / `iptables`)
+- Router/datacenter firewall rules
+- DNS filtering
+
+### 3) Manually install expansions (works even if the eCloud is blocked)
+
+If unblocking is not an option, you can download expansions manually:
+
+1. Go to https://ecloud.placeholderapi.com/
+2. Open the expansion you want.
+3. Download the `.jar`.
+4. Put it into your server’s `plugins/PlaceholderAPI/expansions/` folder.
+5. Run [`/papi reload`](../users/commands.md#papi-reload) (or restart the server).
+
+## Quick connectivity checks (optional)
+
+If you have access to the machine running the server, these checks from a terminal or command prompt can help confirm a block.
+
+```bash
+curl -I https://ecloud.placeholderapi.com/api/v3/
+curl -I https://api.extendedclip.com/v2/
+```
+
+If these commands fail on the server but work on your own PC/network, the server host or datacenter network is most likely blocking outbound connections.
+
+## Still stuck?
+
+If you need help, join the [Discord Server](https://discord.gg/helpchat) and share:
+
+- What you've tried
+- The full console error from the download attempt
+- The link provided by `/papi dump`
+

docs/issues/index.md

@@ -8,6 +8,12 @@ This page lists common issues you may encounter with PlaceholderAPI and how you
 
 If you have more questions, feel free to join the [Discord Server](https://discord.gg/helpchat).
 
+## eCloud download fails / blocked connection
+
+If your host or network blocks outgoing connections to the Expansion Cloud (eCloud), PlaceholderAPI will be unable to download expansions.
+
+See: [eCloud connection blocked](ecloud-block.md)
+
 ## `java.lang.NoClassDefFoundError: com/google/gson/Gson`
 
 If you encounter an issue such as

docs/users/placeholder-list/hytale.md

@@ -14,113 +14,113 @@ Further details on how to contribute to this list or the wiki as a whole can be
 ///
 
 - [Standalone](#standalone)
-    - A
+    - **A**
         - *No Expansions*
-    - B
+    - **B**
         - *No Expansions*
-    - C
+    - **C**
         - *No Expansions*
-    - D
+    - **D**
         - *No Expansions*
-    - E
+    - **E**
         - *No Expansions*
-    - F
+    - **F**
         - *No Expansions*
-    - G
+    - **G**
         - *No Expansions*
-    - H
+    - **H**
         - *No Expansions*
-    - I
+    - **I**
         - *No Expansions*
-    - J
+    - **J**
         - *No Expansions*
-    - K
+    - **K**
         - *No Expansions*
-    - L
+    - **L**
         - *No Expansions*
-    - M
+    - **M**
         - *No Expansions*
-    - N
+    - **N**
         - *No Expansions*
-    - O
+    - **O**
         - *No Expansions*
-    - P
-        - [Player](#player)
-    - Q
+    - **P**
+        - **[Player](#player)**
+    - **Q**
         - *No Expansions*
-    - R
+    - **R**
         - *No Expansions*
-    - S
+    - **S**
+        - **[Server](#server)**
+    - **T**
         - *No Expansions*
-    - T
+    - **U**
         - *No Expansions*
-    - U
+    - **V**
         - *No Expansions*
-    - V
+    - **W**
+        - **[World](#world)**
+    - **X**
         - *No Expansions*
-    - W
+    - **Y**
         - *No Expansions*
-    - X
-        - *No Expansions*
-    - Y
-        - *No Expansions*
-    - Z
+    - **Z**
         - *No Expansions*
 
 ----
 
 - [Plugin-placeholders](#plugin-placeholders)
-    - A
+    - **A**
         - *No Expansions*
-    - B
+    - **B**
         - *No Expansions*
-    - C
+    - **C**
         - *No Expansions*
-    - D
+    - **D**
         - *No Expansions*
-    - E
+    - **E**
         - *No Expansions*
-    - F
+    - **F**
         - *No Expansions*
-    - G
+    - **G**
         - *No Expansions*
-    - H
+    - **H**
         - *No Expansions*
-    - I
+    - **I**
         - *No Expansions*
-    - J
+    - **J**
         - *No Expansions*
-    - K
+    - **K**
         - *No Expansions*
-    - L
+    - **L**
+        - **[LuckPerms](#luckperms)**
+    - **M**
         - *No Expansions*
-    - M
+    - **N**
         - *No Expansions*
-    - N
+    - **O**
         - *No Expansions*
-    - O
+    - **P**
         - *No Expansions*
-    - P
+    - **Q**
         - *No Expansions*
-    - Q
+    - **R**
         - *No Expansions*
-    - R
+    - **S**
         - *No Expansions*
-    - S
+    - **T**
         - *No Expansions*
-    - T
+    - **U**
         - *No Expansions*
-    - U
+    - **V**
         - *No Expansions*
-    - V
+    - **W**
         - *No Expansions*
-    - W
+    - **X**
         - *No Expansions*
-    - X
+    - **Y**
         - *No Expansions*
-    - Y
-        - *No Expansions*
-    - Z
+    - **Z**
         - *No Expansions*
 
 ----

mkdocs.yml

@@ -63,6 +63,8 @@ extra:
       - reject
       - manage
   social:
+    - icon: simple/modrinth
+      link: https://modrinth.com/plugin/placeholderapi
     - icon: fontawesome/regular/paper-plane
       link: https://hangar.papermc.io/HelpChat/PlaceholderAPI
     - icon: simple/spigotmc
@@ -86,7 +88,9 @@ nav:
     - developers/using-placeholderapi.md
     - developers/creating-a-placeholderexpansion.md
     - developers/expansion-cloud.md
-  - common-issues.md
+  - Common Issues:
+    - issues/index.md
+    - issues/ecloud-block.md
   - faq.md
   - Discord: https://discord.gg/helpchat