Hytale Modding Handbook

A Hytale server-plugin & asset API reference, with the descriptions, gotchas, and working examples to build with.

Documentation

Every page under docs/ is listed below; verify-docs.sh fails when one is not. Full index · Repo structure

The docs/ directory contains comprehensive API documentation:

Getting Started

• Overview - Introduction and getting started
• Plugin Lifecycle - Setup, lifecycle, and server events
• Permissions - Permission system

Core Systems

• Components - Entity Component System (ECS)
• Codecs - Serialization and data persistence
• Networking - Network protocols
• Math - Vectors, matrices, shapes

Commands & UI

• Commands - Command system and arguments
• UI - Custom UI pages and HUD
• UI Elements - UI element types
• UI Styling - Styling and layout
• UI Templates - Reusable templates
• UI API - Java UI API
• i18n - Localization

World & Environment

• World - World management
• World Chunks - Per-chunk API, accessors, and ChunkTracker
• World & Chunk Lifecycle Events - Engine events for world and chunk lifecycle
• World Events - Scripted world-event timelines (0.6.3+)
• Universes & Saves - Save format, universe resources, dedicated-server config
• Trigger Volumes - Scripted encounters as JSON effect assets
• Camera - Server-controlled camera and camera effects
• Blocks - Block states and custom blocks
• Connected Blocks - Connected and patterned rule sets
• Blocks Java API - BlockType, block events, world block access
• Fluids - Fluid systems
• Prefabs - Structure templates
• Prefab Categories - Category system for prefabs
• Collision - Collision queries

Entities

• Entities - Entity hierarchy
• Player - Player API
• NPC - NPC and AI systems
• NPC Roles - NPC role templates and behaviors
• NPC Spawning - Spawn beacons, companion spawners, manual markers
• NPC Combat - Melee attacks and the Combat Action Evaluator
• Encounters - Encounter managers and their core components
• Mounts - Mount subsystem
• Deployables - Deployable subsystem
• Drops - Drop system and loot tables
• Projectiles - Projectile configuration

Combat & Effects

• Combat - Damage and kill feed
• Effects & Stats - Status effects and stats

Items

• Items - Item definitions overview
• Block Items - Block items
• Consumables - Consumable items
• Crafting - Crafting system
• Tools - Tool items
• Weapons - Weapon templates

World Generation

• World Generation - World generation overview
• Zones - Zone system
• Biomes - Biome definitions
• Terrain - Terrain layers
• Caves - Cave system
• Prefabs - Structure placement

Interactions

• Interactions - Interactions API overview
• Flow Control - Serial, Parallel, Condition
• Combo System - Chaining and charging
• Context - Context variables
• Operations - Operation types
• World Interactions - Spawning and positioning
• Combat Interactions - Damage and forces

Assets & Events

• Assets - Asset registry
• Asset Editor - Editor events
• Blockymodel Format - Model file format
• Blockyanim Format - Animation file format
• Audio - Audio system
• Events - Event system overview
• Adventure - Adventure gameplay events
• Singleplayer - Singleplayer events

Utilities

• Inventory - Inventory management
• Tasks - Async task scheduling

Examples

examples/commands/

Demonstrates the command system with:

• Simple no-argument commands
• Commands with position arguments

examples/ui/

Demonstrates the UI system with:

• Opening custom UI pages
• Toggling HUD components
• Loading .ui definition files

examples/inventory/

Demonstrates the inventory API with:

• Adding items with transaction handling
• Clearing inventory sections
• Inspecting inventory contents
• Sorting storage by name/type/rarity

examples/entity-count/

Demonstrates the ECS ticking-system pattern with:

• An EntityTickingSystem that runs every tick on the world thread
• Counting entities by component (Total/Players/NPCs/Other)
• Pushing live values to a CustomUIHud overlay

examples/custom-food/

A no-code, no-art Pack (pure JSON, no Java) for beginners:

• Adds a custom food item by extending the real Template_Food
• Reuses an existing in-game icon and real heal/buff effects — nothing to compile or draw
• Teaches the "copy a template, override a few fields" pattern at the heart of JSON modding

Requirements

• Hytale installed (uses HytaleServer.jar from the local install)
  • Windows: %APPDATA%\Hytale\install\release\package\game\latest\Server\
  • Linux (Flatpak launcher): ~/.var/app/com.hypixel.HytaleLauncher/data/Hytale/install/release/package/game/latest/Server/
• Java 25+
• Gradle (wrapper included)

The build resolves the jar automatically per-platform via examples/hytale-paths.gradle.

Building

Each example can be built independently.

Windows:

cd examples\commands
build.bat        :: build
deploy.bat       :: build and deploy to the mods folder

Linux / macOS (use the Gradle wrapper directly — the .bat scripts are Windows-only):

cd examples/commands
./gradlew jar    # build (produces build/libs/*.jar)

Deployment

Copy the built JAR from build/libs/ to the mods folder:

• Windows: %APPDATA%\Hytale\UserData\Mods\
• Linux (Flatpak launcher): ~/.var/app/com.hypixel.HytaleLauncher/data/Hytale/UserData/Mods/

Maintenance

The maintenance/ directory holds maintainer-only tooling — a documentation regression checker and the asset baseline used to detect game-build drift. It is not needed to read the docs or build the examples; see maintenance/README.md if you're keeping the repo in sync with a new Hytale build.

License

MIT License - see LICENSE for details.