feat: cancellable events, expanded API, and PlaceholderAPI support

CHANGELOG.md

@@ -7,9 +7,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+#### Cancellable Event System
+- `Cancellable` interface with cancel reason support for pre-event interception
+- `EventBus.publishCancellable()` for pre-event firing with early cancellation
+- 58 event classes (29 PreEvent + 29 PostEvent) across 7 modules:
+  - **Homes**: set, delete, teleport, share, unshare, setDefault
+  - **Warps**: set, delete, teleport
+  - **Spawns**: set, delete, teleport
+  - **Kits**: claim, create, delete
+  - **Moderation**: ban, unban, mute, unmute, kick, warn
+  - **Teleport**: TPA send/accept/deny, back, RTP
+  - **Utility**: fly, god, AFK toggle
+- All managers fire PreEvent before action (cancellable) and PostEvent after success
+
+#### Expanded Public API
+- `HyperEssentialsAPI` expanded from 12 to 80+ methods covering all modules
+- Home API: getHomes, setHome, deleteHome, getHomeCount, getHomeLimit, shareHome, unshareHome, and more
+- Kit API: getKit, getAllKits, getAvailableKits, cooldown queries, one-time claim checks
+- Moderation API: isBanned, isMuted, getActiveBan, getPunishmentHistory, isIpBanned
+- Utility API: isFlying, isGod, isAfk, isInfiniteStamina, playtime and session queries
+- EventBus access: `registerEventListener()` / `unregisterEventListener()` for external plugins
+- Manager accessors for advanced plugin use (getHomeManager, getKitManager, etc.)
+
+#### PlaceholderAPI Support (~37 placeholders)
+- `HyperEssentialsExpansion` for PlaceholderAPI (`%essentials_*%`)
+- `WiFlowExpansion` for WiFlow PlaceholderAPI (`{essentials_*}`)
+- Placeholder categories: homes (4), kits (3+), moderation (8), utility (13), warps/spawns/TPA (5)
+- Bridge classes with runtime detection and reflection-based registration
+- Conditional WiFlow compilation (excluded when WiFlow JAR not present)
+
 ### Changed
 
 - `/home` (no args) no longer falls back to a home named "home" or auto-selects when only one home exists — players must explicitly set a default via the Homes GUI
+- `EventBus.fire()` renamed to `EventBus.publish()` for consistency with HyperFactions
+- `EventBus` internals switched from `CopyOnWriteArrayList` to `Collections.synchronizedList`
 
 ### Fixed
 

build.gradle

@@ -28,12 +28,16 @@ java {
     }
 }
 
+// WiFlow PlaceholderAPI lib detection (conditional compilation)
+def hasWiFlowLib = file('libs').listFiles()?.any { it.name.contains('WiFlow') } ?: false
+
 repositories {
     mavenCentral()
     maven {
         name = 'hytale'
         url = "https://maven.hytale.com/${hytaleChannel}"
     }
+    maven { url = 'https://repo.helpch.at/releases/' }
 }
 
 dependencies {
@@ -52,6 +56,12 @@ dependencies {
     // Sentry error tracking (bundled in shadow JAR)
     implementation 'io.sentry:sentry:8.33.0'
 
+    // PlaceholderAPI Hytale (soft dependency - compileOnly)
+    compileOnly 'at.helpch:placeholderapi-hytale:1.0.4'
+
+    // Optional local soft dependencies (WiFlowPlaceholderAPI)
+    compileOnly fileTree('libs') { include '*.jar' }
+
     // Null safety annotations
     compileOnly 'org.jetbrains:annotations:24.1.0'
 
@@ -114,6 +124,13 @@ build {
     finalizedBy tasks.matching { it.name == 'sentryUploadSourceBundleJava' }
 }
 
+// WiFlowExpansion extends PlaceholderExpansion (from WiFlowPlaceholderAPI) directly.
+// When WiFlow isn't on the classpath (JitPack / CI), exclude it from compilation.
+// The bridge class (WiFlowPlaceholderIntegration) loads it reflectively at runtime.
+if (!hasWiFlowLib) {
+    sourceSets.main.java.exclude '**/WiFlowExpansion.java'
+}
+
 tasks.named('compileJava') {
     dependsOn 'generateBuildInfo'
     dependsOn ':HyperPerms:shadowJar'

src/main/java/com/hyperessentials/HyperEssentials.java

@@ -168,13 +168,34 @@ public void enable() {
     // Register GUI pages (post-init, modules + managers must be ready)
     registerPages();
 
+    // Initialize PlaceholderAPI integration (after all managers are ready)
+    com.hyperessentials.integration.placeholder.PlaceholderAPIIntegration.init(this);
+
+    // Initialize WiFlow PlaceholderAPI integration (guard before class loading)
+    try {
+      Class.forName("com.wiflow.placeholderapi.WiFlowPlaceholderAPI");
+      com.hyperessentials.integration.placeholder.WiFlowPlaceholderIntegration.init(this);
+    } catch (ClassNotFoundException e) {
+      Logger.debug("WiFlow PlaceholderAPI not found — WiFlow placeholders disabled");
+    }
+
     Logger.info("HyperEssentials enabled with %d modules", moduleRegistry.getEnabledModules().size());
   }
 
   /**
    * Disables HyperEssentials - disables modules, shuts down storage, saves config.
    */
   public void disable() {
+    // Unregister PlaceholderAPI expansions
+    try {
+      Class.forName("com.wiflow.placeholderapi.WiFlowPlaceholderAPI");
+      com.hyperessentials.integration.placeholder.WiFlowPlaceholderIntegration.shutdown();
+    } catch (ClassNotFoundException ignored) {}
+    com.hyperessentials.integration.placeholder.PlaceholderAPIIntegration.shutdown();
+
+    // Clear event bus listeners
+    com.hyperessentials.api.events.EventBus.clearAll();
+
     // Disable modules in reverse order
     if (moduleRegistry != null) {
       moduleRegistry.disableAll();
@@ -506,6 +527,14 @@ private void ensureDirectories() {
   public HomesModule getHomesModule() { return moduleRegistry.getModule(HomesModule.class); }
   @Nullable
   public TeleportModule getTeleportModule() { return moduleRegistry.getModule(TeleportModule.class); }
+  @Nullable
+  public KitsModule getKitsModule() { return moduleRegistry.getModule(KitsModule.class); }
+  @Nullable
+  public ModerationModule getModerationModule() { return moduleRegistry.getModule(ModerationModule.class); }
+  @Nullable
+  public UtilityModule getUtilityModule() { return moduleRegistry.getModule(UtilityModule.class); }
+  @Nullable
+  public AnnouncementsModule getAnnouncementsModule() { return moduleRegistry.getModule(AnnouncementsModule.class); }
 
   // Getters