Playdate SDK

https://sdk.play.date/3.0.3/
Admin
The Playdate SDK provides software tools, libraries, and documentation for developing games in Lua...
Tokens:225,048
Snippets:1,826
Trust Score:10
Update:8 months ago
Show doc for...
Tokens:
Raw
### Example Write Function for File Output (C)

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

Provides an example implementation of a write function that writes JSON string data to a Playdate file using `playdate->file->write()`. This demonstrates how to integrate the JSON encoder with file I/O operations.

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

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

### Lua Table Utility Functions from Playdate SDK

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Shows examples of using convenience functions for Lua tables provided by the Playdate SDK, including finding an element's index, getting table size, creating preallocated tables, and performing shallow and deep copies.

```lua
local myArray = {'a', 'b', 'c'}
local index = table.indexOfElement(myArray, 'b') -- index is 2

local arrCount, hashCount = table.getsize(myArray) -- arrCount is 3, hashCount is 0

local newTable = table.create(10, 5) -- Creates a table with preallocated space

local original = { a = 1, b = { c = 3 } }
local shallowCopy = table.shallowcopy(original)
local deepCopy = table.deepcopy(original)

shallowCopy.b.c = 4 -- This will also change original.b.c
deepCopy.b.c = 5 -- This will NOT change original.b.c
```

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

### Send HTTP GET Request

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

Initiates an HTTP GET request to the specified server. If the connection is not already open, it will be established. Additional headers can be provided as a null-terminated string.

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

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

### SamplePlayer: Set Playback Offset

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

Sets the starting position for audio playback in seconds. Useful for resuming playback or starting at a specific point.

```c
void playdate->sound->sampleplayer->setOffset(SamplePlayer* player, float offset)
```

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

### SamplePlayer: Play Audio

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

Starts playback of the audio sample assigned to the SamplePlayer. Supports looping, playback rate, and returns success status.

```c
int playdate->sound->sampleplayer->play(SamplePlayer* player, int repeat, float rate)
```

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

### Accelerometer Ball Rolling Demo - Playdate SDK

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

A complete example demonstrating how to use the accelerometer to control a ball's movement on the screen. It includes starting the accelerometer, reading values, and updating the ball's position within the game loop.

```lua
import "CoreLibs/graphics"

local function clamp(value, min, max)
    return math.max(math.min(value, max), min)
end

local x, y = 200, 120
-- Make sure to start the accelerometer to begin reading!
playdate.startAccelerometer()

-- A simple example of rolling around a ball on the screen using the accelerometer
function playdate.update()
    playdate.graphics.clear()

    -- We can get the accelerometer values by storing them in multiple variables
    local gravityX, gravityY, _gravityZ = playdate.readAccelerometer()

    -- Try orienting the Playdate flat and tilting it around
    x = clamp(x + gravityX * 10, 0, 400)
    y = clamp(y + gravityY * 10, 0, 240)
    playdate.graphics.fillCircleAtPoint(x, y, 10)
end

```

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

### Create and Load Audio Samples (C)

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

Functions for creating new audio samples, either by allocating a buffer of a specific size, loading from a file path, or creating from raw data. The `load` function returns null if the file is not found.

```c
AudioSample* playdate->sound->sample->newSampleBuffer(int length);
AudioSample* playdate->sound->sample->load(const char* path);
AudioSample* playdate->sound->sample->newSampleFromData(uint8_t* data, SoundFormat format, uint32_t sampleRate, int byteCount, int shouldFreeData);
```

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

### Building for Simulator with NMake

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

Instructions for building a project for the Playdate simulator using NMake and CMake.

```APIDOC
## Building for the Simulator using NMake

### Description
Build your project for the Playdate simulator using NMake. This process involves generating project files with CMake and then using NMake to compile the code.

### Steps
1. Navigate into the project directory and create a `build` folder.
2. Open a Visual Studio Developer Command Prompt.
3. In the developer command prompt, navigate into the `build` directory and run: `cmake .. -G "NMake Makefiles"`
4. Run `nmake` to build the project. This will generate a `.pdx` file in the project root.
```

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

### Restart and Get Launch Arguments (Playdate C)

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

Restarts the Playdate runtime and the current game, optionally with arguments. `getLaunchArgs` retrieves the string passed during launch or restart. It can also return the path of the currently loaded game via an output parameter. These are crucial for game state persistence and command-line interaction.

```c
playdate->system->restart("startGameLevel2");

const char* launchArgs;
const char* gamePath;
playdate->system->getLaunchArgs(&launchArgs, &gamePath);
// launchArgs might be "startGameLevel2"
```

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

### Building for Playdate Device with NMake

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

Instructions for building a project for the Playdate device using NMake, including toolchain configuration.

