Inform 7 documentation and resources

Authoring Inform 7
1

How to Not Lose This Post

Note: Answers to many questions could be found in Reference’s links; they include a lot of info not in the docs.

Inform 7 10.1.2 (current, 2022-08-31)

Official Inform website

Installation

@Juhana’s Borogove lets you edit and run I7 online without installing anything (10.1, 9.3/6M62, or 8.5/6G60). Borogove snippets allows sharing code examples.

10.1.2 packages for Mac OS, Windows, or Linux (as RPM, .deb, or flatpak (Linux IDE installation notes). They include the IDEs; the zipped source code archives there do not.

Building I7 from source (no IDE)

Version History

Previous releases were named by their build numbers; 10.1 introduced a new version number scheme with retroactive application:

Build Version Released
6G60 8.5 Dec 2010
6L02 9.1 May 2014
6L38 9.2 Aug 2014
6M62 9.3 Dec 2015
10.1 Aug 2022

9.1/6L02 included substantial language changes; 10.1 included substantial implementation changes, though its language changes were modest. Many links here are labeled with the I7 version as of which they were current; beware that some details may be outdated. For most, it’s minor. A few have a significant amount of out-of-date info, but still-relevant parts too valuable to miss.

Detailed I7 change logs

Documentation and Resources for 9.3/6M62

Development

The next release will be 11.0. No schedule has been announced. 9.3 is no longer supported; further releases of 10.X are not anticipated. Proposals for development are at Inform Evolution.

Learning

Tutorials

Start here!

Manuals/Books

Reference

Writing with Inform read-through and commentary (9.3/6M62)

Deep dives by @drpeterbatesuk

I7 Reference Manual (unofficial); discussion of I7 Reference Manual

The turn sequence and action-processing rules in detail

Times, Turns, and Tenses: details on counting occurrences of actions and the past tense in conditionals

Room description’s activities and rules (used by look-ing)

The "Rewrite The Parser in Inform 7" Project (6G60). Many details have changed since this was written, but Ron Newcomb’s Original Parser extension’s documentation remains an invaluable resource.

Line break behavior; see also Nathanael’s Cookbook

WI 27.14: what’s permissible in I6 inclusions (10.1)

@emshort’s rules flowchart (PDF) (5U92) illustrating the turn sequence

I7 Windows IDE with the NVDA screenreader

Compilation produces a Project Index, customized for your game and viewable in the IDE. In some ways, it’s the closest thing to an official reference manual, including many details not in the docs. Its Phrasebook Index section (Phrases, Lexicon, Relations, Verbs) is good to check (along with the docs’ General Index) when you half-remember something and are hunting for the right term to look up.

The literate source describes in detail how I7 parses your story; this Syntax.preform documentation PDF (6L02) offers a condensed account. One can also see what irregular verbs and plurals I7 handles (and how) within.

When to use which action rulebooks?

Don’t just put everything in Instead rules. Countless examples in the docs seem to endorse it… examples focused on things other than best practices for creating actions. Implementation may be more perfunctory than exemplary for elements that aren’t an example’s point. The seeming ease and convenience is a trap. If you implement everything in Instead rules, your story will become an incomprehensible mess as it grows beyond example length. See guidelines for rules about actions and:

Built-in Extensions

All use authorial modesty, thus don’t appear in the version command’s output. They can be browsed within the IDE: see “Contents” in any compiled game.

Basic Inform is new in 10.1. With it, one can use Inform, the language, without the IF-specific bits. See A Guide to Kits. A to begin phrase is required for your main code (to begin has no special significance outside of the Basic-only case).

To modify and extend I7’s World Model and built-in actions, it’s crucial to understand them. The Standard Rules are the authority here and are (mostly) highly readable, especially the Actions section.

The docs don’t list all of the built-in actions and commands; newcomers often get tripped up by a “new” command’s conflict with an existing command. See Actions > Commands in the Project Index for the whole list.

@otistdog 's Standard Rules Actions reference (9.3/6M62) has details on the actions, with charts of:

Directions (and their abbreviations) are not conventional commands. If a player enters one, it becomes the noun in a going action. oops / o, again / g, and undo are other parser special cases (they don’t correspond to actions).

Useful threads/posts

Testing and Quality Assurance

Elsewhere

Ryan Veeder

@emshort

Playing

Popular desktop applications supporting I7 games include:

List of glulx/.gblorb interpreters; see also Glulx and Z-machine below.

Extensions

The Windows IDE supports easy installation of extensions from the offical Inform Public Library. It’s broken in 10.1’s Mac OS and Linux IDEs, but you can install extensions manually: see Where to find Inform 7 Extensions.

The Friends of I7 Extensions is the most comprehensive source (the Public Library is based on its contents c. 10.1’s release).

The Technical Development > Inform Extensions category is for discussion of (existing, published) extensions.

Extension Writing Guides

Select games/examples with Source Code available

9.3/6M62

Earlier

How to Organize/Structure Your Project

There’s no one answer. Have multiple answers!

See games with available source code above for examples.

Infrastructure

Inform 6

I7 compiles to I6 which is compiled to your choice of Glulx or Z-code (v8 only). I7’s standard library is built upon kits of I6 code. (The I6 standard library isn’t involved.)

The current version is I6 6.44. I7 10.1 comes with 6.41.

The Inform 6 Designer’s Manual (DM4) was last revised in 2001, prior to I6’s Glulx support. Some essential supplemental docs:

Much more at [I6] The list of Inform 6 documentation

While the docs stress that you shouldn’t need to concern yourself with what lies beneath…

  • modifying or interacting with the I6 layer is the only choice for some things; many extensions do so
  • some I7 behaviors are best understood as artifacts of I6 representations
  • consulting the I7 compiler’s I6 output can be invaluable in troubleshooting

Glulx

Interpreters

Glulx Reference

Glulx Utilities

Glulx assemblers

Glk

Glulx I/O is via the Glk API. Glulx terps need a Glk library, e.g.

  • CheapGlk (no windows, no status line, just input and output streams, primarily of interest for testing and development; invoke terp with the -u command-line flag for UTF-8)) – C
  • GlkTerm (for use in a terminal; supports multiple windows); GlkTermw (supports characters beyond Latin1) – C
  • GlkOte (Quixe/Lectrote) – Javascript
  • cheap-glkote (ElseIFPlayer’s variant) – Javascript
  • RemGlk (I/O via JSON objects; supports multiple windows, most Glk events) – C
  • CocoaGlk (Mac IDE) – C
  • Miniglk (default when compiling to C; built into I7) – C
  • GlkOte-term – Javascript

