tower-defense

# Tower defense balancing and pathing (depth)

Math and structures behind `SKILL.md`. Engine-neutral pseudocode. The numbers are starting
points; tune against playtests. For pathfinding internals defer to `game-ai`.

## 1. Representing the path

Three common approaches:

- **Fixed waypoints (lanes):** an ordered list of points; enemies steer toward the next one.
  Simplest, fully authored, ideal for lane defense. Most TD games use this.
- **Grid + pathfinding (A\*):** enemies path from spawn to goal over a walkable grid. Enables
  **maze TD**, where placing towers reshapes the path. Recompute paths when towers change and
  forbid placements that fully block the goal.
- **Flow field:** precompute one direction per tile pointing toward the goal; every enemy reads
  it. Scales to huge crowds (one computation for all enemies) — see `game-ai`.

```python
# Waypoint following (pseudocode): move toward the next waypoint; advance when close.
def update_enemy(e, dt):
    target = path[e.wp_index]
    e.pos = move_toward(e.pos, target, e.speed * dt)
    if distance(e.pos, target) < ARRIVE_EPS:
        e.wp_index += 1
        if e.wp_index >= len(path):
            leak(e)                        # reached the goal: cost the player a life
```

## 2. Tower targeting modes

Expose a per-tower targeting priority; it changes optimal play more than raw stats:

| Mode | Picks | Good for |
|------|-------|----------|
| First | enemy furthest along the path | default; stops leaks |
| Last | enemy least far along | feeding another tower / slows |
| Closest | nearest to the tower | short-range/splash towers |
| Strongest | highest current/max HP | focus tanks |
| Weakest | lowest HP | last-hit / efficiency |

```python
# Pseudocode. Filter to in-range, then pick by mode.
def acquire_target(tower, enemies, mode):
    in_range = [e for e in enemies if distance(tower.pos, e.pos) <= tower.range]
    if not in_range: return None
    if mode == "first":    return max(in_range, key=lambda e: e.progress)
    if mode == "last":     return min(in_range, key=lambda e: e.progress)
    if mode == "closest":  return min(in_range, key=lambda e: distance(tower.pos, e.pos))
    if mode == "strongest":return max(in_range, key=lambda e: e.hp)
    if mode == "weakest":  return min(in_range, key=lambda e: e.hp)
```

## 3. DPS and "can this lane hold?"

```
tower_dps        = damage * fire_rate            # shots/sec
effective_dps    = tower_dps * (1 - target.armor_reduction)
time_in_range    = path_length_in_range / enemy_speed
damage_dealt     = effective_dps * time_in_range  # what one tower does to one passing enemy
```

A lane holds a wave if the **sum of damage_dealt across all covering towers** ≥ enemy HP for
each enemy, accounting for how many enemies overlap in range at once (a single tower can only
shoot one target at a time unless it has splash/multi-shot).

## 4. Enemy scaling across waves

```python
# Pseudocode. Scale HP (and sometimes count/speed) so towers must be upgraded, not just spammed.
def wave_enemy_hp(base_hp, wave, growth=1.15):
    return int(base_hp * (growth ** wave))     # geometric HP growth

# Mix enemy types so one tower build can't answer everything:
#   fast/low-HP (rush slows), armored (counters low-damage rapid fire),
#   flying (needs anti-air), swarm (needs splash), boss (huge HP spike).
```

Geometric HP growth (~1.1–1.2× per wave) paired with a linear-ish income curve forces
upgrades. If HP grows slower than the player's income/DPS, the game trivializes; faster, and
it walls. Tune the two curves against each other.

## 5. Economy

Income sources and sinks must be balanced so the player is *almost* able to cover each wave:

```
income_per_wave = kill_bounty * enemies_killed + wave_clear_bonus (+ interest, optional)
spend           = tower_costs + upgrade_costs
```

- **Kill bounty:** gold per enemy. Leaks should cost income *and* lives so leaking hurts twice.
- **Upgrade vs. build curve:** make upgrades cost-efficient enough that "tall" (few upgraded
  towers) competes with "wide" (many cheap towers). Diminishing upgrade returns prevent one
  god-tower.
- **Interest/banking (optional):** rewards saving but can snowball; cap it.
- **Sell refund:** partial (e.g. 70%) so repositioning is possible but not free.

## 6. Leak / lives model

- Each enemy reaching the goal removes lives (often 1, bosses more). Game over at 0.
- Show a clear "lives" counter and telegraph the next wave's composition so players can prepare.
- A short build/prep phase between waves (or a "start next wave early" bonus) gives agency and
  pacing control.

## 7. Wave pacing

- Alternate pressure: a hard wave, then a breather, then a spike. Pure monotonic ramps exhaust.
- Telegraph specials (flying/boss) one wave ahead via UI so the counter feels fair, not random.
- Let players trigger the next wave early for an economy bonus — rewards confidence and speeds
  pacing for experts without punishing newcomers.

---
name: tower-defense
description: >
  Build a tower defense: enemies pathing along lanes, wave spawning, towers that auto-target and fire,
  an economy, and lives. Use for a tower-defense/wave-defense game, or balancing waves and economy.
---

# Tower Defense

A playbook for tower defense — enemy pathing, wave spawning, tower targeting, and the
economy that ties them together. This is a **compositional** skill: it orchestrates pathing,
AI, and UI into a TD loop. It does not re-teach pathfinding; it defines the systems and the
balance levers (DPS vs. HP vs. income) that decide whether a TD is tense or trivial.

## When to use

- Use when building a game where the player **places towers** that automatically attack
  **waves of enemies** following a path, spends earned currency to expand/upgrade, and loses
  if too many enemies leak through.
