Clean Engine Feature Overview

Jump to: navigation, search


If you have been tasked with evaluating HeroEngine and want a quickstart, try here instead: Introduction to HeroEngine

What is Clean Engine anyway?

Clean Engine (abbreviated herein as CE) refers to the package of C++, DOM, GOM, Repository and HSL elements that are required for the fundamental functionality of HeroEngine. Clean Engine also includes many generic systems that support the implementation of your game by providing a set of feature-dense foundational components. Clean Engine does not include game-specific components, but you will have access to a Hero's Journey reference to see how things are implemented in HJ.

What can I do out of the box?

Out of the box, you'll be able to log in. The basic area selection and area creation facilities are there, but the implementation for CE is bare-bones. There will be a list of characters that you can select from, but for character creation, the extent of things will be a box to enter your name. However, clean points of extension exist to build whatever GUI / look / behavior you want for your design at these points.

There is one generic "HeroEngine" character which you can use to walk around. It has enough animation and such to exercise the normal operations of movement. For your own game, it will be a trivial step to substitute your own character that you're working on, for the generic HeroEngine character.

In terms of art assets, there will be very little -- some ground for the aforementioned character to walk on, some art for basic generic in-game GUI, one particle effect, and so forth. Very, very light weight. The art assets you have probably seen so far have all been Hero's Journey assets. Starting with CE, they will all be your assets.

If your license includes a license for SpeedTreeRT, you get the full SpeedTree library to start with, which you will have to export to game-ready assets.

You will be working with the default character controller and there will be the usual input system config file that makes that work pretty much the same way as it does in HJ. You can replace it with the character you have wired up and you can walk this character around in the same way.

Also included is a bare-bones "character manager" that allows you to manipulate the features of a dynamic character. It is not a player-friendly-pretty UI, but rather a programmer UI so you can exercise those components. In HJ, we have both the player and this other version available... the player one is appropriate for users but the other one is appropriate for character artists and GMs (dressing NPCs, etc.). You, of course, will build your own character creation GUI to your own design specs.

Bare-bones chat is handled by the chat panel of HeroBlade with or without an in-game GUI representation. To add your own, just wire up a simple GUI from the components and hook into the chat callbacks. When we say chat is bare-bones, that means it doesn't have any game-specific features, such as how your channels (if you have any) might work.

Game slash commands can be issued through HeroBlade via the Chat Panel even before any in-game GUI exists for chat.

Where do I start?

See also: Introduction to HeroEngine

HeroEngine is a very big chunk of technology. So it will take awhile to get a grasp on all the moving parts. This section outlines a lot of the big-picture items with links to other places where you can learn more about them in detail.

When you have reviewed the overview, you can also jump to the various tutorials: Implementation Tutorials. Or, if you have a short time to evaluate HeroEngine and want a quickstart, try Introduction to HeroEngine, a page specifically written for those who have a short time (30 days) to evaluate the product.

Foundational components

The following are additional systems that are included with Clean Engine:

System nodes

System nodes provide convenient access to method calls for a variety of systems. As a rule, system nodes are written to be overridden or extended by the addition of a game-specific implementation class that is GLOMmed onto the system node, implementing HE_ methods called from the base class.

Included in the list below are only system nodes that are called by the C++ code. All other system nodes are parts of their systems and are detailed with the system.


The $ACCOUNT system node handles C++ callbacks for when the account starts a session, enters/leaves areas, activates its character, etc. Its functionality is implemented in the class _accountClassMethods. Very basic game functionality for CE, which is intended to be ultimately replaced by your game-specific implementation, is located in HE_AccountClassMethods.

The ACCOUNT system node participates in the login process.

See also: Adapting the Account System Node


The $AREA system node handles C++ callbacks for when the area is created, spins up/down etc. Its functionality is implemented in the class _areaClassMethods. Very basic game functionality for CE, which is intended to be ultimately replaced by your game specific implementation, is located in HE_AreaClassMethods.

The AREA system node participates in the login process.

See also: Adapting the Area System Node



The $BASECLIENT system node handles C++ callbacks on the client that deal with area (un)loading, room (de)activation, etc. Its functionality is implemented in the class _baseClientClassMethods. The BASECLIENT system node participates in the Login Process.


The $CHARACTERSYSTEM system node participates in the login process.


The HeroEngine chat system is our built-in way of passing strings between the server and clients (and vice versa) for messaging purposes. It is possible that you could replace the chat system entirely using your own system built with Inter-Process Communication should you desire. The chat system uses a slightly specialized version of remote calls to do its thing, but it's pretty similar.

See also: Chat System


The $EDIT system node handles all edit commands sent from HeroBlade to the server updating the server representation based on the edits. There are a limited number of methods located here that you might wish to override which handle how errors are handled and extension of area imports.


The input system node provides the entrance point from C++ for a variety of input events, it is handled by the class _InputHandler and the code is located in the class methods script _InputHandlerClassMethods.


The $REPOSITORY system node handles requests (from HeroEngine) for information about the file structure of the repository, specifically the path in which specific character specifications may be found. This is not to be confused with the general configurations of paths you may have made using Master Control.


The $WORLD system node handles C++ callbacks for when the world or areas spin up/down. Its functionality is implemented in the class _worldClassMethods. Very basic game functionality for CE, which is intended to be ultimately replaced by your game specific implementation, is located in HE_WorldClassMethods.

The WORLD system node participates in the login process.

See also: Adapting the World System Node

Character Creation System

