Playdate SDK

https://sdk.play.date/
Admin
The Playdate SDK provides tools, libraries, and documentation for developing games for the Playdate...
Tokens:208,878
Snippets:1,029
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Send HTTP Requests (GET, POST, Query)

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Enables sending different types of HTTP requests. `get()` sends a GET request with specified path and headers. `post()` is a convenience function for sending POST requests. `query()` provides a general method for sending requests with custom methods, paths, headers, and bodies.

```C
PDNetErr playdate->network->http->get(HTTPConnection* conn, const char* path, const char* headers, size_t headerlen);
```

```C
PDNetErr playdate->network->http->post(HTTPConnection* conn, const char* path, const char* headers, size_t headerlen, const char* body, size_t bodylen);
```

```C
PDNetErr playdate->network->http->query(HTTPConnection* conn, const char* method, const char* path, const char* headers, size_t headerlen, const char* body, size_t bodylen);
```

--------------------------------

### Playdate C API Prerequisites and Setup

Source: https://sdk.play.date/inside-playdate-with-c

Details on the necessary software, compilers, and environment variable configurations required for developing C games with the Playdate SDK.

```APIDOC
## 2. Prerequisites

To compile C games for Playdate, you need:
*   The Playdate SDK.
*   A platform-native C compiler for the Simulator (e.g., Xcode, Visual Studio, Linux dev packages).
*   An ARM embedded compiler for the Playdate hardware:
    *   **macOS**: Installed via the Playdate SDK installer (`/usr/local/playdate`).
    *   **Linux**: Install the `arm-none-eabi-newlib` package.
    *   **Windows**: Download `gcc-arm-none-eabi` from developer.arm.com.

The SDK includes CMake and Make configuration files for example projects, which can serve as a starting point for your build environment. Note that C games built for the Simulator are platform-specific.

### 2.1. Set `PLAYDATE_SDK_PATH` Environment Variable

Setting the `PLAYDATE_SDK_PATH` environment variable is recommended on macOS and required on Linux and Windows for build systems (CMake/Make) to locate the SDK.

**macOS/Linux:**
Add the following line to your shell profile (`~/.zprofile` for zsh, `~/.bash_profile` for bash):

```zsh
export PLAYDATE_SDK_PATH=<path to SDK>
```

Replace `<path to SDK>` with the actual path to your Playdate SDK installation.

**Tip:** Adding `<path to SDK>/bin` to your shell's `$PATH` variable allows you to run SDK command-line tools like `pdc` and `pdutil` from any directory.

**Windows:**
Follow the instructions in the "Building on Windows" section of the SDK documentation to set this environment variable for CMake.
```

--------------------------------

### Example writeFunc for File Output (C)

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

An example implementation of a writeFunc that writes JSON data to a file using playdate->file->write. It takes a file pointer as userdata and writes the provided string and length to it.

```c
void writefile(void* userdata, const char* str, int len) {
	playdate->file->write((SDFile*)userdata, str, len);
}
```

--------------------------------

### SamplePlayer Callbacks and Volume

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Functions for setting and getting playback volume, and for setting a callback function to be executed upon sample completion.

```APIDOC
## SamplePlayer Callbacks and Volume

### Description
Functions to manage audio output volume for both channels and to register a callback function that is invoked when a sample finishes playing.

### Methods
- `playdate->sound->sampleplayer->setFinishCallback(SamplePlayer* player, sndCallbackProc callback, void* userdata)`: Sets a callback function to be called when playback completes.
- `playdate->sound->sampleplayer->setVolume(SamplePlayer* player, float left, float right)`: Sets the playback volume for the left and right channels.
- `playdate->sound->sampleplayer->getVolume(SamplePlayer* player, float* outleft, float* outright)`: Gets the current left and right channel volume.

### Parameters
#### `playdate->sound->sampleplayer->setFinishCallback(SamplePlayer* player, sndCallbackProc callback, void* userdata)`
* **player** (SamplePlayer*) - Required - The SamplePlayer.
* **callback** (sndCallbackProc) - Required - The function to call upon completion.
* **userdata** (void*) - Optional - User-defined data to pass to the callback.

#### `playdate->sound->sampleplayer->setVolume(SamplePlayer* player, float left, float right)`
* **player** (SamplePlayer*) - Required - The SamplePlayer.
* **left** (float) - Required - Volume for the left channel (0.0 to 1.0).
* **right** (float) - Required - Volume for the right channel (0.0 to 1.0).

#### `playdate->sound->sampleplayer->getVolume(SamplePlayer* player, float* outleft, float* outright)`
* **player** (SamplePlayer*) - Required - The SamplePlayer.
* **outleft** (float*) - Output - Pointer to store the left channel volume.
* **outright** (float*) - Output - Pointer to store the right channel volume.

### Response Example (setFinishCallback)
{
  "example": "playdate->sound->sampleplayer->setFinishCallback(myPlayer, myCallbackFunction, NULL);"
}

### Response Example (setVolume)
{
  "example": "playdate->sound->sampleplayer->setVolume(myPlayer, 1.0, 0.5); // Left channel full, right channel half"
}

### Response Example (getVolume)
{
  "example": "float leftVol, rightVol; playdate->sound->sampleplayer->getVolume(myPlayer, &leftVol, &rightVol);"
}
```

