Class InstancesPlugin

java.lang.Object

com.hypixel.hytale.server.core.plugin.PluginBase

com.hypixel.hytale.server.core.plugin.JavaPlugin

com.hypixel.hytale.builtin.instances.InstancesPlugin

All Implemented Interfaces:

CommandOwner

public class InstancesPlugin
extends JavaPlugin

Manages running instances and instance assets.

Instance Assets

An instance asset is a Hytale world with additional instance.bson configuration file. They are stored at Server/Instances in the assets directory where each folder that contains a configuration file is a valid instance.

Referencing

When referring to an instance asset the name of the instance is the path to the instance asset relative to the Server/Instances folder. For example the instance asset Test would be in Server/Instances/Test while the instance Example/Testing would be in Server/Instances/Example/Testing. The path can be resolved for you by using the getInstanceAssetPath(String) method.

Instance Validation

Every instance asset in the assets directory will be loaded during validation with the name instance-validate-<safe-name>. Every chunk will be checked for invalid blocks and block states (and in the future invalid filler blocks). This will also ensure the world is still loadable as well.

This is done to help prevent instances from getting 'stale' when other assets change in the future, potentially introducing breaking changes.

Instance Modification

Instances can be loaded directly from the assets directory for modification using the loadInstanceAssetForEdit(String) method. This involves creating a world with the name instance-edit-<safe-name> and its world path pointing directly to the instance asset instead of a copy, the configuration will also be modified to freeze the world and enable creative.

The limitation is that changes to the configuration of the world will not save currently. This is because the configuration modification as stated above which we wouldn't want saved to the instance as well.

Instance Creation

The spawnInstance(String, String, World, Transform) methods can be used to load a copy of an instance asset as a world. If you don't provide a world name for the instance one will be generated using the format instance-<safe-name>-<uuid>. This involves copying the world files into the local universe before loading it which may take a while to complete if the world provides a large number of pregenerated chunks. You should ensure that this is handled e.g. by using a loading screen for the players trying to enter the world, see the "Instance Entry/Exit" section for one way to handle this.

Instance Entry/Exit

Teleporting to an instance can be done like any other world however the provided teleporting methods (teleportPlayerToInstance(Ref, ComponentAccessor, World, Transform) and teleportPlayerToLoadingInstance(Ref, ComponentAccessor, CompletableFuture, Transform)) are recommended to be used instead as this allows for additional metadata about the transfer to be attached.

The method teleportPlayerToLoadingInstance(Ref, ComponentAccessor, CompletableFuture, Transform) is provided to be a standard way to teleport a player to an instance that is still loading (either because of being copied, slow world gen or other reasons). This removes the player from their current world to prevent them from being damaged/interacted with whilst loading. The player is kept in this state until the target world loads at which point they'll be joined to the world as normal. (See: World.addPlayer(PlayerRef, Transform, Boolean, Boolean)).

