- See also Adapting Clean Engine for instructions on how to adapt the Account System Node for your own game
The $ACCOUNT System Node handles event callbacks from the C++ Engine that are related to a _playerAccount root node on a particular Area Server. The callbacks primarily deal with very low level concepts such as logon/logoff, moving the _playerAccount node from one area to another, or notification that the client is ready to receive HSL RPCs. Callbacks made to the $ACCOUNT system node are generally made in the local GOM for the area in which the _playerAccount node is loaded (there are a few exceptions that occur on the world server).
What problem(s) does this solve?
- Handles engine (C++) level callbacks into HSL for events related to the _playerAccount node
- Extensible framework using the system node concept
$ACCOUNT is a System Node
System nodes are the primary mechanism at the HSL script level enabling game-specific implementations of a licensee. With system nodes, you can extend or override the existing functionality included in Clean Engine. As with all system nodes, this is accomplished by GLOMming (attaching) a game-specific class onto the ACCOUNT prototype. From this, a singleton node $ACCOUNT is instantiated for a particular local GOM.
The events for which the C++ engine notifies the $ACCOUNT system node are:
Logic Flow Diagram
The events detailed in this section are the more commonly used and useful ones, the Advanced Usage section contains the more esoteric callbacks.
Adding game-specific functionality
As a required class/script, it is not permissible to make changes to the _accountClassMethods 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 ACCOUNT 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 _account as a suffix to the name (ex. HJ_account), this makes it easier to locate the pair of classes (the required script prefixed in _account 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 ACCOUNT 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.
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.
\mpac ACCOUNT, hj_account;
|mpac ACCOUNT, hj_account;
The _EnteredArea method is called prior to _CharacterActivated allowing script the opportunity to perform actions such as positioning the character at a waypoint on a path prior to the client rendering the area. The clean engine script makes calls to two game specific methods one prior to required functionality HE_PreEnteredArea and one following required functionality HE_PostEnteredArea.
The _EnteredArea event can be used for any necessary setup for characters prior to the activation of the character so long as the setup does not involve updating the player's client. If you need to send remote call to the player's client, you must wait until the _ClientReady event. Please note that in area 1 (the character selection area) no character is yet selected and consequently the nodes may not be in the local GOM, so you may need to add exceptions to your game specific code depending on what you are doing.
The _ClientReady method is called after _EnteredArea when the player's client is ready to accept statful information about the area it is now entered. It is expected that it may sometimes be necessary to perform asynchronous tasks at this point of the login process, consequently the client waits in the "ready" state until the external function PlayerLoadFinished() is called or an arbitrary timeout occurs by default at one minute.
Clean engine script makes two calls to game specific functionality one before required functionality HE_PreClientReady and one after HE_PostClientReady. If your game specific functionality implements the post method, your code is in charge of calling PlayerLoadFinished() when your processing is complete.
The _CharacterActivated method is called following the execution of the external function
PlayerLoadFinished(). Being "activated" means that other clients are getting update packets for movement, timers have been unsuspended, the player's client is rendering the area, etc. The clean engine script implements calls to two override methods one prior to required functionality HE_PreCharacterActivated and one following required functionality HE_PostCharacterActivated.
This section contains some of the more specialized events, some of which because of the way the logon process works have limited use due to the limitations of the information available in the intermediate steps of logon.
The _AccountLogon method is called on the world server at the start of the logon process. During its processing, the clean engine script makes two override method calls one before any required processing HE_PreAccountLogon and one after any required HeroEngine stuff occurs HE_PostAccountLogon. It is important to note, at this point of the login process the client is not ready to receive remote calls.
The _AccountLogoff method is called on the world server at the end of the logoff process. During its processing, the Clean Engine script makes two override method calls one before any required processing HE_PreAccountLogoff and one after any required HeroEngine processing HE_PostAccountLogoff. Note that at the time of these callbacks you no longer have access to the account node as it is not loaded in the world server's GOM.
- Structure of an Account
- 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.