Hall of Supporters Feature for Zander Hub

README.md

@@ -4,3 +4,5 @@ Documentation: [https://modularsoft.org/docs/products/zander](https://modularsof
 
 Product docs:
 - [Private messaging (Zander Velocity)](docs/private-messaging.md)
+- [Hall of Supporters (Zander Hub)](docs/hall-of-supporters.md)
+- [Statue Customization Guide (Zander Hub)](docs/statue-customization-guide.md)

docs/hall-of-supporters.md

@@ -0,0 +1,50 @@
+# Hall of Supporters / Hall of Roles
+
+The Hall of Supporters is a feature for the Zander Hub plugin that automatically populates armor stand statues and signs with eligible players based on their LuckPerms groups.
+
+## Quick Start Guide (First Time Setup)
+
+Follow these steps to get your Hall of Supporters running in minutes:
+
+1.  **Create a Section**: A section represents a group of players sharing a rank.
+    *   `/hall section create staff`
+    *   `/hall section setlabel staff Staff` (This label appears on the signs below the statues)
+    *   `/hall section addgroup staff admin` (Link the section to a LuckPerms group)
+2.  **Create Slots**: A slot is a physical location where a statue will stand.
+    *   Find the exact spot where you want a statue. **Statues will face the direction you are looking when you run the command.**
+    *   **Place a sign block** exactly one block below your feet. The plugin uses this sign to display the player's name and rank label. **Note: The sign block is meant to stay there as a permanent part of the pedestal.**
+    *   Run: `/hall slot create staff staff-1`
+3.  **Refresh**: Trigger the auto-population system.
+    *   `/hall refresh`
+4.  **Verification**: Check your work.
+    *   `/hall slot list`
+
+## Features
+- **Auto-population**: Players are automatically assigned to available slots based on their LuckPerms groups and priority.
+- **Customizable Statues**: Players can customize their own statue's armor and items via a GUI.
+- **Forced Identity**: Statues always display the player's real skin head and username.
+- **Particle Effects**: Supporters can choose from various particle effects to surround their statue.
+- **Plugin-controlled Signs**: Signs below statues automatically display the player's name and their role label.
+- **Manual Overrides**: Admins can manually assign or lock slots for specific players.
+- **YAML Persistence**: All data is stored in simple YAML files for easy maintenance.
+
+## Detailed Administration
+
+### Sections
+Sections are the "containers" for ranks.
+*   **Priority**: If a player has multiple ranks, they appear in the section with the highest priority number. Use `/hall section setpriority <id> <number>`.
+*   **Sign Labels**: Set what appears on the sign below the statue using `/hall section setlabel <id> <text>`.
+
+### Slots
+Slots are physical locations.
+*   **Rotation**: When creating a slot with `/hall slot create`, the statue's facing direction is set to your current yaw.
+*   **Signs**: The sign block below the slot is a mandatory part of the pedestal. The plugin will take control of its text.
+*   **Dynamic Sorting**: By default, slots are filled automatically based on player priority (usually LuckPerms weight). If a new, higher-priority player joins the server or gains a rank, they may "bump" an existing player out of their slot or move them to a different one.
+*   **Slot Locking**: If you want a specific player to stay in a specific slot permanently, you can use `/hall lock <slotId>`. This prevents the auto-assignment system from moving or replacing the player in that slot.
+
+## Documentation Links
+- [User Customization Guide](statue-customization-guide.md)
+- [Admin Command Reference](hall-of-supporters.md#commands)
+
+## Administration Commands
+... (see [hall-of-supporters.md](hall-of-supporters.md) for full reference)

docs/statue-customization-guide.md

@@ -0,0 +1,37 @@
+# Statue Customization Guide
+
+As a supporter with an assigned statue in the Hall of Supporters, you have the ability to customize its appearance!
+
+## How to Customize
+There are two ways to open the customization menu:
+
+1.  **Command**: Use `/mystatue` while in the hub.
+2.  **Interaction**: **Left Shift + Right Click** your own statue with an empty hand.
+
+## Customization Options
+
+### 1. Armor
+You can cycle through various armor pieces for your statue:
+*   **Chestplate**: Cycle through Leather, Chainmail, Iron, Gold, Diamond, and Netherite.
+*   **Leggings**: Cycle through different leg protection.
+*   **Boots**: Choose your statue's footwear.
+
+### 2. Held Items
+*   **Main Hand**: Cycle through weapons like swords, axes, bows, and tridents.
+*   **Off Hand**: If you have the required rank, you can equip items like shields, totems, or torches.
+
+### 3. Poses
+Change the stance of your statue by cycling through presets:
+*   **Presets**: Default, Zombie (arms forward), Running, and Dancing.
+
+### 4. Particle Effects
+Add some flair to your statue with particle effects:
+*   Options include Hearts, Happy Villager, Flame, Witch, and more.
+
+### 5. Reset
+If you want to start over, use the **Reset Statue** option (Barrier icon) in the menu to return your statue to its default state.
+
+## Rules & Limitations
+*   **Identity**: Your statue will always use your current Minecraft skin head and your username. This cannot be changed.
+*   **Location**: You cannot move your statue; it is fixed to its assigned slot.
+*   **Signs**: The sign below your statue is controlled by the plugin and displays your name and rank.

zander-hub/pom.xml

@@ -10,16 +10,6 @@
 
     <artifactId>zander-hub</artifactId>
 
-
-    <build>
-        <resources>
-            <resource>
-                <directory>src/main/resources</directory>
-                <filtering>true</filtering>
-            </resource>
-        </resources>
-    </build>
-
     <repositories>
         <repository>
             <id>papermc</id>
@@ -62,6 +52,12 @@
             <version>5.3.0</version>
             <scope>provided</scope>
         </dependency>
+        <dependency>
+            <groupId>net.luckperms</groupId>
+            <artifactId>api</artifactId>
+            <version>5.4</version>
+            <scope>provided</scope>
+        </dependency>
     </dependencies>
 
     <build>

zander-hub/src/main/java/org/modularsoft/zander/hub/ZanderHubMain.java

@@ -12,13 +12,19 @@
 import org.modularsoft.zander.hub.events.HubPlayerLeave;
 import org.modularsoft.zander.hub.events.HubPlayerVoid;
 import org.modularsoft.zander.hub.gui.HubCompassItem;
+import org.modularsoft.zander.hub.hall.commands.HallAdminCommand;
+import org.modularsoft.zander.hub.hall.commands.MyStatueCommand;
+import org.modularsoft.zander.hub.hall.events.HallListeners;
+import org.modularsoft.zander.hub.hall.events.HallProtection;
+import org.modularsoft.zander.hub.hall.manager.HallManager;
 import org.modularsoft.zander.hub.protection.HubCreatureSpawnProtection;
 import org.modularsoft.zander.hub.protection.HubInteractionProtection;
 import org.modularsoft.zander.hub.protection.HubProtection;
 import org.modularsoft.zander.hub.utils.CopyResources;
 
 public class ZanderHubMain extends JavaPlugin {
     public static ZanderHubMain plugin;
+    private HallManager hallManager;
 
     public void onEnable() {
         plugin = this;
@@ -59,12 +65,28 @@ public void onEnable() {
         // Item Event Registry
         pluginmanager.registerEvents(new HubCompassItem(), this);
 
+        // Hall of Supporters
+        this.hallManager = new HallManager(this);
+        this.hallManager.init();
+        pluginmanager.registerEvents(this.hallManager.getCustomizationGui(), this);
+        pluginmanager.registerEvents(new HallListeners(this), this);
+        pluginmanager.registerEvents(new HallProtection(this), this);
+
         // Command Registry
         this.getCommand("fly").setExecutor(new fly());
+        this.getCommand("hall").setExecutor(new HallAdminCommand(this));
+        this.getCommand("mystatue").setExecutor(new MyStatueCommand(this));
+    }
+
+    public HallManager getHallManager() {
+        return hallManager;
     }
 
     // load defaults from the embedded resource & don't override existing values
     @Override
     public void onDisable() {
+        if (hallManager != null) {
+            hallManager.stop();
+        }
     }
 }