HTDevLib

HytaleDevLib - Developer Utility Library

A comprehensive utility library for Hytale plugin development that simplifies common modding tasks with tested helper classes and intuitive APIs.

⚠️ Early Development: This is a work in progress with lots planned! Feel free to make suggestions in GitHub Issues.

---

Website & Documentation

Key Features

WorldHelper

• Time & Day System - Get/set game time, check day/night, track moon phases
• Tick Tracking - Schedule delayed actions and interval callbacks
• Player Management - Easy player lookups and messaging
• Thread-Safe Operations - Safe world manipulation from any thread

EntityHelper

• NPC Spawning - Spawn any NPC by name with proper ECS setup
• Player Utilities - Find players by name/UUID, get positions, calculate distances
• Entity Management - Iterate entities, check proximity, teleport entities
• Type Detection - Readable entity type names (e.g., "Cow", "Skeleton_Fighter")

ZoneHelper

• Zone Discovery Tracking - Track which zones each player has discovered
• Current Zone Queries - Get a player's current zone or check if they're in a specific zone
• Player-in-Zone Searches - Find all players currently in a specific zone
• Zone Statistics - Get discovery counts, all discovered zones, and zone popularity
• Thread-Safe Storage - Username-based tracking with concurrent collections

BlockHelper

• Name-Based Operations - Minecraft-style block referencing (e.g., "Rock_Stone")
• Dynamic Block Resolution - Uses game's native asset system for automatic compatibility
• World Editing - Fill regions, replace blocks, find blocks by type
• Automatic Client Sync - Block changes instantly visible to players
• Fluid Support - Programmatic water/lava placement and removal helpers
• Fluid Client Updates - Sends fluid update packets so fluid changes appear immediately

QuestHelper

• Quest Data Models - Build structured quests with objectives and rewards
• Objective Tracking Structures - Support objective type, target, and required amount definitions
• Prerequisite Support - Define quest dependency chains
• Repeatable Quest Patterns - Build daily/looping quest content

EconomyHelper

• Currency Operations - Add/remove/check balances through a single helper API
• Transaction Utilities - Apply costs and payouts for gameplay systems
• Shop/Reward Foundation - Reusable helpers for vendors, quest rewards, and upgrade costs

BlockStateHelper

• Block State Management - Work with chests, signs, and other stateful blocks
• Container Access - Easy access to chest inventories and other containers
• State Persistence - Mark states for saving to ensure data persists
• Future-Proof - Abstracts deprecated BlockState API

ItemHelper

• Item Creation - Create item stacks with specified quantities
• Container Management - Add, remove, count items in containers
• Random Slot Placement - Fill containers with items in random slots for loot variety
• Inventory Queries - Check space, count items, get item information
• Dropped Item Entity Management - Get all dropped items, filter by type/radius, remove items, teleport items
• Item Teleporting - Teleport items to players
• Item Cleanup - Count and remove specific item types from the world

EventHelper

• Simplified Events - No manual EventRegistry boilerplate
• Item Events with Player Entity - Drop, pickup, and crafting detection with player entity access
• Player Events - Chat messages, join/disconnect tracking
• Transaction Parsing - Automatic inventory transaction analysis
• Stat Integration - Access player stats directly in item event callbacks

EcsEventHelper

• Block Events with Player Entity - Break, place, and damage tracking with player entity access
• Mining Progress - Track mining progress and player-specific block interactions
• BlockDamageContext - Read/write access to block health for mining speed multipliers
• Gather Type Filtering - Filter by block categories (Rocks, Woods, Soils, etc.)
• Mining Speed Multipliers - Implement efficiency enchantments and custom mining mechanics
• Zone Discovery - Detect map exploration with zone metadata
• ECS Integration - Automatic system registration for player events
• Smart Filtering - Filters out false positives (e.g., "Empty" blocks)

DeathHelper

• Entity Death Tracking - Track entity deaths with comprehensive information
• Killer Information - Get killer entity (player, NPC, or environment)
• Damage Source - Get damage source and how they died
• Death Position - Get coordinates where entity died
• Automatic Name Resolution - Player usernames and NPC role names

StatsHelper

• Entity Stats Management - Get/set health, stamina, mana, oxygen, and any custom stat
• Stat Modifiers - Add additive or multiplicative buffs/debuffs to stats
• Convenience Methods - Quick access to common stats (health, stamina, mana, oxygen)
• Stat Queries - Get min/max values, percentages, check if stat exists
• Min/Max Operations - Maximize, minimize, or reset stats to defaults
• Auto-Clamping - Values automatically stay within min/max bounds

