MysticEssentials v1.0.1

MysticEssentials v1.0.1 introduces the foundation of the new Portals Module, improves random teleport feedback, expands the public API for external integrations, and resolves several HUD and configuration issues.

---

Highlights

• Added the new Portals Module with asset-driven portal blocks.
• Added a dedicated RTP Status HUD for every stage of random teleportation.
• Added an automatic CurseForge Update Notifier.
• Expanded the Chat and Mail APIs for Discord bridges and external integrations.
• Fixed the AFK Zone HUD becoming frozen on-screen.
• Fixed administrator-managed default files being restored during reloads.
• Improved configuration migration and missing-setting handling.

---

Added

Portals Module

A new Portals Module has been added and is enabled by default.

Any block asset configured with the MysticPortal interaction can now function as a portal. Portal destinations can perform several different actions:

• Teleport players to another world.
• Teleport players to a world's spawn location.
• Teleport players to an exact position and facing direction.
• Refer players to another server.
• Execute a configurable command sequence.

Portal administrators can configure portals directly in-game by pressing Use (F) on a supported portal block.

Additional portal features include:

• Per-portal permission requirements.
• Optional world-map markers.
• Persistent portal configuration.
• Asset-driven portal registration.
• Portal codec registration and loading.
• An in-game Portal Administration interface.

Portal Commands

Command	Description	Permission
/portal list	Lists all registered portals, their types, targets, and locations.	mysticessentials.portal.admin
/portal edit	Opens the administration page for the nearest portal within eight blocks.	mysticessentials.portal.admin
/portal remove <id>	Removes a registered portal by its ID.	mysticessentials.portal.admin

Portals may also require an additional custom permission configured individually for that portal.

NOTICE

Wiki will be created soon for this once the foundation is completed and powering the interactions by assets will no longer be needed.

---

RTP Status HUD

Random teleportation now displays a dedicated status HUD throughout the entire teleport process.

The HUD can display:

• Warmup countdown.
• Safe-location searching status.
• Teleportation status.
• Successful completion.
• Cancellation.
• Search or teleport failure.

Completion, failure, and cancellation messages remain visible briefly before being removed automatically.

Silent RTP requests do not display the status HUD.

Safe-location searching has also been optimized to improve the random teleport process.

---

Update Notifier

MysticEssentials can now automatically check CurseForge for newer published versions.

The update check:

• Runs asynchronously without blocking the server.
• Runs when MysticEssentials starts.
• Repeats at a configurable interval.
• Compares the installed version with the newest published version.
• Logs an update warning to the server console.
• Displays a clickable update notification to authorized players when they join.
• Safely continues operating when CurseForge cannot be reached.

The following configuration section is now available:

"updateNotifier": {
  "enabled": true,
  "notifyOnJoin": true,
  "checkIntervalHours": 12
}

Players require the following permission to receive join notifications:

mysticessentials.update.notify

---

API and Integration Changes

Chat Publishing Event

Added ChatMessagePublishedEvent.

This event is fired after a local player's public message has completed the MysticEssentials chat pipeline, including:

• Message sanitization.
• Item-link expansion.
• Channel routing.
• Nickname resolution.
• Permission-group and rank-prefix resolution.

The event provides:

• Sender UUID.
• Account name.
• Display name.
• Channel ID and display name.
• Sanitized message content.
• Cross-server channel status.
• Primary permission group.
• Rank prefix.

The event is only fired on the message's origin server. Redis deliveries and externally injected messages do not fire it again, preventing bridge loops and duplicate messages.

---

External Channel Messages

Expanded ChatService with support for messages originating outside Hytale.

External integrations can now:

• Retrieve active temporary channel IDs.
• Broadcast an external message into a channel.
• Provide a custom format for externally sourced messages.
• Use supported placeholders such as the sender, channel, server ID, and message.

This provides the foundation for integrations such as MysticIdentity's Discord chat bridge.

---

Temporary Channel Events

Added temporary-channel lifecycle events:

