ScummVM on the Fri3d Camp badge (2024/2026) — project scaffold

What this is / isn't

This gets you a launcher app in MicroPythonOS, built by directly copying the real, shipped com.micropythonos.retrocore_launcher / com.micropythonos.duke_launcher apps (pulled from MicroPythonOS/MicroPythonOS on GitHub) and adapting their exact partition-boot-switch logic — not a guess at the pattern. It also includes the partition table change needed to make room for a ScummVM partition, pulled from the real boards/shared/partitions.16mb.csv in Fri3dCamp/badge_firmware_MicroPythonOS.

It does not include a working ScummVM binary — porting ScummVM's display/input backend to the badge's screen and buttons is the actual hard part, and it's a several-day embedded project, not something generated sight-unseen. Below is the real path to get there, in order.

Why this is needed at all

The real partition table (boards/shared/partitions.16mb.csv) fully allocates the 16 MB flash: otadata/nvs preamble, two 3.5 MiB MicroPythonOS OTA slots (ota_0/ota_1), a 960 KiB retro-core partition, a 1 MiB duke3d-go partition, and a 7 MiB vfs (FAT) data partition for storage. There is no spare app-partition slot for a new binary — partition_table/partitions_scummvm.csv shrinks vfs by 1 MiB to make room for a new scummvm app partition at the same offset pattern as duke3d-go.

Stage 1 — Get a minimal ScummVM building for ESP32 at all

Don't start from the badge. Start from espressif/esp32-scummvm (actively maintained by Espressif) or varna9000/scummvm-tdeck (a leaner, more recently touched ESP32-S3 port with a known-working build). Get either building and running on that reference hardware first with ESP-IDF, using the Monkey Island 1 EGA demo (free from scummvm.org) as your test asset. This validates your toolchain before you touch badge-specific pins.

Trim it down hard:

• Disable every engine except SCUMM in the ScummVM configure step (--disable-all-engines --enable-engine=scumm).
• Disable unused codecs (FLAC, MP3, Vorbis) unless you need the Talkie/CD-audio editions — the EGA demo needs none of them.
• This is exactly what keeps it inside a ~1 MiB app partition; a full multi-engine ScummVM build will not fit.

Stage 2 — Port the display/input backend to the badge

This is the actual porting work. You need a ScummVM OSystem backend that targets the badge's specific display driver and button/joystick GPIO mapping, which is defined in Fri3dCamp/badge_2024_arduino and Fri3dCamp/badge_retro-go. The T-Deck port's backend (backends/platform/esp32 in scummvm-tdeck) is the closest existing reference for what this looks like on ESP32-S3 with an SPI display — read its esp32_osystem.cpp-equivalent before writing your own. Retro-Go's existing display/input driver for the badge (already proven working for NES/GB emulation) is likely reusable/adaptable here rather than writing a driver from scratch.

Build this as its own ESP-IDF app targeting the scummvm partition offset/size in partition_table/partitions_scummvm.csv, flash it standalone first with esptool to confirm it boots and runs before wiring up the MicroPythonOS side.

Stage 3 — Wire up the MicroPythonOS launcher (included here, verified)

apps/com.fri3d.scummvm_launcher/ is a direct adaptation of the real, shipped launcher apps (internal_filesystem/apps/com.micropythonos.retrocore_launcher/ and .../com.micropythonos.duke_launcher/ in MicroPythonOS/MicroPythonOS) — same flat app layout (MANIFEST.JSON + .py at the app root, no META-INF/assets wrapper), same from mpos import Activity, Intent API, and the exact same partition-boot-switch sequence those apps use:

from esp32 import Partition
parts = Partition.find(label="scummvm")
parts[0].set_boot()
import vfs; vfs.umount("/")
# ~1.5s grace period, then:
import machine; machine.reset()

This is not a guess — it's copied from working, shipped code, so esp32.Partition.find()/.set_boot() is confirmed to work on this exact badge build.

Copy the app folder onto the badge's app storage the same way you'd install any MicroPythonOS app (Fri3d-IDE's device file browser, or mpremote cp -r).

What's genuinely new/unverified here: the boot.cfg file the launcher writes to <sdcard>/scummvm/boot.cfg before switching partitions. Retro-Go has its own boot.json convention that the Retro-Go binary itself reads — ScummVM has no equivalent, so this is a convention you invent: your Stage 2 ESP-IDF backend needs to actually read boot.cfg on startup and use it to pick which game folder under /scummvm/games/ to launch. Change the format/path if you want something more elaborate.

Also note: after ScummVM boots, power-cycling returns you to whatever otadata currently points at (MicroPythonOS), not automatically back via a menu — add a "return to launcher" keybind in your ScummVM backend if you want a soft way back in-session.

Practical suggestion

Given the badge hardware is still listed as "Experimental Support (Hardware Prototype Phase)" for 2026, I'd do Stage 1–2 against the 2024 badge (fully supported, stable pinout) or the T-Deck first, and only port to 2026-specific pins once that hardware and its badge_2024_arduino-equivalent pin definitions are finalized — otherwise you're chasing a moving target.