From fbbce8f30ba93c89681b3b69e9060a5d044c084c Mon Sep 17 00:00:00 2001 From: Glenn Hutchings Date: Sat, 9 Apr 2016 21:28:52 +0100 Subject: [PATCH] Add some appendices. --- appendices/a.rst | 161 ++++++++++++++++++ appendices/b.rst | 26 +++ appendices/g.rst | 399 +++++++++++++++++++++++++++++++++++++++++++++ examples/Heidi.txt | 59 +++++++ index.rst | 7 + 5 files changed, 652 insertions(+) create mode 100644 appendices/a.rst create mode 100644 appendices/b.rst create mode 100644 appendices/g.rst create mode 100644 examples/Heidi.txt diff --git a/appendices/a.rst b/appendices/a.rst new file mode 100644 index 0000000..3934f55 --- /dev/null +++ b/appendices/a.rst @@ -0,0 +1,161 @@ +====================================== + 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. diff --git a/appendices/b.rst b/appendices/b.rst new file mode 100644 index 0000000..a479f62 --- /dev/null +++ b/appendices/b.rst @@ -0,0 +1,26 @@ +============================= + Appendix B -- "Heidi" story +============================= + +Heidi in the Forest is our first -- and simplest -- game. We describe it in +three chapters: "Heidi: our first Inform game" on page 33, "Reviewing the +basics" on page 49 and "Heidi revisited" on page 59. Here is a run-time +transcript, and then the original and extended source files. + +Transcript of play +================== + +.. literalinclude:: /examples/Heidi.txt + :language: transcript + +Game source code -- original version +==================================== + +.. literalinclude:: /examples/Heidi.inf + :language: inform6 + +Game source code -- revisited +============================= + +.. literalinclude:: /examples/HeidiPlus.inf + :language: inform6 diff --git a/appendices/g.rst b/appendices/g.rst new file mode 100644 index 0000000..918b42d --- /dev/null +++ b/appendices/g.rst @@ -0,0 +1,399 @@ +======================== + 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. diff --git a/examples/Heidi.txt b/examples/Heidi.txt new file mode 100644 index 0000000..a33641b --- /dev/null +++ b/examples/Heidi.txt @@ -0,0 +1,59 @@ +Heidi +A simple Inform example +by Roger Firth and Sonja Kesserich. +Release 1 / Serial number 040804 / Inform v6.30 Library 6/11 SD + +In front of a cottage +You stand outside a cottage. The forest stretches east. + +>VERBOSE +Heidi is now in its "verbose" mode, which always gives long descriptions of +locations (even if you've been there before). + +>GO EAST + +Deep in the forest +Through the dense foliage, you glimpse a building to the west. A track heads to the +northeast. + +You can see a baby bird here. + +>EXAMINE THE BIRD +Too young to fly, the nestling tweets helplessly. + +>TAKE BIRD +Taken. + +>NE + +A forest clearing +A tall sycamore stands in the middle of this clearing. The path winds southwest +through the trees. + +You can see a bird's nest (which is empty) here. + +>PUT BIRD IN NEST +You put the baby bird into the bird's nest. + +>EXAMINE THE NEST +The nest is carefully woven of twigs and moss. + +>TAKE NEST +Taken. + +>UP + +At the top of the tree +You cling precariously to the trunk. + +You can see a wide firm bough here. + +>PUT NEST ON BRANCH +You put the bird's nest on the wide firm bough. + + *** You have won *** + +In that game you scored 0 out of a possible 0, in 10 turns. + +Would you like to RESTART, RESTORE a saved game or QUIT? +> QUIT diff --git a/index.rst b/index.rst index 5dcfe67..a9d678e 100644 --- a/index.rst +++ b/index.rst @@ -19,6 +19,13 @@ Contents: chapters/* +Appendices: + +.. toctree:: + :glob: + + appendices/* + Indices: * :ref:`genindex` -- 2.31.1