dermek-bp-tower-defense-env 0.1.5

A deterministic tower defense Gymnasium environment focused on long-term planning. Includes generators to make maps and waves. Part of my bachelor's thesis.

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:

pip install dermek-bp-tower-defense-env

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

python file_name.py arguments

Command-line tools

After installation, the map generator can be run with:

tower-defense-map-maker --difficulty 10 --seed 42

The wave generator can be run with:

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

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

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:

MultiDiscrete([3, 3, 10, 10])

The action has the following structure:

[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.