$AREA

From HEWIKI

Jump to: navigation, search

The System node $AREA handles event callbacks on the Area Server from the C++ engine. The callbacks primarily deal with very low level concepts such as an area spinning up/down. Callbacks made to the $AREA system node are made in the local GOM for an area.

What problem(s) does this solve?

Handles engine (C++) level callbacks into HSL for area events
Extensible framework using the system node concept

Concepts

$AREA is a System Node

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

Area Events

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

_OnAreaLoad
_OnAreaUnload
_OnAreaLoadFailed (called on the World Server's $AREA system node)
_NewAreaSetup (called on the World Server's $AREA system node)

Usage

Adding game-specific functionality

As a required class/script, it is not permissible to make changes to the _areaClassMethods 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 AREA prototype.

Create a new class
- Create a class method script for the class
GLOM the class onto the 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 _area as a suffix to the name (ex. HJ_area), this makes it easier to locate the pair of classes (the required script prefixed in _area 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 AREA 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

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.

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 AREA, hj_area;
Client: |mpac AREA, hj_area;

Extending _OnAreaLoad

The _OnAreaLoad event is called during spinup of the area.

There is a pre and post callback from _areaClassMethods during area spinup as well as a callback allowing for the CPU limit to be adjusted during spinup. The method calls are HE_AreaLoadTimelimit, HE_PreOnAreaLoad and HE_PostOnAreaLoad.

HE_AreaLoadTimelimit

Called prior to execution of the pre and post callbacks, allowing for an extension of the CPU limit during area spinup to account for computationally intense processes.

method HE_AreaLoadTimelimit(area as NodeRef of Class AreaRoot, limit references TimeInterval) as Boolean
  //  Used by $AREA.
  //  Set limit to the SYSTEM.EXEC.CPULIMIT that should be set for the area load callbacks, and return true.
  return false
.

HE_PreOnAreaLoad

Called following the opportunity to override the area load time limit. It handles any processing which must be done prior to the required code of the Clean Engine script.

method HE_PreOnAreaLoad( area as NodeRef of Class AreaRoot )
  //  Used by SYSTEM.NODE.AREA
.

HE_PostOnAreaLoad

Called following the required functionality in OnAreaLoad.

method HE_PostOnAreaLoad( area as NodeRef of Class AreaRoot )
  //  Used by SYSTEM.NODE.AREA
.

Common usage

This callback is typically used for various setup operations that need to be performed when the area launches. This includes such operations as:

Notifying the States System to initialize all of its states by running the NOTSET-->DefaultValue transition logic.
Register System areas with $WORLD for player and area events such as logon, spinup, spindown, etc.
Start creature AI

Extending _OnAreaUnload

The _OnAreaUnLoad event is called during spindown of the area.

There is a pre and post callback from _areaClassMethods during area spindown. The method calls are HE_PreOnAreaUnload, and HE_PostOnAreaUnload.

HE_PreOnAreaUnload

Called prior to any required functionality in the _OnAreaUnload method.

method HE_PreOnAreaUnload( area as NodeRef of Class AreaRoot )
  //  Used by SYSTEM.NODE.AREA
.

HE_PostOnAreaUnload

Called following any required functionality in the _OnAreaUnload method.

method HE_PostOnAreaUnload( area as NodeRef of Class AreaRoot )
  //  Used by SYSTEM.NODE.AREA
.

_NewAreaSetup

The callback _NewAreaSetUp is a special callback made when an area is created for the first time. The callback in this case is performed in the World Server process instead of the area's local GOM. During this callback, the external function GetRootNode() will return the areaRoot node for the newly created area. This functionality allows for any specialized setup functionality to run.

HE_PreNewAreaSetup

Called prior to any required functionality in _newAreaSetup.

method HE_PreNewAreaSetup( nodeAnchor as NodeRef of Class AreaNode )
  //  Used by SYSTEM.NODE.AREA
.

HE_PostNewAreaSetup

Called following any required functionality in _newAreaSetup.

method HE_PostNewAreaSetup( nodeAnchor as NodeRef of Class AreaNode )
  //  Used by SYSTEM.NODE.AREA
.

Extending _OnAreaLoadFailed

The method _ONAreaLoadFailed is a special callback performed in the World Server when the external functions LaunchAreaServer() or LaunchEditServer() return TRUE, indicating a spinup request was successfully started but a problem was subsequently encountered. This functionality allows for some kind of recovery code to be run, if there is such a need.

HE_PreOnAreaLoadFailed

Called prior to any required functionality during the _onAreaLoadFailed callback.

method HE_PreOnAreaLoadFailed( details as NodeRef of Class _AreaDetails )
  //  Used by SYSTEM.NODE.AREA
.

HE_PostOnAreaLoadFailed

Called following any required functionality during the _onAreaLoadFailed callback.

method HE_PostOnAreaLoadFailed( details as NodeRef of Class _AreaDetails )
  //  Used by SYSTEM.NODE.AREA
.

$AREA

Contents