A physical Tamagotchi-style writing companion built with an ESP32-S3.
Tama is a tiny dinosaur that survives on your words. Feed it at least 250 words per day or it will slowly get sick... and eventually die.
The project combines:
- Embedded software
- Pixel animation
- Habit tracking
- Physical hardware (buttons, screen, battery)
- 3D printed enclosure
The goal is to create a delightful physical motivator for writing habits.
Tama lives inside the device and reacts to your writing progress.
- Feed Tama 250+ words per day
- Miss 3 days → Tama gets sick
- Miss 6 days → Tama dies
Stage Trigger
Egg Start state Hatch 1,000 words Adult 20% of total goal Sick 3 missed days Dead 6 missed days
The Tamagotchi is controlled with three buttons:
Button Action
Left Decrease value Middle Reset Right Increase value
The buttons are used to:
- log writing progress
- navigate menus
- trigger interactions
Tama expresses its state through pixel animations:
- idle
- reading
- writing
- celebrating
- sick
- dead
Animations are rendered on the LCD using LVGL.
This project uses an ESP32-S3 AMOLED development board.
- ESP32-S3 Touch AMOLED 1.8 display
- 3 × tactile buttons
- LiPo battery
- speaker (optional)
- 3D printed case
Buttons are connected to GPIO pins and ground.
Example wiring:
Button → GPIO
Button → GND
Each button press is detected as a digital input event.
writing-tamagotchi
│
├── main
│ ├── main.c
│ ├── assets
│ │ ├── images
│ │ └── animations
│ │
│ └── audio
│
├── components
│ └── esp_lcd_touch_ft3168
│
├── partitions.csv
└── CMakeLists.txt
Implemented using LVGL
Responsibilities:
- render Tamagotchi background
- display animations
- show icons and menus
Animations are stored as C image arrays generated from PNG files.
assets/animations/
Each state has its own animation set:
prehatch/
hatched/
idle/
writing/
celebrate/
sick/
dead/
Animation frames are displayed sequentially using an FPS controller.
The behaviour logic manages:
- lifecycle transitions
- health tracking
- writing milestones
- animation switching
Simplified state flow:
Egg → Hatched → Idle/Writing → Sick → Dead
Button presses trigger events such as:
- increment word counter
- decrement
- reset
Inputs are read from GPIO pins.
Animations are created as images and converted using the LVGL Image Converter.
PNG → LVGL converter → C pixel array
These are compiled directly into the firmware.
You will need:
- ESP-IDF v5+
- Python 3
- CMake
- ESP-IDF VSCode Extension (recommended)
Clone the repository:
git clone https://github.com/yourname/writing-tamagotchi
cd writing-tamagotchi
Install ESP-IDF dependencies:
idf.py install
Configure the project:
idf.py menuconfig
Select the correct ESP32-S3 board configuration.
Compile the firmware:
idf.py build
Connect the ESP32-S3 via USB.
Flash and monitor:
idf.py -p /dev/ttyUSB0 flash monitor
On macOS the port may be:
/dev/tty.usbmodem*
Once flashed, the device will boot automatically.
The display will show:
- Tamagotchi background
- Current animation
- Writing progress interface
Use the buttons to simulate writing progress.
Edit code → Build → Flash → Test → Repeat
- Draw animation frames
- Export as PNG images
- Convert with LVGL image converter
- Add generated
.cfiles to:
assets/animations/
- Register animation in the animation system.
Potential upgrades:
- WiFi syncing with writing apps
- persistent habit storage
- multiple pets
- streak tracking
- sound effects
- USB charging port in case design
MIT License
Inspired by the original Tamagotchi virtual pets.