--------------------------------

### Set and Get SamplePlayer Offset

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Demonstrates setting and getting the current playback position (offset) of a SamplePlayer in seconds.

```c
playdate->sound->sampleplayer->setOffset(player, 5.0); // Set playback to start at 5 seconds
float currentOffset = playdate->sound->sampleplayer->getOffset(player);
```

--------------------------------

### Game Initialization and Event Handling

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Explains how the Playdate OS loads and executes games, focusing on the `pdex.bin` file and the `eventHandler` function for managing system events.

```APIDOC
## Game Initialization and Event Handling

### Description
When building for the device, a `pdex.bin` file is created. The game launcher looks for this file in the compiled `.pdx` bundle and loads it into memory. The system calls your `eventHandler()` function with `kEventInit` after loading `pdex.bin`. You can also handle other system events like initialization of Lua context, lock/unlock, pause/resume, termination, low power, and Mirror connection status through this handler.

### `eventHandler` Function Signature
```c
int eventHandler(PlaydateAPI* playdate, PDSystemEvent event, uint32_t arg);
```

### `PDSystemEvent` Enum
```c
typedef enum
{
	kEventInit,
	kEventInitLua,
	kEventLock,
	kEventUnlock,
	kEventPause,
	kEventResume,
	kEventTerminate,
	kEventKeyPressed,
	kEventKeyReleased,
	kEventLowPower,
	kEventMirrorStarted,
	kEventMirrorEnded
} PDSystemEvent;
```

### Key Event Handling Scenarios
- **`kEventInit`**: Called after `pdex.bin` is loaded. Use `playdate->system->setUpdateCallback()` to set a C update function.
- **`kEventInitLua`**: Called if no C update callback is set. Use `playdate->lua->addFunction()` and `playdate->lua->registerClass()` to extend the Lua runtime before `main.lua` is loaded.
- **`kEventKeyPressed` / `kEventKeyReleased`**: Called when a key is pressed or released in the Simulator, with the keycode provided in the `arg` parameter.
- **Lifetime Events**: Handles device lock/unlock, game pause/resume, termination, low-power sleep, and Mirror connection/disconnection.

### Windows Specific Note
On Windows, your event handler must be exported using the `__declspec(dllexport)` attribute.
```

--------------------------------

### Send HTTP GET Request (C)

Source: https://sdk.play.date/inside-playdate-with-c

Sends an HTTP GET request to the specified server. If the connection is not already open, it will be opened first. Additional headers can be provided.

```C
PDNetErr playdate->network->http->get(HTTPConnection* conn, const char* path, const char* headers, size_t headerlen);
```

--------------------------------

### Game Initialization and Event Handling

Source: https://sdk.play.date/inside-playdate-with-c

Explains the process of game initialization via pdex.bin and the role of the eventHandler function in responding to various system events.

```APIDOC
## Game Initialization and Event Handling

### Description
This section describes how the Playdate OS loads and initializes a game, focusing on the `pdex.bin` file and the `eventHandler` function.

### Core Function
```c
int eventHandler(PlaydateAPI* playdate, PDSystemEvent event, uint32_t arg);
```

### PDSystemEvent Enum
```c
typedef enum
{
	kEventInit,
	kEventInitLua,
	kEventLock,
	kEventUnlock,
	kEventPause,
	kEventResume,
	kEventTerminate,
	kEventKeyPressed,
	kEventKeyReleased,
	kEventLowPower,
	kEventMirrorStarted,
	kEventMirrorEnded
} PDSystemEvent;
```

### Usage
- The `eventHandler` is called with `kEventInit` after `pdex.bin` is loaded.
- If no update callback is set, `kEventInitLua` is called before `main.lua`.
- `kEventKeyPressed` and `kEventKeyReleased` provide keycode information.
- The function also handles lifetime events like lock, unlock, pause, resume, terminate, low-power, and Mirror connection/disconnection.
- **Note for Windows:** Export the event handler using `__declspec(dllexport)`.
```

--------------------------------

### Create and Load Audio Samples in Playdate SDK

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Demonstrates creating new audio samples, loading sound data from files, and retrieving sample data. Includes functions for allocating buffers, loading data into samples, and loading data directly into new samples.

```c
AudioSample* newSampleBuffer = playdate->sound->sample->newSampleBuffer(int length);
playdate->sound->sample->loadIntoSample(AudioSample* sample, const char* path);
AudioSample* loadedSample = playdate->sound->sample->load(const char* path);
```