```APIDOC
## Building for the Playdate using NMake

### Description
Build your project for the Playdate device using NMake. This requires specifying the ARM toolchain for compilation.

### Steps
1. Navigate into the project directory and create a `build` folder.
2. Open a Visual Studio Developer Command Prompt.
3. In the developer command prompt, navigate into the `build` directory and run: `cmake .. -G "NMake Makefiles" --toolchain=<path to SDK>/C_API/buildsupport/arm.cmake`
4. Run `nmake` to build the project. This will create a device binary and copy it into the `.pdx` bundle.
```

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

### Get Battery Information

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Provides functions to get the current battery charge percentage and voltage level. The percentage ranges from 0 (empty) to 100 (full).

```lua
local percentage = playdate.getBatteryPercentage()
print("Battery Level: " .. percentage .. "%")

local voltage = playdate.getBatteryVoltage()
print("Battery Voltage: " .. voltage .. "V")
```

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

### Basic Playdate Game Setup and Update Loop in Lua

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

This Lua code snippet demonstrates the fundamental structure of a Playdate game. It includes setting up the graphics environment, creating and positioning a player sprite, displaying a background image, and handling d-pad input within the main update loop. It relies on Playdate's CoreLibs for graphics and sprites.

```lua
-- Name this file `main.lua`. Your game can use multiple source files if you wish
-- (use the `import "myFilename"` command), but the simplest games can be written
-- with just `main.lua`.

-- You'll want to import these in just about every project you'll work on.

import "CoreLibs/object"
import "CoreLibs/graphics"
import "CoreLibs/sprites"
import "CoreLibs/timer"

-- Declaring this "gfx" shorthand will make your life easier. Instead of having
-- to preface all graphics calls with "playdate.graphics", just use "gfx."
-- Performance will be slightly enhanced, too.
-- NOTE: Because it's local, you'll have to do it in every .lua source file.

local gfx <const> = playdate.graphics

-- Here's our player sprite declaration. We'll scope it to this file because
-- several functions need to access it.

local playerSprite = nil

-- A function to set up our game environment.

function myGameSetUp()

    -- Set up the player sprite.

    local playerImage = gfx.image.new("Images/playerImage")
    assert( playerImage ) -- make sure the image was where we thought

    playerSprite = gfx.sprite.new( playerImage )
    playerSprite:moveTo( 200, 120 ) -- this is where the center of the sprite is placed; (200,120) is the center of the Playdate screen
    playerSprite:add() -- This is critical!

    -- We want an environment displayed behind our sprite.
    -- There are generally two ways to do this:
    -- 1) Use setBackgroundDrawingCallback() to draw a background image. (This is what we're doing below.)
    -- 2) Use a tilemap, assign it to a sprite with sprite:setTilemap(tilemap),
    --       and call :setZIndex() with some low number so the background stays behind
    --       your other sprites.

    local backgroundImage = gfx.image.new( "Images/background" )
    assert( backgroundImage )

    gfx.sprite.setBackgroundDrawingCallback(
        function( x, y, width, height )
            -- x,y,width,height is the updated area in sprite-local coordinates
            -- The clip rect is already set to this area, so we don't need to set it ourselves
            backgroundImage:draw( 0, 0 )
        end
    )

end

-- Now we'll call the function above to configure our game.
-- After this runs (it just runs once), nearly everything will be
-- controlled by the OS calling `playdate.update()` 30 times a second.

myGameSetUp()

-- `playdate.update()` is the heart of every Playdate game.
-- This function is called right before every frame is drawn onscreen.
-- Use this function to poll input, run game logic, and move sprites.

function playdate.update()

    -- Poll the d-pad and move our player accordingly.
    -- (There are multiple ways to read the d-pad; this is the simplest.)
    -- Note that it is possible for more than one of these directions
    -- to be pressed at once, if the user is pressing diagonally.

    if playdate.buttonIsPressed( playdate.kButtonUp ) then
        playerSprite:moveBy( 0, -2 )
    end
    if playdate.buttonIsPressed( playdate.kButtonRight ) then
        playerSprite:moveBy( 2, 0 )
    end
    if playdate.buttonIsPressed( playdate.kButtonDown ) then
        playerSprite:moveBy( 0, 2 )
    end
    if playdate.buttonIsPressed( playdate.kButtonLeft ) then
        playerSprite:moveBy( -2, 0 )
    end

    -- Call the functions below in playdate.update() to draw sprites and keep
    -- timers updated. (We aren't using timers in this example, but in most
    -- average-complexity games, you will.)

    gfx.sprite.update()
    playdate.timer.updateTimers()

end

```

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

### SamplePlayer Initialization

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Creates a new SamplePlayer object, loading audio data into memory.

```APIDOC
## SamplePlayer Initialization

### Description
Creates a new `playdate.sound.sampleplayer` object, loading the specified sound data into memory. If the sample cannot be loaded, the function returns `nil` and an error message.

### Methods
- `playdate.sound.sampleplayer.new(path)`
- `playdate.sound.sampleplayer.new(sample)`

### Parameters
#### `playdate.sound.sampleplayer.new(path)`
- **path** (string) - Required - The file path to the audio sample.

#### `playdate.sound.sampleplayer.new(sample)`
- **sample** (object) - Required - A sample object to play.

### Response
#### Success Response
- Returns a new `playdate.sound.sampleplayer` object.

#### Error Response
- Returns `nil` and an error message if the sample cannot be loaded.
```

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

