All notable changes to HyperEssentials will be documented in this file.
The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
/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
lastJoinvalue now updates on reconnect (connect handler was running before player data loaded into cache)- Disabled modules no longer show GUI tabs in player or admin navigation — pages dynamically check module enabled status at display time
- Built-in localization system with 10 languages: English, German, Spanish, French, Italian, Dutch, Polish, Portuguese, Russian, Filipino
- ~500 translation keys covering all commands, GUI labels, admin messages, and error text
- Player language auto-detection from client locale with per-player override
- Player Settings page with language selector accessible from GUI nav bar
I18nModulewith HyperFactions-compatible key format (hyperessentials_prefix for admin,hyperessentials.for player commands)- Localized
.langfiles inServer/Languages/<locale>/following Hytale conventions
- Sentry SDK integration for automated error reporting
ErrorHandlerutility wrapping all async operations with contextual breadcrumbs- All modules migrated to use
ErrorHandlerfor consistent error capture
/essimportcommand with adapter pattern for migrating from other essentials plugins- Importers for 4 plugins: EliteEssentials, Essentials (nhulston), EssentialsPlus, and HyEssentialsX
AbstractEssentialsImporterbase class with home/warp/spawn/kit import lifecycleWorldResolverutility for mapping world names across plugin formats- ZIP backup created automatically before import
- Config Editor — In-game config editing with tabbed sections for all 13 module configs, boolean toggles, numeric steppers, text inputs, and save/discard
- Player Moderation Page — Per-player punishment actions with type selection and duration input
- Updates Page — Check for plugin updates from within the admin GUI
- Player Search —
PlayerResolverandPlayerDBServicefor online/offline player lookup across admin pages - Bypass Toggle — Admin bypass enable/disable system gating all bypass permissions (except home limits)
ConfigSnapshottracking for validating config changes before save
- Player Settings Page — Locale selector with auto-detect language toggle, accessible from nav bar
- Kit Edit Modal — Edit kit display name, cooldown, one-time, permission, and per-item delete with preview
- Warp Edit Modal — Edit warp display name, category, description, and permission
- Warp/Kit Name Input — Name input dialog when creating warps and kits from admin GUI
- Automatic ZIP backup on data import and manual backup via admin GUI
- Backup storage in
backups/directory with timestamped filenames
ChatDelegationcoordinator for priority-based chat handling across Werchat, HyperPerms, and built-in formatters- Automatic detection of installed chat plugins with graceful fallback
- Direct API methods via
HyperFactionsIntegration.Delegatefor territory queries ESSENTIALS_BACKzone flag support for/backterritory restrictionsPlayerTerritoryChangeEventsubscription for territory-aware features- Bidirectional language preference sync between HyperEssentials and HyperFactions
HyperPermsProviderAdapterfor direct HyperPerms API access- Quick-add warp/kit permissions to HyperPerms roles from admin GUI (
admin_permission_add.ui)
CronScheduler— 5-field cron expression parser for per-announcement scheduling- Event announcements — join, leave, and first-join event handlers with placeholder support
- Announcement type toggle (CHAT vs NOTIFICATION) with per-announcement configuration
- Full CRUD for announcements via admin GUI
/warn <player> [reason]— issue warnings with staff notification broadcast- WARN punishment type tracked in punishment history
- Source tracking for
/backlocations (death, home, warp, spawn, rtp, tpa, factionhome) - Faction territory checks on
/backdestination withESSENTIALS_BACKzone flag support backFactionsconfig subsection with per-relationship toggles (mirrors homes config)
GuiColors— centralized semantic color constants (brand gold, text, status, backgrounds, dividers)UIPaths— centralized UI template path constants for all shared, player, and admin pagesPlayerPageData— BuilderCodec for player page events (Button, NavTarget, Target, Page)AdminPageData— BuilderCodec for admin page events (Button, NavTarget, Target, Value, Filter, Page)PlayerPageOpener/AdminPageOpener— static utilities to resolve and open pages from registriesGuiManager.openPlayerPage()/openAdminPage()— convenience methods for page openingNavBarHelper.setupAdminBar()— admin nav bar variant with "HE Admin" titleNavBarHelper.handleNavEvent()— overload withGuiTypefor admin/player nav routingUIHelper.formatPlaytime()— human-readable playtime formatting (Xd Xh Xm)hyperessentials.admin.guipermission node for admin panel access/he(no args) now opens player dashboard GUI (falls back to help text if no pages registered)/he adminopens admin dashboard GUI (requiresadmin.guipermission)- Shared
.uitemplates:styles.ui(HyperFactions-quality TextButtonStyle definitions),empty_state.ui,confirm_modal.ui,stat_row.ui
HomesPage— browse homes, teleport (with warmup), delete; shows count/limit headerWarpsPage— browse warps grouped by category with category headers, teleport with warmupKitsPage— browse available kits, claim with cooldown status display, preview items.uitemplates:homes_page.ui,home_entry.ui,warps_page.ui,warp_entry.ui,warp_category_header.ui,kits_page.ui,kit_entry.ui/homes,/warps,/kitscommands now open GUI pages (text fallback preserved)- Page registration in
HyperEssentials.registerPages()with correct display order (Homes=10, Warps=20, Kits=30)
AdminDashboardPage— server overview with online count, warp/spawn/kit stats, module status grid (enabled/disabled indicators)AdminWarpsPage— list all warps sorted by category, create at current location, deleteAdminSpawnsPage— list all spawns with default badge, create at current location, deleteAdminKitsPage— list all kits with item count/cooldown/one-time info, create from inventory, delete.uitemplates:admin_dashboard.ui,admin_module_card.ui,admin_warps.ui,admin_warp_entry.ui,admin_spawns.ui,admin_spawn_entry.ui,admin_kits.ui,admin_kit_entry.ui- Admin page registration in
HyperEssentials.registerPages(): Dashboard(0), Warps(20), Spawns(30), Kits(40) /he adminnow navigable to all 4 admin tabs
PlayerDashboardPage— welcome screen with stat cards (homes, online players, TPA requests), quick action buttons, playtime/join infoTpaPage— incoming TPA requests with per-entry accept/deny, toggle TPA acceptance on/off, time remaining displayStatsPage— player stats (first joined, last login, total playtime, current session) and status indicators (AFK, Fly, God, Infinite Stamina).uitemplates:dashboard.ui,stats.ui,tpa_page.ui,tpa_entry.uiUtilityManager.getSessionStart()— new public accessor for session start time- All 6 player GUI tabs now functional: Dashboard(0), Homes(10), Warps(20), Kits(30), TPA(40), Stats(50)
AdminPlayersPage— list online players sorted by name with UUID previewAdminModerationPage— punishment list with active/all filter, revoke functionality; type-colored badges (BAN=red, MUTE=gold, KICK=cyan)AdminAnnouncementsPage— read-only view of announcement messages, interval, and sequential/random modeAdminSettingsPage— version info, data directory, config reload button, module status grid with enabled/disabled indicatorsModerationManager.getAllPunishments(boolean)— new method to query all punishments across all players (supports active-only filter).uitemplates:admin_players.ui,admin_player_entry.ui,admin_moderation.ui,admin_punishment_entry.ui,admin_announcements.ui,admin_announcement_entry.ui,admin_settings.ui,admin_module_toggle.ui- Admin page registration: Players(10), Moderation(50), Announcements(60), Settings(70)
- Complete GUI system: 14 pages (6 player + 8 admin) all functional
/motd— display configurable message of the day/rules— display server rules/discord— display Discord invite link/list(aliases:/online,/players) — show sorted online player list with count/playtime(alias:/pt) — show total playtime including current session/joindate(alias:/firstjoin) — show first join timestamp/afk(alias:/away) — toggle AFK status with server-wide broadcast/stamina(alias:/stam) — toggle infinite stamina with periodic enforcement/maxstack(alias:/stack) — set held item quantity to max stack size/sleeppercentage(aliases:/sleeppct,/spc) — view/set sleep skip percentage threshold/invsee <player>— stub for inventory viewing (GUI coming later)/trash— stub for disposal inventory (GUI coming later)/repairmax(alias:/fixmax) — fully restore held item including max durability reset/durability(alias:/dura) — set or reset max durability on held items/previewkit(aliases:/vkit,/viewkit) — preview kit contents without claiming
/ipban <player> [duration] [reason]— ban player's IP with smart duration detection/ipunban <ip>— unban an IP addressIpBanrecord with expiration support (permanent and temporary)- IP tracking on player connect via
ModerationManager - Connect-time IP ban enforcement in
ModerationListener - IP ban persistence in
ModerationStorage("ipBans"JSON section) - Same-IP kick on ban (disconnects all players on the banned IP)
PlayerStatsrecord (uuid, username, firstJoin, totalPlaytimeMs, lastJoin)PlayerStatsStoragewith JSON persistence atdata/playerstats.json- Session tracking in
UtilityManagerwith playtime accumulation across sessions - Connect handler infrastructure in
HyperEssentialscore (mirrors disconnect handler)
- Manual AFK toggle via
/afkcommand with server-wide broadcast - Auto-AFK detection via configurable idle timeout (
afkTimeoutSeconds) - Auto-unset AFK on player activity (chat, interact, mouse motion, movement)
- Activity tracking via
PlayerChatEvent,PlayerInteractEvent, andPlayerMouseMotionEventlisteners - Position-based movement detection via periodic polling (Hytale has no PlayerMoveEvent)
- Toggle-based infinite stamina via
UtilityManagerstate tracking - Periodic enforcement via
ScheduledExecutorService(every 1 second) - Uses
EntityStatsModulecomponent withDefaultEntityStatTypes.getStamina()for targeted stat maximization - Support for targeting other players with
stamina.otherspermission
- Auto-import spawn points from Hytale
WorldConfigISpawnProvideron fresh install SpawnManager.importWorldSpawns()for manual import via/he importspawns
/he helpsubcommand with full command listing grouped by module- Each module section only shown if the module is enabled
- 12 new command enable toggles (motd, rules, discord, list, playtime, joindate, afk, invsee, stamina, trash, maxstack, sleepPercentage)
- Content fields:
motdLines,ruleLines,discordUrl - AFK config:
afkTimeoutSeconds(default 300, 0 = disabled) - Sleep config:
sleepPercentagewith per-world overrides
utility.motd,utility.playtime,utility.joindate,utility.afkutility.invsee,utility.stamina,utility.stamina.othersutility.trash,utility.maxstack,utility.sleeppercentagemoderation.ipban
- Homes:
deletehome/rmhome/removehome,listhomes/homelist,createhome - Teleport:
tpy,tpc,tpn,tpt,tpr - Kits:
ckit,dkit - Utility:
cc,fix - Warps:
createwarp - Announcements:
bc - Moderation:
pun
- Unified admin and player GUI styling to match HyperFactions quality standards
- All config module classes now have setters for live in-game editing support
- Kit data model expanded with
withDisplayName,withCooldownSeconds,withOneTime,withPermission,withItemscopy methods
- All commands, GUI pages, and integration messages migrated from hardcoded strings to i18n keys via
ErrorHandler - Homes, warps, spawns, teleport, kits, moderation, utility, announcements, and GUI pages all localized
/ban <player> [duration] [reason]— unified syntax with smart duration detection (replaces/ban+/tempban)/mute <player> [duration] [reason]— unified syntax with smart duration detection (replaces/mute+/tempmute)tempbanalias added to/ban,tempmute/tmutealiases added to/mute
- Kit items now support 4 inventory sections (hotbar, storage, armor, utility) instead of flat slot numbering
- Inventory space pre-check with
INSUFFICIENT_SPACEresult before claiming - Displaced armor/utility items automatically moved to hotbar/storage
- Backward-compatible deserialization from old flat-slot format
- Replaced Creative/Adventure gamemode hack with proper
MovementManager.canFlytoggle - Uses
UpdateMovementSettingspacket for client-side flight mode - Cross-player fly toggle disabled pending entity ref resolution
- Added "already full durability" check before repairing
- Uses
withDurability(maxDurability)instead ofwithRestoredDurability()
- Auto-completion via
ScheduledExecutorServicereplaces manual polling - Added
bypass.warmupandbypass.cooldownpermission checks - Cancels existing warmup before starting a new one
- Clean shutdown lifecycle for plugin disable
- All teleport commands use
executeTeleportcallback pattern withonCompleterunnable - Added
ref.isValid()safety check before teleporting - Switched to
Teleport.createForPlayer()for proper API usage - Store retrieval deferred to world thread for thread safety
- Added
rtpSafetyAirAboveHeadconfig (default 10) to prevent underground RTP placement - RtpManager scans for solid blocks above landing position
TempBanCommand.java— merged intoBanCommandTempMuteCommand.java— merged intoMuteCommand
AdminSettingsPage— replaced by in-game Config Editor with full per-module editing
- Server API 2026.03.26 compatibility — updated
disconnect()calls fromdisconnect(String)todisconnect(Message.raw(String))in ModerationManager and ModerationListener (API removed String overload) - Spawn detection now shows all worlds and ensures global spawn always exists
- Admin GUI crash from i18n key mismatch (
hyperessentials_adminvshyperessentials.adminformat) - Warp and kit creation UX — proper name input dialogs instead of auto-generated names
- Infinite stamina enforcement now dispatches to world thread via
world.execute()(fixesPlayerRef.getComponent() called asyncerror spam) - AFK status now properly clears on player movement (added position polling and mouse motion listener)
/healonly maximizes health stat instead of all stats (avoids unnecessary regen visual effects)/staminamaximize usesDefaultEntityStatTypes.getStamina()instead of iterating all stats- Manifest
IncludesAssetPackset to false (plugin has no bundled assets)
- Chunk-based random location selection with multi-attempt safety verification
findSafeY()heightmap scan withBlockMaterial+ fluid-aware safety checks (avoidWater, avoidDangerousFluids)- Faction claim avoidance with configurable chunk buffer radius via
HyperFactionsIntegration BorderHookinterface for future HyperBorder world border enforcementRtpChunkUtilutility for 32-block chunk coordinate mathRtpResultsealed interface withSuccess(Location)andFailure(String)recordsplayerRelativeconfig option — center RTP ring on player position (default) or fixedcenterX/Zrtp.factionAvoidanceconfig subsection (enabled,bufferRadius)rtp.safetyconfig subsection (avoidWater,avoidDangerousFluids,minY,maxY)hyperessentials.rtp.bypass.factionspermission node- "Searching for a safe random location..." feedback message before search begins
- Found coordinates shown in warmup message: "Found location at (X, Y, Z). Teleporting in Ns..."
- Updated README with complete module table (status, default state), optional dependencies, command quick reference, and docs index
- Updated architecture docs with full package tree including all data records, modules, managers, commands, listeners, and migration framework
- Updated commands docs with all 46 commands across 9 modules (kits, moderation, utility, announcements)
- Updated integrations docs with HyperFactions territory checker, VaultUnlocked economy, LuckPerms, and current Ecotale/Werchat status
- Updated modules docs with correct config file paths, implementation status, and debug configuration section
- Updated storage docs with kits/punishments storage, complete data directory layout, and migration system
- Updated docs index (readme.md) with completion status for all documentation pages
- RTP search now runs on world thread via
currentWorld.execute()for chunk/block access - Player position obtained via
TransformComponent(matches HyperFactions stuck pattern) - Replaced
java.util.RandomwithThreadLocalRandom maxAttemptsconfig now actually used (was previously ignored)- Y coordinate resolved from heightmap scan instead of hardcoded 64
findRandomLocation(String worldName)method (replaced byfindSafeRandomLocation())
Homeimmutable record with timestamps,create()factory,withLastUsed()andwithLocation()update methodsPlayerHomescollection with case-insensitive lookup (lowercase keys, original casing preserved)HomeManagerwith CRUD operations, player cache lifecycle (load on connect, flush on disconnect), permission-based limit resolution (unlimited → limit.N → config default), and bed syncLocation.fromHome()factory method for consistency with existingfromWarp()andfromSpawn()HomeStorageinterface withloadPlayerHomes()andsavePlayerHomes()methodsJsonHomeStorageimplementation with per-player JSON files indata/players/homes/, atomic writes/sethome [name]— set a home with name validation ([a-zA-Z0-9_-]{1,32}), faction territory check, and limit enforcement/home [name]— teleport to a home with faction territory check on destination, warmup/cooldown via WarmupManager/delhome <name>— delete a home with available homes listed on error/homes— list all homes with count/limit display (e.g. "Your homes (2/3)")
- HyperFactions added to
manifest.jsonSoftDependencies for load ordering FactionTerritoryCheckerwithResultenum (ALLOWED, BLOCKED_OWN/ALLY/ENEMY/NEUTRAL/WILDERNESS) andcanUseHome()static methodHomesConfigfactions subsection with per-relationship toggles:enabled(master toggle),allowInOwnTerritory,allowInAllyTerritory,allowInNeutralTerritory,allowInEnemyTerritory,allowInWilderness- Faction bypass permissions:
bypass.factions(wildcard),bypass.factions.sethome,bypass.factions.home HOME_TELEPORTandHOME_LIMIT_PREFIXpermission constants
- Checkstyle linting (10.26.1) with 2-space indent, 120-char lines, relaxed Javadoc rules
- Category-based debug logging via
Logger.DebugCategory(12 categories: homes, warps, spawns, teleport, kits, moderation, utility, rtp, announcements, integration, economy, storage) DebugConfigmodule config with per-category toggle andapplyToLogger()- Migration framework:
Migrationinterface,MigrationTypeenum,MigrationOptions,MigrationResult,MigrationRegistry,MigrationRunnerwith ZIP backup and rollback - VaultUnlocked economy integration via
VaultEconomyProvider(reflection-based lazy init) - Standard directory structure:
config/,data/,data/players/,backups/,data/.versionmarker ConfigFile.hasNewKeys()auto-detection for missing config keys on load
- Reformatted all Java files to 2-space indentation (aligned with HyperFactions code style)
- Logger upgraded from
java.util.logging.Loggerto HytaleLogger (Flogger) withlogger.at(Level).log()pattern - RTP module merged into Teleport module (RtpManager, RtpCommand moved to
module.teleportpackage) - RTP config merged into
TeleportConfigunder"rtp"subsection EcotaleIntegrationnow uses reflection detection instead of stubmanifest.jsonsoft dependencies expanded: HyperPerms, VaultUnlocked, LuckPerms
- Standalone RTP module (
module.rtppackage,RtpConfig)
DurationParserutility for parsing human-readable durations ("1h30m", "7d") and formatting- Categorized
Permissionsconstants: KIT, MODERATION, UTILITY, ANNOUNCE, BYPASS, NOTIFY with wildcards CommandUtil.findOnlinePlayer()for case-insensitive online player lookup- Disconnect handler system in
HyperEssentialscore for session cleanup callbacks
KitandKitItemdata records for kit definitionsKitStoragefor JSON persistence of kit definitions (data/kits.json)KitManagerwith CRUD operations, cooldown tracking, one-time claim tracking, and inventory capture/kit <name>— claim a kit with permission and cooldown checks/kits— list available kits filtered by player permissions/createkit <name>— capture current inventory as a new kit definition/deletekit <name>— remove a kit definitionKitsConfigwithdefaultCooldownSecondsandoneTimeDefaultsettings
Punishmentrecord with ban/mute/kick types, expiry, and revocation trackingModerationStoragefor JSON persistence of punishment history (data/punishments.json)ModerationManagerfor ban/mute/kick operations with broadcast and staff notificationsFreezeManagerwith position-locked movement checking viaScheduledExecutorServiceVanishManagerusingHiddenPlayersManagerwith fake disconnect/connect messagesModerationListenerfor ban enforcement on connect and mute enforcement on chat/ban,/tempban,/unban— permanent and temporary bans with reason support/mute,/tempmute,/unmute— permanent and temporary mutes/kick— kick with custom reason, broadcast, and staff notifications/freeze— toggle position freeze with movement prevention/vanish— toggle vanish with configurable fake leave/join messages/punishments <player>— view punishment historyModerationConfigwith default messages, broadcast toggles, freeze interval, history limitsVanishConfigwith fake message toggles and vanish messages
UtilityManagerfor session-only fly/god state tracking (cleared on disconnect)/heal [player]— heal viaEntityStatsModulestat maximization/fly [player]— toggle Creative/Adventure mode as flight workaround/god [player]— toggleInvulnerableECS component/clearchat [player]— clear chat with configurable line count/clearinventory [player](alias/ci) — clear inventory viaPlayercomponent/repair— repair held item durability viawithRestoredDurability()/near [radius]— list nearby players with configurable default/max radiusUtilityConfigwith per-command enable flags, radius limits, and chat line settings
AnnouncementSchedulerwith configurable interval, sequential/random rotation/broadcast <message>— send formatted announcement to all players/announce list|add|remove|reload— manage announcement rotationAnnouncementsConfigwith interval, randomize, prefix/message colors, and message list
- Initial project scaffold with modular architecture (11 modules)
- Module system:
Moduleinterface,AbstractModulebase class,ModuleRegistrylifecycle manager - Module stubs: homes, warps, spawns, teleport, warmup, kits, moderation, vanish, utility, announcements, rtp
- Configuration system with
ConfigFilebase,CoreConfig, and per-module config files ConfigManagersingleton with load, reload, save, and validation- Permission integration with HyperPerms via reflection-based soft dependency
PermissionManagerwith chain-of-responsibility resolution (HyperPerms -> OP -> config fallback)- GUI framework:
PageRegistry,GuiManager,NavBarHelper,ActivePageTracker,RefreshablePage - Shared UI templates: styles, navigation bar, error page
- Universal warmup/cooldown system:
WarmupManager,CooldownTracker, per-module config - Storage framework:
StorageProviderinterface withHomeStorage,WarpStorage,SpawnStorage,PlayerDataStorage JsonStorageProviderstub implementation- Admin command
/hessentialswith reload and version subcommands - Soft dependency stubs for HyperFactions (territory), Ecotale (economy), Werchat (chat)
- Public API via
HyperEssentialsAPIsingleton - Event bus for cross-module communication
- Shared utilities:
Logger,TimeUtil,CommandUtil,UIHelper,Locationrecord - Full
Permissionsconstants class organized by module - Documentation: architecture, commands, config, permissions, modules, GUI, storage, integrations, API, warmup, migration