Glk can’t fully support Z-machine’s text color options… without the (non-standard) Gargoyle Glk extensions included in:

The display the boxed quotation phrase exists to use a specific Z-machine feature; its use isn’t recommended for Glulx.

More Glk implementations on the IF Archive

Differences between Javascript & C Glk APIs

Glk via network

To put UI in a front-end process while a back-end process run a game, RemGlk is an obvious choice for the back-end (as in Parchment).

Glk Reference

Glk 0.7.6 spec

Old, but still of interest:

Z-code

Some of countless Z-code interpreters:

With Zig or Gluzma, one could run a Z-code game within a Glulx game.

The Spatterlight, Gargoyle, and Lectrote apps, and iplayif.com / Parchment use Glk for I/O even with Z-code, so display the boxed quotation won’t match true Z-Machine appearance/behavior (the Z-machine quote box problem). Lectrote also doesn’t support all Z-machine text color options.

Z-code Reference

Z-code Utilities

Publication

The Web

Per WI Ch. 25: Releasing, release with a website uses a web template to create an index.html page with links to the game file or other included digital assets; release with an interpreter uses an interpreter template to make a play.html page that can run your game within a web browser. (Both cases rely on other files that are also written to the Release directory.)

Web templates

I7 includes the default Standard template and the straight-from-2005 Classic template. Styled is another.

Interpreter Templates