### Create a New Frame Timer

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Creates a new frame timer that runs for a specified duration. Optionally accepts start value, end value, and an easing function. Timers start automatically upon instantiation.

```lua
t = playdate.frameTimer.new(duration, [startValue, endValue, [easingFunction]])
```

```lua
t = playdate.frameTimer.new(200)
```

```lua
t = FrameTimer(50, 0, 100)
```

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

### Manage Synth Parameters and Modulators

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

Allows interaction with synth-specific parameters. You can get the total number of parameters, set a parameter's value, and set or get modulators for individual parameters. Parameter indices are 1-based.

```c
int playdate->sound->synth->getParameterCount(PDSynth* synth);
int playdate->sound->synth->setParameter(PDSynth* synth, int num, float value);
void playdate->sound->synth->setParameterModulator(PDSynth* synth, int num, PDSynthSignalValue* mod);
PDSynthSignalValue* playdate->sound->synth->getParameterModulator(PDSynth* synth, int num);
```

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

### Command Line Make Build for Playdate SDK

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

Build Playdate games using Makefiles. This snippet shows the basic command to initiate a build, which produces a .pdx file suitable for both the simulator and the device. Specific targets like 'simulator' or 'device' can be specified for platform-specific builds.

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

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

### Sample Key Repeat Timer Callback in Playdate

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

This Lua example demonstrates how to set up and manage a key repeat timer. It shows how to define a callback function, initiate the timer on a button press, remove it on button release, and ensure timers are updated each frame.

```lua
import "CoreLibs/timer"

local keyTimer = nil

function playdate.BButtonDown()
    local function timerCallback()
        print("key repeat timer fired!")
    end
    keyTimer = playdate.timer.keyRepeatTimer(timerCallback)
end

function playdate.BButtonUp()
    keyTimer:remove()
end

function playdate.update()
    playdate.timer.updateTimers()
end
```

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

### Get System Playdate Font

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Retrieves the system font, similar to `getFont()`, but always returns the system's default font rather than the currently set custom font. Variants can be specified to get specific system font styles.

```lua
local systemNormalFont = playdate.graphics.getSystemFont(playdate.graphics.font.kVariantNormal)
local systemBoldFont = playdate.graphics.getSystemFont("bold")
```

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

### Sprite Z-Index

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Methods for setting and getting the Z-index of a sprite.

```APIDOC
## Sprite Z-Index

### Description
Methods for setting and getting the Z-index of a sprite.

### `playdate.graphics.sprite:setZIndex(z)`

#### Method
Instance Method

#### Description
Sets the Z-index of the given sprite. Sprites with higher Z-indexes are drawn on top of those with lower Z-indexes. Valid values for `z` are in the range (-32768, 32767).

### `playdate.graphics.sprite:getZIndex()`

#### Method
Instance Method

#### Description
Returns the Z-index of the given sprite.
```

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

### SamplePlayer: Create New Instance

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

Allocates and initializes a new SamplePlayer object. This is the first step in using the SamplePlayer API for audio playback.

```c
SamplePlayer* playdate->sound->sampleplayer->newPlayer(void)
```

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

### Compiling a Playdate Project with pdc

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Demonstrates the basic usage of the `pdc` (Playdate Compiler) command-line tool. It requires the source directory and an output directory (typically ending in `.pdx`). The `-s` option can be used to strip debugging information.

```bash
$ pdc MyGameSource MyGame.pdx
$ pdc -s MyGameSource MyGame.pdx
```

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

### AudioSample Properties

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

Functions to get information about an AudioSample, such as its duration.

```APIDOC
## Getting AudioSample Length

### Description
Returns the duration of the audio sample in seconds.

### Method
`float playdate->sound->sample->getLength(AudioSample* sample)`

### Parameters
- **sample** (AudioSample*) - Required - The AudioSample to query.

### Response
- Returns the length of the sample in seconds (float).

### Example
```c
float duration = playdate->sound->sample->getLength(mySample);
```
```

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

### JSON Reader Implementation Example (C)

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

The `json_reader` struct provides a mechanism for the JSON decoder to read data. The `read` function pointer should be implemented to supply data from a source, such as a file. The example shows a `readfile` function that uses `playdate->file->read` to fill a buffer from an `SDFile`.

```c
typedef struct
{
	int (*read)(void* readud, uint8_t* buf, int bufsize); // fill buffer, return bytes written or 0 on end of data
	void* userdata;
} json_reader;

int readfile(void* readud, uint8_t* buf, int bufsize) {
	return playdate->file->read((SDFile*)readud, buf, bufsize);
}

// Usage example:
// SDFile* file = pd->file->open("data.json", kFileRead);
// pd->json->decode(&decoder, (json_reader){ .read = readfile, .userdata = file }, NULL);
```

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

