Denizen API

From Citizens Wiki

Revision as of 21:45, 8 November 2020 by Mcmonkey (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

For more up-to-date information and full details on specific features (individual commands or tags, for example), check the Meta Documentation.

If you want a full tutorial to help get you set up, check out the Tutorial Videos on youtube or the Beginner's Guide text website.

If you need quick help, visit our Discord group.




This wiki is outdated, please view the tutorial videos/guide, meta documentation, or Discord group (all linked above) for up-to-date information!





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()