10.1 includes Quixe 2.2.1 and a broken version of Parchment. For an up-to-date Quixe or a functional Parchment, make a Templates directory under your project’s Materials directory. Inside it, unpack either or both of:

If you release with an interpreter I7 defaults to Quixe when compiling to Glulx, or Parchment for Z-code. You may specify release with a "Parchment" interpreter when compiling to Glulx. (Quixe is for Glulx only.)

release with an interpreter implies release with a website. play.html is provided by the web template.

Quixe’s Glulx terp is quixe.js; “Quixe” often means the terp, not the template.

Prior to 2025.1, Parchment used ZVM and quixe.js. Thereafter, it uses Git, Glulxe, and Bocfel compiled to Wasm by Emglken. Async Glk is the front end; RemGlk-rs intermediates between it and the terp. “Parchment” often means the large project powering iplayif.com, not the template.

Bisquixe

@Mathbrush 's Bisquixe, a modified Quixe template plus I7 extension (for 9.3/6M62 or 10.1), allows easy changes to text formatting/style during play and hyperlink support. See Fake Twine.

Vorple

Vorple is an interpreter template/extension combo that allows ongoing interaction between a running game and author-created Javascript in the browser, unlocking enormous potential. Jack Welch’s re: Dragon (source available) is an example of an extensively customized UI in Vorple.

Cover Images

If you release along with cover art, put Cover.jpg or Cover.png in your materials directory. Inform automatically copies this to Small Cover.jpg (or png) in Release; this is what is displayed on index.html and play.html; it links to the original. If you provide your own Small Cover, it’s ignored. You can overwrite Small Cover in Release (every single time) if you like.

Alternatives

If your game has file or figure assets, play.html as generated by release with an interpreter won’t be able to find them. Either of these are preferable:

  • @Zarf’s ifsitegen.py is a command-line script that acts on a Z-code, Glulx, or blorb file; results are similar to releasing with Quixe (except it uses ZVM for Z-code)
  • IPlayIF’s sitegen is online and uses Parchment: upload a game file; it creates and downloads a browser-playable game as a single HTML file

Hosting

Some free ways to publish a game on the web:

If your game file can be directly downloaded from the web, you can submit its URL to iplayif.com and record the URL of the IPlayIF page you’re redirected to: if your game remains available at the original URL, anyone can use that IPlayIF URL to play your game online. Or you could could construct the URL: it’shttps://iplayif.com/?story= plus the URL-encoded URL of the game file.

This can’t work if access is encumbered by, e.g., a CAPTCHA or required login. If you upload your game to the IF Archive you’ll end up with a suitable URL for this purpose: many IFDB pages’ Play online buttons do this.

Stand-alone application

Lectrote is Quixe (and other terps) within Electron, roughly. It derived from @Zarf needing cross-platform stand-alone apps for Hadean Lands. It can be the basis for a “bound game”; see trying to make standalone game w/ Lectrote.

One can also compile Inform into C that can compile into a standalone executable.

Utilities

Blorbs

blorb is a standard for bundling game assets into a single file for distribution. Inform creates one when you build for release.

Blorb utilities

Editor plugins

vscode-inform7

Emacs

I7 in translation

How to Not Lose This Post

This post is pinned to its category. By default, Discourse unpins a thread when you reach the bottom; this can be turned off in Interface under Preferences in your Profile. Or you can bookmark it: the bookmark icon is at the bottom of the post (you may have to select a … icon to see it). To see your bookmarks, select your profile icon in the upper right, then select the bookmark icon there. If you do lose the post, search the forum for “documentation and resources” or visit while logged out.

Bookmark interface

428x64

690x385
690x385903×504 53 KB

This ain’t over

Documentary and resourceful goodness continues in the I7 Docs and Resources Annex below.

21 Likes
81

I7 9.3 is no longer maintained and I7 10.1 fixes numerous bugs. Unless you have some specific reason to use 9.3 (e.g., you’re in the middle of a large 9.3 project or your project depends on an extension that isn’t available for 10.1), you probably owe it to yourself to upgrade. That said…

