Adapting Clean Engine

Jump to: navigation, search


The initial setup of the HeroCloud comes with a placeholder package of assets and scripts to facilitate you and your team being able to login and work on day 1. This "Clean Engine" is there to be replaced or modified by you, and contains only very basic implementations of systems like combat and camera movement. But also contains all the core aspects required to have an online game: accounts, characters, areas, timers, on and on. The HeroEngine does not make any assumptions about what sort of game you are making, and so it contains no default implementations of standard types of game-specific elements. Instead, framework contains generic building blocks to show how various pieces of the engine fit together.

We don't recommend trying to tackle taking apart the Clean Engine until you are well along with your familiarity with the engine and the HSL. You'll need to understand how all aspects of the engine work: the GOM, the DOM, System Nodes, Classes, Methods, and Prototypes, but reading on below is a good way to begin to understand how the puzzle pieces fit together.

Also, just when you think you've found all the files, there will be more. And there will be more nodes being loaded, and hidden prototypes. There will be times when you'll have to rebuild the account node, or when characters you've created will be in a broken state due to being associated with old versions, and not your new versions. If this is a task you'd like to take on early in your development, it can be rewarding and informative, but extremely frustrating. Use the forums for help.

System Nodes

System Nodes are special nodes that provide an HeroScript API to HeroEngine. The API is represented by the methods on the classes of these nodes. And, because of that, they are extensible by extending the System Nodes. This is the mechanism used to override the default behaviors that come with the Clean Engine implementation of HeroEngine.

HeroEngine includes numerous System Nodes. System Nodes are special nodes that are created from prototypes, and are referenced via script in the format $PROTOTYPENAME. When referenced for the first time in an Area Server instance, a new node is instantiated from the prototype, and each additional reference from that area server will use the same node (i.e. "singleton pattern").

Some of these prototypes are created from classes that have Class Method scripts that are required by HeroEngine. These class method scripts hold HSL callbacks from the server engine or game client to allow your game to respond to certain events. The callback code, which is part of the Clean Engine set of scripts, have been written to pass along notification of these events to your game-specific scripts in addition to any other default processing they may do. This is a surface against which you interface your game-specific implementation with the Clean Engine.

Even before you write your first script, however, the Clean Engine will already have a certain amount of scripted default game behavior in order to provide functionality at your first login, such as chatting and walking around an area with a character. You will need to replace this default, game-specific HSL with your own game-specific implementations.

See also: System Nodes

Replacing HeroEngine game-specific scripts with your own

On the server there are several fundamental system nodes that hold HSL callbacks from the server engine. Of those, three have HeroEngine game-specific code associated with them that you will want to replace. HeroEngine game-specific means that a minimal amount of game functionality has been provided with the Clean Engine in order to provide you with the functionality for creating characters and moving around the environment with them. To proceed with the developing of your own world, that basic functionality must be replaced by your own game’s specific implementations.

The system nodes in question are:

For each of the above system nodes, you will need to:

  1. Create your game-specific version of the class and scripts that handle the callbacks to these nodes;
  2. Remove the HE_nodeClassMethods class from the prototype that creates each node;
  3. And then add the class you've created, to the prototypes.

GameID in the table below refers to some game-specific identifier for your game.

For example, Hero's Journey uses "HJ"; so, in the Hero's Journey implementation, we'd have a class named HJArea and a script named HJAreaClassMethods. This is simply a convention, as you can use any names you prefer, but the convention helps in documenting the process involved and keeping game-specific code clearly identified at the interface surfaces. The HeroMachine (script interpreter) expects the script to be named as a munge of ClassName + "ClassMethods".

System Node HeroEngine Class HeroEngine Script Your Class Your Script
$WORLD HE_World HE_WorldClassMethods GameIDWorld GameIDWorldClassMethods
$AREA HE_Area HE_AreaClassMethods GameIDArea GameIDAreaClassMethods
$ACCOUNT HE_Account HE_AccountClassMethods GameIDAccount GameIDAccountClassMethods

The classes you create require no fields, but you can add any you wish for your own purposes, either at creation or in the future. The classes can be created using the DOM Editor panel in HeroBlade, as new server data definitions of the classes. (Remember to uncheck "Read Only" to enable DOM changes!)

Once the classes exist, create the appropriate server Class Method script for each class, using the HeroScript Editor. It is recommended that you start by copying the contents of each HE_classClassMethods script into your own, changing the debug messaging to reference your product instead of "default HeroBlade". Also, comment out any HE_ method that contains only debug messaging but leave the Debug() method at the end of the script intact.

To open the HE_classClassMethods scripts, check the "Show Engine" box in the Open Server Script panel of the Script Editor. Copying and editing the default scripts in this way will give you a starting point from which to build, as well as ensure that other HeroEngine systems that you aren't ready to replace will continue operating in their default behavior.

Additional System Nodes

There are additional system nodes you may want to extend in this fashion. See System nodes

The HeroEngine Control Panel

Modification of system nodes is primarily done using a GUI Interface called the "HeroEngine Control Panel". This panel allows you to add or remove classes from the prototype from which a system node is instantiated. It also simultaneously performs the communication necessary to update all instantiations of the system node.

Opening the HeroEngine Control Panel

There are three ways by which you may open the HeroEngine Control Panel:

Invoking the HeroEngine Control Panel via the Utilities Interface

Located on the "TOOLS" panel of the Utilities Interface is an option to invoke the "System Nodes Configuration GUI".


Clicking the "System Nodes Configuration GUI" link will invoke the HeroEngine Control Panel.

Invoking the HeroEngine Control Panel via /HESETUP LAUNCHGUI

Open the "Chat Panel" and type the following /command into the text input box: /HESETUP LAUNCHGUI

Invoking the HeroEngine Control Panel via the Console

Open the "Console" Panel and type the following script call into the text input box: call he_controlpanelgui open


Using the HeroEngine Control Panel

This will open the following GUI, which you can use to edit the classes on system nodes and other persisted nodes used by HeroEngine.


To begin, select a system from the dropdown box that you wish to customize for your game.


Once selected, remove any HeroEngine game-specific class that may be present. These classes will always have names that are prefixed with HE_. Simply click the Remove button for the class you wish to remove. Note that the first listed class in the list is the foundation class from which the node was instantiated, and can not be removed.


When the Remove button is clicked, you will be asked to confirm removal.


Once removed, you then add your game-specific class to the node by typing the name of your class and clicking Add. In the example below, we are re-adding the HeroEngine game-specific class that we just removed.


This process is identical for all of the systems listed in the dropdown menu. Also note that in addition to server-side systems, you can use the process for persistent client-side systems as well.

ChangeToClientSystems.jpg ChangeToClientSystems2.jpg

This process only needs to be done once per system, and from that point on you can simply work with your new scripts as the interface layer to HeroEngine.

IMPORTANT: Note that making changes to system nodes via this control panel will automatically update instantiated copies of those prototypes in spun-up areas, which may have ramifications if you have adapted any of them for local data storage.

Extending the HeroScript language

HeroEngine also has capabilities to allow your programmers to create new plugin DLLs, to even further extend the HeroScript language. This means adding new external functions to do whatever your team needs. For example, if your programmers want to create special HSL functions which will interface with your website, these functions can be created via a HeroScript extension plugin, which is a DLL that can be loaded on the client or the server, depending on your game's needs.

More information is available at It is C++ code that you can compile to create a special DLL that adds new example functions to HeroScript. Once compiled, the DLL is put into the install directory on the client. A sample script then calls the load/unload functions which make the new DLL-enabled functions available to HSL. The sample script also has examples of functions which call the new DLL-enabled functions, via a CALL command.

For more details, see HeroScript Extension Interface.

Character Creation and Selection

HeroEngine defines certain special well-known Areas:

Overriding these games systems is done mechanically like overriding the C++ callbacks for the system nodes specified above, by using the HeroEngine control panel to select the system, then remove/add game-specific classes.

Character Selection

The Character Selection Area (Area ID 1) has special behavior: Accounts that are connecting to the game are loaded there so that a character can be created/selected, and then routed to an appropriate game play area. Area 1 is the only area where the NewCharacter(), DeleteCharacter(), and SelectCharacter() external functions can operate.

See also: CSS

Character Creation System (CCS)

The Clean Engine default implementation provides no character customization at creation other than selecting a name. To replace HeroEngine's character creation you should implement overrides for the CCS in gameIDCharacterCreationClassMethods script you created, which may include specifying a new area (using your game specific content developed by your area builders). It is recommended that you copy HE_CharacterCreationSystemClassMethods into gameIDCharacterCreationClassMethods to give you a starting point. Additionally, on the client you will want to shortly create your own GUI which may inherit from _GUICCSNameSelection and override those methods or may be something totally new.

See also: CCS

What next?

Beyond this is a variety of other systems that you can use as is, or replace with your own. The class methods scripts for $CHAT, $TRAVEL, $COMMANDHANDLER, $INPUT, $SPECORACLEUTILS, and $STATES provide the opportunity for customizing those systems to fit the needs of your game, some of which have equivalents on the client. Additionally many client-side system nodes have callbacks that you should explore and customize/override, the most notable being $COMMANDHANDLER, $BEHAVE, $BASECLIENT, $BASECHARCONTROL, and $CHARACTERSYSTEM.

For a complete list, See System nodes

See also

Personal tools