Hytale Instance System

Use this skill when working with instanced worlds in Hytale plugins. The InstancesPlugin provides a complete API for spawning instance worlds from templates, teleporting players in/out, and managing instance lifecycles.

Source: https://hytalemodding.dev/en/docs/guides/plugin/instances

Quick Reference

Key Concepts

Instance Templates

Instance templates are located in your asset pack under Server/Instances/[Name]. Each template must contain an instance.bson configuration file. When spawnInstance is called, the template is copied and initialized as a new world in the universe.

Return Points

A Transform that defines where the player should be teleported back to when they exit the instance. This is set during instance creation and can be optionally overridden during teleportation.

World Execution Context

All instance operations (spawn, teleport, remove) should be executed within the world's execution context using world.execute(() -> { ... }) to ensure thread safety.

Required Imports

import com.hypixel.hytale.server.core.Message;
import com.hypixel.hytale.server.core.Universe;
import com.hypixel.hytale.server.world.World;
import com.hypixel.hytale.server.world.Transform;
import com.hypixel.hytale.server.world.ISpawnProvider;
import com.hypixel.hytale.server.player.Player;
import com.hypixel.hytale.server.player.PlayerRef;
import com.hypixel.hytale.server.instances.InstancesPlugin;

import java.util.UUID;
import java.util.concurrent.CompletableFuture;

Spawning an Instance

Use spawnInstance to create a new instanced world from a template. Returns a CompletableFuture<World>.

Method Signature

Example

InstancesPlugin plugin = InstancesPlugin.get();
World currentWorld = /* current world context */;
Transform returnPoint = /* where players should go when they leave */;

// Spawn an instance named "Challenge_Combat_1"
World instanceWorld = InstancesPlugin.get()
    .spawnInstance("Challenge_Combat_1", currentWorld, returnPoint)
    .join();

Universe.get().sendMessage(Message.raw("Instance spawned: " + instanceWorld.getName()));

Teleporting Players to Instances

The InstancesPlugin provides two approaches depending on whether the instance world is already loaded or still loading.

Teleporting to an Active Instance

Use when the World object is already available (instance has finished loading).

InstancesPlugin.teleportPlayerToInstance(
    playerRef,             // Ref<EntityStore> — the player's entity reference
    componentAccessor,     // EntityStore — the player's component accessor (store)
    instanceWorld,         // World — the target instance world
    null                   // Transform — optional override for return point (null to use original)
);

Teleporting to a Loading Instance

Use when you have a CompletableFuture<World> from spawnInstance. This queues the teleport to happen as soon as the world is ready.

CompletableFuture<World> worldFuture = plugin.spawnInstance("Challenge_Combat_1", currentWorld, returnPoint);

InstancesPlugin.teleportPlayerToLoadingInstance(
    playerRef,             // Ref<EntityStore> — the player's entity reference
    componentAccessor,     // EntityStore — the player's component accessor (store)
    worldFuture,           // CompletableFuture<World> — future from spawnInstance
    null                   // Transform — optional override for return point (null to use original)
);

Exiting Instances

Returns the player to their original world using the return point defined when the instance was created.

InstancesPlugin.exitInstance(playerRef, componentAccessor);

Managing Instance Removal

Instances can be safely removed when no longer needed (e.g., when empty). Use safeRemoveInstance to cleanly shut down an instance world.

InstancesPlugin.safeRemoveInstance(instanceWorld);

Getting Player Ref and Store

In most contexts you need the player's Ref<EntityStore> and the EntityStore:

// From a PlayerRef
PlayerRef playerRef = Universe.get().getPlayer(playerUUID);
Ref<EntityStore> ref = playerRef.getReference();
EntityStore store = playerRef.getReference().getStore();

// From a Player object (e.g., in a command)
Player player = (Player) ctx.sender();
Ref<EntityStore> ref = player.getReference();
EntityStore store = player.getReference().getStore();

Getting a Return Point from Spawn Provider

World world = Universe.get().getWorld(playerRef.getWorldUuid());
ISpawnProvider spawnProvider = world.getWorldConfig().getSpawnProvider();
Transform returnPoint = spawnProvider != null
    ? spawnProvider.getSpawnPoint(world, playerRef.getUuid())
    : new Transform();

Command Examples

Spawn Instance Command

public class ExampleSpawnInstanceCommand extends CommandBase {
    private final RequiredArg<String> nameArg;

