appendices/g.rst

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