Flora/README.md

# Flora — Turn-Based Battle Game

A turn-based battle game in Python. Normal battles are 4v4; the Tower mode
starts small and ramps up.

## Run it

```
pip install -r requirements.txt
python main.py
```

You land on the **main menu**:
- **Seeds** — seed pack opening; the main way to get/enhance plants.
- **Plants** — the plants you own, with their **level/stage**; open a plant to see its
  stats and **Water** (+1 level) or **Evolve** it
  (at milestone levels, consuming duplicates).
- **Battle** — pick a difficulty stage (1–5, gated by enemy rarity), then the
  enemy team is rolled so you know the matchup, and you pick your 4 allies and
  fight. Higher stages grant more packs on a win; any loss grants a lesser pack.
- **Tower** — a 20-stage gauntlet. Enemies start with 1 common plant and get
  stronger (more enemies, higher rarity, higher level) each stage; your team is
  fresh every fight. After each win you **choose one of three roguelike
  blessings** (shields, stat boosts, enemy debuffs, heal-over-time…) that last
  for the rest of the run — the core of the tower's roguelike loop.
  Stages 1–5 pay 1 water each, stages 6–20 pay scaling
  **Tower packs** (high-rarity odds), which you can open or redeem for 20 water.
- **Collection** — plants you've discovered (they're added when you battle them);
  undiscovered plants show as blacked-out silhouettes. Saved in `data/collection.json`.
- **Soil** — retrieve a **seed** from any owned plant (once per cooldown, from
  its detail page), plant it, then grow a copy in stages. Each stage fills over
  time; **fertilizing** (1 fertilizer per stage) advances it. Higher rarities
  have more stages; harvesting grants a duplicate of that plant. You start with
  **1 plot**; extra plots unlock for escalating fertilizer (10, then 20, 30…,
  up to 5 total). Soil unlocks once you own **8 distinct plants**.

## Rarities

Every plant has a **rarity** tag (common / rare / epic / legendary) —
purely cosmetic, only used to weight seed-pack drops. A **victory** grants
seed packs equal to the difficulty stage (1–5) **plus fertilizer equal to the
floor** (1–5); a **defeat** grants 1
**lesser pack** (worse rarity odds, no type weighting). Type packs roll the
rarity first (matching the general pack) and then pick a plant of that rarity
from the type when possible; rarer plants are rarer pulls.

## Watering, fertilizer & Evolution

Two resources:
- **Water** — the scarce, valuable currency. **Watering** gives an instant +1
  level by spending 1 water, and 5 water can be converted into a seed pack.
  Water comes mainly from Tower rewards (stage 1–5 wins pay 1 water, Tower packs
  redeem for 10).
- **Fertilizer** — the common currency earned from **battle wins**. It's used to
  fertilize growing Soil plots (each fertilizer advances a plot one stage).

- **XP** is earned from battles (participation + win bonus); allies auto-level up.
  Higher difficulty stages pay more XP (scales with the stage number), and Tower
  wins pay XP too. The lowest-level plant on your team earns bonus XP based on
  the level gap (catch-up).
- **Evolution** unlocks at milestone levels (5 → stage 2, 10 → stage 3) and
  consumes duplicates. Stages multiply base stats before the level curve.
- Enemies in battle are scaled to roughly your team's level.
- Stat growth: attack/defense +6%, health +8%, speed +4% per level (see `engine/growth.py`).

## Roguelike blessings (Tower)

After every Tower win you're offered **3 random blessings** and keep one (or
skip). Blessings stack for the rest of the run and apply at the **start of each
battle**. They come in three rarity tiers:

- **Common** — small shields/stat boosts and start-of-battle buffs (e.g. "team
  starts with a shield for 10% of max health").
- **Rare** — bigger boosts, heal-over-time, stronger healing, enemy debuffs
  (Speed/Attack Down).
- **Epic** — strong shields, "+15% attack", "+20% max health", enemies start
  Vulnerable.
- **Legendary** — rare picks with big payoff: block the first damage taken,
  a 40% shield, a one-time revive, or a large HP/attack combo.

Blessings are offered from a **rarity-weighted** pool, so legendary relics show
up rarely.

Blessings are defined declaratively in `engine/relics.py` (`RELIC_POOL`); each
relic is a `Relic` with an `apply(battle)` function that runs once per battle in
`Battle.start()`. They're tracked per-run (not saved). An **"All blessings"
overview** (`ui/relics_overview.py`) shows the whole pool grouped by rarity with
the ones you've collected highlighted in gold; click any card for a closer look.
It opens from the blessing-choice screen and by clicking the "Blessings:" line
on the Tower battle screen.

## Plant types & type advantages

Five types with a rock-paper-scissors cycle:

**Radiant > Nocturnal > Ice > Garden > Wildflowers > Radiant**

- Hitting a type you're strong against deals **+30%** damage.
- Hitting a type that's strong against you deals **−30%**.
- Applies only to damage — heals and shields are unaffected.

## Stats & damage

- **Health** — the damage pool.
- **Attack / Defense** — damage = skill power + attack − defense (min 1).
- **Speed** — an **initiative timeline**: each plant acts based on `100 / speed`
  interval, so faster plants act *more often* and interleave with slower ones
  (e.g. a 110-speed enemy goes 110 → 75 → 110 → 50…). The blue bar under each
  unit's health shows how close it is to its next turn. Speed buffs/debuffs
  change the interval, and "reduce turn progress" effects literally push a
  plant's next turn back.
- **Crit** — base 10%, doubles damage.

## Debuffs

- **Wilt** — damage over 3 turns (total = % of the triggering hit's damage);
  reapplying resets it to 3 turns.
- **Shield** — temporary HP that absorbs damage; cannot be healed.
- **Damage-over-time** (Dark Corrosion, Chill) — deals its listed damage **every
  turn** while active; Dark Corrosion stacks.
- **Sleep** — skips turns until the target has taken damage twice.
- **Vulnerable X** — +50% damage for the next X hits.
- **Intoxicate / Oblivion** — an Intoxicated plant's attacks splash half their
  damage onto one of its own allies; an Oblivious plant may only use its weakest
  skill (both last their stated duration, e.g. 1-2 turns).
- Plus speed/crit/attack/defense down, Madness, Tether, and more.

## The plant pool (27)

All defined declaratively in `engine/plants.py` so new plants are easy to add:

- **Radiant:** Zinnia, Sunflower, Daisy, Marigold, Daffodil
- **Garden:** Rose, Peony, Magnolia, Hydrangea, Sweet Pea, Chrysanthemum
- **Wildflower:** Lily, Hibiscus, Poppy, Tulip, Lotus, Dandelion
- **Nocturnal:** Nightshade, Moonflower, Orchid, Lavender, Venus Flytrap
- **Ice:** Snowdrop, Primrose, Winter Jasmine, Hellebore, Camelia

Each has a role (Attacker / Support / Tank), a unique passive, three skills
with cooldowns, and base stats. Tanks protect their team from single-target
attacks (AOE still hits everyone).

## Architecture

```
engine/   Pure-Python battle logic (types, skills, effects, plants, battle).
          No pygame — reusable for a web UI or Flet later.
ui/       pygame frontend: team picker + battle screen.
tests/    unittest coverage of the engine.
```

Adding a plant later = add one entry to `POOL` in `engine/plants.py`.

## Tests

```
python -m unittest discover -s tests
```

## Roadmap ideas

- Balance pass (sim currently favors the player's chosen teams)
- More team strategies, saving team compositions
- Web UI via Flask, or a real mobile app via Flet