multiverse.server.plugins
Class InstanceClient

java.lang.Object
  multiverse.server.plugins.InstanceClient

public class InstanceClient
extends Object

API for instance management. An instance is created from an instance template and optional override template. The instance template specifies the instance world file, initialization script, and load script. Instances may be persistent or non-persistent. Persistent instances can be unloaded and later loaded. Persistent instances will have the same oid when reloaded.

Note: Instance names may not be unique.

The initial instances should be created by a "post" script passed to the InstancePlugin process. If you're using the supplied 'multiverse.sh' or 'start-multiverse.bat', then the script is named $MV_HOME/config/myworld/startup_instance.py.

Instance objects are searchable using ObjectTypes.instance and PropertySearch. The search result is a collection of java.util.Map objects containing the selected properties. Select properties by name in the SearchSelection. If the selection mode is SearchSelection.RESULT_KEY_ONLY, then the result is a collection of Long instance oids. If the selection mode is SearchSelection.RESULT_KEYED, the result is a collection of SearchEntry where the key is the instance oid and the value is a java.util.Map.

See Also:

SearchManager.searchObjects(multiverse.server.objects.ObjectType, multiverse.server.engine.SearchClause, multiverse.server.engine.SearchSelection)

Nested Class Summary

static class	InstanceClient.CreateInstanceMessage
static class	InstanceClient.GetInstanceInfoMessage
static class	InstanceClient.GetMarkerMessage
static class	InstanceClient.GetRegionMessage
static class	InstanceClient.InstanceEntryReqMessage Request object instance entry.
static class	InstanceClient.InstanceInfo Instance information.
static class	InstanceClient.RegisterInstanceTemplateMessage

Field Summary

static int	FLAG_ALL_INFO Get all available instance information.
static int	FLAG_AMBIENT_LIGHT Get instance ambient light.
static int	FLAG_DIR_LIGHT Get instance directional light.
static int	FLAG_FOG Get instance fog.
static int	FLAG_MULTIPLE Get list of InstanceInfo.
static int	FLAG_NAME Get instance name.
static int	FLAG_OCEAN Get instance ocean data.
static int	FLAG_OID Get instance oid.
static int	FLAG_PLAYER_POPULATION Get current instance player population.
static int	FLAG_REGION_CONFIG Get instance regions.
static int	FLAG_SKYBOX Get instance skybox.
static int	FLAG_TEMPLATE_NAME Get instance template name.
static int	FLAG_TERRAIN Get instance terrain data.
static long	MARKER_ALL Get all marker information.
static long	MARKER_ORIENTATION Get marker orientation.
static long	MARKER_POINT Get marker location.
static long	MARKER_PROPERTIES Get marker properties.
static MessageType	MSG_TYPE_CREATE_INSTANCE
static MessageType	MSG_TYPE_DELETE_INSTANCE
static MessageType	MSG_TYPE_GET_INSTANCE_INFO
static MessageType	MSG_TYPE_GET_MARKER
static MessageType	MSG_TYPE_GET_REGION
static MessageType	MSG_TYPE_INSTANCE_DELETED
static MessageType	MSG_TYPE_INSTANCE_ENTRY_REQ
static MessageType	MSG_TYPE_INSTANCE_UNLOADED
static MessageType	MSG_TYPE_LOAD_INSTANCE
static MessageType	MSG_TYPE_LOAD_INSTANCE_CONTENT
static MessageType	MSG_TYPE_REGISTER_INSTANCE_TEMPLATE
static MessageType	MSG_TYPE_UNLOAD_INSTANCE
static Namespace	NAMESPACE Instance sub-object namespace.
static long	REGION_ALL Get all region information (search selection flag).
static long	REGION_BOUNDARY Get the region boundary (search selection flag).
static long	REGION_PROPERTIES Get the region properties (search selection flag).
static int	RESULT_ERROR_INTERNAL
static int	RESULT_ERROR_NO_WORLD_MANAGER
static int	RESULT_ERROR_RETRY
static int	RESULT_ERROR_UNKNOWN_OBJECT
static int	RESULT_OK
static String	TEMPL_INIT_SCRIPT_FILE_NAME Instance init script file name.
static String	TEMPL_INSTANCE_NAME Instance name.
static String	TEMPL_INSTANCE_TEMPLATE_NAME Instance template name.
static String	TEMPL_LOAD_SCRIPT_FILE_NAME Instance load script file name.
static String	TEMPL_LOADER_OVERRIDE_NAME World loader override name.
static String	TEMPL_TERRAIN_CONFIG_FILE Instance terrain config file (.mvt).
static String	TEMPL_UNIQUE_NAME Unique name flag (Boolean).
static String	TEMPL_WORLD_FILE_NAME Instance world file name.

