Quagents: Protocol

TIP: You may find it useful to read the Quagent Overview first before diving directly into the protocol description below.

Quagent Protocol (General)

The Quagent protocol is based on our experience with intelligent interactive computer agents. The controller can send the bot commands or ask it things. The bot confirms command receipt, sends error messages, or sends back data in response. The bot can also volunteer facts to you about events it senses. The general form of protocol messages is:
From controller to bot:
DO [Command] [Parameters]
ASK [Query] [Parameters]
From to bot to controller:
OK ( [Echo] ) (echos for positive confirmation, as in a submarine movie)
ERR ( [Echo] ) [Error Description] (can't begin to do command).
TELL [Event] [Parameters] (Asynchronous from bot: volunteers information).

Quagent Protocol (Specific)

+ and * are used as usual in regular expressions. UPPER-CASE strings are keywords. [lower-case-id]s represent strings that are parsed by scanf as an integer or real number. [Echo] is shorthand a copy of the command string in the responce. [Error-cause] is shorthand for a helpful error description. The Response
OK ( [Echo] ) or ERR ( [Echo] ) [Error-cause], in which the bot agrees to try to start the command, or to perform it, or says why not, is called the Standard response. Note the parentheses around the echoed response.

[Item-Name] is one of the strings BOX, GOLD, TOFU, BATTERY, DATA, KRYPTONITE, HEAD.

Commands, examples, associated parameters, semantics, and responses follow.

Movement

Command: WALKBY [distance] (e.g. WALK 20.0). Desire Bot to start walking in current direction. Bot will, at best, start walking in the right direction and silently stop when distance is reached. GOTCHA: The bot is really a bounding box and some graphics that change, often in a cycle, when it is doing something, for example walking. The "realistic" look requires that the bot move unequal forward distances between the various images that depict its action. You can see sample code in "monster" source files like .../game/m_gunner.c, which define the graphics, speed of motion, step sizes, etc. for the different quake denizons. Thus your bots take "different sized steps" during their walk cycle. Thus they only approximate the distance in the walkby command, and if you are counting steps (ticks) or something to compute your own distances, you can be surprised.
Response: Standard.

There is as of now no RUNBY command.

Command: STAND. Bot stops moving.
Response: Standard.

Command: TURNBY [angle]. Angle is in degrees, + (left turn) or - (right turn). Changes current yaw (orientation). Usually performed when bot is standing, maybe no reason not to issue while moving.
Response: Standard.

Actions

Command: PICKUP [Item-Name]. Immediately picks up one of the named items if bot is within the of the item.
Response: Standard. Error occurs if item is not close enough.

Command: DROP [Item-Name]. Immediately puts down one of the named items in the bot's inventory.
Response: Standard. Error occurs if bot not holding named item.

Perception

Command: ASK RADIUS [distance]. What items are within the given radius? (There is a system-imposed max-radius).
Response: ERR ( Echo ) [useful_descripton] or
OK ( [Echo] ) [number_of_objects] ([object name] [relative_position])*
, where [relative_position] is an (x,y,z) three-vector of relative distances. Example: OK ( ASK radius 100.0 ) 2 GOLD -20.0 30.0 0 Sandhya -320 -100 0

Command: ASK RAYS [number_of_rays]. What entities are surrounding bot in some set of directions. If number is one, ray's direction is in bot's current direction. The command shoots out [number_of_rays] evenly distributed on a circle around the robot.
Example: ASK RAYS 10
OK ( ASK RAYS 2 ) 1 world_spawn 315.0 277.1 0.0 2 TOFU 200 100 0
Response: ERR [useful_description] or
OK ( [Echo] ) ([ray_number] [object_name] [relative_position])+
relative_position is as in the Ask Radius command. The "world_spawn" entity is a wall or other game structure. You'll need this for bot path-planning, map-making, etc.

Command: CAMERAON. Normally the terminal shows the view from the (first-person) client. This puts the camera on the bot.
Response: Standard

Command: CAMERAOFF. Puts camera on client.
Response: Standard

Command: LOOK. Uploads an image buffer to the quagent controller presenting the world as seen from the bot's point of view.
Response: ERR ( [Echo] ) [useful_description] or
OK [Echo] [image_width] [image_height] [bytes_per_row] CR [binary_image_pixel_data]*
where CR is a carriage return (\n). Image width and height are in pixels. Thus the number of bytes in the pixel data is the image_height times the bytes_per_row. For most graphics engines, each pixel has four bytes, [red, green, blue, alpha], where the first three give RGB intensities and the last is a blending value that is probably useless for vision tasks. If, e.g., the game is run in a window whose size is 1024*768 and X-Window uses 16 bits or 2 bytes for each pixel, a successful LOOK request will return OK LOOK 1024 768 2048 \n followed by 1572864 bytes of image data.

Proprioception and Events

It is useful to be able to query the bot's internal state and to set certain bot parameters for experimental purposes.

Command: GetWhere. Where is bot, how oriented, moving how fast? these values must be in world coordinates to be meaningful.
Response: ERR ( [Echo] ) [useful_description] or
OK ( [Echo] ) [World_State], where [World_state] is a vector of coordinates and a velocity: (world_x, world_y, world_z, roll, pitch, yaw, velocity).

Currently (27 Jan 04) the velocity is returned as a constant 1. It's tricky, not obvious how we can set or get it. If there's a crying need, let us know through the suggestion mechanism.

Command: GetInventory. What is bot holding?
Response: ERR ( [Echo] ) [useful_description] or
OK ( [Echo] ) [Inventory] Where [Inventory] is (inventory_item_name)*

Command: GetWellbeing. How is bot doing in its life?
Response: ERR ( [Echo] ) [useful_description] or
OK ( [Echo] ) [Well_being]. Where [Well-being] is a vector of strings giving the numerical values of (age, health, wealth, wisdom, energy).

Sets: These commands all look alike and allow the experimenter to set values of experimental interest.

SetEnergyLowThreshold [value]
Also settable in the configuration file. When energy drops to this value, bot sends a single TELL message to the controller.

SetAgeHighhreshold [value]
Also settable in the configuration file. When rises above this value, bot sends a single TELL message to the controller.

[Condition] is a string signalling a condition either in the bot or in the world. The bot can volunteer the existence or parameters of this condition, or of an event in the world, using the TELL "response". TELL is not elicited by any DO command, but is sent unsolicited by the bot when the given condition is detected.

Command: None
Response: TELL [Condition].

The following [Condition]s generate TELLs:

STOPPED Motion stops before desired WALK_BY distance attained.
KRYPTONITENEAR: Kryptonite has entered the near effect range (from out of range or far range).
KRYPTONITEFAR: Kryptonite has entered the far effect range (from near or out of range).
KRYPTONITENOT: Kryptonite has gone outside the far effect range.
LOWENERGY: A warning: Energy fallen below Low-threshold: paralysis looms.
NOTLOWENERGY: Energy risen from below to above Low-threshold.
OLDAGE: A warning: Age above threshold: death looms.
DYING: [World_State] [Inventory] [Well_being]. Bot expiring of old age. Death rattle and dying dump.
STALLING: [World_State] [Inventory] [Well_being]. Bot out of energy, alive but unable to move.

Last updated: by costello