Wumpus World Simulator

CSE 5361 - Artificial Intelligence II
Dr. Larry Holder

This document describes how to use the Wumpus World simulation in C++. The wumpus simulation library contains all simulation code as well as a main function. All you will need to provide is the specific code for choosing actions to take.

Player Class Description

The code you write will be a subclass of the class "Player". The Player class performs all the interfacing to the simulation for you, as well as providing you with a history of seen percepts and actions taken.

There are 6 methods your subclass of Player may implement:

There are several methods implemented by the Player class that you can use to get information about your state:

Global Player Variable

You should create a global static variable of the type of your Player subclass. This is all that is needed to add your player to the simulation.

class MyPlayer : public Player { ... };
static MyPlayer myPlayer;

Percept/Action Lists

The Player class provides you with 2 history lists: perceptList and actionList. These instance variables are of a template class called LinkedList<T>. LinkedList objects can be accessed as arrays, and they also maintain a current element pointer for transversing the list.

These are some of the methods you may use to access the lists:

actionList is accessed in the same manner.

Percept Class Description

The Percept parameter is a reference to a object of class Percept. These are the methods you may use to access the Percept. The first five methods return 1=True and 0=False.

The following two methods will be available later in the course.

Image Class

The Image class stores a 2 dimensional array of binary values representing the image. The image can be displayed for test purposes using the output stream operator "<<".


The defined Action symbols to be returned by your process() method are:

You can use the output stream operator "<<" with Action values.

Player KnowledgeBase

The Player class implements a simplified, PROLOG-like knowledge base, called knowledgeBase. You can make basic PROLOG queries, however there is no cut feature, and no PROLOG lists or other advanced features. You must use an ampersand ("&") instead of a comma (",") to seperate predicates on the right hand side of a rule.

Here is an example database:

predicate(X) :- predx(X) & predyz(X,Y).

Here is a list of the methods available for accessing the knowledge base:

Compiling the Simulator

Include directory: /public/cse/5361/wumpus/lib/
Simulation Library: /public/cse/5361/wumpus/lib/libwumpus.a
An example player class: /public/cse/5361/wumpus/MyPlayer.cc
An example makefile: /public/cse/5361/wumpus/Makefile

The example makefile should be easily modified to suit your needs.

Simulation Invocation

The following table is a summary of command line options.

-h Display help.
-s size Generate a random world of size "size". The default is to use the 4x4 world from Russel/ Norvig. Random worlds contain multiple gold pieces, pits, and Wumpi.
-w file Read the world from a file
-n steps Maximum number of steps per trial (default is 1000)
-t trials Number of trials (default is 1)
-r seed Provide the Seed for the Random Number Generator. This is used if you want to replay a game exactly.
-m mode Wumpus Movement Mode. Modes are:
  • sit
  • spin
  • random
  • bump
  • loop
  • goto-gold
  • goto-pit
The default is "sit".
-e Allow Use of Extended Percepts (i.e. Hints and Images)
-p arg Pass some argument to your Player Class via the Player::configure() method.

When the simulation runs, you will see an initial diagram of the world. At each step, you will see messages about what "The Agent" (which is the name of your Player) is doing, along with an updated diagram of the world. At the end of the game, you will see the ending state of the game as well as your player's score. If you run multiple trials, each trial will show the initial state of the world, the steps taken, and then ending score. After all trials, you will see a collection of performance analysis data for your agent.

A world file describes the initial state of a world. Every time the simulation is run, it writes a world file called .world, so that you can re-run a world again if want. You can also design your own world files. A world file has the following format:

Graphical User Interface

The simulator will run in text only mode if there is no environment variable DISPLAY defined. In graphics mode, all text output will still be generated, as well as providing graphical displays and greater control over running trials.

Below is a table of the symbols that you will see on the graphical version of the simulation.

Player (Facing Down)
Player (Facing Up)
Wumpus (Facing Down)
Wumpus (Facing Up)
Player (Facing Left)
Player (Facing Right)
Wumpus (Facing Left)
Wumpus (Facing Right)
Player (Dead)
Pot of Gold
Wumpus (Dead)
Bottomless Pit


If you have any questions or problems, here is how you can contact me. I am usually only available during the day, for both phone and e-mail.

Robert Duff
duffrd@aud.alcatel.com (preferred)
Day Time Phone: (214) 996-6964