InventoryHelper

• Item Management - Give, remove, count items with quantity support
• Inventory Checks - Has item, is full, get active hotbar item
• Player Operations - Clear inventory, check capacity
• Safe API - Null-safe operations with proper error handling

PlayerHelper

• Messaging - Send messages to players
• Permissions - Check player permissions with default values
• Game Mode - Get/set player game mode (Creative, Adventure)
• Block Targeting - Get blocks player is looking at with distance info
• Player Data - Get player component and skin data
• Type Checking - Verify if entity is a player

UIHelper

• Custom Page Management - Open/close custom UI pages
• HUD Control - Show/hide HUD components
• Fade Animations - Smooth fade in/out effects for UI elements
• UI Transitions - Create polished user experiences

TitleHelper

• On-Screen Title Notifications - Display major and minor titles to players
• Major Titles - Large, prominent notifications for important events
• Minor Titles - Smaller, subtle notifications for less critical info
• Custom Icons - Add icons to titles from asset paths
• Fade Animations - Control fade-in and fade-out timing
• Duration Control - Set how long titles display on screen

LootHelper

• Custom Block Drops - Override default block drops with custom items
• Mob Loot System - Add custom drops to any mob with chance-based mechanics
• Chance-Based Drops - 10% legendary items, 50% uncommon drops, 75% common drops
• Loot Tables - Register custom loot for specific block types and mobs
• Physical Item Entities - Spawn items with proper physics and collision
• Flexible Loot Logic - Percentage-based, weighted, depth-based, and conditional drops
• DeathHelper Integration - Works alongside entity death tracking

ContainerHelper

• Container Tracking - Track item changes in chests, furnaces, and other containers
• ContainerTransaction API - Automatic transaction parsing with clean API
• Transaction Cancellation - Cancel transactions to prevent item changes with automatic reversion
• Auto-Registration - Automatically track all containers as they're placed/destroyed
• Shift-Click Detection - Properly detects ADDED vs REMOVED for shift-click transfers
• Chest Protection - Build protection systems and item logging

EquipmentHelper

• Equipment Tracking - Track armor, utility/offhand, and tool changes for any LivingEntity
• EquipmentChange API - Structured change objects with old/new items and slot info
• Equip/Unequip Detection - Convenience helpers for detecting equip vs unequip actions
• Shift-Click Support - Works with both drag/drop and shift-click equipping

ParticleHelper

• 535+ Particle Systems - Access to all Hytale particle effects by name
• 2D & 3D Spawning - Spawn particles at positions, blocks, or entities
• Scale Control - Customize particle size (1.0 = normal, 2.0 = double)
• Color Customization - Built-in color presets for particle tinting
• Player-Specific Particles - Show particles to specific players only
• Automatic Cleanup - Temporary particles auto-disappear, looping effects persist

SoundHelper

• 1,156+ Sound Events - Access to all Hytale sound effects by name
• 2D Sounds (UI/Global) - Play sounds to all players or specific players
• 3D Sounds (Positional) - Play sounds at world positions with distance attenuation
• Volume & Pitch Control - Customize sound playback (1.0 = normal)
• Sound Categories - SFX, MUSIC, AMBIENT, VOICE, MASTER
• Player-Specific Audio - Play sounds to individual players

ComponentHelper

• Type-Safe ECS - Safe component access with null handling
• Display Names - Easy entity name management
• Item Data - Extract item information from components

---

For Server Owners

This is a library mod - it doesn't do anything on its own. Install it only if another plugin requires it as a dependency.

Installation:

1. Download HytaleDevLib JAR
2. Place in your server's Mods folder
3. Install any plugins that depend on HytaleDevLib
4. Restart your server

---

For Mod Developers

HytaleDevLib is designed to be a dependency library for your plugins. It provides the utilities you need without adding gameplay features, keeping your mod focused on what makes it unique.

---

Documentation

Website & Documentation

GitHub Wiki:

• Complete API Reference
• Helper Class Guides
• Code Examples & Use Cases

---

Support & Issues

• GitHub Issues: Report bugs or request features
• Wiki: Full documentation
• Source Code: View on GitHub

---

License & Credits

Author: ShaneeexD
License: MIT License
Version: 0.5.0

You may use this mod as a dependancy for any mod you develop, as long as the download remains hosted within the CurseForge ecosystem.