readme.md

Unofficial Playdate reverse-engineering notes/tools - covers file formats, server API and USB serial commands

⚠️ This documentation is unofficial and is not affiliated with Panic. All of the content herein was gleaned from reverse-engineering Playdate tools and game files, and as such there may be mistakes or missing information.

Documentation

• File Formats
  • Playdate game formats
    • pdex.bin - Executable code
    • .luac - Lua bytecode
    • .pdz - File container
    • .pda - Audio file
    • .pdi - Image file
    • .pdt - Imagetable file
    • .pdv - Video file
    • .pds - Strings file
    • .pft - Font file
  • Other formats
    • .fnt - Font source file
    • .strings - Strings source file (TODO)
• Server
  • Playdate API - Main Playdate server API
• Misc
  • USB - USB serial interface
  • Streaming - Video/audio streaming protocol (via USB serial), used by Playdate Mirror

Tools

• pdz.py - Unpacks all files from a .pdz file container.
• pdex2elf.py - Converts a pdex.bin to an ELF file that can be analyzed in tools such as readelf, objdump or Ghidra, or compiled back to the same original pdex.bin by pdc.
• usbeval.py - Uses the Playdate's USB eval command to evaluate a Lua script over USB. Has access to the Lua runtime of the currently loaded game, except for system apps.

Related Projects and Resources

• pd-usb - JavaScript library for interacting with the Playdate's serial API from a WebUSB-compatible web browser.
• unluac - Fork of the unluac Lua decompiler, modified to support Playdate-flavoured Lua.
• lua54 - Fork of Lua that aims to match the custom tweaks that Panic added for Playdate-flavoured Lua.

Special Thanks

• Zhuowei for this script for unpacking Playdate .pdx executables, which was the base for pdz.py
• Scratchminer for their further reverse-engineering work on the Playdate's file formats, streaming protocol and Lua implementation.
• Simon for helping with some ADPCM audio data reverse engineering
• The folks at Panic for making such a wonderful and fascinating handheld!

---

2022-2023 James Daniel

Playdate is © Panic Inc. - this project isn't affiliated with or endorsed by them in any way.