jWumpus

Installation

To start with with jWumpus, download the latest binary release.
You can also use the github release page to get more information about a release.

You also have to download the required libraries jWumpus-libs.zip. If you want to use the build in guis, also download forms-1.3.0.jar.

After that you need to include the downloaded jWumpus.jar into your build path.
Also extract libraries from jWumpus-libs.zip and also include them into your build path.
If you are using eclipse, just import jWumpus.jar into your workspace and use
Right-click on jWumpus.jar > Build path > Add to build path.
For using the build in guis also import and include the forms-1.3.0.jar the same way.

Usage

jWumpus offers different options to implement an own artificial intelligence (ai). The easiest way is to use the build in graphical user interface (gui) to control everthing like processing steps of the ai, loading maps, ...
It's also possible to do this by your own. Take a look at the exampels to know more about this.

Generally an instance of the class JWumpus from package de.northernstars.jwumpus.core handles the maps, checking of correct ai responses and other things. It also interacts with the ai to set the current state or current map.

Game processing

After a game map is loaded the ai gets a subset of the map from jWumpus including every field it visited before. So on start it gets only the start field. After that the ai is asked for an action to do as next step. Than the ai player moves to the next field accordingly to the last step and the ai gets the updated map, including the new field the player has moved to, and again jWumpus requests the next step of the ai and so on.

Implementing an artificial intelligence

Create a class for your ai and implement the interface WumpusAI from package de.northernstars.jwumpus.core. This interface includes some functions to control the behaviour of th ai.

putWumpusWorldMap(WumpusMap map)
Is used to set a new map. The ai should store a copy of that map.

putLastActionSuccess(ActionSuccess actionSuccess)
Puts information about the successfull execution of the last step.
The action of the last step could be FAILED, SUCCESSFULL, HIT_WALL (after trying to move to a field that is out of bounds of the map), WUMPUS_DEAD (after successfully shooting into one direction) or TIMEOUT (if the ai response for that step wasn't fast enough).

putRemainingTime(long time)
Sets remaining time in milliseconds until the ai has to return an action for the next step.

putPlayerArrows(int arrows)
Sets the number of remaining arrows of the ai player.

getAction()
Is called if the ai has to return an action for the next step.
The ai has a specified time to calculate an action like, moving up, down, left, right or shooting up, down, left or right. If the ai doesn't answer within time, no action is performed.

putPlayerState(PlayerState playerState)
Sets the state of the player on the field.
The player normally would be ALIVE. If he finds a gold field, he gets RICH, if he moves into a trap or a wumpus he is DEAD. If the game is ofer and ai player is not dead, he gets the status WINNER.

resetAi()
Is called if to reset the ai for maybe restarting the game or other reasons. The ai should erase or reset all calculated data (including the game map).

Default ai class template:

public class MyAi implements WumpusAI{
	private WumpusMap map;
	private long remainingTime = 0;
	private int remainingArrows = 0;
	private ActionSuccess lastActionSuccess = ActionSuccess.SUCCESSFULL;
	private PlayerState playerState = PlayerState.UNKNOWN;
	
	@Override
	public void putWumpusWorldMap(WumpusMap map) {
		this.map = new WumpusMap(map);
	}

	@Override
	public void putLastActionSuccess(ActionSuccess actionSuccess) {
		lastActionSuccess = actionSuccess;
	}

	@Override
	public void putRemainingTime(long time) {
		remainingTime = time;
	}

	@Override
	public void putPlayerArrows(int arrows) {
		remainingArrows = arrows;
	}

	@Override
	public Action getAction() {
		// Returns no action to do nothing
		return Action.NO_ACTION;
	}

	@Override
	public void putPlayerState(PlayerState playerState) {
		this.playerState = playerState;
	}

	@Override
	public void resetAi() {
		map = null;
		playerState = PlayerState.UNKNOWN;
	}
}

The map

The wumpus world is implemented inside a WumpusMap that stores a list of WumpusMapObject. The WumpusMapObject contains a list of items of WumpusObjects that descripe the content on the field the WumpusMapObject represents. An object on a field could be a PLAYER, WUMPUS, GOLD, TRAP, BREEZE, STENCH, TWINKLE.

The WumpusMapObject as three attributes. The row and the column are describing the position of the object on the WumpusMap. The boolean attribute visited is true if the player visited this field on the map.

Starting jWumpus

To start jWumpus an instane of JWumpus class from package de.northernstars.jwumpus.core is needed. The constructor of JWumpus class needs an instance of the ai.

Example:

public static void main(String[] args) {
	// Create new instance of JWumpus and pass instance of AI as parameter 
	new JWumpus( new ExampleAI() );
}

See also examples

Back