battery/README.md

# Dying Phone

A single-screen 2D platformer in the spirit of the original *Super Mario Bros.*,
built with Python + pygame. Your phone is dying; sprint to the charger at the
end of each level before the battery hits zero. The catch: the level is packed
with obvious and (mostly) hidden traps. Touch one and you respawn instantly at
the start with every trap reset. The battery is just the story's excuse for a
timer — running it down kills you the same as any spike.

## Install & run

```bash
pip install -r requirements.txt
python main.py                       # play every level in ./levels
python main.py levels/level1.yaml    # play a specific level (or several)
python main.py --debug               # force the debug view on for all levels
```

No art required — everything renders as labeled colored rectangles until you
drop PNGs into `assets/` (see `assets/README.md`).

### Tests

```bash
pip install -r requirements-dev.txt
pytest
```

The suite runs headless (SDL dummy driver) and covers the physics, collision
resolution, every trap and trigger, mounting, crush/shove interactions, and the
game-flow states. See `SPEC.md` for a full description of the engine and level
format.

## Controls

| Key                | Action                                    |
|--------------------|-------------------------------------------|
| `A` / `D` (arrows) | move left / right                         |
| `Space` / `W`      | jump (hold = higher, tap = short hop)     |
| `S` + `Space`      | drop through one-way platforms            |
| `R`                | give up and respawn                       |
| `F5`               | hot-reload the level from disk (counts as a death; also escapes soft-locks) |
| `Esc`              | quit                                      |
| `Enter`            | advance on the level-complete screen      |

## Writing levels

Levels are plain YAML. A level has an ASCII `map` for static geometry and a
`traps` list for the nasty interactive bits.

```yaml
name: "My Level"
tile_size: 32          # pixels per tile (optional; default 32)
battery_seconds: 40    # time limit (optional)

map: |
  .........
  ...###...
  .P.....G.
  #########

traps:
  - type: spike
    at: [4, 2]         # [col, row], 0-based from top-left
    direction: up
    trigger: { within: 2.0 }
```

### Map legend

| Char | Meaning                                   |
|------|-------------------------------------------|
| `#`  | solid block                               |
| `-`  | one-way platform — stand on top, jump/drop through. Renders **identically to a solid block**, so it's a hidden mechanic. |
| `P`  | player spawn                              |
| `G`  | goal / phone charger                      |
| `.` or space | empty                             |

The window is sized to the map automatically — one screen, no scrolling.

Level options (all optional, alongside `name` / `map` / `traps`):

| Key | Default | Meaning |
|---|---|---|
| `tile_size` | 32 | pixels per tile |
| `battery_seconds` | 45 | time limit |
| `battery_pct` | 12 | how full the battery bar *looks* at the start (visual only) |
| `debug` | false | reveal everything normally hidden — a tile grid with col/row labels, faded `-` one-way platforms, tinted fake blocks / invisible walls / warps (with a line to their destination), dormant phase blocks, not-yet-sprung spikes, crumbled-block ghosts, and moving block paths. The `--debug` CLI flag forces this on for every level. Combine with `F5` to iterate on a level without relaunching. |

## Trap reference

All traps take `at: [col, row]`. Where a trap draws its own block (fake, moving,
patrol, crumble, shooter), leave that map cell **empty** — otherwise a real
solid sits underneath it.

Any trap can also take:
- **`invisible: true`** — stays fully functional but isn't drawn (revealed under
  the level's `debug` view). An invisible solid `block` is a wall you can't see.
- **`count: [nx, ny]`** (or a single int for a horizontal line) — place a
  line/grid of copies, offset by **`spacing: [sx, sy]`** tiles (default 1). Only
  `at` is shifted per copy, so `move` is relative and works; an absolute `path`
  is shared. Handy for a row of spikes or a rectangle of (invisible) blocks.

