Denizen API: Difference between revisions

From Citizens Wiki

(Created page with "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, D...")
 
No edit summary
 
(9 intermediate revisions by one other user not shown)
Line 1: Line 1:
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 Script Commands =
For more up-to-date information and full details on specific features (individual commands or tags, for example), check the [https://one.denizenscript.com/denizen/cmds/ Meta Documentation].
 
If you want a full tutorial to help get you set up, check out the [https://one.denizenscript.com/denizen/cmds/denizen/vids Tutorial Videos] on youtube or the [https://guide.denizenscript.com/ Beginner's Guide] text website.
 
If you need quick help, visit our [https://discord.gg/Q6pZGSR Discord group].
 
<br><br><br>
 
<span style="font-family:natalya-alternate-one; font-size:300%; margin-right:-7px; margin-left:-10px;">This wiki is outdated, please view the tutorial videos/guide, meta documentation, or Discord group (all linked above) for up-to-date information!</span>
 
<br><br><br>
 
 
<s>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 ===
=== 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 basically an extension of this base ScriptCommand class, and each time your command is called in for execution, it's this class that is run.
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.
 
* <code>.getCommand()</code> of course, contains a <code>String</code> 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 <code>ENGAGE</code> command for a useful example of utilizing this information.
 
* <code>.arguments()</code> has a <code>String[]</code> of all the arguments the player provided.
*: This pre-formats arguments that have used quotes, for instance, if the script command is <code>YOURCOMMAND argument1 argument2 'this is argument3'</code>, this object would have 3 items in the array.
 
* <code>.sendingQueue()</code> returns a <code>QueueType</code> of either <code>QueueType.TRIGGER</code>, <code>QueueType.TASK</code>, or <code>QueueType.ACTIVITY</code>
*: This contains the type of queue that sent the command. If the command was issues from a TASK script, for example, this would contain <code>QueueType.TASK</code>
 
* <code>.getScript()</code> contains a <code>String</code> name of the script.
 
* <code>.getStep()</code> contains an <code>Integer</code> of the step of the script.
*: Note that if this was a <code>TASK</code> script, for example, this would be null.
 
* <code>.getTriggerType()</code> contains a <code>TriggerType</code> of the script, that is, what type of 'TRIGGER' triggered it.
*: This will be either <code>TriggerType.ATTACK</code>, <code>TriggerType.CLICK</code>, <code>TriggerType.CHAT</code>, <code>TriggerType.PROXIMITY</code>, <code>TriggerType.TASK</code>, or <code>TriggerType.LOCATION</code>. More types are likely to be implemented.
 
* <code>.getPlayer()</code> contains a <code>Player</code> object of the triggering Player, if triggered by a player, that is.
*: If triggered from a <code>ACTIVITY</code> script, this would be null.


==== Barebones ScriptCommand Class ====
* <code>.getDenizen()</code> contains a <code>NPC</code> Citizens2 object, again, if a NPC object is sent with it.
*: If triggered from a <code>TASK</code> script, this is null.


The following is a Hello World example of a ScriptCommand.
* <code>.getInitiatedTime()</code> contains a <code>Long System.currentTimeMillis()</code> of the system time in which it was sent to your Command for processing.


<code>
* <code>.getDelayedTime()</code> contains a <code>Long System.currentTimeMillis()</code> of the system time that was set by using the <code>.setDelay(Long newTime)</code>. This is null by default. Check out the <code>WAIT</code> command for a functional example of usage.


* <code>.getTexts()</code> contains a <code>String[]</code> of 2 elements.
*: First element, <code>.getTexts[0]</code> for example, has the 'raw text' that the player typed to initiate the command. Second element, <code>.getTexts[1]</code> contains the 'friendly text', most likely the Chat Trigger that was set in the script. As you can probaly guess, if <code>.getTriggerType()</code> isn't a <code>TriggerType.CHAT</code> this will most likely be null.


</code>
To summarize, here's a list of methods that can be used to get information about the ScriptCommand.
* <code>.getCommand()</code> <code>.arguments()</code> <code>.sendingQueue()</code> <code>.getScript()</code> <code>.getStep()</code> <code>.getTriggerType()</code> <code>.getPlayer()</code> <code>.getDenizen()</code> <code>.getInitiatedTime()</code> <code>.getDelayedTime()</code> <code>.getTexts()</code></s>

Latest revision as of 21:45, 8 November 2020

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