Light_And_Dark/pygame test/README.md

# Light & Dark — Prototype

A 2D platformer built with **Pygame**. You switch between two forms — **Light** and **Shade** — each with different movement, combat, and ability behavior, all driven by a single shared resource: **Charge (Flow)**.

> Note: this is a prototype. All progress (quests, boss tokens, broken walls, defeated bosses) is **in-memory** and resets when you restart the game — intentional, for fast testing.

---

## Running the game

```
python pygame_test.py
```

Requires Python 3.10+ and `pygame`. Game data (rooms, items, sets, enemies, drops) lives in `data/`. Rooms are edited with the included browser tool: `level_editor_v43.html`.

---

## Controls

| Action | Key |
|---|---|
| Move | A / D |
| Jump | W |
| Move down / drop | S |
| Heal | Space (hold) |
| Melee attack | E |
| Ranged shot | Q |
| Dash | Tab |
| Shatterstep | R |
| Tether | X |
| Reality Break | C |
| Toggle Light/Shade | Left Shift |
| Interact / Talk | F |
| Inventory | I |
| Stats overlay | H |
| Pause / Settings | Esc |

---

## The two forms

**Light** — faster movement, higher jump, and charge **refills** over time. You take contact damage from enemies.

**Shade** — slower but tanky: **immune to enemy contact damage**, deals double melee damage, and can use shade-specific gear bonuses. But being in Shade **drains Charge** (and Shade is forced off when Charge hits 0). Shade also drains Charge **twice as fast while clipping inside an enemy**.

**Charge (Flow)** — base max 100, refills at 20/s in Light, drains at 40/s in Shade. Standing near a **lantern/light source** doubles Charge regeneration. Attacks, dash (Light), ranged shots, and healing all cost Charge.

---

## Abilities (by form)

| Ability | Key | Light | Shade |
|---|---|---|---|
| **Melee** | E | 1 damage, costs 1 Charge | **2 damage**, costs 1 Charge |
| **Dash** | Tab | Costs 10 Charge; **stuns** enemies hit | Costs 1 HP; deals **4 damage** to enemies hit |
| **Ranged** | Q | Costs 5 Charge, 0.45s cooldown, 0.5 damage; **breaks green ability walls** | Same, but 1.0 damage |
| **Shatterstep** | R | Spawns a **platform under your feet** while airborne (extra jumps) | On landing, creates a damaging **shockwave AOE** below you |
| **Tether** | X | **Binds** the enemy (3s) and **fears** it (runs away) | **Insta-kills** enemies below a HP threshold (normal ⅓, miniboss 20%, boss 5%); otherwise **slows** them |
| **Reality Break** | C | Doubles drop & coin rates and glows enemies | **Instantly kills all enemies** but halves drop & coin rates |
| **Heal** | Space | Spend Charge to heal over ~2s (slower while healing) | Unavailable |

---

## Combat notes

- Enemy contact damage only applies in **Light** form.
- Boss **shockwave attacks poison** you for 4 seconds: the health bar turns green and you lose 1 HP per second.
- Attacks and hits use invincibility frames and knockback; your melee hitbox covers ~30% into your body so close/overlapping hits always connect.

---

## Equipment & Armor Sets

Slots: **helmet, chest, pants, necklace**. Pieces roll stats (move speed, heal, charge, health, etc.).

**Rarities:** `tempered` (tier 1) → `attuned` (tier 2) → `awakened` (tier 3, unlocks ability slots). The **Upgrader** NPC turns 5 tempered copies of an item into 1 attuned copy.

**Sets** (3 pieces of the same set, attuned or better):

| Set | Summary |
|---|---|
| Dawnrunner | +HP; awakened adds Light move speed |
| Gravemark | +max Charge; awakened adds Charge regen |
| Vitalweave | +HP; awakened adds +heal |
| Duskwarrior | +Shade damage; awakened restores Charge on Shade hits |
| Twister | Removes Shade speed penalty; awakened gives move speed after switching forms |
| Paladin | Chance to negate incoming damage; awakened adds +HP |
| Luminal Growth | +Charge regen while standing still in Light; awakened also negates damage |
| Abyss Cleaver | Chance to heal on kill; awakened also gives move speed on kill |
| Umbraflow | Reduces Shade Charge drain |
| Adaptive Traveller | Move speed after switching forms; awakened restores Charge on switch |

The shade-focused sets (**Duskwarrior, Umbraflow, Abyss Cleaver, Adaptive Traveller**) are intentionally **excluded** from early boss and town-shop loot, so you can always complete the remaining sets.

---

## NPCs (Town 1: Gloomreach)

- **Vendor** — sells basic armor pieces.
- **Necklace Vendor** — sells necklaces.
- **Upgrader** — attunes 5× tempered → attuned.
- **Combat Master** — upgrades your boss token to unlock the **Hard** boss variant.
- **Boss Diary** — an interactable book: view your collected boss tokens in a grid, slot/unslot them, and start refights.

---

## Rooms & Progression

- `room_01` — tutorial. Contains a **quest object** (pink): accept the **"First Kills"** quest (kill 4 normal enemies → 5–15 light coins, repeatable).
- `room_02` — first enemies.
- `room_07` — hub, branching to the boss, reward room, and town.
- `room_boss_01` — **Gloom Warden** fight. Defeating him drops his **boss token**.
- `room_reward_01` — reward chest + the **Ranged** ability, locked behind green ability walls.
- `room_town_gloomreach` — Town 1 (NPCs above).
- `room_boss_refight_01` — diary refight room (same arena, no exits until the boss dies or you die).

---

## Boss Diary & Tokens

1. Beat the world boss → collect his **token** (teal pickup).
2. Bring it to the diary in town and **slot** it (or keep it in your inventory).
3. Slotting unlocks **Fight (Normal)**. Upgrading the token at the Combat Master unlocks **Fight (Hard)** — the boss moves and shoots twice as fast.
4. Dying in a refight returns you to the diary. Removing a token from the diary sends it back to your inventory, disabling the fight until you re-slot it.

---

## HUD & Stats

- Top-right: health bar (turns **green while poisoned**), Charge bar, coin counts.
- Ability icons with cooldown indicators (top-left).
- **H** toggles a detailed overlay: exact HP/Charge, move speeds (both forms), heal duration, attack rate, Charge regen, the lantern buff, and any stat bonuses from gear.