appendices/g.rst

   1 ========================
   2  Appendix G -- Glossary
   3 ========================
   4
   5 .. only:: html
   6
   7    .. image:: /images/picD.png
   8       :align: left
   9
  10 .. raw:: latex
  11
  12     \dropcap{d}
  13
  14 uring our travels, we've encountered certain terms which have particular
  15 significance in the context of the Inform text adventure development
  16 system; here are brief definitions of many of those specialised words and
  17 phrases.
  18
  19 .. glossary::
  20
  21    action
  22        The generated effect of the player's input, usually by the
  23        :term:`parser` but also occasionally by the designer's code.  It
  24        refers to a single task to be processed by Inform, such as DROP
  25        KETTLE, and it's stored in four numbers: one each for the action
  26        itself and the ``actor`` object who is to perform it (the player or
  27        an :term:`NPC`), one for the ``noun`` -- or direct object, if
  28        present -- and a fourth for the ``second`` noun -- if it exists, for
  29        example the "POT" in THROW KETTLE AT POT.  See also :term:`fake
  30        action`.
  31
  32    alpha-testing
  33        The testing which is carried out by the game's :term:`designer`, in
  34        a futile attempt to ensure that it does everything that it should
  35        and nothing that it shouldn't.  See also :term:`beta-testing`.
  36
  37    argument
  38        A parameter supplied in a call to a :term:`routine`, which is the
  39        actual value for one of the routine's defined local variables.  For
  40        example, the argument is 8 in the call ``MyRoutine(8)``.  The
  41        definition of the routine includes the variable that will hold the
  42        argument, in this case ``x``: ``[ MyRoutine x; ... ];``
  43
  44    ASCII file
  45        See :term:`text file`.
  46
  47    assignment
  48        A statement which sets or changes the value of a :term:`variable`.
  49        There are three in Inform: ``=`` (set equal to), ``++`` (add one to
  50        the current value), ``--`` (subtract one from the current value).
  51
  52    attributes
  53        Named flags that can be defined for an object after the keyword
  54        ``has`` .  An attribute is either present (on) or not present
  55        (off).  The designer may test from any other part of the program
  56        *if* an object *has* a certain attribute, *give* an attribute to an
  57        object or take it away as need arises.  For instance, the attribute
  58        ``container`` states that the object is capable of having other
  59        objects placed inside it.
  60
  61    avatar
  62        See :term:`player`.
  63
  64    banner
  65
  66        Information about a game which is displayed at the start of play.
  67
  68    beta-testing
  69        The testing which is carried out by a small band of trusted
  70        volunteers, prior to general public release, during which the gross
  71        inadequacy of the designer's :term:`alpha-testing` effort becomes
  72        painfully apparent.
  73
  74    binary file
  75
  76        A computer file containing binary data -- 0s and 1s -- which is
  77        created by a program and which only a program can understand.
  78
  79    bold type
  80        Used to highlight a term explained in this glossary.
  81
  82    child
  83        See :term:`object tree`.
  84
  85    class
  86        A special :term:`object` template from which other objects can
  87        inherit :term:`properties` and/or :term:`attributes`.  The template
  88        must begin with the word ``Class`` and must have an internal
  89        identifier.  Objects that wish to inherit from a class usually
  90        begin with the internal ID of the class in place of the word
  91        ``Object`` , but may instead define a segment ``class`` followed by
  92        the class's internal ID.  The designer may test whether an object
  93        belongs to -- is a member of -- a class.
  94
  95    code block
  96        See :term:`statement block`.
  97
  98    comment
  99        Text which starts with an exclamation mark ``!`` and which is
 100        ignored by the compiler when it reads the :term:`source file`;
 101        added to improve the file's layout or for explanatory notes.
 102
 103    compile-time
 104        The time when the :term:`compiler` is at work making the
 105        :term:`story file`.  See also :term:`run-time`.
 106
 107    compiler
 108        A program that reads the source code written by the designer and
 109        turns it into a :term:`story file`, which can then be played by a
 110        Z-machine :term:`interpreter`.
 111
 112    constant
 113        A particular value which is defined at :term:`compile-time`, always
 114        stays the same and cannot be changed while the game is being
 115        played.  Common examples include numbers, strings and the internal
 116        IDs of objects, any of which can be either written out explicitly
 117        or set as the value of a named ``Constant``.
 118
 119    Debug mode
 120        A option which causes to compiler to include extra code into the
 121        story file, thus making it easier for the designer to understand
 122        what's happening while a game is being tested prior to release.
 123        See also :term:`Strict mode`.
 124
 125    designer
 126        A person who uses Inform to create a text adventure game: in other
 127        words, gentle reader, you.
 128
 129    dictionary
 130        The collection of all input words "understood" by the game.
 131
 132    dictionary word
 133        A word written in single quotes '...'  within the :term:`source
 134        file`, usually (but not exclusively) as one of the values assigned
 135        to an object's ``name`` property.  All such words are stored in the
 136        :term:`dictionary`, which is consulted by the :term:`parser` when
 137        attempting to make sense of a player's command.  Only the first
 138        nine characters are significant (thus ``'cardiogram'`` and
 139        ``'cardiograph'`` are treated as the same word).  Use
 140        ``'coins//p'`` to mark "``coins``" as plural, referring to all coin
 141        objects which are present.  Use ``'t//'`` to enter the
 142        single-character word "t" into the dictionary (``'t'`` is a
 143        constant representing a character value).
 144
 145    directive
 146        A line of Inform code which asks the :term:`compiler` to do
 147        something there and then, at :term:`compile-time`; typical examples
 148        are to Include the contents of another file, or to set aside some
 149        space within the story file where a variable value may be stored.
 150        Not to be confused with a :term:`statement`, which asks the
 151        compiler to compose an instruction which the interpreter will obey
 152        at :term:`run-time`; typical examples are to display some text, or
 153        to change the value held within a variable's storage space.
 154
 155    editor
 156        A general-purpose program for creating and modifying :term:`text
 157        file`\s.
 158
 159    embedded routine
 160        A routine that is defined in the body of an object, as the value of
 161        one of its :term:`properties`.  Unlike a :term:`standalone
 162        routine`, an embedded routine doesn't have a name of its own, and
 163        returns ``false`` if execution reaches the terminating marker
 164        ``]``.
 165
 166    entry point
 167        One of a predefined list of optional routines which, if you provide
 168        it, will be called by the library either to produce some
 169        supplementary output or to return a value causing the library to
 170        change its default behaviour.
 171
 172    fake action
 173        An action generated indirectly by the library rather than directly
 174        by what the player types.  For example, PUT X IN Y triggers a real
 175        action of Insert (which can be intercepted by X) and a fake action
 176        of Receive (which can be intercepted by Y).
 177
 178    false
 179        A logical state which is the opposite of :term:`true`, represented
 180        by the value 0.
 181
 182    flag
 183        A variable which can take only two possible values.
 184
 185    function
 186        See :term:`routine`.
 187
 188    global variable
 189        A variable not specific to any routine or object, which can be used
 190        by any routine in the game.
 191
 192    inheritance
 193        The process by which an :term:`object` belonging to a :term:`class`
 194        acquires the properties and attributes of said class.  Inheritance
 195        happens automatically; the designer has just to create class
 196        definitions, followed by objects having those classes.
 197
 198    interpreter
 199        A program that reads the :term:`story file` of a game and enables
 200        people to play it.  Interpreters must be platform-specific (that
 201        is, they will be different programs for each operating system),
 202        thus allowing the story file to be universal and
 203        platform-independent.
 204
 205    italic type
 206        Used for emphasis, and as a placeholder to represent a value which
 207        you should supply.
 208
 209    library
 210        A group of text files, part of the Inform system, that includes the
 211        :term:`parser`, definitions for the :term:`model world`, language
 212        files, grammar definitions and a customised stock of default
 213        answers and behaviour for the player's actions.  The library will
 214        make frequent calls to the game file to see if the designer wants
 215        to override those defaults.
 216
 217    library files
 218        The actual files containing the source code of the library.  There
 219        are basically three (although these three Include other files as
 220        well): ``parser.h`` , ``verblib.h`` and ``grammar.h``, and they
 221        should be Included in every Inform game.
 222
 223    library routine
 224        One of a set of routines included as part of the library which the
 225        designer can call to perform some commonly useful task.
 226
 227    local variable
 228        A variable which is part of only one :term:`routine`; its value
 229        remains unavailable to other routines in the game.  The value of a
 230        local variable is *not* preserved between calls to the routine.
 231
 232    model world
 233        The imaginary environment which the player character inhabits.
 234
 235    newline
 236        The ASCII control character(s) used to mark the end of a line of
 237        text.
 238
 239    NPC
 240        A non-player character; any character other than the protagonist.
 241        Could range from an opponent or love interest to a pet gerbil or a
 242        random pedestrian.
 243
 244    object
 245        A group of :term:`routine`\s and variables bundled up together in a
 246        coherent unit.  Objects represent the items that make up the
 247        :term:`model world` (a torch; a car; a beam of light; etc.), a fact
 248        which organises the designer's code in sensible chunks, easy to
 249        manage.  Each object has two parts: the header, which comprises the
 250        internal ID, the external name and its defined parent (all fields
 251        are optional), and the body, which comprises the property variables
 252        and attribute flags particular to that object, if any.
 253
 254    object tree
 255        A hierarchy that defines objects' relationships in terms of
 256        containment.  Each :term:`object` is either contained within
 257        another object -- its parent -- or is *not* contained; objects such
 258        as rooms which are not within another object have the constant
 259        ``nothing`` (0) as a parent.  An object contained within another is
 260        a child.  For example, a shoe inside a box: the box is the shoe's
 261        parent and the shoe is a child of the box.  Consider now this box
 262        being inside the wardrobe.  The box is a child of the wardrobe, but
 263        the shoe is still a child of the box, not the wardrobe.  In a
 264        normal game, the object tree will undergo many transformations as
 265        the result of the player's activities.
 266
 267    parent
 268        See :term:`object tree`.
 269
 270    parser
 271        Part of the :term:`library` which is responsible for analysing the
 272        player's input and trying to make sense of it, dividing it into
 273        separate words (verb, nouns) and trying to match them against the
 274        words stored in the game's :term:`dictionary` and the actions
 275        defined in the game's grammar.  If the player's input makes sense,
 276        the parser will trigger the resulting :term:`action`; if not, it
 277        will complain that it didn't understand.
 278
 279    PC
 280        1. a personal computer;
 281        2. the player character (see :term:`player`).
 282
 283    player
 284        1. the final user of the game, normally a person full of radical
 285           opinions about your capabilities as a designer;
 286        2. a variable referring to the :term:`object` -- sometimes known as
 287           an "avatar" -- which currently represents that user within the
 288           :term:`model world`.
 289
 290    print rule
 291        A customised rule to apply while in a ``print`` or ``print_ret``
 292        statement, to control the manner in which an item of data is to be
 293        displayed.  For example: ``print (The) noun, " is mine."`` is
 294        telling the game to use a capitalised definite article for the
 295        noun.  The library defines a stock of print rules, and designers
 296        may create some of their own.
 297
 298    properties
 299        Variables attached to a single :term:`object`, of which they are a
 300        part.  They are defined in the body of the object after the keyword
 301        ``with`` and have a name and a value.  The latter (which defaults
 302        to 0) can be a number, a string "...", a dictionary word '...' or
 303        an embedded routine ``[;...]``; it can also be a list of those
 304        separated by spaces.  The value of an object's property can be
 305        tested and changed from any part of the game.  The fact that an
 306        object provides a property may be tested.
 307
 308    RAIF
 309        The ``rec.arts.int-fiction`` Usenet newsgroup for IF designers.
 310
 311    RGIF
 312
 313        The ``rec.games.int-fiction`` Usenet newsgroup for IF players.
 314
 315    room
 316        An :term:`object` which defines a geographical unit into which the
 317        map of the :term:`model world` is divided.  Rooms have no parent
 318        object (or, more precisely, their parent object is ``nothing``) and
 319        they represent the places where the player character is at any
 320        given moment -- the player character can't be in more than one room
 321        at a time.  Note that the name "room" does not imply necessarily
 322        "indoors".  A clearing, a sandy beach, the top of a tree, even
 323        floating in outer space -- these are all possible room objects.
 324
 325    routine
 326        In general terms, a routine is a computer program that makes some
 327        specific calculation, following an ordered set of instructions;
 328        this is the only unit of coherent and executable code understood by
 329        Inform.  More practically, a routine is a collection of
 330        :term:`statement`\s which are written between markers ``[...]``.
 331        When a routine is "called", possibly with arguments -- specific
 332        values for its defined variables, if they exist -- the interpreter
 333        executes the statements in sequence.  If the interpreter encounters
 334        a ``return`` statement, or reaches the ``]`` at the end of the
 335        routine, it immediately stops executing statements in the routine
 336        and resumes execution at the statement which called that routine.
 337        Every routine returns a value, which is either supplied by the
 338        return statement or implied by the ] at the end of the routine.
 339        See :term:`embedded routine` and :term:`standalone routine`.
 340
 341    run-time
 342        The period of time when the :term:`interpreter` is running a
 343        :term:`story file` (that is, someone is playing the game).  See
 344        also :term:`compile-time`.
 345
 346    source file
 347        A text file containing your game defined using the Inform language.
 348
 349    standalone routine
 350        A routine which is not part of an object.  Unlike an
 351        :term:`embedded routine`, it must provide a name of its own, and it
 352        returns ``true`` when execution reaches the terminating marker
 353        ``]``.
 354
 355    statement
 356        A single instruction to be executed at :term:`run-time`.  See also
 357        :term:`directive`.
 358
 359    statement block
 360        A group of :term:`statement`\s bundled up together between braces
 361        ``{...}``, which are then treated as a single unit -- as if they
 362        were only one statement.  They commonly appear in loops and
 363        conditions.
 364
 365    story file
 366        A binary file which is the output of the :term:`compiler` and can
 367        be played through the use of an :term:`interpreter` (also known as
 368        Z-code file or game file).  The format of story files is standard
 369        and platform-independent.
 370
 371    Strict mode
 372        An option which causes the :term:`compiler` to include extra code
 373        into the story file, thus making it easier to detect certain design
 374        mistakes while a game is being played.
 375
 376    string
 377        A piece of text between double quotes "...", to be displayed for
 378        the player's benefit at :term:`run-time`.
 379
 380    switch
 381        1. an optional keyword or symbol to operate special features of the
 382           compiler.
 383        2. a statement which decides among different paths of execution
 384           according to the value of an expression.
 385
 386    text file
 387        A computer file containing words and phrases which a human can
 388        read.
 389
 390    true
 391        A logical state which is the opposite of :term:`false`, represented
 392        by any value other than zero (typically 1).
 393
 394    variable
 395        A named value which can change during :term:`run-time`.  It must be
 396        declared before use, either as a ``Global`` variable (available to
 397        any routine within the game), or as a local variable (part of one
 398        specific routine and usable by that routine alone).  Variables have
 399        a name and a value; it's the value which is capable of change, not
 400        the name.  Object :term:`properties` behave as variables.
 401
 402    Z-code file
 403        See :term:`story file`.
 404
 405    Z-machine
 406        A virtual machine (an imaginary computer simulated by the
 407        :term:`interpreter`) on which story files run.  Z stands for
 408        "Zork", the first ever Infocom title.