System nodes

From HEWIKI
(Redirected from System node)
Jump to: navigation, search

Contents

For a list of the words which are hardcoded into HeroEngine, see System variables.

System nodes are nodes which are created from named prototypes, and can then be referenced by name from any script. They have a multitude of uses, from non-persisted data and state storage, to event handling, and access to various methods. System nodes are non-persisted nodes, created on first use (if needed) from the prototype of the same name (i.e. "singleton pattern"). They exist until the area server process shuts down (so they cannot be used for information that should persist beyond that).

There are a few dozen System Nodes which are provided in Clean Engine as part of the MMO Foundation Framework, and many others can be created for your own game-specific implementation, as needed.

Referencing System Nodes

System nodes are referenced in HSL in one of two ways:

Because System Nodes are so commonly used, the ${Name} alias syntax was introduced. Essentially the $ style is a short-cut alias for SYSTEM.NODE. such that SYSTEM.NODE.CHAT can also be written more easily as $CHAT.

Simply referencing SYSTEM.NODE.aPrototypeName or $APrototypeName in script gives you a NodeRef to a single instance of that node (all references in the same area server, at any time, give the same node). You can call methods and access fields like any other NodeRef.

Usage

For the purpose of this example, say that there is a prototype named "Bob". The following code accesses the System Node created from that prototype:

function Example()
  $BOB.exampleField = true
  $BOB.ExampleMethod()
  var n = $BOB
  where n is kindof ExampleGlommed
    n.anotherField = n.anotherField + 1
  .
.

As another example, suppose you want to keep a count of how many times a script function executes. You could:

$COUNTPROTO.myCount = $COUNTPROTO.myCount + 1

Then in a different script function, you can access the count:

function count()
  println("count=" + $COUNTPROTO.myCount)
.

If you'd rather use methods instead of functions, add the following functions to CountClassClassMethods:

method CountIncrement()
  me.myCount = me.myCount + 1
.
 
method CountTotal() as integer
  return me.myCount
.

Then in the script function:

$COUNTPROTO.CountIncrement()

And in another script:

function count()
  println("count=" + $COUNTPROTO.CountTotal())
.

Anchors

Another common use of System Nodes is as an anchor point for a collection of associated nodes.

In this example, a function determines if a node is in the collection:

function IsInCollection(n as noderef)
  return queryAssociation( $EXAMPLE, "", n).length > 0
.

For any given script environment (client, area server, etc.) there is one instance of the System Node for a given prototype. It's data is local to that script environment, so setting a value in one area does not change it in other areas.

Creating a Server System Node

Using the DOM Editor or the CLI, create a new server class (for example a class named CharacterCache) that will serve as the base class for our new System Node. Once you have created the new server class, use the CLI to create a prototype from that class using the command CPFC.

\cpfc CharacterCache, CHARACTERCACHE; description="System Node for updating the client local cache of character/npc data"

Once the prototype is created, we can access methods on our new System Node in script using the $ syntax.

$CHARACTERCACHE.doStuff()

Creating a Client System Node

Using the DOM Editor or the CLI, create a new client class (for example a class named CharacterCache) that will serve as the base class for our new System Node. Once you have created the new client class, use the CLI to create a prototype from that class using the command CPFC.

|cpfc CharacterCache, CHARACTERCACHE; description="System Node for the local cache of character/npc data"

Once the prototype is created, we can access methods on our new System Node in script using the $ syntax. The prototype itself is not the system node, but the first time that $PROTOTYPENAME or SYSTEM.NODE.PROTOTYPENAME is referenced within an area, a singleton node is automatically created from the prototype, and that node will be used for any further references inside that area.

$CHARACTERCACHE.doStuff()

Advanced usage

Clean Engine implementations

System nodes are used extensively in Clean Engine implementations of both server and client systems. The pattern these follow is that the System Node prototype is created from a Clean Engine class, and then a game-specific implementation class may be GLOMmed onto the prototype for overriding/extending the behavior of the basic functionality.

Methods implemented in the Clean Engine class typically have a name with a leading "_", the override methods they call in a game-specific class method script are prefaced with "HE_" and will generally share the rest of the method name. Methods intended to be implemented by game-specific classes on System Nodes are declared in the "_methodCallbacksClassMethods" script.

CleanEngineSystemNodeStrategy.jpg

// Clean Engine implementation of the _BaseClientClassMethods
 
unique method _Area_Load(areaID as ID, instanceID as ID, AreaName as String)
// Called when Area_Loading is done.
// Note that AreaName is the area's name according to the Spec panel in HeroBlade, not
//   the name according to the Organizer panel.
// Take away the splash screen.
 
  handled as Boolean
  if hasMethod( me, "HE_Area_Load" )
    handled = me.HE_Area_Load(areaID, instanceID, AreaName)
  .
 
  me._SetAreaName( areaName )
 
  if not handled
    // optional stuff
  .
.

// Optional game-specific implementation in whatever class is added to the System Node
method HE_Area_Load(areaID as ID, instanceID as ID, AreaName as String) as Boolean
// Used by SYSTEM.NODE.BASECLIENT
//
// Called when Area_Loading and Area_Preload have completed
// Note that AreaName is the area's name according to the Spec panel in HeroBlade, not
//   the name according to the Organizer panel.
//
// return true skips any "optional" processing by required scripts as default
//   mechanics.  Any functionally required mechanics occur no matter what the setting of this field.
// 
  return false
.

Adding game-specific functionality to HeroEngine System Nodes

As Clean Engine System Nodes use a Required class and Required scripts, it is not permissible to make changes to the base class methods script for any of these System Nodes. Instead, extension/overriding of the methods is accomplished by the creation of a game-specific class (and class methods script) that is GLOMmed on the System Node's prototype.

The addition of game-specific functionality to a System Node is accomplished via the following steps:

Create a game-specific Class

Using the DOM Editor create a new (server or client) class. Our recommendation is that you use a class name that incorporates the Clean Engine class's name as a suffix to the name (ex. _characterCreationSystem might have a game-specific override class of HJ_CharacterCreationSystem). This makes it easier to locate the related classes (the required class methods script prefixed in _ and your game-specific class) for a particular System Node.

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

Adding a game-specific class

Adding your game-specific class to the System Node's 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
HotSpotConfigureSystemNodes.jpg

Opening the System Node Configuration GUI requires you to access the hidden Utilities Interface by pressing F5. On the TOOLs tab, you will find an option to open the System Nodes Configuration GUI.

Using the System Node Configuration GUI, you can ADD|REMOVE classes from HeroEngine System Nodes. When you add or remove, you might not see the changes reflected in the Current Classes list. Use the System drop-down menu to select a different system, then come back to SPECORACLEUTILS to confirm the changes made.

HeroEngineControlPanelGUI.jpg

The System Node Configuration GUI is the preferred method to modify HeroEngine System Nodes, because it handles the communication necessary to update all of the instantiations of the System Node with the change.

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.

Modify a Server Prototype: \mpac charactercreationsystem, hj_charactercreationsystem

Modify a Client Prototype: |mpac charactercreationsystem, hj_charactercreationsystem

Using Script

The prototype from which a System Node is instantiated may be altered via script, as with modifications via the CLI modifications via script will not update any instantiations that have been made in the 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.

var prototype = getPrototype( <nameOfSystemNode> )
GlomClassToPrototype( <yourClass>, prototype )

List of System Nodes

These are the System Nodes that are included as a part of the MMO Foundation Framework

See also

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox