Cranked - A very early Playdate emulator that can load and run native or Lua programs

I've been working on this project for a couple months and finally got it to a state where all of the API functions are mapped/stubbed out and it can run basic graphical programs. A large amount of functionality isn't present at all yet such as sprites and audio, but most of the underlying structure has been created.

It loads Playdate hardware compatible PDX directories, whether developed using the Lua API or the C API, and executes them as if on actual hardware. A virtual address space was created to mimic the physical device memory and facilitate interfacing with the runtime implementation using the help of a sketchy C++ template based translation layer that automatically converts between emulated Arm, native C++, and Lua data types.

A large amount of reverse engineering and testing was needed to replicate the exact behavior of the API functions, due to discrepancies, bugs, and missing details in the otherwise quite thorough documentation, but only a small percentage of the entire API surface has actually been tested, so a testing suite that covers every edge case is needed. There are countless tiny differences in behavior already, with regards to how Lua objects are represented and how native resources are managed, so plenty of room for subtle issues like the line drawing routine being different by a few pixels. In the parts of the API that haven't yet been implemented, the functions generally return null, typically causing an emulated seg-fault in C programs and a null reference error in Lua programs. Suffice to say, it's not ready for running actual games yet, but is a good amount of the way towards it.

The current main issues concern memory/resource ownership with the various APIs and how they behave over the Lua/C boundary, since dangling pointers are inevitable if the ownership isn't properly established. The large amount of audio and graphical effects to implement with few technical details is also a challenge to overcome.

Project GitHub repository


This looks like a very worthwhile endeavour.

Is the goal for it to run at device speed?

That's definitely the goal. Lua speed should be way faster, and the emulated native code should hopefully be comparable, but there's still room for performance gains using JIT and such if needed. The runtime is written in C++, but there are plenty of optimizations that could be made such as in the graphics drawing routines.

I can see a lot of potential for Playdate ports on other systems like the Nintendo Switch and PC.
Since its open sourced, it even allows developers a choice to broaden their game on other platforms.
I can see a lot of awesome things coming from this.

Yep, it's written in a pretty portable way, so different ports should hopefully be simple. Currently targeting a libretro core and a standard desktop executable, but homebrew frontends are also planned.


Hey @TheLogicMaster any updates on this? I was just thinking about it.

1 Like

Missed this message. Progress has been made in the backend, but API support is still roughly the same. Next thing would probably be sprites, but the memory model still isn't entirely clear to me as far as how ownership works for Lua/native shared resources so I've been putting it off. I've considered just reference counting everything, but that may not be accurate.

1 Like