Mystic Essentials

The modular, API-first essentials foundation for Hytale servers — homes, warps, spawn, teleport requests, mail, chat formatting, private messages, announcements, AFK, greetings/MOTD, kits, flight, inventory snapshots, nicknames, and more. Every feature is a module you can toggle in config.json, and it integrates with LuckPerms, PlaceholderAPI, VaultUnlocked, and MysticVanish.

Built and tested against Hytale Server 0.5.6.

Installation

1. Drop MysticEssentials-1.0.0.jar into your server's mods/ folder.
2. Start the server once — it generates mods/MysticEssentials/config.json, the message bundle, and per-module config files.
3. (Optional) Install LuckPerms, PlaceholderAPI, and/or VaultUnlocked for permissions, placeholders, and economy features. They're auto-detected.
4. Edit configs, then run /mystic reload (or restart).

Storage defaults to local JSON. For production, set storage.provider to mysql or mariadb (driver + pool are bundled).

Migration support

Mystic Essentials includes an in-game, file-based migration flow for server owners moving from other Hytale essentials mods. The old mod jar does not need to be installed or loaded; only the old data files need to be present on disk.

Supported source names:

Recommended flow:

/mystic migrate scan <source> [path]
/mystic migrate import <source> [path]

If path is omitted, Mystic checks sibling folders under mods/, such as mods/EssentialsPlus, mods/Hyssentials, mods/EliteEssentials, mods/Essentials, and mods/HyEssentialsX. Use quotes around paths with spaces.

Current built-in imports:

Imports merge by default and skip existing Mystic entries with the same name. Use --replace only when you intentionally want legacy data to overwrite existing Mystic data. Use --dry-run with import to preview the import path without writing.

The importer writes timestamped backups of Mystic module files before changing them and never deletes source data. Mail, nicknames, chat formats, MOTD, economy balances, and moderation data still need manual migration or dedicated source-specific import support.

For detailed planning and validation, see Migration Guide.

Commands

Optional arguments are shown in [brackets], required in <angle brackets>. Player, home, and warp names autocomplete.

Core

Teleportation

Random Teleport

See the Random Teleport page for full details.

Spawn and homes

Warps

Mail

Chat

Announcements, AFK, and greetings

Kits

Flight

Inventory

Nicknames

Player Vaults

See the Player Vaults page. The module is disabled by default.

Patch Notes

See the Patch Notes page.

Tutorial

See the Tutorial module page for the full command tree.

Custom Commands

See the Custom Commands module page. Operator-defined commands are also registered dynamically.

Permissions reference

Every node is defined centrally in api/Permissions.java and documented in Permissions Wiki — the complete operator reference, including the dynamic nodes (home/player-warp limits, per-kit access, per-channel gates).

Numeric limits (homes, player warps) are resolved from the highest .limit.<n> node a player holds, or .limit.unlimited.

Message & colour formatting

Every message and config template supports this markup:

Hover text is not available — the Hytale 0.5.6 message protocol has no hover field (only links).

Configuration

Files live under mods/MysticEssentials/:

config.json                 Main config (storage, integrations, module toggles)
messages/en_us.json         Core message strings
modules/<module>/config.json   Per-module settings
data/                       Player profiles, module data, cache
logs/

Main config.json toggles storage (json / mysql / mariadb + optional Redis for cross-server), integrations (LuckPerms / PlaceholderAPI / VaultUnlocked), and which modules are enabled. New modules added in updates are merged into your existing config automatically.

Notable per-module settings:

• teleportation — requestExpirySeconds (pending /tpa lifetime), tpaWarmupSeconds, tpaCooldownSeconds, backWarmupSeconds, backCooldownSeconds.
• mail — maxInboxSize (0 = unlimited; oldest read mail dropped first when full), maxMessageLength (0 = unlimited; longer bodies truncated), notifyUnreadOnJoin.
• spawn — defaultHomeLimit, teleportOnFirstJoin, teleportOnJoin.
• chat — defaultFormat, priority-ordered formats (permission-gated), per-colour-style permissions, private messaging, channel definitions, temporary channels, configurable channel prefixes/aliases/passwords, and glyphs settings. /channel opens the packaged channel browser UI (Common/UI/Custom/MysticEssentials/ChatChannels.ui). Temporary channels are session channels: without Redis they stay open until the server is empty or restarts; with Redis enabled they can be restored after restart for temporaryChannelDefaultMinutes (default 120) minutes. modules/chat/glyphs.json is generated from the bundled glyph catalog.
• announcements — autoBroadcastEnabled, intervalSeconds, randomOrder, and messages. Message entries may be legacy strings or JSON objects: {"lines":["&7Line one","&fLine two"],"click":{"action":"command","value":"/spawn"}}. Use action: "link" with an https://... value to open a URL. Individual lines entries may also be objects with their own text and click.
• afk — autoAfkSeconds, plus a rewards block (reward zone corners, amount, session/daily caps, combat lockout) for the AFK Rewards submodule.
• greetings — MOTD lines, first-join message, and optional join/leave broadcasts.
• announcements — also broadcastPrefix and alertPrefix for /broadcast and /alert.
• kits — kit definitions (items, cooldownSeconds with -1 = one-time, requiredOnlineSeconds, requirePermission, cost, description) and firstJoinKit granted automatically on first join.
• flight — paidFlight, costPerMinute, and fly-speed multipliers.
• inventory — snapshot triggers (snapshotOnJoin/Leave/Death), timedSnapshotMinutes, and maxSnapshotsPerPlayer.
• nick — nickname length limits, blockedNames, and the nickMarker prefix shown before nicknames in chat.
• chat channels — each channel supports groupFormats, a map of LuckPerms primary group → chat format, overriding the channel format per rank.

Config files are versioned: each carries a configVersion and is migrated (plus merged with new default keys) automatically on load.

Integrations

• LuckPerms — permission checks, primary group, and {luckperms_prefix} / {luckperms_suffix} in chat and messages.
• PlaceholderAPI — resolves %…% placeholders, and exposes Mystic's own as %mystic_<name>% (e.g. %mystic_player_name%, %mystic_group%).
• VaultUnlocked — economy for paid warps, teleport costs, paid flight, kit costs, and AFK rewards. Requires an economy provider mod; without one, costs are free and payouts no-op.
• MysticVanish — vanished players are hidden from the TPA UI and player suggestions, treated as offline for /msg and /tpa, and join/leave/AFK announcements stay silent for them. Auto-detected; drop MysticVanish-1.0.0.jar in mods/.

Cross-server (multiple servers on one network) broadcasts and private messages work when Redis is enabled in config.json.

For developers

Look for the developer api here: Developer API