Hyssentials Documentation

Essential server commands and a powerful rank-based configuration system for Hytale servers. Manage teleportation, homes, warps, and player ranks with an intuitive in-game UI.

Features

• Teleport Requests - TPA system with configurable cooldowns, timeouts, and player selection UI
• Private Messaging - Send private messages with /msg and /r (reply)
• Admin Chat - Configurable staff/admin chat channels with /a command
• Homes System - Players can set and teleport to personal home locations with an interactive UI
• Server Warps - Admin-defined warp points with a warp selection UI
• Random Teleport - Teleport to random safe locations in the world
• Rank System - Fully customizable ranks with per-command settings
• Warmup & Cooldowns - Configurable delays and cooldowns per rank
• Admin UI - In-game graphical interface for rank management
• Interactive GUIs - Run commands without arguments to open selection UIs
• Vanish Mode - Staff can become invisible to other players with /vanish
• Fly Mode - Staff can toggle flight mode with /fly
• Custom Join Messages - Customize player join and leave messages with placeholders

Installation

1. Download the latest Hyssentials JAR file
2. Place the JAR in your server's plugins folder
3. Restart your server
4. The plugin will generate default configuration files automatically

Quick Start

Once installed, all player commands are available immediately. Here's what your players can do:

Teleport Requests (TPA)

The TPA system allows players to request teleportation to other players with their consent.

Player Selection UI

Running /tpa or /tpahere without a player name opens an interactive GUI showing all online players:

Click a player to send them a teleport request

Private Messaging

Send private messages to other players. The reply command remembers who you last messaged.

Aliases

• /msg - also available as /tell, /whisper, /w, /pm
• /r - also available as /reply

Homes

Players can save personal locations and teleport back to them at any time.

Home Selection UI

Running /home without a name opens an interactive GUI showing all your homes:

View, teleport to, or delete your homes from the UI

Home Limits

The number of homes a player can set is determined by their rank. Default players get 5 homes, while VIP players get 10. This is fully customizable in the rank settings.

Warps

Server warps are admin-defined teleport points available to all players.

Warp Selection UI

Running /warp without a name opens an interactive GUI showing all server warps:

Browse and teleport to server warps from the UI

Spawn

Teleport to the server spawn point.

If no custom spawn is set, players will teleport to the world's default spawn point.

Random Teleport (RTP)

Teleport to a random safe location in the world. Great for exploration or finding new places to build.

How It Works

• Searches for a random location between 100-5000 blocks from spawn
• Automatically finds a safe spot (solid ground with air above)
• Pre-loads the destination chunk to prevent issues
• Includes configurable warmup and cooldown per rank

Back

Return to your previous location. Works after teleporting or dying!

The plugin remembers your last 5 locations (configurable) so you can use /back multiple times.

Admin Commands

Administrative commands for server management.

Teleport Commands

Vanish

Fly

Hyssentials Admin Commands

Admin Chat

Private chat channels for staff members. Messages are only visible to players with the appropriate permission.

Aliases

/a is also available as /adminchat and /ac.

Chat Groups

Admin chat supports multiple groups, each with its own permission. By default, two groups are configured:

Custom Join/Leave Messages

Customize the messages shown when players connect to the server or move between worlds/instances. By default, this feature is disabled and Hytale's default messages are used.

Message Types

Hyssentials distinguishes between server connections and world transitions:

Configuration

Edit joinmessages.json in the plugin data folder:

{
  "enabled": true,
  "serverJoinMessage": "7FF55&b{player} &rhas joined the server",
  "serverLeaveMessage": "&#FF5555&b{player} &rhas left the server",
  "worldEnterMessage": "&#AAAAAA{player} entered &#FFAA00{world}",
  "worldLeaveMessage": "&#AAAAAA{player} left &#FFAA00{world}"
}

Placeholders

Formatting

Messages support color and style formatting. See the Formatting Guide for details.

Example Configurations

Simple (No Colors)

{
  "enabled": true,
  "serverJoinMessage": "{player} has joined the server",
  "serverLeaveMessage": "{player} has left the server",
  "worldEnterMessage": "{player} entered {world}",
  "worldLeaveMessage": "{player} left {world}"
}

Colorful

{
  "enabled": true,
  "serverJoinMessage": "7FF55+ &b{player} &rjoined",
  "serverLeaveMessage": "&#FF5555- &b{player} &rleft",
  "worldEnterMessage": "󙀸{player} → &#FFAA00{world}",
  "worldLeaveMessage": "󙀸{player} ← &#FFAA00{world}"
}

Rank System

Hyssentials features a powerful rank-based configuration system. Each rank can have its own settings for every command.

How Ranks Work

• Ranks are defined in ranks.json
• Each rank has a unique permission: hyssentials.rank.<id>
• Players get the highest priority rank they have permission for
• Each rank configures: max homes, cooldowns, warmups, and enabled commands

Default Ranks

Hyssentials comes with two pre-configured ranks:

Per-Command Settings

Each rank can configure the following for every teleport command:

• Enabled - Whether the rank can use the command
• Cooldown - Seconds between uses (0 = no cooldown)
• Warmup - Delay before teleport (0 = instant). Moving cancels the teleport.

Granted Permissions

Ranks can grant additional permissions to players. This is useful for integrating with other plugins. When a player receives a rank, they automatically get all permissions listed in that rank's "Granted Permissions".

Rank Management UI

Manage ranks directly in-game with the graphical interface. Run /hyssentials rank to open.

The Rank Management screen showing all configured ranks

Creating/Editing Ranks

Click "Create" or "Edit" to open the rank editor:

Configure rank ID, display name, priority, max homes, and command settings

Configure RTP settings and grant additional permissions

Rank Settings Explained

• ID - Unique identifier (lowercase, no spaces). Used in the permission node.
• Display Name - Human-readable name shown in UIs
• Priority - Higher priority ranks are checked first (0-100)
• Max Homes - Maximum number of homes players with this rank can set

Assigning Ranks to Players

Use the assignment UI to manage which ranks players have. Run /hyssentials assign to open.

Assign or remove ranks from online players

How to Assign Ranks

1. Open the UI with /hyssentials assign
2. Find the player (use search if needed)
3. Select a rank from the dropdown
4. Click + to add the rank or - to remove it

Configuration Files

All configuration is stored in JSON files in the plugin data folder.

config.json

Main configuration file with global settings:

{
  "ConfigVersion": 4,
  "BackHistorySize": 5,
  "DefaultRankId": "default"
}

Data Files

• homes.json - Player home locations
• warps.json - Server warp points
• spawn.json - Custom spawn point
• ranks.json - Rank definitions

ranks.json Structure

The complete rank configuration format:

{
  "ranks": [
    {
      "id": "default",
      "displayName": "Default",
      "priority": 0,
      "maxHomes": 5,
      "homeSettings": {
        "enabled": true,
        "cooldownSeconds": 60,
        "warmupSeconds": 3
      },
      "warpSettings": { ... },
      "spawnSettings": { ... },
      "backSettings": { ... },
      "tpaSettings": {
        "enabled": true,
        "cooldownSeconds": 30,
        "warmupSeconds": 0,
        "timeoutSeconds": 60
      },
      "rtpSettings": {
        "enabled": true,
        "cooldownSeconds": 300,
        "warmupSeconds": 5
      },
      "grantedPermissions": []
    },
    {
      "id": "vip",
      "displayName": "VIP",
      "priority": 10,
      "maxHomes": 10,
      ...
    }
  ]
}

adminchat.json Structure

Configuration for admin chat groups:

{
  "groups": [
    {
      "id": "staff",
      "displayName": "Staff Chat",
      "permission": "hyssentials.adminchat.staff",
      "prefix": "[STAFF]"
    },
    {
      "id": "admin",
      "displayName": "Admin Chat",
      "permission": "hyssentials.adminchat.admin",
      "prefix": "[ADMIN]"
    }
  ],
  "defaultGroup": "staff"
}

Group Properties

joinmessages.json Structure

Configuration for custom join and leave messages:

{
  "enabled": false,
  "serverJoinMessage": "{player} has joined the server",
  "serverLeaveMessage": "{player} has left the server",
  "worldEnterMessage": "{player} entered {world}",
  "worldLeaveMessage": "{player} left {world}"
}

Properties

Language Files

Hyssentials supports multiple languages through JSON language files located in the lang folder inside the plugin JAR. Currently supported languages:

• en.json - English (default)
• fr.json - French

Message Categories

Language files contain all user-facing messages organized by category:

Example Message Structure

{
  "error": {
    "no_permission": {
      "home": "<red>You don't have permission to use /home.</red>",
      "warp": "<red>You don't have permission to use /warp.</red>"
    },
    "home_not_found": "<red>Home '<yellow>%s</yellow>' not found.</red>",
    "instance_world_home": "<red>You cannot set a home in an instance world. Instance worlds are temporary and will be destroyed when you leave.</red>"
  },
  "success": {
    "home_set": "<green>Home '<yellow>%s</yellow>' set at <gray>%.1f, %.1f, %.1f</gray></green>"
  }
}

Placeholders

Messages use Java's String.format() placeholders:

• %s - String (player names, home names, etc.)
• %d - Integer (cooldown seconds, counts, etc.)
• %.1f - Decimal with 1 decimal place (coordinates)

Color Tags

Messages support MiniMessage-style color tags:

• <red>text</red> - Red text
• <green>text</green> - Green text
• <yellow>text</yellow> - Yellow text
• <orange>text</orange> - Orange text
• <gray>text</gray> - Gray text

Formatting Guide

Hyssentials supports formatting codes in join/leave messages to add colors and text styles. Use the & symbol followed by a code.

Style Codes

Color Codes

Use & followed by a hex color code to set text color:

Common Colors Reference

Combining Styles

You can combine multiple formatting codes. Codes apply to all text that follows until reset with &r.

// Green bold player name, then normal white text
"7FF55&b{player} &rhas joined the server"

// Result: [green bold]Steve[/green bold] has joined the server

// Red bold player name, gray "left", orange world name
"&#FF5555&b{player} &r󙀸left &#FFAA00{world}"

// Result: [red bold]Steve[/red bold] [gray]left[/gray] [orange]The Forgotten Temple[/orange]

Full Example

{
  "enabled": true,
  "serverJoinMessage": "7FF55&b+ {player} &r&#AAAAAAjoined the server",
  "serverLeaveMessage": "&#FF5555&b- {player} &r&#AAAAAAleft the server",
  "worldEnterMessage": "&#AAAAAA{player} entered &#FFAA00&b{world}",
  "worldLeaveMessage": "&#AAAAAA{player} left &#FFAA00&b{world}"
}

Permissions Reference

Rank Permissions

Each rank automatically generates a permission node:

• hyssentials.rank.default - Default rank
• hyssentials.rank.vip - VIP rank
• hyssentials.rank.<id> - Custom ranks

Admin Permissions

Admin Chat Permissions

Special Permissions

Legacy Permissions (Backwards Compatibility)

These permissions from older versions still work: