The world is a room.
The apple is a thing.
Pondering is an action applying to one visible thing. Understand "ponder [any thing]" as pondering.
Poking is an action applying to one touchable thing. Understand "poke [any thing]" as poking.
“Ponder apple” now works even though it isn’t visible to the player, but “poke apple” does not. In other words, the “any” in the understand statement seems to override the action’s visibility, but not touchability, requirement. This leaves me confused: first, why is an understand rule modifying the “type signature” of the action? I would have thought that there were two completely different steps: first the parser converts the input into a verb and up to two nouns (with understanding helping it do so), and then, completely separately, it tries to invoke the corresponding action, and checks that the object is visible/touchable/carried by the player, as required by that action. But apparently understanding and actions are a lot more coupled than I thought?
So secondly, what exactly does “visible” formally mean? Is there a chapter in the manual that discusses this? I’ve read 12.17 but it’s very vague.
This is accurate, but the following gloss (“the player can see it”) is misleading in many important cases.
In your case, you have to combine this with the following (from section 16.7):
Since it’s possible to refer to any door, that means the doors count as visible as per the bit I quoted from section 12.17, since you can refer to them. Or in your case, when you type “poke apple,” you’re allowed to refer to the apple or any other thing anywhere in the model world (since there’s an [any thing] token in the relevant understand line), so they all count as visible.
Another important case is when you’ve manually placed something in scope, as in section 17.27 of the manual; usually then that thing will count as “visible” but not touchable.
It might help to think of “visible” as meaning “referable.” Ironically, things that are “visible” but not touchable are often things that you can’t see, but can refer to because of an [any] token or because you’ve manually placed them in scope. (And since “applying to one thing” defaults to “one touchable thing,” I think, “visible thing” is usually broader than thing and you need to say “applying to one visible thing” when you want the action to apply to things you can’t see!)
“Visible” means that there is no touchability requirement, whereas the “any thing” token applies to any item in scope. Consider the following:
Lab is a room.
Closet is a room.
A glass box is a transparent, closed container. It is in lab.
An apple is in the glass box.
A broom is in the closet.
Pondering is an action applying to one visible thing. Understand "ponder [any thing]" as pondering.
Glancing at is an action applying to one visible thing. Understand "glance at [a thing]" as glancing at.
Poking is an action applying to one thing. Understand "poke [any thing]" as poking.
Cleaning with is an action applying to one thing. Understand "clean with [a thing]" as cleaning with.
After doing something:
say "Action succeeded."
Test me with "ponder broom/ponder box/ponder apple/glance at broom/glance at box/glance at apple/poke broom/poke box/poke apple/clean with broom/clean with box/clean with apple".
You can see that pondering works always, no matter where the object is or whether it’s touchable or not.
If you change the the token from “any thing” to “a thing” you force the parser to consider the scope (only things that the player can see). Now the action fails for everything that isn’t in the same location (or anything that can’t be seen).
If you keep the “any thing” token and remove the visibility requirement (thus enforcing that the player must be able to touch the object; note that “…applying to one thing” is equal to “…applying to one touchable thing”), you get a response from trying to poke the broom that says you can’t touch the broom because it’s too far away (in another room).
Finally if you have the standard “a thing” token and the touchability requirement, the action fails for the broom (it’s not in scope) and the apple (not touchable).
Hopefully this clears it up a bit. The “visible” keyword is rather misleading and there’s a request that it should be changed.
What always gets me in a bind is that “visible” actually has two different meanings, depending on context. In the definition of an action it means there is no touchability requirement. But it’s also defined as an adjective meaning “in scope.” So sometimes “visible” means exactly what you think it does, which only makes it more confusing when it doesn’t.
As far as I know, there’s no adjective meaning “applicable to the current grammar line” - so for example if you have this:
Understand "open [any closed thing]" as telekinetically opening.
you’ll just have to reiterate “closed things” to figure out what might apply.
I just looked at the Uservoice request and I noticed an even deeper potential for confusion:
People there are suggesting the phrase “in scope” instead of visible, but at the moment, this is closer to the adjective definition than the action definition:
[code]Test is a room. There is an apple.
Discussing is an action applying to one visible thing. Understand “discuss [any thing]” as discussing. Report discussing: say “You talk about [the noun].”;
After deciding the scope of the player when touching: place the apple in scope;
Every turn: showme the list of visible things.
test me with “discuss apple/touch apple/z”[/code]
If you run this, you’ll see that using the “any” token in the discussing command does not make the apple visible. Does that mean it’s not in scope? I’m not sure.
On the other hand, placing the apple in scope explicitly when touching causes the apple to become visible, even though it really isn’t.
My conclusion: Not only is the word “visible” ambiguous and confusing, but the phrase “in scope” is not much better. We need a clearer distinction between “available to the current action,” “available to the parser,” and “perceptible to the PC.”