Quagents: Programming

What is a Quagent?

A quagent is Quake II bot that is controlled by an external program. The Quake II quagent mod provides a quagent server which quagent client code connects at port 33333 in order to establish a communications channel. Instructions to, and feedback from, the bot is accomplished using a simple text based protocol (see Quagent Protocol Reference). The idea is that programs can be written external to the Quake code base, with no knowledge whatsoever of the Quake game engine code, in any programming language. All that is required is a basic socket connection and knowledge of the quagent messaging protocol. Quagent programs provide the "brain" for the bot and through commands and feedback provide a system for the bots behaviors and reflexes.

Configuration

You can configure characters and items to spawn and their locations in the world when the game loads by optionally creating a quagent.config file and placing it in the current working directory where you will run the game from. See the configuration file page for details on the format and options available.

mapping tip:
Walk the client (FPS) around and type ]viewpos at the console. It will give your current world vector coord.
(see console commands for more commands)

Java Examples

Minimal Example Using the Quagent Protocol from a Java Program

QuagentControl

QuagentControl illustrates how easy it is to create a simple client that can spawn a quagent bot and use some rudimentary control commands provided by the quagent protocol to navigate the bot around the world. The QuagentController program has no Quake code whatsoever nor does it need any. It simply sends and receives quagent messages. This demonstrates how one could begin to develop external programs that have a communications channel into a running Quake II session without having to know anything at all about programming the actual game engine code!

tip:
You can add a quagent.config file to control which character
and location your bot will be spawned as well as adding some other items to rooms in the map.
(see Quagents Configuration File for more info)

Find the code at examples/QuagentControl in the source bundle (see Obtaining the Code).

Example code snippet from QuagentControl.java which show the code that controls the direction buttons for walking the quagent bot around.
out is a handle on an output socket. (See Quagents Protocol Reference) Each directional button simply prints a quagent command to the communications channel (the socket) to control the bots behavior. A more sophisticated quagent would analyse feedback from the bot and make decisions about how to direct the bots behavior beyond simply steering.

//
// button actions defined
//

private void moveForward(){
debug("moveForward()");
out.println("do walkby 2000");
}

private void moveBackward(){
debug("moveBackward()");
out.println("do turnby 180");
out.println("do walkby 2000");

}
private void moveLeft(){
debug("moveLeft()");
out.println("do turnby 90");
out.println("do walkby 2000");

}
private void moveRight(){
debug("moveRight()");
out.println("do turnby -90");
out.println("do walkby 2000");

}
private void stopMoving(){
debug("stopMoving()");
out.println("do stand");

}

(see the instructions for running the QuagentControl example)

Encapsulating the Command Interface

DrunkenMaster

You might want to insulate yourself from the details of dealing with messages by providing objects and methods that encapsulate the parsing details.
For example: code snippet DrunkenMaster example (examples/DrunkenMaster see Obtaining the Code)


      Command cmd = new WalkCommand(20);
      this.send(cmd);

      Query query = new RadiusQuery(33.0);
      Answer answer = this.ask(query);
      if (answer.isOK()) {
          ... extract answer.value() and cast or something ...
      }

Jess Java Library Examples

Two of the code examples use the production system language Jess. JessQuagent and Wumpus. Jess is easily available by download and requires an academic-style non-dissemination and not-for-profit license, also available on line at
http://herzberg.ca.sandia.gov/jess/