Extending Instance Classes
In the HeroEngine servers, instances of game world assets are represented by GOM nodes. These nodes are created from definitions described by DOM classes. Adding new fields to GOM nodes is a two step process:
- First, new fields are added to the GOM node's corresponding DOM class.
- Second, the HeroEngine client C++ code is updated to understand the new fields. While the GOM node will now correctly load the fields, it does not persist them to disk.
This document presents HeroEngine's easily extensible field persistence solution. By utilizing HeroEngine's field persistence scheme, licensees can persist GOM field values without any server-side source code changes.
Instance DOM class and Ghost Class
- It must be created from a DOM class which is a kind of Instance.
- It must be created from a DOM class of Archetype INSTANCE.
- It must be created from a DOM class parented to a class of kind _SpecializedWritableInstanceProperties.
- All fields on the GOM node which are to be persisted, must belong to its parent _SpecializedWritableInstanceProperties derived DOM class.
The image to the left depicts a simple, Instance-derived DOM class hierarchy tree. Inheriting from Instance and SomeClassWritableInstanceProperties satisfies all of the requirements for a field persisting DOM class. All fields within SomeClassWritableInstanceProperties will automatically be persisted.
Using the Instance DOM class
Class Instance Archetype: INSTANCE Parent Class: _WritableInstanceProperties Package: Required
The Instance DOM class is of Archetype INSTANCE and provides a small set of persisted fields through its parent _WritableInstanceProperties class. Therefore, adding fields to _WritableInstanceProperties in effect gives all Instance derived classes the new fields. Nota Bene: Remember to place any fields added to _WritableInstanceProperties in the Game package to avoid Clean Engine update clobbers.
The Ghost Class associated with the INSTANCE archetype understands that Instance classes contain fields which are to be persisted. Furthermore, it understands that all of the persisted fields reside within the Instance class' _SpecializedWritableInstanceProperties derived parent. With this knowledge the Ghost Class is capable of automatically handling all field persistence.
DOM classes which are to persist fields must derive from the Instance DOM class.
Using the _SpecializedWritableInstanceProperties DOM class
Class _SpecializedWritableInstanceProperties Archetype: DATA Parent Class: Package: Required
The _SpecializedWritableInstanceProperties DOM class serves as a lookup point for the field persistence system. The fields within _SpecializedWritableInstanceProperties derived classes are understood to be persistant by the Ghost Class associated with the INSTANCE archetype. By setting the fields to +Reflect, the Ghost Class associated with the INSTANCE archetype will receive updates to the fields' values and correctly persist them.
DOM classes which are to persist fields specify which fields to persist by deriving from a base class which in turn derives from _SpecializedWritableInstanceProperties. The fields that are to be persisted are placed in the _SpecializedWritableInstanceProperties derived parent class.
Extending Clean Engine Instance Classes
Several of Clean Engine's DOM classes derive from the Instance DOM class. Each of these classes has a corresponding _SpecializedWritableInstanceProperties parent whose name follows the convention of _InstanceClassNameWritableInstanceProperties; where InstanceClassName is the name of the Instance derived class.
Additional persisted fields may be added to the Clean Engine classes by adding the fields to their corresponding _SpecializedWritableInstanceProperties derived parent classes. Nota Bene: Remember to place any fields added to Clean Engine, _SpecializedWritableInstanceProperties derived classes in the Game package to avoid Clean Engine update clobbers.