--------------------------------

### Get Crank Position and Change (C)

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Functions to get the current angle of the crank and the change in angle since the last call. The angle is in degrees, with 0 pointing up and increasing clockwise.

```c
float playdate->system->getCrankAngle(void);
float playdate->system->getCrankChange(void);
```

--------------------------------

### Playdate C API Overview

Source: https://sdk.play.date/inside-playdate-with-c

Introduction to the Playdate C API, its advantages over Lua for performance-critical tasks, and when to consider using it.

```APIDOC
## 1. About the C API

Playdate’s C API allows the use of native C code within games, enabling the creation of both OS-specific libraries for the Simulator and binary files for the Playdate hardware. While most games utilize Playdate’s Lua API, the C API offers performance advantages, especially for computationally intensive tasks. Examples of C API usage can be found in the SDK at `C_API/Examples`.

### 1.1. Why use the C API?

Lua's garbage collector can introduce performance variability. The C API provides more predictable performance by allowing direct memory management and avoiding garbage collection overhead. This is particularly beneficial for games that are sensitive to frame-to-frame performance fluctuations.

### 1.2. Before porting to C

Before migrating Lua code to C, optimize existing Lua implementations. Strategies include flattening loops, localizing frequent global accesses, preloading assets, caching expensive computations and drawing routines, reusing tables, moving table allocations out of loops, and using `table.concat()` for string aggregation instead of excessive concatenation. Profiling on the actual hardware is crucial, as the Playdate Simulator may not accurately reflect performance on the device.

### 1.3. How to use the C API

The C API serves two primary purposes:
1. **Extending the Lua Runtime**: Add native functions to be called from Lua using `playdate->lua->addFunction()` and `playdate->lua->registerClass()`.
2. **Bypassing Lua**: Replace the Lua update callback with a native function using `playdate->system->setUpdateCallback()`, allowing the entire game logic to be implemented in C.
```

--------------------------------

### Reset and Get Elapsed Time

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Resets a high-resolution timer and provides a method to get the elapsed time in seconds with microsecond accuracy. This is useful for precise timing within a game loop.

```c
void playdate->system->resetElapsedTime(void)
float playdate->system->getElapsedTime()
```

--------------------------------

### Command Line: CMake for Simulator Build

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Builds a Playdate project for the simulator using CMake and Make on the command line. It creates a 'build' directory, navigates into it, and runs CMake followed by 'make'.

```bash
mkdir build
cd build
cmake ..
make
```

--------------------------------

### Configure LFO Delay and Retrigger (C)

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Sets an initial delay for the LFO before it starts modulating, along with a ramp time to reach its full depth. Also includes an option to retrigger the LFO's phase when a synth note starts.

```c
void playdate->sound->lfo->setDelay(PDSynthLFO* lfo, float holdoff, float ramptime);
void playdate->sound->lfo->setRetrigger(PDSynthLFO* lfo, int flag);
```

--------------------------------

### Build Playdate Game with Make

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Builds a Playdate game using the example Makefiles. Requires 'arm-none-eabi-newlib' and C dev packages. Produces a .pdx file for the device and Simulator.

```bash
cd <project folder>
make
```

--------------------------------

### Build Playdate Game for Simulator with CMake and NMake

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Builds a Playdate game for the Simulator using CMake and NMake. Requires Visual Studio Developer Command Prompt. Creates a .pdx file runnable in the Simulator.

```bash
cmake .. -G "NMake Makefiles"
nmake
```

--------------------------------

### Audio - Default Channel

Source: https://sdk.play.date/inside-playdate-with-c

Gets the default audio channel.

```APIDOC
## GET /audio/default_channel

### Description
Returns the default channel, where sound sources play if they haven’t been explicity assigned to a different channel.

### Method
GET

### Endpoint
`/audio/default_channel`

### Parameters
#### Query Parameters
None

#### Path Parameters
None

### Request Example
```
GET /audio/default_channel
```

### Response
#### Success Response (200)
- **channel** (SoundChannel*) - A pointer to the default SoundChannel object.

#### Response Example
```json
{
  "channel": "0x12345678"
}
```
```

--------------------------------

### Instrument Assignment

Source: https://sdk.play.date/inside-playdate-with-c

Functions to set and get the PDSynthInstrument associated with a SequenceTrack.

