Untitled

{{tocright}}

The [[System node]] '''$AREA''' handles [[event callbacks]] on the [[Technical:Area Server|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 [[Technical:World Server|World Server's]] $AREA system node)
* _NewAreaSetup (called on the [[Technical:World Server|World Server's]] $AREA system node)

== Usage ==

{{SystemNodesAddingGameSpecificFunctionality|frameworkClass=_area|prototypeName=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.

<hsl>
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
.
</hsl>

=== 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.

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

=== HE_PostOnAreaLoad ===

Called following the required functionality in OnAreaLoad.

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

==== 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 [[Technical:States System|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.

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

=== HE_PostOnAreaUnload ===

Called following any required functionality in the _OnAreaUnload method.

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

== _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 [[Technical:World Server|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.

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

=== HE_PostNewAreaSetup ===

Called following any required functionality in _newAreaSetup.

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

== Extending _OnAreaLoadFailed ==

The method _ONAreaLoadFailed is a special callback performed in the [[Technical:World Server|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.

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

===HE_PostOnAreaLoadFailed ===

Called following any required functionality during the _onAreaLoadFailed callback.

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

== See also ==

* [[Adapting Clean Engine]] - Detailing the replacement/extension of Clean Engine via game-specific classes and the GUI created for that purpose.
* [Connection Logic]] - Details the logic that runs when a character connects/logs in.
* [[System Nodes]] - Primary mechanism for enabling the extension/overriding of the required Clean Engine implementations and a game-specific implementation of a licensee.
* [[Area node structure]]

[[Category:System Nodes|Area]]