Required
|
The Distribution Package system classifies different elements, to explain the differences between the Required HeroEngine systems, and a licensee's game.
Specific elements covered include:
- Events that are handled by scripts. This page includes a sample execution path
- DOM definitions and related ID spaces
- Configuration values
- System nodes and root nodes
- The HeroEngine publishing tool
Distribution packages
Every definition type in the DOM, including scripts, is assigned to one of the Distribution Packages. This trait specifies how it is handled in various situations, such as updates.
The HeroEngine developers use CLI commands or the DOM Editor to assign the distribution package of the definitions included in HeroEngine. The CLI reference page documents the commands used to change the distribution package of definitions. It is important to note that each script and DOM definition in HeroEngine is assigned to one and only one Distribution Package. These are:
- Required
- The set of definitions and scripts tagged as Required are those that are needed for the base HeroEngine to function. These are maintained by HeroEngine, and represent the fundamental building blocks on which a specific game is constructed using the toolset. (To extend the Required HeroEngine scripts for a specific game implementation, see Adapting Clean Engine.)
- Optional
- Optional DOM components are stand-alone scripts and definitions that are not required for the base HeroEngine to function.
- Game
- The default distribution package of a definition, and the one that should be used by implementors of a game, is
Game. The other distribution packages are used by the HeroEngine development team, and are not intended to be used by a licensee.
- OptionalGame
- The OptionalGame scripts and definitions are the bare bones scripts that provide a gamelike functionality to HeroEngine, before the game developer has created Game-specific scripts. These components connect pieces of the base HeroEngine together to allow the game client to have at least minimal function in the game world. They are provided to the licensee as part of Clean Engine, but are up to the licensee as to whether they're going to be kept as-is, or later modified. An example of an OptionalGame system is the basic character selection system which is provided with Clean Engine.
The only definitions which should ever be modified by a licensee, are those in the Game package. Note: Licensees must never modify anything that is not in the Game package. Doing so would make it difficult or impossible to accept/apply any future updates of HeroEngine.
System Nodes define the Script Event Handler
- Main page: System Nodes
HeroEngine supports instantiation of prototypes as non-persistent nodes to support an object-oriented pattern of event handling.
The most important part of this feature with respect to customizing HeroEngine for a Game is that the Prototype being used to generate the System Node can be modified by glomming a Game-specific class. The initial clean HeroEngine distribution will have the OptionalGame scripts already glommed on to the various prototypes used as System Nodes. The Game implementor is then free to unglom the OptionalGame classes from the prototypes, and glom their own Game-specific class onto the prototype so that HeroEngine will call their Game-specific event handler methods instead of the OptionalGame event handler methods.
Execution Path
- An event is triggered by a user
- HeroEngine does its initial processing of the event, and checks to see if any Game-specific overrides are required
- If there is a Game-specific override, HeroEngine passes processing to the methods in the game script
- If there is not a Game-specific override, HeroEngine completes the processing of the event
The way that HeroEngine checks to see whether or not there is a Game-specific override, is by examining the appropriate System Node to see if there are any methods which need to be called.
See also
HeroEngine Publish
In the four different packages involved with HeroEngine, the licensee is allowed to change any element of the "Game" package, but should not modify any of the non-game elements, as this may be overwritten during a publish.
HeroEngine Publish Packages are used to create and update HeroEngine. These packages, which may be distributed via Download, Perforce access or a DVD, may contain new versions of server and client executables, DOM components, and repository files.
- A "Creation" HeroEngine Publish Package contains all of the elements required to set up a new HeroEngine install, and then create a new game world.
- An "Update" HeroEngine Publish Package contains the required components to upgrade the version of HeroEngine which is being run by a world. If an update does not apply properly, it will leave the game world in the state it was before the update began. A successful update will overwrite any changes made to the non-Game-specific definitions (including those in the OptionalGame distribution package) with the latest version of those definitions. If there are Game-specific definitions already in place that conflict with the publish package, the package application will fail. To resolve this problem, remove or rename the conflicting Game-specific definitions and reapply the package.
- HeroEngine Publish, a step by step tutorial, provides a guide to creating a HeroEngine Publish Package with HEPublish and HEPublishApply.
ID space distribution
Every definition in the DOM has a unique identifier. Also, every node created in the GOM has a unique number as well. These numbers are used instead of the name, since the name of definitions can be changed; only the ID serves as the true unique identifier.
Because new definitions can be added during a HeroEngine Publish, it is important to separate the ID space of HeroEngine and any given specific Game. To facilitate this, the distributed HeroEngine initial setups will start their ID space at a number that the HeroEngine ID space will not overlap. All internal data objects (scripts, DOM definitions, even assets) that are required by the core HeroEngine implementation will be in an ID space that does not overlap with the ID space of licensees. This reserved ID space is used by HeroEngine when maintaining, updating and expanding the core HeroEngine platform.
Substituting Game-specific Code
Licensees are not allowed to modify the non-Game-specific definitions, but they need to be able to call Game-specific code from HeroEngine events. To allow this, there are exceptions to the definition modification rule.
The addition of a Game-specific class to a prototype by glomming is allowed. This is used primarily with System Nodes to introduce classes which implement event-handling methods.
Also, Game-specific classes can inherit from non-Game-specific classes. This allows the game implementor to create nodes with new behavior that will still work with the non-Game-specific script functions. The new behavior is introduced by overriding methods in the Game-specific class method script.
Using World Configuration Values
The HeroEngine processes are configured through Master Control. Various named configuration options may be given different values. A subset of the configurations are accessible to script through external functions. By changing the value of these configurations, the operation of HeroEngine can be changed in certain pre-defined ways. All of these script accessible configuration values will be documented and the Game developer will be able to choose a configuration value that suits his needs.
The HeroEngine client also has script-accessible configuration values. These are delivered to the client when it connects to the Service Directory. The specific values are also documented.
See also: Script Config Values.
New versions
If you need to download new versions of any HeroEngine applications, check the Download page.