```APIDOC
## SequenceTrack setInstrument(SequenceTrack* track, PDSynthInstrument* instrument)

### Description
Assigns a PDSynthInstrument to the SequenceTrack.

### Method
`void`

### Endpoint
`playdate->sound->track->setInstrument(SequenceTrack* track, PDSynthInstrument* instrument)`

### Parameters
- **track** (SequenceTrack*) - Required - A pointer to the SequenceTrack.
- **instrument** (PDSynthInstrument*) - Required - A pointer to the PDSynthInstrument to assign.

### Response
None

## SequenceTrack getInstrument(SequenceTrack* track)

### Description
Retrieves the PDSynthInstrument currently assigned to the SequenceTrack.

### Method
`PDSynthInstrument*`

### Endpoint
`playdate->sound->track->getInstrument(SequenceTrack* track)`

### Parameters
- **track** (SequenceTrack*) - Required - A pointer to the SequenceTrack.

### Response
Returns a pointer to the assigned PDSynthInstrument.
```

--------------------------------

### Build Playdate Project with Make

Source: https://sdk.play.date/inside-playdate-with-c

Builds a Playdate game using Makefiles. Requires `arm-none-eabi-newlib` and C dev packages. Produces a .pdx file runnable on the device and Simulator.

```shell
cd <project folder>
make
```

```shell
cd <project folder>
make simulator
```

```shell
cd <project folder>
make device
```

--------------------------------

### Get All Overlapping Sprites

Source: https://sdk.play.date/inside-playdate-with-c

Retrieve an array of all sprites that are currently overlapping with any other sprite.

```APIDOC
## LCDSprite** allOverlappingSprites(int *len)

### Description
Returns an array of all sprites that have collide rects that are currently overlapping. Each consecutive pair of sprites is overlapping (eg. 0 & 1 overlap, 2 & 3 overlap, etc). _len_ is set to the size of the array. The caller is responsible for freeing the returned array.

### Method
GET

### Endpoint
/playdate/sprite/allOverlappingSprites

### Parameters
#### Query Parameters
- **len** (int*) - Output - Pointer to an integer that will be set to the size of the returned array.

### Response
#### Success Response (200)
- **LCDSprite*** - An array of LCDSprite pointers where each pair of consecutive sprites are overlapping.

#### Response Example
```json
{
  "allOverlappingSprites": [
    // Array of LCDSprite pointers, pairs overlap
  ]
}
```
```

--------------------------------

### Build Playdate Game for Device with CMake and NMake

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Builds a Playdate game for the device using CMake and NMake with the ARM toolchain. Requires Visual Studio Developer Command Prompt and the ARM toolchain. Creates a device binary within the .pdx.

```bash
cmake .. -G "NMake Makefiles" --toolchain=<path to SDK>/C_API/buildsupport/arm.cmake
nmake
```

--------------------------------

### Get Overlapping Sprites

Source: https://sdk.play.date/inside-playdate-with-c

Find all sprites that are currently overlapping with a given sprite.

```APIDOC
## LCDSprite** overlappingSprites(LCDSprite *sprite, int *len)

### Description
Returns an array of sprites that have collide rects that are currently overlapping the given _sprite_ ’s collide rect. _len_ is set to the size of the array. The caller is responsible for freeing the returned array.

### Method
GET

### Endpoint
/playdate/sprite/overlappingSprites

### Parameters
#### Query Parameters
- **sprite** (LCDSprite*) - Required - The sprite to check for overlaps.
- **len** (int*) - Output - Pointer to an integer that will be set to the size of the returned array.

### Response
#### Success Response (200)
- **LCDSprite*** - An array of LCDSprite pointers that are overlapping with the provided sprite.

#### Response Example
```json
{
  "overlappingSprites": [
    // Array of LCDSprite pointers
  ]
}
```
```

--------------------------------

### Create and Load Audio Samples

Source: https://sdk.play.date/inside-playdate-with-c

Functions for allocating new AudioSample objects and loading audio data from files. `newSampleBuffer` allocates space, `loadIntoSample` loads into an existing sample, and `load` allocates and loads from a file path, returning null if the file is not found.

```c
AudioSample* playdate->sound->sample->newSampleBuffer(int length);
void playdate->sound->sample->loadIntoSample(AudioSample* sample, const char* path);
AudioSample* playdate->sound->sample->load(const char* path);
```

--------------------------------

### Create and Free SamplePlayer

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Demonstrates how to allocate a new SamplePlayer and subsequently free it. This is essential for managing audio resources.

```c
SamplePlayer* player = playdate->sound->sampleplayer->newPlayer();
// ... use player ...
playdate->sound->sampleplayer->freePlayer(player);
```

--------------------------------

### SamplePlayer Volume Control

Source: https://sdk.play.date/inside-playdate-with-c

Functions for setting and getting the playback volume of a SamplePlayer.

