Playdate Simulator

The Playdate Simulator is an application that mimics the Playdate device, and makes Playdate development quick and easy on macOS, Windows, and Linux. The Simulator not only runs Playdate applications, but can also emulate the functionality of Playdate’s controls, including its crank and accelerometer.

Table of Contents

Controls

Games running in the simulator can be controlled by the on-screen GUI, or keyboard shortcuts. The simulator can also be controlled by a select number of compatible game controllers, or the Playdate console itself, if connected.

You can switch between several control schemes in the Controls menu. These will change which keyboard buttons control the d-pad and the A and B buttons.

You can also configure compatible game controllers in Preferences.

Crank and Accelerometer

The Simulator includes a GUI for approximating control of the device’s accelerometer and crank inputs.

Drag the controls to control these inputs. You can also control the crank using the keyboard, or by scrolling the scroll wheel on your mouse or other pointing device. Double-clicking the crank circle will let you turn it just by moving your mouse.

Games can tell whether the crank is docked or not; there is also a checkbox control to simulate this. You can enter the crank angle manually, or use the slider to set a constant rotation forward or backward.

Device menu

When you connect a Playdate to your computer, you can use a number of device features from the Simulator. Here’s you how access the device menu:

• Connect your Playdate to your computer via USB cable.
• Unlock your Playdate by pressing the Lock button on Playdate’s top edge.

Using your Playdate to control the Simulator

If you enjoy the rapid development the Playdate Simulator offers, while also wanting the tactile feel of Playdate controls, you can put your Playdate device into controller mode to control the Simulator with your Playdate hardware.

Choose the Device > Use Device as Controller option in the above menu. Your Playdate’s inputs will now control the Simulator.

On macOS, there is also a reverse option: Device > Control Device with Simulator. This may be useful when testing a feature that’s easier to control or reproduce with computer input.

Uploading games from the Simulator

Using this will upload the currently loaded .pdx to the device. It will overwrite the .pdx of the same name if it exists on the device.

On macOS, this will essentially merge the two bundles, so any files that were present in the old .pdx on the device will remain, and existing files will be overwritten with new ones.

This upload process may take some time with larger games.

Performance

Game performance is considerably faster in the Simulator than on the Playdate hardware. Please take that into consideration when developing your game, and make sure to periodically test on Playdate hardware.

You can learn a lot about your code’s performance by using the debugging features of the Simulator.

Throttling Lua performance

Appearance

Highlighting screen updates

A major way to improve the performance of your game is to not redraw the screen more than is needed. You can check how much of the screen is being redrawn in your game if you enable the Playdate > Highlight Screen Updates option:

This is particularly useful—and your code will likely run more efficiently—if you take advantage of our sprite system, which tracks which areas should be redrawn.

Showing sprite collision rects

Enabling the Playdate > Show Sprite Collision Rects option is a good way to debug your collisions.

Debug Drawing

If your code implements playdate.debugDraw, you can turn its display on and off in the Playdate menu on Windows and Linux.

Simulating device appearance

Enabling Playdate > Simulate Device Appearance will do the following:

• The Simulator window will become yellow, to match the color of the Playdate hardware.
• The display will use two gray colors instead of pure black and pure white, to match the Memory LCD display on the hardware
• Screenshots and GIFs you save will use these gray colors as well.

Saving screenshots and GIFs

With your game running or paused, you can take a screenshot of it by using the “photo camera” button in the toolbar. You’ll be presented with a dialog to save this as a PNG image. Holding down the Option/Alt button while clicking the Screenshot button will copy the image to your clipboard instead of saving a file.

While your game is running, click the “video camera” button in the toolbar to begin recording a GIF animation of the display.

Note: Screenshots and GIFs will use simulated device appearance (gray colors) if this function is enabled.

Note: GIFs won’t record your game’s sound. If you’d like to capture a video with sound, you can use our Mirror app, or a screen-recording app.

Note: Overlays such as screen-update highlights, collision rects, and debug draws won’t be saved with your screenshots and GIFs. Game recordings will be saved as they would appear to players.

Debugging

The Playdate Simulator includes a number of tools for measuring, inspecting, and debugging your running code. These are separate windows, available from the Window menu and the toolbar.

• Lua Memory. Shows all the Lua objects taking up your game’s memory. Note: this tool is available only while your game is paused.
• Malloc Log. Shows the memory usage by your C code.
• Device Info. When a Playdate is connected to your computer, this tools shows a variety of graphs outlining its performance and memory usage.
• Console. Displays logs printed from your code, and lets you enter commands to evaluate in real time.
• Sampler. Lets you sample a running game to see where your code is spending most of its time.

Debug adapter protocol

The Playdate Simulator supports the debug adapter protocol, which makes it possible to debug execution line by line from your code editor, such as Nova.

Keyboard shortcuts