Constructor Summary

InstanceClient()

Method Summary

static Long	createInstance(String templateName, Template override) Create an instance.
static boolean	deleteInstance(long instanceOid) Delete an instance.
static InstanceClient.InstanceInfo	getInstanceInfo(long instanceOid, int flags) Get instance information.
static List<InstanceClient.InstanceInfo>	getInstanceInfoByName(String instanceName, int flags) Get instance information by instance name.
static Long	getInstanceOid(String instanceName) Get instance oid from an instance name.
static List<Long>	getInstanceOids(String instanceName) Get loaded instance oids from an instance name.
static Marker	getMarker(long instanceOid, String markerName) Get marker location and orientation from a loaded instance.
static Marker	getMarker(long instanceOid, String markerName, long flags) Get marker information from a loaded instance.
static Point	getMarkerPoint(long instanceOid, String markerName) Get marker location from a loaded instance.
static Region	getRegion(long instanceOid, String regionName, long flags) Get region information from a loaded instance.
static int	loadInstance(long instanceOid) Load a persistent instance.
static boolean	objectInstanceEntry(long oid, BasicWorldNode instanceLoc, int flags) Move an object to a different instance.
static boolean	objectInstanceEntry(long oid, BasicWorldNode instanceLoc, int flags, BasicWorldNode restoreWnode) Move an object to a different instance.
static boolean	objectInstanceEntry(long oid, String instanceName, BasicWorldNode instanceLoc, int flags) Move an object to a different instance.
static boolean	registerInstanceTemplate(Template template) Register an instance template.
static boolean	unloadInstance(long instanceOid) Unload a persistent instance.

Methods inherited from class java.lang.Object

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

Field Detail

FLAG_OID

public static final int FLAG_OID

Get instance oid.

See Also:

Constant Field Values

FLAG_NAME

public static final int FLAG_NAME

Get instance name.

See Also:

Constant Field Values

FLAG_TEMPLATE_NAME

public static final int FLAG_TEMPLATE_NAME

Get instance template name.

See Also:

Constant Field Values

FLAG_SKYBOX

public static final int FLAG_SKYBOX

Get instance skybox.

See Also:

Constant Field Values

FLAG_FOG

public static final int FLAG_FOG

Get instance fog.

See Also:

Constant Field Values

FLAG_AMBIENT_LIGHT

public static final int FLAG_AMBIENT_LIGHT

Get instance ambient light.

See Also:

Constant Field Values

FLAG_DIR_LIGHT

public static final int FLAG_DIR_LIGHT

Get instance directional light.

See Also:

Constant Field Values

FLAG_OCEAN

public static final int FLAG_OCEAN

Get instance ocean data.

See Also:

Constant Field Values

FLAG_TERRAIN

public static final int FLAG_TERRAIN

Get instance terrain data.

See Also:

Constant Field Values

FLAG_REGION_CONFIG

public static final int FLAG_REGION_CONFIG

Get instance regions.

See Also:

Constant Field Values

FLAG_PLAYER_POPULATION

public static final int FLAG_PLAYER_POPULATION

Get current instance player population.

See Also:

Constant Field Values

FLAG_MULTIPLE

public static final int FLAG_MULTIPLE

Get list of InstanceInfo.

See Also:

Constant Field Values

FLAG_ALL_INFO

public static final int FLAG_ALL_INFO

Get all available instance information.

See Also:

Constant Field Values

MARKER_POINT

public static final long MARKER_POINT

Get marker location.

See Also:

Constant Field Values

MARKER_ORIENTATION

public static final long MARKER_ORIENTATION

Get marker orientation.

See Also:

Constant Field Values

MARKER_PROPERTIES

public static final long MARKER_PROPERTIES

Get marker properties.

See Also:

Constant Field Values

MARKER_ALL

public static final long MARKER_ALL

Get all marker information.

See Also:

Constant Field Values

