This page defines the planned Quagents3 protocol.

ProtocolZero is the command protocol used for directly talking to Quagents. (The naming convention adopted here is that ProtocolOne is the protocol (or API) between the thing that sits on top of Quake and deals with socket I/O and whatever more abstract structure exists above that; ProtocolTwo would be two levels removed.) In particular, ProtocolZero is for the agent-based communication, not for the experimental control.

Overview

ProtocolZero commands are sent as plaintext over a TCP/IP socket to Quake on port 6000. Currently, any new connections to this port result in the creation of a new bot. Initial commands are simply ASCII strings of the form CMD PARAM. The final initial command given is "ready", after which the bot is spawned, and live commands become usable. Live command format is of the form A BB IDNUM PARAM_1 PARAM_2 PARAM_3 PARAM_4... \n

• where A is either a 't' or 'n' character, for 'then' or 'now', specifying scheduling (see below).
• where BB is the opcode of the instruction (always 2 characters).
• where IDNUM is a sequence of numeric characters representing an unsigned 32-bit integer. This code will be returned on completion, for the client's convenience. We imagine that users will typically make this a sequence number, but we do not require or enforce uniqueness.
• where P1... are parameters for the instruction, and may be any length. They are delimited by spaces, and therefore cannot contain spaces (even if explicitly quoted or escaped). Parameters should be printed in ASCII, so 253 is '2','5','3', not '\253'. Floats are interpreted by the atof() function.
• and \n is a newline. A carriage-return will work just as well.

Examples (each of these entries ought to be terminated by a newline):

• t ju 653 0 1
  • This command means: "after you do everything I've told you to do, jump. This is command id=0, and you should jump in direction 0 degrees at speed 1".
  • The server will respond after some time "cp ju 653 done".
• n po 0
  • This command means: "immediately pop what you're doing, this is command id=0".
  • The server will respond (almost instantly in this case) "cp po 0 done" then some other message about the previous command (say, "cp ju 653 popped").
• t mf 350 180 0.4
  • This command means: "after you do everything I've told you to do, walk forever, this is command id=350, direction=180 degrees, speed=0.4".
  • The server might eventually respond "cp mf 350 blocked".

Quagents model their behavior in the form of a double-ended queue that has a maximum capacity of 128 commands. Commands can be pushed onto either the front ("now" commands) or the end ("then" commands).

A future goal is to implement a GOD (Global Overview Descriptor) structure which collects and returns macroscopic game data, such as all Quagents' position and group-based metrics (TBD). The idea is that there are two types of connection permissions - GOD and Quagent. This is defined during initial connection, either with a character permission system or the utilization of a different port number.

Brief Specification

INITIAL COMMANDS

• name - "set name", sets what the name of the bot will be when it spawns. Takes one argument:
  • string name
• botfile - "set botfile", sets the botfile of the bot. Among other things, this determines the bot's in-game model. See botfiles for a list of options. FIXME: problem loading bot models?
  • string filename
• skill - "set skill", sets the skill level of the bot, which selects subsections from the botfiles.
  • integer skill
• team - "set team" sets the team of the bot ("red" or "blue") in CTF or team deathmatch mode.
  • string team
• ready - "ready", spawns the bot. Takes no arguments.

LIVE COMMANDS

• Movement:
  • mf - "Move Forever". Takes three arguments:
    • int obstacles
    • float direction
    • float speed
  • mb - "Move By". Takes four arguments:
    • int obstacles
    • float direction
    • float speed
    • float distance
  • ju - "JUmp once". Takes two arguments:
    • float direction
    • float speed
  • ro - "ROtate". Takes two arguments:
    • float yaw
    • float pitch
• Command Queue Management
  • po - "POp". Takes no arguments.
  • pa - "PAuse". Takes no arguments.
  • fa - "Forget All tasks". Takes no arguments.

GOD

Not Yet Implemented Commands

INITIAL COMMANDS

• General management
  • ready - switches the bot into the live state, spawning the bot. No more initial commands can be given. Live commands may now be given.
  • botfile [NAME] - selects the botfile to use for the bot
  • team [TEAM] - puts the bot on red/blue team if game is in team mode
  • initialPosition [LOCATION] - selects where the bot will start
  • name [NAME] - sets chatname of bot

LIVE COMMANDS

• Basic robot-like functions for users who want low-level fine control. (Implement first)
  • move [LOCATION] - bot moves to specified location. uses native pathfinding. It would be nice if along the way it used Quake's goal system. That would give us free puzzle-solving/button-pushing/surfacing-for-air.
  • move [OBJECT] - finds the location of specified object, and pathfinds to it using move[LOCATION].
  • echo [STRING] - reports a string back over the socket to the user
  • jump [VOID] - makes the Quagent jump in place.
  • crouch [VOID] - makes the Quagent crouch in place.
  • fireWeapon [VOID] - makes the Quagent fire the currently equipped weapon.
  • changeWeapon [WEAPON] - Quagent equips to the given weapon, if possible.
  • say [STRING] - Quagent "speaks" the STRING aloud. Has limited range. Possible implementation for user with speech synth. Used during Quagent collaboration.
  • look [VOID] - sends an image over the socket back to the user representing what the agent can see.
  • listen [TIME] - sends sounds back to the user for the specified time. This seems like it might be Hard.
  • zoom [VOID] - sends an image that zooms on the Quagent's current view. Uses quake zoom func.
• More complex robot-like functions. (Implement next)
  • follow [ENTITY] [DIST] - Bot moves toward/away from entity until it is at the given distance, if possible, and attempts to maintain that.
  • track [ENTITY] - Bot rotates to face entity.
• Invokable Quake Behavior (Implement last)
  • whereareyou? - returns what the bot usually says if you ask it that in a team game ("I'm by the rail gun in the blue base." sort of things).
  • followsmart [ENTITY] - smartly follows the given character using Quake's follow chat command.
  • playQuake - activates Deathmatch AI?
• Sensors
  • currentHealth - returns Quagent's current health
  • maxHealth - returns Quagent's maximum health.
  • currentArmour - returns Quagent's current armour.
  • maxArmour - returns Quagent's maximum armour.
  • getPosition - returns Quagent's current location (GPS)
  • currentItem - returns description of currently held items.
• The following are booleans constructed from other protocol functions. They are implemented in the API for convenience.
  • isDead? - returns true if agent is dead
  • hasAmmo? - true if agent has > 0 ammo.
  • hasArmour? - true if agent has > 0 armour.
  • hasItem? - true if agent is carrying an item.
• Behavior management system / agent management (Also implement first?)
  • peek - echoes a description of the current command.
  • peeknext - echos a description of the next command to evaluate

GOD

• Group-based sensor functions. Used to send data back to GOD client.
  • getPositions [VOID] - returns list of all Quagent positions
  • getMetric [METRIC] - returns evaluation of given metric (TBD).
• We also want GOD functions that can change the world state. These are TBD.

WalterAPI

Walter mentioned to me that he would like implementations of the following functions, they seem pretty possible:

• SENSORS
  • current_health
  • max_health
  • current_armor
  • max_armor
  • current_location
  • current_item
• ACTIONS
  • player_use
  • player_move_forward [DIST]
  • player_move_backward [DIST]
  • player_move_left [DIST]
  • player_move_right [DIST]
  • view_rotate_left [DIST]
  • view_rotate_right [DIST]
  • view_rotate_up [DIST]
  • view_rotate_down [DIST]
  • player_crouch
  • player_jump
  • weapon_fire
  • weapon_alternate
  • weapon_switch [WEAPON]