§A5   Entry point routines

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.