# Novelty search and quality diversity in open-ended evolution

This project, part of a thesis on "Novelty Search and Quality Diversity in Open-Ended Evolution" implements open-ended evolutionary algorithms for generating diverse and functional Minecraft buildings. It decomposes building creation into layout, roof, and gradient evolution, utilizing novelty search and quality diversity metrics. In addition to that the project includes tools for running experiments, visualization and analisys of results. The project employs the [upgraded EvoCraft API](https://gitlab.mff.cuni.cz/bakosm/dp-minecraft-rpc) using the [SpongVanilla](https://spongepowered.org/) modding platform.

This project is based on this [Evocraft-py project](https://github.com/real-itu/Evocraft-py).

Citation:

    @inproceedings{
        grbic2021evocraft,
        title={EvoCraft: A new challenge for open-endedness},
        author={Grbic, Djordje and Palm, Rasmus Berg and Najarro, Elias and Glanois, Claire and Risi, Sebastian},
        booktitle={International Conference on the Applications of Evolutionary Computation (Part of EvoStar)},
        pages={325--340},
        year={2021},
        organization={Springer}
    }

## How to Run this project

### Preparation

1. **Install Java 17:**
   - Ensure you have Java 17 installed. You can check your Java version by running:
     ```bash
     java -version
     ```

2. **Clone or Download the Repository:**
   - Clone the repository using Git:
        ```bash
        git clone https://gitlab.mff.cuni.cz/bakosm/dp-open-endedness.git
        ```
   - Alternatively, you can download the repository as a ZIP file and extract it.

3. **Install Python Requirements:**
   - Make sure you have `pip` (Python's package installer) installed.
   - Navigate to the project directory in your terminal.
   - Install the required Python packages using the `requirements.txt` file:
        ```bash
        pip install -r requirements.txt
        ```

4. **Install Minecraft**
   - To experience the full potential of this project and see your creations come to life, you can install Minecraft. You can download it from the official Minecraft website: https://www.minecraft.net/en-us/download

### Starting Server

To run scripts and interact with the project, you need to start the modded Minecraft server:

1. **Navigate to the Project Directory:** Open your terminal and navigate to the `dp-open-endedness` folder where you cloned or downloaded the project.

2. **Start the Server:** Choose one of the following methods:

   * **Basic Start:**
     ```bash
     java -jar spongevanilla-1.20.2-11.0.0-RC1477-universal.jar
     ```

   * **Start with Heap Size Specification:** If you want to adjust the memory allocated to the server, use this command:
     ```bash
     java -Xmx8G -Xms8G -jar spongevanilla-1.20.2-11.0.0-RC1477-universal.jar 
     ```
     (This sets the maximum and initial heap size to 8GB. Adjust as needed for your system.)

   * **Using the Batch File (Windows):**
     ```bash
     start_the_server.bat
     ```

The `spongevanilla-1.20.2-11.0.0-RC1477-universal.jar` can be found and dowloaded from [here](https://spongepowered.org/downloads/spongevanilla).

1. **Accept the EULA:** The first time you start the server, a `eula.txt` file will be created. Open this file and change the last line to `eula=true` to agree to the Minecraft End User License Agreement.

2. **Restart the Server:** Repeat step 2 to start the server again.

3. **Verify Successful Startup:** Look for a line in the server's output that includes `[... INFO]: Listening on 5001`. This indicates the server is running and ready to accept connections.

**Additional Notes:**

* You can now send commands to the server directly through the terminal where it's running.

* The exact version number in the `.jar` file name might change in the future. Ensure you're using the correct file provided in the project.

* If you encounter any issues during startup, check the server logs for error messages.

### Logging into the Server

To see the project's results in action within the Minecraft game world and to be able to better interact with the algorithm, follow these steps:

1. **Install and Launch Minecraft:**
   - If you don't already have it, purchase and install Minecraft: Java Edition.
   - Launch the Minecraft Launcher.

2. **Create a Compatible Version:**
   - In the Launcher, ensure **Minecraft: Java Edition** is selected.
   - Go to the **Installations** tab.
   - Click **New Installation**.
   - Give the installation a name.
   - Select version **release 1.20.2** from the dropdown.
   - Click **Create**.
   - Return to the **Play** tab.

3. **Select the Correct Installation:**
   - Make sure the newly created installation (with version 1.20.2) is selected to the left of the **PLAY** button.

4. **Launch the Game:**
   - Click the **PLAY** button to start Minecraft.

5. **Go to Multiplayer:**
   - From the main menu, select **Multiplayer**.

6. **Add the Server:**
   - Click **Add Server**.
   - (Optional) Give the server a name for easier identification.
   - For the **Server Address**, enter either:
      - `localhost` (if you're running the server on your own computer)
      - The server address shown in the server's startup log (look for a line like `[...INFO]: Starting Minecraft server on {server address}`)
   - Click **Done**.

7. **Join the Server:**
   - Select the server you just added from the list and click **Join Server**.

### Enabling Commands

To use commands within the Minecraft server, follow these steps after logging into the game:

1. **Locate Your Player Name:** In the terminal where the server is running, find the message that looks like this:
   ```bash
   [...INFO]: UUID of player {player name}
   ```
Replace `{player name}` with your actual in-game name in the next step.

2. **Grant Operator Permissions (Op):**
- In the same terminal, enter the following command:
  ```bash
  /op {player name}
  ```
  Replace `{player name}` with the name you found in step 1.

You should now have operator (op) status, which grants you the ability to use commands within the game.

**Additional Notes:**

* You can check if you have successfully been given operator permissions by typing `/op` in the in-game chat. If you see a message confirming your op status, you're good to go!

## Usage

All scripts for running the project are located in the py_scripts folder.

Important: If you're running the scripts from the command line, make sure that your working directory is set to the root project directory (the same folder where this README file is located).

### Observing the Evolution In-Game

- **Find the Starting Coordinates:**
   - The in-game chat will display a message indicating the coordinates where the scrip execution will take place:
     ```
     Workspace created at Coordinates(x={x}, y={y}, z={z})
     ```

- **Teleport to the Execution Site:**
   - Open the chat (press T) and enter the following command:
     ```
     /tp {player name} {x} {y} {z}
     ```
     Replace `{player name}` with your in-game name and `{x}`, `{y}`, and `{z}` with the coordinates you noted in step 2.

### Start the Evolution

    To start the evoolution of a building:

   - Open your terminal and navigate to the `py_scripts` folder.
   - Run the `main.py` file to initiate the evolution process:
     ```bash
     python main.py
     ```
   - Teleport to the evolution site
   - The server chat will provide messages guiding you through the evolution process. Follow their lead.

**Additional Notes:**

* The `main.py` script is the primary entry point for the project. You can explore other scripts in the `py_scripts` folder to understand the underlying implementation details or to customize the evolution parameters.
* Feel free to experiment with different settings and configurations to observe how they affect the evolution of your Minecraft creations!

### Display Showcase

### Experiments

This project offers tools for conducting and analyzing experiments:

#### Run Experiments

Script `experiment_runs.py` implements experimental framework. It allows you to run the evolutionary algorithm with various configurations and parameters. It also logs the results for further analysis.

#### Analyze Experiments

The `experiment_analysis.ipynb` Jupyter Notebook provides a framework for analyzing the experimental results generated by `experiment_runs.py`. You can use it to visualize data, identify trends, and evaluate the effectiveness of different evolutionary strategies.

## Project Overview

For more infomation on development, motivation behind the project refer to the text of the thesis (name: "Novelty Search and Quality Diversity in Open-Ended Evolution")

### Evolution Scripts

The scripts with the "evolution_" prefix contain the implementation of the evolutionary algorithms responsible for evolving different aspects of the generated buildings:

*   **`evolution_layout.py`:**  Evolves the building layout (floor plan).
*   **`evolution_roof.py`:** Evolves the roof structures of the buildings.
*   **`evolution_gradient.py`:** Evolves the gradient patterns applied to the building.

These scripts are the core of the project's evolutionary processes, controlling how the buildings change and adapt over time.

### Example Scripts

The scripts with the "example_" prefix serve different purposes:

* **Toy example:** These scripts are designed for testing and familiarization with The EvoCraft API and with the DEAP (Distributed Evolutionary Algorithms in Python) and NEAT (NeuroEvolution of Augmenting Topologies) libraries.

* **Building Blocks:** These files contain an alternative, but ultimately unused, approach to building creation. While not part of the main project implementation, they may offer insights into different architectural strategies.

These scripts are primarily intended for educational or experimental purposes, and they are not essential for running the core evolutionary algorithms of the project.

### Minecraft Scripts

The `minecraft_pb2_grpc.py`, `minecraft_pb2.py`, and `minecraft_pb2.pyi` scripts are essential, defining communication protocols for interacting with the Minecraft server using the EvoCraft API. They enable the Python scripts to send commands and receive information from the server.

### Test Scripts

The scripts with the "test_" prefix are used to test various aspects of the implementation. These scripts contain unit tests and other test cases to ensure the correctness and reliability of the codebase.

While the test files focus on formal testing, the **`test_playground.ipynb`** notebook is more of a developer's sandbox. It serves as a code testing playground for quick, iterative development and experimentation. It contains various code snippets, proofs of concept, visualizations, and debugging tools used during the development process.

### Utility Scripts

These scripts provide various helper functions and utilities for the project:

#### Essential Utilities

These scripts provide core functionalities for managing the workspace, coordinates, and communication with the Minecraft server:

*   **`utils_coordinates.py`:** Implements the `Coordinates` class, representing a position (x, y, z) in the Minecraft world. This class is fundamental for handling block placements and spatial calculations throughout the project.

*   **`utils_server_client.py`:** Implements a client interface to simplify interaction with the Minecraft server using the EvoCraft API. It streamlines the creation and handling of gRPC requests, converting variables used in other part of code into the corresponding gRPC messages. This client also offers flexibility by supporting various ways to specify actions, accommodating different data formats.

*   **`utils_workspace_manager.py`:** Offers a framework for managing the workspace where evolution takes place. It handles tasks such as tracking the positions of individuals or creating requests to clean up the workspace.

#### Evolution Utilities

These scripts provide core utilities and data structures for the evolutionary algorithms used in the project:

* **`utils_evolution_tools.py`:**  Contains various helper functions for the evolution process, such as:
    - Shape pixelization calculations
    - Roof function calculations
    - Other general-purpose tools for evolutionary algorithms

* **`utils_individuals.py`:** Defines the classes representing individual solutions in the evolutionary process. These classes encapsulate the genetic representation of building layouts, roofs, and gradient patterns.

* **`utils_novelty.py`:** Implements different types of archives used by the evolutionary algorithms. It also includes tools for clustering individuals within the archive based on their novelty metric.

#### Color Management

* **`utils_block_color.py`:**  Manages information about block colors in Minecraft. It includes methods for:
    - Color manipulation (metrics, interpolation)
    - Gradient computation
    - Loading color data from `block_to_color.json`

**`block_to_color.json`:** This file stores the color information for each block in Minecraft. You can find it, along with scripts for its generation, in the `py_scripts/block_color_extraction` folder.

**Generating `block_to_color.json`:**

1. Place a folder containing Minecraft block textures in the `block_color_extraction` folder.
2. Navigate to the `block_color_extraction` folder in your terminal.
3. Run the `block_textures_to_rgb.py` and `block_textures_to_rgb.py` script to extract color information from the textures and generate the `block_to_color.json` file. Don't forget to navigate the scripts to the folder with block textures.

#### Library Specific Tools

These scripts provide additional tools and customizations for the NEAT and DEAP libraries used in the project:

* **`utils_neat.py`:** Handles the loading of appropriate files for NEAT.
* **`utils_deap_tools.py`:** Offers additional tools and functions that enhance or tailor the DEAP (Distributed Evolutionary Algorithms in Python) library's functionality for use in the project.

#### Other Utilities

`utils_blocks_categories.py` contains a manually curated categorization of Minecraft blocks into various groups.

### Miscellaneous

* **`functions.ggb`:** This [GeoGebra](https://www.geogebra.org/calculator) file provides a exported setup for visualizing the roof functions used in the project.

* **`readme-original.md`:** This file is the original README from the EVOCRAFT challenge, serving as a reference to the original project.

* If you would like to improve upon the EvoCraft API mode, take a look at `import_minecraft-rpc.bat`. It contains (Windos bash) code for importing new generated files from that project.
