182 lines
9.7 KiB
Markdown
182 lines
9.7 KiB
Markdown
# 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 |
|
||
|
||
**Mouse**: **Left button** = melee attack, **Right button** = ranged shot.
|
||
|
||
**Hold-to-recast**: Melee (E / left mouse) and Ranged (Q / right mouse) can be **held** — the attack auto-recasts as soon as its cooldown is ready, and never faster than the cooldown.
|
||
|
||
---
|
||
|
||
## 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. Saving **fully restores your health and Charge** (and clears poison), and sets your respawn point 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.63s 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.
|
||
- The **Gloom Warden's** ground shockwaves **poison** you for 4 seconds (the health bar turns green, −1 HP/s). **Sky Terror's** slam does **not** poison.
|
||
- Once a boss first spots you in Light form it tracks you permanently — even in Shade form and from any distance.
|
||
- 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
|
||
|
||
> The town room isn't in the current build (removed in the room overhaul); these NPC types still exist and can be placed with the editor.
|
||
|
||
- **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
|
||
|
||
> The room set was overhauled; the old reward/town rooms are gone. Notable rooms:
|
||
|
||
- `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_04` — **miniboss** arena; the walls seal until the miniboss is slain.
|
||
- `room_05` — **charger boss** arena (seals until slain).
|
||
- `room_07` — hub, branching to the boss arena and back.
|
||
- `room_08` — **Sky Terror**, the flying boss. Entering locks you in: the exit back to `room_07` and the right-hand door to `room_09` only appear once he's dead.
|
||
- `room_09` — the area past Sky Terror's right door.
|
||
- `room_boss_fly_refight` — Sky Terror **diary refight** arena.
|
||
|
||
---
|
||
|
||
## Boss Diary & Tokens
|
||
|
||
1. Beat a world boss → collect its **token** (a distinct pickup per boss).
|
||
2. **Slot** it in the Boss Diary (or keep it in your inventory).
|
||
3. Slotting unlocks **Fight (Normal)**. Upgrading the token at the **Combat Master** unlocks **Fight (Hard)**.
|
||
4. Dying in a refight ends it; removing a token from the diary sends it back to your inventory.
|
||
|
||
Bosses: **Gloom Warden** (`boss_01`, legacy) and **Sky Terror** (`boss_02`) — Sky Terror lives in `room_08` (51 HP) and refights in `room_boss_fly_refight`; on Hard he opens with **two** skills per attack cycle and escalates to **all three** below 20% HP.
|
||
|
||
---
|
||
|
||
## 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. |