Help Setting Up the SDK on MacOS for a Complete Code Newbie

Hello all!

I recently got interested in learning to code small games for the Playdate. I have basically no code experience other than messing around in Godot for a couple of hours. The idea of not having an engine is foreign to me, but I'm up for the challenge and I'm a quick learner.

My problem is that I have no idea how to start. If there's a kind soul out there who could give me a hand in understanding the very basics, I'm sure I can improvise and learn from there.

My main problem at this point is I have downloaded the SDK file in order to begin coding, but in reality I don't even really know what an SDK is or how to make it interact with any code editor I download. I've also got VS Code downloaded (I know Nova exists, but I can't afford a license currently, so I want to just hurl myself in the deep end and learn without it), but every tutorial I've found is geared towards Windows, so there are steps that just don't work.

For reference, I'm running Ventura 13.0.1 on a MacBook.

So to summarize, my questions are:

  • Can someone just give me a quick rundown on what exactly the SDK is?

  • Does anyone have tips on how to get the SDK interacting with a code editor on Mac OS?

Apologies for my lack of knowledge, the first step is always the hardest and I look forward to being a valuable member of this community some day. A short lesson to stand me upright would go a long way towards getting me to walk.

Thanks all.

1 Like

Prerequisites for the SDK (Software Development Kit) are that you know either the Lua or C programming language. If you don't know either then easiest to learn is Lua, then come back to the SDK. But this will take a chunk of time.

If you want to jump in, read the beginning of Inside Playdate which talks you through getting things set up and running. After reading that you should have a simple SDK game running in the Simulator. Then try the incuded examples.

Alternatively, try Playdate Pulp. It's not the SDK but may well be more approachable for somebody who has not coded before.

1 Like

The SDK is a set of tools, documentation, code librairies, and examples. It also includes a simulator to help you test your games.

Everything is contained in a folder named "PlaydateSDK":

From there if you want to code in Lua, the main thing you have to do is it add the SDK folder to your IDE library path and you are good to go.

For example, in VSCode with Lua extension from sumneko. Set the path to the library in the settings:

Then you can fine-tune your IDE to have better feedback on your code. The Playdate Lua library uses a global variable named playdate and adds some non-standard functions to Lua.

And that's it. You can open the examples, build them with the compiler pdc (located in the bin/ folder) from the command line:

It will create a .pdx file that you can run by double clicking on it:

If you really are a complete code newbie, it may scare you a little. But when this is done, you will be able to focus on the code and learn Lua bit by bit.

And like @matt said, take a look at Inside Playdate. It explains a lot of things.

If you want to code in C, it is a bit more complicated but we can help!


Thanks so much for this! Two last questions, when I'm creating a folder in which to house the individual .lua files and assets, should I be copying the playdate SDK into it as well, or is setting it up once enough to have it referenced in subsequent projects? And could you elaborate for one second longer about the compiler pdc and how that works? I've got an example open in VS Code, but am unsure as to how and onto which .lua file I should be using the pdc command in order to properly compile and get a working demo.

You don't need to copy any file and setting your environment once is enough for subsequent projects.

In a normal project, you usually would have a Source folder containing at least a file named main.lua (see the "Level 1-1" example in the SDK). To create a .pdx from there, you have to use :

pdc Source NameOfYourGame.pdx

It is explained a bit better in the section 3.3. Compiling a project of "Inside Playdate".

In my previous post, I was using the -m flag that allows you to compile a project from a single Lua file (useful to compile the examples located in the "Single File Examples" folder).

1 Like

You rock. Thank you.

I apologize again for continuing to ask so many questions. I'm having real difficulty with the idea of compiling. I've followed your directions for adding the SDK folder to the IDE library path, but I'm completely lost after that. I've tried and failed to look for the "~/.zprofile" mentioned in the compiling section of the SDK documentation, as well as attempting to run the compiler with the -m command, the -m pdc command, and even the export_SDK_PATH mentioned in section 3.3, all to no avail.

Is there something else I have to set up before attempting to compile? And then after that, if everything has been set up correctly, typing "$ pdc MyGameSource MyGame.pdx" (Is the "MyGameSource" the filepath for where I want the .pdx file to end up? If not, is it literally just "MyGameSource" always?) in the terminal is what ultimately runs the compile function and creates the .pdx file that I can then open with the simulator application to run my file on the simulator?

I'm sorry again if these questions are stupid. I am slowly getting a grasp on the language itself, but have little to no understanding of the how to move what I could potentially put on the page into an actual file. It's like understanding how to spell and that words go on paper, but not understanding how to use a pencil to move the spelling onto the page.

You have multiple problems here.

The first command code ~/.zshrc is meant to open the file .zshrc located inside your home folder /Users/ocwri (~ is an alias of the home folder) with Visual Studio Code (= code).

It failed with the message command not found: code because ZSH (= your terminal) does not know where VSCode is located. You have to edit a variable named PATH to tell it where to look but a bit more friendly way you can do this is to open your home folder from Visual Studio Code directly and look for a file named .zshrc.

If the file .zshrc does not exists, you can create it from VS Code. You will have to make it executable with the command chmod u+x ~/.zshrc.

You should write the export command inside the file .zshrc. You have to remove the < and > characters. It is used to tell you "please replace this value by yours".

You have the same problem with pdc than you have with code. Your terminal does not know where it is located.
To fix this, you should add the following line inside .zshrc after export PLAYDATE_SDK_PATH:


The PATH variable list every folder where ZSH have to look to find commands (separated by :).

About the command $ pdc MyGameSource MyGame.pdx. The dollar sign is not something you have to write. It is a separator displayed in most terminal before the prompt. Your terminal is using % for the same thing (there is no difference, don't worry).

MyGameSource is the name of the folder containing main.lua. In your case, you are already inside the folder containing main.lua so you can use . (= current folder) instead. However I recommend that you create a folder named Source and move your main.lua inside it.

Edit: changes made to the .zshrc file are loaded when you start a new terminal or when you run it:

1 Like

You have been incredibly helpful thank you! I have successfully exported that file as a .pdx and it returned a value of 2. T

o anyone in the future that has stumbled across this exchange and is having the same problem I briefly did while following Daeke's explanation, when running a .pdx file to open it in the simulator, it only looks for the SDK folder in /users/ocwri/Developer. I had initially downloaded the SDK folder to my desktop, so an error popped up.

If you move the SDK folder to the Developer folder, then change the appropriate file paths in the Lua > Workspace: Library (Daeke's first reply) and in the export PLAYDATE_SDK_PATH=, it should work fine. At least it worked for me.

Thank you so much Daeke. I'm sure I'll have a thousand more questions down the road, but for this specific problem, you've been incredibly helpful in getting me to the starting line. Have a wonderful holiday!

1 Like