4.1 The Basics

In this section the basic concepts behind Crystal Entity Layer are explained. Crystal Entity Layer is a game layer that sits on top of Crystal Space and adds game specific notions.

Entities

The most important concept in nearly every game is an entity. An entity can be anything that has a meaning in the game. This includes objects a player can interact with (like keys, weapons, ...), non player characters (NPC), monsters, boxes that you can open and close, the player itself, the world, a part of the storyline the player needs to solve. And the list goes on. Basically everything that you consider a seperate entity when talking about your game will be an entity in Crystal Entity Layer.

Entities are not always visual entities. i.e. you can't always see an entity on screen. An entity can also be something that is not visual like a story element or some data you want to keep.

An entity is represented by the iCelEntity interface. An entity is created by an iCelPlLayer instance.

On its own an entity in Crystal Entity Layer is pretty useless. It is just an empty stub with a name. That's all. To make an enity useful two important concepts are introduced: property classes and a behaviour.

Property Classes

A property class is a piece of code (typically implemented in a plugin) that you can attach to some entity. By attaching the right property classes to an entity you define the characteristics of that entity. This notion can be explained best with a few examples. Let's say you want to define an entity for a box in a game. Here are the property classes you could use for that entity:

• `pcmesh' (see section Mesh). This property class gives entities a 3D representation (i.e. a mesh in Crystal Space terminology). It is only when an entity has this property class that you can see it in the 3D world. In this particular example this property class would be setup with a mesh that represents a box.
• `pclinearmovement' (see section Linear Movement). This property class is the general movement system in Crystal Entity Layer that does not use physics but only simple gravity and collision detection simulation. By attaching this property class this entity will correctly fall on the floor when it is released in the air.
• `pcinventory' By adding this property class the box will be able to contain other items (entities). It really acts like a box now. You can assign various attributes to the inventory so that you can set the maximum capacity this box can carry for example.

Here is another example of how you could setup your hero:

• `pcmesh' (see section Mesh). Again we need a mesh if we plan to use our hero in third-person mode.
• `pclinearmovement' (see section Linear Movement). Here we again use `pclinearmovement'. This time we use it also to control actual movement of the hero.
• `pcdefaultcamera' Our hero defines the camera. So everything the hero sees we see too. The default camera in Crystal Entity Layer also suports 3rd person view. It is actually a pretty powerful property class with lots of options on how you want the camera to follow the hero.
• `pcactormove' This class helps to combine the features of the three property classes above so that they work nicely together. It basically knows about player animations and how they relate to walking/running speed.
• `pcinventory' Possible a player can hold items so it is useful to have an inventory.
• `pccommandinput' To be able to react to user input (mouse, keyboard, ...) we use the `pccommandinput' property class. We also configure this property class so that the right input is propagate to `pcactormove'.

These are only two examples. There are a lot more possibilities. It is important to note that property classes are dynamic. You can add or remove property classes at runtime so that you can actually change the characteristics of an entity.

A property class is represented by the iCelPropertyClass interface. Property classes are created from property class factories.

Behaviour

The property classes define what an entity can do. The combination of property classes define the characteristics of that entity. The behaviour for an entity defines how the entity actually interacts in and with the game. It is where the game logic is defined. The entity system and property classes represent code that is written in Crystal Entity Layer itself but the behaviours represent code that you as a game creator need to write. There are currently three supported ways to write behaviours:

• Using `python': you can make python scripts that control the game logic.
• Using XML: Crystal Entity Layer has a scripting language based on XML that is specifically made to create behaviours.
• Using `c++' code: you can also code behaviours with regular `c++' code.

In the same game you can mix behaviours of different types and in the future more ways will be added.

Property classes send messages to the behaviour when something interesting happens. For example, when an entity has a `pccommandinput' property class then the behaviour will get messages every time a key is pressed. In reaction to those messages the behaviour can then call API calls in `pcactormove' to (for example) move the actor around.

A behaviour is represented by the iCelBehaviour interface. You can create behaviours from iCelBlLayer.

Physical Layer

The physical layer is the core of Crystal Entity Layer. It is responsible for the creation and management of entities and property classes. In addition to the physical layer plugin the plugins that contain the code for the property class factories are also considered part of the physical layer.

A physical layer is represented by the iCelPlLayer interface. You can get an instance of the physical layer from the object registry if you loaded the plugin at initialization time.

Behaviour Layer

The behaviour layer is a simple class which has only one responsability: the creation of behaviours. For XML and `python' there are already two predefined behaviour layers. If you want to use `c++' for the game logic then you must make your own behaviour layer.

The behaviour layer is represented by the iCelBlLayer interface.

This document was generated using texi2html 1.76.