I7 9.3/6M62 (released 2015-12-24)

9.3/6M62 language and IDE docs (included in the IDEs)

For official packages mentioned below: I7 9.3 Downloads.

MacOS

Use I7 site’s package, not the App Store’s.

Known issues:

An unofficial MacOS IDE release addresses these (but testing examples in Extension Projects doesn’t work)

Windows

Use the package on the I7 site (said to work with any version of Windows from XP SP 3 on). There’s a current 64-bit-only beta release of a new Windows version that allows compiling for any of 6L02, 6L38, 6M62 that has been tested only on Windows 10, but may work with older versions. Be warned that there have been multiple reports of security/antivirus programs causing problems with it: Avast, AVG, Windows Defender.

Linux

The 6M62 IDE uses GTK2, not modern GTK3, making it hard to build in modern Linux.

Unofficial rpm/deb IDE packages

Linux kernels < 4.11 (c. 2017) are incompatible with versions of ni prior to 6M62. To use 6L38 or older try an old Linux in a VM or Windows Inform in WINE. For 6G60, try playfic.com or borogove.app.

The official packages include components with more recent versions, e.g.,

Where to find I7 extensions includes info for 9.3/6M62.

Tutorials

Licensing

If you encounter memory limits in compilation, see Memory Limit and Storage Variable Limit settings or try I6 6.36 or higher, which does away with these limits

The I6 Template Layer that Inform installations have under Internal/I6T. Once called Appendix B of the docs, the template layer’s comments document some things not documented elsewhere.

Standard Rules

I7 includes the Standard Rules in every game. They’re the authority on I7’s World Model and defaults and can be browsed within the IDE: see “Contents” for any compiled game. They used to be called Appendix A of the docs. Some things in the SR may look modifiable but they’re really interdependent with something hard-coded in the compiler. Beware that 9.X’s Standard Rules (6L02, 6L38, 6M62) are all marked Version 3/120430 but each is different. (Likewise, 6E59 through 6G60’s Standard Rules are each different but all marked Version 2/090402.)

Bugs

6M62 Patches by Friends of I7 provides fixes for some known issues in 9.3/6M62.

The I6 that shipped with 9.3/6M62 was 6.33N. The current version is 6.43. Bugs in (the current) I6 can be reported at the Inform 7 bug tracker

The old I7 suggestion forum, via archive.org.

Beyond Inform

(invaluable resources not specific to Inform)

Language Comparisons

History

Toward I6: New Tricks for an old Z-machine

  1. Digging the Trenches
  2. Hacking Deeper, or Follies of Graham Nelson’s Youth
  3. A Renaissance Is Nigh

Toward I7

Toward I7 v10

Legacy Projects

Miscellany

Jeff Nyman

@emshort

Z-machine implementations on some notable hardware

Updating 6G60 code

82

Rockin; thank you :slight_smile:

83

Could this be made sticky?

84

Done

1 Like
85

Would be nice to have an I6 sticky as well, preferably A B O V E the I7 sticky so that there is no doubt as to which language is the original and which the knockoff.

1 Like
86

I would especially push for the link below (which is actually mostly in Inform 7). It’s Appendix A – i.e. the Standard Rules commented and explained literate programming style. To my mind, it’s a vital part of the I7 documentation.

87

For what it’s worth, I haven’t updated the syntax document for the last build, and don’t expect to do so going forward, because the indexing has improved enough that it should now provide a comprehensive reference for that kind of thing (and it’s automatically cross-linked with the documentation). But if people find the old document useful to browse anyway, that’s fine – just be warned it’s largely been supplanted.

88

Excellent!

89

Also, this link to Appendix B, the underlying I6 template layer–just as vital in my opinion as the documentation of the Standard Rules.

inform7.com/sources/src/i6templa … index.html

–Erik

90

Thanks for the comments folks, I’ve updated the OP.

91

I third this suggestion. I also recommend that, if the author will be updating the first post, the title be updated, too, so we also know when this was last updated.

92

Good suggestion, done.

