# Intro2AI: Project 02 - Logical Search Agent

## About this assignment:
**Rule:**
- World 10x10.
- Room (1, 1) is the bottom-left one, and Room (10, 10) is the top-right one.
- Coordinate (\<horizontal>, \<vertical>).
- Agent appears randomly, always facing to the right.
- Random number of pits and golds in the world.
- At least one Wumpus.
- The agent carries an infinite number of arrows.
- The game will end when one of the three following conditions occurs:
1. The agent dies.
2. The agent kills all of the Wumpus AND grabs all the gold.
3. The agent climbs out of the cave.

**The scores:**
- Add 10: climb out of the cave.
- Add 100: pick up each gold.
- Reduce 10: move from one room the next one.
- Reduce 100: shoot an arrow.
- Reduce 10000: die.

**Input:**

- The first line: size of map.
- N next lines:
- Empty: -
- Wumpus: W
- Pit: P
- Breeze: B
- Stench: S
- Agent: A
- Between two adjacent rooms: .

For example: **-.BS.W.BS.P.B.-.-.-.-**

## Introduction

| Student's Name | Student ID |
| -------------------- | :--------: |
|La Thanh Thai (Leader)| 18127207 |
|Hy Phu Quyen | 18127195 |

## Overview

| Assignment | Self-rating | Progress | Contributors |
| :---------------- | :----------: | :-----------------: | ----------------------------: |
| Gather References | 10/10 | :heavy_check_mark: | La Thanh Thai<br>Hy Phu Quyen |
| Graphic Display | 10/10 | :heavy_check_mark: | La Thanh Thai |
| Handle KB | 10/10 | :heavy_check_mark: | Hy Phu Quyen |
| Testing | 10/10 | :heavy_check_mark: | La Thanh Thai<br>Hy Phu Quyen |
| Report | 10/10 | :heavy_check_mark: | La Thanh Thai<br>Hy Phu Quyen |

## Directory

- 18127195_18127207
- ASSET
- Background
- Characters
- Char-01.png
- Char-02.png
- ...
- Fonts
- Grounds
- Miscellaneous
- INPUT
- map-01.txt
- map-02.txt
- map-03.txt
- ...
- SOURCE
- PACKAGES
- OBJECTS
- \_\_init\_\_.py
- agentcontroller.py
- mapcontroller.py
- character.py
- button.py
- text.py
- SCENES
- \_\_init\_\_.py
- scenebase.py
- titlescene.py
- mapselectingscene.py
- playscene.py
- gameoverscene.py
- SETTINGS
- \_\_init\_\_.py
- gameflags.py
- gamesettings.py
- gamehandler.py
- \_\_init\_\_.py
- gameplay.py

## General decriptions:

- General:
-- GUI supported
-- Auto visualize maps according to input
- Core Algorithms for Agent:
-- Apply `Glucose4` to represent the logical mechanism
-- Use `A* path finding` to support
- Graphic:
-- `Scene-based` oriented
-- Implemented with `pygame`

## Graphic

- Applied scene-based oriented to manage each render of the related scene.
- Each scene has 3 states: ProcessInput, Update and Render
- ProcessInput: Manage the user's input. (e.g. You can exit game by pressing Alt + F4 OR Escape Button OR 'X' Button)
- Update: Update the attributes and the states of the game process.
- Render: Render each scene and local changes to `pygame` screen.

## Core Algorithm

There are 2 main classes: `MapController` and `AgentController`
- MapController: Control the whole map including reading input file, updating, and reseting the map state. This is implemented with the Singleton design pattern.
- AgentController: Seperated into 2 smaller classes, one represents for the movement and the other represents for the brain(`logic inference`) of the agent.
- The general rules in wumpus world:
-- Consider the position (x, y) is safe or not: check the presentation of the wumpus or the pit based on prior knowledge.
**Example:**
W(x, y) -> S(x + 1, y) ^ S(x - 1, y) ^ S(x, y + 1) ^ S(x, y - 1)
P(x, y) -> B(x + 1, y) ^ B(x - 1, y) ^ B(x, y + 1) ^ B(x, y - 1)
The safe place would be marked as: $!$ W(x, y) ^ $!$ B(x, y)
-- Convert rules above to CNF and apply to KB of agent.
-- Move step by step to perceive the environment (stench or breeze) and take the appropriate move (`safe place`).
-- When agent concludes all rooms are dangerous, it will make a decision on shooting the wumpus or turning back to the exit depending on the possibility of optimization of the score.

## Environment

* Wumpus project was built on `python 3.7.3`, with IDE `Visual Studio 2019` and editor `Atom` on `Windows`.
* Necessary libraries: `python-sat (0.1.6.dev6)`, `numpy (1.19.1)`, `pygame (1.9.6)`.

## HOWTO run?

Step 1: Set up enviroment, install libraries

+ pip install python-sat
+ pip install numpy
+ pip install pygame

Step 2:

+ Run file gameplay.py to play the game

**Note 1:** Before playing the game, you could add more map inputs to the `INPUT` folder. It will automatically generate the button to execute the map.
You should name the map input file following this syntax: `map-xx.txt`.
-- Where: xx is the latest index following the previous available files.

**Note 2:** `map-11.txt` is the map of Figure 1 mentioned in the problem description.

**Note 3:** Initialized score would be 1000.

## Illustration

### **Menu**
- Double click on gameplay.py to start (After setting up the environment)

### **Select Map**
- Choose any specified map to operate

### **Gameplay**
- Agent's playing


## **Score board**
- Reset to return to Menu or Quit the game


## Achievements

* Apply GUI for game using `pygame`
* Understand more about logical agent
* HOWTO manage the project
* Apply rules using KB to agent to optimize the game

## References:
https://www.javatpoint.com/knowledge-based-agent-in-ai
http://intrologic.stanford.edu/notes/chapter_05.html
https://pysathq.github.io/docs/pysat.pdf
https://stackoverflow.com/questions/34383559/pygame-clock-tick-vs-framerate-in-game-main-loop
https://stackoverflow.com/questions/14044147/animated-sprite-from-few-images
https://stackoverflow.com/questions/34383559/pygame-clock-tick-vs-framerate-in-game-main-loop
http://www.pygame.org/wiki/ConstantGameSpeed?parent=CookBook