    public ExampleSpawnInstanceCommand() {
        super("spawninstance", "Spawns a new instance from a template");
        this.nameArg = this.withRequiredArg("name", "The name of the new instance", ArgTypes.STRING);
    }

    @Override
    protected void executeSync(@Nonnull CommandContext ctx) {
        UUID playerUUID = ctx.sender().getUuid();
        PlayerRef playerRef = Universe.get().getPlayer(playerUUID);
        World world = Universe.get().getWorld(playerRef.getWorldUuid());

        ISpawnProvider spawnProvider = world.getWorldConfig().getSpawnProvider();
        Transform returnPoint = spawnProvider != null
            ? spawnProvider.getSpawnPoint(world, playerRef.getUuid())
            : new Transform();

        world.execute(() -> {
            World instanceWorld = InstancesPlugin.get()
                .spawnInstance(this.nameArg.get(ctx), world, returnPoint)
                .join();
            Universe.get().sendMessage(
                Message.raw("Instance spawned: " + instanceWorld.getName())
            );
        });
    }
}

Enter Instance Command

Spawns an instance and immediately teleports the player into it (using teleportPlayerToLoadingInstance so it works even before the world finishes loading):

public class ExampleEnterInstanceCommand extends CommandBase {
    private final RequiredArg<String> nameArg;

    public ExampleEnterInstanceCommand() {
        super("enterinstance", "Spawns and enters an instance immediately");
        this.nameArg = this.withRequiredArg("name", "The name of the instance", ArgTypes.STRING);
    }

    @Override
    protected void executeSync(@Nonnull CommandContext ctx) {
        UUID playerUUID = ctx.sender().getUuid();
        PlayerRef playerRef = Universe.get().getPlayer(playerUUID);
        World world = Universe.get().getWorld(playerRef.getWorldUuid());

        ISpawnProvider spawnProvider = world.getWorldConfig().getSpawnProvider();
        Transform returnPoint = spawnProvider != null
            ? spawnProvider.getSpawnPoint(world, playerRef.getUuid())
            : new Transform();

        world.execute(() -> {
            CompletableFuture<World> worldFuture = InstancesPlugin.get()
                .spawnInstance(this.nameArg.get(ctx), world, returnPoint);

            InstancesPlugin.teleportPlayerToLoadingInstance(
                playerRef.getReference(),
                playerRef.getReference().getStore(),
                worldFuture,
                null
            );
        });
    }
}

Exit Instance Command

public class ExampleExitInstanceCommand extends CommandBase {
    public ExampleExitInstanceCommand() {
        super("exitinstance", "Exits the current instance and returns to the previous world");
    }

    @Override
    protected void executeSync(@Nonnull CommandContext ctx) {
        Player player = (Player) ctx.sender();
        World world = player.getWorld();

        world.execute(() -> {
            InstancesPlugin.exitInstance(
                player.getReference(),
                player.getReference().getStore()
            );
        });
    }
}

Remove Instance Command

public class ExampleRemoveInstanceCommand extends CommandBase {
    private final RequiredArg<String> worldArg;

    public ExampleRemoveInstanceCommand() {
        super("removeinstance", "Safely removes an instance");
        this.worldArg = this.withRequiredArg("world", "The world to remove", ArgTypes.STRING);
    }

    @Override
    protected void executeSync(@Nonnull CommandContext ctx) {
        String worldName = ctx.get(this.worldArg);
        World targetWorld = Universe.get().getWorld(worldName);

        if (targetWorld == null) {
            ctx.sendMessage(Message.raw("World not found: " + worldName));
            return;
        }

        targetWorld.execute(() -> {
            InstancesPlugin.safeRemoveInstance(targetWorld);
        });
    }
}

Best Practices

1. Always use world.execute() — Instance operations must run within the world's execution context for thread safety.
2. Prefer teleportPlayerToLoadingInstance — When spawning and immediately entering, use the loading variant to avoid blocking on .join() before teleporting.
3. Use spawn provider for return points — Get the world's ISpawnProvider to calculate proper return positions rather than hardcoding coordinates.
4. Clean up instances — Call safeRemoveInstance when an instance is no longer needed to free resources.
5. Null return point override — Pass null for the override parameter when you want to use the return point set during spawnInstance.
6. Instance templates — Place templates under Server/Instances/[Name] with an instance.bson configuration file.