- Use when designing wave composition/pacing, tower targeting priorities, or the gold economy.

**When _not_ to use:** the player directly controls a shooter → `fps-shooter`. Free-form base
building with needs → `survival-crafting`. For the pathfinding algorithm itself, use `game-ai`.

## Core loop

**Prepare (place/upgrade towers with current gold) → start the wave → enemies path toward the
goal while towers auto-fire → earn gold from kills → survive the wave → repeat against a
harder one.** The tension is a planning puzzle: is my current DPS enough for what's coming,
and can I afford the answer?

## Must-have systems

1. **Enemy path** — waypoint lanes, or grid + pathfinding for maze TD (refs).
2. **Wave spawner** — timed, scripted sequences of enemy types with per-wave scaling.
3. **Towers** — range, fire rate, damage, projectile/hitscan, splash; placement validity.
4. **Targeting** — per-tower priority (first/last/closest/strongest/weakest) (refs).
5. **Economy** — gold from kills + wave bonuses; tower/upgrade costs; sell refund.
6. **Lives / leak** — enemies reaching the goal cost lives; 0 = game over.
7. **Wave/prep UI** — lives, gold, next-wave preview, start-next-wave control.

## Design knobs

| Knob                      | Effect                  | Notes                                    |
| ------------------------- | ----------------------- | ---------------------------------------- |
| Enemy HP growth/wave      | upgrade pressure        | Geometric ~1.1–1.2× (refs).              |
| Income vs. HP curves      | difficulty              | Player should _almost_ afford each wave. |
| Tower DPS / range / cost  | tower identity          | Cheap+wide vs. expensive+tall.           |
| Targeting priority        | optimal placement       | Changes play more than raw stats.        |
| Enemy variety             | counters one-build wins | Fast / armored / flying / swarm / boss.  |
| Leak penalty              | stakes                  | Cost lives _and_ lost bounty.            |
| Upgrade vs. build economy | strategy depth          | Diminishing upgrade returns.             |
| Wave pacing               | tension curve           | Spike → breather → spike, not monotonic. |

## Patterns

### 1. Wave spawner (timed, data-driven)

```python
# Pseudocode. A wave is data: a list of (enemy_type, count, spacing). Spawn over time.
wave = [ ("grunt", 10, 0.5), ("runner", 5, 0.3), ("tank", 2, 1.0) ]

def run_wave(wave):
    for enemy_type, count, spacing in wave:
        for _ in range(count):
            spawn_enemy(enemy_type, at=path[0])   # enter at the path start
            wait(spacing)                          # seconds between spawns (use a timer/coroutine)
    # wave clears when all spawned enemies are dead or have leaked
```

### 2. Tower targeting (filter to range, then pick by priority)

```python
# Pseudocode. "First" (furthest along path) is the standard default for stopping leaks.
def acquire_target(tower, enemies, mode="first"):
    in_range = [e for e in enemies if distance(tower.pos, e.pos) <= tower.range]
    if not in_range: return None
    if mode == "first":    return max(in_range, key=lambda e: e.progress)   # furthest along path (stop leaks)
    if mode == "last":     return min(in_range, key=lambda e: e.progress)   # least progress (guard the entrance)
    if mode == "closest":  return min(in_range, key=lambda e: distance(tower.pos, e.pos))
    if mode == "strongest":return max(in_range, key=lambda e: e.hp)         # burn down tanks first
    if mode == "weakest":  return min(in_range, key=lambda e: e.hp)         # secure kills / last-hit bounty
    return in_range[0]
```

### 3. "Can this lane hold?" sanity check (DPS vs. HP)

```python
# Pseudocode. One tower's damage to one enemy crossing its range.
tower_dps     = tower.damage * tower.fire_rate
time_in_range = tower.range_coverage_length / enemy.speed
damage_dealt  = tower_dps * time_in_range
# Lane holds if summed damage_dealt from covering towers >= enemy.hp (per enemy). See refs.
```

## Pitfalls / failure modes

- **Enemy HP scales slower than player income/DPS** → game trivializes after a few waves.
  Tune the HP curve against the income curve (refs).
- **One dominant tower/strategy** → no decisions. Add enemy types that hard-counter builds
  (armored vs. rapid-fire, flying vs. ground-only) and diminishing upgrade returns.
- **Maze TD that can fully block the goal** → enemies get stuck/softlock. Forbid placements
  that sever the path; recompute paths when towers change (refs).
- **No next-wave telegraph** → specials feel random and unfair. Preview upcoming composition.
- **Per-frame movement unscaled by `dt`** → speed varies with frame rate. Scale steering by `dt`.
- **Leaks only cost lives, not gold** → leaking is sometimes optimal. Make leaks lose bounty too.
- **Monotonic difficulty ramp** → exhausting. Pace spikes and breathers.

## Composition (build it from these skills)

- **Pathing:** `game-ai` for A\*/flow-field/steering; for fixed lanes, simple waypoint following.
- **Enemy movement:** `godot-2d-movement` (or engine equivalent) to move along the path; `unity-navmesh` for nav-based pathing.
- **Map:** `godot-tilemap` / `unity-tilemap-2d` for the grid/lanes; `level-design` for map layouts.
- **Data:** `godot-resources` / `unity-scriptableobjects` to define towers, enemies, and waves as assets.
- **UI:** `game-ui-ux` for HUD layout, scaling, and the build menu; `godot-ui-control` for the concrete widgets (lives, gold, wave preview).
- **Polish:** `audio-design` for fire/hit/leak sound cues.

## References

- For path representations (waypoints / A\* / flow fields), targeting modes, DPS and economy
  math, enemy scaling, and wave pacing, read `references/balancing.md`.