Actions

Actions are commands that can be added (and removed) from interactives. You can add any command to an interactive via the addAction method in the interactive's action manager. You pass it the command string and a method that should be called when the player enters that command. The method will be passed the command typed by the player as well as any arguments. For example, assume you wanted to implement a jump command in a room with a cliff. You would first create a method somewhere designed to implement the command:

   def jumpCommand(self, commandString, arguments):
      stdlib.thisPlayer().write("You jump off the cliff!")
      return 1  #success

Then you register the method with the interactive's action manager:

   anInteractive.getActionManager().addAction("jump", foo.jumpCommand)

You can register multiple commands for the same method, as well:

   anInteractive.getActionManager().addAction("leap", foo.jumpCommand)

To remove the commands (when the player leaves the room, for example), use the removeAction method:

   anInteractive.getActionManager().removeAction("jump", foo.jumpCommand)
   anInteractive.getActionManager().removeAction("leap", foo.jumpCommand)

You have to pass the remove method both the command and the method because it's possible for multiple methods to be specified for a single command. In that case, the method most recently added is called first. If it fails, then previously added methods for that command are given a chance to execute. For example, suppose you were carrying a scroll with a read command. Then you walk into a room with a sign that also supports a read command. The sign's method would be invoked first and, if it failed, then the scroll's read method would be invoked.

Given the above, it's important to note when your command has failed. You do this simply by returning 0 (false). Quite often you want to display a failure message, in which case you should use the notifyFail method in the action manager:

   def jumpCommand(self, commandString, arguments):
      if not arguments or arguments != "off cliff":
	 stdlib.thisPlayer().getActionManager().notifyFail("Jump off what?")
	 return 0 #failure
      else:
	 stdlib.thisPlayer().write("You jump off the cliff!")
	 return 1 #success

The reason you use notifyFail instead of just writing the failure message is because the action manager will give other methods for that command a chance to run. The failure message will only be displayed if no method succeeds. Note that if you just return 0 without setting a failure message then the player will just see What? if no other method succeeds.

See the documentation for the mudlib.living.ActionManager class for more details.