Message for failed actions

I’m defining new actions and I am trying to decipher the success and failure chapter of the Inform 7 guide. Here’s one example:

Chewing it with is an action applying to two things. 
Understand "chew [something] with [something]" as chewing it with.

Instead of chewing the tree with the beaver: 
	say "The animal chews the tree one last time."; 
	try hitting the gnawed tree with the beaver.

Instead of chewing something with something: say "That failed."

The third paragraph does what I mean it to do as far as a failure message is concerned (without it I just get a blank line) but I am wondering if this is the right way to do it.

Is it really this simple? Will I encounter issues?

1 Like

That will work. It doesn’t really depend at all on success vs failure. All that matters is that an Instead rule stops the action, and more specific Instead rules are checked first.

2 Likes

Thanks. I have noticed that this overrides “after” rules. Is there a more specific way to target it so that the “instead” rule is only run when a command displays a blank line?

Ideally I would like to create one section of code that just says “That fails” whenever a blank line is displayed, rather than defining that for every new action.

Now that I look at it, I am not sure whether the blank line is actually “failure” or “no outcome” but I think you get what I mean.

By “blank line” do you mean:

> chew tree with me
>

or

>chew tree with me

>

? I’m assuming it’s the first, since nothing in the code you provided suggests it would be the second.

Writing in Inform: New Actions

When you create an action, 3 rulebooks are created, e.g., Check Chewing, Carry Out Chewing, Report Chewing. There are 3 other action rulebooks that are followed for all actions except out of world actions: Before, Instead, After. And a few other action-processing rules…

The order is Before rules, then visibility (if this action was defined as requiring light, do we have light? n.b.: this does not have to do with saying “applying to a visible thing” in the action definition), accessibility (if this action was defined as requiring a touchable thing, the default if you just say “thing”, can the player touch the thing) and carrying requirement rules (if the action was defined as applying to a carried thing, is the player carrying the thing).

Then the Instead Rules. If an Instead rule triggers, the default is that the action fails unless the rule includes continue the action (that’s why you don’t get to any After rules). After Instead are the Check rules.

The action might fail during any of those. The visibility, accessibility, and carrying requirements rules are all about testing whether the action should fail. The intent of the Check rulebook is that that’s where you put tests to see if something fails.

But once you’re beyond the Check rulebook and into the next, the Carry out rules, the action is a success by definition.

With new actions, there’s simply no output by default. Unless a Before or Instead rule causes some output, or there’s an error message from one of the tests between Before or Instead, it’ll say nothing. So the absence of output you’re seeing is typically an action succeeding, but having no Report rules defined (though you could write a Before or Instead or Check rule that could make it fail without output if you tried.)

So rather than thinking of it as “say something unless there would be no output” it might be easier to think of it as: “say something or not” knowing that not saying anything is the default.

You might want to personalize things with individual messages per action, but if you really want a default “That failed”, then when you define new actions you can make them a kind of action (no relation to the more usual meaning of “kind” in I7).

Chewing is a default-message action.
Crumping is a default-message action.
[...]
After a default-message action, say "That failed."

It’s a lie – so far as I7’s concerned the action succeeded. But you’re the author and you get to lie as much as you want.

Of course, the above is not especially shorter, and perhaps less clear than just:

check chewing: instead say "That failed."
check crumping: instead say "That failed."

These both assume that the successful version is implemented with, say an Instead or Before rule redirecting to another action, as in your example.

Then, just to wrap up, after the Carry out rules are the After rules. Like Instead, these default to ending the action immediately if they don’t include continue the action. And, finally, the Report rules, typically the place where output for successful actions lives.

Guidelines on how to write rules about actions

Thank you, report seems to be what I need.

Report chewing it with: instead say "That failed."

works for my purposes so far. I’m not sure if I will run into more issues.

You said that this contains output for successful actions, though? So in this case, is the idea that reporting the output is successful, even though the action itself failed or did nothing?

Btw, by blank line I mean that the parser output is empty, not that there is an extra line break.

I’ll call attention to Success and Failure:

“Success” and “failure” are technical terms here: they do not mean that the player has or hasn’t got what he wanted.

When you refer to success or failure of player actions when talking about designing the situations and obstacles in your game, you would just mean whether the player got what they wanted. But there’s a separate, specific, technical idea of it. If the action was stopped prior to reaching the Carry Out rules, the action failed. Otherwise, it succeeded. No matter what happened in the game (or whether nothing happened) or what was or wasn’t output.

Normally, we never test for it and don’t care. Zarf said “I long ago made the executive decision to never rely on the action success result.” and that’s good enough for me. But if you wanted to, say, make use of Unsuccessful Attempt By rules, that would be a case where success vs failure mattered. That’s why I’m dwelling on the existence of this technical definition: because it can matter.

So Report rules are never reached if an action failed: they can only report on (technically) successful actions.

I said that in acknowledgement of this, from the guidelines on how to write rules about actions I linked to.

if the action is to look at something, then carrying it out is in a sense the same thing as reporting it

Actions whose whole point is to output info like look or inventory do those in Carry Out rules instead of Report rules.

1 Like

In fact, I said that long ago, so the decision is now double-long ago!

I stand by it though.

2 Likes