### Create Sound Source with Callback (C)

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

Creates a `SoundSource` that uses a provided callback function to generate audio data. The callback receives audio buffers and length, and should return 1 if audio was generated, or 0 if silent. The caller is responsible for freeing the `SoundSource`.

```c
int myAudioCallback(void* context, int16_t* left, int16_t* right, int len) {
    // Fill left and right buffers with audio data
    // Return 1 if audio generated, 0 if silent
    return 1;
}

SoundChannel* channel = playdate->sound->channel->newChannel();
SoundSource* source = playdate->sound->channel->addCallbackSource(channel, myAudioCallback, NULL, 1); // 1 for stereo

// When done with the source:
// playdate->system->realloc(source, 0);
```

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

### Build for Device with NMake and ARM Toolchain

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

Builds the Playdate project for the physical device using NMake and the ARM toolchain. This generates a device binary file that is copied into the .pdx bundle.

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

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

### SamplePlayer Sample Management

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Sets or gets the audio sample data for a SamplePlayer.

```APIDOC
## SamplePlayer Sample Management

### Description
Allows changing the audio sample associated with a `SamplePlayer` instance or retrieving the currently assigned sample.

### Methods
- `playdate.sound.sampleplayer:setSample(sample)`
- `playdate.sound.sampleplayer:getSample()`

### Parameters
#### `playdate.sound.sampleplayer:setSample(sample)`
- **sample** (object) - Required - The new audio sample object to set.

### Response
#### `playdate.sound.sampleplayer:setSample()`
- No explicit return value.

#### `playdate.sound.sampleplayer:getSample()`
- Returns the currently assigned audio sample object.
```

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

### Sprite Bounds Getting

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Methods for retrieving the bounding box information of a sprite.

```APIDOC
## GET playdate.graphics.sprite:getBounds()

### Description
Returns the current bounds of the sprite as individual values: x, y, width, and height.

### Method
GET

### Endpoint
playdate.graphics.sprite:getBounds

### Parameters
None

### Response
#### Success Response (200)
- **x** (number) - The x-coordinate of the upper-left corner.
- **y** (number) - The y-coordinate of the upper-left corner.
- **width** (number) - The width of the bounds.
- **height** (number) - The height of the bounds.

#### Response Example
```json
{
  "x": 10,
  "y": 20,
  "width": 50,
  "height": 60
}
```

## GET playdate.graphics.sprite:getBoundsRect()

### Description
Returns the sprite's bounds as a `playdate.geometry.rect` object.

### Method
GET

### Endpoint
playdate.graphics.sprite:getBoundsRect

### Parameters
None

### Response
#### Success Response (200)
- **boundsRect** (object) - A `playdate.geometry.rect` object representing the sprite's bounds.

#### Response Example
```json
{
  "boundsRect": {"x": 10, "y": 20, "width": 50, "height": 60}
}
```
```

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

### Build for Playdate Device with CMake (C)

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

Commands to configure and build a C project for the Playdate device using CMake. This involves specifying the toolchain file for ARM compilation and then running 'make'. The output is a device binary file added to the .pdx folder.

```bash
cd build
cmake -DCMAKE_TOOLCHAIN_FILE=<path to SDK>/C_API/buildsupport/arm.cmake ..
make
```

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

### Build for Simulator with NMake

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

Builds the Playdate project for the simulator using NMake. This process involves generating Makefiles with CMake and then executing nmake to create a .pdx file.

```bash
mkdir build
cd build
cmake .. -G "NMake Makefiles"
nmake
```

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

### Sprite Image Manipulation

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Methods for setting and getting the image associated with a sprite.

```APIDOC
## Sprite Image Manipulation

### Description
Methods for setting and getting the image associated with a sprite.

### `playdate.graphics.sprite:setImage(image, [flip, [scale, [yscale]]])`

#### Method
Instance Method

#### Description
Sets the sprite’s image to `image`, which should be an instance of `playdate.graphics.image`. The `flip_` argument is optional; see `playdate.graphics.image:draw()` for valid values. Optional scale arguments are also accepted. Unless disabled with `playdate.graphics.sprite:setRedrawOnImageChange()`, the sprite is automatically marked for redraw if the image isn’t the previous image.

### `playdate.graphics.sprite:getImage()`

#### Method
Instance Method

#### Description
Returns the `playdate.graphics.image` object that was set with `setImage()`.
```

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

### SamplePlayer Playback Control

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Controls the playback of a SamplePlayer, including starting, scheduling, and stopping.

