Here’s the new material on Extensions, which will replace the old material in the Handbook. Please let me know if you spot any problems with this! (And ignore the indentation in the last code block if that gets mangled; I’m just doing a quick copy/paste here.)
–JA
Extensions for Inform
A number of people in the Inform 7 community (which exists almost entirely on the Internet, though local meet-ups have popped up here and there) have written extensions for Inform. An extension is a file containing code that can be used by authors to do something specific — something that’s not included in the standard version of Inform.
There are extensions for creating tricky kinds of objects, such as liquids and secret doors; for producing smoother and more interesting conversations between the player character (PC) and non-player characters (NPCs); for constructing menus of hints that your players can consult; and for many other purposes.
Extensions are written using the Inform programming language — so technically, an extension can’t do anything you couldn’t do yourself. But most of them were written by experienced Inform users, have been tested and debugged, and come with documentation that tells how to use them. So why spend a week working out how to do something tricky when you can download an extension and have it working in half an hour?
Unfortunately, the situation with respect to extensions has become a bit disorganized and confusing. Some extensions that were written years ago for earlier versions of Inform won’t work in 6L02, 6L38, or 6M62, because they haven’t been updated. If you try to include one, the compiler will issue an error message. Sometimes updating the code in an extension is simple enough that you may be able to do it yourself. (See Appendix B for tips on how to do this.) Or the old extension may be irremediably broken.
It was formerly the case that all extensions could be downloaded from an Extensions page of the Inform 7 website, but that page no longer exists. What’s worse, the Inform IDE provides clickable links to a repository called the Public Library — but while those links still work, the archive in the Public Library is not being maintained. Do not under any circumstances click on any of the blue or purple buttons in the Public Library page! Doing so runs the risk of replacing an extension that works with an older version that doesn’t. Clicking on a button in the Public Library page that says INSTALLED may not be a great idea either; I make no promises.
Currently (as of November 2021) the I7 extensions are to be found on github (GitHub - i7/extensions: Inform 7 extensions -- some may be ready for public use, others may be barely working experiments. Enjoy!). In the right-hand column on that page is a Readme link. The Readme will tell you how to download all of the extensions at once, as a single zip file, and how to install them once you’ve downloaded them.
Once you’ve done that, the documentation for each extension will now be available under the Home button in the Extensions page of the Inform program. You’ll find that the extensions are listed alphabetically by the first name of the author.
And there are so many! How to find what you need? The Public Library page in the IDE lists extensions by category, After finding an item in this list that looks promising, you can go back to the full list by clicking the Home button at the upper right and then locate the item you want.
Before tossing an extension into your work-in-progress, I’d suggest that you try running it in a separate project that you use only for testing. Most extensions have example games that you can load into the Source window by clicking that little square button to the left of the example’s title. When in doubt, I’d suggest that you stick to extensions written by authors who are known to be competent — Emily Short, Eric Eve, Aaron Reed, Andrew Plotkin, Dannii Willis, and perhaps one or two other people. If you can’t find what you need among their contributions, then jam on with whatever strikes your fancy.
If you’re upgrading to Inform 6L38 (or a later version) from an earlier version and you already have some extensions installed, you’ll need to install them using a slightly more complex process. Basically, you need to drag your old folder of extensions off somewhere, so that Inform won’t be able to find it. In Windows, the usual location for this folder is My Documents/Inform. In the MacOS, it will be in the Library folder in your folder in Users (for instance, Users/jimaikin/Library/Inform). However, the MacOS tends to want to hide this Library folder from users. If you can’t find it, open a Terminal window. Type this line and hit Return:
chflags nohidden ~/Library/
This code will make the Library folder show up. Please don’t make any other changes in the Library! Once you’ve deleted the Extensions folder from Library/Inform, you can safely download and install the current library of extensions.
Once the extensions are installed, using one of them in your game is easy. Near the top of your source code, just below the name of the game and the author byline, enter a line like this:
Include Notepad by Jim Aikin.
This format is required: You have to give the name of the author, and you can’t put a comma after the name of the extension.
It’s possible to open extension in a new window in the Inform IDE and edit the code just the way you would any other Inform code. If an extension doesn’t work, you may want to try this, but it’s not something you should do as a matter of course. Until you become an Inform power user, it’s far too easy to create problems that are messy and hard to diagnose by editing an extension. If you want to try editing an extension — for instance, because you think it has a bug in it — make a backup copy of it first by copying the file and pasting it to a new folder on your hard drive. That way, if you don’t get the results you’re expecting, you can restore the original version without needing to download it again.
Some extensions use other extensions. If extension A uses extension B (by including it, as shown above) but extension B has been updated more recently than extension A, extension A may now be broken. In this type of situation, your best bet is to report the problem, either in the intfiction.org forum or directly to the extension author.
Appendix B: Updating Older Extensions
Extensions are an important and convenient way of extending the functionality of Inform 7. Many of them are available, but their reliability is not guaranteed. Some may be out of date and won’t compile with the latest version of Inform. Others may be current but experimental and not yet complete or well tested. At this writing (November 2021), the most current archive of extensions is in a github repository at GitHub - i7/extensions: Inform 7 extensions -- some may be ready for public use, others may be barely working experiments. Enjoy!. You can grab single extensions from there, or consult the Readme (GitHub - i7/extensions: Inform 7 extensions -- some may be ready for public use, others may be barely working experiments. Enjoy!), which will tell you how to download everything at once and install it.
Important: Once you have done this, you must avoid clicking on the blue or purple buttons in the IDE’s Public Library page. The Public Library is dead, and those buttons are more likely to get you in trouble than to help you. They may overwrite an extension that works with an older version that doesn’t.
Some older extensions may work in the latest version of Inform without any changes. With other extensions, the needed changes may be so massive that considerable study may be required. In between these two categories, however, are some extensions that can easily be tidied up. If you see one in the github repository that you think might be useful, feel free to download it, install it by putting it in a folder in your Extensions folder, and give it a try.
One of the issues you may find with older extensions is that certain details of Inform syntax have changed. For instance, the old “change … to” syntax is no longer supported. The new syntax is “now … is”. After opening the extension in the Inform IDE or in the text editor of your choice, use the Find command to find all instances of the word “change” and edit those lines as needed.
Another change is that the word “consider” is no longer used to send the game off to a list of rules in the Standard Rules. The new syntax is “follow”. Again, a quick search-and-replace can deal with this.
The code “if using … option” is another non-functional bit of syntax. Replace this with “if the … option is active”. References to the Inform 6 Library Messages, which take the form “L__M”, no longer work, so you’ll need to replace those with new output messages.
A bigger problem in some extensions is procedural rules. At one time, these were used to bypass normal rules in the Standard Library under certain conditions, but they’re no longer allowed. One way to get around this is to write a new rule that replaces the normal rule, insert it in place of the normal rule, and add the required conditions to it. The handy phrase “do nothing” has the effect of bypassing the rule. Here’s a quick example, not from an extension but from the 2009 edition of this Handbook. The “Dangerous Jewel Box” example in Appendix C originally contained this code:
A procedural rule: if taking gems when the jewel box is dangerous then ignore the announce items from multiple object lists rule.
A procedural rule: if removing gems from the jewel box when the jewel box is dangerous then ignore the announce items from multiple object lists rule.
The idea behind this code, obviously, was to bypass the “announce items from multiple object lists rule” in one specific game situation. Here’s how the same code looks today — a new rule that replaces the old rule, checks the game-specific situation, and says “do nothing” if that’s what’s needed:
This is the new announce items from multiple object lists rule:
if the current item from the multiple object list is not nothing:
if taking gems when the jewel box is dangerous:
do nothing;
else if removing gems from the jewel box when the jewel box is dangerous:
do nothing;
else:
say "[current item from the multiple object list]: [run paragraph on]"
.
The new announce items from multiple object lists rule is listed instead of the announce items from multiple object lists rule in the action-processing rules.