$WORLD

From HEWIKI
(Redirected from Technical:$WORLD)
Jump to: navigation, search

Contents

The System Node $WORLD handles event callbacks on the World Server from the C++ engine. The callbacks primarily deal with very low level concepts such as an area spinning up/down, the area server to which an account is currently connected, and some generic mechanics used by system areas to access information related to those events. Callbacks are made in the World Server's local GOM.

What problems does this solve?

Concepts

$WORLD is a System Node

System nodes were adopted as the primary mechanism at the HSL script level enabling game-specific implementations of a licensee to extend/override the required functionality included in the Clean Engine. As with all system nodes, this is accomplished by GLOMming a game-specific class onto the WORLD prototype from which a singleton node $WORLD is instantiated for a particular local GOM.

Callbacks are performed in the World Server's local GOM

While system nodes are functionally singletons available for any area server to use, the C++ engine callbacks are performed only on the world area server for those events that are handled by the $WORLD system node. That means the only information available to script is information which is known/cached in the world area server.

World Events

The events for which the C++ engine notifies the $WORLD system node are:

_WorldClassMethods

The class methods script _worldClassMethods is a required script (included in Clean Engine) that implements the functionality of the $WORLD system node. As with all required scripts, you are not intended to make (under normal circumstances) changes to it. Rather it is expected that extension and overrides be performed in a game-specific class.

Usage

Adding game-specific functionality

As a required class/script, it is not permissible to make changes to the _worldClassMethods script. Instead, extension/overriding the script is accomplished by the creation of a game-specific class (and class methods script) that is GLOMmed onto the WORLD prototype.

Create a game-specific class

Using the DOM Editor create a new (server|client) class. Our recommendation is that you use a class name that incorporates the _world as a suffix to the name (ex. HJ_world), this makes it easier to locate the pair of classes (the required script prefixed in _world and your game-specific class).

Once you have created the game-specific class, create a new client class methods script for that class.

Adding a game-specific class

Adding your game-specific class to the WORLD prototype is achieved using the System Node Configuration GUI or the CLI server command \mpac or client |mpac in the Console Panel. The System Node Configuration GUI is the preferred method because it handles the communication to update any instantiations of a system node to reflect the changes you have made.

Using the System Node Configuration GUI

UtilitiesInterfaceConfigureSystemNodes.jpg

Opening the System Node Configuration GUI requires you to access the hidden Utilities Interface toolbox, located in the top left corner of the render window with ctrl-shift-click (or press F5), which will open the Interface. On the Tools tab within the menu, is an option to open the System Nodes Configuration GUI.

See also: Adapting Clean Engine



Using the CLI

It is important to recognize that modification of the prototype from which a system node is instantiated will not update any instantiations that have already been made in various local GOMs. That means your changes will not take effect until the area (in the case of server system nodes) restarts, or the client (in the case of client system nodes), restarts.

Adding a class to a prototype is done via the CLI command Modify Prototype Add Class(MPAC).

Server: \mpac WORLD, hj_world;
Client: |mpac WORLD, hj_world;



Extending _OnWorldLoad

The _OnWorldLoad event is called during the spinup of the world area server (area 0 instance 0).

There is a pre and a post callback made from the _worldClassMethods script to a game-specific implementation. The callbacks are made to the methods: HE_PreOnWorldLoad and HE_PostOnWorldLoad.

HE_PreOnWorldLoad

Called prior to any required functionality in _OnWorldLoad. This allows for any necessary setup prior to required setup by the Clean Engine script.

method HE_PreOnWorldLoad( world as NodeRef of Class WorldRoot )
  //  Used by SYSTEM.NODE.WORLD
.

HE_PostOnWorldLoad

Called following the required functionality in _OnWorldLoad, allows for game-specific setup after the required setup.

method HE_PostOnWorldLoad( world as NodeRef of Class WorldRoot )
  //  Used by SYSTEM.NODE.WORLD
.

Extending _OnWorldUnLoad

The _OnWorldUnLoad event is called during the spindown of the world area server (area 0 instance 0).

