= Java Quagents Client = [[Image(Java_Duke.png)]] The [[Java Quagents Client]] is made of two parts - the core API and the front-end [[Scenarios]]. The API is meant for internal development, and will usually not be necessary to modify for most intents and purposes. The front-end is meant for general user development - research, education, et cetera. This wiki is meant to detail the abstract structure of the client. For information on usage, see the [[Java Client Tutorial]]. == Compiling The Client == To compile the client, simply navigate to the client/API/ directory and type "ant". To remove the associated build directory and executable jar, type "ant clean". == Launching The Client == The server and client must be launched independently. The server ''must'' be running when the client jar is executed. === To start the server: === * Navigate to the top-level quagents directory. * Launch the server using the run script by executing "./run.sh ", where corresponds to the directory which you specified during initial installation. '''NOTE:''' if you receive an error when attempting to run the script, use the command "chmod u+x run.sh" to fix. === To start the client: === * Navigate to /client/API/, where corresponds to the top-level quagents directory. * Execute the command "java -jar Quagents3.jar ". * For a list of usable maps and scenarios, execute "java -jar Quagents3.jar" (note: this is not synchronized with new maps and scenarios automatically, these must be inserted at ScenarioStarter.java). == Internal Structure == === Entities === All objects in quake which may impact the game world are treated as Entities, and represented with the Entity interface. This includes both the GOD (Director) and Quagents. All Commands and ReaderThreads (see below) use entities to perform internal operations, so socket operations are independent of entity type. ==== Client (Entity) ==== The Client entity is an implementation of a QuagentEntity, which is a derived form the aforementioned Entity. It represents a Quagent in the Quake world. The Client is notable because it provides a multitude of convenience methods for executing Commands. We realize that the usage of the original Command execution may unintuitive for some users, so this provides a more functional paradigm. === Commands === The Java client is built on Command objects. These objects each represent one or more commands. ProtocolZero commands have a one-to-one correspondance with the commands detailed in [[ProtocolOZero]]. They do not instrument or interpret function, and may be thought of as simply wrapping the protocol commands. ProtocolOne commands, on the other hand, may have an arbitrary level of complexity, or may even not deal with quake at all! These commands may call one or more [[ProtocolZero]] commands, and adjust or interpret data to developer desire. An example may be found in CartesianSensor2D.java. Each command must first be instantiated, which sets all relevant parameters and generates necessary structures for use in data retrieval. At this point, the Command is independent of a command "executor". Once the command is constructed, it must then be attached to an executor. This may most easily be accomplished by using the Entity ''execute()'' or ''start()'' functions, the difference being that ''execute()'' blocks until the command is completed while ''start()'' does not. Once the command has completed execution, the user may access data by calling Command-specific functions. It is important to note that these functions do not block for return, so it is recommended that users use caution when executing non-periodic commands. ==== Periodic Commands ==== Each Command also has an associated periodic functionality. If desired, the user may add an additional argument to the end of any constructor (or Client entity function), and the Command will execute automatically (in a separate thread) at a period of that many milliseconds. This is very useful for sensors or other queries that the user might want to be updated frequently or automatically. === ReaderThread === Another important structure is the non-blocking ReaderThread. Each entity has a ReaderThread associated with it, which handles read operations from the socket. Once a message is read, it is parsed and interpreted, at which point the ReaderThread locates the Command object associated with the message (by using the command ID and a list of currently running operations) and performs the relevant operation. === Listeners === Multiple types of swing-like action listeners have been implemented. The user may choose to use these to achieve a reactive paradigm code style, or mix them with aforementioned styles to create a custom code style. ==== Event ==== The event listener is triggered by in-game [[Events]]. These differ between GOD and Quagent connection, but generally relate to changes in the gamestate or significant in-game occurrences, such as Quagent death, players connecting or disconnecting, or the "say" command ([[sy]]). The functions are automatically triggered when an event is read, so the user must only define and attach the listener to receive events. ==== Command Termination ==== The command termination listener has two forms - one attached to an individual command and one attached to an entity as a while. The termination listener is accessed when a command termination message has been read from the server. This does not guarantee successful completion, but the user may poll exit code and relevant data to determine this. == External (User-Level) Structure == === [[Scenarios]] === [[Scenarios]] represent an packaged set of changes to the Quagents server and executable client code. This forms an atomic Quagents execution, e.g. a specific experiment or lecture. Both the launcher and the standard JAR executable (described in the above) are configured to accept and execute scenarios. == List of Files == === edu.rochester.cs.quagents3.aux === AudioInput.java - Captures user voice data for use in the CaptureTheFlag scenario experiment. Capture.java - Used in conjunction with AudioInput to capture user audio data. === edu.rochester.cs.quagents3.client === AbstactWumpusSolver.java - Used in support of the WumpusWorld scenario. Agent.java - Depreciated entity implementation. BatchRangeFinder.java - Represents [[ProtocolZero]] batch rangefinder command. CameraQuagent.java - Used for the [[RoboticImagingSystem]] scenario. CanSee.java - Represents the [[ProtocolZero]] cansee command. CartesianSensor2D.java - Example of [[ProtocolOne]] command. Shoots rangefinder in four axial directions. Used during [[CaveExploration]]. CheckInventory.java - Represents the ProtocolZero checkinventory command. Client.java - Implementation of QuagentEntity. Provides convenience functions for accessing and executing commands. ClientInf.java - Interface for Client.java. Command.java - Abstract superclass for all commands. CommandTerminationListener - defines the command termination event listener. CommandType.java - enumerated type allows for command type checking. Crouch.java - Represents crouch ProtocolZero command. CTFPlayer.java - represents a player in the CaptureTheFlag scenario. CurrentAmmo.java - Represents a currentammo ProtocolZero command. CurrentArmor.java - Represents a currenarmor ProtocolZero command. CurrentHealth.java - Represents a currenthealth ProtocolZero command. CurrentLocation.java - Represents a currentlocation ProtocolZero command. periodic instantiation works like an in-game gps. == For More Information == For more detailed information on class and method uses, see the javadoc, located at /client/API/doc/ == Note == For some reason TRAC keeps linking CamelCase as wiki pages. Many of these are not intended as actual pages.