Server Regions

From Multiverse

Multiverse Servers

Installing  •  Installing on Linux  •  Running  •  Troubleshooting  •  FAQ  •  Release Notes  •  Updating  •  JMX Monitoring & Mgmt.

Infrastructure

Platform Architecture  •  Registering a World  •  Proxy Server  •  Event Handling  •  World Manager  •  Voice Server

Messaging System

Perception Messaging  •  Using Extension Messages  •  Message Marshalling  •  Multi-subject Messaging  •  Message Catalog

Object Architecture

World Instancing  •  Server Object Search  •  Server Regions  •  Server Markers

Scalability and Performance

Overview  •  Scalability Testing

Reference

File Layout  •  Property File  •  Logging  •  API

Contents 1 Overview 2 Built-in region features 2.1 Forest, grass, and water 2.2 Fog 2.3 Sound 2.4 Ambient light 2.5 Directional light 3 Accessing regions 4 Custom regions 4.1 Adding custom region properties 5 Custom region triggers 5.1 Defining a region trigger 5.2 MessageRegionTrigger 5.2.1 Trigger mode 5.2.2 Additional message properties 5.2.3 Property exclusions 5.2.4 Message type 5.2.5 Message class 5.2.6 Message properties 5.3 InstanceEntryRegionTrigger 6 Finding regions

Overview

Use Multiverse World Editor to create a region that defines a closed area that you can fill with sound, light, fog, grass, water, and so on. Regions are two-dimensional (they have no Y component) and are pinned to the terrain.

At run-time, the server supplies regions and their features to the client as needed.

In addition to the region features available in the World Editor, regions support custom features via name/value properties. When a player enters a custom region, the server can execute custom code to publish a message or put the player in an instance. See World Instancing for more information about instances.

Built-in region features

A single region can have all or none of these features.

• Forest, grass, and water
• Fog
• Sound
• Ambient light
• Directional light

Forest, grass, and water

All forest, grass, and water regions are sent to the client at connection time.

Fog

When a player is inside a fog region, the server sends the region's fog parameters to the client. If there are multiple overlapping regions, the server sends only the highest-priority region information.

Sound

When a player is inside a sound region, the server instructs the client to play the region's sound. Overlapping sound regions result in playing overlapping sounds. These are ambient sounds; they are played at a fixed volume everywhere in the region.

For more information, see Working with Sound.

Ambient light

When a player is inside an ambient light region, the server tells the client to change the ambient light color. If there are multiple overlapping regions, the server specifies only the highest priority region.

Directional light

When a player is inside a directional light region, the server tells the client to change the directional lighting. Diffuse and specular color are supported along with direction (set the Orientation in the WorldEditor). If there are multiple overlapping regions, only the highest priority region is used.

Accessing regions

Use the InstanceClient.getRegion() method to get a specific Region object in an instance. The arguments to this method are:

• long - Instance OID
• String - Name of the region
• int - Info selection flags. Bit-mask of REGION_* constants.

The flags are:

• InstanceClient.REGION_ALL - Get all region information
• InstanceClient.REGION_BOUNDARY - Get region boundary
• InstanceClient.REGION_PROPERTIES - Get region properties

Custom regions

Custom regions allow you to define your own server-side region features. The custom region is configured in the WorldEditor by adding NameValue properties. The properties trigger server code to run when a player enters or leaves the region.

Adding custom region properties

To add NameValue properties to a region:

1. In the World Editor, select a region in the object tree view.
2. In the Properties tab, select the "NameValue" property and click the "..." button that appears. This will bring up the Name Value dialog box where you configure custom region properties.
3. The left side of the dialog box shows the region's current properties. The right side may contain property templates. The templates are predefined property sets that enable region features.

To get the value of a specific NameValue property, call Region.getProperty(), passing the name String as the argument. To get a Map of all the NameValue properties, call Region.getPropertyMapRef().

Custom region triggers

A region with properties named "onEnter" or "onLeave" is a custom region. The property value is a comma separated list of RegionTrigger names. When a player enters a custom region, the "onEnter" triggers are run. When a player leaves a custom region, the "onLeave" triggers are run.

To control trigger behavior, use region properties.

Sampleworld registers two region triggers supplied with the Multiverse platform: MessageRegionTrigger and InstanceEntryRegionTrigger.

Defining a region trigger

To define a region trigger, define a class that implements the multiverse.server.objects.RegionTrigger interface. This interface has two methods:

• enter(), for objects entering the region
• leave(), for objects leaving the region.

These methods take two parameters:

• an MVObject that is the player.
• a Region that is the region that was entered. The region name, boundary points, and properties are all available from the Region.

Do not perform blocking or computationally expensive operations in region triggers. If required,schedule them in a different thread instead.

You must register a region trigger with the world manager using WorldManagerPlugin.registerRegionTrigger(). Generally, register a region trigger in extensions_wmgr.py, for example:

WorldManagerPlugin.registerRegionTrigger("myRegionTrigger", MyRegionTrigger())

If a region names an unregistered trigger, the instance server logs an error.

MessageRegionTrigger

The MessageRegionTrigger publishes a message when a player enters or leaves a region. The message is either an extension or property message and can be targeted or subject-based.

The message properties are taken from four sources

• "regionAction" -- every message will have this property set to either "onEnter" or "onLeave" depending on which action triggered the message.
• Trigger properties -- a fixed set of properties added to every message
• Region properties -- properties copied from the region object
• Object properties -- properties copied from the player object

The region and object properties are subject to the trigger's property exclusions; some property names can be filtered out.

Trigger settings and properties on the active region control trigger behavior. The trigger is stateless, so the same trigger can be used for multiple regions.

Trigger mode

To set the trigger mode, call MessageRegionTrigger.setMode(). The trigger mode is either:

• MessageRegionTrigger.TARGET_MODE -- publish a TargetMessage sub-class which will apply only to the object itself. When combined with message class 'extension' the message will be sent directly to the client.
• MessageRegionTrigger.SUBJECT_MODE -- publish a SubjectMessage sub-class which will be received by all perceivers of the subject (the player).

Additional message properties

Call MessageRegionTrigger.setMessageProperties() to set additional message properties. These properties are added to all messages sent by the trigger. The property exclusions do not apply to the additional properties.

Property exclusions

Call MessageRegionTrigger.setPropertyExclusions() to define property names excluded from messages. Useful when copying all region or object properties. The single parameter is a Set of Strings that are to be excluded from messages. Useful in combination with messageRegionProperties=ALL or messageObjectProperties=ALL.

Message type

Defined by region property "messageType"; the name of a MessageType. If not defined, then a default message type is used.

Message class

Defined by region property "messageClass"; either 'extension' or 'property'. When set to "extension" an ExtensionMessage or TargetedExtesionMessage is published depending on the trigger mode. When set to "property" a PropertyMessage or TargetedPropertyMessage is published depending on the trigger mode.

Message properties

Defined by region properties "messageRegionProperties" and "messageObjectProperties". Each is a comma delimited list of propery names. If the property is exactly "ALL", then all properties are used.

The properties named in "messageRegionProperties" are copied from the active region. The properties named in "messageObjectProperties" are copied from the object (the player). Unknown property names are ignored. Note that the object is the player's world manager sub-object so only those properties are available.

These properties are subject to the trigger's property exclusions.

InstanceEntryRegionTrigger

InstanceEntryRegionTrigger changes a player's instance when the player enters the region. The trigger is controled by region properties:

• instanceName -- destination instance name
• locMarker -- name of marker spawn point in destination instance

Use World Editor to add these properties to a region. In World Editor, select the region and then edit the NameValue property in the Property View. For details, see World Editor - Adding and editing properties.

Finding regions

If you know the region name, you can get the region by calling

InstanceClient.getRegion(Long instanceOid, String regionName)

For more information, see Accessing regions.

To find regions by property value, use the Server Object Search API with the following search parameters:

• objectType: Region.OBJECT_TYPE
• query: instance of Region.Search
• selection: instance of SearchSelection with flags Region.PROP_BOUNDARY, Region.PROP_PROPERTIES, or Region.PROP_ALL.

The Region.Search must have an instance OID (you can only search within a single instance). Region.Search is a PropertySearch sub-class so you can search by region property.

The search result is Region objects with the selected information. Only the region PROP_* flags are supported (property name selection is not supported). SearchSelection flags RESULT_KEYED and RESULT_KEY_ONLY are both supported.

instanceOid = InstanceClient.getInstanceOid("default")

queryProps = HashMap()
queryProps.put("onEnter","instanceEntry")
search = Region.Search(instanceOid,queryProps)

selection = SearchSelection(Region.PROP_ALL)
regions = SearchManager.searchObjects(Region.OBJECT_TYPE, search, selection)
print "Regions with onEnter=instanceEntry: " + str(regions)