```APIDOC
## SamplePlayer Playback Control

### Description
Manages the playback of audio samples using the `SamplePlayer` class. This includes starting playback immediately, scheduling playback for a future time, and stopping playback.

### Methods
- `playdate.sound.sampleplayer:play([repeatCount], [rate])`
- `playdate.sound.sampleplayer:playAt(when, [vol], [rightvol], [rate])`
- `playdate.sound.sampleplayer:stop()`

### Parameters
#### `playdate.sound.sampleplayer:play([repeatCount], [rate])`
- **repeatCount** (number) - Optional - The number of times to loop the sample. If 0, it loops indefinitely. Defaults to 1 (plays once).
- **rate** (number) - Optional - The playback rate. Defaults to the rate set by `setRate()`.

#### `playdate.sound.sampleplayer:playAt(when, [vol], [rightvol], [rate])`
- **when** (number) - Required - The device time at which to play the sound. This is an offset in the audio device's time scale.
- **vol** (number) - Optional - The volume for the left channel (0.0 - 1.0).
- **rightvol** (number) - Optional - The volume for the right channel (0.0 - 1.0). If omitted, it defaults to the `vol` value.
- **rate** (number) - Optional - The playback rate. Defaults to the rate set by `setRate()`.

### Response
#### `playdate.sound.sampleplayer:play()`
- No explicit return value, but playback begins.

#### `playdate.sound.sampleplayer:playAt()`
- Returns `true` if the sound was successfully queued, `false` otherwise (e.g., if the channel is full).

#### `playdate.sound.sampleplayer:stop()`
- No explicit return value, but playback stops.

### Notes
- `playAt()` can only queue one event at a time. Subsequent calls will overwrite the previous event.
- If `when` is less than the current audio time, the sample plays immediately.
```

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

### Play Audio with Fileplayer

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Starts playback of the loaded audio file. If a buffer size hasn't been set, a default 1/4 second buffer is created. Playback can be set to repeat a specified number of times, with 0 indicating infinite looping. The function returns true on success, and false with an error message otherwise.

```lua
fp:play()
-- Play once and repeat 3 times
fp:play( 3 )
-- Loop indefinitely
fp:play( 0 )
```

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

### SamplePlayer Offset Control

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Sets or gets the current playback offset within the sample.

```APIDOC
## SamplePlayer Offset Control

### Description
Manages the current playback position within the sample, specified in seconds. This offset is not affected by the playback rate.

### Methods
- `playdate.sound.sampleplayer:setOffset(seconds)`
- `playdate.sound.sampleplayer:getOffset()`

### Parameters
#### `playdate.sound.sampleplayer:setOffset(seconds)`
- **seconds** (number) - Required - The desired playback offset in seconds.

### Response
#### `playdate.sound.sampleplayer:setOffset()`
- No explicit return value.

#### `playdate.sound.sampleplayer:getOffset()`
- Returns the current playback offset in seconds.
```

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

### Initialize and Configure Tilemap

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Creates a new tilemap object and sets its dimensions and image table. The width can also be configured when setting tiles.

```lua
local myTilemap = playdate.graphics.tilemap.new()
myTilemap:setImageTable(myImageTable)
myTilemap:setSize(width, height)
```

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

### Release Build Configuration

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

How to configure a release build with optimized settings.

```APIDOC
## Building for Release

### Description
Generate release build targets with optimized settings by passing a specific argument to CMake.

### Configuration
Pass the `-DCMAKE_BUILD_TYPE=Release` argument to CMake when generating build targets. Note that this argument is ignored in Visual Studio; use the build popup menu to select 'Release' instead.
```

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

### Sprite Center and Size

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Methods for setting and getting the center point and dimensions of a sprite.

```APIDOC
## Sprite Center and Size

### Description
Methods for setting and getting the center point and dimensions of a sprite.

### `playdate.graphics.sprite:setCenter(x, y)`

#### Method
Instance Method

#### Description
Sets the sprite’s drawing center as a fraction (ranging from 0.0 to 1.0) of the height and width. Default is 0.5, 0.5 (the center of the sprite). This means that when you call `:moveTo(x, y)`, the center of your sprite will be positioned at `x`, `y`. If you want x and y to represent the upper left corner of your sprite, specify the center as 0, 0.

### `playdate.graphics.sprite:getCenter()`

#### Method
Instance Method

#### Description
Returns multiple values (`x`, `y`) representing the sprite’s drawing center as a fraction (ranging from 0.0 to 1.0) of the height and width.

### `playdate.graphics.sprite:getCenterPoint()`

#### Method
Instance Method

#### Description
Returns a `playdate.geometry.point` representing the sprite’s drawing center as a fraction (ranging from 0.0 to 1.0) of the height and width.

### `playdate.graphics.sprite:setSize(width, height)`

#### Method
Instance Method

#### Description
Sets the sprite’s size. The method has no effect if the sprite has an image set.

### `playdate.graphics.sprite.width`

#### Description
Can be used to directly read your sprite’s width.

### `playdate.graphics.sprite:getSize()`

#### Method
Instance Method

#### Description
Returns multiple values (`width`, `height`), the current size of the sprite.
```

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

### HTTP Request Methods

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

Functions for sending GET, POST, and general query requests.

