Section A10: Entry points and meaningful constants

Contents Back Forward | ### A10. Entry points and meaningful constants
| Entry points are routines which you can provide, if you choose to, and which are called by the library routines to give you the option of changing the rules. All games must define an `Initialise` routine, which is obliged to set the `location` variable to a room; the rest are optional.bigskip `AfterLife` 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=0` again it can resurrect the player. `AfterPrompt` 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. `Amusing` 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. (But only if you have defined the constant `AMUSING_PROVIDED` in your own code.) `BeforeParsing` 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, and can leave the word marker anywhere; there is no meaningful return value. `ChooseObjects(obj,c)` When `c` is 0, the parser is processing an "all'' and has decided to exclude `obj` from it; when `c` is 1, it has decided to include it. Returning 1 forces inclusion, returning 2 forces exclusion and returning 0 lets the parser's decision stand. When `c` is 2, the parser wants help in resolving an ambiguity: using the `action_to_be` variable the routine must decide how appropriate `obj` is for the given action and return a score of 0 to 9 accordingly. See Section 29. `DarkToDark` Called when a player goes from one dark room into another one; a splendid excuse to kill the player off. `DeathMessage` Prints up "You have died" style messages, for `deadflag` values of 3 or more. (If you choose ever to set `deadflag` to such.) `GamePostRoutine` A kind of super-`after` rule, which applies to all actions in the game, whatever they are: use only in the last resort. `GamePreRoutine` A kind of super-`before` rule, which applies to all actions in the game, whatever they are: use only in the last resort. `Initialise` A compulsory routine, which must set `location` and is convenient for miscellaneous initialising, perhaps for random settings. `InScope` An opportunity to place extra items in scope during parsing, or to change the scope altogether. If `et_flag` is 1 when this is called, the scope is being worked out for `each_turn` reasons; otherwise for everyday parsing. `LookRoutine` Called at the end of every `Look` description. `NewRoom` Called when the room changes, before any description of it is printed. This happens in the course of ordinary movements or use of `PlayerTo`, but may not happen if the game uses `move` to shift the player object directly. `ParseNoun(obj)` 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. `ParseNumber(text,n)` 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`. `ParserError(pe)` The chance to print different parser error messages (like "I don't understand that sentence''). `pe` is the parser error number (see Section 29). `PrintRank` Completes the printing of the score. You might want to change this, so as to make the ranks something like "junior astronaut" or "master catburglar" or whatever suits your game. `PrintVerb(v)` 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. Returns true (or 1) if it has printed something. `PrintTaskName(n)` Prints the name of task `n` (such as "driving the car"). `TimePasses` Called after every turn (but not, for instance, after a command like "score" or "save"). It's much more elegant to use timers and daemons, or `each_turn` routines for individual rooms -- using this is a last resort. `UnknownVerb` Called by the parser when it hits an unknown verb, so that you can transform it into a known one. The following constants, if defined in a game, change settings made by the library. Those described as "To indicate that...'' have no meaningful value; one simply defines them by, e.g., the directive `Constant DEBUG;`. `AMUSING_PROVIDED` To indicate that an `Amusing` routine is provided. `DEBUG` To indicate that the special "debugging" verbs are to be included. `Headline` Style of game and copyright message. `MAX_CARRIED` Maximum number of (direct) possessions the player can carry. `MAX_SCORE` Maximum game score. `MAX_TIMERS` Maximum number of timers or daemons active at any one time (defaults to 32). `NO_PLACES` To indicate that the "places'' and "objects'' verbs should not be allowed. `NUMBER_TASKS` Number of 'tasks' to perform. `OBJECT_SCORE` Score for picking up a `scored` object for the first time. `ROOM_SCORE` Score for visiting up a `scored` room for the first time. `SACK_OBJECT` Object which acts as a 'rucksack', into which the game automatically tidies away things for the player. `Story` Story name, conventionally in CAPITAL LETTERS. `TASKS_PROVIDED` To indicate that "tasks'' are provided. `WITHOUT_DIRECTIONS` To indicate that the standard compass directions are to be omitted.

Contents / Back / Forward
Chapter I / Chapter II / Chapter III / Chapter IV / Chapter V / Chapter VI / Appendix

Mechanically translated to HTML from third edition as revised 16 May 1997. Copyright © Graham Nelson 1993, 1994, 1995, 1996, 1997: all rights reserved.