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 entity 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:

‘pcobject.mesh’ (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.

‘pcmove.linear’ (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.

‘pctools.inventory’
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:

‘pcobject.mesh’ (see section Mesh).
Again we need a mesh if we plan to use our hero in third-person mode.

‘pcmove.linear’ (see section Linear Movement).
Here we again use ‘pcmove.linear’. This time we use it also to
control actual movement of the hero.

‘pccamera.old’
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. Note that it is called 'old' because we're working on a
future new camera system.

‘pcmove.actor.standard’
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. Note that it is
called 'old' because we're working on a future new movement system.

‘pctools.inventory’
Possible a player can hold items so it is useful to have an inventory.

‘pcinput.standard’
To be able to react to user input (mouse, keyboard, ...) we use the
‘pcinput.standard’ property class. We also configure this property class
so that the right input is propagate to ‘pcmove.actor.standard’.

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 ‘pcinput.standard’ 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 ‘pcmove.actor.standard’ 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.