AvalonEssentials: The Ultimate Hytale RPG Suite

AvalonEssentials is a complete RPG framework that integrates Land Claims, Guilds, Dungeons, Advanced NPCs, Player Shops, and a Banking Economy into one seamless, high-performance package.

Installation

To install AvalonEssentials on your Hytale server, extract the release ZIP and copy the contents to your server's mods folder:

Extract the release package containing:
- AvalonEssentials.jar - The plugin file
- AvalonEssentials - Configuration folder
Copy to server mods folder: (DOWNLOAD ASSETS)

   mods/
   ├── AvalonEssentials.jar
   └── AvalonEssentials
       ├── manifest.json
       ├── player_shops.json
       ├── shop_config.json
       ├── Backups
       ├── Common
       ├── Guilds
       ├── Minigames
       ├── PlayerQuests
       ├── Protections
       ├── RPG
       ├── Server
       └── Templates

Restart the server to load the plugin.

Project History

Originally born as a specialized system for House Protection and Safe Zones, this project quickly evolved as more complex RPG mechanics were integrated. To better reflect its comprehensive nature and its role as the backbone of a true RPG experience, the project was renamed from "Home Claim Property Protection" to AvalonEssentials. Today, it stands as a modular and powerful toolkit for server owners.

Design Philosophy: GUI-First Experience

AvalonEssentials is built with a single core principle: Immersion through Interaction. We believe that a true RPG experience should feel like a real game, not a text-based terminal. By replacing traditional, immersion-breaking slash commands with high-quality Graphical User Interfaces (GUIs) and physical world interactions, we ensure that players stay focused on the world of Avalon. Whether you are managing your guild, checking your bank balance at an ATM, or tracking quests in your journal, every action is designed to be tactile, visual, and intuitive.

Accessing the System

The gateway to all AvalonEssentials features is the Avalon Book (avalontm:book) item.

Automatic Delivery: New players receive the Avalon Book in their hotbar upon joining the server.
Visual Interface: Holding this item and interacting provides instant access to all RPG hubs: Character RPG Management, Profiles, Property Management, Banking, Guilds, and the Quest Journal.
Unified Navigation: There are no slash commands required for gameplay; the Avalon Book serves as the central launcher for every plugin system.
Admin Tools: Administrative features and advanced zone management are integrated directly into the Avalon Book interface for authorized staff members.
HUD Integration: While holding the book, players receive on-screen hints and status updates regarding nearby zones and active selections.

RPG System: Core Progression

A complete character progression system with classes, attributes, profiles, and active skills.

Profile Management

Players can maintain multiple RPG Profiles through the Avalon Book, allowing them to switch between different character setups:

Separate Progression: Each profile has its own Level, XP, Attributes, and Class.
Inventory Sync: Player inventories and equipped gear are tied to their active profile.

Attribute System

Six core statistics that define character growth and mechanical bonuses:

Attribute	Effect	Calculation / Bonus
VIT	Vitality	+10 Max HP per point
INT	Intelligence	+2 Max Mana and +0.1 Mana Regen/sec per point
STR	Strength	Increases Physical Damage and carry capacity
AGI	Agility	Increases Attack Speed and Movement Speed
DEX	Dexterity	Increases Critical Hit Chance (1% per point)
STAM	Stamina	Increases Max Stamina and +0.5 Stamina Regen/sec per point

Class Specialization

Five distinct classes with unique skills and playstyles. Players select their class through the RPG Hub in the Avalon Book.

Knight (Tank)

Primary Stat: VITALITY
Description: Defensive specialist with crowd control and self-healing abilities.
Class Skills:
- Shield Bash - Stuns target and deals minor damage
- Fortify - Increases defense temporarily
- Taunt - Forces enemies to attack you
- Cleave - Area damage to surrounding enemies
- Second Wind - Restores health over time

Mage (Spellcaster)

Primary Stat: INTELLIGENCE
Description: Powerful ranged spellcaster with burst damage and teleportation.
Class Skills:
- Fireball - Launches a fire projectile at enemies
- Teleport - Instantly moves to target location
- Ice Barrier - Creates a protective ice shield
- Arcane Explosion - Area damage around caster
- Mana Shield - Converts mana into damage absorption

Assassin (DPS)