REGION_BOUNDARY

public static final long REGION_BOUNDARY

Get the region boundary (search selection flag).

See Also:

Constant Field Values

REGION_PROPERTIES

public static final long REGION_PROPERTIES

Get the region properties (search selection flag).

See Also:

Constant Field Values

REGION_ALL

public static final long REGION_ALL

Get all region information (search selection flag).

See Also:

Constant Field Values

RESULT_OK

public static final int RESULT_OK

See Also:

Constant Field Values

RESULT_ERROR_UNKNOWN_OBJECT

public static final int RESULT_ERROR_UNKNOWN_OBJECT

See Also:

Constant Field Values

RESULT_ERROR_INTERNAL

public static final int RESULT_ERROR_INTERNAL

See Also:

Constant Field Values

RESULT_ERROR_NO_WORLD_MANAGER

public static final int RESULT_ERROR_NO_WORLD_MANAGER

See Also:

Constant Field Values

RESULT_ERROR_RETRY

public static final int RESULT_ERROR_RETRY

See Also:

Constant Field Values

NAMESPACE

public static Namespace NAMESPACE

Instance sub-object namespace.

TEMPL_INSTANCE_TEMPLATE_NAME

public static final String TEMPL_INSTANCE_TEMPLATE_NAME

Instance template name. Available on an instance object. Ignored on an instance template.

See Also:

Constant Field Values

TEMPL_WORLD_FILE_NAME

public static final String TEMPL_WORLD_FILE_NAME

Instance world file name. Available on an instance object and template.

See Also:

registerInstanceTemplate(Template), Constant Field Values

TEMPL_INIT_SCRIPT_FILE_NAME

public static final String TEMPL_INIT_SCRIPT_FILE_NAME

Instance init script file name. Available on an instance object and template.

See Also:

registerInstanceTemplate(Template), Constant Field Values

TEMPL_LOAD_SCRIPT_FILE_NAME

public static final String TEMPL_LOAD_SCRIPT_FILE_NAME

Instance load script file name. Available on an instance object and template.

See Also:

registerInstanceTemplate(Template), Constant Field Values

TEMPL_TERRAIN_CONFIG_FILE

public static final String TEMPL_TERRAIN_CONFIG_FILE

Instance terrain config file (.mvt). Overrides world file terrain configuration. Available on an instance object and template.

See Also:

registerInstanceTemplate(Template), Constant Field Values

TEMPL_INSTANCE_NAME

public static final String TEMPL_INSTANCE_NAME

Instance name. Available on an instance object.

See Also:

Constant Field Values

TEMPL_LOADER_OVERRIDE_NAME

public static final String TEMPL_LOADER_OVERRIDE_NAME

World loader override name.

See Also:

Constant Field Values

TEMPL_UNIQUE_NAME

public static final String TEMPL_UNIQUE_NAME

Unique name flag (Boolean). If true, then instance name must be unique during instance creation.

See Also:

Constant Field Values

MSG_TYPE_REGISTER_INSTANCE_TEMPLATE

public static final MessageType MSG_TYPE_REGISTER_INSTANCE_TEMPLATE

MSG_TYPE_CREATE_INSTANCE

public static final MessageType MSG_TYPE_CREATE_INSTANCE

MSG_TYPE_GET_INSTANCE_INFO

public static final MessageType MSG_TYPE_GET_INSTANCE_INFO

MSG_TYPE_GET_MARKER

public static final MessageType MSG_TYPE_GET_MARKER

MSG_TYPE_GET_REGION

public static final MessageType MSG_TYPE_GET_REGION

MSG_TYPE_LOAD_INSTANCE

public static final MessageType MSG_TYPE_LOAD_INSTANCE

MSG_TYPE_UNLOAD_INSTANCE

public static final MessageType MSG_TYPE_UNLOAD_INSTANCE

MSG_TYPE_DELETE_INSTANCE

public static final MessageType MSG_TYPE_DELETE_INSTANCE

MSG_TYPE_LOAD_INSTANCE_CONTENT

public static final MessageType MSG_TYPE_LOAD_INSTANCE_CONTENT

MSG_TYPE_INSTANCE_UNLOADED

public static final MessageType MSG_TYPE_INSTANCE_UNLOADED

MSG_TYPE_INSTANCE_DELETED

