README

TamaPoke



!Board
!Firmware

!Code
!Languages


A gen-1-Pokémon-inspired tamagotchi for the
Waveshare ESP32-S3-Touch-AMOLED-1.75 (round 466×466 AMOLED, CO5300 driver
over QSPI, CST9217 touch over I2C). Raise any of the 151, evolve it, train it
and complete them all (shinies included).

 Personal, non-commercial fan project. Code is MIT; the sprites are from
 PMD SpriteCollab (CC BY-NC, Pokémon © Nintendo/Game Freak), and the 3D case is
 CC BY-NC-SA. See License and Credits.

🔴 3D-printed Pokéball case + print profiles → on MakerWorld · flash it in your browser → web installer

 Status

Running on hardware. Implemented: the 151 + shinies animated from microSD, full
life cycle (egg by rarity → evolution → farewell/release/runaway, each gated
behind a decision dialog), bred-Pokédex with gallery, battle stats (genes +
training), retention hooks (streak / bond / medals / name), biome + real-time
backgrounds, ball minigame, training bag, animated bath, RTC with offline
progression, battery (AXP2101) and PWR button, anti-burn-in dimming,
sound (ES8311), 8 UI languages (English default), starter choice on
first run, and a one-click web installer.

Pending: wild encounters / battle (designed, not implemented), 3D case, soak
test. See Roadmap.

 Game manual (the actual numbers)

A quick reference to how the game really works (values straight from the code).

 Time & leveling
- 1 real minute = 1 in-game minute. Your Pokémon gains +1 level every hour
  of real time. Leveling is purely time-based — caring well doesn't speed it up,
  but neglect delays evolution.
- It keeps aging while powered off (the RTC runs), catching up to 2 weeks max.

 The four stats (0–100)
Needs: FOOD, JOY, ENE (energy), HYG (hygiene). Start 80 / 80 / 80 / 100.
While awake, per minute:

| Stat | Drain/min | Notes |
|---|---|---|
| FOOD | −2 | |
| ENE | −1 | −1 extra if overweight (weight  50 → sluggish) |
| HYG | −1 | −4 more per poop on screen (max 3 poops) |
| JOY | −1 | −2 extra if FOOD  40). Poops tank hygiene fast.
- Care slip-up = letting any stat hit ≤ 10 (30-min cooldown so it counts once).
  Each slip-up delays evolution by 1 level and cools the bond.

 Actions
- 🍎 Berry (3 flavors): +25 FOOD. Each species has a hidden favorite flavor
  → +35 FOOD, +10 JOY, ♥, bond, and it gets revealed.
- 🍬 Candy: +10 FOOD, +12 JOY, but +12 weight (fattening).
- ⚽ Play / minigame: +JOY, −ENE; the minigame trains SPEED and burns weight.
- 🥊 Training bag: trains STRENGTH (~4 hits = 1 pt, cap +18/session), tires it.
- 🫧 Bath: clears poops, HYG → 100.
- 👆 Pet it: +5 JOY + bond.
- 🌙 Sleep: rest — ENE +6/min, needs drain ~4× slower with floors
  (FOOD 30 / JOY 35 / HYG 45). No poops, no slip-ups, can't run away while asleep.

 Eggs & who you get (spawn odds)
- First ever pet: you pick a starter — Bulbasaur / Charmander / Squirtle.
- Hatch the egg: tap it 3× (or wait — it hatches on its own).
- Every later egg rolls a rarity tier (over the ~79 base forms that come from eggs):

| Tier | Base chance

Top issues