Changes between Version 29 and Version 30 of ProtocolOne


Ignore:
Timestamp:
Jun 28, 2011 7:51:17 PM (13 years ago)
Author:
jherwitz
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • ProtocolOne

    v29 v30  
    1 [[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 of all possible Quagent actions and queries, as well as providing useful compound . For all functions, a priority '1' indicates a "now" command and a priority "0" indicates a "then" command (this will change to a more intuitive format soon). All server commands and queries return the "commandid", which references the [[Command]] structure. [[ProtocolOne]] functions return values as specified.
     1== ProtocolOne ==
     2[[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.
    23
    3 = Usage =
    4 To use quagents, you must have the Client directory in your filesystem. Create a class with a main method, and import the [[Necessary Classes]]. 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.
     4For 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.
     5
     6= Overview =
     7An atomic Quagents scenario contains two phases of execution, an [[Initial Phase]] and a [[Live Phase]].
     8During 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.
     9The 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:
     10* [[Initial Commands]]
     11* Live Commands
     12 * [[Actions]]
     13 * [[Queries]]
     14 * [[Command Queue Management]] (CQM)
     15 * [[Compound Functions]]
     16
     17'''Flow of Execution'''
     18To 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.
    519
    620''Example:''
     
    2741}}}
    2842
     43== Command Structure ==
     44[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.
     45The 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.
     46It 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).
     47It 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).
     48
     49''Example''
     50The following two code blocks are identical.
     51{{{
     52client.fireWeapon();
     53}}}
     54{{{
     55FireWeapon fw = new FireWeapon();
     56}}}
     57
     58
     59= Retrieving Data =
     60
     61The following is an example of a complete Quagents session:
     62{{{
     63Client quagent = new Client("127.0.0.1");
     64
     65//begin initial phase
     66quagent.name("Billy");
     67//end initial phase
     68quagent.ready();
     69//begin live phase
     70quagent.
     71}}}
     72
    2973Note that using multiple quagents is as simple as creating a new Client object, and following the same steps as above for each.
    3074
    31 = Initial Commands =
    32  {{{name(String name)}}}
    33   Specifies the Quagent's ingame name.
    34  {{{ready()}}}
    35   Spawns the bot, opens the nonblocking socket reader, and starts the live section of the game. This is the final command called during the initial section.
    36  {{{ready(String[] opcodes)}}}
    37    Same core functionality as above. The ''opcodes'' array specifies operations which the user wishes to be automatically updated on through the wiki:datastream.
    38 = Live Functions =
    39  '''[[ProtocolZero]] Actions'''
    40   {{{move(double dir, double dist, double speed, int obstacles, int priority)}}}
    41    Moves by ''dist'' towards the ''dir'' direction at ''speed'' quickness. ''obstacles'' indicates whether the bot automatically maneuvers past simple obstacles.
    42   {{{move(double dir, double speed, int obstacles, int priority)}}}
    43    Moves indefinitely towards the ''dir''direction at speed ''speed''. ''obstacles'' is as above.
    44   {{{move(double[] point, double speed, int obstacles, int priority)}}}
    45    Moves to the specified ''point''. The ''point'' array should be in {x,y} form.
    46   {{{move(double dir, long time, double speed, int obstacles, int priority)}}}
    47    Moves in the specified direction for ''time''.
    48   {{{jump(double dir, double speed, int priority)}}}
    49    Jumps in the ''dir'' direction at speed ''speed''.
    50   {{{rangeFinder(int type, int range, double rot, double azi, int priority)}}}
    51    Uses the wiki:rangefinder at a limited ''range'', in the direction specified by the ''rot''ational angle and the ''azi''muthal angle. The rangefinder is of the given ''type'' (for more information, see wiki:rf).
    52   {{{rangeFinder(int type, int priority)}}}
    53    Uses the wiki:rangefinder in the current direction, with no limit on distance. Uses the specified ''type''.
    54   {{{rangeFinder(int priority)}}}
    55    Uses the wiki:rangefinder in the current direction, with no limit on distance. Uses type #1.
    56   {{{rotate(double rot, double azi, int priority)}}}
    57    Rotates the bot by a rotational angle ''rot'' and an azimuthal angle ''azi''.
    58  '''Command Queue management'''
    59   {{{forgetAllTasks(int priority)}}}
    60    Clears Quagent command queue, acts as a soft "reset".
    61   {{{pause(int time, int priority)}}}
    62    Pauses command queue execution.
    63   {{{pop(int priority)}}}
    64    Pops action off command queue.
    65   {{{skip(int priority)}}}
    66    Skips the next AI game frame. For more information, see wiki:sk.
    67  '''[[ProtocolZero]] Queries'''
    68   {{{currentHealth(int priority)}}}
    69    Returns Quagent's current health.
    70   {{{maxHealth(int priority)}}}
    71    Returns Quagent's maximum health. Kind of useless.
    72   {{{currentArmour(int priority)}}}
    73    Returns Quagent's current armor. British spelling adds class.
    74   {{{maxArmour(int priority)}}}
    75    Returns Quagent's maximum armor.
    76   {{{canSee(int entityid, int priority)}}}
    77    Returns true if entity can see specified ''wiki:entityid''. Also returns distance, yaw, and pitch to target.
    78   {{{facing(int priority)}}}
    79    Returns the Quagent's current direction vector.
    80   {{{radar(double range, int priority)}}}
    81    Returns a list of all entities within ''range''.
    82   {{{whatIs(int entityid, int priority)}}}
    83    Returns a description of the entity specified by ''entityid''.
    84  '''[[ProtocolOne]] Actions (compound functions)'''
    85   {{{rotateMove(double rot, double azi, double dist, double speed, int obstacles, int priority)}}}
    86    Rotates by ''rot''ational and ''azi''muthal angles to face a new direction, then moves in that direction for ''dist''.
    87   {{{rotateMove(double rot, double azi, double speed, int obstacles, int priority)}}}
    88    Rotates by 'rot' and 'azi' to face a new direction, then moves in that direction indefinitely.
    89   {{{rotateFireWeapon(double rot, double azi, int priority)}}}
    90    Rotates by 'rot' and 'azi' to face a new direction, then fires weapon.
    91   {{{moveFireWeapon(double dir, double dist, double speed, int obstacles, int priority)}}}
    92    Moves ''dist'' distance in the specified ''dir'' direction, then fires weapon.
    93   {{{findMaxiumumDirection(int priority)}}}
    94    Returns the deepest direction as detected by the type 1 wiki:rangefinder. This values is directly returned by the function.
    95   {{{faceMaximumDirection(int priority)}}}
    96    Finds the maximum direction, and then rotates to face it. Does not return anything.
    97   {{{findEntityDirection(int entityid, int priority)}}}
    98    Directly returns the direction of the specified entityid, in the form of [rotational,azimuthal]. Returns -1 if nothing found.
    99   {{{faceEntityDirection(int entityid, int priority)}}}
    100    Finds the direction of specified entity, then rotates to face this direction.
    101   {{{gotoEntity(int entityid, double speed, int obstacles, int priority)}}}
    102    Moves to the specified entity. using the specified ''speed''.
    103   {{{followEntity(int entityid, double speed, int obstacles, long duration, int priority)}}}
    104    Follows the specified entity for ''duration''.
    105   {{{showImage(int priority)}}}
    106    Displays a depth mapping representing the bot's current "sight".
    107   {{{maintainDistanceFrom(int entityid, double distbuffer, double speed, int obstacles, long duration, int priority)}}}
    108    Maintains a "space buffer". If the specified entity enters the buffer zone, the Quagent will run in the opposite direction.
    10975= Class structure = 
    11076