```APIDOC
## POST /playdate/sound/sampleplayer/setVolume

### Description
Sets the playback volume for the left and right channels of the specified SamplePlayer.

### Method
POST

### Endpoint
/playdate/sound/sampleplayer/setVolume

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **player** (SamplePlayer*) - Required - The SamplePlayer to adjust.
- **left** (float) - Required - The volume for the left channel (0.0 to 1.0).
- **right** (float) - Required - The volume for the right channel (0.0 to 1.0).

### Request Example
```json
{
  "player": "0x7f9b3c8d4e6f",
  "left": 0.8,
  "right": 0.8
}
```

### Response
#### Success Response (200)
- **status** (int) - Indicates success (typically 1).

#### Response Example
```json
{
  "status": 1
}
```

## GET /playdate/sound/sampleplayer/getVolume

### Description
Gets the current left and right channel volume of the specified SamplePlayer.

### Method
GET

### Endpoint
/playdate/sound/sampleplayer/getVolume

### Parameters
#### Path Parameters
None

#### Query Parameters
- **player** (SamplePlayer*) - Required - The SamplePlayer to query.

### Request Example
```json
{
  "player": "0x7f9b3c8d4e6f"
}
```

### Response
#### Success Response (200)
- **outleft** (float*) - Pointer to store the left channel volume.
- **outright** (float*) - Pointer to store the right channel volume.

#### Response Example
```json
{
  "outleft": 0.8,
  "outright": 0.8
}
```
```

--------------------------------

### SoundChannel Volume Control

Source: https://sdk.play.date/inside-playdate-with-c

Functions for setting and getting the volume of a sound channel.

```APIDOC
## SoundChannel Volume Control

### Description
Allows control over the volume of a `SoundChannel`, including setting and retrieving the current volume and applying modulators.

### Functions

- **setVolume**
  - **Signature**: `void playdate->sound->channel->setVolume(SoundChannel* channel, float volume)`
  - **Parameters**:
    - `volume` (float) - The desired volume level, in the range [0.0 - 1.0].
  - **Description**: Sets the volume for the `SoundChannel`.

- **getVolume**
  - **Signature**: `float playdate->sound->channel->getVolume(SoundChannel* channel)`
  - **Returns**: The current volume of the `SoundChannel`, in the range [0.0 - 1.0].

- **setVolumeModulator**
  - **Signature**: `void playdate->sound->channel->setVolumeModulator(SoundChannel* channel, PDSynthSignalValue* mod)`
  - **Parameters**:
    - `mod` (PDSynthSignalValue*) - A signal to modulate the channel volume. Set to `NULL` to clear the modulator.
  - **Description**: Sets a signal to dynamically modulate the `SoundChannel`'s volume.

- **getVolumeModulator**
  - **Signature**: `PDSynthSignalValue* playdate->sound->channel->getVolumeModulator(SoundChannel* channel)`
  - **Returns**: A pointer to the `PDSynthSignalValue` modulating the volume, or `NULL` if none is set.

```

--------------------------------

### PDSynth Sample Playback

Source: https://sdk.play.date/inside-playdate-with-c

API for providing and configuring audio samples for playback with PDSynth.

```APIDOC
## PDSynth Sample Playback

### Description
Configure a PDSynth to play audio samples, including looping sustain sections.

### Set Sample

*   **Method:** `void`
*   **Endpoint:** `playdate->sound->synth->setSample(PDSynth* synth, AudioSample* sample, uint32_t sustainStart, uint32_t sustainEnd)`
*   **Description:** Provides an audio sample for the synth. Sample data must be uncompressed PCM. If `sustainStart` and `sustainEnd` are provided, the sample will loop during the sustain phase. If `sustainEnd` is 0 and `sustainStart` > 0, `sustainEnd` defaults to the sample length.

### Set Wavetable

*   **Method:** `int`
*   **Endpoint:** `playdate->sound->synth->setWavetable(PDSynth* synth, AudioSample* sample, int log2size, int columns, rows)`
*   **Description:** Sets a wavetable for the synth. Sample data must be 16-bit mono uncompressed. `log2size` is the base-2 logarithm of the number of samples per waveform cell. `columns` and `rows` define the grid dimensions of the wavetable. Returns 1 on success; use `playdate->sound->getError()` for errors.
```

--------------------------------

### Play, Stop, and Pause SamplePlayer

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Shows how to initiate playback of a sample with optional repeat and rate, stop playback, and pause/resume playback.

```c
playdate->sound->sampleplayer->play(player, 1, 1.0); // Play once at normal speed
// ... later ...
playdate->sound->sampleplayer->stop(player);
// ... or ...
playdate->sound->sampleplayer->setPaused(player, 1); // Pause playback
playdate->sound->sampleplayer->setPaused(player, 0); // Resume playback
```

--------------------------------

### Getting Values from Lua

Source: https://sdk.play.date/inside-playdate-with-c

Functions to retrieve arguments passed to a C function from Lua.

