--- /dev/null
+======================================
+ Appendix A -- How to play an IF game
+======================================
+
+Playing IF requires just a bit of instruction. All you have to do is read
+the descriptions and situations that appear on the screen and then tell the
+game what you'd like to happen next. Imagine that you're saying "I WANT TO
+..."; you don't actually type those three words, but you *do* type what
+follows, instructing the game to do something on your behalf. Commands
+usually take the form of a simple imperative sentence, with a verb and a
+direct object (for example, typing EXAMINE THE KETTLE will display a
+description of the kettle, TAKE KETTLE will make it one of your belongings,
+and so on). If there's more than one kettle around, you can be specific
+(TAKE RED KETTLE); otherwise, the game will ask you something like "Which
+do you mean, the red kettle or the rusty kettle?" Answering RED is enough
+in a case like this. Some commands refer to two objects, like: PUT KETTLE
+ON TABLE.
+
+To make them stand out on the page, we're showing the words that you type
+in capital letters. You can actually use upper-case or lower-case letters
+-- it makes no difference -- and you can usually omit words like THE
+(though TAKE A BATH and TAKE THE BATH may have different effects, as will
+TAKE A COIN and TAKE THE COIN if there are several to choose from).
+
+To move around, use the verb GO and one of the cardinal points: GO NORTH
+will move you in the desired direction. Movement happens quite a lot, so
+you can shorten that to just NORTH, and you can even use the initial(s) of
+the direction in which you want to travel (easier and faster to type): N,
+S, E, W, NE, NW, SE and SW. Also available are UP (U), DOWN (D) and,
+occasionally, IN and OUT. There is quite an impressive stock of standard
+actions which can generally be relied upon to do something, even if only to
+tell you that you're wasting your time:
+
+.. hlist::
+ :columns: 5
+
+ * ASK
+ * BURN
+ * BUY
+ * CLEAN
+ * CLIMB
+ * CLOSE
+ * CUT
+ * DIG
+ * DISROBE
+ * DRINK
+ * DROP
+ * EAT
+ * EMPTY
+ * ENTER
+ * EXAMINE
+ * EXIT
+ * FILL
+ * GIVE
+ * GO
+ * INSERT
+ * INVENTORY
+ * JUMP
+ * KILL
+ * KISS
+ * LISTEN
+ * LOCK
+ * LOOK
+ * OFF
+ * ON
+ * OPEN
+ * PRAY
+ * PULL
+ * PUSH
+ * PUT
+ * READ
+ * SEARCH
+ * SHOW
+ * SING
+ * SIT
+ * SLEEP
+ * SMELL
+ * STAND
+ * SWIM
+ * SWITCH
+ * SWITCH
+ * TAKE
+ * TASTE
+ * TELL
+ * THINK
+ * THROW
+ * TIE
+ * TOUCH
+ * TRANSFER
+ * TURN
+ * UNLOCK
+ * WAIT
+ * WAVE
+ * WEAR
+
+You don't have to play IF with a list like this open in front of you; the
+idea is that a good game should understand whatever seems logical for you
+to try next. Sometimes that will be a standard action, sometimes a verb
+like SALUTE or PHOTOGRAPH which, although less common, makes perfect sense
+in context.
+
+You'll discover that usually many of these actions are fairly irrelevant.
+Try logical things first (if you have a torch, BURN may be promising, while
+EAT probably not). Of special interest are LOOK (or just L), to print a
+description of the current location; EXAMINE (or X) *object*, which gives
+you a detailed description of the object; INVENTORY (INV or I) lists the
+objects you are carrying. You may combine some of these verbs with
+prepositions to expand the possibilities: LOOK THROUGH, LOOK AT, LOOK IN,
+LOOK UNDER all perform different actions. Remember that we're mentioning
+only a selection of the possible verbs; if you feel that something else
+ought to work, try it and see.
+
+You can change the way the game offers descriptions of locations as you
+arrive in them. The default setting is usually BRIEF, which provides you
+with long descriptions only the first time you enter a new location. Some
+people like to change this to VERBOSE, which *always* gives you long
+location descriptions. Here are some other special commands and
+abbreviations you should know:
+
+| AGAIN (G) repeats the action you've just performed.
+| WAIT (Z) skips one turn of action while you loiter and see what happens.
+| QUIT ends the game.
+| SAVE saves your current position in the game.
+| RESTORE reloads a previously saved position.
+| RESTART starts again from the beginning.
+| SCORE tells you the current state of progress.
+| UNDO goes back one turn so that your most recent action never happened.
+
+Often, there will be characters that you'll have to interact with. Let's
+suppose you find your cousin Maria: you may ASK (or TELL) MARIA ABOUT
+something, GIVE (or SHOW) object TO MARIA or ASK MARIA FOR object.
+Characters may be willing to help you, when you can indicate your wishes
+with: MARIA, GO NORTH or MARIA, TAKE THE GUN. If you are really fond of
+Maria, you may want to KISS her and if she offends you beyond measure, you
+might like to ATTACK her.
+
+Once you've referred to an object or a character by name, you may use the
+pronouns IT, HIM or HER to simplify the typing process. These pronouns
+will remain set until you refer to any other object or character. If you
+wish to check the current pronoun assignments, type PRONOUNS. As a rule of
+the thumb, try to keep your actions simple. Most games will actually
+understand long commands like TAKE ALL FROM THE BAG EXCEPT THE GREEN PEARL
+THEN THROW CAMEMBERT CHEESE AT UGLY MATRON, but such things are hard to
+type without mistakes. Also, you'll find that other inputs don't work as
+well: GO BACK TO THE KITCHEN or GET NEAR THE SINGING PIRATE or READ
+NEWSPAPER OVER THE SHERIFF'S SHOULDER will all give you error messages of
+some kind. Understanding the conventions of command typing is fairly
+intuitive and you'll quickly master it after a little experimentation.
+
+.. note::
+
+ We're talking here about the core capabilities that most Inform games
+ provide (though much of this is equally applicable to other IF systems).
+ Often the designer will have extended these capabilities by defining
+ additional commands appropriate to the nature of the game; either you'll
+ be told about these, or they'll come naturally to mind during play.
+ Less frequently, some designers like to tamper with the default
+ behaviour of the parser, the interface, or with the way that commands
+ work -- maybe even disabling some of the standard ones completely. When
+ this happens, it's common and polite practice for the game to let you
+ know.
--- /dev/null
+========================
+ Appendix G -- Glossary
+========================
+
+During our travels, we've encountered certain terms which have particular
+significance in the context of the Inform text adventure development
+system; here are brief definitions of many of those specialised words and
+phrases.
+
+.. glossary::
+
+ action
+ The generated effect of the player's input, usually by the
+ :term:`parser` but also occasionally by the designer's code. It
+ refers to a single task to be processed by Inform, such as DROP
+ KETTLE, and it's stored in four numbers: one each for the action
+ itself and the ``actor`` object who is to perform it (the player or
+ an :term:`NPC`), one for the ``noun`` -- or direct object, if
+ present -- and a fourth for the ``second`` noun -- if it exists, for
+ example the "POT" in THROW KETTLE AT POT. See also :term:`fake
+ action`.
+
+ alpha-testing
+ The testing which is carried out by the game's :term:`designer`, in
+ a futile attempt to ensure that it does everything that it should
+ and nothing that it shouldn't. See also :term:`beta-testing`.
+
+ argument
+ A parameter supplied in a call to a :term:`routine`, which is the
+ actual value for one of the routine's defined local variables. For
+ example, the argument is 8 in the call ``MyRoutine(8)``. The
+ definition of the routine includes the variable that will hold the
+ argument, in this case ``x``: ``[ MyRoutine x; ... ];``
+
+ ASCII file
+ See :term:`text file`.
+
+ assignment
+ A statement which sets or changes the value of a :term:`variable`.
+ There are three in Inform: ``=`` (set equal to), ``++`` (add one to
+ the current value), ``--`` (subtract one from the current value).
+
+ attributes
+ Named flags that can be defined for an object after the keyword
+ ``has`` . An attribute is either present (on) or not present
+ (off). The designer may test from any other part of the program
+ *if* an object *has* a certain attribute, *give* an attribute to an
+ object or take it away as need arises. For instance, the attribute
+ ``container`` states that the object is capable of having other
+ objects placed inside it.
+
+ avatar
+ See :term:`player`.
+
+ banner
+
+ Information about a game which is displayed at the start of play.
+
+ beta-testing
+ The testing which is carried out by a small band of trusted
+ volunteers, prior to general public release, during which the gross
+ inadequacy of the designer's :term:`alpha-testing` effort becomes
+ painfully apparent.
+
+ binary file
+
+ A computer file containing binary data -- 0s and 1s -- which is
+ created by a program and which only a program can understand.
+
+ bold type
+ Used to highlight a term explained in this glossary.
+
+ child
+ See :term:`object tree`.
+
+ class
+ A special :term:`object` template from which other objects can
+ inherit :term:`properties` and/or :term:`attributes`. The template
+ must begin with the word ``Class`` and must have an internal
+ identifier. Objects that wish to inherit from a class usually
+ begin with the internal ID of the class in place of the word
+ ``Object`` , but may instead define a segment ``class`` followed by
+ the class's internal ID. The designer may test whether an object
+ belongs to -- is a member of -- a class.
+
+ code block
+ See :term:`statement block`.
+
+ comment
+ Text which starts with an exclamation mark ``!`` and which is
+ ignored by the compiler when it reads the :term:`source file`;
+ added to improve the file's layout or for explanatory notes.
+
+ compile-time
+ The time when the :term:`compiler` is at work making the
+ :term:`story file`. See also :term:`run-time`.
+
+ compiler
+ A program that reads the source code written by the designer and
+ turns it into a :term:`story file`, which can then be played by a
+ Z-machine :term:`interpreter`.
+
+ constant
+ A particular value which is defined at :term:`compile-time`, always
+ stays the same and cannot be changed while the game is being
+ played. Common examples include numbers, strings and the internal
+ IDs of objects, any of which can be either written out explicitly
+ or set as the value of a named ``Constant``.
+
+ Debug mode
+ A option which causes to compiler to include extra code into the
+ story file, thus making it easier for the designer to understand
+ what's happening while a game is being tested prior to release.
+ See also :term:`Strict mode`.
+
+ designer
+ A person who uses Inform to create a text adventure game: in other
+ words, gentle reader, you.
+
+ dictionary
+ The collection of all input words "understood" by the game.
+
+ dictionary word
+ A word written in single quotes '...' within the :term:`source
+ file`, usually (but not exclusively) as one of the values assigned
+ to an object's ``name`` property. All such words are stored in the
+ :term:`dictionary`, which is consulted by the :term:`parser` when
+ attempting to make sense of a player's command. Only the first
+ nine characters are significant (thus ``'cardiogram'`` and
+ ``'cardiograph'`` are treated as the same word). Use
+ ``'coins//p'`` to mark "``coins``" as plural, referring to all coin
+ objects which are present. Use ``'t//'`` to enter the
+ single-character word "t" into the dictionary (``'t'`` is a
+ constant representing a character value).
+
+ directive
+ A line of Inform code which asks the :term:`compiler` to do
+ something there and then, at :term:`compile-time`; typical examples
+ are to Include the contents of another file, or to set aside some
+ space within the story file where a variable value may be stored.
+ Not to be confused with a :term:`statement`, which asks the
+ compiler to compose an instruction which the interpreter will obey
+ at :term:`run-time`; typical examples are to display some text, or
+ to change the value held within a variable's storage space.
+
+ editor
+ A general-purpose program for creating and modifying :term:`text
+ file`\s.
+
+ embedded routine
+ A routine that is defined in the body of an object, as the value of
+ one of its :term:`properties`. Unlike a :term:`standalone
+ routine`, an embedded routine doesn't have a name of its own, and
+ returns ``false`` if execution reaches the terminating marker
+ ``]``.
+
+ entry point
+ One of a predefined list of optional routines which, if you provide
+ it, will be called by the library either to produce some
+ supplementary output or to return a value causing the library to
+ change its default behaviour.
+
+ fake action
+ An action generated indirectly by the library rather than directly
+ by what the player types. For example, PUT X IN Y triggers a real
+ action of Insert (which can be intercepted by X) and a fake action
+ of Receive (which can be intercepted by Y).
+
+ false
+ A logical state which is the opposite of :term:`true`, represented
+ by the value 0.
+
+ flag
+ A variable which can take only two possible values.
+
+ function
+ See :term:`routine`.
+
+ global variable
+ A variable not specific to any routine or object, which can be used
+ by any routine in the game.
+
+ inheritance
+ The process by which an :term:`object` belonging to a :term:`class`
+ acquires the properties and attributes of said class. Inheritance
+ happens automatically; the designer has just to create class
+ definitions, followed by objects having those classes.
+
+ interpreter
+ A program that reads the :term:`story file` of a game and enables
+ people to play it. Interpreters must be platform-specific (that
+ is, they will be different programs for each operating system),
+ thus allowing the story file to be universal and
+ platform-independent.
+
+ italic type
+ Used for emphasis, and as a placeholder to represent a value which
+ you should supply.
+
+ library
+ A group of text files, part of the Inform system, that includes the
+ :term:`parser`, definitions for the :term:`model world`, language
+ files, grammar definitions and a customised stock of default
+ answers and behaviour for the player's actions. The library will
+ make frequent calls to the game file to see if the designer wants
+ to override those defaults.
+
+ library files
+ The actual files containing the source code of the library. There
+ are basically three (although these three Include other files as
+ well): ``parser.h`` , ``verblib.h`` and ``grammar.h``, and they
+ should be Included in every Inform game.
+
+ library routine
+ One of a set of routines included as part of the library which the
+ designer can call to perform some commonly useful task.
+
+ local variable
+ A variable which is part of only one :term:`routine`; its value
+ remains unavailable to other routines in the game. The value of a
+ local variable is *not* preserved between calls to the routine.
+
+ model world
+ The imaginary environment which the player character inhabits.
+
+ newline
+ The ASCII control character(s) used to mark the end of a line of
+ text.
+
+ NPC
+ A non-player character; any character other than the protagonist.
+ Could range from an opponent or love interest to a pet gerbil or a
+ random pedestrian.
+
+ object
+ A group of :term:`routine`\s and variables bundled up together in a
+ coherent unit. Objects represent the items that make up the
+ :term:`model world` (a torch; a car; a beam of light; etc.), a fact
+ which organises the designer's code in sensible chunks, easy to
+ manage. Each object has two parts: the header, which comprises the
+ internal ID, the external name and its defined parent (all fields
+ are optional), and the body, which comprises the property variables
+ and attribute flags particular to that object, if any.
+
+ object tree
+ A hierarchy that defines objects' relationships in terms of
+ containment. Each :term:`object` is either contained within
+ another object -- its parent -- or is *not* contained; objects such
+ as rooms which are not within another object have the constant
+ ``nothing`` (0) as a parent. An object contained within another is
+ a child. For example, a shoe inside a box: the box is the shoe's
+ parent and the shoe is a child of the box. Consider now this box
+ being inside the wardrobe. The box is a child of the wardrobe, but
+ the shoe is still a child of the box, not the wardrobe. In a
+ normal game, the object tree will undergo many transformations as
+ the result of the player's activities.
+
+ parent
+ See :term:`object tree`.
+
+ parser
+ Part of the :term:`library` which is responsible for analysing the
+ player's input and trying to make sense of it, dividing it into
+ separate words (verb, nouns) and trying to match them against the
+ words stored in the game's :term:`dictionary` and the actions
+ defined in the game's grammar. If the player's input makes sense,
+ the parser will trigger the resulting :term:`action`; if not, it
+ will complain that it didn't understand.
+
+ PC
+ 1. a personal computer;
+ 2. the player character (see :term:`player`).
+
+ player
+ 1. the final user of the game, normally a person full of radical
+ opinions about your capabilities as a designer;
+ 2. a variable referring to the :term:`object` -- sometimes known as
+ an "avatar" -- which currently represents that user within the
+ :term:`model world`.
+
+ print rule
+ A customised rule to apply while in a ``print`` or ``print_ret``
+ statement, to control the manner in which an item of data is to be
+ displayed. For example: ``print (The) noun, " is mine."`` is
+ telling the game to use a capitalised definite article for the
+ noun. The library defines a stock of print rules, and designers
+ may create some of their own.
+
+ properties
+ Variables attached to a single :term:`object`, of which they are a
+ part. They are defined in the body of the object after the keyword
+ ``with`` and have a name and a value. The latter (which defaults
+ to 0) can be a number, a string "...", a dictionary word '...' or
+ an embedded routine ``[;...]``; it can also be a list of those
+ separated by spaces. The value of an object's property can be
+ tested and changed from any part of the game. The fact that an
+ object provides a property may be tested.
+
+ RAIF
+ The ``rec.arts.int-fiction`` Usenet newsgroup for IF designers.
+
+ RGIF
+
+ The ``rec.games.int-fiction`` Usenet newsgroup for IF players.
+
+ room
+ An :term:`object` which defines a geographical unit into which the
+ map of the :term:`model world` is divided. Rooms have no parent
+ object (or, more precisely, their parent object is ``nothing``) and
+ they represent the places where the player character is at any
+ given moment -- the player character can't be in more than one room
+ at a time. Note that the name "room" does not imply necessarily
+ "indoors". A clearing, a sandy beach, the top of a tree, even
+ floating in outer space -- these are all possible room objects.
+
+ routine
+ In general terms, a routine is a computer program that makes some
+ specific calculation, following an ordered set of instructions;
+ this is the only unit of coherent and executable code understood by
+ Inform. More practically, a routine is a collection of
+ :term:`statement`\s which are written between markers ``[...]``.
+ When a routine is "called", possibly with arguments -- specific
+ values for its defined variables, if they exist -- the interpreter
+ executes the statements in sequence. If the interpreter encounters
+ a ``return`` statement, or reaches the ``]`` at the end of the
+ routine, it immediately stops executing statements in the routine
+ and resumes execution at the statement which called that routine.
+ Every routine returns a value, which is either supplied by the
+ return statement or implied by the ] at the end of the routine.
+ See :term:`embedded routine` and :term:`standalone routine`.
+
+ run-time
+ The period of time when the :term:`interpreter` is running a
+ :term:`story file` (that is, someone is playing the game). See
+ also :term:`compile-time`.
+
+ source file
+ A text file containing your game defined using the Inform language.
+
+ standalone routine
+ A routine which is not part of an object. Unlike an
+ :term:`embedded routine`, it must provide a name of its own, and it
+ returns ``true`` when execution reaches the terminating marker
+ ``]``.
+
+ statement
+ A single instruction to be executed at :term:`run-time`. See also
+ :term:`directive`.
+
+ statement block
+ A group of :term:`statement`\s bundled up together between braces
+ ``{...}``, which are then treated as a single unit -- as if they
+ were only one statement. They commonly appear in loops and
+ conditions.
+
+ story file
+ A binary file which is the output of the :term:`compiler` and can
+ be played through the use of an :term:`interpreter` (also known as
+ Z-code file or game file). The format of story files is standard
+ and platform-independent.
+
+ Strict mode
+ An option which causes the :term:`compiler` to include extra code
+ into the story file, thus making it easier to detect certain design
+ mistakes while a game is being played.
+
+ string
+ A piece of text between double quotes "...", to be displayed for
+ the player's benefit at :term:`run-time`.
+
+ switch
+ 1. an optional keyword or symbol to operate special features of the
+ compiler.
+ 2. a statement which decides among different paths of execution
+ according to the value of an expression.
+
+ text file
+ A computer file containing words and phrases which a human can
+ read.
+
+ true
+ A logical state which is the opposite of :term:`false`, represented
+ by any value other than zero (typically 1).
+
+ variable
+ A named value which can change during :term:`run-time`. It must be
+ declared before use, either as a ``Global`` variable (available to
+ any routine within the game), or as a local variable (part of one
+ specific routine and usable by that routine alone). Variables have
+ a name and a value; it's the value which is capable of change, not
+ the name. Object :term:`properties` behave as variables.
+
+ Z-code file
+ See :term:`story file`.
+
+ Z-machine
+ A virtual machine (an imaginary computer simulated by the
+ :term:`interpreter`) on which story files run. Z stands for
+ "Zork", the first ever Infocom title.
projects / ibg.git / commitdiff