Denizen API: Difference between revisions

From Citizens Wiki

Line 9: Line 9:
==== What a ScriptCommand holds ====
==== What a ScriptCommand holds ====


ScriptCommands hold data about the situation surrounding the event that activates your command. Which type of script activates your Command, the ScriptCommand can have a multitude of information available.  
ScriptCommands hold data about the situation surrounding the event that activates your command. Which type of script activates your Command, the ScriptCommand can have a multitude of information available. Keep in mind that the ScriptCommand object sent along may not have ALL this information, depending on the circumstances sent.


* <code>.getCommand()</code> of course, contains a <code>String</code> of the name of your command.
* <code>.getCommand()</code> of course, contains a <code>String</code> of the name of your command.

Revision as of 21:33, 5 July 2012

In Denizen, the Script Command system is extensible by design. It's very easy to make your own commands (and soon Requirements) extend the built-in features. On top of that, Denizen has some features available that may be of use to Plugin Developers.

Building your own Commands

The ScriptCommand Object

When Denizen reads scripts, each line is turned into a SciptCommand object that contains the command, the arguments, and various other data and objects, as described below. Your command is an extension of this base Command class, and each time your command is called in for execution, it's this class that is executed and handled a ScriptCommand. How the Command uses the ScriptCommand information is of course, up to you.

What a ScriptCommand holds

ScriptCommands hold data about the situation surrounding the event that activates your command. Which type of script activates your Command, the ScriptCommand can have a multitude of information available. Keep in mind that the ScriptCommand object sent along may not have ALL this information, depending on the circumstances sent.

  • .getCommand() of course, contains a String of the name of your command.
    Useful if your command module contains instructions for more than one command. You can register multiple commands to your module, as discussed later in this document. See the ENGAGE command for a useful example of utilizing this information.
  • .arguments() has a String[] of all the arguments the player provided.
    This pre-formats arguments that have used quotes, for instance, if the script command is YOURCOMMAND argument1 argument2 'this is argument3', this object would have 3 items in the array.
  • .sendingQueue() returns a QueueType of either QueueType.TRIGGER, QueueType.TASK, or QueueType.ACTIVITY
    This contains the type of queue that sent the command. If the command was issues from a TASK script, for example, this would contain QueueType.TASK
  • .getScript() contains a String name of the script.
  • .getStep() contains an Integer of the step of the script.
    Note that if this was a TASK script, for example, this would be null.
  • .getTriggerType() contains a TriggerType of the script, that is, what type of 'TRIGGER' triggered it.
    This will be either TriggerType.ATTACK, TriggerType.CLICK, TriggerType.CHAT, TriggerType.PROXIMITY, TriggerType.TASK, or TriggerType.LOCATION. More types are likely to be implemented.
  • .getPlayer() contains a Player object of the triggering Player, if triggered by a player, that is.
    If triggered from a ACTIVITY script, this would be null.
  • .getDenizen() contains a NPC Citizens2 object, again, if a NPC object is sent with it.
    If triggered from a TASK script, this is null.
  • .getInitiatedTime() contains a Long System.currentTimeMillis() of the system time in which it was sent to your Command for processing.
  • .getDelayedTime() contains a Long System.currentTimeMillis() of the system time that was set by using the .setDelay(Long newTime). This is null by default. Check out the WAIT command for a functional example of usage.
  • .getTexts() contains a String[] of 2 elements.
    First element, .getTexts[0] for example, has the 'raw text' that the player typed to initiate the command. Second element, .getTexts[1] contains the 'friendly text', most likely the Chat Trigger that was set in the script. As you can probaly guess, if .getTriggerType() isn't a TriggerType.CHAT this will most likely be null.

To summarize, here's a list of methods that can be used to get information about the ScriptCommand.

  • .getCommand() .arguments() .sendingQueue() .getScript() .getStep() .getTriggerType() .getPlayer() .getDenizen() .getInitiatedTime() .getDelayedTime() .getTexts()