```APIDOC
## GET /lua/getArgType

### Description
Returns the type of the variable at stack position _pos_. If the type is _kTypeObject_ and _outClass_ is non-NULL, it returns the name of the object’s metatable.

### Method
GET

### Endpoint
/lua/getArgType

### Parameters
#### Query Parameters
- **pos** (int) - Required - The stack position of the argument.
- **outClass** (const char**) - Optional - Pointer to store the metatable name for kTypeObject.

### Response
#### Success Response (200)
- **LuaType** (enum) - The type of the argument.

### Response Example
```json
{
  "type": "kTypeString"
}
```

## GET /lua/getArgCount

### Description
Returns the number of arguments passed to the function.

### Method
GET

### Endpoint
/lua/getArgCount

### Response
#### Success Response (200)
- **int** - The number of arguments.

### Response Example
```json
{
  "count": 3
}
```

## GET /lua/argIsNil

### Description
Returns 1 if the argument at the given position _pos_ is nil.

### Method
GET

### Endpoint
/lua/argIsNil

### Parameters
#### Query Parameters
- **pos** (int) - Required - The stack position of the argument.

### Response
#### Success Response (200)
- **int** - 1 if the argument is nil, 0 otherwise.

### Response Example
```json
{
  "isNil": 1
}
```

## GET /lua/getArgBool

### Description
Returns one if the argument at position _pos_ is true, zero if not.

### Method
GET

### Endpoint
/lua/getArgBool

### Parameters
#### Query Parameters
- **pos** (int) - Required - The stack position of the argument.

### Response
#### Success Response (200)
- **int** - 1 if the boolean argument is true, 0 otherwise.

### Response Example
```json
{
  "value": 1
}
```

## GET /lua/getArgFloat

### Description
Returns the argument at position _pos_ as a float.

### Method
GET

### Endpoint
/lua/getArgFloat

### Parameters
#### Query Parameters
- **pos** (int) - Required - The stack position of the argument.

### Response
#### Success Response (200)
- **float** - The float value of the argument.

### Response Example
```json
{
  "value": 3.14
}
```

## GET /lua/getArgInt

### Description
Returns the argument at position _pos_ as an int.

### Method
GET

### Endpoint
/lua/getArgInt

### Parameters
#### Query Parameters
- **pos** (int) - Required - The stack position of the argument.

### Response
#### Success Response (200)
- **int** - The integer value of the argument.

### Response Example
```json
{
  "value": 42
}
```

## GET /lua/getArgString

### Description
Returns the argument at position _pos_ as a string.

### Method
GET

### Endpoint
/lua/getArgString

### Parameters
#### Query Parameters
- **pos** (int) - Required - The stack position of the argument.

### Response
#### Success Response (200)
- **const char*** - The string value of the argument.

### Response Example
```json
{
  "value": "hello world"
}
```

## GET /lua/getSprite

### Description
Returns the argument at position _pos_ as an LCDSprite.

### Method
GET

### Endpoint
/lua/getSprite

### Parameters
#### Query Parameters
- **pos** (int) - Required - The stack position of the argument.

### Response
#### Success Response (200)
- **LCDSprite*** - A pointer to the LCDSprite.

### Response Example
```json
{
  "spritePtr": "0x7ffc12345678"
}
```

## GET /lua/getArgBytes

### Description
Returns the argument at position _pos_ as a string and sets _outlen_ to its length.

### Method
GET

### Endpoint
/lua/getArgBytes

### Parameters
#### Query Parameters
- **pos** (int) - Required - The stack position of the argument.

### Response
#### Success Response (200)
- **const char*** - A pointer to the byte array.
- **size_t*** - The length of the byte array.

### Response Example
```json
{
  "bytes": "\x01\x02\x03",
  "length": 3
}
```

## GET /lua/getBitmap

### Description
Returns the argument at position _pos_ as an LCDBitmap.

### Method
GET

### Endpoint
/lua/getBitmap

### Parameters
#### Query Parameters
- **pos** (int) - Required - The stack position of the argument.

### Response
#### Success Response (200)
- **LCDBitmap*** - A pointer to the LCDBitmap.

### Response Example
```json
{
  "bitmapPtr": "0x7ffc87654321"
}
```
```

--------------------------------

### TCP Get Error

Source: https://sdk.play.date/inside-playdate-with-c

Retrieves the last error code associated with a TCP connection.

```APIDOC
## PDNetErr playdate->network->tcp->getError

### Description
Returns a code for the last error on the connection, or NET_OK if none occurred.

### Method
`PDNetErr`

### Parameters

#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
`PDNetErr`: The error code for the last operation on the connection.

#### Response Example
None
```

--------------------------------

### Build Playdate Project with NMake

Source: https://sdk.play.date/inside-playdate-with-c

Builds a Playdate project using NMake after CMake configuration. Generates a .pdx file for the Simulator.

```shell
nmake
```

--------------------------------

### Add SDK bin to PATH (Tip)

Source: https://sdk.play.date/inside-playdate-with-c

This tip suggests adding the Playdate SDK's 'bin' directory to your shell's PATH variable. This allows for easier execution of command-line tools like 'pdc' and 'pdutil' from any directory without specifying the full path.

