The System Node $CHARACTERSELECTIONSYSTEM (abbreviated CSS) implements the Clean Engine character selection mechanics including:
- Scaling mechanics for assigning a character to a CCS Instance for character creation
- Invoking a character selection GUI for the user
- Issuing appropriate events to the client system node
What problem(s) does this solve?
- Known pattern for extension of the system (a system node)
- Common game-specific functionality is easily implemented by overriding the appropriate method
- Reduces, but does not eliminate, the need to implement game-specific code
What problem(s) does this not solve?
- Does not implement your game's character selection GUI
The CSS is both Client and Server System Nodes
The $CHARACTERSELECTIONSYSTEM implements an interface on the client through which GUIs may communicate with the server system node to execute code in permissible ways. Both system nodes may be extended individually, allowing each side to be overridden as needed, replacing individual behaviors without requiring the implementation of a whole system.
The CSS Area is registered as a "System Area" with the World
One of the scalability features of the CSS is that it registers, when enabled, the CSS area as a System Area which provides access to some types of data that are normally only available at the World Server level. Specifically area data (such as which area instances are currently up).
Adding game-specific functionality
As a required class/script, it is not permissible to make changes to the _characterSelectionSystemClassMethods 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 CHARACTERSELECTIONSYSTEM 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 _characterSelectionSystem as a suffix to the name (ex. HJ_characterSelectionSystem), this makes it easier to locate the pair of classes (the required script prefixed in _characterSelectionSystem 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 CHARACTERSELECTIONSYSTEM 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 CHARACTERSELECTIONSYSTEM, hj_characterSelectionSystem;
|mpac CHARACTERSELECTIONSYSTEM, hj_characterSelectionSystem;
Disable the CSS
If you do not want to take advantage of the CSS or have implemented an alternate system that has not yet been adapted to using the CSS, you can easily disable the entire system by implementing the method described below in a game-specific override class that is GLOMmed onto the server system node.
method HE_CSSEnabled( enabled references Boolean ) as Boolean // Globally enabled/disable the CSS system // To disable the CSS system: enabled = false return true .
Clean Engine Selection GUI
The Clean Engine GUI implements the basic functionality required to select a character, initiate creation of a new character, and delete an existing character. The mechanics of the Clean Engine GUI are implemented in the _GUICSSCharacterSelectionClassMethods script.
Select a character and login
The CSS GUI (right) allows a user to select a character from a list of their existing characters by clicking on the character name and then the login button. Clicking the Load into Clean Test Area will cause the character to load into a clean test area (new play instance) with minimal assets instead of loading into the area from which the character logged off. The clean test area is HeroEngine_StartingArea (by default), but may be overridden to any area you like by implementing a game-specific class for the $CLEANTESTAREA system node.
Change to a game-specific character selection GUI
The CSS launches the character selection GUI in a method on the client system node, what kind of GUI to launch is easily overridden by implementing the following method in your game-specific class on the system node.
method HE_CSSInvokeGUI( args as LookupList indexed by String of String ) as Boolean // Used by $CHARACTERSELECTIONSYSTEM // // Used to invoke the character selection gui. The args passed in are the args that where passed // to the client system node by the _CSSInvokeGUI method on the server node which could be extended/overridden // by implementing the HE_CSSInvokeGUI method on the server and adding whatever data is needed to a remote call that // the override makes to the client system node. // // return true to indicate you handled everything ie popped up your game-specific gui return false .
Change the prototype from which the _PlayerCharacter Node is instantiated
When a new character is requested, HSL uses the external function NewCharacter and passes in the name of a prototype that should be used. The class of the specified prototype must inherit from _PlayerCharacter and may have any additional game-specific classes as parent classes. Since it is a prototype, you may set any field values to appropriate values to serve as their defaults.
The prototype that is used may be changed by implementing the HE_CSSUseCharacterPrototype method in your game-specific class on the CHARACTERSELECTIONSYSTEM node.
method HE_CSSUseCharacterPrototype( args as LookupList indexed by String of String, proto references NodeRef ) as Boolean // Used by $CHARACTERSELECTIONSYSTEM // // return a reference to the prototype from which you want character nodes to be created, args lookup // is the args passed in the original remote call from the client GUI requesting a new character // be created so you could pass some data in it to specify which character prototype is appropriate proto = GetPrototype( "GameSpecificCharacterPrototypeName" ) return true .
Character Movement State Knowledge
The default HeroEngine character controller (C++) communicates character movement commands to the server, on the server some state information is exposed by the clean engine class _characterMoveState. When you implement your own character controller, it is quite likely that you will want different/additional state information to be exposed to script on the server.
Assuming you have chosen to use the CSS, during character selection a method call is made to the method _CSSAddCharacterMoveState and to an override method HE_CSSAddCharacterMoveState during which the _characterMoveState class (or your game-specific class) is GLOMmed onto the character.
method HE_CSSAddCharacterMoveState( character as NodeRef of Class character_class ) as Boolean // Used by $CHARACTERSELECTIONSYSTEM // // The character move state class handles callbacks from the C++ engine to cache movement state for the // character. The default class, handles the clean engine character controller's states but if you have // replaced the character controller with your own, you will almost certainly have different/additional states // that need to be cached and events handled/raised. // // return true to indicate none of the default behavior should execute return false .
See also: Character Move State
- $CHARACTERCREATIONSYSTEM - The CSS sends players to the Character Creation System if they select the create new character option.
- 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.