When an instance is spawned a return point is stored. When the exitInstance(Ref, ComponentAccessor) method is used the player will be teleported back to this return point. Optionally a player can store its own return point (InstanceEntityConfig.getReturnPoint(), in that case it'll be used instead of the world's point. The player's return point is set when adding the player to a world using the value set in InstanceEntityConfig.setReturnPointOverride(WorldReturnPoint) if anything otherwise it'll be set to the world's return point.

Instance Removal

When removing an instance there are three options:

• Using Universe.removeWorld(String).

  This option will instantly remove the world and go through the normal process for removing players from the world which is to try and send them back to their return point and if that fails then to send them to the default world.

• Using RemovalConditions set in the world config.

  This will call Universe.removeWorld(String) automatically when the conditions are met.

• Using safeRemoveInstance(World).

  This option uses the above removal conditions and replaces any set on the world with a WorldEmptyCondition.

See RemovalCondition.

See Also:

• World
• Universe

Field Summary

Fields

Modifier and Type	Field	Description
static final String	CONFIG_FILENAME	The file name of the config file for an instance.
static final String	INSTANCE_PREFIX	The prefix used for instance worlds.

Fields inherited from class PluginBase

METRICS_REGISTRY

Constructor Summary

Constructors

Constructor	Description
InstancesPlugin(JavaPluginInit init)	Default Constructor for an InstancesPlugin instance.

Method Summary

Modifier and Type	Method	Description
static boolean	doesInstanceAssetExist(String name)	Returns whether an instance asset with the given name exists.
static CompletableFuture<Void>	exitInstance(Ref<EntityStore> targetRef, ComponentAccessor<EntityStore> componentAccessor)	Returns the entity to the return world/point for the instance they are currently in.
static InstancesPlugin	get()
ComponentType<ChunkStore, ConfigurableInstanceBlock>	getConfigurableInstanceBlockComponentType()
static Path	getInstanceAssetPath(String name)	Returns the path to the instance asset (the world) with the given name.
List<String>	getInstanceAssets()	Returns a list of instance assets
ComponentType<ChunkStore, InstanceBlock>	getInstanceBlockComponentType()
ResourceType<ChunkStore, InstanceDataResource>	getInstanceDataResourceType()
ComponentType<EntityStore, InstanceEntityConfig>	getInstanceEntityConfigComponentType()
static void	inheritDefaultWorldConfigSettings(WorldConfig instanceWorldConfig, GameplayConfig gameplayConfig)	Players can override some of the default settings when creating a new world (e.g. toggling fall damage/PvP), so we need to carry these over in some instances (like portals).
static CompletableFuture<World>	loadInstanceAssetForEdit(String name)	Opens an instance asset in-place to allow for modifying.
static String	safeName(String name)	Removes characters that cannot be used in world names and replaces them with -.
static void	safeRemoveInstance(World instanceWorld)	Flags the instance for removal by changing its removal conditions to remove once empty, ignoring the rest.
static void	safeRemoveInstance(String worldName)	Flags the instance for removal by changing its removal conditions to remove once empty, ignoring the rest.
static void	safeRemoveInstance(UUID worldUUID)	Flags the instance for removal by changing its removal conditions to remove once empty, ignoring the rest.
CompletableFuture<World>	spawnInstance(String name, World forWorld, Transform returnPoint)	Spawns an instance of the instance asset world.
CompletableFuture<World>	spawnInstance(String name, String worldName, World forWorld, Transform returnPoint)	Spawns an instance of the instance asset world.
CompletableFuture<World>	spawnInstance(String name, String worldName, World forWorld, Transform returnPoint, Consumer<WorldConfig> configureWorld)	Spawns an instance of the instance asset world.
static void	teleportPlayerToInstance(Ref<EntityStore> playerRef, ComponentAccessor<EntityStore> componentAccessor, World targetWorld, Transform overrideReturn)	Called to teleport the given player entity to the target world.
static void	teleportPlayerToLoadingInstance(Ref<EntityStore> entityRef, ComponentAccessor<EntityStore> componentAccessor, CompletableFuture<World> worldFuture, Transform overrideReturn)	Teleports a player to a world that may not be loaded yet.
static void	teleportPlayerToLoadingInstance(Ref<EntityStore> entityRef, ComponentAccessor<EntityStore> componentAccessor, CompletableFuture<World> worldFuture, Transform overrideReturn, Transform arrival)	Called to teleport the given player entity to a loading target world, arriving at arrival instead of the world's spawn point when provided.

Methods inherited from class JavaPlugin

getClassLoader, getFile, getType

Methods inherited from class PluginBase

getAssetRegistry, getBasePermission, getChunkStoreRegistry, getClientFeatureRegistry, getCodecRegistry, getCodecRegistry, getCodecRegistry, getCommandRegistry, getDataDirectory, getEntityRegistry, getEntityStoreRegistry, getEventRegistry, getIdentifier, getLogger, getManifest, getName, getState, getTaskRegistry, isDisabled, isEnabled, preLoad

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

INSTANCE_PREFIX

@Nonnull
public static final String INSTANCE_PREFIX

The prefix used for instance worlds.

Only used when an instance doesn't have a fixed name and needs one generated for it.

See Also:

• Constant Field Values

CONFIG_FILENAME

@Nonnull
public static final String CONFIG_FILENAME

The file name of the config file for an instance.

See Also:

• Constant Field Values

Constructor Details

InstancesPlugin

public InstancesPlugin(@Nonnull
 JavaPluginInit init)

Default Constructor for an InstancesPlugin instance.

Parameters:

init - The plugin initialization step for this plugin.

Method Details

get

public static InstancesPlugin get()

Returns:

the global static instance of this plugin.

spawnInstance

@Nonnull
public CompletableFuture<World> spawnInstance(@Nonnull
 String name,
 @Nonnull
 World forWorld,
 @Nonnull
 Transform returnPoint)

Spawns an instance of the instance asset world.

Depending on the type of instance this may take a while to complete.

Parameters:

name - The name of the instance asset to spawn.

forWorld - The world this instance is for

returnPoint - The return point in the previous world to return to on exit

Returns:

A future that will return the created world once ready.

spawnInstance

@Nonnull
public CompletableFuture<World> spawnInstance(@Nonnull
 String name,
 @Nullable
 String worldName,
 @Nonnull
 World forWorld,
 @Nonnull
 Transform returnPoint)

Spawns an instance of the instance asset world.

Depending on the type of instance this may take a while to complete.

Parameters:

name - The name of the instance asset to spawn.

worldName - The name of the world to spawn, or null to use a generated name.

forWorld - The world this instance is for

returnPoint - The return point in the previous world to return to on exit

Returns:

A future that will return the created world once ready.

spawnInstance

@Nonnull
public CompletableFuture<World> spawnInstance(@Nonnull
 String name,
 @Nullable
 String worldName,
 @Nonnull
 World forWorld,
 @Nonnull
 Transform returnPoint,
 @Nullable
 Consumer<WorldConfig> configureWorld)

Spawns an instance of the instance asset world.

Depending on the type of instance this may take a while to complete.

Parameters:

name - The name of the instance asset to spawn.

worldName - The name of the world to spawn, or null to use a generated name.

forWorld - The world this instance is for

returnPoint - The return point in the previous world to return to on exit

configureWorld - Adjusts the loaded WorldConfig before the world starts, so world start listeners see the changes. Not called when an existing copy is reused.

Returns:

A future that will return the created world once ready.

inheritDefaultWorldConfigSettings

public static void inheritDefaultWorldConfigSettings(@Nonnull
 WorldConfig instanceWorldConfig,
 @Nonnull
 GameplayConfig gameplayConfig)

Players can override some of the default settings when creating a new world (e.g. toggling fall damage/PvP), so we need to carry these over in some instances (like portals).

teleportPlayerToLoadingInstance

public static void teleportPlayerToLoadingInstance(@Nonnull
 Ref<EntityStore> entityRef,
 @Nonnull
 ComponentAccessor<EntityStore> componentAccessor,
 @Nonnull
 CompletableFuture<World> worldFuture,
 @Nullable
 Transform overrideReturn)

Teleports a player to a world that may not be loaded yet.

Parameters:

entityRef - The entity reference of the entity we are teleporting.

componentAccessor - The ComponentAccessor for component access.

worldFuture - The future that will return the world.

overrideReturn - The potential return location to set on player return.

teleportPlayerToLoadingInstance

public static void teleportPlayerToLoadingInstance(@Nonnull
 Ref<EntityStore> entityRef,
 @Nonnull
 ComponentAccessor<EntityStore> componentAccessor,
 @Nonnull
 CompletableFuture<World> worldFuture,
 @Nullable
 Transform overrideReturn,
 @Nullable
 Transform arrival)

Called to teleport the given player entity to a loading target world, arriving at arrival instead of the world's spawn point when provided.

teleportPlayerToInstance

public static void teleportPlayerToInstance(@Nonnull
 Ref<EntityStore> playerRef,
 @Nonnull
 ComponentAccessor<EntityStore> componentAccessor,
 @Nonnull
 World targetWorld,
 @Nullable
 Transform overrideReturn)

Called to teleport the given player entity to the target world.

Parameters:

playerRef - The entity reference of the player entity.

componentAccessor - The ComponentAccessor<EntityStore> for component access.

targetWorld - The target world that the player is teleporting to.

overrideReturn - The potential return location to set on player return.

exitInstance

public static CompletableFuture<Void> exitInstance(@Nonnull
 Ref<EntityStore> targetRef,
 @Nonnull
 ComponentAccessor<EntityStore> componentAccessor)

Returns the entity to the return world/point for the instance they are currently in.

Parameters:

targetRef - The entity reference of the entity.

componentAccessor - The component accessor for component access.

Throws:

IllegalArgumentException - If the entity is not in an instance or the return world is missing.

safeRemoveInstance

public static void safeRemoveInstance(@Nonnull
 String worldName)

Flags the instance for removal by changing its removal conditions to remove once empty, ignoring the rest.

Parameters:

worldName - The name of the world to remove.

safeRemoveInstance

public static void safeRemoveInstance(@Nonnull
 UUID worldUUID)

Flags the instance for removal by changing its removal conditions to remove once empty, ignoring the rest.

Parameters:

worldUUID - The unique UUID of the world to remove.

safeRemoveInstance

public static void safeRemoveInstance(@Nullable
 World instanceWorld)

Flags the instance for removal by changing its removal conditions to remove once empty, ignoring the rest.

Parameters:

instanceWorld - The world to remove.

getInstanceAssetPath

@Nonnull
public static Path getInstanceAssetPath(@Nonnull
 String name)

Returns the path to the instance asset (the world) with the given name.

Parameters:

name - The name of the instance asset (can include subdirectories like "Category/MyInstance").

Returns:

The path to the instance asset.

Throws:

IllegalArgumentException - if name attempts path traversal

doesInstanceAssetExist

public static boolean doesInstanceAssetExist(@Nonnull
 String name)

Returns whether an instance asset with the given name exists.

An instance asset exists if the world config exists for the given name. Chunks are not required.

Parameters:

name - The name of the instance asset to check for.

Returns:

Whether the asset exists.

loadInstanceAssetForEdit

@Nonnull
public static CompletableFuture<World> loadInstanceAssetForEdit(@Nonnull
 String name)

Opens an instance asset in-place to allow for modifying.

Loads it with a modified config to prevent updating the config and setting creative mode.

Parameters:

name - The name of the instance asset to load

Returns:

A future that will resolve to the loaded world

getInstanceAssets

@Nonnull
public List<String> getInstanceAssets()

Returns a list of instance assets

Returns:

The list of instance assets

safeName

@Nonnull
public static String safeName(@Nonnull
 String name)

Removes characters that cannot be used in world names and replaces them with -.

Parameters:

name - The name to make safe.

Returns:

the safe name of the instance.

getInstanceDataResourceType

@Nonnull
public ResourceType<ChunkStore, InstanceDataResource> getInstanceDataResourceType()

Returns:

the resource type for the InstanceDataResource resource

getInstanceEntityConfigComponentType

@Nonnull
public ComponentType<EntityStore, InstanceEntityConfig> getInstanceEntityConfigComponentType()

Returns:

the component type for the InstanceEntityConfig component

getInstanceBlockComponentType

@Nonnull
public ComponentType<ChunkStore, InstanceBlock> getInstanceBlockComponentType()

Returns:

the component type for the InstanceBlock component

getConfigurableInstanceBlockComponentType

@Nonnull
public ComponentType<ChunkStore, ConfigurableInstanceBlock> getConfigurableInstanceBlockComponentType()

Returns:

the component type for the ConfigurableInstanceBlock component