```shell
export PATH="<path to SDK>/bin:$PATH"
```

--------------------------------

### SoundSource Volume Control

Source: https://sdk.play.date/inside-playdate-with-c

Functions for setting and getting the playback volume of a sound source.

```APIDOC
## SoundSource Volume Control

### Description
Allows granular control over the playback volume for both left and right channels of a `SoundSource`.

### Functions

- **setVolume**
  - **Signature**: `void playdate->sound->source->setVolume(SoundSource* c, float lvol, float rvol)`
  - **Parameters**:
    - `lvol` (float) - The desired volume for the left channel [0.0 - 1.0].
    - `rvol` (float) - The desired volume for the right channel [0.0 - 1.0].
  - **Description**: Sets the playback volume for the left and right channels of the `SoundSource`.

- **getVolume**
  - **Signature**: `void playdate->sound->source->getVolume(SoundSource* c, float* outlvol, float* outrvol)`
  - **Parameters**:
    - `outlvol` (float*) - Pointer to store the left channel volume.
    - `outrvol` (float*) - Pointer to store the right channel volume.
  - **Description**: Retrieves the current playback volume for the left and right channels of the `SoundSource`.

```

--------------------------------

### Build Playdate Project with CMake and Visual Studio

Source: https://sdk.play.date/inside-playdate-with-c

Builds a Playdate project using CMake and Visual Studio. Requires opening a Developer Command Prompt and running CMake commands to generate project files.

```shell
cmake ..

```

--------------------------------

### SoundChannel Panning Control

Source: https://sdk.play.date/inside-playdate-with-c

Functions for setting and getting the stereo panning of a sound channel.

```APIDOC
## SoundChannel Panning Control

### Description
Manages the stereo panning of a `SoundChannel`, allowing left/right balance adjustment and modulation.

### Functions

- **setPan**
  - **Signature**: `void playdate->sound->channel->setPan(SoundChannel* channel, float pan)`
  - **Parameters**:
    - `pan` (float) - The pan value, in the range [-1.0, 1.0], where -1 is full left, 0 is center, and 1 is full right.
  - **Description**: Sets the pan parameter for the `SoundChannel`.

- **setPanModulator**
  - **Signature**: `void playdate->sound->channel->setPanModulator(SoundChannel* channel, PDSynthSignalValue* mod)`
  - **Parameters**:
    - `mod` (PDSynthSignalValue*) - A signal to modulate the channel pan. Set to `NULL` to clear the modulator.
  - **Description**: Sets a signal to dynamically modulate the `SoundChannel`'s pan.

- **getPanModulator**
  - **Signature**: `PDSynthSignalValue* playdate->sound->channel->getPanModulator(SoundChannel* channel)`
  - **Returns**: A pointer to the `PDSynthSignalValue` modulating the pan, or `NULL` if none is set.

```

--------------------------------

### AudioSample API

Source: https://sdk.play.date/inside-playdate-with-c

Functions for creating, loading, and managing audio samples.

```APIDOC
## AudioSample Creation and Loading

### newSampleBuffer
Allocates and returns a new AudioSample with a buffer large enough to load a file of a specified length.

### Method
`AudioSample*`

### Endpoint
`playdate->sound->sample->newSampleBuffer(int length)`

### Parameters
#### Path Parameters
- `length` (int) - Required - The desired buffer length in bytes.

### loadIntoSample
Loads sound data from a file into an existing AudioSample.

### Method
`void`

### Endpoint
`playdate->sound->sample->loadIntoSample(AudioSample* sample, const char* path)`

### Parameters
#### Path Parameters
- `sample` (AudioSample*) - Required - A pointer to the AudioSample to load data into.
- `path` (const char*) - Required - The file path to the sound data.

### load
Allocates and returns a new AudioSample with sound data loaded from a file.

### Method
`AudioSample*`

### Endpoint
`playdate->sound->sample->load(const char* path)`

### Parameters
#### Path Parameters
- `path` (const char*) - Required - The file path to the sound data.

### newSampleFromData
Returns a new AudioSample referencing the given audio data.

### Method
`AudioSample*`

### Endpoint
`playdate->sound->sample->newSampleFromData(uint8_t* data, SoundFormat format, uint32_t sampleRate, int byteCount, int shouldFreeData)`

### Parameters
#### Path Parameters
- `data` (uint8_t*) - Required - Pointer to the audio data.
- `format` (SoundFormat) - Required - The format of the audio data (e.g., kSound8bitMono).
- `sampleRate` (uint32_t) - Required - The sample rate of the audio data.
- `byteCount` (int) - Required - The number of bytes in the audio data.
- `shouldFreeData` (int) - Required - Flag indicating if the data should be freed when the sample is freed.

### SoundFormat Enum
`kSound8bitMono`, `kSound8bitStereo`, `kSound16bitMono`, `kSound16bitStereo`, `kSoundADPCMMono`, `kSoundADPCMStereo`

### Helper Macros and Functions
`SoundFormatIsStereo(f)`, `SoundFormatIs16bit(f)`, `SoundFormat_bytesPerFrame(fmt)`
```

