feat: homes module with HyperFactions territory integration

.gitignore

@@ -43,9 +43,14 @@ libs/
 # Local config overrides
 config.local.json
 
+# Local build setup (multi-project wiring is machine-specific)
+settings.gradle
+gradle.properties
+
 # AI Files
 CLAUDE.md
 .claude/
+.serena/
 .cursorrules
 .cursorignore
 .cursor/

README.md

@@ -4,23 +4,20 @@ Modular server essentials for Hytale. Part of the [HyperSystems](https://github.
 
 ## Features
 
-HyperEssentials consolidates essential server functionality into a single modular plugin:
-
-| Module | Features | Status |
-|--------|----------|--------|
-| **Homes** | Home CRUD, sharing, bed sync | Planned |
-| **Warps** | Warp CRUD, categories | Planned |
-| **Spawns** | Spawn CRUD, per-world, respawn | Planned |
-| **Teleport** | TPA, /back | Planned |
-| **Warmup** | Universal warmup/cooldown system | Scaffold |
-| **Kits** | Kit system | Planned |
-| **Moderation** | Mute, temp ban, IP ban, freeze | Planned |
-| **Vanish** | Vanish system | Planned |
-| **Utility** | Clear chat, clear inventory, repair, near | Planned |
-| **Announcements** | Broadcast/announcement system | Planned |
-| **RTP** | Random teleport | Planned |
-
-Each module can be independently enabled or disabled via configuration.
+HyperEssentials consolidates essential server functionality into a single modular plugin with 10 modules, 46 commands, and 50+ permission nodes. Each module can be independently enabled or disabled.
+
+| Module | Features | Default | Status |
+|--------|----------|---------|--------|
+| **Warmup** | Universal warmup/cooldown system for all teleport actions | Enabled | Implemented |
+| **Homes** | Home CRUD, sharing, bed sync, faction territory restrictions | Enabled | Implemented |
+| **Warps** | Warp CRUD, categories, custom permissions per warp | Enabled | Implemented |
+| **Spawns** | Spawn CRUD, per-world spawns, group routing, respawn teleport | Enabled | Implemented |
+| **Teleport** | TPA requests, /back history, random teleport (RTP) | Enabled | Implemented |
+| **Kits** | Kit creation from inventory, cooldowns, one-time claims, per-kit permissions | Disabled | Implemented |
+| **Moderation** | Ban, tempban, mute, tempmute, kick, freeze, vanish, punishment history | Disabled | Implemented |
+| **Utility** | Heal, fly, god mode, clear chat, clear inventory, repair, near | Disabled | Implemented |
+| **Announcements** | Scheduled broadcasts, announcement rotation, manual broadcast | Disabled | Implemented |
+| **Vanish** | Standalone vanish module (vanish is also available via Moderation) | Enabled | Stub |
 
 ## Requirements
 
@@ -29,7 +26,10 @@ Each module can be independently enabled or disabled via configuration.
 
 ## Optional Dependencies
 
-- [HyperPerms](https://github.com/HyperSystems-Development/HyperPerms) - Advanced permission management
+- [HyperPerms](https://github.com/HyperSystems-Development/HyperPerms) — Advanced permission management (chain-of-responsibility resolution)
+- [HyperFactions](https://github.com/HyperSystems-Development/HyperFactions) — Territory-aware home restrictions
+- [VaultUnlocked](https://github.com/TheNewEconomy/VaultUnlockedAPI) — Economy integration
+- LuckPerms — Permission provider fallback
 
 ## Installation
 
@@ -40,27 +40,56 @@ Each module can be independently enabled or disabled via configuration.
 
 ## Configuration
 
-HyperEssentials uses a split configuration system:
-
-- `config.json` - Core settings (prefix, colors, admin)
-- `config/homes.json` - Home module settings
-- `config/warps.json` - Warp module settings
-- `config/spawns.json` - Spawn module settings
-- `config/teleport.json` - TPA module settings
-- `config/warmup.json` - Warmup/cooldown settings
-- `config/kits.json` - Kit module settings
-- `config/moderation.json` - Moderation settings
-- `config/vanish.json` - Vanish settings
-- `config/utility.json` - Utility settings
-- `config/announcements.json` - Announcement settings
-- `config/rtp.json` - Random teleport settings
+HyperEssentials uses a split configuration system with per-module config files:
+
+- `config.json` — Core settings (prefix, colors, admin, storage)
+- `config/homes.json` — Home module (limits, bed sync, faction restrictions)
+- `config/warps.json` — Warp module (default category)
+- `config/spawns.json` — Spawn module (default spawn, join/respawn teleport)
+- `config/teleport.json` — TPA and RTP settings (timeouts, back history, RTP radius)
+- `config/warmup.json` — Per-module warmup/cooldown timers
+- `config/kits.json` — Kit module (default cooldown, one-time claims)
+- `config/moderation.json` — Moderation (default reasons, broadcast toggles, freeze interval)
+- `config/vanish.json` — Vanish (fake join/leave messages)
+- `config/utility.json` — Utility commands (per-command toggles, radius limits)
+- `config/announcements.json` — Announcement rotation (interval, randomize, messages)
+- `config/debug.json` — Debug logging (per-category toggles)
 
 ## Commands
 
-| Command | Description | Permission |
-|---------|-------------|------------|
-| `/hessentials reload` | Reload configuration | `hyperessentials.admin.reload` |
-| `/hessentials version` | Show version | - |
+See [docs/commands.md](docs/commands.md) for the complete command reference with all 46 commands, permissions, and aliases.
+
+### Quick Reference
+
+| Module | Commands |
+|--------|----------|
+| Admin | `/hessentials reload\|version` |
+| Homes | `/sethome`, `/home`, `/delhome`, `/homes` |
+| Warps | `/warp`, `/setwarp`, `/delwarp`, `/warps`, `/warpinfo` |
+| Spawns | `/spawn`, `/setspawn`, `/delspawn`, `/spawns`, `/spawninfo` |
+| Teleport | `/tpa`, `/tpahere`, `/tpaccept`, `/tpdeny`, `/tpcancel`, `/tptoggle`, `/back`, `/rtp` |
+| Kits | `/kit`, `/kits`, `/createkit`, `/deletekit` |
+| Moderation | `/ban`, `/tempban`, `/unban`, `/mute`, `/tempmute`, `/unmute`, `/kick`, `/freeze`, `/vanish`, `/punishments` |
+| Utility | `/heal`, `/fly`, `/god`, `/clearchat`, `/clearinventory`, `/repair`, `/near` |
+| Announcements | `/broadcast`, `/announce` |
+
+## Permissions
+
+See [docs/permissions.md](docs/permissions.md) for the complete permission reference. All nodes use the `hyperessentials` prefix.
+
+## Documentation
+
+Detailed documentation is available in the [docs/](docs/) directory:
+
+| Document | Description |
+|----------|-------------|
+| [Architecture](docs/architecture.md) | Package structure, module lifecycle, cross-module communication |
+| [Commands](docs/commands.md) | All 46 commands organized by module |
+| [Config](docs/config.md) | Configuration reference for core and all modules |
+| [Permissions](docs/permissions.md) | Permission nodes organized by module |
+| [Modules](docs/modules.md) | Module system overview, enable/disable, lifecycle |
+| [Storage](docs/storage.md) | Storage providers, JSON format, data directory layout |
+| [Integrations](docs/integrations.md) | HyperPerms, HyperFactions, VaultUnlocked integration |
 
 ## Building
 

build.gradle

@@ -1,11 +1,26 @@
 plugins {
     id 'java'
+    id 'checkstyle'
     id 'com.gradleup.shadow' version '9.3.1'
 }
 
 group = 'com.hyperessentials'
 version = '0.1.0'
 
+// ---------------------------------------------------------------------------
+// Hytale Maven version resolution
+// ---------------------------------------------------------------------------
+def resolveHytaleVersion(String channel) {
+    def url = "https://maven.hytale.com/${channel}/com/hypixel/hytale/Server/maven-metadata.xml"
+    def text = new URL(url).text
+    def matcher = text =~ /<release>(.+?)<\/release>/
+    if (!matcher.find()) throw new GradleException("Could not resolve Hytale server version from ${url}")
+    return matcher.group(1)
+}
+
+def hytaleChannel = project.findProperty('hytale_channel') ?: 'release'
+ext.hytaleVersion = resolveHytaleVersion(hytaleChannel)
+
 java {
     toolchain {
         languageVersion = JavaLanguageVersion.of(25)
@@ -14,6 +29,10 @@ java {
 
 repositories {
     mavenCentral()
+    maven {
+        name = 'hytale'
+        url = "https://maven.hytale.com/${hytaleChannel}"
+    }
 }
 
 dependencies {
@@ -95,3 +114,16 @@ tasks.withType(JavaCompile).configureEach {
     options.encoding = 'UTF-8'
     options.compilerArgs.addAll(['-Xlint:all', '-Xlint:-processing'])
 }
+
+checkstyle {
+    toolVersion = '10.26.1'
+    configFile = file('config/checkstyle/checkstyle.xml')
+    ignoreFailures = true
+}
+
+tasks.withType(Checkstyle).configureEach {
+    reports {
+        xml.required = true
+        html.required = true
+    }
+}