---

name: hytale-modding description: Develop mods for Hytale, a voxel-based sandbox RPG by Hypixel Studios. Use when creating server plugins (commands, events, entities), working with the Entity Component System (ECS), creating custom UI, managing inventory, world generation, prefabs, or publishing mods. Covers Java 25 development with Maven, IntelliJ IDEA setup, and the complete plugin development lifecycle.

Hytale Modding

Quick Start

1. Setup: Java 25 + IntelliJ IDEA + Maven (see references/dev-environment.md)
2. Clone template: git clone https://github.com/HytaleModding/plugin-template.git MyMod
3. Add server JAR: Install HytaleServer.jar to local Maven repo
4. Build: mvn package produces JAR in target/
5. Test: Copy JAR to %appdata%/Hytale/UserData/Mods/

Architecture: Entity Component System (ECS)

Hytale uses ECS - understand these core concepts:

See references/ecs.md for complete ECS guide.

Plugin Structure

CopyMyMod/
├── pom.xml                 # Maven config
├── manifest.json           # Plugin metadata
├── src/main/java/
│   └── com/example/
│       └── MyPlugin.java   # Main plugin class
└── resources/
    └── Common/UI/Custom/   # UI files (if using custom UI)

Main Plugin Class:

Copypublic class MyPlugin extends JavaPlugin {
    @Override
    public void setup() {
        // Register commands, events, systems here
    }
}

Common Tasks

Creating Commands

Extend AbstractPlayerCommand:

Copypublic class MyCommand extends AbstractPlayerCommand {
    public MyCommand() {
        super("mycommand", "Description");
    }

    @Override
    public void execute(CommandContext ctx, Store<EntityStore> store,
                        Ref<EntityStore> ref, PlayerRef player, World world) {
        player.sendMessage(Message.raw("Hello!"));
    }
}

Register in setup(): getCommandRegistry().register(new MyCommand());

Listening to Events

Copypublic static void onPlayerReady(PlayerReadyEvent event) {
    Player player = event.getPlayer();
    player.sendMessage(Message.raw("Welcome " + player.getDisplayName()));
}

Register: getEventRegistry().registerGlobal(PlayerReadyEvent.class, MyEvents::onPlayerReady);

Spawning Entities

Copyworld.execute(() -> {
    Holder<EntityStore> holder = EntityStore.REGISTRY.newHolder();
    ModelAsset asset = ModelAsset.getAssetMap().getAsset("Minecart");
    Model model = Model.createScaledModel(asset, 1.0f);

    holder.addComponent(new TransformComponent(position, rotation));
    holder.addComponent(new PersistentModel(model));
    holder.addComponent(new ModelComponent(model));
    // ... add required components

    store.addEntity(holder, AddReason.SPAWN);
});

Playing Sounds

Copyint soundIndex = SoundEvent.getAssetMap().getIndex("SFX_Cactus_Large_Hit");
world.execute(() -> {
    SoundUtil.playSoundEvent3dToPlayer(playerRef, soundIndex,
        SoundCategory.UI, transform.getPosition(), store);
});

Reference Documentation

Key APIs

Entity Access:

• player.getWorld() - Get world from player
• world.getEntityStore().getStore() - Get entity store
• store.getComponent(ref, componentType) - Get component from entity

Common Components:

• TransformComponent - Position and rotation
• PlayerRef / Player - Player connection and presence
• UUIDComponent - Entity unique ID
• ModelComponent - Visual model

System Types:

• EntityTickingSystem - Per-entity each tick
• TickingSystem - Global each tick
• DelayedEntitySystem - Per-entity with delay
• RefChangeSystem - React to component changes

Manifest.json

Copy{
    "PluginId": "com.example.myplugin",
    "PluginName": "My Plugin",
    "PluginVersion": "1.0.0",
    "IncludesAssetPack": true
}

Set IncludesAssetPack: true when including custom UI or assets.

Testing Workflow

1. Build: mvn package
2. Copy JAR to %appdata%/Hytale/UserData/Mods/
3. Launch Hytale → Create World → Settings → Mods
4. Enable "Diagnostic Mode" in settings for error details