Metadata-Version: 2.4
Name: dermek-bp-tower-defense
Version: 0.1.0
Summary: Tower defense game with procedural maps, wave structure and a gymnasium environment. This project serves as 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
Requires-Dist: dermek-bp-tower-defense-env
Dynamic: license-file

# Tower Defense Game

A deterministic tower defense game focused on long-term planning.

This package provides the playable part of the bachelor's thesis project. The is build around tower defense mechanics, resource management, procedural map generation, procedural wave generation, and optional visualization of an agent interacting with the environment.

The game package depends on the separate environment package:
```text
dermek-bp-tower-defense-env
```
That package contains the Gymnasium environment, shared game logic, procedural map generator, procedural wave generator, default map/wave data, and command-line tools for general custom scenarios.

## Installation
Install the game package with:
```bash
pip install dermek-bp-tower-defense
```

This also installs the environment package dependency.

Alternatively, clone the GitHub repository and simply run the files with:
```bash
python file_name.py
```

The relevant file for this package is just `main.py`.

## Command-line tools
After installation, the following command is available from this package:
```bash
tower-defense
```
The environment package also provides:
```bash
tower-defense-map-maker
tower-defense-wave-maker
```

These commands can be used to generate maps and wave structures used by the game and environment.

## Running the game
Run `main.py` with python, or if using the installation:
```bash
tower-defense
```
To view available arguments:
```bash
tower-defense -h
```
Currently the only argument is `--seed`, which sets the seed used by the environment action sampler to allow for experiment reproducibility.

## Generating maps
The map generator is provided by the environment package.

### Example:
```bash
tower-defense-map-maker --difficulty 10 --seed 42
```
### 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>

The generated map is saved to the configured map data file used by the game. This output location can not be changed in the current version.

## Generating waves
The wave generator is provided by the environment package.

### Example:
```bash
tower-defense-wave-maker --difficulty 10 --num-waves 20 --seed 42
```
### 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

The generated wave structure is saved to the configured wave structure data file used by the game. This output location can not be changed in the current version.

## Game overview
The game is a deterministic single-player tower defense game.

The player defends a base against waves of enemies moving along a predefined path. The game is played on a grid-based map containing:
- path tiles, where enemies move
- buildable tiles, where towers and factories can be placed

The player can build:
- towers, which attack enemies
- factories, which produce resources

The game is designed around delayed consequences and long-term planning. The player must decide whether to spend resources immediately on defense or invest in factories that produce resources for future waves.

### Resources
The game uses three main resources:
- money
- resource 1
- resource 2

Money is gained by defeating enemies, Resource 1 and resource 2 are produced by factories.

Different tower and factory types require different resource combinations. Stronger buildings are more expensive, so the player must prepare for future waves by managing resources carefully.

### Towers and enemies
The game contains three types of towers and three types of enemies.

A tower can defeat enemies of the same or lower type. This means stronger enemies require stronger towers.

This type hierarchy creates long-term planning pressure because the player must prepare stronger defenses before stronger enemy types become a threat.

### Factories
Factories are placed on buildable tiles similarly to towers, but they do not attack enemies. Instead, they produce resources during the game.

Factories are important because they allow the player to afford stronger towers later. However, they also occupy limited building space and do not provide immediate defense.

This creates a trade-off between short-term survival and long-term resource production.

## Relationship to the environment package

This package is focused on running the game-facing application.

The separate environment package, dermek-bp-tower-defense-env, provides the Gymnasium-compatible environment used for reinforcement learning experiments.

Use the environment package directly if you want to:

- create the environment with gym.make
- train reinforcement learning agents
- inspect the action and observation spaces
- run faster non-visual simulations (the environment still includes a human rendering mode)
- use the environment as a benchmark

Use this game package if you want to:

- run the visual game application
- demonstrate gameplay
- observe the environment in a Pygame window

## Reproducibility
The project supports reproducible behavior through seed values.

Seeds can be used when:
- generating maps
- generating waves
- resetting the Gymnasium environment
- sampling agent actions

Using the same configuration and seed values should provide the same resulting scenarios.
