ICommandBuilder - Revision history

Meduris: changed command classes to public (Staxel won't be able to access internal classes)

2018-02-06T16:13:45Z

changed command classes to public (Staxel won't be able to access internal classes)

TheMogMiner: Correcting some important EntityId-related info.

2018-02-03T16:16:37Z

Correcting some important EntityId-related info.

TheMogMiner: Wording fix.

2018-02-03T16:13:54Z

Wording fix.

TheMogMiner: Minor clarity edit.

2018-02-03T11:02:39Z

Minor clarity edit.

TheMogMiner: Added a basic example of how to use the PublicCredentials class via the ClientServerConnection class in ICommandBuilder.

2018-02-02T21:14:00Z

Added a basic example of how to use the PublicCredentials class via the ClientServerConnection class in ICommandBuilder.

TheMogMiner: Some changes to spacing.

2018-02-02T18:34:52Z

Some changes to spacing.

TheMogMiner: Added an additional example, isOnline, to demonstrate the use of ICommandsApi.

2018-02-02T18:33:28Z

Added an additional example, isOnline, to demonstrate the use of ICommandsApi.

TheMogMiner: Initial revision, containing a simple /echo command.

2018-02-02T17:20:17Z

Initial revision, containing a simple /echo command.

New page

[[Category:Modding]]

ICommandBuilder is the basic interface for server-side commands. On startup, Staxel will use the C# class loader to obtain a list of all classes which implement the ICommandBuilder interface. Therefore, no special code is necessary in order to register your command or commands: Simply ensure that each class implements ICommandBuilder, fill out the appropriate methods, and Staxel will handle the rest.

= The Methods =

* <code><nowiki>Kind</nowiki></code> is a public string getter which returns a string containing command itself.
* <code><nowiki>Usage</nowiki></code> is a public string getter which returns a string containing [[Translations|translation]] key for an explanation on how to use the command. This will be displayed when invoking the <code>/help</code> command.
* <code><nowiki>Public</nowiki></code> is a public bool getter which returns if the command can be used by public users (true) or only administrators (false).
* <code><nowiki>Execute</nowiki></code> is a public method which will execute the action of the command itself. It is passed the command string pre-broken into an array of tokens based on using space as a delimiter, the [[DataPacket]] data blob itself, the current [[ClientServerConnection]], and the [[ICommandsApi]] interface. It is expected to return a string containing the [[Translations|translation]] key for the response text to print to the console, as well as to initialize an array of strings in the event that the localized response contains one or more parameters to fill in at run-time. In the event that no parameters are needed, this array should be initialized to a 0-length array of objects.

= Example: Echo Command =

One of the most basic things that one can do is implement a command which simply echoes back what was typed to the user who invoked the command. Here is the code to do exactly that:

<pre>
using Plukit.Base;
using Staxel.Commands;
using Staxel.Server;

namespace SampleCommands
{
internal class EchoCommand : ICommandBuilder
{
public string Kind => "echo";

public string Usage => "mods.sampleCommands.echo.description";

public bool Public => true;

public string Execute(string[] bits, Blob blob, ClientServerConnection connection, ICommandsApi api, out object[] responseParams)
{
responseParams = new object[1];
string concatenatedBits = "";
for (int i = 1; i < bits.Length; i++)
{
concatenatedBits += bits[i];
if (i < (bits.Length - 1))
concatenatedBits += " ";
}
responseParams[0] = concatenatedBits;
return "mods.sampleCommands.echo.response";
}
}
}
</pre>

Likewise, here is the corresponding [[Translations|.lang]] file:

<pre>
language.code=en-GB
language=English

mods.sampleCommands.echo.description=^c:F2E200;echo ^c:FFFFFF;(optional)parameters
mods.sampleCommands.echo.response=You wrote: {0-bits}
</pre>

As the code implies, the first token in the <code><nowiki>bits</nowiki></code> array is always the command itself. Thus, the processing of command parameters should always begin with the second item in the array (index 1).

In this example, we simply concatenate each command parameter, inserting a space after each parameter except for the last one. Since the response has one string replacement, we initialize <code><nowiki>responseParams</nowiki></code> to a string array of length 1, and store the concatenated string there. Lastly, since the command cannot fail, we always return the response [[Translations|translation]] key.

@@ Line 20: / Line 20: @@
 namespace SampleCommands
+{
-     internal class EchoCommand : ICommandBuilder
+     public class EchoCommand : ICommandBuilder
+     {
          public string Kind => "echo";
@@ Line 78: / Line 78: @@
 namespace SampleCommands
+{
-     internal class IsOnlineCommand : ICommandBuilder
+     public class IsOnlineCommand : ICommandBuilder
+     {
          public string Kind => "isOnline";
@@ Line 143: / Line 143: @@
 namespace SampleCommands
+{
-     internal class MyInfoCommand : ICommandBuilder
+     public class MyInfoCommand : ICommandBuilder
+     {
          public string Kind => "myInfo";

@@ Line 67: / Line 67: @@
 = Example: isOnline Command =
-One of the basic features of the <code><nowiki>ICommandsApi</nowiki></code> API is the ability to look up an [[Entity]] by its ID. In this case, a player Entity's ID is the player's username. This function is, aptly enough, called <code><nowiki>FindPlayerEntityId</nowiki></code>. It accepts a string as its only parameter, and returns an [[Entity]] instance if successful, or Null if not.
+One of the basic features of the <code><nowiki>ICommandsApi</nowiki></code> API is the ability to look up a player [[EntityId]] by name. This function is, aptly enough, called <code><nowiki>FindPlayerEntityId</nowiki></code>. It accepts a string as its only parameter, and returns an [[EntityId]] if successful, or Null if not.
 Using this knowledge as well as the previous example, we can write a simple command to check if a player is online:

@@ Line 67: / Line 67: @@
 = Example: isOnline Command =
-One of the basic features of the <code><nowiki>ICommandsApi</nowiki></code> API is the ability to look up an [[Entity]] by its ID. In this case, a player Entity is the player's username. This function is, aptly enough, called <code><nowiki>FindPlayerEntityId</nowiki></code>. It accepts a string as its only parameter, and returns an [[Entity]] instance if successful, or Null if not.
+One of the basic features of the <code><nowiki>ICommandsApi</nowiki></code> API is the ability to look up an [[Entity]] by its ID. In this case, a player Entity's ID is the player's username. This function is, aptly enough, called <code><nowiki>FindPlayerEntityId</nowiki></code>. It accepts a string as its only parameter, and returns an [[Entity]] instance if successful, or Null if not.
 Using this knowledge as well as the previous example, we can write a simple command to check if a player is online:

@@ Line 64: / Line 64: @@
 [[File:Echo.png]]
 = Example: isOnline Command =
@@ Line 77: / Line 78: @@
 namespace SampleCommands
+{
-     internal class EchoCommand : ICommandBuilder
+     internal class IsOnlineCommand : ICommandBuilder
+     {
          public string Kind => "isOnline";
@@ Line 126: / Line 127: @@
 [[File:isOnline.png]]

@@ Line 5: / Line 5: @@
 = The Methods =
 * <code><nowiki>Kind</nowiki></code> is a public string getter which returns a string containing command itself.
-* <code><nowiki>Usage</nowiki></code> is a public string getter which returns a string containing [[Translations|translation]] key for an explanation on how to use the command. This will be displayed when invoking the <code>/help</code> command.
+* <code><nowiki>Usage</nowiki></code> is a public string getter which returns a string containing the [[Translations|translation]] key for an explanation on how to use the command. This will be displayed when invoking the <code>/help</code> command.
 * <code><nowiki>Public</nowiki></code> is a public bool getter which returns if the command can be used by public users (true) or only administrators (false).
 * <code><nowiki>Execute</nowiki></code> is a public method which will execute the action of the command itself. It is passed the command string pre-broken into an array of tokens based on using space as a delimiter, the [[DataPacket]] data blob itself, the current [[ClientServerConnection]], and the [[ICommandsApi]] interface. It is expected to return a string containing the [[Translations|translation]] key for the response text to print to the console, as well as to initialize an array of strings in the event that the localized response contains one or more parameters to fill in at run-time. In the event that no parameters are needed, this array should be initialized to a 0-length array of objects.
@@ Line 59: / Line 59: @@
 As the code implies, the first token in the <code><nowiki>bits</nowiki></code> array is always the command itself. Thus, the processing of command parameters should always begin with the second item in the array (index 1).
-In this example, we simply concatenate each command parameter, inserting a space after each parameter except for the last one. Since the response has one string replacement, we initialize <code><nowiki>responseParams</nowiki></code> to a string array of length 1, and store the concatenated string there. Lastly, since the command cannot fail, we always return the response [[Translations|translation]] key.
+In this example, we simply concatenate each command parameter, inserting a space after each parameter except for the last one. Since the response has one string replacement, we initialize <code><nowiki>responseParams</nowiki></code> to an object array of length 1, and store the concatenated string there. Lastly, since the command cannot fail, we always return the response [[Translations|translation]] key.
 Here is a screenshot of the results of the above command:

@@ Line 1: / Line 1: @@
 [[Category:Modding]]
 ICommandBuilder is the basic interface for server-side commands. On startup, Staxel will use the C# class loader to obtain a list of all classes which implement the ICommandBuilder interface. Therefore, no special code is necessary in order to register your command or commands: Simply ensure that each class implements ICommandBuilder, fill out the appropriate methods, and Staxel will handle the rest.
 = The Methods =
 * <code><nowiki>Kind</nowiki></code> is a public string getter which returns a string containing command itself.
 * <code><nowiki>Usage</nowiki></code> is a public string getter which returns a string containing [[Translations|translation]] key for an explanation on how to use the command. This will be displayed when invoking the <code>/help</code> command.
@@ Line 13: / Line 11: @@
 = Example: Echo Command =
 One of the most basic things that one can do is implement a command which simply echoes back what was typed to the user who invoked the command. Here is the code to do exactly that:
@@ Line 47: / Line 44: @@
+}
 </pre>
 Likewise, here is the corresponding [[Translations|.lang]] file:
@@ Line 62: / Line 60: @@
 In this example, we simply concatenate each command parameter, inserting a space after each parameter except for the last one. Since the response has one string replacement, we initialize <code><nowiki>responseParams</nowiki></code> to a string array of length 1, and store the concatenated string there. Lastly, since the command cannot fail, we always return the response [[Translations|translation]] key.
 Here is a screenshot of the results of the above command:
@@ Line 69: / Line 66: @@
 = Example: isOnline Command =
 One of the basic features of the <code><nowiki>ICommandsApi</nowiki></code> API is the ability to look up an [[Entity]] by its ID. In this case, a player Entity is the player's username. This function is, aptly enough, called <code><nowiki>FindPlayerEntityId</nowiki></code>. It accepts a string as its only parameter, and returns an [[Entity]] instance if successful, or Null if not.