Extensions Guidelines

Checklist

Suppose you have written a new extension, and are nearly finished:

* Have you written a rubric for your extension?

* If your extension is meant for a particular virtual machine, have you marked it accordingly?

* Does your extension include testing commands?

* Do your newly-defined actions have rules for characters other than the player?

* Have you given an explicit name to each of your rules?

* Have you made it easy for authors to replace the text output of your extension?

* Have you written documentation?

* Does your documentation mention any dependencies?

* If your extension is a long or complex one, is your documentation divided up into sections?

* Have you included at least one example showing how your extension works?

* Have you tested this example to make sure that it runs properly?

* Does the example have a paste button?

* Does the example have at least one test?

* If your extension is large or can achieve a variety of effects, do you have more than one example?

Suppose you have seen to all of that and now want to publish the result on the Inform website:

* If your extension is complex, have you asked someone else to proofread and beta-test it?

* Do you understand the implications of the Creative Commons attribution license?

* Is your extension attached to the email as a text file?

* Do you provide a blurb to go on the Inform website?

Suppose you have written a new extension, and are nearly finished:

* Have you written a rubric for your extension?

CLARIFICATION: The rubric is the piece of text immediately after the heading, as in

"Rigorously implements the smells and flavors of 39 varieties of cheese."

RATIONALE: This text is displayed when the author mouses over his list of installed extensions, and makes it easier for him to find what he wants.

* If your extension is meant for a particular virtual machine, have you marked it accordingly?

CLARIFICATION: A virtual machine indication should appear in parentheses after the title of the extension, like this:

Version 4 of Advanced Wine Pairings (for Glulx only) by Emily Short begins here.

RATIONALE: You will spare authors time and frustration if you make it clear which VM your extension accepts. Note that if your extension depends on another extension, which only works on one VM, then yours should be similarly marked.

* Does your extension include testing commands?

CLARIFICATION: For instance, a "not for release" section of the extension could include one or more testing commands - which, like the built-in testing command SHOWME, could print out any information your extension is storing behind the scenes, or, like the built-in ACTIONS, could switch on a mode in which your extension prints up explanations of what it is doing. Since such commands are in a "not for release" section, they disappear without trace in any released game. It's a good idea to make the names of such testing commands fairly specific, and essential that they don't clash with any potentially sensible commands of a player - for instance, don't create a testing command called LOOK. It's also a good idea to document (briefly) what testing commands there are, perhaps right at the end of the extension's documentation.

RATIONALE: Simple extensions may not really need testing commands, but very often time spent creating them is easily repaid later when it comes to debugging awkward cases which you missed on the first writing. Remember that Inform is a moving target, and that syntax and other conventions do change as time passes by; and sometimes one extension clashes with another, by somebody else, so that unanticipated problems can easily arise later on. There are Inform 6 extensions written in the early 1990s which are still used in some circles today, often having been maintained by people other than the original author. If your extension is useful, it may have a very long lifetime, by software standards. Making it easier to maintain could be a great help to your future self, and your successors.

* Do your newly-defined actions have rules for characters other than the player?

CLARIFICATION: Rules for the player's actions read like

Check manufacturing a cheese: ...

Rules that apply to other people's actions read like

Check someone manufacturing a cheese: ...

and rules that apply to both the player and the other characters read like

Check an actor manufacturing a cheese: ...

If you are creating an extension that adds new actions to the game world, consider implementing them so that other characters can also perform the actions. The built-in extensions Locksmith and Rideable Vehicles already do this, if you would like to compare how they work.

RATIONALE: Every one of Inform's built-in actions works for every character: that is, any person can be the actor. This means that authors (and other extensions) assume that anyone can perform any action, and that in turn means that many interesting effects become possible. (It's especially the case that character-driven rather than old school puzzle-driven IF tends to involve people other than the player planning what to do, and then carrying out their plans - all via actions.) An author writing his own work of IF can afford to make an action work only for the player, because he knows everything which will happen in his own world: but an extension-writer never knows what might be happening in the works using his extension.

* Have you given an explicit name to each of your rules?

CLARIFICATION: Your rules should all look not like this

Instead of smelling a washed-rind cheese:

say "Whew, that's strong."

but like

Instead of smelling a washed-rind cheese (this is the washed-rind cheeses stink rule):

say "Whew, that's strong."

or

This is the washed-rind cheeses stink rule: ...

Inform requires that rule names end with the word "rule". Beyond that, there are conventions in how to name rules: try imitating the style used in the many, many examples on the Actions index page. For instance, a rule preventing some attempted action normally has a name beginning with "can't" - as in the "can't take what you're inside rule". Your rule names need to be fairly specific, since they must not clash with names of rules in other extensions being used alongside yours: so don't go for "the bad object rule".

RATIONALE: Authors using your extension can manipulate the rules (replacing or moving them) only if the rules have individual names. This makes your extension much more flexible and more likely to be useful on a wide range of systems. Named rules also make your extension easier to debug, since it means that the ACTIONS command can tell you which rule stopped one of your actions, for instance.

* Have you made it easy for authors to replace the text output of your extension?

CLARIFICATION: Text is reasonably easy to replace if it appears in a table or in a named variable, or if it occurs in an isolated rule, like

Table of Cheese Flavors

variety flavor

gruyere "Faintly nutty."

or

The Gruyere-flavor message is some text that varies. The Gruyere-flavor message is "Faintly nutty."

or

A gruyere has some text called the flavor. The flavor of a gruyere is usually "Faintly nutty."

or

Report eating a gruyere (this is the gruyere-flavor rule):

say "It tastes faintly nutty." instead.

or

Rule for giving flavor of a gruyere:

say "It tastes faintly nutty."

Text is difficult to replace if it appears interwoven with a lot of other logic in a rule.

If the text needs to change during play, properties, tables and variables can be a good choice (probably in that order).

Tables are also a good choice if you expect the user to need to add to (rather than replace) the material you provide, since he can always continue a table in his own source.

Otherwise, rules and rulebooks are usually the easiest way to help users to modify your extension's behaviour. For instance, the following:

Giving flavor is an object-based rulebook. Rule for giving flavor of a gruyere (this is the gruyere-flavor rule): say "It tastes faintly nutty." Rule for giving flavor (this is the unspecified-flavor rule): say "It tastes frankly bland."

Report eating a cheese sample (called the hunk): consider the giving flavor rules for the hunk.

can be translated into another language, or reworded, simply by replacing the two "giving flavor" rules by name, and the user can also add interesting new rules to cover extra cases, large or small.

RATIONALE: Authors using your extension are more likely to want to tweak the text than pretty much any other aspect of the extension's behavior. They might want to use your logic, for instance, to write a game in Spanish; or they might have changed output to the first person, and need to override all instances of "You..." in your prose. You'll make your extension more broadly valuable if you make it easy to adjust in this way.

* Have you written documentation?

CLARIFICATION: Every extension can easily include its own documentation, with no fuss or need for additional files, simply by concluding with a special section of text written for the user's benefit. This can include sample source text using your extension, and even examples like the ones in the main Inform documentation. See the Extension documentation section of the Extensions section on how to format this, and the "Modern Conveniences" example for a discussion of what kinds of information are especially useful to list in an extension.

RATIONALE: Extension documentation is typeset by Inform and automatically placed into the in-application documentation as soon as an extension has been installed. Users expect always to find this, whereas they often can't easily read the text of the active part of the extension - even if they are willing to. In practice, users never take advantage of extensions which have no documentation. An extension is just not finished without it.

* Does your documentation mention any dependencies?

CLARIFICATION: Some extensions need to include other extensions in turn: this is called a dependency. Dependencies are not a bad thing: the whole design of extensions is based around the idea of interlocking pieces all contributing to the whole.

RATIONALE: If the extensions you depend on are built-in (like "Basic Screen Effects by Emily Short"), you can be fairly sure that the user will have them to hand, but if not then the user will need to download them - and it's polite to make this clear in the documentation.

