level editor overhaul

more objects, NPCs, better toolbar and snapping

light_and_dark/README.md

@@ -2,7 +2,7 @@
 
 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.
+> 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.
 
 ---
 
@@ -12,7 +12,7 @@ A 2D platformer built with **Pygame**. You switch between two forms — **Light*
 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`.
+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.
 
 ---
 
@@ -31,7 +31,8 @@ Requires Python 3.10+ and `pygame`. Game data (rooms, items, sets, enemies, drop
 | Tether | X |
 | Reality Break | C |
 | Toggle Light/Shade | Left Shift |
-| Interact / Talk | F |
+| Interact / Talk / Save | F |
+| Use Butterfly Jar | G |
 | Inventory | I |
 | Stats overlay | H |
 | Pause / Settings | Esc |
@@ -44,7 +45,29 @@ Requires Python 3.10+ and `pygame`. Game data (rooms, items, sets, enemies, drop
 
 **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.
+**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.
 
 ---
 
@@ -129,5 +152,19 @@ The shade-focused sets (**Duskwarrior, Umbraflow, Abyss Cleaver, Adaptive Travel
 ## 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 buff, and any stat bonuses from gear.
+- **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.