The $CHARACTERCREATIONSYSTEM system node handles character creation in clean engine and provides a convenient set of hooks allowing for the implemenation of game specific systems.

Character Selection System

The $CHARACTERSELECTIONSYSTEM system node handles character selection in clean engine and provides a convenient set of hooks allowing for the implemenation of game specific systems.


Cinematics/Master Camera

See also: Cinematics

Master Camera Commands

Creatures and NPCs

The Creatures and NPCs|Creatures and NPCs system provides the fundamental HSL building blocks for the introduction of non-player characters to your game. Each subsystem of Creatures and NPCs is extendable and overridable such that you may use the systems or not as the needs of your game dictate, it is nearly certain you will at a minimum extend the functionality provided.

See also: Creatures and NPCs

Node Collections

A fundamental pattern in programming is creating lists (collections) of objects, adding new objects, removing objects and iterating through those objects. Because the need to create collections is common, the code supporting these can be extracted out of individual systems into something that can be generically reused as a system called Node Collections.

See also: HSL Node Collections

Command Handler

The command handler system is used to send strings from client to server to be interpreted via a server script, via a separate pathway from the chat system keeping the two distinct. Like chat, this system could effectively be replaced by other Inter-Process Communication, but doing that is not as lightweight. As the system is only capable of transmitting a single string, it should not be considered for use with complex data.

This system is used to implement the ubiquitous /commands typical in an MMO.

See also: Command Handler

Debugging Utilities

Debugging HSL scripts uses techniques familiar to programmers, and some that are not. In programming languages like C++, for example, one might debug code with asserts, printf()s, log messages, and ultimately a sophisticated debugging tool such as that built into Visual Studio. It is important to realize that HeroEngine servers are servicing many connected users simultaneously (both in the live game and in development) and therefore the HSL virtual machines cannot afford to be suspended for the typical "single stepping" that is common to debuggers. As you can imagine, this would break the highly collaborative nature of HeroEngine.

Instead, HeroEngine supports an extremely rapid iterative development style where a developer can make changes to code and compile in literally seconds to create rapid, incremental tests. Consequently, debugging HSL primarily consists of inserting messages or ASSERTs at major branches in the code and then adding additional messaging as needed to narrow down the problem.

This may seem odd, or a bit primitive at first, but it does work remarkably well. This is made possible by the extremely rapid code-compile-test cycle time (and no startup time, as in rerunning a C++ program).

Because of this approach, HeroEngine (and its essential systems) also include advanced functionality that allows for real-time monitoring of field changes (on the client), debug message histories and multiple implementations of the observer pattern for selective monitoring of these messages (so as to filter high-frequency message streams).

See also: Debugging Utilities

Fx System

Main page: Fx System

The Fx System is an event-driven control system that allows you to piece together particle effects, sound effects, models, and more, and display them on the client. With this system, you can create simple effects such as a having flames appear in a character's hand, to more complex effects such as: "hurling a fireball into the sky which is soon swallowed by a dark cloud and causes a beam of energy to strike the ground, scorching everything in its path as it draws a line of fiery vengeance along the ground"!

Fx's are created using the FxGUI. With it, the user can simply drag elements into their Fx, set properties that specify when each element should appear and dissappear, tell particle emitters to chase a target, attach elements to each other, transform the size and position of objects and more.

Generic Observer Pattern Implementations

Main page: Observer Pattern

GUI Functionality

Basic Controls

GUI Layers

GUI Layers are a way to separate out various related interface elements into their own autonomous groups. They may be thought of transparent "slices" or "sheets" onto which all GUI controls are placed. The layer system's biggest strength (and primary use) is the ability to turn on/off entire systems and groups of controls simultaneously, and control which interface elements may be present.

See also: GUI Layers

GUI Animation

GUIAnimations are a mechanism for modifying the appearance of a GUIcontrol over time. This could mean anything from playing actual frames of an animation (like a stick figure walking around), to causing other types of changes such as modifying the texture, position, or size of the GUIControl. Animations can be set to run immediately when the Control is first created, or they can be set to trigger upon certain events such as a mouse click.

See also: GUI Animations

Icon System

ID Spaces

Frequently it is useful for systems to be able to assign unique IDs to things. While the server can easily provide a unique ID using the CreateID() exteneral function the id it provides is within the world's ID space and generally looks something like 67894000023. Server assigned IDs are unique but will eventually climb towards 64-bit IDs.

Thus the HeroScript Version of ID Spaces was created to assign unique IDs on a per-system basis that start at the nice display/user friendly ID of 1.

See also: ID Spaces

Marshal Utilities

The marshalling utilities extends the serialization capabilities of HeroEngine to provide a more complete framework for use in the serializing objects. If you wish to transmit objects between client/server or server/server it is almost always better to use Replication.

Spec Oracles

The Spec System, a HeroEngine Required System, provides a flexible and robust framework for the definition of efficient game objects using a mixture of mutable and immutable data storage. The framework includes support for the automatic propagation of immutable data the client should know via a bandwidth optimized pathway.

See also: Spec System

States System - Area States

The states system is a generic system for the storage of stateful information with the potential to execute a list of actions when a transition to a new value occurs. The premiere example of this is the concept of "area states" which are used to keep track of information such as which door is open/closed.

Using the action lists, the state of the door can be communicated to players logging into the area so that their view of the "area" is the same as that of others in the area. The actions performed can be as simple as setting a field, to as complex as playing a series of FX's while transforming the position/rotation/scale of objects.

See also: States System


See also

Personal tools