```APIDOC
## HTTP Request Methods

### Description
Functions to perform various HTTP request methods like GET, POST, and custom queries.

### `get`
```c
PDNetErr playdate->network->http->get(HTTPConnection* conn, const char* path, const char* headers, size_t headerlen);
```
**Description:** Sends an HTTP GET request to the specified path. Opens the connection if not already open and includes optional headers.

### `query`
```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);
```
**Description:** Sends a generic HTTP request with a specified method, path, optional headers, and a request body.

### `post`
```c
PDNetErr playdate->network->http->post(HTTPConnection* conn, const char* path, const char* headers, size_t headerlen, const char* body, size_t bodylen);
```
**Description:** Sends an HTTP POST request. This is a convenience function equivalent to calling `query` with the method set to `POST`.
```

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

### Initialize Fileplayer

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Creates a new fileplayer object for streaming audio from disk. Optionally, a buffer size in seconds can be specified to control latency and underrun probability. The file path can be provided during initialization or loaded later using the load() method.

```lua
local fp = playdate.sound.fileplayer.new()
-- or
local fp = playdate.sound.fileplayer.new( "audio/myaudio" )
-- or with buffer size
local fp = playdate.sound.fileplayer.new( "audio/myaudio", 0.5 )
```

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

### Get Audio Sample Details (C)

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

Retrieves the raw data, format, sample rate, and byte length of an AudioSample. The output parameters are pointers that will be populated with the sample's information.

```c
void playdate->sound->sample->getData(AudioSample* sample, uint8_t** data, SoundFormat* format, uint32_t* sampleRate, uint32_t* bytelength);
```

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

### Playdate SDK: Basic Image Mask Transparency Example

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Demonstrates how image masks control transparency in Playdate SDK. It shows a new image with an automatic mask, how removing the mask affects drawing, and how masks determine what parts of an image are visible. This example highlights the fundamental concept of transparency being managed by image masks.

```lua
-- By default, new images are transparent, so an image mask is automatically applied to 'image'
local image = playdate.graphics.image.new(20, 20)
-- maskImage will be a 20x20 black image, to mark that the entire image should be transparent
local maskImage = image:getMaskImage()
maskImage:draw(0, 0)

-- When the image is drawn, there will be nothing drawn, because the image mask makes it all transparent
image:draw(0, 0)

-- Removing the mask here will result in 'image' no longer having transparency
image:removeMask()

-- Drawing the image again will draw a black square, because without an image mask, there is no transparency
image:draw(0, 0)

-- Hopefully this cements the concept that all transparency is handled by image masks

```

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

### Lua Object-Oriented Class System using CoreLibs

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Demonstrates creating and extending classes in Lua using the CoreLibs object system. It covers class definition, inheritance, constructor (`init`), instance creation, checking class type (`isa`), and debugging with `tableDump`. Requires importing `_CoreLibs/object`.

```lua
class('Tree').extends()

class('Tree', {color = 'Brown'}).extends(Object)

class('Oak').extends(Tree)

function Oak:init(age, height)
    Oak.super.init(self, age)
    self.height = height
end

oakInstance = Oak(age, height)
oakInstance.className -- equals 'Oak'
oakInstance:isa(Tree) -- returns true
oakInstance:tableDump()
```

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

### Custom JSON Parsing Logic Example (C)

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

This example demonstrates how to use the `json_decoder` callbacks to parse a nested JSON structure, specifically focusing on a 'widget' object. The `myParser_WillDecodeSublist` function sets up custom handlers for the 'widget' scope, and `setWidgetValue` populates widget properties. `finishWidget` is called upon exiting the 'widget' scope.

```c
void myParser_WillDecodeSublist(json_decoder* decoder, const char* name, json_value_type type)
{
	if ( strcmp(name, "widget") == 0 )
	{
		Widget* widget = pd_malloc(sizeof(Widget));
		decoder->userdata = widget;
		decoder->didDecodeTableValue = setWidgetValue;
		decoder->didDecodeSublist = finishWidget;
	}
}

void setWidgetValue(json_decoder* decoder, const char* key, json_value value)
{
	Widget* widget = decoder->userdata;
	if ( strcmp(key, "floops") == 0 )
		widget.floops = json_floatValue(value);
	// ...
}

void* finishWidget(json_decoder* decoder, const char* name, json_value_type type)
{
	widgetCompleted(decoder->userdata); // send to external function
	return decoder->userdata; // or return the widget in didDecodeTableValue()'s value.data.tableval field
}
```

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

### HTTP Request Methods

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Methods for sending HTTP requests, including GET, POST, and query.

