Guide to Inform Library Contributions

Imperfect and incomplete, but an attempt to record what library contributions already exist for dealing with common inform problems. Appended are my notes if I have myself used the library in question. Because this list depends mostly on what I use and what I see discussed on r*if, it's far from perfect. If you have a library you use a lot (preferably one you didn't write yourself), feel free to drop me a review of it.

For a full list of library contributions, see the Inform site. Even more up-to-date, though perhaps not as easy to browse, are the indices of Inform and Glulx contributions, at the ifarchive.

For solutions to commonly-encountered problems that may not deserve a whole library to correct, see Roger Firth's Inform FAQ page. If your code is producing bugs that you can't explain, it may also be worth checking to see if it is a bug in the library itself: see the Inform patch site.

The list is divided into the following categories:

Utilities: String handling, boolean variables, and other fun things that can be used just about anywhere.
Debugging: Additional verbs and routines that will perform useful debugging functions.
Display: Menuing and display libraries.

Clothing: Levels and layers of clothes.
NPC Control: Conversation and movement libraries for non-player characters.
Map and Geography: Items to facilitate movement for the player, draw maps, unlock doors, and more.

Systems: Covers systems of libraries designed to work together. (Currently, the Onyx Ring Library set.)
Replacement Libraries: Platypus, and specially Platypus-compatible libraries.

Re Scoring: the "Use" constant represents how useful I consider the library addition to be. Items scored a 9 or a 10 are things I use in every, or almost every, game, and consider part of a standard package. The more abstruse and particular the contents are, the closer it will come to a 1. Likewise, if a library requires a large number of special fixes and so on from an author, its score will drop as well.

The "Power" constant represents how hard this would be to write on your own. Note that this is a particularly subjective call on my part, but I have attempted to take into account the obscurity of the coding tricks involved, the quantity and complexity of the code, the amount of testing required to poke it into behaving itself, etc.

The "Gl" column indicates whether the library functions properly with Glulx. N means it will need adjustments, Y means that it needs none or the adjustments have already been made, and no entry means I haven't checked.


Utilities

File NameAuthor Use Pow Gl Comments
pname.zip Neil Cerutti 10 6 -- A great contribution to avoid the disambiguation headaches of different objects sharing dictionary words. It lets you forget about writing complex parse_name routines by adding a simple pname property, which works pretty much like your normal name property, with a few extras. Flexible and powerful. [Review courtesy of Sonja Kesserich.]
adname.h Andrew Clover 10 5 -- Creates a distinction between adjectives and nouns for better parsing. Pretty damn useful, and it's hard to see how inform gets along without it. A tiny and essential library. [Review courtesy of Nick Montfort.]
newflags.h Adam Cadre / Fredrik Ramsberg 8 3 -- Manages Boolean flags, saving space over using a whole bunch of global variables. Based on Adam Cadre's flags.h, but with improvements to the power-of-two function and programmer's interface provided by Fredrik Ramsberg.
Hints.h L. Ross Raszewski 8 7 -- Object oriented hint-menu-making system (which itself relies on domenu.h, altmenu.h, utility.h). Sean Barrett recommends.
istring.h L. Ross Raszewski 4 9 -- Does string manipulation of a kind that Inform does not have natively built in, concatenating things nicely and so on. This may seem entirely irrelevant to you, and, indeed, in most cases will be totally useless. People doing heavy-duty prose generation may be very grateful, however.
yesno.h L. Ross Raszewski 6 4 -- An alternative to the YesOrNo() routine, this extension allows the player to respond either with a yes/no answer or with some other command entirely. Small and elegant.


Debugging

File NameAuthor Use Pow Gl Comments
checkout.h Roger Firth 9 3 -- Provides a debugging verb that will go through all the rooms of your game and make sure that two-way connections are implemented. (Eg, if room x is east of room y, it will check that room y is also west of room x.) An exception list is provided in case you are making asymmetric paths on purpose, rather than as the result of late-night dyslexia (a frequent problem for me, personally.)

This library doesn't find out anything that you couldn't find out yourself with extensive beta-testing and so on, but it does provide a quick and convenient way of auditing yourself. My only gripe: if you have a successful checkout, the debugging verb prints nothing at all.


