1
Developer's documentation, part 3: Entities
	Matti Niemenmaa, 2007-11-05

1
This is the third part of the developer documentation, explaining how entities
work and can be written. Like all developer documentation, this is meant to be
read in order, which is why keywords like "part-1" are provided, but a text
editor is best.

2
7
___Part-1___
An entity is essentially a result of a special case of spell. It can only be
cast in the lab, and it creates the entity, which is more complicated than a
spell effect.

An entity is worth a number of points, awarded when the bell in the lobby is
rung. When performing a *motion*, the entity is generally worth less points, as
this shows that it isn't fully under the caster's control.

To consider the game "won", an entity //must// be summoned.

The basic structure of an entity:

summoning spell (see Developer's documentation, part 2)
names
*default state*
[motions]

The summoning spell is different from a normal spell in that its results
implicitly have the *consequence* (see appendix A) that the entity is summoned
(unless the spell fails), and that the only allowed consequences are: fail,
sanity, gameover, realgameover. (gameover and realgameover are equivalent
here.)

The names are used as possible parameters to the "look" verb. They should be
brief and obvious.

12
___Part-2___
An entity is always in a *state*, either the default state or performing a
motion. Each state has a description and any number of results (see appendix
A), which are the entity's responses to spells cast in its presence. This is
similar to the way a spell's effects may change depending on what spells are in
effect when it is cast, with the difference that the results are specified in
the entity.

The *default state* looks such:

score
short description
long description
[results]

Where:
- score is the score awarded at the end of the game, when the bell is rung: it
  must be in the interval [-128, 128),
- short description is the description shown as part of the room description,
- long description is the description shown when the entity is looked at,
- results are the entity's default responses to spells.

Note that regardless of the state in which the entity is, the default responses
always apply unless overridden by the non-default state. For instance, consider
the case where an entity's default state contains responses to the spells A and
B, and the current state has a response to spell B. When spell B is cast, the
current state's response is used. When spell A is cast, the default state's
response is used.

A *motion* is comprised of the following:

interval probability length
pre-requisite
score modifier
entry message
short description
long description
[while results]
end results

Where:
- short description and long description are as in the default state,
- interval is a positive integer which represents how often the check whether
  to enter the state is made,
- probability is a decimal which represents the chance of entering the state
  when the check is made,
- length is a positive integer which represents how long the motion takes
  before the end results are applied,
- pre-requisite is a boolean expression (see appendix A) which must be true for
  the motion to be begun,
- score modifier is an integer in the interval [-128, 128) added to the default
  state's score if this motion is active when the bell is rung,
- entry message is the message displayed when the motion is begun,
- while results are the entity's responses to spells whilst in the state,
- end results are what happens when the motion is completed.

Starting from when the entity last entered the default state (i.e. from when it
was summoned or from when the previous motion ended), every **interval** turns,
if the **pre-requisites** are true, there is a probability of **probability**
that the motion is entered.

While results and end results are differentiated by preceding the boolean
expression in each case with "while" and "end", respectively.

A while result failing means that the motion ends and the default state is
assumed. An end result failing is meaningless, but may be added (for clarity -
but with the current implementation it is also a minor optimization).

Valid motion consequences (for both end and while results) are: fail, counter,
sanity, leave, gameover, realgameover.
