HyCommands

Requires AurumX

HyCommands is a lightweight, configurable server utility plugin for Hytale that consolidates common server features into a single, high-performance mod. It's designed for server operators who want robust defaults, safe async operations, and easy integration with other server-side plugins (for example, AurumX economy).

Core goals: performance, configurability, small footprint, safe async persistence, and predictable permission hooks.

• Player homes: per-player named homes with configurable limits, cooldowns and warmups.
• Warps: named server warps with per-warp permissions and easy management.
• Teleportation: /tpa, /tpaccept, /tpdeny, /back (includes death/back), /rtp (random safe teleport).
• Spawn management: /spawn, /setspawn (world-aware).
• Sleep management: configurable sleep percent to skip night, chat announcements, and graceful handling when players disconnect.
• Communication: /msg (private messages), /broadcast, automated join/quit/join messages and scheduled announcements.
• Admin utilities: /sethome (admin override), /delhome, /setwarp, /delwarp, /warps, /homes list, and permission-based control.
• Rate limiting & cooldowns: configurable per-command cooldowns to prevent abuse.
• Safe async persistence: player data saved in JSON under mods/HyCommands/ using a thread-safe JsonRepository.
• Economy hooks: optional AurumX integration (compileOnly dependency) for economy-based features (e.g., costing teleports or homes).
• Configurable messages and color codes (& style) with placeholders via MessageFormatter.
• Teleport safety: movement-cancel checks, warmups, chunk async loading, and safe landing detection (scan down to find ground).
• Permissions-first design: commands extend AbstractPlayerCommand and check requirePermission() up-front.
• Chat rooms: persistent per-room chat channels with join/leave management, per-room color and formatting, and configurable visibility. New chat commands: /chatrooms (list), /chatroom <join|leave|create|delete> [name], /chatcolor <color> (set your chat color for room messages).
• Player utilities: game-mode and movement helpers for server staff and quality-of-life for players: /gmc, /gma, /gamemode <mode>, /fly, /speed <value>, /heal, /feed, /god, /near <radius>, /ping, /playtime, /seen <player>, /playerlist.
• Teleport utilities (admin and player): /tp <player|x y z>, /tphere <player>, /tpall, /tppos <x> <y> <z>, /back, /switchworld <world>, /switchserver <address>.
• Economy integration (AurumX-backed): account and currency commands when AurumX is present: /balance [player], /balancetop, /pay <player> <amount>, admin money commands /addmoney <player> <amount>, /removemoney <player> <amount>, /setmoney <player> <amount>, and /currency to list currencies. Economy features are optional and enabled when AurumX is available on the server classpath.
• Player stats tracking: persistent playtime and join tracking used by /playtime, /seen, /playerlist, and to drive automated announcements or moderation tools.

These systems are configurable — see the configuration.md additions for chat and playerStats sections.

Commands (quick reference)

Command	Usage	Description
/sethome	/sethome [name]	Save your current location as a named home
/home	/home [name]	Teleport to a saved home
/delhome	/delhome [name]	Delete a saved home
/homes	/homes	List your saved homes
/setwarp	/setwarp <name>	Create a server warp at your location
/warp	/warp <name>	Teleport to a warp
/delwarp	/delwarp <name>	Remove a warp
/warps	/warps	List available warps
/tpa	/tpa <player>	Send a teleport request to another player
/tpaccept	/tpaccept	Accept an incoming teleport request
/tpdeny	/tpdeny	Deny an incoming teleport request
/back	/back	Return to your previous location (supports death/back)
/rtp	/rtp	Random safe teleport
/spawn	/spawn	Teleport to world spawn
/setspawn	/setspawn	Set the world spawn point
/sleeppercent	/sleeppercent [value]	Set required percent of players to sleep
/msg	/msg <player> <message>	Send a private message
/broadcast	/broadcast <message>	Send server-wide announcement

Additional commands added in the patch

