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:

Concept	Purpose	Example
Entity	Unique identifier (no data)	Player, Minecart, Block
Component	Data container (no logic)	TransformComponent, Health
System	Logic processor	DamageSystem, MovementSystem
Store	Entity manager	EntityStore, ChunkStore
Holder	Blueprint before spawning	"Shopping cart" for components
Ref	Safe entity reference	NEVER store entity objects directly

See references/ecs.md for complete ECS guide.

Plugin Structure

MyMod/
├── 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:

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

Common Tasks

Creating Commands

Extend AbstractPlayerCommand:

public 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

public 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

world.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

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

Reference Documentation

Topic	File	Contents
Dev Environment	references/dev-environment.md	Java 25, IntelliJ, Maven setup
ECS Architecture	references/ecs.md	Store, Holder, Ref, Components, Systems
Server Plugins	references/server-plugins.md	Commands, events, UI, packets
Gameplay Systems	references/gameplay-systems.md	Entities, inventory, blocks, prefabs
World Generation	references/world-generation.md	Zones, biomes, caves
Publishing	references/publishing.md	Modtale, CurseForge distribution

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

{
    "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