There is a pre and a post callback made from the _worldClassMethods script to a game-specific implementation. The callbacks are made to the methods: HE_PreOnWorldUnLoad and HE_PostOnWorldUnLoad.

HE_PreOnWorldUnLoad

Called prior to any required functionality in _OnWorldUnLoad, allows for any necessary cleanup prior to required cleanup by the Clean Engine script.

method HE_PreOnWorldUnLoad( world as NodeRef of Class WorldRoot )
  //  Used by SYSTEM.NODE.WORLD
.

HE_PostOnWorldUnLoad

Called following the required functionality in _OnWorldUnLoad, allows for game-specific cleanup following required cleanup.

method HE_PostOnWorldUnLoad( world as NodeRef of Class WorldRoot )
  //  Used by SYSTEM.NODE.WORLD
.

Extending _OnAreaRegister

The _OnAreaRegister event is called during the spin up and spindown of area instances (with a boolean set to indicate whether the area is loading or unloading).

The method passes a data node through to its callbacks when the area is loading. The class _SessionStarting is GLOMmed onto the data node. The data node is destroyed following the callbacks.

details as NodeRef of Class _AreaDetails = CreateNodeFromClass( "_AreaDetails" )
details.AreaID = areaID
details.AreaInstanceNumber = instanceID

HE_PreOnAreaRegister

Called prior to any required functionality in the _OnAreaRegister callback.

method HE_PreOnAreaRegister( details as NodeRef of Class _AreaDetails )
  //  Used by SYSTEM.NODE.WORLD
.

HE_PostOnAreaRegister

Called after any required functionality in the _onAreaRegister callback.

method HE_PostOnAreaRegister( details as NodeRef of Class _AreaDetails )
  //  Used by SYSTEM.NODE.WORLD
.

Request Spin-Up for an Area

The method _requestLaunchAreaServer exposed by the system allows for any area to issue a request for the world to spin up an arbitrary area. Assuming the area from which the request is made has registered for world knowledge, it will receive notification when the requested area instance has been spun up and is ready.

areaID as id = 999               // spin up for area 999
editInstance as boolean = false  // spin up request is for a play instance
var listener = $WORLD._createAreaLaunchScriptListener( SYSTEM.EXEC.THISSCRIPT )
requestID as id                  // RequestID is a unique ID assigned to this request
                                 //   only useful if the current area is registered for world AREA
                                 //   knowledge.  Otherwise no events will be received.
requestID = $WORLD._requestLaunchAreaServer( areaID, editInstance, listener )

The sample code above used a _obsAreaLaunchScriptListener, which makes a callback to the specified script with events related to the request.

Events 
All events generated by $WORLD for AREA knowledge are passed as objects of class _AreaDataSystemAreaEvent. The eventType is stored in the _systemAreaChangeType field.
<requestID> 
The first event generated on by the World following the LaunchAreaServer(), this event is used to pass the AreaInstanceNumber back so the listener(s) can match the requestID to the area instance number that corresponds to that request.
register 
Following successful launch of an area, a register change is sent to all areas registered for world AREA knowledge.
unregister 
Following successful shutdown, an unregister event is generated to notify all areas registeref for world AREA knowledge to remove the area instance from their local caches.
launchfailed-<requestID> 
A launchfailed-<requestID> is generated when the world responds that it was unable to launch the requested area.

Request Area Shutdown

The method _requestStopAreaServer exposed by the system allows for any area to issue a request for the world to shutdown an arbitrary area. Assuming the area from which the request is made has registered for world knowledge, it will receive notification when the area instance down in response to this request.

areaID as id = 999               // spin down for area 999
instance as id = 0               // spin down for edit instance
var listener = $WORLD._createAreaLaunchScriptListener( SYSTEM.EXEC.THISSCRIPT )
requestID as id                  // RequestID is a unique ID assigned to this request
                                 //   only useful if the current area is registered for world AREA
                                 //   knowledge.  Otherwise no events will be received.
requestID = $WORLD._requestStopAreaServer(areaID, tokens[3], listener )

The sample code above used a _obsAreaLaunchScriptListener, which makes a callback to the specified script with events related to the request.

The event that will be received by the listener for this request is unregister.

Reference

See also

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox