Ah, a reminder to get back to my unfinished gotchas article…
Here’s one biggie.
When you specify an action acts on a thing, you can specify that it acts on a visible thing, a touchable thing, or a carried thing. You may also specify whether requiring light applies to the action.
In between Before rules and Instead rules are, in order, the basic visibility rule, the basic accessibility rule, and the carrying requirements rule. And the most obvious thing in the world would be to assume there’s a one-to-one correspondence here: that the basic visibility rule enforced the visible thing criterion, the basic accessibility rule the touchable thing criterion, and the carrying requirements rule the carried thing criterion. And you’d be two thirds right: it does work that way for touchable things and carried things.
The basic visibility rule enforces the “requiring light” criterion. Nothing enforces the “one visible thing” criterion, because there’s nothing to enforce. Because one visible thing means… any direction, room, region, or thing in the game (including any subkind thereof), anywhere, in or out of play.
You can often get away with it without everything going haywire, though, because it’s the grammar tokens in the Understand lines that determine whether a command will ever invoke that action. And if you’ve said
Fooing is an action applying to one visible thing.
Understand "foo [thing]" as fooing.
you’re actually fine in practice. Because that’ll enforce its use only with in-scope things. And since directions, regions, rooms, aren’t things, you’d have to have written understand lines specifying them as tokens for the action to possibly be invoked. But if you’d said:
Understand "foo [anything]" as fooing.
thinking that meant the same thing as "foo [thing]", then suddenly foo works on any thing in the game with no consideration of scope.
Compounding the ease of error here is that if you say:
Lesnerizing is an action applying to one thing.
it means one touchable thing. It’s natural to think that “visible thing” must be more restrictive than “thing” because you’ve qualified it. But it is (potentially) much more encompassing.
So: never use “visible thing” unless you understand all this and you’re doing it for a very specific reason.
and as a chaser, there’s pointers to useful stuff in the Inform 7 Documentation and Resources thread. (But it’s going to need a thorough rewrite for the new release…)