Mod Lifecycle

Mods go through a defined lifecycle from loading to shutdown. This guide explains what to do in each phase.

Overview

preLoad()

Called before the server is fully initialized. Returns CompletableFuture<Void> (nullable).

@Override
public CompletableFuture<Void> preLoad() {
    return CompletableFuture.runAsync(() -> {
        // early async initialization if needed
    });
}

setup()

The main registration phase. Called when your mod loads.

@Override
protected void setup() {
    // register a command
    getCommandRegistry().registerCommand(new MyCommand());

    // register event listeners
    getEventRegistry().register(PlayerJoinEvent.class, this::onPlayerJoin);

    // register a component
    this.myComponentType = getEntityStoreRegistry()
        .registerComponent(MyComponent.class, "MyComponent", MyComponent.CODEC);
}

See what Hytale's built-in mods register in setup()

Task	Method
Register commands	`getCommandRegistry().registerCommand()`
Register event listeners	`getEventRegistry().register()`
Register components	`getEntityStoreRegistry().registerComponent()`
Register systems	`getEntityStoreRegistry().registerSystem()`
Register block states	`getBlockStateRegistry().registerBlockState()`
Register asset stores	`AssetRegistry.register()`
Register codecs	`getCodecRegistry().register()`
Register interactions	`Interaction.CODEC.register()`
Register entity types	`getEntityRegistry().registerEntity()`

start()

Called after all mods have completed setup(). Use for initialization that depends on assets or other mods being ready.

@Override
protected void start() {
    // load an asset (not safe during setup - assets may not be loaded yet)
    ModelAsset modelAsset = ModelAsset.getAssetMap().getAsset("My_Model");
    if (modelAsset == null) {
        throw new IllegalStateException("Model 'My_Model' not found");
    }
    this.model = Model.createUnitScaleModel(modelAsset);

    // read config and apply settings
    MyConfig cfg = this.config.get();
    this.maxPlayers = cfg.maxPlayers;

    // schedule a recurring task
    this.saveTask = HytaleServer.SCHEDULED_EXECUTOR
        .scheduleWithFixedDelay(this::saveData, 5, 5, TimeUnit.MINUTES);
}

start() fires before world threads have started. The ECS stores (ChunkStore, EntityStore), chunk loader, lighting manager, and map ticking are all uninitialized at this point — accessing them will throw a NullPointerException.

If your mod needs to interact with world contents (chunks, entities, blocks), defer that work to StartWorldEvent:

@Override
protected void start() {
    getEventRegistry().registerGlobal(StartWorldEvent.class, event -> {
        // world is fully initialized — stores, loader, lighting all ready
        World world = event.getWorld();
        initializeRenderer(world);
    });
}

What is safe in start(): loading assets, reading config, scheduling tasks, registering event listeners, and accessing WorldConfig. See World initialization order for the full timeline.

See what Hytale's built-in mods do in start()

Task	Method
Load asset references	`ModelAsset.getAssetMap().getAsset()`
Read configuration values	`this.config.get()`
Schedule recurring tasks	`HytaleServer.SCHEDULED_EXECUTOR.scheduleWithFixedDelay()`
Cross-mod integration	`PluginManager.getPlugin()`

If a command needs state that’s only available in start() (world references, loaded config), register the command in setup() and pass the mod instance. The command accesses runtime state through the mod:

// in setup()
getCommandRegistry().registerCommand(new MyMapCommand(this));

// in the command
public class MyMapCommand extends CommandBase {
    private final MyPlugin plugin;

    public MyMapCommand(MyPlugin plugin) {
        super("mymap", "myplugin.commands.mymap.desc");
        this.plugin = plugin;
    }

    @Override
    protected void executeSync(CommandContext context) {
        MapRenderer renderer = plugin.getRenderer(); // initialized in start()
        if (renderer == null) {
            context.sendMessage(Message.translation("myplugin.notready"));
            return;
        }
        // use renderer
    }
}

shutdown()

Called when the server stops. Use for cleanup that isn’t handled automatically.

@Override
protected void shutdown() {
    // cancel scheduled tasks
    if (this.saveTask != null) {
        this.saveTask.cancel(false);
    }

    // save any pending data
    this.dataStore.saveToDiskAll();
}

See what Hytale's built-in mods do in shutdown()

Task	Method
Cancel scheduled tasks	`scheduledFuture.cancel(false)`
Save persistent data	`dataStore.saveToDisk()`
Close external connections	`connection.close()`