93 lines
3.3 KiB
Markdown
93 lines
3.3 KiB
Markdown
# 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 |
|