Connection Logic covers the process of establishing and maintaining a connection between a client (HeroBlade|Player Client) and the server processes that service the connection. The logic involves a complex series of steps, typically including:
- Launch server by the Autolauncher (optional, but standard)
- Service Directory
- World (a.k.a. Shard)
- GamePlay Area
Connection to a Launch Server by the Autolauncher
The autolauncher is a company-specific application which handles the installation of the various files needed for HeroEngine. It communicates with a Launch Server to retrieve the current version. The autolauncher, if needed:
- Downloads a new version of client application.
- Installs new version
Connection To a Service Directory
Connection to a service directory involves the following steps:
- Authentication by way of the UACCESS Protocol to the Billing System chosen by the Licensee. This authentication occurs at the server.
- Selection of a World (a.k.a. Shard) to which to connect
- Disconnection from the Service Directory
- Forwarding the User to Connect to the selected World's services
When the user launches the HeroBlade or the Player Client, the application reads a configuration file (
.cfg) from the installation directory to determine which service directory it should talk to to authenticate and request a list of available worlds.
LauncherCommand=HEROBLADEREFERENCE.heal LoginServer=tcp:ref.servicedirectory.play.net:10373 AppStoragePath=HEROBLADEREFERENCE
Source code licensees will sometimes want to use a development version of a HeroBlade to connect to a service directory other than the one to which it typically communicates. This is easily accomplished by editing the
HeroBlade.cfg file to comment out the normal
LoginServer with another one. The comment delimiter is two slashes "//" and can be used
LauncherCommand=HEROBLADEREFERENCE.heal LoginServer=tcp:ref.servicedirectory.play.net:10373 //LoginServer=tcp:foo.servicedirectory.play.net:10373 //LoginServer=tcp:bar.servicedirectory.play.net:10373 AppStoragePath=HEROBLADEREFERENCE
In the above sample configuration file, the 2nd and 3rd versions of the LoginServer config line will be ignored when parsed due to the parsing looking for exactly
In release 1.67, the LoginServer line supports multiple service directories in a pipe '|' delimited format:
- <public service directory name 1>,<transport 1>|<public service directory name 2>,<transport 2>|...<public service directory name N>,<transport N>
LoginServer=US East Server 16,tcp:MC.A-USEAST-1A-C016.dyn.cloud.heroengine.net:10373|US East Server 1,tcp:MC.A-USEAST-1C-C001.dyn.cloud.heroengine.net:10373
Connecting using HE Admin
HE Admin provides a way to enter the world that bypasses the normal login process. HE Admin should be kept in mind if you plan on modifying the Clean Engine login process in case anything prevents users from accessing the game world.
Connection to a World
Once a user selects a world (a.k.a. shard) to which he/she wishes to connect, the client application establishes connections to services for that World.
- Establish connections to the world's services
- Repository Server - Scalable process that serves up repository files to populate the client's Local Repository Cache with game data/cotent
- Dude Server - Scalable dynamic process to which the client maintains a persistent TCP connection and through which virtually all communication with the client passes.
- World server is notified of Account Arrival
- Creates an Account Root Node if one does not exist for the user
- The connection is redirected to one (of N) Character Selection Areas
- A connection node is factoried for the user
- Character Selection mechanics
World Creates an Account Node
When the world is notified of account logon, the database is queries to get the ID of the Arbitrary Root Node that is the player's account node. If the account is not present in the database, the world factories a new account node from a prototype specified during startup (default
account_prototype) and notifies the database of the ID of the account node created.
World is Notified of Account Logon
At this point a callback is made at the World Server to the $ACCOUNT system node at the
_AccountLogon() method, notifying it that the account is starting its logon. This callback is of limited usefulness as it is made at the World Server and the account root node hierarchy is not loaded (and should not be loaded here anyway), it does however provide opportunity to tell other services to expect the user's logon.
// Call from C++ prior to the account in question starting its login process // This callback is made at the world server level and the account root // node is not loaded. It occurs once per session. unique method _AccountLogon( accountID as ID ) // Parameters: // accountID - ID of the account logging in .
The $ACCOUNT system node then makes a call to a game specific method
HE_AccountLogon() (if implemented).
// Call at the world level notifying it that an account is logging on. // Occurs only once per session, and the account node is not loaded // in the world server at the time of this call. method HE_AccountLogon( accountID as ID ) as Boolean // Used by $ACCOUNT // Parameters: // accountID - id of the account logging on // Returns: // handled - boolean indicating whether or not the clean engine // processing should be used return false .
The internal logical connection is then redirected to the Character Selection Area Instance 1, the ID of the Character Selection Area to use is a Configuration in Master Control.
Selection Area Notified Of Connection Arrival
Connection of the redirected internal logical connection to the Selection Area results in a callback to the $ACCOUNT system node to factory a player connection node to represent the client's connection.
// Called by C++ to factory the player connection node. // The primary class of a player connection node must either be _playerConnection or a child class thereof unique method _FactoryPlayerConnection(accountID as ID) as NodeRef of Class _playerConnection // Parameters: // accountID - ID of the account that needs a connection node // Returns: // connection - reference to the connection node created ...SNIP return connection .
As a part of the
_FactoryPlayerConnection call, a callback is made to a game specific override method
HE_FactoryPlayerConnection if implemented.
// C++ call from the engine to factory a connection node for the player, root nodes (such as the account/character) are attached // to the connection so they travel with the player as their connection switches between area servers method HE_FactoryPlayerConnection(accountID as ID, connection references NodeRef) as Boolean // Used by $ACCOUNT // Parameters: // accountID - id of the account for which the connection is being factoried // Returns: // handled - boolean indicating whether or not all necessary behaviors were handled by the override // connection - (by reference) reference to the connection node factoried by the override. The connection node must be factoried either from // the class _playerConnection or from a class that is a child. return false .
C++ then initializes some fields on the connection node and binds the internal logical connection to it.
Selection Area Notified Connection Session Started
Now that the connection is represented by a connection node, the selection area is notified that the connection session has started by a call to the $ACCOUNT system node at its
_ConnectionSessionStarted() method. The session started call is generally used to initialize the request the asynchronous load of the Account Root Node for this user.
Due to Arbitrary Root Node loading being asynchronous in nature, typically there is little additional processing that can be done at this point and the connection process is suspended pending the load of the account root node and subsequent attachment to the connection node.
// Called by C++ following the factory of a connection node in _FactoryPlayerConnection // this is called only once per session. Typically, this method is used to initialize the request to load // the account root node unique method _ConnectionSessionStarted( connection as NodeRef ) .
Which makes a call to the game specific override
// Initial call made from C++ to the Character Selection Area upon connection by a player // typically used to request the load of the player's account root node method HE_ConnectionSessionStarted( connection as NodeRef ) as Boolean // Used by $ACCOUNT // Parameters: // connection - reference to the _playerConnection node // Returns: // handled - boolean indicating whether or not the clean engine processing should be used return false .
Connection to a Game Play Area
Move To a New Area
Arrive in New Area
Seamlessly Move to a New Area
(does this need additional information?)