--------------------------------

### Get Battery Voltage

Source: https://sdk.play.date/inside-playdate-with-c

Returns the current voltage level of the device's battery.

```C
float playdate->system->getBatteryVoltage()
```

--------------------------------

### Restart and Get Launch Arguments (C)

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Restart the Playdate runtime with optional arguments and retrieve launch arguments passed at startup or after a restart. The `getLaunchArgs` function can also return the current game's path.

```C
playdate->system->restart("argument_string");

const char* launchArgs = playdate->system->getLaunchArgs(NULL);
// launchArgs contains "argument_string"
```

```C
const char* gamePath;
const char* args = playdate->system->getLaunchArgs(&gamePath);
// args contains launch arguments
// gamePath contains the path to the current game
```

--------------------------------

### Get Sprite Tag

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Retrieves the tag assigned to a sprite.

```c
uint8_t playdate->sprite->getTag(LCDSprite *sprite);
```

--------------------------------

### Volume Control

Source: https://sdk.play.date/inside-playdate-with-c

Set and get the playback volume for the synth's left and right channels.

```APIDOC
## void playdate->sound->synth->setVolume(PDSynth* synth, float lvol, float rvol)

### Description
Sets the playback volume (0.0 - 1.0) for the left and, if the synth is stereo, right channels of the synth. This is equivalent to `playdate->sound->source->setVolume((SoundSource*)synth, lvol, rvol)`.

### Method
`void`

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **synth** (PDSynth*) - The synth object.
- **lvol** (float) - The volume for the left channel (0.0 - 1.0).
- **rvol** (float) - The volume for the right channel (0.0 - 1.0).

### Request Example
```c
playdate->sound->synth->setVolume(mySynth, 0.7f, 0.7f);
```

### Response
None

---

## float playdate->sound->synth->getVolume(PDSynth* synth, float* outlvol, float* outrvol)

### Description
Gets the playback volume for the left and right (if stereo) channels of the synth. This is equivalent to `playdate->sound->source->getVolume((SoundSource*)synth, outlvol, outrvol)`.

### Method
`float` (returns 1 if stereo, 0 if mono)

### Endpoint
N/A (Function Call)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **synth** (PDSynth*) - The synth object.
- **outlvol** (float*) - Pointer to store the left channel volume.
- **outrvol** (float*) - Pointer to store the right channel volume.

### Request Example
```c
float isStereo;
float leftVol, rightVol;
isStereo = playdate->sound->synth->getVolume(mySynth, &leftVol, &rightVol);
```

### Response
#### Success Response (200)
- **isStereo** (float) - Returns 1 if the synth is stereo, 0 if mono.
- **leftVol** (float) - The volume of the left channel.
- **rightVol** (float) - The volume of the right channel.
```

--------------------------------

### System Settings

Source: https://sdk.play.date/inside-playdate-with-c

Retrieve global system settings for screen orientation and display flashing.

```APIDOC
## GET /system/settings

### Description
Retrieves the current status of global system settings.

### Method
GET

### Endpoint
/system/settings

### Parameters
#### Query Parameters
- **setting** (string) - Required - The name of the setting to retrieve. Accepted values: "flipped", "reduceFlashing".

### Response
#### Success Response (200)
- **value** (integer) - The status of the requested setting. 1 if set, 0 otherwise.

#### Response Example
```json
{
  "value": 1
}
```
```

--------------------------------

### SoundChannel Signal Levels

Source: https://sdk.play.date/inside-playdate-with-c

Functions to get signals representing the channel's volume before and after effects.

```APIDOC
## SoundChannel Signal Levels

### Description
Provides access to signals that track the channel's volume before and after audio effects are applied.

### Functions

- **getDryLevelSignal**
  - **Signature**: `PDSynthSignalValue* playdate->sound->channel->getDryLevelSignal(SoundChannel* channel)`
  - **Returns**: A `PDSynthSignalValue` representing the channel's volume before effects.

- **getWetLevelSignal**
  - **Signature**: `PDSynthSignalValue* playdate->sound->channel->getWetLevelSignal(SoundChannel* channel)`
  - **Returns**: A `PDSynthSignalValue` representing the channel's volume after effects.

```

--------------------------------

### Build Playdate Game for Simulator with CMake and Visual Studio

Source: https://sdk.play.date/2.7.6/Inside%20Playdate%20with%20C

Builds a Playdate game for the Simulator using CMake and Visual Studio. Requires Visual Studio (2019/2022) and CMake. Generates a .pdx file and starts a debugging session.

```bash
cmake ..
# Then open the generated Visual Studio project and build.
```
Tokens:
Raw