Primary Stat: DEXTERITY
Description: High burst damage dealer with mobility and poison effects.
Class Skills:
- Shadow Step - Teleports behind target
- Backstab - High damage from behind
- Poison Blade - Applies poison DOT
- Evasion - Chance to dodge attacks
- Assassinate - Finishing move on low HP targets

Druid (Support)

Primary Stat: INTELLIGENCE
Description: Nature-based healer and controller with transformations.
Class Skills:
- Healing - Restores health to target
- Nature's Burst - Area heal around caster
- Root - Immobilizes target
- Bear Form - Transforms into bear for defense
- Thorns - Reflects damage back to attackers

Paladin (Hybrid)

Primary Stat: INTELLIGENCE
Description: Holy warrior with healing and protective abilities.
Class Skills:
- Holy Smite - Holy damage to enemies
- Lay on Hands - Large burst heal
- Blessing - Buffs target stats
- Divine Shield - Complete damage immunity
- Retribution - Area holy damage

Skill System

Skill Categories

Category	Behavior	Example Skills
DAMAGE	Deals damage to target(s)	Fireball, Backstab, Holy Smite
HEAL	Restores health to target(s)	Healing, Lay on Hands
BUFF	Applies temporary stat modifications	Blessing, Evasion
DASH/TELEPORT	Moves player quickly	Shadow Step, Teleport

Target Types

Target Type	Description
SELF	Affects only the caster
SINGLE_TARGET	Affects one entity in front of caster
AREA	Affects all valid entities within radius

Target Filters

Filter	Behavior
SELF_ONLY	Only affects the caster
ENEMIES	Only affects hostile entities with EntityStatMap
ALLIES	Only affects: caster, party members, guild members
ALL	Affects any entity with EntityStatMap (except caster)

Ally Detection

The system automatically identifies allies to prevent accidental friendly fire and to target beneficial skills:

Players: Caster is always an ally. Party members and Guild members are automatically identified as allies.
NPCs/Mobs: Currently, NPCs and monsters are not treated as valid allies for skill targeting.

Skill Configuration (JSON)

Skills are configured via JSON files in mods/AvalonEssentials/RPG/Skills/:

{
  "id": "fireball",
  "name": "Fireball",
  "description": "Launches a fireball at enemies dealing 50 damage",
  "manaCost": 25,
  "cooldownMs": 5000,
  "minLevel": 1,
  "effectId": "fire_effect",
  "targetType": "PROJECTILE",
  "targetFilter": "ENEMIES",
  "range": 20.0,
  "radius": 3.0,
  "category": "DAMAGE",
  "power": 50.0,
  "requiredClassId": "mage"
}

Class Configuration (JSON)

Classes are configured via JSON files in mods/AvalonEssentials/RPG/Classes/:

{
  "id": "mage",
  "displayName": "Mage",
  "description": "Powerful spellcaster with fire and ice abilities",
  "baseAttributes": [0, 5, 0, 0, 0, 0],
  "statsPerLevel": [0, 2, 0, 0, 0, 0],
  "skills": ["fireball", "teleport", "ice_barrier", "arcane_explosion", "mana_shield"]
}

How Skills Work

Activating a skill is a seamless process managed by the RPG engine:

Activation: Players use the /cast command or interact with the RPG Hub to trigger a skill.
Requirements Check: The system automatically verifies if the player has the required Level, Class, and sufficient Mana. It also checks if the skill is currently on cooldown.
Execution: Once validated, the skill effect is applied based on its type:
- Targeted Skills: Automatically find the nearest valid target (Enemy or Ally) in front of the caster.
- Area Skills: Apply effects to all valid entities within a specified radius.
- Self Skills: Apply buffs or heals directly to the caster.
- Movement Skills: Instantly move the player via dashing or teleportation.

Commands

Command	Description
`/cast <skillId>`	Activate a skill

Economic Features

AvalonEssentials features a physical-first economy driven by world interactions.

Physical Currency (Coins)

Wealth is represented by physical Coin items dropped by mobs or found in loot. Players must collect and carry these assets.

ATM Banking System

Banking is handled exclusively via interactive ATM blocks:

Digital Storage: Deposit physical coins into your account via an ATM to protect them from loss upon death.
Interaction Hub: Manage your balance and view transaction history at any physical ATM.

Player Markets

Market Items: Establish personal shops using specialized Player Market items.
Interactive Browsing: Players interact directly with Market items in the world to buy goods.

Social and Community Features

Both Guild and Party systems are accessed directly through the Avalon Book interface.

