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. Each command should be terminated with a newline character.

Quagents model their behavior in the form of a double-ended queue (note: some nastiness here since there's no dynamic memory allocation - but it seems possible to 'fake it' pretty well with two arrays). Commands can be pushed onto either the front ("now" commands) or the end ("then" commands). Some commands may generate automatic subcommands that are pushed onto the front of the queue - for example, "get railgun" might insert a bunch of moves first.

Additionally, all commands are optionally suffixable with an IDSTRING. If an IDSTRING is specified, when the task is complete, the agent should report "COMPLETED IDSTRING" or something like that (this is so simple to implement that it might be better left to a higher level: just insert an 'echo COMPLETED IDSTRING' task that is just behind the task itself). This may seem redundant given that the "then" commands already allow explicit task scheduling, but I can imagine it being nice to know precisely when given actions complete, without having to remember what order you issued commands in.

It might be nice to allow all commands to be suffixed with a MAX_DURATION as well? The idea there is that you get a unified framework for specifying how long to do something before quitting.

A future goal is to implement a GOD (Global Overview Director) 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.

Specification

The front-end API is currently implemented in Java. The following functions are defined in the API, and their implementation is in progress.

All the below commands should be prefixable with "now" or "then" to determine where they go on the queue. This will be implemented with an additional parameter for all function calls. All commands should start with a letter, not a number or other character. Commands should not have spaces other than to separate parameters.

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 [DIRECTION,DISTANCE] - bot moves in given direction for the specified distance.
  • 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 [DIRECTION] - bot moves according to DIRECTION indefinitely until a collision occurs.
  • move [OBJECT] - finds the location of specified object, and pathfinds to it using move[LOCATION].
  • rotate [ROTATIONAL,AZIMUTHAL] - rotates the bot clockwise by the specified rotational and azimuthal angles.
  • 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?)
  • forgetalltasks - clears the command queue
  • pause [TIME] - if TIME=0, wait forever, else wait TIME milliseconds. (As with all commands, can be interrupted with "now pop".)
  • pop - deletes the current command. If this is the only command, does nothing. (Note: weird to think about: "then pop, then walkby" - pop will clear the walkby even though it was issued before it.)
  • peek - echoes a description of the current command.
  • peeknext - echos a description of the next command to evaluate

Overseer

• getPositions [VOID] - returns list of all Quagent positions
• getMetric [METRIC] - returns evaluation of given metric (TBD).

Implementation

Each of these behaviours will be modelled as an ai_node function. Parameters will be saved in the bot state struct, which gets passed to these functions.

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]