Denizen API Command Template: Difference between revisions

From Citizens Wiki
Line 1: Line 1:
=== YourCommand extends AbstractCommand ===
Denizen is extensible! In addition to Triggers and Requirements(soon!), an API is being provided to help you make custom Script Commands in your project! Have a neat idea for a command? Have a better way to STRIKE a player? (MEGASTRIKE command, anybody?)


Below is a command template, ready to copy/paste into your project. You can also view a copy on [http://pastie.org/4368657 Pastie], which is color coded.
Keep reading!


==== Command Template ====


<pre>
=== The ScriptEntry object ===
package net.aufdemrand.denizen.commands.core;


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


import org.bukkit.Location;


import net.aufdemrand.denizen.bookmarks.BookmarkHelper.BookmarkType;
=== YourCommand extends AbstractCommand ===
import net.aufdemrand.denizen.commands.AbstractCommand;
import net.aufdemrand.denizen.scripts.ScriptEntry;
import net.citizensnpcs.command.exception.CommandException;


/**
The first thing you need is a custom command class that extends the Denizen AbstractTrigger. This contains the method called when it's time for your command to be executed. This is called every-single-time a script contains your command.
* Your command!
* This class is a template for a Command in Denizen.
*
* @author You!
*/


public class SampleCommand extends AbstractCommand {


/* COMMAND_NAME [TYPICAL] (ARGUMENTS) */
==== Example Command ====


/*
I think sometimes the easiest way to work is to see an example. View a copy of the STRIKE command on Pastie.org for a very simple command. For more examples, you can always [
* Arguments: [] - Required, () - Optional
* [TYPICAL] argument with a description if necessary.
* (ARGUMENTS) should be clear and concise.
* 
* Modifiers:
* (MODIFIER:VALUE) These are typically advanced usage arguments.
* (DURATION:#) They should always be optional. Use standard modifiers
*  already established if at all possible.
* 
* Example Usage:
* COMMAND_NAME VALUE
* COMMAND_NAME DIFFERENTVALUE OPTIONALVALUE
* COMMAND_NAME ANOTHERVALUE 'MODIFIER:Show one-line examples.'
*
*/


@SuppressWarnings("unused") // This should be removed in your code.
@Override
// This is the method that is called when your command is ready to be executed.
public boolean execute(ScriptEntry theEntry) throws CommandException {


/* Initialize variables */
==== Command Template ====
 
    // Typically initialized as null and filled as needed. Remember: theEntry
    // contains some information passed through the execution process.
Boolean requiredVariable = null;
Location sampleBookmark = null;
/* Match arguments to expected variables */
if (theEntry.arguments() != null) {
for (String thisArgument : theEntry.arguments()) {
// Do this routine for each argument supplied.
if (plugin.debugMode) plugin.getLogger().info("Processing command " + theEntry.getCommand() + " argument: " + thisArgument);
 
// Includes are some typical arguments. Modify/add code to handle your command needs.
// If argument is a number.
if (thisArgument.matches("((-|\\+)?[0-9]+(\\.[0-9]+)?)+")) {
// Insert code here.


}
[http://pastie.org/4368657 View a command template copy on Pastie.org] for a copy/paste of the skeleton of a custom denizen commmand.
// If argument is a valid bookmark, set location.
else if (plugin.bookmarks.exists(theEntry.getDenizen(), thisArgument)) {
if (plugin.debugMode) plugin.getLogger().log(Level.INFO, "...matched bookmark '" + thisArgument + "'.");
sampleBookmark = plugin.bookmarks.get(theEntry.getDenizen(), thisArgument, BookmarkType.LOCATION);
} else if (thisArgument.split(":").length == 2) {
if (plugin.bookmarks.exists(thisArgument.split(":")[0], thisArgument.split(":")[1]))
if (plugin.debugMode) plugin.getLogger().log(Level.INFO, "...matched bookmark '" + thisArgument.split(":")[0] + "'.");
sampleBookmark = plugin.bookmarks.get(thisArgument.split(":")[0], thisArgument.split(":")[1], BookmarkType.LOCATION);
}
// If argument is a modifier.
else if (thisArgument.toUpperCase().contains("MODIFIER:")) {
if (plugin.debugMode) plugin.getLogger().log(Level.INFO, "...matched modifier '" + thisArgument.split(":")[0].toUpperCase() + "'.");


// Insert code here.
}
// If can't match to anything...
// This isn't always possible, depending on the arguments your command uses, but nice if you can.
else {
if (plugin.debugMode) plugin.getLogger().log(Level.INFO, "...unable to match argument!");
}
}
}


/* Execute the command, if all required variables are filled. */
==== ScriptEntry hold runtime data ====
if (requiredVariable != null) {
// Execution process.
// Do whatever you want the command to do, here.
/* Command has sucessfully finished */
return true;
}
// else...
/* Error processing */
// Processing has gotten to here, there's probably not been enough arguments.
// Let's alert the console.
if (plugin.debugMode) if (theEntry.arguments() == null)
throw new CommandException("...not enough arguments! Usage: SAMPLECOMMAND [TYPICAL] (ARGUMENTS)");
return false;
}


  // You can include more methods in this class if necessary. Or not. :)
The Denizen ScriptEngine and Executer construct and fill a ScriptEntry with information that can be used in your command.


}
{{ScriptEntry
</pre>
|1= .getCommand()
|2= Some more text
|3= 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.
}}

Revision as of 02:38, 1 August 2012

Denizen is extensible! In addition to Triggers and Requirements(soon!), an API is being provided to help you make custom Script Commands in your project! Have a neat idea for a command? Have a better way to STRIKE a player? (MEGASTRIKE command, anybody?)

Keep reading!


The ScriptEntry object

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


YourCommand extends AbstractCommand

The first thing you need is a custom command class that extends the Denizen AbstractTrigger. This contains the method called when it's time for your command to be executed. This is called every-single-time a script contains your command.


Example Command

I think sometimes the easiest way to work is to see an example. View a copy of the STRIKE command on Pastie.org for a very simple command. For more examples, you can always [


Command Template

View a command template copy on Pastie.org for a copy/paste of the skeleton of a custom denizen commmand.


ScriptEntry hold runtime data

The Denizen ScriptEngine and Executer construct and fill a ScriptEntry with information that can be used in your command.

.getCommand()
Some more text
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.
Retrieved from ‘https://wiki.citizensnpcs.co/index.php?title=Denizen_API_Command_Template&oldid=1654’