This preliminary document is the first try at the game design
document for Dreams Eternal. It is unfinished at the moment
but it is a first draft so that it can be examined.
History:
- 20-Nov-2000: Added the 'Activated' event.
- 13-Nov-2000: Added the 'input' property class.
- 10-Nov-2000: Added the notion of the 'pathFinder', 'locator',
and 'timer' property classes. Also added several events that will
be generated by those new property classes. Note that these property
classes are not implemented yet.
- 9-Nov-2000: Added 'Action' and 'Activate' events for
BasicEntity.
- 7-Nov-2000: Added the 'identity' property class and added
more information about the 'inventory' property class.
- 6-Nov-2000: Inventory property class is now implemented. Added
this information to the entity system description. Also extended the
notion of events that are attached to property classes.
Added the 'teleportation' dream power.
- 30-Oct-2000: Big update of the entity/scripting section.
- 19-Oct-2000: Several modifications from the discussion on the
mailing list. Added a list of possible illusions. Added notion of
illusion selector, shape selector, and dream selector for the user
interface. Added notion of actions and binding keys to action. Redefined
movement and keys for 1st and 3rd person view. Several other changes
to user interface specification. Modified the skeleton plain dream
a little.
- 17-Oct-2000: Modifications to User Interface Specs.
- 16-Oct-2000: Addition of User Interface Specs. Addition of
contents for creature section. Addition of Table of Contents.
Addition of Scripting Specification. Addition of skeleton plain dream.
Addition of cutscenes section.
- 21-Sep-2000: Creation
The players dream is basicly the main entrance point for our player.
It is also the point he will often come back too in order to continue with
the rest of the game. Since this dreams comes from the subconscious of
the player himself so it can possibly contain many things that are
comforting for the player (personal items or people that
he knows).
The level should not be too nightmare like. Basicly the feeling of
this level will be a bit surrealistic with very symbolic and strange
things.
Areas
- Players house:
The players house is a surrealistic version of
his real house. The rooms are the same but all objects float around at
random places. The television (which connects to the journalist dream)
is one of those objects but it is slightly hard to find. If the players
goes outside one of the windows of his house he will not arrive at the
scenes he sees through the window (the garden of his house) but instead
he'll arrive at the top of the tower with the nine pools (see below).
- The Nine Pools:
You are on top of a tower. All around you you
see sky and clouds. There is no ground to be seen. On the top of the tower
there are nine rectangular pools. Some pools have dirty black water,
others are empty. Some contain unknown objects or mental items. Sometimes
the water moves in some of the pools. This area is some symbolic
representation of the player's unconsciousness. Each pool represents
a crucial memento in his live. In the bottom of each pool there are objects
or mental items taken from this memento. The player can (try) to bring them
to the surface. Sometimes they are useful items, sometimes they are not.
The items are persistant (i.e. can occur in other dreams too) because they
represents part of the players subconscious. We need a puzzle here to
be able to get out the objects. Note that there may be creepy creatures
in some of the pools. We still have to find a way back from the tower to
the house. One way would be jumping of the tower but there has to be a
clue somewhere that this is the way to do it.
Goals
- Central Point:
The main goal of this level is to introduce the game itself and be
the central point of the entire game play (at least in the beginning
of the game).
Inside Connections
- Players House to Nine Pools:
By going through a window in the house.
- Nine Pools to Players House:
To be discussed. One option is to jump off the tower.
Outside Connections
- To Journalist Dream:
The connection to this dream is through
the television set in the players house. To activate it the player
simply has to go very near the television (i.e. touch it).
- To Skeleton Plains:
One of the nine pools could contain a skeleton. Jumping in that pool
could be the way to enter this dream.
Items
- Photograph of beloved:
This item could be available in one
of the nine pools (as a memento) or else it could be one of the
floating items in the players house. Making it available in one
of the nine pools might be better as this is a powerful item.
- Candle:
A candle can be found in the house.
The journalist dream represents the dream of the journalist that made the news item
that the player saw in the first cutscene. This dream is a nightmare based on
a photography theme.
You start in a very dark room with only a small button visible. This is a light-switch.
When you turn on the light the rooms is lit red (it is a photographic dark room). There is a
lot of rubbish in the room but nothing of that matters much. You can go outside to the
rest of the flat of the journalist. The journalist is there in his nightmare. He is
blind and running around wildly. When you come too close he will scratch and
attack you. So be careful! You have to engage him in some conversation so that
he quiets down and talks to you. He says: 'If only I 'm no more blind! I will
show you, I will!' So you have to find his eyes. In the kitchen there is a
fridge. If you open the fridge there is a staircase down into a strange labyrinth
full of items related to photography (but larger). Some examples: a giant diaphragm
as a door, pools full of chemical liquids, flash lights, photos, a giant lens,
mirrors, ... The journalists eyes are on a horror like robot. You have to try
to catch the robot to get the eyes. After getting the eyes you give them to
the journalist. He will then show you some pictures of the building. This is
the first Mental Item in order to solve the rest of the game.
Areas
- Journalist appartment:
This contains the dark room and the journalist. There is also
the television to return to the players dream.
- The Photographic Maze:
A maze full of photographic items but distorted.
Goals
- Journalist Eyes:
The main goal of this level is to find the journalist eyes and give
them to the journalist. Then he will show you a photograph of the
scientist building (mental item).
- SCENARIO Drugged 1: The Drugged Scientist:
A side goal of this level is to find the dream pocket to the
dream of the drugged scientist. We have yet to find out how
this pocket is hidden.
Inside Connections
- From Appartment to Maze:
Through the staircase in the fridge.
- From Maze to Appartment:
Back to the fridge.
Outside Connections
- The Players Dream:
Through the television set in the living room of the journalist.
- SCENARIO Drugged 1: The Drugged Scientist Dream:
To be discussed. Option is a photograph of the drugged scientist.
Items
- Journalist Eyes:
The eyes of the journalist. This item is local to this dream and
only serves to solve this level.
- Building Image (Mental Item):
This mental item gives the player the notion of the existance
of the scientist buildings. This will be important later.
A kingdom. Not the bright cheery kind, but one composed
of twisted structures, statues of demonic faces and creatures,
paintings reflecting a man being dragged down into a hole by
something or evil consuming that same man. The residents roaming
around (possibly people in the patient's life) appear as they do
in the real world at first, but when they notice an intruision
(you), they morph into how the patient viewed them in the real
world.. a stuck-up rich and pretty girl becomes hugely deformed,
and ugley.
As you go deeper into the madness, more clues are revealed what
exactly happened here. To solve the major puzzle, you must find
the scientist, wake him and free him from his cage (surrounding his
imprisonment are the demons, which will later be revealed to be
the scientists who brought him to this madness. Before that,
you'll find several versions(clones) of himself, the kings of
this place, who you might have to stop. There will be puzzle-like
ways to kill each of them, and doing so will probably unlock the
place where you can find the patient.
Once you finally free him, and get him to realize he's still in
a dream, the world changes and becomes bright and cheery, the
people roaming the hallways are locked away or something. There's
still a certain eeriness due to the scientist, but overall calmer.
The scientist then reveals that he was the first, one of those the
scientists experimented on to create their machine. When he
threatened to expose them, they drugged him, which caused his
dreamworld to warp into what you found it as, trapping him deep
inside..
Areas
- Kingdom:
Like described above: a twisted castle with a village around
it would be a good possibility here.
Goals
- Find Mental Item for Machine:
The main goal of this level is to find the mental item representing
the knowledge of the existance of the machine that controls the
dream world.
Inside Connections
Outside Connections
- SCENARIO Drugged 1: The Journalist Dream:
Back to the dream of the journalist. To be discussed.
- SCENARIO Drugged 2: The Skeleton Plain:
Back to the dream of the skeleton plain. To be discussed.
Items
- Machine Knowledge (Mental Item):
This mental item gives the player the notion of the existance
of the machine to control the dreams.
A big infinite plain with towers here and there. To every tower there is
a skeleton attached. See the concept art on the Dreams Eternal page.
In this dream the person who is dreaming this is unknown (and not important
to the game). This dream has two purposes depending on the scenario.
The towers are arranged in a regular fashion. However there are two towers
that stands out in some way. The first tower is the one you start in. This
tower contains the portal back to the players dream. To distinguish
this tower there is a light (with a halo) above this tower.
The other tower contains the item and is different because there is a creature
guarding it.
When you enter this dream you are inside one of the towers. There is an open
doorway to the plain.
Areas
- Large Plain:
Like described above: an infinite plain with towers and skeletons.
Goals
- Lantern:
The main goal of this level is to find a lantern. The lantern can
be found on the guarded tower.
- SCENARIO Drugged 2: The Drugged Scientist:
A side goal of this level is to find the dream pocket to the
dream of the drugged scientist. To enter this dream there
will be a ghost (of the scientist) flying between the towers.
The ghost seems to be in agony. Touching the ghost will open
the portal to the dream of the Drugged Scientist. This ghost will
not be present in Scenario Drugged 1.
Inside Connections
Outside Connections
- The Players Dream:
Inside the tower you started in there is the portal back to the
players dream.
- SCENARIO Drugged 2: The Drugged Scientist:
Through a portal opened by touching the floating ghost.
Items
- Lantern:
This item is a source of light.
To make the game richer there will be several alternative paths. Every alternative
path is called a scenario. A scenario has a name and a number. The name indicates
a scenario setting while the number indicates which of the scenario options is
chosen:
- SCENARIO Drugged:
The dream of the drugged scientist is available through two paths. The
first path (option 1) is through the dream of the journalist. The second
path (option 2) is through the skeleton plain dream (by touching the
floating ghost).
Cutscenes will be made by using the Crystal Space engine itself. So in many
cases we'll be able to reuse the levels from the dreams for them. Here
is a list of all the cutscenes that we have:
- Cutscene 1: Watching Television
It is dark outside and raining (thunderstorm?). The camera starts
in the garden and slowly moves towards one of the windows of the
house. In the house you see the light burning and the hero watching
television. First the camera moves around the hero while he is
busy watching television and drinking something. Then the camera
hovers over the television for a while showing some the important
news item about the experiment.
Then the hero stands up, turns out the television and moves upstairs
to bed. The camera follows him. He enters his bed and turns off the
lights. The camera zooms to the window. You see lightning and the
flash resulting from that ends this cutscene. The game starts...
In this section we summarize all the possible items to be found
in the game and their effect:
- Photograph of beloved:
The effect of this item when applied would be to decrease the
mental stress. This item has limited use as it is very
powerful (there are going to be similar but less powerful items
that are easier/more frequent to use). Everytime you use this item
the photograph will fade slightly. If it is totally blank you cannot
use it anymore. There is no way to recharge it and there is only
one photograph in the game.
- Candle:
A candle gives light. It is as easy as that :-) Candles are
relatively easy to find but they have a limited lifetime (i.e.
they burn out) and when burned out they disappear. A candle
is affected by a draft and can go out then. You need some
fire to be able to activate a candle.
- Lantern:
This item is also a source of light. The difference with the candle
is mainly that it is more resistant to drafts. It will still go out
if in contact with water though.
- Journalist Eyes:
The eyes of the journalist. This item is local to the journalist dream and
only serves to solve this level.
- Building Image (Mental Item):
This mental item gives the player the notion of the existance
of the scientist buildings. This item is persistant and is part
of the core game clues.
- Machine Knowledge (Mental Item):
This mental item gives the player the notion of the existance
of the machine to control the dreams. This item is persistant and
is part of the core game clues.
Here is a summary of all creatures and characters in the game and what
they can do:
- Our hero (Friendly):
Well, this is you :-)
- Creepy Pool Creatures (Unfriendly):
For the players dream we need creatures that live in the pools.
Some slimy ugly creature seems good here :-)
- Creepy Creatures in general (Unfriendly):
We're going to need those for other nightmares too.
- Journalist (Neutral):
The journalist from the Journalist Dream.
- Horrific Robot (Unfriendly):
The robot with the eyes from the Journalist Dream.
- People/Malformed (Neutral):
Residents in the Drugged Scientist Dream. They look normal
at first but when you come close they morph into something
very ugly (but still resembling a person).
- Drugged Scientist (Friendly):
The drugged scientist.
- Scientist Ghost (Neutral):
The ghost representation of the drugged scientist.
- Tower Guard (Unfriendly):
Some nasty creature guarding the tower in the skeleton
plains dream.
- Demons (Unfriendly):
Manifestations of the scientists that drugged the Drugged
Scientist.
Here we describe various environmental effects that can occur in
the game. Environmental effects can be local to some area (like
water or draft) or occur depending on some event (a fireball for
example):
- Draft or Wind:
The effect of a draft may be to blow out a candle. The effect
of a strong wind may be that you are not able to move as
quickly in the opposite direction that the wind is blowing.
- Fire:
Useful to turn on a candle or burn something.
- Water:
Also has the effect of countering fire.
Every dreamer (the player and cooperative/non cooperative other AI based
dreamers) have the capability to perform certain powers. Here is a list
of all the powers in the game. The use of any of these powers decreases the mental
strength of the dreamer. The ability to use one of these powers is also
dependent on the mental agility of the dreamer. Every power will have an associated
mental agility that is needed to be able to perform that power.
- Flying:
The ability to fly for a short distance.
- Concentration:
Some items or other objects need to be activated by concentrating
on them. This also adds an additional cost to using that item.
- Dream Warping:
This is the ability to go to another dream at will by opening
a dream pocket. It is only possible to visit dreams that you
already visited before.
- Teleportation:
This ability is similar to dream warping but teleportation only
allows you to move between locations in one dream. The destination
of teleportation cannot be controlled but is selected from a fixed
set of locations in the level (to prevent teleporting in locations
you cannot get out or which would spoil puzzles).
- Shape Shifting:
The ability to change into another shape can be useful to be able
to go piecefully between similarly shaped monsters or it can
be useful to make yourselves smaller in order to go through some
small hole. Changing into a random shape is cheaper then changing
into some specific shape. You can only change shape to shapes you
have 'touched'... This makes it hard to change shape to creatures
that are very powerful as you need to be able to touch them.
- Creating Illusions:
The ability to create illusions can be useful in order to trick
other monsters or dreamers. Shape shifting is similar to illusions but
there is a difference. With shape shifting you can morph shape into
some creature you touched before. With illusions you can do other things.
Here is a list of possible illusions you can create:
- Invisibility: create the illusion that you're invisible.
- Inanimate object: create the illusion that you're some
object that isn't alive. When you invoke this illusion you cannot
move. Otherwise you will break the illusion.
- Creature: a random other creature will appear in the same
room that you are in. The real monster might get confused by
that. This creature will disappear after some time.
- Strength: this illusion will make you appear stronger
than you really are. A creature might be frightened by this.
- Wall: you can create an illusionary wall in front of you.
A monster might be trapped into thinking it is a real wall and
so not be able to see you. Walking through the wall can break
the illusion though.
- Walking Through Solids:
This ability is only possible through certain kinds of solids (needs
to be marked in the object attributes of level entities).
- Clear Vision:
Invoking this power will enable the dreamer to see through an illusion.
- Telekinesis:
This is the ability to move objects by sheer mind power.
Every dreamer has a number of characteristics. Some are dynamic. Some
are more static. Items can influence these statistics temporarily or
permanently:
- Mental Strengh:
This indicates the ability of the player to perform certain powers. Every
power has a cost associated with it. There is a maximum mental strength
value for every dreamer which increases gradually as the player gets
more experience. The current mental strength value can never exceed the maximum.
The mental strength itself regenerates slowly until it reaches maximum.
- Maximum Mental Strength:
The maximum mental strength a dreamer currently has.
- Mental Agility:
Together with mental strength, mental agility indicates your ability
to perform certain powers. You start with agility 0 which means that you
cannot perform any power at all. When your experience rises you get
access to more powers. Every power has a mental agility level associated
with it. If mental agility is greater than the powers required agility
then it will always work. If mental agility is less than the required
agility it will never work. If mental agility is equal then it will
always work but not always with the full effect.
- Mental Stress:
Mental stress indicates how strong the dreamer is in his mind. If he is
attacked by some creature or suffers another traumatic event in one of
the dreams his mental stress will increase. If mental stress reaches
the current maximum mental stress the dreamer will die.
- Maximum Mental Stress:
The maximum mental stress that a dreamer can withstand.
- Mental Stress Resistance:
How resistant a dreamer is to attacks increasing mental stress. If
a dreamer is 100% resistant his mental stress will not be affected
by any attack. If a dreamer is 0% resistant then he will receive
the full blow of the attack.
- Experience:
Every monster you defeated or every puzzle you solved gives experience
points. Your maximum mental stress, maximum mental strength, and
mental agility will rise with your experience.
- Eyes:
You either have or don't have your eyes. Certain monsters, dreams,
or otherwise can remove your eyes so that you become blind. Blind
doesn't mean that the player (i.e. the person sitting behind the
screen) cannot see anymore. But it means that the dreamer becomes
more difficult to control. He will stumble all the time and move
uncontrollably.
In general the game should be as immersive as possible. This means that
status bars, inventory slots, menu selections, ... should be either very
small and non-obstrusive or else optional.
We will avoid right mouse click so that we can run on Macintosh too.
But right click can be defined to some action by the player if he/she
wants it. The default binding for Right click on systems that support it
will be the same action as Double click.
It will be possible to bind keys to actions. That's why there are no
specific keys mentioned in the text below. In general we have the following
keys and their default binding:
- Action(arg): default left mouse button
- Activate(arg): default double click and right mouse button
- Pickup: default ','
- Attack: default space
- Movement: arrow keys
- Mouselook: default backslash
In addition it will be possible to assign hotkeys to invoking dream powers,
items in the inventory, ...
In general we have the following user interface elements:
- Play Area:
The play area is where the game occurs. It is a 3D view of the world
centered around the player. The play area can be in 3rd perspective
or in first person view.
Both for 1st person and 3rd person view there are the following
actions and what they do:
- Action(item) will pick it up.
- Action(creature/unfriendly) will attack it.
- Action(creature/friendly) will enter chat mode.
- Action(portal) will enter that portal.
- Activate(item) will activate it (i.e. light a candle).
- Pickup will either pick up the item you are standing
above (i.e. not visible) or else show a popup of items that
are below your feet so that the player can choose.
- Attack will attack the monster in front of you.
- Movement through portal will enter that portal.
- Movement will move around.
- Mouselook + Mouse movement will control the where
the camera looks (i.e. let you look around).
- Mouse movement over an item will pop up a small info note
in some corner of the screen.
- Info Note:
This is a very small object containing some information about the
item that is currently being targetted by the mouse. It contains
things like friendly/unfriendly status (if a creature) and a short
description of the object.
- Large Status Bar and Inventory:
The status bar shows all player statistics and the inventory.
This includes mental strenght, mental stress, experience, ...
This status bar is in general not open but can optionally be opened
for examination. Opening this screen will NOT pause the game!
The status bar/inventory is centered around the play area. The play area
is still visible in the center. This allows you to drag objects between
the inventory and objects in the world and back.
The following items/information is shown on this screen:
- Inventory slots: several slots (10 to 30?) holding items
you collected.
- Dream powers: all dream powers that you are capable
of performing.
- Statistics: mental stress, mental strength, experience, ...
The following actions are possible:
- Dragging is the main way to get objects from the world to
the inventory. You can also drag to get an object from the inventory
into the world or an object in the world (like a chest).
- Activate(item) will activate it (i.e. light a candle).
- Action(item) will select it. There are a few buttons that
you can use then:
- Use: Same as double-click.
- Drop: Drop the item at your current spot.
- Info: Show info about the object.
- Activate(power) will invoke that power. Invoking some
powers will cause an additional screen to pop up (i.e. invoking
the 'dream warp' power will open a screen with all dreams you
can visit.
- Dream Selector:
When the 'dream warp' power is activated a dream selector window
will open on which all previously visisted dreams are shown.
Action(dream) will enter that dream.
- Shape Selector:
When the 'shape shift' power is activated a shape selector window
will open on which all known shapes are shown. A shape will only
appear there when the shape has been 'touched'.
- Illusion Selector:
When the 'illusion' power is activated an illusion selector window
will open from which the illusion is shown.
- Small Status Bar:
The small status bar shows only the important mental strength
and mental stress features. This status bar can be overlayed on top
of the play area and it should be as non-obstrusive as possible.
Optionally even this status bar can be toggled on/off with a single
key stroke. On critical events (i.e. dangerously high mental
stress) it could open automatically.
- Game Control Menus:
These menus are for controlling the game itself. i.e. Loading/Saving
a game and starting a new one. When this menu is active the game
is also paused (or hasn't even started yet).
This is a very technical section that explains how the Dreams Eternal
entity system works on both the Python and C++ side and how both sides
interact with each other.
Every object in the game is represented by an entity. The entity
system allows the Dreams Eternal game programmer to speak to game objects
in a consistant manner. Examples of entities are: the player, the world
itself, creatures, a candle, objects in general, mental items, ...
Every entity has a C++ representation and a Python representation. The
C++ representation controls the general characteristics and attributes
of every entity while the Python representation controls the behaviour.
Attached to every entity we have a list of property classes. A property
class describes a specific kind of behaviour or attribute set for an entity.
All the property classes together define what the entity really is.
This will become clearer if we give a list of all current property classes:
- physical: The physical property class describes the physical
attributes of an entity. It contains the size and mass and also
contains information relevant for doing collision detection with
the entity.
- visual: The visual property class contains visual information
for the entity. For example there is now a visual property class
which controls a 3D sprite (Crystal Space concept). Entities should
have a visual attached if they want to be visible.
- movable: If an entity has a movable property class attached
to it then it will be moved by the game system through semi-realistic
physics (gravity...). The movable property class requires the
presence of a physical property class and it will also optionally
control the position of the attached visual property class if present.
- camera: If the object must be followed by a camera then
it will need this property class. The player is usually the only
entity which has a camera property class attached but the system
is general enough to allow other cameras.
- input: If an entity is interested in keyboard and mouse events
then it can add this property class. In addition this property class
can be configured to work together with a 'movable'. In that case it
will automatically call
ApplyForce
on the 'movable'
correctly depending on the keys that are pressed. The player is usually
the only entity that has an 'input' property class attached to its
'movable'.
- mind: An entity which has this property class has a mind.
This means that it will have attributes like mental strength and
mental stress and it will also be able to invoke dream powers and do
other mental things.
- inventory: The inventory property
class contains a set of other entities. An entity which has this
property class is capable of containing other entities. This property
class has attributes like the maximum number of objects it can contain,
the maximum size, maximum weight, ... The system is hierarchical.
For example, a box entity can have an inventory so that you can
put objects in that box. If the player picks up the box then the
box including the contents will be in the player inventory.
All objects in the world (except for the world itself) belong to
some inventory. This is to avoid dangling references. The inventory
system goes to great lengths to insure that the maximum capacity
of entities inside is not exceeded. This even works for nested
inventories. i.e. if the player holds a box and the weight of the
box plus contents is near the limit of what the player can hold then
you will not be able to add another item to the box.
- identity: The identity property describes the identity of
an entity. Things like the class of object (item, mentalItem, player,
creature, ...), a description, and a unique id.
- pathFinder: (Not implemented yet) The pathFinder
can be used by creatures that are interested in finding out how to
move to some location through the level. The details of how the
pathFinder will be implemented are not clear yet but a handmade
network of nodes through the level is one possibility. In general
the entity should not concern itself about how the path is found.
This property class works together with 'movable' in order to
actually move the entity around until it reaches the correct
destination. This property class also generates events when the
destination is reached or the destination cannot be reached
for some reason.
- locator: (Not implemented yet)( The locator is used
to keep track of the position of another entity. There can be multiple
instances of locator attached to one entity if that entity is interested
in more than one entity. When a locator is attached to an entity
the entity will receive events when the other entity moves, becomes
visible, becomes invisible, or is destroyed. Only the last event
is immediate. The others are only calculated every second (default:
this is configurable for any locator). The locator is very useful
in combination with the pathFinder above.
- timer: (Not implemented yet) The timer is a general
purpose property class that fires an event when a specific number
of miliseconds has elapsed. An entity can have multiple timers.
When a timer fires it needs to be reactivated manually so that it
will fire again after the same amount of time.
This is only the beginning. More property classes will follow as the game
system is further refined. The property class system is a very dynamic
and flexible system which allows us to dynamically change properties
of entities on the fly. It is possible to add/remove any of the above
property classes at any time. This is something that is very hard
to do if we were to use the traditional inheritance based entity system.
On the C++ side we basicly have two kinds of classes. Classes beginning
with the 'de' prefix are classes that are only accessed from
within C++ itself and not (directly) usable from within Python. Classes
(or rather interfaces) that start with the 'i' prefix
are meant for communication between Python and C++. In src/python/dreams.i
the relation between those interfaces and Python is defined. The SWIG
program reads that file and generates corresponding wrappers from that.
Note that most 'de' classes also implement the corresponding
'i' interface.
In the C++ entity system the base class for all entities is deEntity
(src/entity/eentity.h
). There is only one subclass which is
deWorld
. The reason for this is that there is special code
attached to deWorld for controlling and loading the world. Aside from the
world itself all other entities are just instances of deEntity
.
iEntity
is the interface for Python.
As explained above the behaviour and appearance of every entity is controlled
by the list of associated property classes. Every entity has an instance
of the class dePropertyClassList
(and associated interface
iPropertyClassList
) which controls this list of entities.
This list contains property classes.
iPropertyClass
is the basic interface for a property class.
In addition there are also interfaces describing the specific property
classes:
- physical: dePhysicalPClass and iPhysicalPClass
- visual: deVisualPClass and iVisualPClass
- movable: deMovablePClass and iMovablePClass
- camera: deCameraPClass and iCameraPClass
- input: deInputPClass and iInputPClass
- mind: deMindPClass and iMindPClass
- inventory: deInventoryPClass and iInventoryPClass
- identity: deIdentityPClass and iIdentityPClass
- pathFinder: dePathFinderPClass and iPathFinderPClass
- locator: deLocatorPClass and iLocatorPClass
- timer: deTimerPClass and iTimerPClass
For example dePhysicalPClass
is the implementation of the
physical property class. dePhysicalPClass
implements both
iPropertyClass
(because it is a property class) and
iPhysicalPClass
(because it is a physical property class).
On the python side the situation is different. For every entity there is
both a C++ instance of deEntity
and a Python instance
of BasicEntity
(BasicEntity
inherits from
the Python version of iEntity
).
As explained above the C++ side of every entity is responsible for
controlling the attributes (through the property classes) of every entity.
Property classes also define some basic behaviour. An example of this
is the 'movable' property class. An object with this property class will
automatically (by the game system in C++) be moved according to semi-realistic
physics rules.
The Python side of every entity controls the rest. Every entity is
created blank on the C++ side. It is the responsibility of the associated
Python script to attach the needed property class instances and initialize
them to the required settings.
On the Python side every entity will inherit from BasicEntity
.
BasicEntity
controls default behaviour for all the possible
events that can occur from within the game system (more on events later).
An important fact here is that while we don't use inheritance on the C++
entity system but instead describe entities using property classes this
is not the case for the Python entity system. Python entities inherit
from super classes that control more general behaviour. For example
we could make a ContainerEntity
which subclasses
BasicEntity
and is responsible for all containers in the game
(i.e. boxes, sacks, belts, ...). Every specific container can then again
subclass from ContainerEntity
.
Events are used to communicate from C++ to Python. Every event
corresponds to a Python method in the corresponding script. Most events
are actually generated by attached property classes. If you don't attach
a property class generating some event then that event cannot occur.
The following table lists all current events grouped by the property class
by which they are generated:
- Init (global): The entity is initialized. This method should attach
all required property classes and initialize them to the correct
values.
- Action (global): This is called whenever the entity is clicked.
The appropriate action depends on the entity but the default action
as implemented in
BasicEntity
is to try to pick up the
entity and put it in the inventory of the entity that initiated this
event. This all depends on wether or not that entity actually has
an inventory that can hold the entity upon which Action is called.
- Activate (global): This is called whenever an entity is
clicked with the right mouse button. Note that it is called on the
entity that is doing the click (usually the player entity).
- Activated (global): This is called whenever the entity is
clicked with the right mouse button. The appropriate action depends
on the entity. Note that this is called on the entity that is being
clicked on.
- OnGround (movable): The object touches the ground. This
happens after the object jumped or was dropped down from some
height. When it then hits the ground this event will be fired.
- FromGround (movable): This is the opposite of OnGround.
It will be fired if the object leaves the ground for some reason.
- TargetDestroyed (locator): When a targetted entity is destroyed
the entity will get this event immediatelly. The entity that is
destroyed will be a parameter.
- TargetVisible (locator): When a target becomes visible
the entity will get this event. This is not immediate because visibility
is not sampled every frame.
- TargetInvisible (locator): When a target becomes invisible
the entity will get this event. This is not immediate because visibility
is not sampled every frame.
- TargetMoves (locator): When a target moves a significant
amount the entity will get this event. This is not immediate because
it is not sampled every frame.
- PathReached (pathFinder): When the movable controlled by
the pathFinder is sufficiently close to the destination the entity
will get this event.
- PathStuck (pathFinder): When the pathFinder decides it cannot
reach the destination it will send this event and stop searching.
- TimerFires (timer): This event is fired if the timer
fires.
- InputKey (input): This event will be fired by the 'input'
property class if a key is pressed. The integer argument is the key
code.
- InputMouse (input): This event will be fired by the 'input'
property class if a mouse button is pressed. The first argument is
the button, the two last arguments are the x and y coordinates.
More events will of course follow. This is only the beginning. Entities
which inherit from BasicEntity
need to implement Init.
The other events have default implementations (which do nothing).