Command	Usage	Description
/chatrooms	/chatrooms	List configured chat rooms
/chatroom	/chatroom <join|leave|create|delete> [name]	Manage or join chat rooms
/chatcolor	/chatcolor <color>	Set your chat color for room messages
/gmc	/gmc	Set creative mode (admin)
/gma	/gma	Set adventure mode (admin)
/gamemode	/gamemode <mode> [player]	Change a player's game mode
/fly	/fly [on|off]	Toggle flight
/speed	/speed <value>	Set player movement speed
/heal	/heal [player]	Restore health
/feed	/feed [player]	Restore hunger
/god	/god [player]	Toggle invulnerability
/near	/near [radius]	List nearby players or entities
/ping	/ping [player]	Show network latency
/playtime	/playtime [player]	Show playtime statistics
/seen	/seen <player>	Show last seen time for a player
/playerlist	/playerlist	List online players with basic stats
/tp	/tp <player|x y z>	Teleport player or to coordinates
/tphere	/tphere <player>	Bring a player to you
/tpall	/tpall	Teleport everyone to you
/tppos	/tppos <x> <y> <z>	Teleport to specific coordinates
/switchworld	/switchworld <world>	Move player to another world
/switchserver	/switchserver <address>	Connect player to an external server (if supported)
/balance	/balance [player]	Show economy balance (AurumX)
/balancetop	/balancetop	Show top balances (AurumX)
/pay	/pay <player> <amount>	Pay another player (AurumX)
/addmoney	/addmoney <player> <amount>	Admin: add money (AurumX)
/removemoney	/removemoney <player> <amount>	Admin: remove money (AurumX)
/setmoney	/setmoney <player> <amount>	Admin: set balance (AurumX)
/currency	/currency	List currencies provided by AurumX

For full command options and permissions, see the commands.md in this module.

Permissions (high level)

• hycommands.home — use homes
• hycommands.home.set — set homes
• hycommands.home.limit.<n> — grant home slots (highest wins)
• hycommands.warp — use warps
• hycommands.warp.set — create warps
• hycommands.warp.use.<name> — use a specific warp
• hycommands.warp.bypass — ignore warp protections
• hycommands.tpa — send teleport requests
• hycommands.tpaccept — accept teleport requests
• hycommands.spawn.set — set spawn
• hycommands.admin.* — administrative commands (broadcast, delhome, delwarp, etc.)

Permissions are intentionally flat and simple — see permissions.md for the exhaustive list and examples.

Configuration highlights

Configurations are written to mods/HyCommands/hycommands.json. Key configurable sections:

• homes — default limits, cooldowns, warmups
• warps — public/private defaults and per-warp permissions
• teleport — warmup durations, movement-cancel thresholds, cooldown times
• sleep — requiredPercent to skip night
• messages — templates for announcements, placeholders like {player}, {time}
  • chat — chat rooms, per-room color, visibility, and permissions
  • playerStats — enable/disable playtime and join tracking, retention and storage options

Minimal example (hycommands.json excerpt):

{
  "homes": {
    "defaultLimit": 3,
    "cooldownSeconds": 30
  },
  "teleport": {
    "warmupSeconds": 5,
    "movementCancel": 1.5
  },
  "sleep": {
    "requiredPercent": 50
  }
}

See configuration.md for the full schema and defaults.

Building and installing

Build the jar with Gradle (root or module):

./gradlew :hycommands:shadowJar

Drop the produced HyCommands-<version>.jar into your server mods/ folder and restart the server. The plugin will generate a config in mods/HyCommands/ on first run.

Notes:

• The project compiles against a TestServer/HytaleServer.jar (compileOnly) — ensure server/TestServer/HytaleServer.jar is present for local builds.
• Optional AurumX economy integration is available; the module is compiled compileOnly(project(":aurumx")) so include the AurumX module on the classpath for related features.

Data storage

Player and server data are stored under mods/HyCommands/ in JSON format using a thread-safe JsonRepository. The repository writes off the main thread to avoid server stalls.

Community & Support

• Discord: https://discord.gg/TJc3CxR4jK
• GitHub: https://github.com/MeherBenSalem/jauml
• Website: https://nightbeam.dev
• Store: https://nightbeam.dev/store
• CurseForge: https://www.curseforge.com/members/nightbeamstudio/projects
• Modrinth: https://modrinth.com/organization/nightbeam

License

Feel free to include HyCommands in modpacks.

Please do not redistribute modified versions without permission.