DM4 §A5: Entry point routines

## §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.