Hytale Server API - Plugin System

protected void setup();      // Override for setup logic
protected void start();      // Override for start logic
protected void shutdown();   // Override for cleanup

<T> Config<T> withConfig(BuilderCodec<T> configCodec)
<T> Config<T> withConfig(String name, BuilderCodec<T> configCodec)
CompletableFuture<Void> preLoad()

HytaleLogger getLogger()
PluginIdentifier getIdentifier()
PluginManifest getManifest()
Path getDataDirectory()
PluginState getState()
boolean isEnabled()
boolean isDisabled()

Path getFile()
PluginClassLoader getClassLoader()
PluginType getType()  // Returns PluginType.PLUGIN

NONE → SETUP → START → ENABLED → SHUTDOWN → DISABLED

{
    "Group": "namespace",
    "Name": "pluginname",
    "Version": "1.0.0",
    "Description": "Plugin description",
    "Authors": [{ "Name": "Author", "Email": "email", "Url": "website" }],
    "Website": "https://example.com",
    "Main": "com.example.plugin.MainClass",
    "ServerVersion": "*",
    "Dependencies": { "group:plugin": "1.0.0" },
    "OptionalDependencies": { "group:optional": "*" },
    "LoadBefore": { "group:other": "*" },
    "SubPlugins": [],
    "DisabledByDefault": false,
    "IncludesAssetPack": true
}

String toString()  // Returns "group:name"
static PluginIdentifier fromString(String str)  // Parse "group:name"

static PluginManager get()
void registerCorePlugin(PluginManifest builder)
void setup() throws URISyntaxException, IOException
void start()
void shutdown()

List<PluginBase> getPlugins()
PluginBase getPlugin(PluginIdentifier identifier)
boolean hasPlugin(PluginIdentifier identifier, SemverRange range)
Map<PluginIdentifier, PluginManifest> getAvailablePlugins()

boolean load(PluginIdentifier identifier)
boolean load(PendingLoadPlugin pendingLoadPlugin)
boolean findAndLoadPlugin(PluginIdentifier identifier)
static PluginManifest loadManifest(Path file)

boolean reload(PluginIdentifier identifier)
boolean unload(PluginIdentifier identifier)
void unloadJavaPlugin(JavaPlugin plugin)

void validatePluginDeps(PendingLoadPlugin plugin, Map<PluginIdentifier, PendingLoadPlugin> pending)
boolean dependenciesMatchState(PluginBase plugin, PluginState requiredState, PluginState stage)

boolean isInServerClassPath()
void setPlugin(JavaPlugin plugin)
Class<?> loadClass(String name, boolean resolve)
Class<?> loadClass0(String name, boolean useBridge)
Class<?> loadLocalClass(String name)
URL getResource(String name)
Enumeration<URL> getResources(String name)
static boolean isFromThirdPartyPlugin(Throwable throwable)

Class<?> loadClass0(String name, PluginClassLoader pluginClassLoader)
Class<?> loadClass0(String name, PluginClassLoader pluginClassLoader, PluginManifest manifest)
URL getResource0(String name, PluginClassLoader pluginClassLoader)
Enumeration<URL> getResources0(String name, PluginClassLoader pluginClassLoader)

PluginManifest getPluginManifest()
Path getDataDirectory()
boolean isInServerClassPath()  // Returns true

Path getFile()
PluginClassLoader getClassLoader()
boolean isInServerClassPath()  // Delegates to classLoader

// Simple registration
<EventType extends IBaseEvent<Void>> EventRegistration<Void, EventType> register(
    Class<? super EventType> eventClass,
    Consumer<EventType> consumer
)

// With priority
<EventType extends IBaseEvent<Void>> EventRegistration<Void, EventType> register(
    EventPriority priority,
    Class<? super EventType> eventClass,
    Consumer<EventType> consumer
)

