# 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. Some progress (quests, boss tokens, broken walls, defeated bosses) is **in-memory** and resets when you restart — intentional, for fast testing. Saves (via pause menu or lanterns) persist player state, coins, equipment, inventory, and your respawn point. --- ## Running the game ``` python main.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`** — see [Level Editor](#level-editor) below. --- ## 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 / Save | F | | Use Butterfly Jar | G | | 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 **10/s** in Light (halved to make light sources matter), drains at **40/s** in Shade. Standing near a **butterfly** light source doubles Charge regeneration. Attacks, dash (Light), ranged shots, and healing all cost Charge. --- ## Saving & lanterns **Lanterns are save points.** Walk up to a lantern and press **F** to save — a "Press F - Save at lantern" prompt appears when you're in range. Your respawn point is set to that lantern, so dying (or reloading the save) puts you back at your latest lantern. Saving via a lantern in a *different room* than where you last died also respawns butterfly jars in the world. You can also save anytime from the pause menu (**Esc → Save Game**). --- ## Butterfly jars Butterfly-in-a-jar pickups are scattered through the rooms (you can hold up to **3**). Press **G** to consume one and instantly refill your Charge bar to max. Collected jars are shown below your coin counters (empty slots are greyed out). Jars are lost when you die. They respawn at their pickup points after you save at a lantern in a different room, or after reloading the game. --- ## Death & recovery When you die you lose your **butterfly jars for good** and drop your coins. A **faded player model (corpse)** marks the spot — touch it to reclaim all lost coins. Dying again *without* reclaiming keeps only **50%** of the coins in a new corpse at the new death spot (the old corpse vanishes), so the rest is lost. Falling out of the world (void deaths) leaves no recoverable corpse. --- ## 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. - Butterfly-jar slots below the coin counters (shown once you own at least one; remaining slots are greyed out). - 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/light buff, and any stat bonuses from gear. --- ## Level Editor Open `level_editor_v43.html` in a browser to edit rooms. Highlights: - **Icon toolbar** on the right edge of the canvas (Select, Platform, Enemy, NPC, Player, Entry, Exit, Ability Door, Object). Toggle **grid snap** in the left sidebar. - **Objects catalog** (built-in, always available; `data/objects/objects.json` can override/add): `flow_butterfly` (light source), `lamp` (save point), `flow_butterfly_jar` (collectible), `house`, `diary`, and `player` (a size reference that renders nothing in-game). - **NPC support**: place/select/move NPCs (vendor, upgrader, necklace_vendor, combat_master) and standalone **house props**. - **Layers**: every object (platforms, houses, NPCs, enemies, props, ability doors, exits) has a **layer** number. Lower = further back, higher = further forward; lower is set in the Properties panel. The editor and game both draw back-to-front by `(layer, category)`, and the select tool is layer-aware. - **Link lines**: enable **Draw link lines** (with Compare view) to see dashed lines from a room's exits to the matching doors in the other room. - Load the game's enemy types (`data/enemies/enemy_types.json`) to preview hitboxes and aggro ranges; enemy/miniboss/boss are also built in.