| `type`          | Key parameters | Behavior |
|-----------------|----------------|----------|
| `spike`         | `direction` (`up`/`down`/`left`/`right`), `trigger`, `delay` | Deadly spike; active while its `trigger` holds. The sprite auto-rotates to point the way `direction` faces. |
| `block`         | see below | The all-in-one block: stationary, sliding, patrolling, deadly, fake, crumbling, and/or phasing. |
| `arrow_shooter` | `direction`, `speed`, `interval`, `trigger`, `delay` | A wall turret firing deadly arrows every `interval` seconds while its `trigger` holds. |
| `warp` | `to` [col,row] | Invisible tile that teleports the player to `to` on contact. Re-arms once you leave it. |

### The `block` trap

One trap covers stationary blocks, sliders, patrolling platforms, spike blocks,
fake blocks, crumbling blocks, and phase blocks — compose the behaviour from
options (which combine, e.g. a moving platform that crumbles, or a phase block
that's always moving):

| option | meaning |
|---|---|
| `path` [[col,row],…] | waypoints it travels between (default just `[at]` = stationary) |
| `move` [dcol,drow] | shorthand for a 2-point path `[at, at+move]` (a slider) |
| `mode` | `once` (default): advance to the last point while triggered, retreat to the first when not — the slider/dropper. `loop` / `pingpong`: cycle the whole path continuously (a patrol). |
| `trigger` | when it activates (default `always`). A patrol is just a path + the default `always` trigger. A block that both moves and phases can give each its own trigger via a per-target map (see Triggers). |
| `deadly` (bool) | `true` → a hazard (spikes) instead of a solid. On a phase block the hazard is live only once materialised. |
| `fake` (bool) | looks solid but you fall straight through it |
| `crumble` (bool) + `crumble_delay`, `respawn` | gives way `crumble_delay` s after you stand on it, vanishes, then reappears after `respawn` s (killing you if you're standing where it re-forms) |
| `phase` (bool) + `fade` | invisible/intangible until triggered, then fades into a solid (or a hazard, if `deadly`) over `fade` s (default 0.3) and back out when the trigger releases. Forming into you is lethal, but a non-deadly one first shoves you clear if you're only clipping an edge; if you die while one is mid-fade it snaps fully visible for the death freeze. |
| `speed` | px/s |
| `sprite` | override sprite (default: `spike_block` if deadly, `fake_block` if fake, `crumble_block` if crumble, `phase_block` if phase, else `moving_block`) |
| `delay` / `release` | hold `delay` s to activate (may be a per-target map); in `once` motion, be clear `release` s (default 0.1) to start retracting — stops boundary jitter |
| `sense` | `home` (default): a slider senses its trigger from its resting cell, so moving away can't toggle its own trigger. `current`: senses from the live position — for a block you *ride* (e.g. a dropper) so it stays put while ridden instead of pulling back |

```yaml
- type: block                     # stationary spike block
  at: [13, 4]
  deadly: true

- type: block                     # dropper: extends down while you're above it, rides with you
  at: [21, 9]
  move: [0, 4]
  sense: current
  trigger: { all: [ {within: 5}, {dir: above, aligned: true} ] }

- type: block                     # patrolling platform
  at: [9, 10]
  path: [[9, 10], [14, 10], [14, 6]]
  mode: loop
  sprite: patrol_block

- type: block                     # deadly block that patrols AND phases in near you
  at: [9, 3]
  phase: true
  deadly: true
  move: [4, 0]
  trigger:
    motion: always                # always sliding back and forth
    phase: { within: 3 }          # but only solid/deadly when you're close
```

A `once` block runs a *committed stroke*: once it starts moving it runs all the
way to the endpoint (never reversing mid-stroke) and only reconsiders its
trigger while parked — so a slider that moves out of its own sensor range can't
buzz. Blocks track their live position, so a moving block can shove or crush
you, and you can ride a non-deadly one.

### Triggers

`spike`, `block`, and `arrow_shooter` are active while a **trigger
condition** holds. A trigger is `always` (the default) or a condition object
measured against the player each frame, relative to the trap's *current*
position (so a moving trap's sensors follow it):

| condition | meaning |
|---|---|
| `{ within: N }` | player within N tiles (radius) |
| `{ dir: left\|right\|above\|below }` | player is on that side |
| `{ dir: …, range: N }` | …and within N tiles that way |
| `{ dir: …, aligned: true }` | …and overlapping on the perpendicular axis (i.e. *directly* left / *directly* above) |
| `{ dir: …, inclusive: true }` | …also count the trap's own tile as being on that side (default `false`: the player must be strictly past the near edge) |
| `{ timer: { interval: A, up_time: B } }` | cyclic: off A seconds, on B seconds |
| `{ all: [ … ] }` | every listed condition (AND) |
| `{ any: [ … ] }` | any listed condition (OR) |

```yaml
# drops only when you're close AND standing over it; keeps dropping as you ride it
trigger:
  all:
    - { within: 5 }
    - { dir: above, aligned: true }
```

**`delay`** (seconds, default `0`): the trigger condition must hold
*continuously* this long before the trap arms; leaving the condition resets the
countdown. Handy for "linger and it strikes" spikes.

**Per-target triggers.** A `block` can both move and phase, and each behaviour
can take its own trigger (and `delay`). Give a single condition to drive both,
or a map keyed by target (`motion` / `phase`) with `default` covering the rest:

```yaml
trigger:
  default: always            # phase (and anything else)
  motion: { within: 5 }      # motion only
delay: { motion: 0.1, phase: 0.3 }
```

A map that names some targets but omits `default` leaves the unnamed ones with
no trigger (off) — the debug view warns if that silently disables a capability.
An unknown target name is an error.

### Getting crushed

You also die if a moving (non-deadly) `block` **pinches** you: presses you
against a solid surface — squished into the ground from above, carried up into a
ceiling, or driven sideways into a wall by a block hitting you from the side.
Riding a platform horizontally into a wall is *not* a crush, though: you simply
stop at the wall while the platform slides on under your feet. During the death
pause the whole scene freezes, so the offending block stops on the spot until
you respawn.

### Mounting traps on other traps

Any trap can carry a `mounts:` list of child traps that ride along with it. A
mounted trap's `at` is read as a **relative** offset (in tiles) from its parent,
and it tracks the parent's live position every frame — so you can bolt a spike
onto a patrolling platform, or a turret onto a moving block:

```yaml
- type: block
  path: [[6, 10], [9, 10]]
  mode: pingpong
  sprite: patrol_block
  mounts:
    - type: spike
      at: [0, -1]          # one tile above the block; moves with it
      trigger: always
      direction: up
```

Everything the mounted trap does — hazards, solids, trigger sensing, drawing —
follows the parent automatically; no special-casing per trap type. You can mount
a `block` too (e.g. deadly blocks at the ends of a moving platform for spikes on
a moving hazard) — a mounted trap **rides rigidly** at its offset and doesn't
run its own motion, so mount stationary pieces (spikes, blocks, turrets) rather
than something you expect to move on its own.

### Adding a new trap type

Subclass `Trap` in `game/traps.py`, implement any of the hooks
(`solid_rects`, `oneway_rects`, `hazard_rects`, `carriers`, `update`, `draw`,
`reset`), and register the class in `TRAP_TYPES`. The engine polls those hooks
every frame — nothing else needs to change.

## Project layout

```
main.py            entry point
game/
  game.py          loop, states, HUD, death/respawn/win flow
  level.py         YAML -> geometry + traps
  player.py        movement & AABB collision
  traps.py         trap base class + all trap types + factory
  assets.py        PNG loading with colored-rect placeholders
  settings.py      physics/gameplay tunables
levels/*.yaml      level definitions
assets/*.png       optional sprites
```