A command should return a result that indicates how successful it was. First, some terms so we know what we are talking about.

"verb"

Verbs are used by commands; they are attributes of objects, for example the "take" attribute is used by the TAKE command. They are called verbs, following the convention of Quest 5 somewhat. A verb should return true if it was successful and the game world changed (the item was picked up), and false if it did not happen, and the world was not updated (the item could not be picked up).

The important point is that if a verb returns false, the game will not update the world (for example the panes on the left) and turnscripts will not run (unless the command involves multiple items and another item returns true).

"player"

A text adventure involves two people. One is sat at a computer typing commands; this is the user. The other lives in the game world, and acts according to the commands the user types. This is the player character, or PC for short or more often just player.

"meta-command"

Some commands do not affect the player. If the user types HELP, the player is not affected, and knows nothing about the command or response, and for that reason the response is printed using the metamsg function to differentiate it. This is a meta-command. This is also a consideration with regards to the result of a command.

Results

The result of a command should be an integer (if a Boolean is used, a debug message will be given as a warning), but should be indicated by a constant. If the user attempts a command with multiple objects, the returned result should be the best, so if any of them on their own would rate SUCCESS, then the overall result in SUCCESS.

There are four results Quest will recognise. Each of these is set to be a non-zero integer.

world.SUCCESS

The command was a success (in some sense) and the game world has changed. The game world will be updated and turnscripts will run.

world.SUCCESS_NO_TURNSCRIPTS

The command was a success; however the game world has not changed and in game no time has passed, so turnscripts should not be run. Meta-commands such as HELP, TERSE and SPOKEN are obvious examples.

I have chosen to make LOOK, INVENTORY and MAP return this on the basis that the player character should know where she is; the commands serve to jog the user's memory, not to have the player character do something. Set TURNSCRIPT_AFTER_LOOK to true in settings.js otherwise.

world.FAILED

The command was understood but the user is trying to do something that is not allowed, such as go though an exit that does not exist, put an item in something that is not a container.

I have taken the view that the player character knows there is no door, knows the item is not a container, so no time passes in game, and so turnscripts should not run, no time has passed.

You can change that by setting FAILS_COUNT_AS_TURNS to true in settings.js.

More borderline examples are trying to go through a locked door; does the PC spent time trying the door to find it is locked? It is arguable.

world.PARSER_FAILURE

The parser has failed to understand what the user typed. The game world is not changed, the game is not updated and turnscripts are not run. Generally commands should not return this - it is used when no command was found.