Display

File NameAuthor Use Pow Gl Comments
GWindows.zip L. Ross Raszewski 7 9 Y This library (or set of libraries, really, but they are tightly coordinated) provides a much-easier, object-oriented way to deal with the mysteries of Glulx window creation and maintenance. Windows on the screen are represented by actual objects, which can remember (by assigning properties) what their size and image contents are supposed to be -- which eliminates many of the traditional save/restore/undo maintenance problems.

The system also provides a wide range of automatic widgets, including pop-up windows, automatically self-generating menus (with hyperlinked contents), and so on. It is accompanied by generous documentation in html, and lengthy (perhaps so large as to be daunting) example code.

There are a few objections and feature-lacks, some of which are not the author's fault. So far, for instance, there isn't a standard way to tell graphics window to center a picture; graphics windows automatically scale. The author has stated that he is philosophically opposed to graphics windows whose contents do not scale, but some of us have other ambitions.

The pop-up windows appear somewhat strange in MacGlulxe, because even when the pop-up window is in its hidden state, there is a thin outlined bar. This is arguably the fault of MacGlulxe and not of the library.

A few properties and routine names are things that might reasonably conflict with things you already have defined (e.g., "color" and "update"). You may or may not find this annoying.

Finally, this is not a perfectly simple library to use, and in particular it takes a little while to understand how to set up the tree of window objects. It is also possible to produce a configuration that will crash the terp at start-up. Nonetheless, this is much, much easier to handle than making your own Glulx windows -- especially if you are likely to be changing your mind periodically and wanting to modify the UI.

I would strongly recommend this to anyone planning to do anything with Glulx UI more complex than a standard status-line-and-text-window.

style.h Chris Klimas 9 2 N This one's trivial, but useful: it provides handy routines to allow you to, for instance, print (b) "foo" and have foo come out in boldface. Defining these yourself is not exactly a long day's work, but grabbing the file and including it is perhaps even shorter.


Clothing

File NameAuthor Use Pow Gl Comments
clothes.h Denis Moskowitz
Timothy Groves
4 5 Y A modified version of Denis Moskowitz's Clothing.h library. The original version provided functionality for keeping track of several layers and areas of clothing (for example, a jacket over a shirt, worn with pants) and would print error messages if you tried to wear things in the wrong order (putting on the shirt while wearing the jacket, for instance.)

Timothy Groves' extension leaves the Clothes class in place, but adds several routines to do things like describe what another character is wearing (showing only the layers of clothing that are visible on the outside).

This extension is obviously only useful if you want to provide for numerous types of clothing and states of dress in your game. It also does not (currently) deal with the problem that some clothes cover more than one "area" -- such as a dress that goes on over both the pants and shirt.


NPC Control

File NameAuthor Use Pow Gl Comments
phtalkoo.h Adam Cadre
David Glasser
8 5 -- One of the standard approaches to conversation menu handling seems to be through this library. I personally never use it, but this is because I have my own little ways, instead. But I gather it's very useful.
Info.h Jesse Burneko 8 5 -- Provides topic objects for for doing ASK/TELL conversations with NPCs and for consulting texts. This gets you the author away from fiddling with consult_word and other hackish frights to make your encyclopedia and/or Encyclopedia Brown implementation work. Sean Barrett recommends.
AskTellOrder.h Irene Callaci 5 3 N A routine for reparsing the player's input, converting input of the form "ASK/TELL THE NPC TO DO SOMETHING" into "NPC, DO SOMETHING". This library relies on BeforeParsing, so you will have to be careful if you are already using BeforeParsing for other purposes. It is also Glulx incompatible at the moment; you'll have to change a few constants in order to get it to work with the new wordsize.
moveclass.h Neil Brown
Alan Trewartha
Matthew Russotto
3 9 Y [Review courtesy of Sonja Kesserich.]: The library contribution that I know includes random movement as an option is Moveclass.h, which must use the extension follower.h to have a "follow NPC" verb. Moveclass.h does not have all the extended features of the NPC_Engine (such a asking NPCs about where other NPCs are, or looking through windows) but I've found it easy to use and convenient for movement purposes.