Guilds

Hierarchy & Permissions: Manage ranks (Owner, Officer, Member) and permissions via the Guild Menu.

Minigame Engine

AvalonEssentials features a robust, action-based Minigame Engine designed for high-performance session management and immersion.

Inventory Management System

The plugin includes a robust inventory management system that automatically saves and restores player inventories when entering and exiting minigames and edit mode.

How It Works

Entry: When a player joins a minigame or edit mode, their current inventory is automatically saved to a backup file.
Exit: When leaving, the inventory is restored from the backup, returning all original items to the player.

Snapshot Types

The system uses separate backup files for different modes to prevent conflicts:

Type	Filename Format	Description
MINIGAME	`{playerId}_minigame.json`	Saved when entering a minigame
EDIT	`{playerId}_edit.json`	Saved when entering edit mode

Files Location

Inventory backups are stored in:

mods/AvalonEssentials/Backups/Inventories/

Key Features

Automatic Save: Inventories are saved automatically when entering minigames or edit mode
Automatic Restore: Original items are restored when leaving
Multiple Modes: Separate backups for minigames and edit mode prevent item conflicts
Safe Deletion: Backup files are deleted after successful restoration to prevent duplicates

Technical Details

The system is implemented in:

InventorySnapshotManager.java - Core inventory save/restore logic
MinigameService.java - Handles minigame inventory management
EditModeService.java - Handles edit mode inventory management
MinigameListener.java - Event listener for player state restoration

Configuration (`minigame_config.json`)

The engine uses a unified, JSON configuration. Settings are divided into gameSettings, scoreSettings, and the powerful Event System.

{
  "gameSettings": {
    "lives": 3,
    "maxHealthOverride": 100.0,
    "disableFallDamage": true,
    "disablePvP": false,
    "gameDuration": 600
  },
  "scoreSettings": {
    "winCondition": "POINTS",
    "targetScore": 20,
    "pointsPerKill": 1,
    "pointsPerDeath": -1
  },
  "events": {
    "onJoin": [
      "CLEAR_INVENTORY",
      "GIVE_START_INVENTORY",
      "SEND_MESSAGE: &aWelcome to the Arena!"
    ],
    "onDeath": [
      "TELEPORT_TO_SPAWN",
      "SEND_MESSAGE: &cYou died! Respawning..."
    ],
    "onWin": [
      "SEND_MESSAGE: &6&lVICTORY!",
      "GIVE_KIT:WINNER_REWARD"
    ]
  },
  "teamSettings": {
    "enabled": true,
    "friendlyFire": false,
    "autoAssign": true,
    "teams": [
        { "id": "RED", "name": "Red Team", "color": "#FF0000" },
        { "id": "BLUE", "name": "Blue Team", "color": "#0000FF" }
    ],
    "teamSpawns": {
        "RED": { "x": 10.0, "y": 65.0, "z": 10.0, "yaw": 0.0 },
        "BLUE": { "x": -10.0, "y": 65.0, "z": -10.0, "yaw": 180.0 }
    }
  }
}

Automation Actions

Use these keys in your events list to trigger automatic logic:

RESET_STATS: Sets health, hunger, and status to default.
SET_MAX_HEALTH:<value>: Equalizes health for all participants.
CLEAR_INVENTORY: Wipes armor, hotbar, and storage.
GIVE_START_INVENTORY: Equips items defined in the game configuration.
TELEPORT_TO_SPAWN: Moves the player to their assigned team spawn.
SEND_MESSAGE:<text>: Broadcasts a local message.
HIDE_HUD / SHOW_HUD: Toggles the game interface for cinematic experiences.

Victory Conditions

The engine supports three primary win conditions:

POINTS: First player/team to reach targetScore wins.
LAST_MAN_STANDING: Last player alive wins (requires lives to be set).
TIME: The player/team with the highest score when gameDuration (seconds) ends wins.

Camera & Perspective Support

Enhance gameplay with unique viewpoints via the integrated Camera Manager:

Side-Scroller: Professional 2D platformer camera with locked axes.
Top-Down: Optimized for ARPG/RTS styles.
Isometric: Fixed-angle perspective for classic RPG immersion.

Technical Information & Configs

To generate JSON configurations for NPCs, Quests, and Shops, use our web-based automation tool:

Interaction Generator: https://hytale-tools.netlify.app/

Developed by AvalonTM. Developer GitHub