93

Yay, glad I could contribute in some small way!

I know that one thing I’m only just discovering is how to use the skein and transcripts from it. Is there any website that guides us through that?

I also had no idea how to use the IDE’s features for looking through all standard actions. I’d think if someone could make a youtube video or selection of screenshots to guide a person through, that’d be hugely helpful. I suspect once people know this sort of thing is there, that’s a lot less work.

Finally, one of the big roadblocks I’ve had is knowing which extensions to use. So many times, I’ve been wondering if I should bother programming X and not knowing whether there was an extension Y that would take care of it. I think any one person’s documentation generally catches some good ones, but is there something more general? I know I’d find it useful to be able to see programming examples or evaluations. Beyond the extension authors’ own, which I don’t want to belittle. But it’s more the “wow, other people can use this”

Is anyone aware of these? Does anyone want to create such a page? Are these questions out of the scope of the topic? I hope I haven’t hijacked the thread, but really, I’m glad someone took the time to tie this up, and I thought I’d ask a few more questions while I was at it.

One final thing–let us know whether it might be better to PM/email you with small changes, or if we should just post here.

94

Posting in the thread works for me. At some point it’ll make more sense to put this somewhere that’s generally editable, like ifwiki, and I’ll probably just post a redirect link in the OP.

Your questions about extensions definitely are relevant, and in fact Aaron Reed proposed something very similar, see this topic Extension Census 2010 - #7 by George. I don’t know if he’s gone further than that.

95

This is a very low-tech way to address this, but I usually go to the Extensions page, click “All Extensions by Category” (or any of the other aggregate links), and do a quick in-page search for keywords related to the problem I want to solve, like “liquid” or “inventory” or whatever.

Regarding better extensions visibility: I think everyone agrees it would be great to have this integrated into the IFDB, or give more sharing and community features to the official site, but it’s as usual a question of volunteer-hours available. We’ve tried to kick-start this a couple times but it involves major work and coordination of effort between several people, and it just hasn’t come together yet.

In the meantime, it would be awesome if someone started a third party site promoting extensions somehow-- I’m afraid it’s not going to be able to be me at the moment, although I’d certainly be open to contributing if a group effort arises.

96

This has worked well for me. I think it is good and will work for others, too. However, it’s those moments where someone points something out and I say “of course the extension was there, and of course it did this” that work really well.

Sounds like a good idea for a spinoff topic. I would like to be part of this effort, because I think my biggest growths as a coder have occurred when I realized that, yes, you could do this-or-that easily.

Though obviously this’d require a lot of white paper, I have some ideas. However, I also have no idea how to go about building a website, or how to possibly integrate a website into something bigger. Simply giving statistics on how many games use which extensions, and maybe a blurb on how they use it, could be effective. Granted, the quality of the games may not reflect the quality of the extensions, but there’s a lot of “how’d they do this” that gets dispelled pretty in a game, regardless of quality, that you don’t see in an example.

I also have no clue how much/little extension authors tolerate/appreciate having an extra example made that uses their extensions. But in my experience, I generally have to use an extension in a dumb game before I’m brave enough to use it in something real.

97

Two more I7 reference documents (slightly oldish):
Emily Short’s 2007 draft of an I7 syntax reference at http://www.inform-fiction.org/I7Downloads/Documents/I7_syntax.txt.
And a document giving the grammar for I7 in Backus-Naur notation at http://www.inform-fiction.org/I7Downloads/Documents/I7-Grammar.pdf. (Not sure about its up-to-datedness.)

98

I’d love to read some of Emily Short’s code after seeing in another post that it’s “spectacularly clean.” Organization is an area in which I’m really interested in developing a good practice.

Where’s the source code at this link? For example, here’s the entry for Bronze:

ifdb.tads.org/viewgame?id=9p8kh3im2j9h2881

I’m sure it’s just me, but I can’t find a link on this page for the source code.

Thanks!

99

All of Emily’s released source is linked from here. (It would be sensible if the IFDB pages also had links to it, though.)

1 Like