Documentation/content/core-concepts/registries.en.md

title, type, weight

title	type	weight
Registries	docs	1

Registries are central to Hytale plugin development. They provide a way to register and manage various game elements like commands, events, entities, and more.

Packages:

• com.hypixel.hytale.server.core.command.system (CommandRegistry)
• com.hypixel.hytale.event (EventRegistry)
• com.hypixel.hytale.server.core.plugin.registry (AssetRegistry, CodecRegistry)

Available Registries

Your plugin has access to these registries through the PluginBase class:

Registry	Method	Purpose
CommandRegistry	getCommandRegistry()	Register server commands
EventRegistry	getEventRegistry()	Register event listeners
EntityRegistry	getEntityRegistry()	Register custom entities
BlockStateRegistry	getBlockStateRegistry()	Register block states
TaskRegistry	getTaskRegistry()	Schedule and manage tasks
AssetRegistry	getAssetRegistry()	Register custom assets
ClientFeatureRegistry	getClientFeatureRegistry()	Register client features
EntityStoreRegistry	getEntityStoreRegistry()	Entity storage components
ChunkStoreRegistry	getChunkStoreRegistry()	Chunk storage components

CommandRegistry

Register commands that players can execute:

@Override
public void start() {
    getCommandRegistry().registerCommand(new MyCommand());
}

See Commands for detailed documentation.

EventRegistry

Subscribe to game events:

import com.hypixel.hytale.event.EventPriority;
import com.hypixel.hytale.server.core.event.events.player.PlayerConnectEvent;
import java.util.logging.Level;

@Override
public void start() {
    // Simple registration
    getEventRegistry().register(PlayerConnectEvent.class, event -> {
        getLogger().at(Level.INFO).log("Player connecting: " + event.getPlayerRef().getUsername());
    });

    // With priority
    getEventRegistry().register(
        EventPriority.EARLY,
        PlayerConnectEvent.class,
        this::onPlayerConnect
    );
}

See Events for detailed documentation.

EntityRegistry

Register custom entity types:

@Override
public void start() {
    getEntityRegistry().register(MyCustomEntity.class, MyCustomEntity::new);
}

See Entities for detailed documentation.

BlockStateRegistry

Register custom block states:

@Override
public void start() {
    getBlockStateRegistry().register(myBlockState);
}

TaskRegistry

Track async tasks for cleanup during plugin shutdown:

{{< callout type="warning" >}} TaskRegistry does NOT have runAsync(), runSync(), runLater(), or runRepeating() methods. Use Java's standard concurrency APIs. {{< /callout >}}

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.Executors;
import java.util.concurrent.ScheduledExecutorService;
import java.util.concurrent.ScheduledFuture;
import java.util.concurrent.TimeUnit;

@Override
public void start() {
    // Async operation
    CompletableFuture<Void> task = CompletableFuture.runAsync(() -> {
        // Background work
    });
    getTaskRegistry().registerTask(task);

    // Delayed operation (3 seconds)
    CompletableFuture.delayedExecutor(3, TimeUnit.SECONDS)
        .execute(() -> {
            getLogger().at(Level.INFO).log("Delayed task executed!");
        });

    // Repeating operation (every 5 minutes)
    ScheduledExecutorService scheduler = Executors.newSingleThreadScheduledExecutor();
    ScheduledFuture<?> repeating = scheduler.scheduleAtFixedRate(() -> {
        getLogger().at(Level.INFO).log("Repeating task!");
    }, 0, 5, TimeUnit.MINUTES);
    getTaskRegistry().registerTask((ScheduledFuture<Void>) repeating);
}

See Tasks for detailed documentation.

AssetRegistry

Register custom game assets:

@Override
public void start() {
    getAssetRegistry().register(myAsset);
}

CodecRegistry

For registering custom serialization codecs:

getCodecRegistry(MyType.CODEC_MAP).register("my_type", MyType.CODEC);

Automatic Cleanup

{{< callout type="info" >}} All registrations are automatically cleaned up when your plugin is disabled. You don't need to manually unregister anything in your shutdown() method. {{< /callout >}}

Registration Timing

Register your components in the start() method, not in setup():

@Override
public void setup() {
    // Configuration only - don't register here
    withConfig(MyConfig.CODEC);
}

@Override
public void start() {
    // Register everything here
    getCommandRegistry().registerCommand(new MyCommand());
    getEventRegistry().register(PlayerConnectEvent.class, this::onJoin);
}

This ensures all plugins have completed their setup phase before any registrations occur.