By definition, an “entry point routine”
is a routine which you can choose whether or not to define in your
source code. If you do, the library will make calls to it from time
to time, allowing it to change the way the game rules are administered.
The exception is Initialise
, which is compulsory.
AfterLife() |
see §21 |
When the player has died (a condition signalled by
the variable deadflag
being set to a non-zero value other
than 2, which indicates winning), this routine is called: by setting
deadflag
to be false
again it can resurrect
the player.
No return value
AfterPrompt() |
see §22 |
Called just after the prompt is printed: therefore,
called after all the printing for this turn is definitely over. A
useful opportunity to use box
to display quotations without
them scrolling away.
No return value
Amusing() |
see §21 |
Called to provide an “afterword” for
players who have won: for instance, it might advertise some features
which a successful player might never have noticed. This will only
be called if you have also defined the constant AMUSING_PROVIDED
in your own code.
No return value
BeforeParsing() |
see §30 |
Called after the parser has read in some text and
set up the buffer
and parse
tables, but has
done nothing else yet except
to set the word marker wn
to 1. The routine can do anything
it likes to these tables provided they remain consistent with each other,
and can leave the word marker anywhere.
No return value
ChooseObjects(obj,c) |
see §33 |
When c
is false
, the parser
is processing an “all” and has decided to exclude obj
from it; when c
is true
, it has decided to
include it. When c
is 2, the parser wants help in resolving
an ambiguity: perhaps using the action_to_be
variable the
routine must decide how appropriate obj
is for the given
action.
Routine returns When c
is
false
or true
, return false
to
accept the parser's decision, 1 to force inclusion of obj
,
2 to force exclusion. When c
is 2, return a numerical
score between 0 and 9, with 0 being “inappropriate”
and 9 “very appropriate”.
DarkToDark() |
see §19 |
Called when a player goes from one dark room into another one, which is a splendid excuse to kill the player off.
DeathMessage() |
see §21 |
If the player's death occurs because you have set
deadflag
to a value of 3 or more, this entry point is
called to print up a suitable “You have died”-style message.
No return value
GamePostRoutine() |
see §6 |
A kind of super-after
rule, which
applies to all actions in the game, whatever they are: use this only
in the last resort.
Routine returns false
to allow the action to continue as usual, true
to stop
the action and print nothing further.
GamePreRoutine() |
see §6 |
A kind of super-before
rule, which
applies to all actions in the game, whatever they are: use this only
in the last resort.
Routine returns false
to allow the action to continue as usual, true
to stop
the action and print nothing further.
Initialise() |
see §21 |
An opportunity to set up the initial state of the
game. This routine is compulsory and has one compulsory task: to set
location
to the place where the player begins, or to
the enterable
object in or on which the player begins.
It's usual to print a welcoming message as well.
Routine returns true
or false
to continue as usual; 2 to suppress the game
banner, which would otherwise be printed immediately after this routine
is called.
InScope() |
see §32 |
An opportunity to change the library's definition
of what is in scope. This acts as a sort of global version of a scope
token routine: it should use the library routines ScopeWithin
and PlaceInScope
to define what scope should be. It may
want to look at the library variable et_flag
. If this
is true
, the scope is being worked out in order to run
through each_turn
. If it's false
, then the
scope is being worked out for everyday parsing.
Routine returns false
to
tell the parser to add all the usual objects in scope as well, or
true
to tell the parser that nothing further is in scope.
LookRoutine() |
see §26 |
Called at the end of every Look
action, that
is, room description.
No return value
NewRoom() |
see §21 |
Called when the room changes, before any description
of it is printed. This happens in the course of any movements or uses
of PlayerTo
.
No return value
ParseNoun(obj) |
see §28 |
To do the job of parsing the name
property (if
parse_name
hasn't done it already). This takes one argument,
the object in question, and returns a value as if it were a
parse_name
routine.
Routine returns The number of words
matched, or 0 if there is no match, or −1 to decline to make
a decision and give the job back to the parser. Note that if −1
is returned, the word number variable wn
must be left
set to the first word the parser should look at — probably the
same value it had when ParseNoun
was called, but not
necessarily.
ParseNumber(text,n) |
see §28 |
An opportunity to parse numbers in a different, or
additional, way. The text to be parsed is a byte array of length
n
starting at text
.
Routine returns 0 to signal “no
match”, 1 to 10000 to signal “this number has been
matched”.
ParserError(pe) |
see §33 |
The chance to print different parser error messages
such as “I don't understand that sentence”. pe
is the parser error number and the table of possible values is given
in §33.
Routine returns true
to
tell the parser that the error message has now been printed, or
false
to allow it to carry on and print the usual one.
PrintRank() |
see §22 |
Completes the printing of the score. Traditionally, many
games have awarded the player a rank based on the current value of
the variable score
.
No return value
PrintTaskName(n) |
see §22 |
Prints the name of task n
, which lies
between 0 and NUMBER_TASKS
minus 1.
No return value
PrintVerb(v) |
see §30 |
A chance to change the verb printed out in a parser
question (like “What do you want to (whatever)?”) in
case an unusual verb via UnknownVerb
has been constructed.
v
is the dictionary address of the verb.
Routine returns true
to
tell the parser that the verb has now been printed, or false
to allow it to carry on and print the usual one.
TimePasses() |
see §20 |
Called after every game turn, which is to say, not
after a group 1 action such as “score” or “save”,
but after any other activity. Use this entry point only as a last
resort, as it's almost certainly easier and tidier to use timers
and daemons.
No return value
UnknownVerb(word) |
see §30 |
Called by the parser when it hits an unknown verb,
so that you can transform it into a known one. word
is the
dictionary value of this unknown verb.
Routine returns false
to
allow the parser to carry on and print an error message, or the
dictionary value of a verb to use instead.