• TemporaryChannelCreatedEvent
• TemporaryChannelClosedEvent
• TemporaryChannelMembershipChangedEvent

External integrations can now detect when:

• A temporary channel is created.
• A temporary channel is closed or expires.
• The server clears temporary channels.
• A player joins a temporary channel.
• A player leaves a temporary channel.
• A player implicitly leaves after disconnecting.

---

Mail Received Event

Added MailReceivedEvent.

External integrations can now detect when mail arrives for an online or offline player.

The event includes:

• Recipient UUID.
• Sender name.
• Plain-text body preview.
• Whether the mail contains rewards.
• Whether the recipient is currently online.

This provides support for external mail notifications, including Discord notification integrations.

---

Improved

Configuration Loading

Configuration files now support improved missing-key migration.

When an existing configuration is loaded:

• Missing settings are added from the current defaults.
• Existing administrator values remain unchanged.
• Nested configuration sections are merged recursively.
• Newly introduced settings automatically appear in older configurations.
• Invalid configuration files are not overwritten.

Module configuration loading can now use separate defaults for:

• Initial file generation.
• Updating an existing configuration.

This prevents example or administrator-managed collection entries from being restored after intentional removal.

---

Kit Configuration Preservation

The Kits Module no longer restores default kit entries after an administrator removes them.

Default kits are still generated for new installations, but existing kit collections are now treated as administrator-managed data.

---

Tutorial Default Files

Tutorial example files are now generated only once.

MysticEssentials records when the tutorial defaults have been initialized. After initialization:

• Deleted example tutorials are not recreated.
• Renamed tutorials are not recreated under their old names.
• Deleted tutorial pages remain deleted.
• Existing owner-managed tutorial files are preserved.
• Reloading or restarting no longer restores removed examples.

Existing installations are detected and adopted without regenerating previously removed files.

---

Documentation

Updated the project documentation with:

• Portals Module information.
• Portal commands.
• Portal permissions.
• Update-notification permissions.
• Updated module overview.
• Updated command reference.
• Updated permission reference.

---

Fixed

AFK Zone HUD Freezing

Fixed an issue where the AFK Zone reward HUD could become permanently frozen on-screen after a player left an AFK Zone.

HUD ownership is now handled exclusively by the AFK Zone update task, preventing competing scheduler tasks from re-adding a stale HUD after it has been removed.

---

Teleport HUD Conflicts

Fixed the teleport warmup HUD conflicting with other active HUDs.

The teleport HUD now uses the correct dedicated HUD identifier and lifecycle handling.

---

Default Files Regenerating

Fixed administrator-managed default files and entries being regenerated during /mystic reload or server restart.

This primarily affected:

• Kit definitions.
• Tutorial definitions.
• Tutorial pages.
• Tutorial localization.
• Tutorial example documentation.

---

RTP HUD Cleanup

Improved RTP HUD ownership and cleanup behavior.

Older RTP sessions can no longer remove or overwrite the HUD belonging to a newer random teleport request.

---

New Permissions

Permission	Description
mysticessentials.portal.admin	Grants access to portal commands and the portal administration interface.
mysticessentials.update.notify	Displays the clickable update notification when an authorized player joins.

Individual portals may also require custom permission nodes configured through the Portal Administration interface.

---

Configuration Changes

The following settings are automatically merged into existing config.json files when missing:

{
  "updateNotifier": {
    "enabled": true,
    "notifyOnJoin": true,
    "checkIntervalHours": 12
  },
  "modules": {
    "portals": true
  }
}

Existing configuration values are preserved during the merge.

---

Upgrade Notes

1. Replace the previous MysticEssentials JAR with version 1.0.1.
2. Start the server or run /mystic reload.
3. Review the newly generated updateNotifier configuration.
4. Assign mysticessentials.portal.admin to portal administrators.
5. Assign mysticessentials.update.notify to staff who should receive update alerts.
6. Configure portal-compatible assets with the MysticPortal interaction before creating portal destinations.