This mod supports user-created commands. A major design goal of version 2.0 was to make implementing these commands as painless as possible. This tutorial is intended to explain the new process in detail.

To add custom commands to the console you'll need a mod that contains two things: your commands' scripts, and the file data/console/commands.csv to register them in. You do not need to add Console.jar to your mod_info.json.

All commands are contained in their own separate Java class. The console mod loads command classes itself, so you can place the java files anywhere in your mod folder you want - data/console/commands is a good choice as data/console already exists to contain commands.csv. Commands can also be in jars (which shouldn't create a dependency as these classes won't be loaded if the console isn't active).

It is _highly_ recommended that you do not place your commands in data/scripts. Starsector will automatically compile any scripts in this directory or its subdirectories, and this will cause errors when the console mod is not active. Placing them elsewhere allows you to bundle commands with a regular mod that will only be loaded if the console is tagged in the launcher.

An example mod that adds several simple commands can be found in the mod folder. If you are the sort who learns best by example, you might find copying from that mod easier than following this tutorial.


 STEP 1 - THE SCRIPT
=====================

(Sometimes you may want to start with the CSV row to get a better idea of how your command will look. Just comment out the row by adding a # at the beginning to prevent the game from loading your command until it's finished)

First off, make sure your IDE has "mods/Console Commands/jars/lw_Console.jar" added as a library. Just follow the same procedure you did to add the Starsector API.

Your commands must implement the org.lazywizard.console.BaseCommand interface. This interface contains only one method (plus two enumerations, see below):
 - public CommandResult runCommand(String args, CommandContext context)

'args' is the argument(s) the player entered after this command, for example the command "addcrew 500 elite" would pass in "500 elite" as a single String. Parsing these arguments into something usable is left up to your script. This argument will never be null - if no arguments were entered, an empty String will be passed in instead.

'context' is a CommandContext passed into your script that tells it where this command was used. CommandContext is the first enum included in BaseCommand, and has the following values (these should be self-explanatory):
 - CAMPAIGN_MAP
 - COMBAT_CAMPAIGN
 - COMBAT_MISSION
 - COMBAT_SIMULATION

runCommand() returns a CommandResult, which is the other enum included in BaseCommand. CommandResult has the following possible values:
 - SUCCESS, returned when a command runs without error.
 - BAD_SYNTAX, return this if the player entered improperly formatted arguments (for example, a String where an number was expected). The console will automatically display the proper syntax to the player if this is returned.
 - WRONG_CONTEXT, if a command was entered in the wrong place (for example, using a campaign-only command during a mission).
 - ERROR, if a command used the proper syntax but still failed for some reason.

If you wish to show output to the player, Console.showMessage(String message) will format and print the String passed in to the player.

With all of this in mind, the basic structure of runCommand() is thus:
 - Check if the context passed in is a valid one for this command. Show a message and return CommandResult.WRONG_CONTEXT if the player used the command in the wrong context (ex: a camapaign travel command during combat).
 - Parse the arguments passed in. If they don't match what is expected, return CommandResult.BAD_SYNTAX (no message is needed; the console mod itself will show the proper syntax from commands.csv if BAD_SYNTAX is returned).
 - Try to run the command with the parsed arguments. If something goes wrong during this stage, show an error message and return CommandResult.ERROR. Console.showException(String message, Exception ex) can be used to display the stack trace of any exceptions to the player.
 - If everything went well, show a message and return CommandResult.SUCCESS

If you need further help implementing your command, the source files for every core command are included in jars/lw_Console.jar (most modern archive programs can open jars) in the org/lazywizard/console/commands directory. You can also find the most up-to-date source code at bitbucket.org/LazyWizard/console-commands/src


 STEP 2 - THE CSV
==================

After you have written your command's code, you will need to register it so the console can find it. Once you've done this, the mod will automatically load your command when the game starts.

Commands are registered in data/console/commands.csv. This CSV file has the following columns:
 - command: This is what the user enters to use your command.
 - class: This points to the script you wrote in Step 1 above. Use the fully-qualified name of your class (ex: data.console.commands.Example). This class can be a loose script or inside a jar, the console will work with both.
 - tags: Used with the 'help' command to find specific commands easier. For example, 'help combat' will return a list of all commands with 'combat' as one of their tags. Tags are solely a convenience feature and don't affect how your command functions in any way.
 - syntax: The basic instructions on how to use this command. Shown when a command returns CommandResult.BAD_SYNTAX, or as part of 'help <command>'
   <> - This denotes a required field
   [] - This denotes an optional field
 - help: Detailed instructions on how to use a command. Shown with 'help <command>'

Command and Class are required. Tags, Syntax and Help can be left empty, but it is HIGHLY recommended that you enter something in these fields unless this command is for personal use only.


(tutorial last updated 2015-12-11)