appendices/g.rst

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