I don’t think anyone here is going to criticize you for not reading the documentation closely enough. Although Jim’s book seems pretty good, the built-in documentation is notoriously poor. I consider this forum to be the primary source of documentation!
Success and failure of actions takes some time to understand. Here’s a summary:
The command “stop the action” and “rule fails” are roughly equivalent. They will abort the current action whether you’re in the check, carry out, or report rulebook. Not only will the current rulebook halt, but none of the following action specific rulebooks will execute. Therefore, it is a bad idea to use these phrases in a carry out or report rule.
If you “silently try” an action, the check and carry out rulebooks will run, but the report rulebook will not.
A rulebook has a default outcome. All the action specific rulebooks have a default of “continue the action,” which means the same as “make no decision.”
The Before rulebook also defaults to “continue the action,” but the Instead and After rulebooks stop the action by default (Instead stops the action with failure, and After stops the action with success). Before, Instead, and After rulebooks can apply to multiple actions (e.g. “doing something,” “examining or touching”) - check, carry out and report rules only apply to a single action (e.g. “examining”).
This is the order of action processing rulebooks:
Before
Instead
check
carry out
After
report
An action is considered successful if it makes it through the entire check rulebook without a “stop the action” or “rule fails.” You can abort an action and call it a success by saying “rule succeeds.” Here’s a twist I discovered when playing around: an action is also considered successful if a check rule triggered a “try” that ended in success, even if the triggering rule exited with an “instead” or “stop the action.” “Rule fails” always causes the action to fail, though, and this is seems to be the default for Instead rules.
The “actions” debugging command is really useful in this kind of case - it will tell you what actions are triggered, and whether each one was successful.
One last note: “we have examined the notebook” is only true if the action was successful, but “examining the notebook” is true even if it failed. A warning, though - the latter phrase is only true if a command was parsed as the action - it won’t be true if the action was triggered by a “try” phrase.
Here’s an example:
[code]Test is a room.
A newspaper is in test.
Check touching:
instead try examining the noun.
Every turn when we have touched the newspaper:
say “You successfully touched the newspaper.”
Every turn when examining the newspaper:
say “You tried examining the newspaper.”
test me with “actions/touch newspaper/x newspaper”[/code]