// With key
<KeyType, EventType extends IBaseEvent<KeyType>> EventRegistration<KeyType, EventType> register(
    Class<? super EventType> eventClass,
    KeyType key,
    Consumer<EventType> consumer
)

// Global (all events of type)
<KeyType, EventType extends IBaseEvent<KeyType>> EventRegistration<KeyType, EventType> registerGlobal(...)

// Async variants
<EventType extends IAsyncEvent<Void>> EventRegistration<Void, EventType> registerAsync(...)
<KeyType, EventType extends IAsyncEvent<KeyType>> EventRegistration<KeyType, EventType> registerAsyncGlobal(...)

// Unhandled (fallback)
<KeyType, EventType extends IBaseEvent<KeyType>> EventRegistration<KeyType, EventType> registerUnhandled(...)

CommandRegistration registerCommand(AbstractCommand command)

TaskRegistration registerTask(CompletableFuture<Void> task)
TaskRegistration registerTask(ScheduledFuture<Void> task)

import com.hypixel.hytale.server.core.HytaleServer;
import java.util.concurrent.ScheduledFuture;
import java.util.concurrent.TimeUnit;

private ScheduledFuture<?> tickTask;

@Override
protected void start() {
    // Schedule a recurring task every 500ms
    tickTask = HytaleServer.SCHEDULED_EXECUTOR.scheduleAtFixedRate(
        this::onTick,
        1000,  // initial delay
        500,   // period
        TimeUnit.MILLISECONDS
    );
}

@Override
protected void shutdown() {
    if (tickTask != null) {
        tickTask.cancel(false);
    }
}

private void onTick() {
    // Task logic here
}

<T extends Entity> EntityRegistration registerEntity(
    String key,
    Class<T> clazz,
    Function<World, T> constructor,
    DirectDecodeCodec<T> codec
)

<K, T extends JsonAssetWithMap<K, M>, M extends AssetMap<K, T>, S extends AssetStore<K, T, M>>
AssetRegistry register(S assetStore)

CodecMapRegistry<T, C> register(String id, Class<? extends T> aClass, C codec)
CodecMapRegistry<T, C> register(Priority priority, String id, Class<? extends T> aClass, C codec)

Assets<T, C> register(String id, Class<? extends T> aClass, BuilderCodec<? extends T> codec)
Assets<T, C> register(Priority priority, String id, Class<? extends T> aClass, BuilderCodec<? extends T> codec)

PendingLoadPlugin createSubPendingLoadPlugin(PluginManifest pluginManifest)
PluginBase load()
boolean isInServerClassPath()

static List<PendingLoadPlugin> calculateLoadOrder(Map<PluginIdentifier, PendingLoadPlugin> pending)

JavaPlugin load()  // Instantiates main class with JavaPluginInit

{
    "Group": "momo",
    "Name": "voidstorage",
    "Version": "1.0.0",
    "Description": "Void storage mod",
    "Main": "net.momo.voidstorage.VoidStoragePlugin",
    "ServerVersion": "*",
    "IncludesAssetPack": true
}

import java.util.logging.Level;

public class VoidStoragePlugin extends JavaPlugin {
    private static VoidStoragePlugin instance;

    public VoidStoragePlugin(JavaPluginInit init) {
        super(init);
        instance = this;
    }

    @Override
    protected void setup() {
        // Register global event listener (receives all events of this type)
        getEventRegistry().registerGlobal(
            PlayerConnectEvent.class,
            event -> getLogger().at(Level.INFO).log("Player connected: %s", event.getPlayerRef().getUsername())
        );

        // Register command
        getCommandRegistry().registerCommand(new VoidStatusCommand());
    }

    @Override
    protected void start() {
        getLogger().at(Level.INFO).log("Plugin started");
    }

    @Override
    protected void shutdown() {
        getLogger().at(Level.INFO).log("Plugin shutting down");
    }

    public static VoidStoragePlugin getInstance() {
        return instance;
    }
}