I-Wars Java Project Protocol

I-Wars Protocol Specification, Version 2.2

Other Resources:

A short, text-based summary of changes to the protocol can be found in the NEWS.txt file. A general description of the project is also available.

What Is Not Covered:

This protocol defines precisely the interactions that should happen between the Monitor and Players. However, Player-to-Player communications are left completely left up to Players. the Directive/Command framework defined here would be completely reasonable for use in a Player-to-Player communication protocol.

Player-to-Player command should be worked out among all the players. The game can be played effectively without any Player-to-Player communication protocol (per se); however Players are encouraged to decide on a reasonable Player-to-Player protocol.

Overview of The I-Wars Protocol

Communication Modes:

The protocol has two modes of communication: Directive and Command modes. Your application must support both of these modes for a variety of cases, which are described herein.

e Communication Styles:

There are three styles of communication that can occur in the game:

Player A to Monitor (Player A makes active connection to Monitor's server)
Monitor to Player A (Monitor makes active connection to Player A's server)
Player A to Player B (Player A makes active connection to Player B's server)

In all cases, regardless of the direction of the connection, the Monitor always operates in Directive mode, and the player in question is required to operate in Command mode.

In the case of two players, the player who initiated the connection (above, this would be Player A) will be in Directive mode while the other player is in Command mode. (Note that this is the only official statement about Player-to-Player communications here; Players must work out Player-to-Player communications themselves.)

Server and Clients:

Each player must have one server process (which may "spin off" many passive client processes), and at least one active client process.

The server process listens as a ServerSocket() on a particular port, awaiting connections. The server must be capable of handling more than one connection at a time. This is of the utmost importance, since the Monitor makes frequent (and sometimes simultaneous!) connections to the server process. Therefore, each connection should generate a passive client process to handle that connection. (Hint: Use Threads!)

(Note that some might call this "passive client" something different. Basically, it is a separate "handler" that takes a socket connection made to your server port, and talks to it in command mode. Call this what you will---but this is what it must do.)

Each player also must have at least one active client process, but can have as many as the programmer desires. Active client processes are used to make proactive connections to the server ports of the Monitor and other players. At startup, the very first task of the first active client process will be to make a connection to the Monitor's server and go through a Registration Transaction.

Note that active client processes should not interfere with (although they may need to internally communicate with) the player's own server process. They should be almost completely independent of each other. Clearly, some communication of internal state will be required, but on the whole, they should operate independently (Hint: Use Threads!).

Active client processes differ from passive client processes in one key area. The passive client process is started only when someone (the Monitor or another Player) makes a connection to the Player's server port and makes some requests. The active client process is that which goes out and makes connections to other Players server port and to the Monitor's server port.

The server process for the Monitor will always be on the machine boole.ececs.uc.edu on port 7777. In addition, all active client processes from the Monitor will generate from boole.ececs.uc.edu.

Directive Mode

In this discussion of Directive Mode, the sender is considered the process in Directive mode, while the receiver is the process to whom the sender is communicating to. By requirements of the protocol, if the sender is in Directive Mode, the receiver must be in Command mode.

Overview:

Directive mode is the mode that the Monitor is always in, and the mode that a player's active client processes must be in when connection to other players.

When in Directive mode, a process will send a series of Message Groups across the socket. Each message group consists of one or more Directives. Each Directive is on a separate line. After each Message Group, the sender waits for the receiver to issue a single Command. (More information about Commands is below).

The Directives:

(Note that all interactions are case insensitive). All Directives are in the form:
DIRECTIVE: ARG1 ARG2 ... ARGN STRING
ARG1 through ARGN and/or STRING are optional or not depending on each particular Directive. A given ARGI will be guaranteed to contain no whitespace. Sometimes, a given ARGI will be guaranteed to always be the exact same token. In these cases, that literal token will be listed in the tables below.

STRING is usually a free-form string, which can contain whitespace.

Directives are always terminated by a newline.

Directive Description

WAITING: Indicates that the current Message Group is complete, and the sender awaits a Command from the receiver.

REQUIRE: ARG1 Indicates that the sender is demanding that the next Command from receiver be ARG1. If the receiver sends some Command besides ARG1, the most likely result will be a COMMAND_ERROR: Directive, and another REQUIRE: ARG1 Directive in the next Message Group.

COMMAND_ERROR: STRING Indicates that an error occurred during the processing of the last Command. This could be because of invalid arguments, incorrect number of arguments, an unexpected Command (e.g., if a different Command is currently REQUIREd), or because a Command is not yet implemented. The STRING will be a diagnostic error message. COMMAND_ERROR only appears in a Message Group if there was an error with the last command.

COMMENT: STRING This Directive is used to give verbose output on the operation of various Commands, and to give general feedback about a variety of things. STRING is completely free-form, and more than likely will only be useful to human eyes for debugging. Not every Message Group is guaranteed to have a COMMENT directive.

RESULT: ARG1 STRING This Directive is used to return results from the last Command issued by the receiver. ARG1 will be the Command for which these are results. STRING, in this case, will not be free-form. Rather, it will be in the format as described by the result format for the Command, ARG1. In many cases, particularly with those commands that generate no results, STRING will be the empty string. Note that the RESULT: Directive does not appear when there is an error executing a given command. See the COMMAND_ERROR Directive.

PLAYER_PASSWORD_CHECKSUM: ARG1 This Directive is sent by the Monitor to authenticate to the player. ARG1 is a SHA-1 digest of the player's password, represented in hexadecimal. This directive is most useful when the player receives a connection on its server port. The Monitor will always have this Directive in the first Message Group that it sends during an active client connection. However, it is up to the player to verify that ARG1 does, in fact, authenticate the Monitor properly. Note that some players will most surely be attempting to impersonate the Monitor!

WAR_DECLARATION: ARG1 This Directive is sent by the Monitor to Player_B, on behalf of Player_A. ARG1 is the identity of the Player_A, who is declaring war on Player_B. Note that Player_B will always be the receiver of the Directive, otherwise the Directive is basically meaningless. This Directive usually occurs in a message group with a REQUIRE: WAR_DEFEND.

TRADE: ARG1 ARG2 ARG3 for ARG5 ARG6 ARG7 This Directive is sent by the Monitor to Player_B, on behalf of Player_A. ARG1 is the identity of the Player asking for the trade (e.g., PLAYER_1. ARG2 is the resource that the PLAYER_1 would like to trade. ARG3 is the amount (an integer) that PLAYER_1 is offering. ARG5 is the identity of the Player that Player_A would like to trade to (e.g., Player_B). Note that Player_B will always be the receiver of the Directive, otherwise the Directive is basically meaningless. ARG6 is the resource which is being requested from Player_B. ARG7 is the amount of that resource that is being requested.

WAR_TRUCE_OFFERED: ARG1 to ARG3 ARG4 ARG5 ARG6 ARG7 ... ARGN This Directive is sent by the Monitor to Player_B, on behalf of Player_A. ARG1 is the identity of the Player asking for the truce (e.g., Player_A. ARG2 is always "to". ARG3 is the identity of the Player who will benefit from the truce (i.e., Player_A). ARG3 is the string representing a resource, and ARG4 is the amount of this resource offered. This continues through the rest of the directive, which odd-number arguments being the resource and even numbers being the amount offered. If the truce is accepted, the amounts of those resources will be transferred from Player_A to Player_B. Note that Player_B will always be the receiver of the

Directive	Description
`WAITING:`	Indicates that the current Message Group is complete, and the sender awaits a Command from the receiver.
`REQUIRE: ARG1`	Indicates that the sender is demanding that the next Command from receiver be `ARG1`. If the receiver sends some Command besides `ARG1`, the most likely result will be a `COMMAND_ERROR:` Directive, and another `REQUIRE: ARG1` Directive in the next Message Group.
`COMMAND_ERROR: STRING`	Indicates that an error occurred during the processing of the last Command. This could be because of invalid arguments, incorrect number of arguments, an unexpected Command (e.g., if a different Command is currently `REQUIRE`d), or because a Command is not yet implemented. The `STRING` will be a diagnostic error message. `COMMAND_ERROR` only appears in a Message Group if there was an error with the last command.
`COMMENT: STRING`	This Directive is used to give verbose output on the operation of various Commands, and to give general feedback about a variety of things. `STRING` is completely free-form, and more than likely will only be useful to human eyes for debugging. Not every Message Group is guaranteed to have a `COMMENT` directive.
`RESULT: ARG1 STRING`	This Directive is used to return results from the last Command issued by the receiver. `ARG1` will be the Command for which these are results. `STRING`, in this case, will not be free-form. Rather, it will be in the format as described by the result format for the Command, `ARG1`. In many cases, particularly with those commands that generate no results, `STRING` will be the empty string. Note that the `RESULT:` Directive does not appear when there is an error executing a given command. See the `COMMAND_ERROR` Directive.
`PLAYER_PASSWORD_CHECKSUM: ARG1`	This Directive is sent by the Monitor to authenticate to the player. `ARG1` is a SHA-1 digest of the player's password, represented in hexadecimal. This directive is most useful when the player receives a connection on its server port. The Monitor will always have this Directive in the first Message Group that it sends during an active client connection. However, it is up to the player to verify that `ARG1` does, in fact, authenticate the Monitor properly. Note that some players will most surely be attempting to impersonate the Monitor!
`WAR_DECLARATION: ARG1`	This Directive is sent by the Monitor to `Player_B`, on behalf of `Player_A`. `ARG1` is the identity of the `Player_A`, who is declaring war on `Player_B`. Note that `Player_B` will always be the receiver of the Directive, otherwise the Directive is basically meaningless. This Directive usually occurs in a message group with a `REQUIRE: WAR_DEFEND`.
`TRADE: ARG1 ARG2 ARG3 for ARG5 ARG6 ARG7`	This Directive is sent by the Monitor to `Player_B`, on behalf of `Player_A`. `ARG1` is the identity of the Player asking for the trade (e.g., `PLAYER_1`. `ARG2` is the resource that the `PLAYER_1` would like to trade. `ARG3` is the amount (an integer) that `PLAYER_1` is offering. `ARG5` is the identity of the Player that `Player_A` would like to trade to (e.g., `Player_B`). Note that `Player_B` will always be the receiver of the Directive, otherwise the Directive is basically meaningless. `ARG6` is the resource which is being requested from `Player_B`. `ARG7` is the amount of that resource that is being requested.
`WAR_TRUCE_OFFERED: ARG1 to ARG3 ARG4 ARG5 ARG6 ARG7 ... ARGN`	This Directive is sent by the Monitor to `Player_B`, on behalf of `Player_A`. `ARG1` is the identity of the Player asking for the truce (e.g., `Player_A`. `ARG2` is always "to". `ARG3` is the identity of the Player who will benefit from the truce (i.e., `Player_A`). `ARG3` is the string representing a resource, and `ARG4` is the amount of this resource offered. This continues through the rest of the directive, which odd-number arguments being the resource and even numbers being the amount offered. If the truce is accepted, the amounts of those resources will be transferred from `Player_A` to `Player_B`. Note that `Player_B` will always be the receiver of the

Message Groups:

A Message Group is defined as a sequence of N Directives, one per line. A Message Group also has the following properties:

N >= 1
Each line contains one and only one Directive, each terminated by a newline character
The last Directive is WAITING:, unless the sender is terminating the connection, in which case the Message Group will not end with WAITING:, but instead will end with the an end of file marker.

Command Mode

In this discussion of Command Mode, the sender is considered the process in Command mode, while the receiver is the process to whom the sender is communicating to. By requirements of the protocol, if the sender is in Command Mode, the receiver must be in Directive mode.

The Commands:

(Note that all interactions are case insensitive). All Commands are in the form:
COMMAND ARG1 ARG2 ... ARGN
ARG1 through ARGN are optional or not, depending on each particular Command. A given ARGI will be guaranteed to contain no whitespace. Sometimes, a given ARGI will be guaranteed to always be the exact same token. In these cases, that literal token will be listed in the tables below.

Commands are always terminated by a newline.

The following table of commands are used in all transactions:

Command Description Result
IDENT ARG1 ARG2 This command is used to send the sender's identity to the receiver. A player's identity is not a secret---like a username, it is the method by which others (including the Monitor) identify the player. ARG1 is the identity of the username. ARG2 is optional. If ARG2 is sent, it should be the Player's portion that is needed to do shared-secret discovery. (See the Cryptography section below for details.) The result is
RESULT: IDENT ARG1
ARG1 is optional, and only appears if cryptography was requested. If it was requested, then ARG1 will be the public key that the Player needs to do shared-secret discovery. (See the Cryptography section below for details.) Note, that since the IDENT command can be used in Player-to-Player communications, Players who wish to be sure that they can communicate with everyone must implement this encryption, and give ARG1 back properly if cryptography was requested by the IDENT command.

QUIT This command terminates the current connection. The result is
RESULT: QUIT
In addition, note that the Message Group that follows this Command will not contain the WAITING: Directive, as the connection will be closed.

Command	Description	Result
`IDENT ARG1 ARG2`	This command is used to send the sender's identity to the receiver. A player's identity is not a secret---like a username, it is the method by which others (including the Monitor) identify the player. `ARG1` is the identity of the username. `ARG2` is optional. If `ARG2` is sent, it should be the Player's portion that is needed to do shared-secret discovery. (See the Cryptography section below for details.)	The result is `RESULT: IDENT ARG1` `ARG1` is optional, and only appears if cryptography was requested. If it was requested, then `ARG1` will be the public key that the Player needs to do shared-secret discovery. (See the Cryptography section below for details.) Note, that since the IDENT command can be used in Player-to-Player communications, Players who wish to be sure that they can communicate with everyone must implement this encryption, and give `ARG1` back properly if cryptography was requested by the `IDENT` command.
`QUIT`	This command terminates the current connection.	The result is `RESULT: QUIT` In addition, note that the Message Group that follows this Command will not contain the `WAITING:` Directive, as the connection will be closed.

The following Commands should be used only in transmissions from the Player to the Monitor (however, there is no Monitor-imposed penalty for Players who try to use these Commands with other Players):

Command Description Result
PASSWORD ARG1 This command is used to transmit the player's password to the monitor. ARG1 is the player's password. The Monitor sometimes sends REQUIRE: PASSWORD after a successful IDENT command. Note that this command is a bootstrap for secure communications with the Monitor later, so the player should use other means to verify that the request definitely came from the Monitor. The result is
RESULT: PASSWORD STRING
which is sent in the Message Group following the Command invocation. STRING is an alphanumeric string with no whitespace that is the player-specific monitor password (sometimes called a "cookie"). This password ("cookie") is different from the player's own password. This password ("cookie") should be used with the ALIVE command to identify the player to the Monitor.

CHANGE_PASSWORD ARG1 ARG2 This command is used to request a change in the player password and the player-specific monitor password. ARG1 is the player's old password (the one currently in use). ARG2 is the new password that the player would like to use from this time forward. Note that the password is only changed if the command successfully returns a RESULT: Directive in the next Message Group. The result is
RESULT: CHANGE_PASSWORD STRING
which is sent in the Message Group following the Command invocation. STRING is an alphanumeric string with no whitespace that is the player-specific monitor password (sometimes called a "cookie"). This new player-specific monitor password will be different from before. The CHANGE_PASSWORD command not only allows the player to change the player password, but also automatically changes the player-specific monitor password ("cookie"). Note that Players should be careful with this command. It is recommended that it be sent first in any set of transactions. Some Players have abused the fact that the Monitor gives 180 seconds for a connection, however, connections should never last that long. If the CHANGE_PASSWORD command is sent at the end of one of these "marathon" connections, Players may be cut off before they can receive the new Monitor password, and may be locked out of the game.

SYNTHESIZE ARG1 This command is used to synthesize a complex resource. The complex resources are WEAPONS, COMPUTERS, and VEHICLES. ARG1 should be the resource to synthesize. Be sure that the name of the resource matches the name given by the PLAYER_STATUS command. See the table in the "Synthesize" section for more information about what raw resources are needed to synthesize the complex resources. The result is
RESULT: SYNTHESIZE STRING
which is sent in the Message Group following the Command invocation. STRING is
RESOURCE holdings increased by one
, where RESOURCE is the resource that was increased. A COMMAND_ERROR is sent if the resource could not be synthesized for any reason.

HOST_PORT ARG1 ARG2 This Command is always sent by an active client process of a player to the Monitor. It is used by the sender to inform receiver (usually the Monitor) what hostname and port the sender currently lives on. ARG1 should be the fully qualified DNS name of the host where the server process of the sender is running. ARG2 should be the integer port number (between 2048 and 65000, inclusive) where the server Socket for the sender is running on. Note: This Command will only be successful if there is currently a server process for the sender running on the given hostname and port. The result is
RESULT: HOST_PORT HOST_NAME PORT
HOST_NAME is the fully qualified DNS hostname that the Monitor was able to identify you as, and PORT is the port where you live.

SIGN_OFF This command is used to that the Monitor "forget about the Player". The Monitor "forgets about the Player" in two ways. First, it forgets what host and port the Player's server is on. This means that the HOST_PORT will be REQUIRE: the next time the Player connects to the Monitor with an active client connection. In addition, the Monitor will "forget about the Player" by invalidating the current Player-specific Monitor password for the Player. This means that the Player will get a PASSWORD command REQUIRE: the next time that the Player connects to the Monitor with an active client connection. Note that if you execute this command, the Monitor will consider that you are not alive, until you again send the HOST_PORT command. The result is
RESULT: SIGN_OFF
in the Message Group following the Command invocation.

PLAYER_STATUS This Command is used to check on the status of the sender's wealth. The result is
RESULT: PLAYER_STATUS STRING
which is sent in the Message Group following the Command invocation. The string is in the format:
RESOURCE_0 AMOUNT_0 RESOURCE_1 AMOUNT_1 ... RESOURCE_9 AMOUNT_9
where RESOURCE_I is the alphanumeric string of one of the 10 resources, and AMOUNT_I is the amount of that resource the sender currently has.

ALIVE ARG1 This Command is sent to by the sender to indicate to the Monitor that the Player is indeed alive. ARG1 should be the player-specific monitor password ("cookie") that was given to the Player by the Monitor as a RESULT: of the PASSWORD Command. In ARG1 is not the write password ("cookie"), a COMMAND_ERROR: will and the Player will not be counted as alive. The result is
RESULT: ALIVE Identity has been verified

TRADE_REQUEST ARG1 ARG2 ARG3 for ARG5 ARG6 ARG7 This command is used by the initiator of a trade to ask the Monitor to confirm the trade, by making a request to the other player. The arguments to TRADE_REQUEST are exactly the same as those to the TRADE: directive. Note that ARG5 may be MONITOR. In this case, the Player is requesting a trade with the Monitor itself. If the Monitor has the requested materials available, the Monitor approves trades that at current market values, plus a percentage mark-up. The result is
RESULT: TRADE_REQUEST ARG1
ARG1 is either ACCEPTED, REJECTED, or NOT_ALIVE. All of which refer to the status of the Player with whom this trade was requested. If ARG1 is ACCEPTED, then the Player can expect her wealth to be changed to reflect the trade.

TRADE_RESPONSE ARG1 This command is used to either accept or reject a trade request. This command is most probably used in response to a Message Group that contained the TRADE: Directive (and probably a REQUIRE: TRADE_RESPONSE Directive as well). ARG1 is either ACCEPT or DECLINE. The result is
RESULT: TRADE_RESPONSE
Depending on whether the Player accepted or declined the trade (and, if a Monitor approval was given), the Player's wealth will be changed.

WAR_DECLARE ARG1 ARG2 ARG3 ARG4 ARG5 This command is used by Player_A to declare war on Player_B. ARG1 should be the identity of Player_B. ARG2 should be the host where Player_B lives, and ARG3 should be the port on which Player_B is listening. ARG4 is the number of weapons that Player_A would like to commit to this war, and ARG5 is the number of vehicles that Player_A would like to commit to this war. If this host and/or port for Player_B is wrong, Player_A will automatically loose some percentage of the weapons and vehicles committed, and the war will not be started (in other words, Player_A must know where Player_B "lives" before declaring war. Finally, note that the given weapons and vehicles will be tied up in that war until end of the war. A COMMAND_ERROR will be in the resulting Message Group if Player_B cannot be found, or if Player_A has less weapons and/or vehicles than were specified. The result is
RESULT: WAR_DECLARE War begun with ARG1

WAR_DEFEND ARG1 ARG2 This command is used to declare defending parameters for a war that was declared via a WAR_DECLARATION: directive. ARG1 is the number of weapons the Player wishes to use in this war. ARG2 is the number of vehicles the player wishes to use in this war. This command is most probably used in response to a Message Group that contained the WAR_DECLARATION: Directive (and probably a REQUIRE: WAR_DECLARATION Directive as well). The result is
RESULT: WAR_DEFEND

WAR_TRUCE_OFFER ARG1 to ARG3 ARG4 ARG5 ARG6 ARG7 ... ARGN This command is used by the initiator of a trade to ask the Monitor to confirm a truce, by making a request to the other player. The arguments to WAR_TRUCE_OFFER are exactly the same as those to the WAR_TRUCE_OFFERED: directive. The result is
RESULT: WAR_TRUCE_OFFER ARG1
ARG1 is either ACCEPTED, REJECTED, NOT_ALIVE, or WAR_OVER. If ARG1 is ACCEPTED, then the Player can expect her wealth to be changed to reflect the truce terms. A COMMAND_ERROR occurs if a war is not active between the two parties, an invalid resource name is given, or if the player who has offered the truce does not have sufficient resources. Note that weapons and vehicles already tied up in the war cannot be used in a war trade agreement.

WAR_TRUCE_RESPONSE ARG1 This command is used to either accept or reject a truce request. This command is most probably used in response to a Message Group that contained the WAR_TRUCE_OFFERED: Directive (and probably a REQUIRE: WAR_TRUCE_RESPONSE Directive as well). ARG1 is either ACCEPT or DECLINE. The result is
RESULT: WAR_TRUCE_RESPONSE
Depending on whether the Player accepted or declined the trade (and, if a Monitor approval was given), the Player's wealth will be changed.

WAR_STATUS ARG1 This command is used find the status of current or recently fought wars. ARG1 is the identity of Player_B, the player against whom the requester (Player_A wishes to see the war status. A COMMAND_ERROR is sent in the resulting Message Group if Player_A has never been at war with Player_B The result is
RESULT: WAR_STATUS aggressor ARG2 defender ARG4 winner ARG6 battles ARG8 status ARG10 weapons ARG12 vehicles ARG14
ARG2 is the identity of the aggressor in this war. ARG4 is the identity of the defender in this war. ARG6 will be the identity of the winner, TRUCE is a truce was found, or NONE if the war still continues. ARG8 will be an integer that represents the number of battles fought thus far in this war. ARG10 will be COMPLETED if the war is over, or ACTIVE if the war is still active. ARG12 is the number of weapons that Player_A (you) has committed to this war. ARG14 is the number of vehicles that Player_A (you) has committed to this war. Note: the number of vehicles and weapons committed to wars are not part of your PLAYER_STATUS total.

GET_GAME_IDENTS This command is used to get a list of identities of Players in the current game. This is useful, for example, if you want to know who can be traded with. The result is
RESULT: GET_GAME_IDENTS ARG1 ... ARGN
There will be N arguments in the response. Each argument will be the identity of another Player who is currently in the game.

RANDOM_PLAYER_HOST_PORT This command is used to ask the Monitor for a host port of some random identity. This is useful when a Player wishes to go to war with another Player, as in these cases, it is necessary to know the host and port of the Player to be fought. A COMMAND_ERROR occurs if you have already asked for a random Player host and port recently. The result is
RESULT: RANDOM_PLAYER_HOST_PORT ARG1 ARG2 ARG3
ARG1 will be the identity of the Player, ARG2 will be the most recent host on which that Player has been seen, and ARG3 will be the port on which that Player lives and/or the host and port where that player was most recently seen.

PLAYER_HOST_PORT ARG1 This command is used to ask the Monitor for a host port of some given Player's identity. The command costs one computer resource. A COMMAND_ERROR occurs if the Player issuing the command does not have adequate computer resources. A COMMAND_ERROR also occurs if the identity is not known and/or the requested Player is not currently alive. Note that the computer resource is taken even if the identity is not known or the Player is not alive. The result is
RESULT: PLAYER_HOST_PORT ARG1 ARG2 ARG3
ARG1 will be the identity of the Player, ARG2 will be the most recent host on which that Player has been seen, and ARG3 will be the port on which that Player lives and/or the host and port where that player was most recently seen.

PLAYER_STATUS_CRACK ARG1 ARG2 This command is used to make an attempt to get the player status information of an enemy Player. ARG1 is the identity of the Player whose status to crack. ARG2 is the number of computer resources to spend on this attempt. The computer resources will be lost, regardless of whether or not the crack attempt succeeds. The more computer resources committed, the greater the chance of success. A COMMAND_ERROR occurs if the Player issuing the command does not have at least the amount of computer resources requested. A COMMAND_ERROR also occurs if the identity is not known. The result is
RESULT: PLAYER_STATUS_CRACK ARG1 ARG2 STRING
ARG1 will be the identity of the Player whose status was to be cracked. ARG2 will be either SUCCEEDED or FAILED. If ARG2 is SUCCEEDED, then STRING will equivalent to the result string for the PLAYER_STATUS command, however, the status will of course be for Player, ARG1.

PLAYER_MONITOR_PASSWORD_CRACK ARG1 ARG2 This command is used to make an attempt to crack the Monitor password of another player. ARG1 is the identity of the Player whose Monitor password to crack. ARG2 is the number of computer resources to spend on this attempt. The computer resources will be lost, regardless of whether or not the crack attempt succeeds. The more computer resources committed, the greater the chance of success. A COMMAND_ERROR occurs if the Player issuing the command does not have at least the amount of computer resources requested. A COMMAND_ERROR also occurs if the identity is not known. The result is
RESULT: PLAYER_MONITOR_PASSWORD_CRACK ARG1 ARG2 ARG3
ARG1 will be the identity of the Player whose Monitor password was to be cracked. ARG2 will be either SUCCEEDED or FAILED. If ARG2 is SUCCEEDED, then ARG3 will the Monitor password of ARG1. Otherwise, ARG3 will be the empty string.

Command	Description	Result
`PASSWORD ARG1`	This command is used to transmit the player's password to the monitor. `ARG1` is the player's password. The Monitor sometimes sends `REQUIRE: PASSWORD` after a successful `IDENT` command. Note that this command is a bootstrap for secure communications with the Monitor later, so the player should use other means to verify that the request definitely came from the Monitor.	The result is `RESULT: PASSWORD STRING` which is sent in the Message Group following the Command invocation. `STRING` is an alphanumeric string with no whitespace that is the *player-specific* monitor password (sometimes called a "cookie"). This password ("cookie") is different from the player's own password. This password ("cookie") should be used with the `ALIVE` command to identify the player to the Monitor.
`CHANGE_PASSWORD ARG1 ARG2`	This command is used to request a change in the player password and the player-specific monitor password. `ARG1` is the player's old password (the one currently in use). `ARG2` is the new password that the player would like to use from this time forward. Note that the password is only changed if the command successfully returns a `RESULT:` Directive in the next Message Group.	The result is `RESULT: CHANGE_PASSWORD STRING` which is sent in the Message Group following the Command invocation. `STRING` is an alphanumeric string with no whitespace that is the *player-specific* monitor password (sometimes called a "cookie"). This new player-specific monitor password will be different from before. The `CHANGE_PASSWORD` command not only allows the player to change the player password, but also automatically changes the player-specific monitor password ("cookie"). Note that Players should be careful with this command. It is recommended that it be sent first in any set of transactions. Some Players have abused the fact that the Monitor gives 180 seconds for a connection, however, connections should never last that long. If the `CHANGE_PASSWORD` command is sent at the end of one of these "marathon" connections, Players may be cut off before they can receive the new Monitor password, and may be locked out of the game.
`SYNTHESIZE ARG1`	This command is used to synthesize a complex resource. The complex resources are WEAPONS, COMPUTERS, and VEHICLES. `ARG1` should be the resource to synthesize. Be sure that the name of the resource matches the name given by the `PLAYER_STATUS` command. See the table in the "Synthesize" section for more information about what raw resources are needed to synthesize the complex resources.	The result is `RESULT: SYNTHESIZE STRING` which is sent in the Message Group following the Command invocation. `STRING` is `RESOURCE holdings increased by one` , where `RESOURCE` is the resource that was increased. A `COMMAND_ERROR` is sent if the resource could not be synthesized for any reason.
`HOST_PORT ARG1 ARG2`	This Command is always sent by an active client process of a player to the Monitor. It is used by the sender to inform receiver (usually the Monitor) what hostname and port the sender currently lives on. `ARG1` should be the fully qualified DNS name of the host where the server process of the sender is running. `ARG2` should be the integer port number (between 2048 and 65000, inclusive) where the server Socket for the sender is running on. Note: This Command will only be successful if there is currently a server process for the sender running on the given hostname and port.	The result is `RESULT: HOST_PORT HOST_NAME PORT` `HOST_NAME` is the fully qualified DNS hostname that the Monitor was able to identify you as, and `PORT` is the port where you live.
`SIGN_OFF`	This command is used to that the Monitor "forget about the Player". The Monitor "forgets about the Player" in two ways. First, it forgets what host and port the Player's server is on. This means that the `HOST_PORT` will be `REQUIRE:` the next time the Player connects to the Monitor with an active client connection. In addition, the Monitor will "forget about the Player" by invalidating the current Player-specific Monitor password for the Player. This means that the Player will get a `PASSWORD` command `REQUIRE:` the next time that the Player connects to the Monitor with an active client connection. Note that if you execute this command, the Monitor will consider that you are not alive, until you again send the `HOST_PORT` command.	The result is `RESULT: SIGN_OFF` in the Message Group following the Command invocation.
`PLAYER_STATUS`	This Command is used to check on the status of the sender's wealth.	The result is `RESULT: PLAYER_STATUS STRING` which is sent in the Message Group following the Command invocation. The string is in the format: `RESOURCE_0 AMOUNT_0 RESOURCE_1 AMOUNT_1 ... RESOURCE_9 AMOUNT_9` where RESOURCE_I is the alphanumeric string of one of the 10 resources, and AMOUNT_I is the amount of that resource the sender currently has.
`ALIVE ARG1`	This Command is sent to by the sender to indicate to the Monitor that the Player is indeed alive. `ARG1` should be the player-specific monitor password ("cookie") that was given to the Player by the Monitor as a `RESULT:` of the `PASSWORD` Command. In `ARG1` is not the write password ("cookie"), a `COMMAND_ERROR:` will and the Player will not be counted as alive.	The result is `RESULT: ALIVE Identity has been verified`
`TRADE_REQUEST ARG1 ARG2 ARG3 for ARG5 ARG6 ARG7`	This command is used by the initiator of a trade to ask the Monitor to confirm the trade, by making a request to the other player. The arguments to `TRADE_REQUEST` are exactly the same as those to the `TRADE:` directive. Note that `ARG5` may be `MONITOR`. In this case, the Player is requesting a trade with the Monitor itself. If the Monitor has the requested materials available, the Monitor approves trades that at current market values, plus a percentage mark-up.	The result is `RESULT: TRADE_REQUEST ARG1` `ARG1` is either `ACCEPTED`, `REJECTED`, or `NOT_ALIVE`. All of which refer to the status of the Player with whom this trade was requested. If `ARG1` is `ACCEPTED`, then the Player can expect her wealth to be changed to reflect the trade.
`TRADE_RESPONSE ARG1`	This command is used to either accept or reject a trade request. This command is most probably used in response to a Message Group that contained the `TRADE:` Directive (and probably a `REQUIRE: TRADE_RESPONSE` Directive as well). `ARG1` is either `ACCEPT` or `DECLINE`.	The result is `RESULT: TRADE_RESPONSE` Depending on whether the Player accepted or declined the trade (and, if a Monitor approval was given), the Player's wealth will be changed.
`WAR_DECLARE ARG1 ARG2 ARG3 ARG4 ARG5`	This command is used by `Player_A` to declare war on `Player_B`. `ARG1` should be the identity of `Player_B`. `ARG2` should be the host where `Player_B` lives, and `ARG3` should be the port on which `Player_B` is listening. `ARG4` is the number of weapons that `Player_A` would like to commit to this war, and `ARG5` is the number of vehicles that `Player_A` would like to commit to this war. If this host and/or port for `Player_B` is wrong, `Player_A` will automatically loose some percentage of the weapons and vehicles committed, and the war will not be started (in other words, `Player_A` must know where `Player_B` "lives" before declaring war. Finally, note that the given weapons and vehicles will be tied up in that war until end of the war. A `COMMAND_ERROR` will be in the resulting Message Group if `Player_B` cannot be found, or if `Player_A` has less weapons and/or vehicles than were specified.	The result is `RESULT: WAR_DECLARE War begun with ARG1`
`WAR_DEFEND ARG1 ARG2`	This command is used to declare defending parameters for a war that was declared via a `WAR_DECLARATION:` directive. `ARG1` is the number of weapons the Player wishes to use in this war. `ARG2` is the number of vehicles the player wishes to use in this war. This command is most probably used in response to a Message Group that contained the `WAR_DECLARATION:` Directive (and probably a `REQUIRE: WAR_DECLARATION` Directive as well).	The result is `RESULT: WAR_DEFEND`
`WAR_TRUCE_OFFER ARG1 to ARG3 ARG4 ARG5 ARG6 ARG7 ... ARGN`	This command is used by the initiator of a trade to ask the Monitor to confirm a truce, by making a request to the other player. The arguments to `WAR_TRUCE_OFFER` are exactly the same as those to the `WAR_TRUCE_OFFERED:` directive.	The result is `RESULT: WAR_TRUCE_OFFER ARG1` `ARG1` is either `ACCEPTED`, `REJECTED`, `NOT_ALIVE`, or `WAR_OVER`. If `ARG1` is `ACCEPTED`, then the Player can expect her wealth to be changed to reflect the truce terms. A `COMMAND_ERROR` occurs if a war is not active between the two parties, an invalid resource name is given, or if the player who has offered the truce does not have sufficient resources. Note that weapons and vehicles already tied up in the war cannot be used in a war trade agreement.
`WAR_TRUCE_RESPONSE ARG1`	This command is used to either accept or reject a truce request. This command is most probably used in response to a Message Group that contained the `WAR_TRUCE_OFFERED:` Directive (and probably a `REQUIRE: WAR_TRUCE_RESPONSE` Directive as well). `ARG1` is either `ACCEPT` or `DECLINE`.	The result is `RESULT: WAR_TRUCE_RESPONSE` Depending on whether the Player accepted or declined the trade (and, if a Monitor approval was given), the Player's wealth will be changed.
`WAR_STATUS ARG1`	This command is used find the status of current or recently fought wars. `ARG1` is the identity of `Player_B`, the player against whom the requester (`Player_A` wishes to see the war status. A `COMMAND_ERROR` is sent in the resulting Message Group if `Player_A` has never been at war with `Player_B`	The result is `RESULT: WAR_STATUS aggressor ARG2 defender ARG4 winner ARG6 battles ARG8 status ARG10 weapons ARG12 vehicles ARG14` `ARG2` is the identity of the aggressor in this war. `ARG4` is the identity of the defender in this war. `ARG6` will be the identity of the winner, `TRUCE` is a truce was found, or `NONE` if the war still continues. `ARG8` will be an integer that represents the number of battles fought thus far in this war. `ARG10` will be `COMPLETED` if the war is over, or `ACTIVE` if the war is still active. `ARG12` is the number of weapons that `Player_A` (you) has committed to this war. `ARG14` is the number of vehicles that `Player_A` (you) has committed to this war. Note: the number of vehicles and weapons committed to wars are not part of your `PLAYER_STATUS` total.
`GET_GAME_IDENTS`	This command is used to get a list of identities of Players in the current game. This is useful, for example, if you want to know who can be traded with.	The result is `RESULT: GET_GAME_IDENTS ARG1 ... ARGN` There will be `N` arguments in the response. Each argument will be the identity of another Player who is currently in the game.
`RANDOM_PLAYER_HOST_PORT`	This command is used to ask the Monitor for a host port of some random identity. This is useful when a Player wishes to go to war with another Player, as in these cases, it is necessary to know the host and port of the Player to be fought. A `COMMAND_ERROR` occurs if you have already asked for a random Player host and port recently.	The result is `RESULT: RANDOM_PLAYER_HOST_PORT ARG1 ARG2 ARG3` `ARG1` will be the identity of the Player, `ARG2` will be the most recent host on which that Player has been seen, and `ARG3` will be the port on which that Player lives and/or the host and port where that player was most recently seen.
`PLAYER_HOST_PORT ARG1`	This command is used to ask the Monitor for a host port of some given Player's identity. The command costs one computer resource. A `COMMAND_ERROR` occurs if the Player issuing the command does not have adequate computer resources. A `COMMAND_ERROR` also occurs if the identity is not known and/or the requested Player is not currently alive. Note that the computer resource is taken even if the identity is not known or the Player is not alive.	The result is `RESULT: PLAYER_HOST_PORT ARG1 ARG2 ARG3` `ARG1` will be the identity of the Player, `ARG2` will be the most recent host on which that Player has been seen, and `ARG3` will be the port on which that Player lives and/or the host and port where that player was most recently seen.
`PLAYER_STATUS_CRACK ARG1 ARG2`	This command is used to make an attempt to get the player status information of an enemy Player. `ARG1` is the identity of the Player whose status to crack. `ARG2` is the number of computer resources to spend on this attempt. The computer resources will be lost, regardless of whether or not the crack attempt succeeds. The more computer resources committed, the greater the chance of success. A `COMMAND_ERROR` occurs if the Player issuing the command does not have at least the amount of computer resources requested. A `COMMAND_ERROR` also occurs if the identity is not known.	The result is `RESULT: PLAYER_STATUS_CRACK ARG1 ARG2 STRING` `ARG1` will be the identity of the Player whose status was to be cracked. `ARG2` will be either `SUCCEEDED` or `FAILED`. If `ARG2` is `SUCCEEDED`, then `STRING` will equivalent to the result string for the `PLAYER_STATUS` command, however, the status will of course be for Player, `ARG1`.
`PLAYER_MONITOR_PASSWORD_CRACK ARG1 ARG2`	This command is used to make an attempt to crack the Monitor password of another player. `ARG1` is the identity of the Player whose Monitor password to crack. `ARG2` is the number of computer resources to spend on this attempt. The computer resources will be lost, regardless of whether or not the crack attempt succeeds. The more computer resources committed, the greater the chance of success. A `COMMAND_ERROR` occurs if the Player issuing the command does not have at least the amount of computer resources requested. A `COMMAND_ERROR` also occurs if the identity is not known.	The result is `RESULT: PLAYER_MONITOR_PASSWORD_CRACK ARG1 ARG2 ARG3` `ARG1` will be the identity of the Player whose Monitor password was to be cracked. `ARG2` will be either `SUCCEEDED` or `FAILED`. If `ARG2` is `SUCCEEDED`, then `ARG3` will the Monitor password of `ARG1`. Otherwise, `ARG3` will be the empty string.

Cryptography

Players may communicate securely with the Monitor. The Monitor implements Diffie-Hellman shared-secret exchange to exchange a key with the Players. This key is then used as the key for Karn symmetric encryption. For Diffie-Hellman to work, Players will need the proper N and G values. We have created a class, called DHKeyObject that holds these values. Players will be given a serialized DHKeyObject for each game that is played.

Since encryption routines are difficult to implement, we are providing three classes, DHEngine.java, DHKeyObject.java, and Cipher.java that Players can drop into their Player code to handle encryption. Minimal instructions for plugging this code in are provided in the comments.

Note that when using these routines, each line from the Monitor is encrypted as a separate block of ciphertext that must be decrypted.

Transactions

A sequence such as: Message_Group_0 Command_0 Message_Group_1 Command_1 ... Message_Group_N QUIT
can be categorized as a transaction. Often, transactions can be very "free-from". Thus, there is no formal definition of types of transactions.

However, frequently, the Monitor will use a series of REQUIRE: Directives to force a transaction to play out in a particular way. Thus, transactions tend to "emerge" in a particular formats. These transactions are not a formalized portion of the protocol, but considering the transaction examples given here may help you consider useful designs for your Player.

Below are some common transactions that you will probably encounter. You may find look at this interactions helpful to decipher how the protocol plays out. However, note that these are only a few of the types of transactions that you will encounter, and they are presented for pedagogical purposes only. Do not assume that all transactions will work out like this!

In the transaction examples below, text that is sent by the Monitor is in red. Text that is sent by Player A (you) is in green. Text that is sent by Player B (a rival player) is in orange. Finally, comments (things that do not appear at all but are added to explain what is going on) appear in black.

Registration Transaction:

This transaction is initiated when the active client of Player A (you) connects to the Monitor for the first time, or after having restarted on a new hostname and/or port. The transaction goes as follows.

COMMENT: Game Monitor Version 2.2 REQUIRE: IDENT WAITING: Ident WHO_I_AM RESULT: IDENT REQUIRE: PASSWORD WAITING: Password MYLITTLESECRET RESULT: PASSWORD NRMVEXUHFELPNN REQUIRE: HOST_PORT WAITING:

Note here the RESULT:. This means that NRMVEXUHFELPNN is our Monitor password ("cookie"). We will need that later on.

Now, suppose that you ignored this REQUIRE: and sent a different command?
Player_Status COMMAND_ERROR: Command, PLAYER_STATUS, was not expected in this context, please send HOST_PORT REQUIRE: HOST_PORT WAITING:

Since you ignored did not send the command that was being REQUIRE:'d, a COMMAND_ERROR: was generated, and a new REQUIRE: of the same command has been given.

Now, you answer properly:
HOST_PORT myhost.occ.uc.edu 7891

At this point, before responding to you, the Monitor will attempt to contact the machine myhost.occ.uc.edu on port 7891. The transaction that takes place on that connection will be an Are-You-Alive? transaction, described below. Once that transaction is completed successfully on the other port. The result you see back on this connection is:
RESULT: HOST_PORT MYHOST.OCC.UC.EDU 7891 WAITING:

At this point, you can send any valid command, since there is no RESULT: Directive in the Message Group.

Are-You-Alive Transaction:

The Monitor initiates an Are-You-Alive Transaction frequently. It is done on demand when the HOST_PORT command is sent on a client connection to the monitor. In addition, the Monitor uses the Are-You-Alive connection to verify you are online and to determine if you have met the requisite uptime for receiving your daily allotment of resources.

The Are-You-Alive Transaction is initiated by a Monitor client to Player A's server port. Here is what the Transaction looks like:
COMMENT: Game Monitor Version 2.2 REQUIRE: IDENT WAITING: Ident WHO_I_AM PLAYER_PASSWORD_CHECKSUM: 36c00161466dc725834a9787fc0f18497361f0a6 RESULT: IDENT REQUIRE: ALIVE WAITING: ALIVE NRMVEXUHFELPNN RESULT: ALIVE Identity has been verified. REQUIRE: QUIT WAITING: QUIT RESULT: QUIT

Operation Transaction:

This transaction is almost the same as the Registration Transaction. However, note that the HOST_PORT command is not required, since the Monitor was able to verify that you still "live" on the same port as when you last registered.
COMMENT: Game Monitor Version 2.2 REQUIRE: IDENT WAITING: Ident WHO_I_AM RESULT: IDENT REQUIRE: ALIVE WAITING: ALIVE NRMVEXUHFELPNN RESULT: ALIVE Identity has been verified. WAITING:

Note that the Operation Transaction is frequently used when you need to get to a point where you need to send free-form commands to the Monitor (e.g., PLAYER_STATUS). You should expect that most active connections you make the monitor to start out with something like the Operation Transaction, and then leave you in a mode where you can send any command you choose to the Monitor, as you see above.

Operation Transaction with changed HOST_PORT:

This transaction is a variant of the Operation Transaction discussed above. If your host and/or port have changed, the Monitor will need to require the HOST_PORT command again to get a the new host and/or port.
COMMENT: Game Monitor Version 2.2 REQUIRE: IDENT WAITING: Ident WHO_I_AM RESULT: IDENT REQUIRE: ALIVE WAITING: ALIVE NRMVEXUHFELPNN RESULT: ALIVE Identity has been verified. COMMENT: unable to connect to host MYHOST.OCC.UC.EDU on port 7891 REQUIRE: HOST_PORT WAITING: HOST_PORT myhost.occ.uc.edu 9971

At this point, the Monitor will have to carry out an Are-You-Alive transaction on the new host and port.

RESULT: HOST_PORT MYHOST.OCC.UC.EDU 9971 WAITING:

Trade Transaction

This transaction is used to perform trades with other players. It would normally start with an Operational Transaction, so that Player A can have an active client connection where she can issue commands.
[...] WAITING: TRADE_REQUEST Player_A steel 1 for Player_B glass 10 RESULT: TRADE_REQUEST ACCEPTED WAITING: This commands issues a request from the Player with identity Player_A to trade one unit of steel for ten units of glass from the Player with identity, Player_B. In this case, Player_B has accepted the trade.

Immediately after the valid TRADE_REQUEST was made by Player_A, Player_B will receive the following on her server port.

COMMENT: Game Monitor Version 2.2 REQUIRE: IDENT WAITING: Ident Player_B PLAYER_PASSWORD_CHECKSUM: 36c00161466dc725834a9787fc0f18497361f0a6 RESULT: IDENT TRADE: PLAYER_1 RUBBER 1 FOR PLAYER_2 STEEL 1 REQUIRE: TRADE_RESPONSE WAITING: TRADE_RESPONSE ACCEPT Since Player_B has accepted the trade, the RESULT: back on Player_A's connection reflects that.

Synthesis:

Players are permitted to synthesize the complex resources. To perform the synthesis, Players must have in the their holdings 2 units of each of the resources needed to build the complex resource. The required raw resources to build complex resources are listed in the table below:

Complex Resource Raw Resources Needed
WEAPONS STEEL, PLASTIC, OIL

COMPUTERS COPPER, PLASTIC, GLASS

VEHICLES STEEL, RUBBER, GLASS, OIL

Complex Resource	Raw Resources Needed
`WEAPONS`	`STEEL, PLASTIC, OIL`
`COMPUTERS`	`COPPER, PLASTIC, GLASS`
`VEHICLES`	`STEEL, RUBBER, GLASS, OIL`

Rules:

In general, players are permitted to use whatever means that are not in violation of state, federal, local law, and not in violation University of Cincinnati, or College of Engineering rules, regulations, and computer usage policies to win the game.

For example, impersonation of the Monitor is completely permitted. In addition, impersonation of another Player to the Monitor or other Players is also permitted.

The following things are explicitly prohibited, and are considered poor game conduct:

Running a so-called Denial of Service attack on the Monitor server, any Player's server, or on any machine on the University of Cincinnati network or the Internet. (This includes sending multiple, rapid requests over and over to tie up a machine or server to stop it from getting an work done, or attempting to "crash" someone's machine or server.)
Refusing to answer requests on your server port based on what machine is connecting to you. You should always answer all requests, and you may answer them with a "not interested" answer. However, for game play to continue reasonably, you must respect and answer anyone connecting to your server port and sending you valid Message Groups.

Permission is granted to make and distribute verbatim copies of this document materials provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this document under the conditions for verbatim copying, provided also that they are marked clearly as modified versions, that the authors' names and title are unchanged (though subtitles and additional authors' names may be added), and that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.