Entity type definitions

User Defined Entity Header Files

The header files that the programmer writes to declare user defined entities in the editor have some restrictions. They must be C header files, with limitations on the structure definitions that are used for the editor entities. Macro expansion is not supported, and nested includes are not supported.

#pragma GE_Type("Player.bmp")
typedef struct tagPlayerStart {
#pragma GE_Published

Vec3d origin;

#pragma GE_Origin(origin)
} PlayerStart;

In the example above, the first pragma tells the editor that the following type is to be read as an entity definition. The name of the entity definition in the editor will be the final structure tag in the type definition, in this case 'PlayerStart'. The BMP string in the GE_Type pragma is used by the editor to read a bitmap to be used in the user interface of the editor for selection of the entity template. Entity bitmaps should be 32x32 pixels in size, 256-color Windows .BMP files.

The second pragma (GE_Published) tells the parser that fields below this point in the structure definition should be displayed in the editor's property editors. Another pragma (GE_Private) is used to make fields in the structure private from the editor. An example of this is shown below. The pragma GE_Origin is used to tell the editor which field in the type, if any, is supposed to represent the geometric position of the entity in the editor. This allows the programmer to specify which field of the structure is to be updated when the level designer selects an entity and moves it in the editor views.

The editor understands the following implicit types:

• int
• char *
• float
• geFloat
• geWorld_Model *
• GE_RGBA
• geVec3d
• geBoolean

Each of these types has a built in property editor in the editor. When the level designer double clicks on a field of type GE_RGBA, for example, the editor will raise a color picker dialog.

Structures can refer to each other by reference. You cannot have embedded structures in your structure definitions, except for the special cases of GE_RGBA and Vec3d. Forward references of structures are allowed. For example, here are the type definitions that would allow you to build a linked list:

#pragma GE_Type("PathPt.bmp")
typedef struct tagPathPoint PathPoint;
#pragma GE_Type("PathPt.bmp")
typedef struct tagPathPoint {
#pragma GE_Published

geVec3d origin;
PathPoint * Next;

#pragma GE_Origin(origin)

} PathPoint;

Here, the editor has to deal with a field in the entity which is not of an implicit or built in type. The Next field is a pointer to a PathPoint structure. The editor will display the field name Next in its property editors, and when the designer edits this field, the editor will bring up a list of existing entities in the world which are of the type PathPoint. The designer may select only from this list to assign a value to the field. This ensures strong typing in the data structures that the editor builds for the programmer.

#pragma GE_Type("monster.bmp")
typedef struct Monster { 
#pragma GE_Published

geVec3d origin;
int HitPoints;
geFloat Speed;
GE_RGBA Color;

#pragma GE_Origin(origin)
#pragma GE_DefaultValue(HitPoints, "100")
#pragma GE_DefaultValue(Speed, "2.0f")
#pragma GE_DefaultValue(Color, "255 0 255")
} Monster;

The above is an example of the GE_DefaultValue pragma. This pragma allows the editor to assign default values to fields in the entities. Default values may not be assigned to fields that are pointers to user types. They may be defined only for fields of implicit or built in type.

Documentation fields

#pragma GE_Type("monster.bmp")
typedef struct Monster { 
#pragma GE_Published

geVec3d origin;
int HitPoints;
geFloat Speed;
GE_RGBA Color;

#pragma GE_Origin(origin)
#pragma GE_DefaultValue(HitPoints, "100")
#pragma GE_DefaultValue(Speed, "2.0f")
#pragma GE_DefaultValue(Color, "255 0 255")
#pragma GE_Documentation(HitPoints, “Monster’s starting hit points”)
} Monster;

This is an example of the GE_Documentation pragma. This pragma instructs the editor to display the specified string in a hint box if you hover the mouse over the field in the Entities Editor dialog box.

#pragma GE_Type("door.bmp")
typedef struct Door {
#pragma GE_Published

geVec3d origin;
geWorld_Model * DoorGeometry;

#pragma GE_Private

int IsOpening;

#pragma GE_Origin(origin)
} Door;

Above is an example of the GE_Private pragma. The fields marked as GE_Published will be editable in the editor. The fields marked as GE_Private will not be displayed in the editor's entity property editor.

When the editor writes the entities out to the level, it stores the type definitions as well.

The engine parsees the type definitions, and streams in the entities. The engine allocates space for each entity’s data structure at level load time. The published fields, for which the editor had data, will be filled in with whatever the designer placed in the level.

Fields that are pointers to other structures will be properly initialized to point to those structures. This is possible because each entity is named by the editor, and the engine performs load time binding on those names to fill in the structure fields. The private fields are all initialized to zero by the engine at load time. The programmer can then access the data structures directly without having to perform any load time binding of the structures.