```APIDOC
## HTTP Request Methods

### Description
Methods for sending HTTP requests, including GET, POST, and query.

### Methods

#### `playdate.network.http:get(path, [headers])`

- **Description**: Opens the connection to the server if it’s not already open and sends a GET request with the specified path and optional headers.
- **Method**: GET
- **Endpoint**: /websites/sdk_play_date_3_0_3/get
- **Parameters**:
  - **path** (string) - Required - The path for the GET request.
  - **headers** (string | table) - Optional - Additional headers to send with the request.
- **Returns**: `true` on success, `false` and an error string on failure.

#### `playdate.network.http:query(path, [headers], data)`

- **Description**: Opens the connection and sends a request with the specified path, optional headers, and data. If only one argument follows `path`, it's assumed to be `data`.
- **Method**: POST
- **Endpoint**: /websites/sdk_play_date_3_0_3/query
- **Parameters**:
  - **path** (string) - Required - The path for the request.
  - **headers** (string | table) - Optional - Additional headers to send with the request.
  - **data** (any) - Optional - The data to send with the request.
- **Returns**: `true` on success, `false` and an error string on failure.

#### `playdate.network.http:post(path, [headers], data)`

- **Description**: Equivalent to calling `playdate.network.http:query()` with the method set to `POST`.
- **Method**: POST
- **Endpoint**: /websites/sdk_play_date_3_0_3/post
- **Parameters**:
  - **path** (string) - Required - The path for the POST request.
  - **headers** (string | table) - Optional - Additional headers to send with the request.
  - **data** (any) - Required - The data to send with the request.
- **Returns**: `true` on success, `false` and an error string on failure.
```

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

### Command Line CMake Build for Playdate SDK

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

Build Playdate projects from the command line using CMake. This includes steps for creating a build directory, configuring the build for the simulator, and then reconfiguring for the device using the arm.cmake toolchain file.

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

```bash
cd build
cmake -DCMAKE_TOOLCHAIN_FILE=<path to SDK>/C_API/buildsupport/arm.cmake ..
make
```

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

### Sprite Rotation

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Methods for setting and getting the rotation angle of a sprite. Rotation can be combined with scaling.

```APIDOC
## POST playdate.graphics.sprite:setRotation(angle, [scale, [yScale]])

### Description
Sets the rotation for the sprite in degrees clockwise, with an optional scaling factor. If `setImage()` is called after this, the rotation and scale are applied to the new image. This only affects sprites that have an image set. Use with discretion due to potential performance impact.

### Method
POST

### Endpoint
playdate.graphics.sprite:setRotation

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **angle** (number) - The rotation angle in degrees clockwise.
- **scale** (number) - Optional. The scaling factor to apply along with rotation.
- **yScale** (number) - Optional. The y-axis scaling factor. Defaults to `scale` if not provided.

### Request Example
```json
{
  "angle": 45,
  "scale": 1.1
}
```

### Response
#### Success Response (200)
No specific response body, operation is performed.

### Caution
Consider pre-rendering rotated images for your sprites instead of using this function frequently for performance reasons.

## GET playdate.graphics.sprite:getRotation()

### Description
Returns the current rotation angle of the sprite.

### Method
GET

### Endpoint
playdate.graphics.sprite:getRotation

### Parameters
None

### Response
#### Success Response (200)
- **angle** (number) - The current rotation angle in degrees.

#### Response Example
```json
{
  "angle": 45
}
```
```

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

### Create Directory (C)

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

Creates a new directory at the specified path within the game's Data/<gameid> folder. Intermediate directories are not created automatically. Returns 0 on success, -1 on error.

```c
int playdate->file->mkdir(const char* path);
```

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

### Volume Control

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

Functions to set and get the playback volume for the left and right channels of a synthesizer.

```APIDOC
## Volume Control

### Description
Functions to set and get the playback volume for the left and right channels of a synthesizer.

### Methods

- `void playdate->sound->synth->setVolume(PDSynth* synth, float lvol, float rvol)`
  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);
  ```

- `float playdate->sound->synth->getVolume(PDSynth* synth, float* outlvol, float* outrvol)`
  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);
  ```
```

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

### Get Fileplayer Audio Length

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Retrieves the total length of the currently loaded audio file in seconds.

```lua
local length = fp:getLength()
print("Audio length: " .. length .. " seconds")
```

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

### Get System Settings (Playdate C)

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

Retrieves global system settings for screen orientation and flashing reduction. These functions return an integer value: 1 if the setting is enabled, and 0 otherwise. They do not require any specific inputs.

```c
int getFlippedSetting = playdate->system->getFlipped();
int getReduceFlashingSetting = playdate->system->getReduceFlashing();
```

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

### Create and Free PDSynthInstrument (C)

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

Demonstrates how to create a new PDSynthInstrument object and how to free an existing one. These functions are essential for managing the lifecycle of polyphonic instruments in the Playdate sound engine.

```c
PDSynthInstrument* instrument = playdate->sound->instrument->newInstrument();
// ... use instrument ...
playdate->sound->instrument->freeInstrument(instrument);
```

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

### Image Information and Manipulation

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Functions for getting image dimensions, copying, clearing, and sampling pixel colors.