* If your extension is a long or complex one, is your documentation divided up into sections?

CLARIFICATION: This ability was introduced with build 4X60 during the summer of 2007, and it is very easy to take advantage of, with Inform automatically generating a table of contents.

* Have you included at least one example showing how your extension works?

CLARIFICATION: You may include examples demonstrating your extension, just like the examples in the main manual. See "Examples and headings in extension documentation" on how to do this.

RATIONALE: There are actually several benefits here. For one thing, authors find it easier to understand and apply your work, of course; and they can quickly see clear evidence that your extension does what it claims to do. Examples are a showcase for your work.

Another benefit is that an example helps defend your extension against breakage as Inform upgrades. When we build each new release, the extension librarian runs an automated script testing all the examples of all the submitted games. If there are compiler failures, she can then notify you that the extension needs an update, or even (with your permission and if the required changes are small) make and upload a revised version.

Examples also help you to test that your own extension continues to work after you've made "improvements".

* Have you tested this example to make sure that it runs properly?

CLARIFICATION: A common mistake is to create the example but not to have the correct include line in it: make sure that "Include Dairy Products by John Moo." is present.

* Does the example have a paste button?

CLARIFICATION: A paste button makes it easier for the user to try your extension out.

* Does the example have at least one test?

CLARIFICATION: To help the user quickly see what the example can do, you may want to include a "test me" line, like those found in the manual examples. For instance:

Test me with "eat roquefort / smell gruyere / taste gruyere".

RATIONALE: This not only helps the user, but also means that automated tests can check that everything behaves as it is supposed to. Without such a test case, all we can do to check your extension after a new build of Inform is to see that it still compiles. An example isn't really finished without a test script.

* If your extension is large or can achieve a variety of effects, do you have more than one example?

RATIONALE: It's probably good to have a one-star, fairly simple, example first - if only to show the user how easy it is to begin using your extension. You can then follow up with something longer and more substantial. Remember that what seems familiar to you is all just more syntax to be learned for a new user: offering a quick reward for users who are just starting will encourage them to go deeper into the possibilities. That's why the built-in extension "Locksmith by Emily Short" has four examples, for instance.

Suppose you have seen to all of that and now want to publish the result on the Inform website:

* If your extension is complex, have you asked someone else to proofread and beta-test it?

CLARIFICATION: Complex extensions deserve to be beta-tested, just like complete game code. A fellow I7 user will be able to give you some feedback on whether the documentation is easy to understand and whether the extension provides a useful range of functionality.

Please do not ask the Inform extensions librarian to beta-test your work for you. This might seem like a minor favor to ask, but there are many extensions coming in, often all at once, and the extensions librarian has many other tasks already.

* Do you understand the implications of the Creative Commons attribution license?

CLARIFICATION: Extensions on the extension site are published under a Creative Commons attribution license; more on this can be found from the main extensions page. If you aren't happy with that license -- which *allows* your work to be modified, distributed, and incorporated in commercial products -- then please do not submit it.

This is not because of any ideology of the Inform writers: it's just to reflect the traditional customs of the IF community, and to make the site easily understandable for users. You are very welcome to publish any extension you write elsewhere, under any license you please. (But please make clear what your terms are, of course.)

If you have already published an extension on the Inform website, but now want to change your mind about its licensing, you are free to give any subsequent versions that you produce any license of your choice. The Creative Commons license would not apply to those versions. But you are not free to remove the old version from the website - and this wouldn't be fair: others might be relying on it.

* Is your extension attached to the email as a text file?

CLARIFICATION: The answer should be "Yes". Pasting the extension into the body of the email makes it just a bit harder to file; this is not a huge problem, but we appreciate the help.

* Do you provide a blurb to go on the Inform website?

CLARIFICATION: When you submit an extension, it's nice if you give a short description that the librarian can add to the website: this might be the rubric for the extension, plus an extra line or two explaining what dependencies the extension has, any major changes in the latest version, and so on. If you don't submit this, the extensions librarian will make something up. It might or might not be exactly what you had in mind.