Intro to the Command File

The recommended way to use Ordinate is with the command file. The command file is a custom format parsed by Ordinate's command parser which specifies all your command's metadata. There are three main elements of the command file: Command bodies, arguments, and tags. The file extension for these is .ordn, and the convention is to call your command file command.ordn and place it in the root of your project's resources folder.

Command Bodies

A command body is how you define commands with the command file. In its simplest form, a command body is just a name followed by some braces:

example {
}

This defines a command called example. Since there's nothing else here, the command has no real properties. It would be run by just typing example (preceded by whatever command prefix your platform uses), but it can't actually do anything yet.

Commands can also have aliases, alternate names they can be run with. These can be specified by separating the names with a comma (but no spaces):

example,ex {
}

This command can be run as example or as ex, but still doesn't do anything.

Arguments

Usually, commands have arguments. To specify them in the command file, you write them as type:name after the name of the command:

example string:arg {
}

Now we've defined a command that has a string argument. If you run it like example abc, the value of that argument will be abc. You can also run it like example "a b c", using quotes to include spaces in the argument, whose value will now be a b c.

The default argument types are strings and most primitives: string, int, float, long, double, boolean.

You can specify multiple arguments just as you'd expect, by appending another before the opening brace of your command body:

example int:a int:b {
}

However, while we can add as many arguments as we want, our command is still not able to actually execute anything. In order to execute anything, we need to learn about tags.

Tags

Tags define additional metadata about a command, like help messages. We can set the help message for our command by using the help tag:

add int:a int:b {
	help = Adds two numbers together
}

There are two ways to use a tag. Most tags take additional values - in this case, the additional value for the help tag is the help message we wrote after the =. Some tags don't take additional values, and are just specified by typing out their name on a line. An example of this is the noHelpSubcommand tag. By default, all commands have an auto-generated help subcommand which will display the help of the command to the user. If you don't want this, you can disable it with the noHelpSubcommand tag:

add int:a int:b {
	help = Adds two numbers together
	noHelpSubcommand
}

For our command to run anything, we're going to need to use the hook tag. This allows the command to hook into our code to run a method when the command is executed, and the arguments will be passed as method parameters.

add int:a int:b {
	help = Adds two numbers together
	hook = add
}

With this hook added, our command specification in the command file is complete. However, the command needs one more thing to actually run: A method to be called to execute the command. To learn more, read on about Method Hooks.