TamaPoke
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 < 30, −2 extra if HYG < 30 |
- ~15 %/min chance to poop (only 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 | After a proper goodbye | # species |
|---|
| ✨ Legendary | ~3 %* | ~10 % | 5 |
| 🔵 Rare | ~27 % | ~45 % | 27 |
| ⚪ Common | the rest | the rest | 47 |
* Legendaries only start appearing once you've registered ≥ 25 Pokémon.
- A daily streak and high bond push rare/legendary odds higher.
- A clean goodbye blesses the next egg; a run-away curses it (forces Common).
- Within a tier it favors species whose evolution line you haven't finished (so
all 151 are completable).
- Shiny: base 1 / 48 (→ 1 / 24 right after a goodbye), improved by
streak/bond down to a best of 1 / 8. Tracked separately in the dex.
- Every hatch rolls unique genes (90–110 % per stat) — no two are identical.
Evolution
- Triggers when level ≥ its evolution level (16 for most base forms; ~30 for
stone-style, ~40 for trade-style) and every stat ≥ 40 at that moment.
- Never automatic — a button appears and you tap to witness it (with a
flicker between the old and new form). Each slip-up delays it by 1 level.
- You can decline ("keep form"); it re-offers at the next level.
- Eevee branches toward whichever evolution you're still missing.
The three endings (you choose & witness each — none auto-fire)
- 💛 Farewell — when it's a final form that has lived 3 days. A button
appears; triggering it blesses your next egg. You can postpone ("stay
together", re-offered in a day). The good ending.
- 💔 Run-away — if you let all four stats sit at 0 for a full hour. A single
act of care cancels it. It curses the next egg (forces Common). The sad ending.
- 👋 Release — long-press the creature to let it go on your terms (neutral).
After any ending, a new egg appears.
Bonds, streaks, medals, Pokédex
- Streak (player-wide, survives across pets): first care each real day; milestones
at 3 / 7 / 30 / 100 days; skipping a day breaks it.
- Bond (per pet, resets on hatch): grows with affection (cap +8/day), cools on
neglect. Both streak & bond improve egg/shiny odds.
- 8 medals (Lv10/25/50, favorite berry found, 7-day streak, max bond, final form,
"fit" = weight 0 & no slip-ups), per-pet + a global counter.
- Pokédex: raising a species registers it; 151 + shinies to complete.
Battle stats
ATK / DEF / SPD = real Gen-1 base × genes + level + training (STRENGTH ← bag,
SPEED ← minigame, DEFENSE ← 12 h of unbroken good care). (Battles: on the roadmap.)
Hardware
- Board: ESP32-S3-Touch-AMOLED-1.75
— get the Standard (no case) or -G (GPS, also fits) version; not the "-B"
(ships with a protective case that won't fit). The separate "1.75C" is a different board.
- Where to buy: Waveshare store (often on backorder), or the -G on Amazon — TamaPoke leaves the GPS unused, the board is otherwise identical: 🇺🇸 .com · 🇪🇸 .es · 🇩🇪 .de · 🇬🇧 .co.uk · 🇮🇹 .it · 🇫🇷 .fr · 🇯🇵 .co.jp · 🇨🇦 .ca. Optional battery — 1100 mAh protected LiPo, MX1.25 plug: 🇪🇸 .es · 🇺🇸 .com · 🇮🇹 .it · 🇫🇷 .fr (DE/UK: that exact pack is not listed — search for a protected 3.7 V LiPo, ~1100 mAh, size , 1.25 mm micro-JST plug) — check plug polarity against the board first. Amazon links are affiliate links; as an Amazon Associate I earn from qualifying purchases.
Libraries (Arduino IDE / arduino-cli)
| Library | Author | Use |
|---|
GFX Library for Arduino (Arduino_GFX) | moononournation | CO5300 over QSPI + framebuffer in PSRAM |
| SensorLib | Lewis He | CST9217 touch + PCF85063 RTC |
| XPowersLib | Lewis He | AXP2101 PMU (battery, brightness, PWR button) |
| U8g2 | olikraus | CJK glyphs (unifont_t_japanese3, the only Japanese subset that also carries ！？。、「」; unifont_t_korean2 for Hangul, 2350 syllables against korean1's 478); only the font data is used, not its display driver |
| ESP_I2S (bundled in the ESP32 core) | Espressif | I2S to the ES8311 codec |
IDE setup / build
- Board: ESP32S3 Dev Module · Flash 16MB · PSRAM OPI PSRAM
(required: the 466×466×16-bit framebuffer ≈ 434 KB lives in PSRAM) ·
Partition Scheme with FAT (e.g.
16M Flash (3MB APP/9MB FATFS)) ·
USB CDC On Boot Enabled
FQBN="esp32:esp32:esp32s3:CDCOnBoot=cdc,FlashSize=16M,PSRAM=opi,PartitionScheme=app3M_fat9M_16MB"
arduino-cli compile --fqbn "$FQBN" .
arduino-cli upload -p /dev/cu.usbmodemXXXX --fqbn "$FQBN" .
Easiest install: the web installer
web/index.html flashes the firmware (ESP Web Tools) and pushes the sprites to
the SD over Web Serial, no Arduino needed. Serve it over HTTPS or localhost
(secure context) and open it in Chrome/Edge. See web/README.md.
Generate and load the sprites yourself
All sprites come from PMD SpriteCollab
(CC BY-NC). You can regenerate the whole set and load it onto your board with the
pipeline below — the firmware accepts files over USB (PUT protocol with per-block
ACK), so you don't have to remove the card (it formats the SD to FAT if needed).
python3 tools/pack_pmd.py # fetch + pack PMD sprites: the 151 + shiny -> tools/sdcard/mons/p[s]NNN.bin
python3 tools/make_thumbs.py # Pokédex thumbnails (from the PMD sprites) -> thumbs.bin
python3 tools/send_sd.py # send tools/sdcard/mons/* to the board's SD over USB
To make the one-click web-installer bundle instead of sending over USB:
python3 tools/pack_bundle.py # bundle tools/sdcard/mons/* into web/sprites.pak
Then load it from the web installer's "Load sprites" button (or send_sd.py
above). pack_pmd.py also takes individual dex numbers, e.g. pack_pmd.py 7 25.
(~40 MB total, all PMD. Versioned under tools/sdcard/.)
How to play
On first run you choose a starter (Bulbasaur / Charmander / Squirtle). After
that you start with an egg. Tap it 3 times or wait and it hatches. From then
on, care for your companion:
Four stats that decay: FOOD, JOY, ENE (energy), HYG (hygiene).
If one bottoms out it counts as a slip-up.
Buttons (bottom arc, icons):
- 🍎 Feed → food menu: 3 berries (each species has a hidden favourite that
gives a bonus) and a candy (+happiness but it fattens; weight makes it sluggish).
- ⚽ Play → the pokeball minigame (trains SPEED).
- 🌙 Light → sleep/wake (recovers energy, dims the screen). While asleep,
needs decay much slower (rest).
- 🫧 Bath → a foam scene that cleans up the poops.
Touch gestures:
- Tap the creature = pet it (+happiness, bond).
- Horizontal swipe = open the Pokédex / gallery.
- Vertical swipe up = open the stat card (4 pages: Profile / Battle / Medals /
Progress; swipe between them; tap the name on Profile to rename; on Battle the
"Train strength" button opens the bag).
- Swipe down = set the clock and pick the language + sound on/off.
- Long press (3 s) on the creature = release dialog.
Physical PWR button: short = screen on/off · long (4 s) = full power-off
(the RTC stays alive, so time passes even while it's off).
Decisions: you choose, and you watch
The three life-cycle endings and evolution don't happen on their own — when
the conditions are met a button appears and you tap it (so you're present to
witness it), each opening a two-option dialog:
- Evolution (red button): Evolve (epic animation: halo, rays, sparkles and
a flicker between the old and new form) or Keep form (re-offered next level).
- Farewell (gold button, final form + 3 days): Say goodbye (warm farewell,
rising hearts → new egg) or Stay together (keep your companion; re-offered in
a day). Tension: a maxed-out friend vs. completing the Pokédex.
- Runaway (dark button, total neglect for 1 h): a somber "feels abandoned"
ending in the rain — caring for the creature cancels it.
Sprites: PMD SpriteCollab everywhere
- PMD SpriteCollab (everything — main screen, stat card, minigame and the
Pokédex grid + detail view): behaviour sprites —
tools/pack_pmd.py packs
actions (Idle, Walk L/R, Sleep, Eat, Hurt, Attack, Pose, Nod, DeepBreath) into
the multi-action TPK2 format (/mons/pNNN.bin). The engine in TamaPoke.ino
makes the creature wander, gesture, curl up to sleep, chew and wince. Anchored by
the feet (lowest content row), not the canvas. The Pokédex thumbnails
(thumbs.bin, TPTH) are derived from these by tools/make_thumbs.py.
- In-house workshop (
tools/sprites.py): 9 primitive-drawn sprites as a
no-SD fallback + the UI icons. Generates species.h. Preview in
tools/sheet.png, emit with python3 tools/sprites.py emit.
sdmon.h/.cpp loads the PMD sprites into PSRAM (PmdMon for TPK2) plus the
thumbnails (SdThumbs). SdMon (TPK1) remains as a dormant legacy fallback only.
Pokédex and species data
tools/dex_data.py is the single source: name, slug, type (accent colour +
background biome), evolution line with gen-1 levels, rarities and starters.
tools/dex_stats.py has the real base stats (from PokéAPI). tools/gen_names.py
pulls the official localized names from PokéAPI into tools/dex_names.py
(only French and German differ in gen 1; Spanish, Italian and Portuguese use the
English ones). gen_dex.py emits dex.h (the DEX_TBL[152] table plus the
per-language name tables and the dexName() accessor). The pet's identity is its
Pokédex number (persisted in NVS).
- Evolution gen-1 style (levels 16/36/…; stones ≈30, trade ≈40; Eevee
branches to whichever evolution you're missing). Each slip-up delays it 1
level; it won't evolve with any stat < 40 or while asleep.
Battle stats and training
Each creature has ATK/DEF/SPD = real gen-1 base × genes (90–110 %, rolled at
hatch) + level + training:
- SPEED ← the minigame
- DEFENSE ← sustained good care (12 h with no slip-ups)
- STRENGTH ← the training bag (whacking)
Shown on the Battle page of the stat card. The (hidden) weight goes up with candy
and burns off with training.
Retention: streak, bond, medals, name
- Streak (the player's, persists across creatures): the first care of each
real day advances the streak; 3/7/30/100 milestones are celebrated; skipping a
day breaks it. Flame badge on the main screen.
- Bond (the creature's): rises slowly with care and petting, drops with slip-ups.
- Medals for the individual (level, berry, streak, bond, final form, fit) +
a global counter. Medals page of the stat card.
- Name: touch keyboard; the nickname rules the header and the card.
High streak and bond improve the egg roll (rarity and shiny): caring well
always pays off.
Life cycle, eggs by rarity, languages
The life cycle lasts 3 days of play. Three endings (all leave a new egg):
farewell (final form + 3 days), release (long press), runaway (all 4
bars at zero for 1 h). Each bred species is recorded in the bred Pokédex
(normal and shiny separately).
The egg rolls rarity over the ~79 base forms (47 common / 27 rare / 5 legendary),
biased towards the lines you're missing (all 151 are completable), blessed by
a farewell and punished by a runaway. Legendaries only with 25+ registered.
Shiny 1/48 (better with streak/bond/farewell).
Languages: the UI ships in 8 languages — English (default), Spanish, French,
German, Italian, Portuguese, Japanese and Korean — switchable from the settings
screen (swipe down).
Pokémon names are localized too: French, German, Japanese and Korean show
the official names (Bulbizarre, Bisasam, フシギダネ, 이상해씨...). Spanish, Italian
and Portuguese use the English ones, which is what those regions officially use
for gen 1. Nidoran♀/♂ read ニドランF/M in Japanese and 니드런 암/수 in Korean: no
U8g2 unifont subset carries ♀ or ♂, so each language picks its own substitute.
Backgrounds: biome + real time
The idle screen paints the sky from the RTC's real time (dawn / day / dusk /
night with moon and stars) and the ground from the type's biome (meadow,
beach, forest, volcano, mountain, snow). Sleeping forces night.
Layout
TamaPoke.ino — init, game loop, render of every screen, gestures, serial console, audiopet.h / pet.cpp — pet state and logic (stats, evolution, life cycle, streak/bond/medals, NVS)sdmon.h / sdmon.cpp — TPK1 (animated) and TPK2 (PMD) sprites + thumbnails, and file reception over USB (PUT/LS)rtcbat.h / rtcbat.cpp — PCF85063 RTC + AXP2101 PMU (battery, brightness, PWR button)audio.h / audio.cpp — ES8311 + I2S + Game-Boy-style tone synth (non-blocking task)i18n.h / i18n.cpp — the 8-language string tablesdex.h — GENERATED (gen_dex.py): the 151 tablespecies.h — GENERATED (sprites.py): fallback sprites, UI icons, colourspin_config.h — the board's official pinstools/ — pipeline: dex_data.py (data), dex_stats.py, dex_names.py +
gen_names.py (localized names), gen_dex.py,
sprites.py (workshop), pack_pmd.py / make_thumbs.py
(packers), pack_bundle.py (web bundle), send_sd.py (SD upload), touch_log.pytools/sdcard/mons/ — the generated .bin files (animated, shiny, PMD, thumbnails)web/ — the browser installer (ESP Web Tools + Web Serial sprite loader)
Battery
The percentage on screen comes from a typical single-cell LiPo discharge curve (batcurve.h) over a smoothed
voltage, and only goes down while discharging; on USB or while charging the PMU's own gauge is used. When the
smoothed voltage stays under 3.30 V for 30 s the pet is saved and the PMU powers off (not in the first 30 s
after boot); the PMU itself is set to cut at 3.1 V as a backstop.
What the firmware does to save power (the policy is in power.h, covered by test/test_power.cpp):
- Frame rate follows activity. 10 fps while you interact; 6.7 fps after 1 min without touching;
4 fps when the screen dims (90 s); 1 fps when it is almost off (5 min); 2 fps while the pet sleeps and
nobody touches it. The ball minigame keeps its 85 ms step. Over 10 idle minutes this sends about 68 % fewer
frames to the panel (each one is a full redraw plus a 434 KB QSPI transfer).
- Static screens are not redrawn. Keyboard, clock, card pages 2-4 and the starter choice are painted once
and again only when something on them changes.
- Light sleep when nobody is looking. With the screen off, or almost off (5 min), and on battery, the CPU
sleeps until the next frame or 200 ms; a touch wakes it at once. With USB connected it never sleeps (the
serial port for the SD card stays available), and USB is checked right before each sleep.
- Speaker amplifier only when it can be used. It is off while the pet sleeps and while the screen is dimmed
or off; a sound requested meanwhile (e.g. "ready to evolve") switches it on for 4 s, and sounds wait 50 ms
after a power-up so the start is not cut.
- Low battery (< 20 %, not charging): brightness capped (100, then 60 under 10 %) and frames twice as slow.
- Battery reads over I2C every 10 s instead of 2 s when the screen is off or almost off.
- The pet walks by real time, so lower frame rates do not slow it down.
Serial console (115200, debug)
STATS (full state) · SPEC <dex> (change species) · LVL <n> · HATCH ·
SHINY · NICK <x> · BYE / RUN (farewell / runaway) · ABANDON (force the
runaway-ready state) · WIPE (factory reset → new game) · BEEP (audio test) ·
REG (Pokédex) · EGGS (simulate 20 eggs) · GAL (gallery) · CAREDAY ·
TIME <epoch> / RTCSET <epoch> · HEALTH (uptime + heap for the soak test) ·
LS / PUT (SD files).
To test fast: lower PET_TICK_MS, MINUTES_PER_LEVEL and FAREWELL_AGE_MIN in pet.h.
Roadmap
- Wild encounters / battle — designed (see project memory): resolution by
ATK/DEF/SPD with PMD Attack/Hurt animations, trainer rank as endgame. Style
still to pick (auto / timing / turn-based).
- Soak test 24–48 h (instrumentation ready:
HEALTH command/heartbeat).
(Done: 3D-printed case published on MakerWorld; repo public with the browser installer + one-click sprite bundle.)
Community forks
- TamaPoke — Expanded by ShadowEnemy — a substantial community fork (different author/branch): a full type-matchup battle system, all 151 + shinies with a Pokédex / collection box and daily goals, 6 UI languages, ES8311 sound, starter choice and a one-click web installer. Worth a look. 🎮
- TamaPoke by DylanPDao — another substantial fork: gym battles and LAN battles between two devices, movesets, a party + box system, an EV/IV stat system, and coverage extended up to Gen 3 (386). Keeps the PMD sprite pipeline. 🏆
Credits
All sprites: PMD SpriteCollab
(community, CC BY-NC). Base stats: PokéAPI. Pokémon is a ™ of
Nintendo / Game Freak / The Pokémon Company. Non-commercial, personal-use project.
Full list in CREDITS.md. Version history in
CHANGELOG.md — most of the fixes there came from people
who built one and reported what they found.
License
- Source code (firmware + tooling): MIT.
- Sprites & names: © Nintendo / Game Freak / The Pokémon Company; pixel art
from PMD SpriteCollab (CC BY-NC 4.0).
Non-commercial use only.
- 3D-printed case: remix of "Pokeball" by yoyothechicken
(MakerWorld #839922),
licensed CC BY-NC-SA, and shared here under the same terms.
This is an unofficial fan project, not affiliated with or endorsed by Nintendo.