See also the manual.

npc_engine.zip Volker Lanz 2 10 -- A mammoth and fantastically powerful engine that allows you to move NPCs along pre-defined or dynamically selected paths. There are entry points to indicate what they should do should they be stopped by a closed or locked door. Also implements a FOLLOW verb, and allows the player to ask NPCs when and where they have last seen each other, and looks after such things as seeing an NPC passing through a room or seeing an NPC through a window to another location.

Drawbacks and liabilities: if you have numerous characters moving around autonomously at the same time, there is a noticeable performance hit. Moreover, use of the library requires some customization of the locations in the game to ensure that the NPCs will not trigger any inappropriate announcements (by, for instance, attempting to go in a direction which ordinarily prints a string.)

rap11.zip Nate Cull 2 8 -- RAP stands for "Reactive Agent Planner": this is an engine designed to handle goal-oriented NPC behavior. Plans can be made up of subgoals ('find the foo, take it, find the bar, take that, give them both to Mr. Baz...'), and a path-finding algorithm (without some of the fancy features of NPC_Engine) is included. NPC planning takes into account changes in the environment, so that if a plan is invalidated partway through (because the player moves a needed object, for instance) the NPC can react appropriately, rather than mindlessly pursuing a now-invalid script.

This is potentially extremely powerful in its ramifications, but it is a bit let down by the demonstration game. The bad news is that a lot of the routines that one would expect to need -- routines to let characters search rooms, unlock doors, open containers, take objects in a sensible way, etc -- are not provided in any form. The routines that are provided, to find objects in the game map, are somewhat underpowered and simplistic; they assume, for instance, that all objects available to the NPC will be lying around on the floor (or, as a special case, owned by the PC), rather than being nested inside containers or supporters. Clearly Nate expected to come back and improve on these, but didn't get around to doing so.

Also, as the notes for RAP point out, the engine assumes that the NPC knows everything there is to know about the game world; there is no discrepancy between NPC knowledge and game state, so that an NPC will unerringly go directly to the item it desires, for instance, without any intervening searching, whether or not it has ever seen that item before.

The good news is that RAP is so open-ended that it could be taught to do all of these things and, presumably, a great deal more; it presumes very little about the world model being used by the game author, and one is free to fill things in. Extensions to the RAP library could usefully be added by other authors, perhaps building up a system of routines that would ultimately provide quite considerable power.

Another intriguing fact: a version of this library exists for TADS.


Movement and Geography

File NameAuthor Use Pow Gl Comments
smartcantgo.h Roger Firth 9 3 Y Small but elegant and extremely useful, this library allows you to replace the cant_go message with one that tells the player what exits are available. Warning: if you have two exits that functionally point to the same place (eg, n_to and out_to both lead to Outside_House, for instance), these exits will be listed as though they were two separate exits ("You can go north or out."). I have occasionally found it useful to hack the library so that it ignores in_to and out_to, but this is not a universal solution.

Still, very nice.

dirs_2.h Gunther Schmidl 9 2 -- Adds verbs to the game to provide for an EXITS verb that will list all the viable exits from a room. Trivial, but if you want that functionality, rather nice.
GoNeighbour.h Alan Trewartha 8 4 -- Allows movement to adjacent rooms by commands such as >GO TO KITCHEN. Allows the author to specify on a case-by-case basis whether an unvisited room may be referred to by name. Note: this isn't a full-bore path-finder; it allows the player only to go into rooms that are accessible from the room they are in, and will not plot a course halfway across the game map.