public static final MessageType MSG_TYPE_INSTANCE_DELETED

MSG_TYPE_INSTANCE_ENTRY_REQ

public static MessageType MSG_TYPE_INSTANCE_ENTRY_REQ

Constructor Detail

InstanceClient

public InstanceClient()

Method Detail

registerInstanceTemplate

public static boolean registerInstanceTemplate(Template template)

Register an instance template. The template specifies the instance world file, scripts, and custom properties. An instance template is required to create an instance.

The supported properties are:

TEMPL_WORLD_FILE_NAME -- name of the world file

TEMPL_INIT_SCRIPT_FILE_NAME -- instance initialization script

TEMPL_LOAD_SCRIPT_FILE_NAME -- load script The world file should be a .mvw file. The init script is run once when the instance is created. The load script is run each time a persistent instance is loaded after creation.

The file names undergo variable expansion prior to use. The supported variables are:

• $MV_HOME -- the value of MV_HOME environment variable
• $WORLD_NAME -- the world name
• $WORLD_DIR -- the world config directory: $MV_HOME/config/$WORLD_NAME

Returns:

True on success, false on failure

createInstance

public static Long createInstance(String templateName,
                                  Template override)

Create an instance. The instance properties are taken from the registered templateName merged with the override. Properties in the override template take precedence over those in the registered template. See registerInstanceTemplate(Template).

To make a persistent instance, set the persistent property in the registered or override template:

            Java:
            template.put(Namespace.OBJECT_MANAGER,
                ObjectManagerClient.TEMPL_PERSISTENT, true)
            Python:
            template.put(Namespace.OBJECT_MANAGER,
                ObjectManagerClient.TEMPL_PERSISTENT, Boolean(True))
        

Instance creation has the following steps:

1. Select world manager to host instance (currently hardcoded to "WorldManager1").
2. Generate instance object via object manager. Sub-objects are created in the instance and world manager plugins.
3. Load world file into instance; structures, lights, etc.
4. Create world editor defined spawn generators
5. Run the instance init script (TEMPL_INIT_SCRIPT_FILE_NAME)

Returns:

Instance oid on success, null on failure

loadInstance

public static int loadInstance(long instanceOid)

Load a persistent instance.

Instance loading has the following steps:

1. Select world manager to host instance (currently hardcoded to "WorldManager1").
2. Load instance object via object manager. Sub-objects are loaded in the instance and world manager plugins.
3. Load world file into instance; structures, lights, etc.
4. Load instance contents; persistent objects spawned in the instance
5. Create world editor defined spawn generators
6. Run the instance load script (TEMPL_LOAD_SCRIPT_FILE_NAME)

Returns:

RESULT_OK on success, RESULT_ERROR_UNKNOWN_OBJECT if the instanceOid does not exist, RESULT_ERROR_NO_WORLD_MANAGER if there's no world manager to host the instance, RESULT_ERROR_RETRY if the instance is in an intermediate state, and RESULT_ERROR_INTERNAL for any other error.

unloadInstance

public static boolean unloadInstance(long instanceOid)

Unload a persistent instance. For a non-persistent instance, this is the same as deleting the instance. Instance content (objects spawned in the instance) are automatically unloaded when the instance unloads. However, players in the instance are not unloaded.

A MSG_TYPE_INSTANCE_UNLOADED SubjectMessage is published after the content is unloaded, but before the instance object is unloaded. The message is published as a broadcast RPC and the caller waits for all subscribers to respond.

This operation is actually implemented in the object manager plugin.

Returns:

True on success, false on failure

deleteInstance

public static boolean deleteInstance(long instanceOid)

Delete an instance. Instance content (objects spawned in the instance) are automatically deleted when the instance is deleted. However, players in the instance are not deleted. For a persistent instance, the object and content are deleted from the database.

A MSG_TYPE_INSTANCE_DELETED SubjectMessage is published after the content is deleted, but before the instance object is deleted. The message is published as a broadcast RPC and the caller waits for all subscribers to respond.

This operation is actually implemented in the object manager plugin.

Returns:

True on success, false on failure

getInstanceOid

public static Long getInstanceOid(String instanceName)

Get instance oid from an instance name. Instance names may not be unique. In case of duplicate instance names, the selected instance is undefined.

Returns:

Oid on success, null on failure or unknown name.

