Wumpus-World-Game

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

Wumpus-World-Game

★ 17 Open GitHub ↗

🧠 This repository features an intelligent agent that autonomously explores the Wumpus World—a grid filled with hidden Wumpuses, pits, and gold. Using logic, inference, and planning, the agent avoids dangers, finds gold, and escapes. Includes real-time Pygame visualization and customizable settings, ideal for AI/game logic study and experimentation

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Wumpus World Game

![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20MacOS-lightgrey.svg)
![Pygame](https://img.shields.io/badge/pygame-2.x-orange.svg)

An intelligent agent simulation of the classic Wumpus World problem, featuring a graphical interface and advanced reasoning modules. The agent explores a grid-based world, avoids deadly Wumpuses and pits, and tries to retrieve the gold and escape safely.

</div>

## Demo

![Wumpus World Demo](https://raw.githubusercontent.com/NhanPhamThanh-IT/Wumpus-World-Game/main/demo/demo.gif)

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Game Controls](#game-controls)
- [Project Structure](#project-structure)
- [How It Works](#how-it-works)
- [Credits](#credits)
- [License](#license)
- [Contributing](#contributing)
- [Troubleshooting](#troubleshooting)
- [Useful Links](#useful-links)

## Features

- Customizable grid size, number of Wumpuses, and pit probability
- Moving Wumpus option for advanced challenge
- Intelligent agent with knowledge base, inference engine, and planning module
- Pygame-based graphical interface
- Real-time display of agent's percepts, actions, and score
- Modular code for easy extension and experimentation

## Installation

1. **Clone the repository:**
   ```sh
   git clone https://github.com/NhanPhamThanh-IT/Wumpus-World-Game.git
   ```
2. **Install Python 3.11+ and pip**
3. **Install required packages:**
   ```sh
   pip install pygame
   ```

## Usage

Run the game from the command line:

```sh
python main.py
```

You will be prompted to enter:

- Grid size (default: 8)
- Number of Wumpuses (default: 2)
- Pit probability (default: 0.2)

## Game Controls

- The agent is fully autonomous; you only need to set the initial parameters.
- To quit, close the game window.

## Project Structure

```
main.py                # Entry point, runs the game loop
config/environment.py  # World generation and environment logic
logic/agent.py         # Agent reasoning and decision-making
logic/knowledge_base.py# Agent's knowledge representation
logic/inference_engine.py # Logical inference for safe/risky cells
logic/planning_module.py  # Pathfinding and planning
ui/visualization.py    # Pygame-based GUI
README.md, LICENSE     # Documentation and license
```

## How It Works

1. **Environment:**
   - Generates a grid with Wumpuses, pits, and gold.
   - Updates percepts (stench, breeze, glitter) for each cell.
2. **Agent:**
   - Maintains a knowledge base of visited and inferred cells.
   - Uses an inference engine to deduce safe/risky cells.
   - Plans paths to gold, safe unvisited cells, or escape.
   - Executes actions: move, turn, grab, climb out, shoot arrow.
3. **Visualization:**
   - Displays the grid, agent, hazards, and percepts.
   - Shows agent's score, last action, and percepts in real time.

## Credits

- Developed by Nhan Pham Thanh
- Inspired by the classic AI Wumpus World problem

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

## Contributing

Contributions, bug reports, and suggestions are welcome! Feel free to open issues or submit pull requests.

## Troubleshooting

- If you encounter issues with Pygame, ensure your Python and pip versions are up to date.
- For graphical errors, check your system's graphics drivers and Pygame installation.
- For any other problems, please open an issue on the [GitHub repository](https://github.com/NhanPhamThanh-IT/Wumpus-World-Game/issues).

## Useful Links

- [Pygame Documentation](https://www.pygame.org/docs/)
- [Wumpus World (Wikipedia)](https://en.wikipedia.org/wiki/Wumpus_world)
- [AI: A Modern Approach](http://aima.cs.berkeley.edu/)

## Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Game Controls](#game-controls)
- [Project Structure](#project-structure)
- [How It Works](#how-it-works)
- [Credits](#credits)
- [License](#license)

## Features

- Customizable grid size, number of Wumpuses, and pit probability
- Moving Wumpus option for advanced challenge
- Intelligent agent with knowledge base, inference engine, and planning module
- Pygame-based graphical interface
- Real-time display of agent's percepts, actions, and score
- Modular code for easy extension and experimentation

## Installation

1. **Clone the repository:**
   ```sh
   git clone https://github.com/NhanPhamThanh-IT/Wumpus-World-Game.git
   ```
2. **Install Python 3.11+ and pip**
3. **Install required packages:**
   ```sh
   pip install pygame
   ```

## Usage

![Wumpus World Demo](https://raw.githubusercontent.com/NhanPhamThanh-IT/Wumpus-World-Game/main/demo/demo.gif)

Run the game from the command line:

```sh
python main.py
```

You will be prompted to enter:

- Grid size (default: 8)
- Number of Wumpuses (default: 2)
- Pit probability (default: 0.2)

## Contributing

Contributions, bug reports, and suggestions are welcome! Feel free to open issues or submit pull requests.

## Troubleshooting

- If you encounter issues with Pygame, ensure your Python and pip versions are up to date.
- For graphical errors, check your system's graphics drivers and Pygame installation.
- For any other problems, please open an issue on the [GitHub repository](https://github.com/NhanPhamThanh-IT/Wumpus-World-Game/issues).

## Useful Links

- [Pygame Documentation](https://www.pygame.org/docs/)
- [Wumpus World (Wikipedia)](https://en.wikipedia.org/wiki/Wumpus_world)
- [AI: A Modern Approach](http://aima.cs.berkeley.edu/)

- The agent is fully autonomous; you only need to set the initial parameters.
- To quit, close the game window.

## Project Structure

```
main.py                # Entry point, runs the game loop
config/environment.py  # World generation and environment logic
logic/agent.py         # Agent reasoning and decision-making
logic/knowledge_base.py# Agent's knowledge representation
logic/inference_engine.py # Logical inference for safe/risky cells
logic/planning_module.py  # Pathfinding and planning
ui/visualization.py    # Pygame-based GUI
README.md, LICENSE     # Documentation and license
```

## How It Works

1. **Environment:**
   - Generates a grid with Wumpuses, pits, and gold.
   - Updates percepts (stench, breeze, glitter) for each cell.
2. **Agent:**
   - Maintains a knowledge base of visited and inferred cells.
   - Uses an inference engine to deduce safe/risky cells.
   - Plans paths to gold, safe unvisited cells, or escape.
   - Executes actions: move, turn, grab, climb out, shoot arrow.
3. **Visualization:**
   - Displays the grid, agent, hazards, and percepts.
   - Shows agent's score, last action, and percepts in real time.

## Credits

- Developed by Nhan Pham Thanh
- Inspired by the classic AI Wumpus World problem

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

</div>

Wumpus-World-Game

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README