https://github.com/acpayers-alt/raising-hell-cardputer
Open-source virtual pet firmware for the M5Stack Cardputer.
https://github.com/acpayers-alt/raising-hell-cardputer
arduino cardputer embedded-game esp32 firmware m5stack virtual-pet
Last synced: about 2 months ago
JSON representation
Open-source virtual pet firmware for the M5Stack Cardputer.
- Host: GitHub
- URL: https://github.com/acpayers-alt/raising-hell-cardputer
- Owner: acpayers-alt
- License: mit
- Created: 2026-02-04T22:57:39.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-04-07T08:31:13.000Z (about 2 months ago)
- Last Synced: 2026-04-07T10:22:42.131Z (about 2 months ago)
- Topics: arduino, cardputer, embedded-game, esp32, firmware, m5stack, virtual-pet
- Language: C++
- Homepage:
- Size: 38.6 MB
- Stars: 56
- Watchers: 6
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Raising Hell — Cardputer ADV Edition
A Tamagotchi-style virtual pet game for the M5Stack Cardputer ADV (ESP32).
Raise your infernal companion through multiple life stages, feed it, play mini-games, manage sleep cycles, survive decay, and maybe… resurrect what should not be resurrected.
------------------------------------------------------------
Hardware Target
------------------------------------------------------------
- M5Stack Cardputer ADV
- ESP32 (240 MHz)
- SD card (required for assets)
------------------------------------------------------------
Controls
------------------------------------------------------------
Arrow Keys - Navigate
Enter/G - Confirm
Esc - Menu
Del/Q
GO - Screen Off/On
Shake Your cardputer to wake the screen
Hold GO - Power Menu
/ - Console
Keyz Z-M are hotkeys for all the tabs
(Some mini-games may use alternate input behavior.)
Alternate Navigation - E,A,S,D and O,J,K,L - allows for one handed navigation
------------------------------------------------------------
Planned Features
------------------------------------------------------------
loading screen for games
shake sensitivity settings
screen flashes same color as alert LED (maybe even shows pet status)
create log file as txt on sdcard for user upload
add heartbeat sequence to death flow
Clock Mode
Human reasable/editable settings file for easy recovery
------------------------------------------------------------
Project Structure
------------------------------------------------------------
src/ (all .cpp and .h files)
assets/ Image Files
docs/ Licensing, Changelog, Contrib
tools/ Asset Manifest Generator and other Dev Tools
------------------------------------------------------------
Installation
------------------------------------------------------------
Raising Hell runs on the **M5Stack Cardputer ADV**.
There are three ways to install the game depending on your setup.
---
# 1. Install via M5Launcher (Recommended)
This is the easiest way to install Raising Hell directly from the Cardputer.
### Steps
1. Install **M5Launcher** on your Cardputer if it is not already installed.
2. Connect the device to **Wi-Fi**.
3. Open **M5Launcher**.
4. Browse the application list and locate **Raising Hell**.
5. Select the game and choose **Install**.
After installation:
- Launch the game from the launcher.
- On first boot the game will **automatically provision required assets via OTA**.
No manual asset downloads are required.
---
# 2. Install using M5Burner
You can install the firmware from a computer using **M5Burner**.
### Requirements
- M5Burner installed on your computer
- USB connection to the Cardputer ADV
### Steps
1. Connect the Cardputer ADV to your computer via USB.
2. Open **M5Burner**.
3. Search for **Raising Hell**.
4. Select the application.
5. Click **Burn**.
6. Wait for flashing to complete.
After the first launch:
- The game will **download required assets automatically via OTA**.
---
# 3. Manual Firmware Install (Advanced)
Advanced users can manually flash the firmware using **PlatformIO or esptool**.
### Step 1 — Download firmware
Download the latest firmware binary from the **GitHub Releases page**:
https://github.com/acpayers-alt/raising-hell-cardputer/releases
### Step 2 — Flash firmware
Flash the firmware to the device.
Example using PlatformIO:
```bash
pio run -t upload
```
Or using esptool:
```bash
esptool.py --chip esp32s3 --port /dev/ttyACM0 write_flash 0x10000 firmware.bin
```
### Step 3 — Launch the game
After booting the firmware:
- The game will automatically **provision its asset pack via OTA**.
---
# First Boot Behavior
On first launch Raising Hell will:
- Check for required game assets
- Download missing assets automatically
- Store assets on the SD card
This process only occurs once.
---
# Hardware Support
Currently supported hardware:
M5Stack Cardputer ADV
The original first-generation Cardputer has not been tested and may not work correctly.
---
# Troubleshooting
If the game fails to start:
- Ensure an **SD card is installed**
- Ensure the device has **Wi-Fi connectivity** for asset provisioning
- Restart the device after flashing
------------------------------------------------------------
Development Direction
------------------------------------------------------------
This project is under active architectural cleanup and refactor toward:
- Modular state architecture
- Strict include hygiene
- Removal of legacy globals
- Separation of platform and gameplay logic
- Open-source readiness
------------------------------------------------------------
Arduino IDE Settings
------------------------------------------------------------
Recommended configuration:
Board: M5Cardputer
Flash Mode: QIO 80MHz
Flash Size: 4MB (32Mb)
Partition Scheme: Huge APP (3MB No OTA / 1MB SPIFFS)
CPU Frequency: 240MHz (WiFi)
Upload Speed: 921600
------------------------------------------------------------
Building From Source
------------------------------------------------------------
1. Clone the repository.
2. Copy the assets folder contents to an SD card.
3. Open raising_hell_cpADV.ino in the Arduino IDE.
4. Select the board settings listed above.
5. Compile and upload.
------------------------------------------------------------
Known Limitations
------------------------------------------------------------
- Requires SD card
- Designed specifically for Cardputer ADV hardware
- Not optimized for alternate ESP32 boards
------------------------------------------------------------
License
------------------------------------------------------------
Code is licensed under the MIT License.
See the LICENSE file for details.
Assets licensing is described in ASSETS_LICENSE.md.
------------------------------------------------------------
Author
------------------------------------------------------------
Aaron Ayers
If you build this, fork it, improve it, or port it — I’d love to see it.
------------------------------------------------------------
Screenshots
------------------------------------------------------------
