== ProtocolOne ==
[[ProtocolOne]] is the Java API which abstracts the Quagents game engine to a simple Java interface. The underlying clientside structure maintains data transmission, reception, and storage, while providing an API for Quagent actions and queries. Named for its level of abstraction, [[ProtocolOne]] builds on [[ProtocolZero]], allowing easy access to its hooks through a functional interface. The interface aims to provide the user easy access to Quagent commands, while handling all client/server interaction, data formatting, and data storage, internally. 

For API code documentation, see the [http://www.google.com Javadoc]. This wiki will focus mainly on the usage of [[ProtocolOne]] (intended for users, rather than developers), while the [http://www.google.com Javadoc] will provide a comprehensive specification of the [[ProtocolOne]] API. 

= Overview =
An atomic Quagents scenario contains two phases of execution, an [[Initial Phase]] and a [[Live Phase]]. 
During the [[Initial Phase]], users may specify pre-spawn attributes (e.g., initial spawn position or the Quagent's in-game name). The user may '''not''' call Quagent actions or queries during this stage. During the [[Live Phase]], Quagents are spawned and active in the scenario. All Quagent actions and queries are unlocked for the user to utilize.
The API contains two distinct function types, which correspond to the aforementioned phases. These phases are disjoint - a "Live Command" may not be used during the "Initial Phase", and vice-versa.  These are:
* [[Initial Commands]]
* Live Commands
 * [[Actions]]
 * [[Queries]]
 * [[Command Queue Management]] (CQM)
 * [[Compound Functions]]

'''Flow of Execution'''
To create a Quagent, simply create a new client using the Client constructor. The constructor takes one argument, which must specify the IP address of the Quagents server.

''Example:''
 {{{
Client quagent = new Client("127.0.0.1");
}}}

Now, before the bot spawns, you may use initial commands to specify certain static parameters. These are optional. When you have completed these modifications, call the ready() function to initiate the live section of the session.

''Example:''
 {{{
quagent.ready();
}}}

During the live section, you are free to call any [[ProtocolZero]] or [[ProtocolOne]] functions you wish (with the exception of initial commands).

''Example:''
{{{ 
//this will make the Quagent face and shoot at the user. 
while(true){
    quagent.faceEntityDirection(0,1);
    quagent.fireWeapon(1);
}
}}}

== Command Structure ==
[ProtocolOne] provides the user two ways of executing Quagent commands. All commands are represented as objects. These objects handle writing the specified command to the server, automatically update data fields with any relevant server data response, and maintain auxiliary data related to the command, such as command [[exitcode]] and runtime.
The user may choose to execute commands by either explicitly instantiating these objects or calling the relevant function. Each command has an object which is specific to its individual properties, such as data response, parameter access, and socket server protocol. To execute a command explicitly using the object, simply call.
It is important to note that all Commands are implemented as [http://download.oracle.com/javase/1.4.2/docs/api/java/util/TimerTask.html TimerTasks], so a user may easily implement an application involving high-level scheduling or planning using [http://download.oracle.com/javase/1.4.2/docs/api/java/util/Timer.html Timers] (this is actually how the periodic execution is implemented). 
It is recommended that users new to Quagents use the command functions, as these provide a more intuitive command interface and also allow the client to record any results in its command history (although this may be moved into the Command class to ensure identical functionality between both methods of execution).

''Example''
The following two code blocks are identical. 
{{{
client.fireWeapon();
}}}
{{{
FireWeapon fw = new FireWeapon();
}}}


= Retrieving Data =

The following is an example of a complete Quagents session:
{{{
Client quagent = new Client("127.0.0.1");

//begin initial phase
quagent.name("Billy");
//end initial phase
quagent.ready();
//begin live phase
quagent.
}}}

Note that using multiple quagents is as simple as creating a new Client object, and following the same steps as above for each.

= Class structure =  

= Example behaviors =
* These assume that the Client object (which represents a Quagent) has been instantiated as "client".
'''Take an depthmap of the player.'''
 {{{
client.faceEntityDirection(0,1);
client.showImage(1);
}}}