A nice effect is to name the room at the top of a staircase "upstairs", so that >GO UPSTAIRS will work, for instance. A nice additional effect, it now occurs to me, would be the ability to do >PUSH WHEELBARROW INTO ROSE GARDEN. (While we're at it.)

outofrch.h Marnie Parker 6 5 -- Allows you to restrict the player's reach depending on where he is.

[Review courtesy of Joe Mason.]: Doe's outofreach.h is great - it's sort of the opposite of scoper.h (in the Movement & Geography category) - it lets you make a simple list of what objects in a room can be reached from other objects, for things like standing on chairs and in vehicles and such. I actually have some enhancements, which I'll release once my WIP which uses them is done.

Locksmith.h Emily Short 3 1 -- A small utility that labels all keys after they have been used so that the inventory prints, for instance, "A silver key (which unlocks the hope chest)". After a key's purpose has been identified, that key is always automatically used for opening and closing the appropriate object; otherwise, when the player does >UNLOCK THING without specifying a key, the game will try any unidentified key first. (If there is more than one unidentified key in the player's possession, he will be asked to disambiguate as usual.) If the player attempts to unlock an item whose key he has identified once but no longer possesses, he will be reminded of where the key is.

Also provides a debugging verb UNLOCKALL which unlocks all the locked items in a game instantly.

scoper.h Daniel Barkalow ? 6 -- I passionately hate dealing with scope-hacks in Inform. Daniel Barkalow's library provides functionality to put items in another room into scope (for instance, to provide the impression of a large room in which distant objects are visible but cannot be touched.)

What I wanted it for was a slight variation on what it was built for, so I need to reserve judgement on scoring for the moment. It does barf up some warnings at compile-time; this can be dealt with by removing a couple of spare local variables. An aesthetic annoyance only.


Systematic Sets of Library Modules

File NameAuthor Use Pow Gl Comments
ORLib modules Jim Fisher -- -- -- At the moment, I haven't had time to go through these and test them myself. I would be eager to hear about people's experiences using them. A few specifics follow; here is Howard Sherman's testimonial to the set as a whole:

They ROCK!

Implementation of some key features are made simple. A lot of code I wrote "by hand" was neatly included in the OR libraries as well as lots of things I was prepared to program "the hard way" myself. The excellent documentation and continuous attention to detail and frequent updates really shows Jim cares!

ORExamWithContents Jim Fisher 9 3 -- [Review courtesy of Stephen Norris.] Automatically includes the contents of containers and supporters. Very useful to avoid tedious code to describe them.
OREnglish Jim Fisher 7 5 -- [Review courtesy of Stephen Norris.] Rewrites all the messages to be actor independent and to appear in either present or past tense. Very complete, and very handy.

Also included in the library are routines for doing the same in one's own messages, which allows objects to be manipulated by NPC's with a minimum of effort.