getInstanceOids

public static List<Long> getInstanceOids(String instanceName)

Get loaded instance oids from an instance name. Currently does not support getting unloaded instances.

Returns:

List of oids. The list is empty if there are no instances matching the given name.

getInstanceInfo

public static InstanceClient.InstanceInfo getInstanceInfo(long instanceOid,
                                                          int flags)

Get instance information. Information is selected by the flags parameter. Information for unloaded instances is limited to the 'oid' and 'loaded' status.

Parameters:

instanceOid - Instance identifier.

flags - Bit-mask of the FLAG_* constants.

Returns:

Always returns an InstanceInfo. InstanceInfo.oid will be null if the instance does not exist.

getInstanceInfoByName

public static List<InstanceClient.InstanceInfo> getInstanceInfoByName(String instanceName,
                                                                      int flags)

Get instance information by instance name. Information is selected by the flags parameter. Currently does not support getting information for unloaded instances.

Parameters:

instanceName - Instance name.

flags - Bit-mask of the FLAG_* constants.

Returns:

List of InstanceInfo, one for each loaded instance. List will be empty if no instances of the given name are loaded.

getMarker

public static Marker getMarker(long instanceOid,
                               String markerName)

Get marker location and orientation from a loaded instance.

Parameters:

instanceOid - Instance identifier.

markerName - Marker name.

Returns:

Marker object or null if unknown instance or marker.

getMarker

public static Marker getMarker(long instanceOid,
                               String markerName,
                               long flags)

Get marker information from a loaded instance. Information is selected by the flags parameter.

Parameters:

instanceOid - Instance identifier.

markerName - Marker name.

flags - Bit-mask of MARKER_* constants.

Returns:

Marker object or null if unknown instance or marker.

getMarkerPoint

public static Point getMarkerPoint(long instanceOid,
                                   String markerName)

Get marker location from a loaded instance.

Parameters:

instanceOid - Instance identifier.

markerName - Marker name.

Returns:

Marker object or null if unknown instance or marker.

getRegion

public static Region getRegion(long instanceOid,
                               String regionName,
                               long flags)

Get region information from a loaded instance. Information is selected by the flags parameter.

Parameters:

instanceOid - Instance identifier.

regionName - Region name.

flags - Bit-mask of REGION_* constants; REGION_BOUNDARY, REGION_PROPERTIES, REGION_ALL.

Returns:

Region object or null if unknown instance or region.

objectInstanceEntry

public static boolean objectInstanceEntry(long oid,
                                          BasicWorldNode instanceLoc,
                                          int flags,
                                          BasicWorldNode restoreWnode)

Move an object to a different instance. The destination instance, location, and orientation are specified in instanceLoc. The destination instance must already be loaded. Passing InstanceClient.InstanceEntryReqMessage.FLAG_PUSH for flags pushes the current instance and location onto the player's instance restore stack. A subsequent instance entry with InstanceClient.InstanceEntryReqMessage.FLAG_POP will instance back to this location.

Passing InstanceClient.InstanceEntryReqMessage.FLAG_POP for flags removes the top entry from the player instance stack and moves the player to that instance and location. The bottom of the instance restore stack is the fail-safe location and is never removed.

The destination instance may be the same as the current instance.

Blocks until the instance entry is complete. Currently only supported for player objects.

See InstanceClient.InstanceEntryReqMessage for additional instance entry options.

Parameters:

oid - Object identifier (only players are supported).

instanceLoc - Instance and location.

flags - One of FLAG_NONE, FLAG_POP, or FLAG_PUSH from

restoreWnode - Location to push onto instance restore stack InstanceClient.InstanceEntryReqMessage.

Returns:

True on success, false on failure.

See Also:

InstanceClient.InstanceEntryReqMessage

objectInstanceEntry

public static boolean objectInstanceEntry(long oid,
                                          BasicWorldNode instanceLoc,
                                          int flags)

Move an object to a different instance. See objectInstanceEntry().

objectInstanceEntry

public static boolean objectInstanceEntry(long oid,
                                          String instanceName,
                                          BasicWorldNode instanceLoc,
                                          int flags)

Move an object to a different instance. The instance is identified by name (however instance names may not be unique).

See Also:

objectInstanceEntry(long,BasicWorldNode,int), InstanceClient.InstanceEntryReqMessage