Metadata-Version: 2.4
Name: dermek-bp-tower-defense-env
Version: 0.1.1
Summary: A deterministic tower defense Gymnasium environment focused on long-term planning. Includes generators to make maps and waves. Part of my bachelor's thesis.
Author: Maximilián Dermek
License-Expression: MIT
Project-URL: Homepage, https://github.com/mDermek94/BP-tower-defense
Project-URL: Repository, https://github.com/mDermek94/BP-tower-defense
Project-URL: Issues, https://github.com/mDermek94/BP-tower-defense/issues
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pygame>=2.6.1
Requires-Dist: gymnasium>=1.2.3
Requires-Dist: numpy>=2.0.0
Dynamic: license-file

# Tower Defense Environment

A deterministic tower defense game and Gymnasium environment focused on long-term planning in reinforcement learning.

This project provides a custom single-player tower defense environment where an agent must manage resources, place towers, and prepare for future enemy waves. The environment is designed to emphasize delayed consequences and long-term planning rather than only short-term reactions.

The package includes:

- a Gymnasium compatible reinforcement learning environment
- a renderable tower defense game mode
- procedural map generation
- procedural wave generation
- default map and wave data
- command-line tools for generating maps and waves

---

## Installation

Install the package with pip:

```bash
pip install dermek-bp-tower-defense-env
```

Alternatively, clone the GitHub repository and run the Python files directly:

```bash
python file_name.py arguments
```

## Command-line tools
After installation, the map generator can be run with:
```bash
tower-defense-map-maker --difficulty 10 --seed 42
```

The wave generator can be run with:
```bash
tower-defense-wave-maker --difficulty 10 --num-waves 20 --seed 42
```

### Map generator arguments
- `-h`: print available arguments with descrptions
- `--seed`: choose a seed for randomness, if not included, chooses a random seed
- `--difficulty`: choose a difficulty value, required argument, gets clamped to <1;20>

### Wave generator arguments
- `-h`: print available arguments with descrptions
- `--seed`: choose a seed for randomness, if not included, chooses a random seed
- `--difficulty`: choose a difficulty value, required argument
- `--num-waves`: choose the number of waves to generate, required argument

## Basic usage
### Direct package usage
```python
from dermek_bp_tower_defense_env import TowerDefenseEnv

env = TowerDefenseEnv(render_mode="dictionary")

obs, info = env.reset(seed=42)

terminated = False
truncated = False

while not (terminated or truncated):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
    game_state = info.get("game_state")

env.close()
```

### Gymnasium usage
```python
import gymnasium as gym
import dermek_bp_tower_defense_env

env = gym.make("DermekBPTowerDefense-v0", render_mode="dictionary")

obs, info = env.reset(seed=42)

terminated = False
truncated = False

while not (terminated or truncated):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)
    game_state = info.get("game_state")

env.close()
```

## Render modes
The environment supports two render modes:
- `dictionary`: no visual output, intended for faster reinforcement learning experiments
- `human`: renders the game to a Pygame window, intended for demonstration

## Observation space
The observation is returned as a dictionary.

The main observation keys are:
- `board`: current board state
- `resources`: current money, resource 1, resource 2, health and wave index
- `next_wave`: enemy composition of the next wave
- `next_3_waves`: enemy composition of the next three waves

## Action space
The action space is:
```python
MultiDiscrete([3, 3, 10, 10])
```

The action has the following structure:
```bash
[action_type, action_subtype, x, y]
```

### Action type
- `0`: build tower
- `1`: build factory
- `2`: start wave phase

### Action subtype
The subtype represents the tower or factory type. It is ignored when starting the wave phase.

### Coordinates
The `x` and `y` values represent the target tile on the 10x10 board. They are used for building actions and ignored when starting wave phase.

## Invalid actions
The environment allows invalid actions. Invalid actions do not change the game state and are penalized through the rewards.

Examples of invalid actions include:
- building on a path tile
- building on an occupied tile
- building without enough resources
- choosing an invalid building subtype

## Reproducibility
The map generator, wave generator and environment reset support seed values. Using the same seeds and configurations should produce reproducible scenarios and environment behavior.
