Commands

Introduction

In Lugdunon, commands are what drive the game state. Any action that occurs should result in a command being generated to be handled in the update loop. Commands are also the method in which the client and server communicate. Commands are specific to a given server, and are loaded from the classpath based on their inclusion in the WORLD/etc/commands.json file.

Commands are referenced in code by their unique command id. Programmatically, commands are referenced by a short int opcode, meaning that commands are limited to at most 2¹⁵-1 (32767). With the exception of of net.lugdunon.command.core.ErrorCommand, net.lugdunon.command.core.GetServerStatusCommand, and net.lugdunon.command.core.ConnectToServerCommand the opcode for a command is dynamically assigned at server start and should never be relied upon to remain the same value across server instances.

A command exists as a single instance, loaded and initialized upon server start for server-side commands and upon client connect for client-side commands. Commands are referenced in code via their command id, a unique string that identifies a specific command. How to call commands on the server and client will be examined towards the end of this article.

A quick word about DataView, EnhancedDataInput/OutputStream, and String length

All traffic that passes between the client and server via commands is packaged and unpackaged using an extended version of the default DataView on the client and extended versions of the java.io.DataInputStream and java.io.DataOutputStream on the server side. The enhancements amount to providing an analogue of the java data io functionality in the client as well as providing a method for writing UTF strings with lengths > 2¹⁶-1. Listed below are the mappings of calls between the client and the server:

Client (Dataview)		Server (net.lugdunon.io.EnhancedCharacterInputStream)
readInt8()	⇄	readByte()
readUint8()	⇄	readUnsignedByte()
readInt16()	⇄	readShort()
readUint16()	⇄	readUnsignedShort()
readInt32()	⇄	readInt()
readUint32()	⇄	readInt()
readFloat32()	⇄	readFloat()
readFloat64()	⇄	readDouble()
readBoolean()	⇄	readBoolean()
readString()	⇄	readUTF()
readLargeString()	⇄	readLargeUTF()

Client (Dataview)		Server (net.lugdunon.io.EnhancedCharacterOutputStream)
writeInt8()	⇄	writeByte()
writeUint8()	⇄	writeUnsignedByte()
writeInt16()	⇄	writeShort()
writeUint16()	⇄	writeUnsignedShort()
writeInt32()	⇄	writeInt()
writeUint32()	⇄	writeInt()
writeFloat32()	⇄	writeFloat()
writeFloat64()	⇄	writeDouble()
writeBoolean()	⇄	writeBoolean()
writeString()	⇄	writeUTF()
writeLargeString()	⇄	writeLargeUTF()

One last thing to note. When determining the actual length (in bytes) of a string as it is written using the DataView.writeString() and DataView.writeLargeString() it is necessary to use the String.lengthInBytes() and String.largeLengthInBytes() functions to determine the actual length.

Client Side Command API

On the client-side, commands extend the net.lugdunon.command.core.Command javascript class. There are a few default functions that require overriding:

100. /**
101.  * Accepts a parameter containing any data used to populate this command call.
102.  *
103.  * @param {Object} initData
104.  */
105. net.lugdunon.command.core.Command.prototype.opInit=function(initData){};
106.  
107. /**
108.  * Returns the length (in bytes) of the command call's data.
109.  *
110.  * @returns {Number}
111.  */
112. net.lugdunon.command.core.Command.prototype.getCommandLength=function(){return(0);};
113.  
114. /**
115.  * Where the command call's data is actually written to the dataView object passed in.
116.  *
117.  * @param {DataView} dataView
118.  */
119. net.lugdunon.command.core.Command.prototype.buildCommand=function(dataView){};
120.  
121. /**
122.  * Where a command that has come in from the server is processed. The response parameter is a DataView object for reading in the response data.
123.  *
124.  * @param {DataView} response
125.  */
126. net.lugdunon.command.core.Command.prototype.commandReponse=function(response){};

Server Side Command API

On the server-side, commands extend the net.lugdunon.command.core.Command java class. There are a few abstract methods that require implementing:

100. /**
101.  * Returns the length (in bytes) of the command call�s data.
102.  *
103.  * @return {int}
104.  */
105. public abstract int getCommandLength();
106.  
107. /**
108.  * Returns the unique string value that identifies this command.
109.  *
110.  * @return {String}
111.  */
112. public abstract String getCommandId();
113.  
114. /**
115.  * Returns a string containing the display name of the command.
116.  *
117.  * @return {String}
118.  */
119. public abstract String getName();
120.  
121. /**
122.  * Returns a string containing a short description of the command.
123.  *
124.  * @return {String}
125.  */
126. public abstract String getDescription();
127.  
128. /**
129.  * Returns the true if the command has a client side counterpart.
130.  * The server will not look for a client-side asset for this command when sending the commands code to the client on initial connect.
131.  *
132.  * @return {boolean}
133.  */
134. public abstract boolean hasClientSide();
135.  
136. /**
137.  * Handles the actual processing of the command and its data.
138.  *
139.  * @param request - Provides access to the EnhancedDataInputStream via getData() and (if the command originated from a client) the CommandWebSocket where the command originated via getOrigin().
140.  *
141.  * @throws IOException
142.  * @throws ConsoleFiredCommandNotSupportedException
143.  */
144. public abstract void handle(CommandRequest request) throws IOException, ConsoleFiredCommandNotSupportedException;

Console Fired Commands

Console fired commands are a special subset of commands that are initiated via the client-side console. Console commands consist of an initial command identifier, called an opCodeAlias, that always begins with a ‘/’ character. For a full listing of console commands, check the Console Commands section. On the client-side, commands that are capable of being fired via the console must extend the net.lugdunon.command.core.console.ConsoleFiredCommand class and override the following functions:

100. /**
101.  * Evaluates the passed in opCodeAlias and determines if this command is a match.
102.  *
103.  * For Example, if the console line is '/df impassable' the value of opCodeAlias will be 'df'.
104.  *
105.  * @param opCodeAlias - the opCodeAlias, minus the '/' to be checked.
106.  * @returns {Boolean} - true if the opCodeAlias matches this command.
107.  */
108. net.lugdunon.command.core.console.ConsoleFiredCommand.prototype.matchesConsoleOpCodeAlias=function(opCodeAlias)
109. {
110.         return(false);
111. };
112.  
113. /**
114.  * If this command is to be handled on the client side, then this function must be implemented.
115.  * It should evaluate the passed in data as the console line minus the command opCodeAlias.
116.  *
117.  * For Example, if the console line is '/df impassable' the value of consoleMessage will be 'impassable'.
118.  *
119.  * @param consoleMessage - the console message minus the opCodeAlias
120.  */
121. net.lugdunon.command.core.console.ConsoleFiredCommand.prototype.handle=function(consoleMessage)
122. {
123.         ;
124. };

On the server-side, commands that are capable of being fired via the console must extend the net.lugdunon.command.core.console.ConsoleFiredCommand abstract class and implement the following functions:

100. /**
101.  * Evaluates the passed in opCodeAlias and determines if this command is a match.
102.  *
103.  * For Example, if the console line is '/df impassable' the value of opCodeAlias will be 'df'.
104.  *
105.  * @param {String} opCodeAlias - the opCodeAlias, minus the '/' to be checked.
106.  * @returns {Boolean} - true if the opCodeAlias matches this command.
107.  */
108. public abstract boolean matchesConsoleOpCodeAlias(String opCodeAlias);
109.  
110. /**
111.   * Evaluates the passed in data as the console line minus the command opCodeAlias.
112.   *
113.   * For Example, if the console line is '/df impassable' the value of consoleMessage will be 'impassable'.
114.   *
115.   * @param {CommandRequest} request - the request where this command originated.
116.   * @param {String} consoleMessage - the console message minus the opCodeAlias.
117.   */
118. public abstract void handle(CommandRequest request, String consoleMessage) throws IOException;

GM Only Commands

GM only commands are commands that are executable by a player only if they have GM status. Such a command needs but to extend the net.lugdunon.command.core.gm.GmOnlyCommand java class instead of net.lugdunon.command.core.Command. And implement the handleAsOp(CommandRequest request) method instead of the handle(CommandRequest request).The client is agnostic on this point so nothing needs to be done there.

100. /**
101.  * Commands that are restricted to players that have GM privileges should implement this method
102.  * instead of handle(CommandRequest request). This method will only be called if the player has
103.  * GM privileges.
104.  *
105.  * @param request - Provides access to the EnhancedDataInputStream via getData() and (if the
106.  * command originated from a client) the CommandWebSocket where the command originated via getOrigin().
107.  *
108.  * @throws IOException
109.  */
110. public abstract void handleAsOp(CommandRequest request) throws IOException;

100.  

100.