ORNPC_doverb Jim Fisher 4 7 -- [Review courtesy of Stephen Norris.] In my opinion, the most useful of the modules! It allows a NPC to do any action with simply person.doVerb(##Action, noun, second);. Includes calling before & after routines - essentially duplicates what ; would do, but for any NPC!
ORNPC_movement Jim Fisher 4 ? -- [Review courtesy of Stephen Norris.] A complete replacement for the moveclass.h module.
ORNPC_Converse & ORNPC_AskTellLearn Jim Fisher 4 6 -- [Review courtesy of Stephen Norris.] Allows NPC's to learn topics of information (OR_KnowledgeTopics) and to tell them to the player and other NPC's. Each NPC can present the information in their own way.
ORAdjective Jim Fisher 10 6 -- [Review courtesy of Stephen Norris.] Implements adjectives in the standard way. (See pname.zip, above.)


Replacement Libraries (currently just Platypus)

File NameAuthor Use Pow Gl Comments
platypus.zip Anson Turner 10 10+ -- Platypus, as implied above, is not an extension of the existing Inform library, but a wholesale replacement of it. It has its own learning curve (sort of like acquiring a new dialect of a language you already speak), and is not guaranteed to work with the other items on this page. (It may work, but no promises. There have been some library contributions tweaked to make them Platypus-compatible; see below.) Converting existing code to Platypus may also be a fairly large undertaking, though a lot of it seems to consist of changing the names of various properties, variables, and entrypoints. (See the Standard to Platypus conversion page for more on this topic.)

[Sabrejack's review:] I'm going to summarize Platypus in one sentence: Platypus makes Inform feel like it was written for you, too, and not solely for use by Curses and Jigsaw.

Welcome to my quick write-up of the pros and cons of the Inform standard library replacement, Platypus. We're going to discuss three major ideas: the programming model, the world model, and fixes. Learning to use Platypus is an undertaking, and I hope to help you decide if it's a move you should make. Be forewarned Do not try to convert your work in progress to Platypus unless you are extremely early along or you're that special sort of masochist. It's better to start your next work in Platypus if you decide to learn it. We'll start with the pros.

The programming model of Platypus is quite different. The summary documentation gives a terrific overview. Most of the changes are small or cosmetic, removing redundancies, gotchas, and so forth. However, the major programming model change Platypus brings to the table is the flow of operations during an action. As you're used to, Inform's standard library goes: orders, react_before, before, after, react_after. It also calls a few entry points. Platypus is much more fine-grained, and follows this line: orders, meddle_early, respond_early, respond_early_indirect, meddle, respond, respond_indirect, meddle_late, respond_late, respond_late_indirect, meddle_late_late.

That was a mouthful. Meddle properties are called for all objects in scope, respond properties are called for the noun object in a directed action, and respond indirect properties are called for the second object in actions such as Neo in "throw spoon at neo". This conveniently removes some of the fake actions, implementing a suggestion straight out of the Inform Design Manual 4.

The world model of Platypus is generally smoothed out and improved, but not radically changed. Of note, examining a wall now says "You notice nothing new in that direction.", making for suitable indoor and outdoor use alike. Objects may now be a supporter, a container, and/or a hider (something under the object), with upon_capacity, inside_capacity, and under_capacity being separate properties (a box, on its side, would be both a supporter and a container, while a couch might be all three if you plan to hide things in the cushions!) The ##Put verb knows the difference between put in, put on, and put under. The ##Take verb will take a hider, but not the things underneath. And so on.

Bug and annoyance fixes make up the majority of what impresses me with Platypus. People have written many libraries to handle many issues, but Platypus has already taken care of some of them. The respond indirect routines are one example, and the indoor/outdoor walls are another. Verbs have been generally tidied up. Platypus provides a disambiguation method, a footnotes.h, an 'exits' verb, and a 'go to ' command for rooms you've already visited (along with ways to restrict path finding). The Actors class comes with a perform routine with which you can control an actor and make him perform any non-meta verb. A puppet is as simple as orders [ ; default: self.perform(action, noun, second); ]. The verb library prints all actions from the proper perspective. The parser has been tweaked to understand slightly more complex ideas -- "pet the kitten in the box on the table" will find the correct kitten, and not the one in the box under the table. It provides an adjective property, and the parser will favour nouns over adjectives. The classic example is that "get orange" will take the orange in the fruit basket (with noun 'orange') before the orange ball (with noun 'ball', adjective 'orange'). There is also a 'multiflag' global variable which allows you to, with a little cleverness, code responses which are aware if the player is taking multiple objects (having eight "Taken." lines was a pet peeve of mine). There is a way to teach the parser how to print property values when using showobj instead of simply showing property [] (192843). It helps out with the Ask/Tell system. It handles NPC movement with the same world rules as the player (doors etc.)

This is not an exhaustive list. There is a lot more to know and learn, but these are the most immediate advantages.

Now for the cons. The biggest con is the learning curve. The ActionMessage system was a bit bulky for me to understand at first, and indeed, looking at a line of your code and trying to remember what ActionMessage(##Open, 100) prints out is not friendly. Thankfully the ActionMessage system is optional at first (unless you want to use narrative mode in your game, which is also optional.) There are new (and improved), but initially strange systems for library messages, tasks and scoring, allowing entry upon/inside/under an object. I would have liked to seen AskTellOrder.h, outofrch.h, and Locksmith.h incorporated, but I can't have everything. Another downside, standard Inform libraries may not work exactly right with Platypus, in which case, they will need to be ported.

Platypus simply seems weird at first, and it will take a while to relearn how to accomplish all the old tricks you used to know how to do under the standard library but when you do, you'll see there's really a lot less bending of the rules required.

See also the Platypus webpage.

plphtoo.h Adam Cadre
David Glasser
Alexandre Muniz
8 -- -- Much like phtalkoo.h above, but corrected to work with the Platypus library.


Return to Main Page
Last update February 28, 2003.