Doe's Inform 6 Primer

I'd call it a faq except no one asked me frequently enough. ;-)



This primer is still under construction.

In writing this "primer" I focused on what I found "hardest" when learning Inform. Based on the premise that what I found tricky, others might too. However, I really had to cast my mind back, because I know Inform fairly well now. Also, when I started learning it I already knew how to program, so I didn't start from ground zero. In other words, this doesn't cover the basics of how to program and/or more than a few basics of Inform (read the Inform Designer's Manual and the Inform Beginner's Guide), but newbies may still get something out of it.

To make this primer more useful, I decided to add homework. One or more assignments included after every "lesson." The solutions, working mini-games with source code, are included as zip files for you to look at after you do your homework.

All complex code has been tested.


Updated May 2002. Note that not everything has been rewritten, only parts here and there. Also some sections are still unwritten.



Contents:
  1. A, B (O), C - Inform's Basic Building Blocks.
    Actions (Verbs), objects (nouns), and the Inform compiler/library. Plus game code layout
    and an attribute summary.
  2. True or false, but, thankfully, no essay.
    How Inform routines return true or false.
  3. Big "bad" table.
    The order in which Inform routines are processed.
  4. Stupid Initialise tricks.
    Setting the location, changing the player (adding body parts), starting the player on something, beginning with
    a quote, creating a timed game, and skipping the banner.
  5. Attributes and properties -- apples and oranges.
    The difference between attributes and properties, global/local properties, and avoiding vile zero errors from hell.
  6. 1, 2, 3, 4 - Before, After, React_After, React_Before
    Using the before, after, react_after, and react_before routines to affect actions.
  7. Verbalizing without conjugating.
    Creating new verbs and verbsub routines.
  8. Multiply the power, multiply the fun.
    Arrays, array properties, and found_in.
  9. Attending to classes.
    Creating classes, testing class membership, non-additive/additive properties, the superclass operator, and "self."
  10. Skip a Grade to Advanced Inform Programming
    PlayerTo, parse_name, GamePreRoutine, ChooseObjects, etc.


  1. A, B (O), C - Inform's Basic Building Blocks.

    Grammar & the Parser

    I wasn't really going to cover Inform basics, but then I decided I could probably write an introduction as well (or as badly) as anyone else ;-). Please bear with me, grammar is not my forte.

    Inform is very "grammar-like." That is because the core of Inform is its parser.

    >ask the troll about the sword

    >hit the troll

    >cut the troll with the sword

    >give the lantern to the troll

    This makes sense if you look at typical player input. According to Webster's, parse means to:  1. resolve (as a sentence) into component parts and speech and describe them grammatically. 3. to give a grammatical description of a word or a group of words.

    The Inform parser takes player input, which is usually entered as a simple sentence, and breaks it down into parts of speech. These parts are then used to enable the player to play the game. (Note that old-fashioned parsers couldn't handle complete sentences, having difficulty with adjectives, articles, and prepositions. Also note that player input is usually entered without periods.)

    > ask the troll about the sword

    > hit the troll

    > cut the troll with the sword

    > give the lantern to the troll

    The most meaningful parts of speech for Inform are verbs and nouns (both direct objects and indirect objects). Because Inform handles prepositions and articles fairly automatically, usually a game author doesn't need to worry about them except in special cases 1 .

    So Inform is centered around actions (verbs) and objects (nouns). This is reflected in the three "include files" that must be included in every game 2 .

    parser.h   <- the parser
    grammar.h  <- grammar definitions (mainly verbs)
    verblib.h  <- verb programming routines that perform the actual actions
    
    1 Prepositions connection to verbs can be defined when you create new verbs or extend existing verbs. And new articles, such as some, can be defined for plural nouns and other objects that require special articles.
    2 The parser is really in parser m .h, and the verb routines in verblib m .h. But parser.h is the file that must be included and it, in turn, loads parserm.h. Ditto with verblib.h and verblibm.h.

    A - Actions (Verbs)

    > ask the troll about the sword

    > hit the troll

    > cut the troll with the sword

    > give the lantern to the troll

    Naturally, when players enter a verb they expect some action to result, even if it's only a printed response.

    >ask the troll about the sword
    There is no reply.

    >hit the troll
    Violence isn't the answer to this one.

    >Cut the troll with the sword.
    You aren't holding the sword.

    >give the lantern to the troll
    Done.
    (removes lantern from player's inventory)

    At a rough count, Inform has approximately 75 built-in verbs. And that does not count the "meta" actions/verbs that save/restart a game, etc. Each verb also has synonyms, such as "throw" and "discard" for "drop." Verbs are not only defined, but also have accompanying programming routines that respond to player input.

    Many of the game (non-meta) verbs will just print a default message, but some also actually do something, such as adding/removing something to/from the player's inventory (what the player is carrying). So verbs become game actions.

    It is quite possible for an author to write an Inform game just using the verbs that are already pre-defined. However, it is also pretty easy to create new verbs and/or change existing verbs if one needs to ( Verbalizing without Conjugating).

    B (O) - Objects (Nouns)

    >ask the troll about the sword

    >hit the troll

    >cut the troll with the sword

    >give the lantern to the troll

    Just as players expect entering a verb to result in some action, they expect to be able to interact with the nouns in the game, not have them be just nouns in a sentence. They expect to be able to examine, touch, hit, talk to the troll -- to interact with him in all the ways that they can think of and that the game allows. They also expect to be able to pick up, drop, and use the lantern and sword.

    Games attempt to "simulate" the real world (even when it is a fantasy world). This means the player should be able to:  move from room to room, take/drop/manipulate small objects, and interact with characters. To accomplish these complicated actions, nouns -- like verbs -- must also have accompanying programming. So nouns become game objects.

    In contrast to its 75+ built-in verbs, Inform only has two built-in objects:  the player object (to enable the player to take/drop things) and the dark object (for the absence of light to be handled in a standard way).

    So 90% of an Inform game author's writing consists of creating/designing objects.

    Objects can have true/false characteristics called attributes, and variables called properties (which, since they are variable, can be strings, numbers, or routines -- Attributes and Properties -- Apples and Oranges ).

    Using attributes, objects come in basically four flavors:  locations ("rooms"; inside or outside -- they usually have the light attribute), non-takeable objects (objects that are too big to take or are included just to add color -- they have the static or scenery attribute), takeable objects, and "live" objects (people, animals, insects, robots, etc. -- they have the animate attribute).

    Object string properties describe objects:  name, initial, describe, and description. And object routine properties, usually before and after, interact with verb routines to accomplish complicated actions that are beyond the scope of the standard verb responses.

    This primer doesn't really cover objects in detail, so refer to the DM (Inform Designer's Manual).

    C - Inform Compiler/Library

    Inform actually consists of two parts:  the Inform compiler and the Inform library. When you write a game, you create/write plain text 3 files that include the Inform library and are then compiled by the Inform compiler.

    3 Plain text files are often referred to as ASCII (American Standard Code for Information Interchange) files. They contain just the A-Z and 0-9 characters, along with a few others, but no special no word processing formating characters, so a text editor is needed.

    Inform Compiler

    The Inform compiler, Inform.exe, is an executable file. This means that entering "Inform" at the prompt (Dos, Mac, etc.) will run (execute) the program. "Inform yourgamename" compiles your game. Compiling takes the plain text files you have written and turns them into one low-level machine-language file. This compiled .z5 or .z8 file is read by a game interpreter (Jzip, Frotz, WinFrotz, etc.) when players play your game.

    The compiler is "hardcoded " (pre-compiled with the C language). It is not alterable by Inform game authors (yes, it could be altered by an advanced programmer, but it is not meant to be). Read the copyright notice at the front of the Inform Designer's Manual.

    Inform Libary

    The Inform library consists of eight text files that are called "include files." They are called that because when you write your game you also include them. Then when your game is compiled, they are loaded along with what you have written, and both are combined together to create the game. These files (or replacements) must be included, as an Inform game will not work without them.

    The Inform library include files are plain text, so you can read them and alter them. However, when making changes/additions to the Inform library, the rule of thumb is to make those changes/additions in your own writing, because: 

    1. according to the Inform copyright notice, if you do change the Inform library you may not distribute that changed library to anyone else
    2. the Inform library already provides all kinds of "hooks" that allow you to make changes/additions at the relevant points
    3. for standardization purposes it is a good idea not to change the library itself -- i.e., if you ask other people for help with a programming problem, they won't know about any changes you made to the library, so they won't be able to answer questions about problems that may have resulted from your changes
    4. unless you know Inform very well, it's not smart to fool with the library itself, because it contains complicated programming and variables that are used in numerous places, so if you change one thing here, you may inadvertently change something else there, without realizing it.


    Game Code Layout

    Initialise Routine

    Each Inform game has an Initialise Routine that sets the player's beginning location and inventory. It also usually prints the banner (game title, author name, and Inform compiler and library versions) and an introduction to the game (Stupid Initialise Tricks).

    Include Files

    Code is the name for the plain text used in programming. When you write a game you are essentially programming, although the Inform library does a great deal of the necessary programming for you already.

    As stated, the Inform library consists of eight include files.

    parser.h   - Defines the Inform library version and fake actions. 
                 Includes parserm.h.
    parserm.h  - Declares the player and the dark objects and contains the parser.
                 Includes linklpa.h and english.h (language.h*).
    linklpa.h  - Defines the global attributes and properties.
    linklv.h   - Defines other global variables that are used by the library 
                 in conjunction with Inform compiler.
    english.h  - Contains the standard library messages (responses to verbs
                 and other messages). english.h will be called something else
                 if the game is written in another language other than English.*
    grammar.h  - Defines the verbs and links them to the verb routines that will
                 be performed when the verbs are used.
    verblib.h  - Defines some constants (that relate to actions).
                 Includes verblibm.h.
    verblibm.h - Declares the verb routines and contains other supporting routines. 
                 Includes linklpa.h and linklv.h.
    
    Because several include files include other include files, you only need to include three in your code:  parser.h, grammar.h, and verblib.h. To include one, use the following type of statement.

    #include "parser"
    
    The ".h" can be dropped from (or included in) in the statement.

    Where these files are included in your code is very important.

    Basic Layout

    The basic layout is:

    Inform compiler switches
    Constant Story
    Constant Headline
    #include "parser"
    #include "verblib"
    Initialise routine
    game objects
    #include "grammar"

    Constant Story and Constant Headline are both used in the game banner. Story is usually the game title and Headline is usually the author's name.
    !----------------------------------------------------------------------------
    ! Globals
    !----------------------------------------------------------------------------
    
    ! Example Troll I.
    
    Switches xdv5s;
    
    Constant Story "^^Troll Example I^";
    Constant Headline "by Doe^";
    
    #include "parser";
    #include "verblib";
    
    !----------------------------------------------------------------------------
    ! Initialization Routine
    !----------------------------------------------------------------------------
    
    [ Initialise;
      location = cave;
      move sword to player;
      "^^You don't know how you got here...";
    ];
    
    !----------------------------------------------------------------------------
    ! Objects
    !----------------------------------------------------------------------------
    
    Object sword "sword"
     with name "sword" "blade" "knife",
     description "It appears to be an ordinary sword.";
    
    Object cave "Cave"
      has light
      with description "You are high, vaulting cave. The far reaches are in
                        darkness.";
    
    Object -> troll "troll"
     has animate
     with name "troll" "big" "ugly" "guy",
     description "He's just as big, ugly, and dumb-looking as you always thought
                 a troll would be.";
    
    !----------------------------------------------------------------------------
    ! Verbs
    !----------------------------------------------------------------------------
    
    #include "grammar";
    
    Layout with New Verbs

    When you create new verbs or extend existing verbs, their definitions/routines go after grammar is included. If you replace an existing verb routine, the replacement statement goes after the parser is included but before verblib is included.

    Inform compiler switches
    Constant Story
    Constant Headline
    #include "parser"
    replacement statements
    #include "verblib"
    Initialise routine
    game objects
    #include "grammar"
    new/extended verbs
    !----------------------------------------------------------------------------
    ! Globals
    !----------------------------------------------------------------------------
    
    ! Example Troll II.
    
    Switches xdv5s;
    
    Constant Story "^^Troll Example II^";
    Constant Headline "by Doe^";
    
    #include "parser";
    
    Replace CutSub;
    
    #include "verblib";
    
    !----------------------------------------------------------------------------
    ! Initialization Routine
    !----------------------------------------------------------------------------
    
    [ Initialise;
      location = cave;
      move cloak to player;
      move sword to player;
      move lantern to player;
      "^^You don't know how you got here...";
    ];
    
    !----------------------------------------------------------------------------
    ! Objects
    !----------------------------------------------------------------------------
    
    Object cloak "cloak"
     has clothing worn
     with name "cloak" "cape",
     description "It is a plain black cloak, but it swishes dramatically.",
     before
     [; Attack : "Then you'd have nothing to swish."; ];
    
    Object sword "sword"
     with name "sword" "blade" "knife",
     description "It appears to be an ordinary sword.";
    
    Object lantern "lantern"
     has light
     with name "lantern" "light",
     description "It looks strangely familiar.",
     before
     [; Attack : "If you broke the lantern you would be without light."; ];
    
    Object cave "Cave"
      with description "You are high, vaulting cave. The far reaches are in
                        darkness.";
    
    Object -> troll "troll"
     has animate
     with name "troll" "big" "ugly" "guy",
     description "He's just as big, ugly, and dumb-looking as you always thought
                 a troll would be.";
    
    !----------------------------------------------------------------------------
    ! Verbs
    !----------------------------------------------------------------------------
    
    #include "grammar";
    
    Extend 'cut' replace
       * noun 'with' held ->Cut;
    
    Extend 'attack'
       * noun 'with' held ->Cut;
    
    Verb 'swish' 'swirl'
       *                  ->Swish
       * noun             ->Swish;
    
    [ CutSub;
      if ((second ~= sword) || (noun == sword)) "Huh?";
      <<Attack noun>>
    ];
    
    [ SwishSub;
      if ((noun == 0) || (noun ~= cloak))
         "Interesting, didn't realize you had that preference.";
      if (cloak hasnt worn)
         "But you aren't wearing the cloak.";
      "You swish the cloak dramatically. Ahhh.";
    ];
    
    
    Attribute Summary

    These tables are summaries, for more complete explanations see the DM. They are also not arranged alphabetically, but by the four object "types" and by attribute importance. Note that some attributes may be duplicated in the various tables because they can be used more than one way. Also these are not the only ways that attributes can be used, just the most common ways.

    Locations
    Attribute Description
    light Location that has light. If the location doesn't have light, doesn't contain an object that provides light, or the player isn't carrying an object that provides light, then the player will be in the dark (actually in thedark object).
    visited Location that has been visited before. The Inform library automatically assigns visited to a location when it is first visited (after the first look which is preformed automatically). Visited rooms may give an abbreviated description the next time look is used.
    scored Location which will add to the score when visited for the first time.


    Non-Takeable Objects
    Attribute Description
    scenery Object which will not show up in the room description, but it can be examined and manipulated (touched, etc.) if properties are included for that. When player attempts to take object, "That's/They're hardly portable.", will be printed. Player is also "unable" to push, pull, or turn it.
    static Object which will show up in the room description, but when the player attempts to take it, "That's/They're fixed in place.", will be printed. The same message is also printed if the player attempts to remove, push, pull, or turn it.


    Objects which do not have the scenery or static attribute, and are not characters or rooms, are usually "takeable objects." They usually (except for concealed) will show up in room descriptions and the player can take them (if their before routines allow it).

    Takeable/Non-Takeable Objects
    Attribute Description
    concealed Object which will not show up in the room description, but once the player knows it is there, it can be referred to and taken (if its before routine allows it).
    moved Object that has been or is being held by the player. The Inform library automatically assigns moved to an object when it is taken by the player (in the player's inventory). An object that has not been moved and has an initial property, and its initial description will be printed after the room description.
    light Object that provides light, such as a lantern.
    switchable Object that can be switched on or off.
    on A switchable object that is on. The Inform library automatically assigns on to an object when the object is switched on (and on is made false when the object is switched off).
    talkable Object that the player can talk to, such as a microphone. However, a talkable object does not have a life routine so it will not respond to other character interaction (see "live" objects).
    edible Object that can be eaten, thus removed from the game.
    clothing Object that can be worn by the player.
    worn Object that is currently being worn by the player. Usually used with clothing.
    proper Object which will be referred to by its name without a preceeding the/a ("proper name").
    pluralname Pronouns referring to this object will be plural -- them or some.
    scored Object which will add to the score when picked up for the first time.


    Supporters/Containers
    Attribute Description
    supporter Object that hold things and is considered to be a "flat-surface." The objects it holds will be described as being "on" it.
    container Object that can hold things and is considered to have sides and a lid (although they are not explicitly stated). The objects it holds will be described as being "in" it.
    enterable A supporter or container that the player can enter, but only if it is "on the floor" (not carried and not in/on something else).
    openable Used with container, a container that can be opened (if it is not locked).
    open Used with container and openable, an openable container that is currently open. The Inform library automatically assigns open to an object when it is opened (and open is made false when it is closed).
    lockable Used with container, a container that can be locked.
    locked Used with container and locked, a lockable container that is currently locked (and closed -- not open). If the object has the with_key property, the object designated by with_key can open it.
    transparent Used with container, a container that is transparent. The contents of a transparent container will be visible when it is closed. Also when the player is inside a closed transparent container they will be able to see the surrounding room. Inside a closed regular container, they will only be able to see the inside of the container.


    Doors
    Attribute Description
    supporter Object that hold things and is considered to be a "flat-surface." The objects it holds will be described as being "on" it.
    container Object that can hold things and is considered to have sides and a lid (although they are not explicitly stated). The objects it holds will be described as being "in" it.
    enterable A supporter or container that the player can enter, but only if it is "on the floor" (not carried and not in/on something else).
    openable Used with container, a container that can be opened (if it is not locked).
    open Used with container and openable, an openable container that is currently open. The Inform library automatically assigns open to an object when it is opened (and open is made false when it is closed).
    lockable Used with container, a container that can be locked.
    locked Used with container and locked, a lockable container that is currently locked (and closed -- not open). If the object has the with_key property, the object designed by with_key can open it.
    transparent Used with container, a container that is transparent. The contents of a transparent container will be visible when it is closed. Also when the player is inside a closed transparent container they will be able to see the surrounding room. Inside a closed regular container, they will only be able to see the inside of the container.


    "Live" Objects
    Attribute Description
    animate Only objects with the animate attribute can have the life property. The life property routine can provide responses for:  Ask, Answer, Tell, Attack, ThrowAt, Kiss, Show, Give, Order, and WakeOther. In other words, an animate object can be conversed with and interacted with as if is a "live" character. (Note that the talkable attribute also allows conversation.)
    male Pronouns referring to this object will be masculine -- him. Usually used with animate.
    female Pronouns referring to this object will be feminine -- her. Usually used with animate.
    neuter Pronouns referring to this object will be gender neutral - it. Usually used with animate.
    proper Used with animate, character which will be referred by his/her/its "proper" name without a preceeded the/a -- Jack and Jill, not the boy and the girl.
    transparent Used with animate, everything the character is carrying can be referrable to by the player, although the held object descriptions are not automatically printed with the character description.


    There is a lot more to learning, Inform, of course, such as using -> to place an object inside another object, but this covers its basic building blocks. The rest of this primer focuses only on the major road blocks you may encounter on the way to learning Inform.



Next Page - Sections 2-4 and First Homework Assignment

Top of Page    Infotips    Interactive Fiction Main Page

If this primer has been of any use to you I wouldn't mind hearing about it.
If you find any factual errors in this primer, I also wouldn't mind hearing about it.