# Panagotchi

A Tamagotchi-style virtual pet for the **CH32V003F4P6** badge — a hacker-themed creature that evolves from `proc` → `user` → `root`, then either ascends to **Claude** or degrades into a **glitch** depending on how well you tend to it.

Fits in ~12 KB of the 16 KB flash budget.

## Hardware

| Pin  | Function        |
|------|-----------------|
| PA1  | Indicator LED   |
| PC0  | OK button       |
| PC1/PC2 | SSD1306 128×64 OLED (I2C1) |
| PD2  | Passive piezo buzzer |
| PD5  | Right button    |
| PD6  | Left button     |

Powered by a CR2032 coin cell via a TLV61070A boost converter to 3.3V. See [pinout.md](pinout.md) for the full pin assignment and power architecture.

## Gameplay

**Controls:** Left / Right move the menu cursor. OK activates the selected action.

**Menu actions:**

| Icon    | Action  | Effect |
|---------|---------|--------|
| Apple   | FEED    | +30 satiety, −5 hygiene |
| Ball    | PLAY    | +25 happy, −12 energy (requires energy ≥ 15) |
| Moon    | SLEEP   | Toggle nap; restores energy |
| Drop    | CLEAN   | Reset hygiene to 100, remove poop piles |
| Cross   | HEAL    | +35 health |
| Chart   | STATS   | Show stat bars + XP readout |
| Gear    | SETTINGS| Screen timeout, brightness, sound |

Stats decay on a ~15-second tick. Health responds to overall wellbeing — if any need drops below 15 it bleeds down; if all are above 50 it recovers. Let health reach 0 and the pet dies with a `SEGFAULT (11)`.

**Evolution** (XP thresholds: 45 / 120 / 240):

```
proc  →  user  →  root  →  Claude (well-kept) / glitch (neglected)
```

Each stage gains a visual accessory: shades at `user`, a gaming headset and mic boom at `root`.

**Species** (chosen on the welcome screen):

- **Panko** — the panda; full 7-expression animation set
- **Shell** — a friendly CRT terminal with a `> _` prompt mouth
- **Tmux** — a split-pane terminal with a status bar

## Building

Requires [ch32v003fun](https://github.com/cnlohr/ch32v003fun) checked out as a sibling directory.

```sh
# Generate sprites from source art
python3 sprites_gen.py > sprites.h

# Build and flash
make
```

Flash via the `minichlink` or `wch-link` programmer. The Makefile targets `cv_flash` / `cv_clean` from ch32fun.

Check real flash usage with:

```sh
riscv-none-elf-size tama.elf
```

## Power saving

The OLED is the biggest power draw. When the screen-off timeout fires, the display is blanked and the MCU enters WFI light-sleep. Two wake sources:

- **Button press** (EXTI falling edge on PC0/PD5/PD6) — lights the screen back up
- **TIM2 overflow** (~once per game tick) — runs a background stat update and low-need chirp, without waking the display

SRAM and all pet state survive WFI; only the CPU clock is gated.

Brightness and screen-off timeout are adjustable in the settings menu.

## Files

| File | Purpose |
|------|---------|
| [tama.c](tama.c) | Main firmware: game logic, rendering, input, low-power |
| [sprites_gen.py](sprites_gen.py) | Python sprite generator — edit art here |
| [sprites.h](sprites.h) | Auto-generated 1-bpp sprite data (do not edit) |
| [funconfig.h](funconfig.h) | ch32fun config overrides (disables printf backends) |
| [pinout.md](pinout.md) | Full pin assignment and power architecture notes |
| [OPTIMIZATION.md](OPTIMIZATION.md) | Flash size backlog and optimization notes |