```APIDOC
## Image Information and Manipulation

### Description
Functions for getting image dimensions, copying, clearing, and sampling pixel colors.

### Methods

#### `playdate.graphics.image:getSize()`

Returns the pair (`width`, `height`).

#### `playdate.graphics.image:clear(color)`

Erases the contents of the image, setting all pixels to white if `color` is `playdate.graphics.kColorWhite`, black if it’s `playdate.graphics.kColorBlack`, or clear if it’s `playdate.graphics.kColorClear`. If the image is cleared to black or white, the mask (if it exists) is set to fully opaque. If the image is cleared to `kColorClear` and the image doesn’t have a mask, a mask is added to it.

#### `playdate.graphics.image:sample(x, y)`

Returns `playdate.graphics.kColorWhite` if the image is white at (`x`, `y`), `playdate.graphics.kColorBlack` if it’s black, or `playdate.graphics.kColorClear` if it’s transparent.

**Note**: The upper-left pixel of the image is at coordinate `(0, 0)`.
```

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

### Resume Per-Frame Updates

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

playdate.start() resumes per-frame callbacks to playdate.update(), re-enabling the regular game loop after it may have been stopped.

```lua
playdate.start()
```

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

### Get File Type - Playdate Lua

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Determines and returns the type of the file located at the specified path.

```lua
playdate.file.getType(path)
```

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

### Get GMT Time Table

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Returns a table containing the current GMT time, with the same keys as `playdate.getTime()`.

```lua
local gmtTimeTable = playdate.getGMTTime()
```

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

### Sample Code Performance (Lua)

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

The `sample(name, function)` function profiles the execution time of a given function. Wrap code blocks in an anonymous function and provide a unique name for each sample. Requires importing `_CoreLibs/utilities/sampler_`.

```lua
local sampler = require("_CoreLibs/utilities/sampler")

sampler.sample("MyHeavyTask", function()
    -- Code to be profiled
    for i = 1, 10000 do
        math.sqrt(i)
    end
end)
```

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

### SoundSequence Playback Control

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

Functions for controlling the playback of SoundSequences, including starting, stopping, and checking playback status.

```APIDOC
## SoundSequence Playback Control

### Description
Provides controls for playing and stopping `SoundSequence` objects, with options for callback functions upon completion.

### Methods

- **`playdate->sound->sequence->play(SoundSequence* sequence, SequenceFinishedCallback finishCallback, void* userdata)`**
  - **Description**: Starts playing the `SoundSequence`.
  - **Parameters**:
    - `sequence` (SoundSequence*) - The sequence to play.
    - `finishCallback` (SequenceFinishedCallback) - An optional callback function to be called when the sequence finishes or is stopped.
    - `userdata` (void*) - User-defined data to pass to the callback function.

- **`playdate->sound->sequence->stop(SoundSequence* sequence)`**
  - **Description**: Stops the currently playing `SoundSequence`.
  - **Parameters**:
    - `sequence` (SoundSequence*) - The sequence to stop.

- **`playdate->sound->sequence->isPlaying(SoundSequence* sequence)`**
  - **Description**: Checks if the `SoundSequence` is currently playing.
  - **Parameters**:
    - `sequence` (SoundSequence*) - The sequence to check.
  - **Returns**: 1 if playing, 0 otherwise.
```

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

### Setup and Draw List-Style Grid View in Playdate

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Creates a simple list-style grid view using the playdate.ui.gridview module. It configures the view with a background image, sets the number of rows based on an array, and defines custom cell drawing and padding. The grid view is then drawn within a specified rectangle.

```lua
local menuOptions = {"Sword", "Shield", "Arrow", "Sling", "Stone", "Longbow", "MorningStar", "Armour", "Dagger", "Rapier", "Skeggox", "War Hammer", "Battering Ram", "Catapult"}
local listview = playdate.ui.gridview.new(0, 10)
listview.backgroundImage = playdate.graphics.nineSlice.new('scrollbg', 20, 23, 92, 28)
listview:setNumberOfRows(#menuOptions)
listview:setCellPadding(0, 0, 13, 10)
listview:setContentInset(24, 24, 13, 11)

function listview:drawCell(section, row, column, selected, x, y, width, height)
        if selected then
                gfx.fillRoundRect(x, y, width, 20, 4)
                gfx.setImageDrawMode(gfx.kDrawModeFillWhite)
        else
                gfx.setImageDrawMode(gfx.kDrawModeCopy)
        end
        gfx.drawTextInRect(menuOptions[row], x, y+2, width, height, nil, "...", kTextAlignment.center)
end

function playdate.update()
    listview:drawInRect(220, 20, 160, 210)
    playdate.timer:updateTimers()
end
```

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

### Get Sprite Collides-With-Groups Bitmask (Lua)

Source: https://sdk.play.date/3.0.3/Inside%20Playdate

Retrieves the current integer value of the sprite's collides-with-groups bitmask.

```lua
playdate.graphics.sprite:getCollidesWithGroupsMask()
```
Tokens:
Raw