Playdate SDK

https://sdk.play.date/3.0.2/
Admin
Playdate SDK is a development kit for creating games for the Playdate handheld gaming console,...
Tokens:228,563
Snippets:1,759
Trust Score:10
Update:8 months ago
Show doc for...
Tokens:
Raw
### Command Line Make Build (Default)

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

Builds a Playdate project using the example Makefiles. Assumes necessary C development packages and ARM toolchain are installed.

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

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

### Screen Shake Effect Example (Lua)

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

An example demonstrating how to create a screen shake effect using `playdate.display.setOffset()` in conjunction with timers. The shake magnitude gradually decreases over time, and the offset is reset when the effect ends.

```lua
-- You can copy and paste this example directly as your main.lua file to see it in action
import "CoreLibs/graphics"
import "CoreLibs/timer"

-- This function relies on the use of timers, so the timer core library
-- must be imported, and updateTimers() must be called in the update loop
local function screenShake(shakeTime, shakeMagnitude)
    -- Creating a value timer that goes from shakeMagnitude to 0, over
    -- the course of 'shakeTime' milliseconds
    local shakeTimer = playdate.timer.new(shakeTime, shakeMagnitude, 0)
    -- Every frame when the timer is active, we shake the screen
    shakeTimer.updateCallback = function(timer)
        -- Using the timer value, so the shaking magnitude
        -- gradually decreases over time
        local magnitude = math.floor(timer.value)
        local shakeX = math.random(-magnitude, magnitude)
        local shakeY = math.random(-magnitude, magnitude)
        playdate.display.setOffset(shakeX, shakeY)
    end
    -- Resetting the display offset at the end of the screen shake
    shakeTimer.timerEndedCallback = function()
        playdate.display.setOffset(0, 0)
    end
end

function playdate.update()
    playdate.timer.updateTimers()
    if playdate.buttonJustPressed(playdate.kButtonA) then
        -- Shake the screen for 500ms, with the screen
        -- shaking around by about 5 pixels on each side
        screenShake(500, 5)
    end

    -- A circle to be able to view what the shaking looks like
    playdate.graphics.fillCircleAtPoint(200, 120, 10)
end

```

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

### Playdate SDK: Basic Image Mask Transparency Example

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

Demonstrates how image masks control transparency. Initially, a new image is transparent due to an automatically applied mask. Removing the mask makes the image opaque. This example illustrates 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

```

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

### Bouncing Ball Animation Example

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

Demonstrates creating a frame timer to animate a bouncing ball. This example utilizes properties like `reverses`, `repeats`, `reverseEasingFunction`, and `updateCallback` to achieve the effect.

```lua
local r = playdate.geometry.rect.new(100, 10, 40, 40)

local t = playdate.frameTimer.new(20, 10, 150, playdate.easingFunctions.inCubic)
t.reverses = true
t.repeats = true
t.reverseEasingFunction = playdate.easingFunctions.outQuad
t.updateCallback = function(timer)
    r.y = timer.value
end
```

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

### Accelerometer Ball Rolling Demo - Playdate Lua

Source: https://sdk.play.date/3.0.2/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 its values in the update loop, and clamping the ball's position within screen bounds.

```lua
-- You can copy and paste this example directly as your main.lua file to see it in action
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

```

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

### Example Write Function for File Output

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

Provides an example implementation of a 'writeFunc' that writes JSON data to a Playdate file using playdate->file->write(). This demonstrates how to connect the JSON encoder's output to persistent storage.

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

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

### JSON Reader Implementation Example (C)

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

This example shows a `readfile` function that implements the `json_reader`'s `read` callback to read data from a Playdate SDK `SDFile`. It uses `playdate->file->read` to populate the buffer. The subsequent code snippet demonstrates how to initialize a `json_reader` with this function and use it with `pd->json->decode` to parse a JSON file named 'data.json'.

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

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

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

### Custom JSON Parsing Logic Example (C)

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

This example demonstrates how to implement custom logic for parsing specific JSON structures using the `json_decoder` callbacks. The `myParser_WillDecodeSublist` function shows how to detect a 'widget' object, allocate memory for it, and assign specific callback functions (`setWidgetValue`, `finishWidget`) to handle its contents. This allows for tailored data extraction and processing.

```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;
	}
}
```

```c
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);
	// ...
}
```

```c
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
}
```

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

### Frame Timer Sample Code

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

Examples demonstrating the usage of frame timers for simple counting, value interpolation, and animation.

```APIDOC
## Frame Timer Sample Code

### Simple Frame Counter

```lua
t = playdate.frameTimer.new(200)
-- Access the current frame count via t.frame
```

### Value Interpolation

```lua
-- Interpolate between 0 and 100 over 50 frames using linear easing
t = playdate.frameTimer.new(50, 0, 100)
-- Access the current interpolated value via t.value

-- Using a specific easing function (e.g., inCubic)
t = playdate.frameTimer.new(50, 0, 100, playdate.easingFunctions.inCubic)
```

### Bouncing Ball Animation Example

```lua
local r = playdate.geometry.rect.new(100, 10, 40, 40)

local t = playdate.frameTimer.new(20, 10, 150, playdate.easingFunctions.inCubic)
t.reverses = true
t.repeats = true
t.reverseEasingFunction = playdate.easingFunctions.outQuad

t.updateCallback = function(timer)
    r.y = timer.value
end
```

### Timer Configuration Notes

*   Timers created with `playdate.frameTimer.new(duration)` will automatically start and complete without repeating or reversing.
*   Set `t.discardOnCompletion = false` to retain a timer after it finishes for potential reuse.
*   When `reverses` is true, the timer runs forward for `duration` frames, then backward for `duration` frames. The `updateCallback` will be called throughout both phases.
*   The `timerEndedCallback` is invoked when a timer finishes its cycle (either forward or reverse, if applicable).
```

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

### SamplePlayer State and Configuration

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

Functions for getting and setting various properties of a SamplePlayer, such as length, rate, volume, and callbacks.

```APIDOC
## SamplePlayer State and Configuration

### Description
Functions for getting and setting various properties of a SamplePlayer, such as length, rate, volume, and callbacks.

### Method
- `playdate->sound->sampleplayer->getLength(SamplePlayer* player)`
- `isPlaying(SamplePlayer* player)`
- `setFinishCallback(SamplePlayer* player, sndCallbackProc callback, void* userdata)`
- `setOffset(SamplePlayer* player, float offset)`
- `getOffset(SamplePlayer* player)`
- `setPlayRange(SamplePlayer* player, int start, int end)`
- `setRate(SamplePlayer* player, float rate)`
- `getRate(SamplePlayer* player)`
- `setSample(SamplePlayer* player, AudioSample* sample)`
- `setVolume(SamplePlayer* player, float left, float right)`
- `getVolume(SamplePlayer* player, float* outleft, float* outright)`

### Endpoint
N/A (Library functions)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
float duration = playdate->sound->sampleplayer->getLength(myPlayer);

playdate->sound->sampleplayer->setRate(myPlayer, 0.5);
float currentRate = playdate->sound->sampleplayer->getRate(myPlayer);

playdate->sound->sampleplayer->setVolume(myPlayer, 0.8, 0.8);
float leftVol, rightVol;
playdate->sound->sampleplayer->getVolume(myPlayer, &leftVol, &rightVol);
```

### Response
#### Success Response (200)
- `float` for `getLength()`, `getOffset()`, `getRate()`
- `int` for `isPlaying()`
- `void` for setter functions

#### Response Example
N/A
```

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

### Basic Playdate Game Setup and Input Handling in Lua

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

This Lua code sets up a basic Playdate game by initializing graphics, creating a player sprite, and displaying a background image. It also implements the game's update loop to handle d-pad input for player movement.

```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

```

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

### Get Menu Item Title - Playdate Lua

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

Retrieves the current title displayed for a menu item. This function is useful for reading the text associated with a menu item, for example, to display it elsewhere or to check its current value.

```lua
playdate.menu.item:getTitle()
```

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

### Create SamplePlayer from Path

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

Instantiates a new SamplePlayer object by loading sound data from the specified file path. If the file cannot be loaded, it returns nil and an error message. This method is suitable for loading sound effects or short audio clips.

```lua
playdate.sound.sampleplayer.new(path)
```

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

### Get global Playdate font tracking

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

Gets the current global font tracking value in pixels. This represents the additional spacing applied between letters across all fonts.

```lua
local tracking = playdate.graphics.getFontTracking()
```

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

### Compiling a Playdate Project with pdc

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

Demonstrates the basic usage of the Playdate Compiler ('pdc') command-line tool. It requires input source directory and an output directory (conventionally ending in .pdx).

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

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

### Command Line Make Build Options

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

Demonstrates the different build targets available when using Make for Playdate projects.

```makefile
make simulator
make device
```

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

### Play Audio File with Fileplayer

Source: https://sdk.play.date/3.0.2/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 repeated a specified number of times, with 0 indicating infinite looping. Returns true on success, false with an error message otherwise.

```lua
local success, err = fp:play()
local successLoop = fp:play(0) -- Infinite loop
local successRepeat = fp:play(3) -- Play once, then loop 3 times
```

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

### Perform HTTP GET Request

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

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

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

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

### Initialize Fileplayer

Source: https://sdk.play.date/3.0.2/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.

```lua
local fp = playdate.sound.fileplayer.new()
local fpWithPath = playdate.sound.fileplayer.new("audio/myaudiofile")
local fpWithBuffer = playdate.sound.fileplayer.new(0.5)
local fpAll = playdate.sound.fileplayer.new("audio/myaudiofile", 0.5)
```

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

### Tilemap Usage Example

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

Illustrates the basic steps for using tilemaps in Playdate. This involves creating a tilemap, associating it with an image table, setting the tile data, and then drawing the tilemap to the screen. This is a common pattern for rendering game levels.

```lua
-- 1. Instantiate a blank tilemap.
local myTilemap = playdate.graphics.tilemap.new()

-- 2. Attach an imagetable.
local tileImages = playdate.graphics.imagetable.new("level_tiles")
myTilemap:setImagetable(tileImages)

-- 3. Set the tilemap's matrix of indices and width.
-- Assuming 'levelData' is a table of tile indices and 'mapWidth' is the tilemap width.
-- Example: levelData = {1, 2, 1, 3, 1, 1, 2, 3, ...}
-- Example: mapWidth = 10
myTilemap:setTiles(levelData, mapWidth)

-- 4. Draw your tilemap.
myTilemap:draw(0, 0) -- Draws the tilemap at the top-left corner of the screen
```

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

### Playdate Graphics Animator: reset() Method

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

Resets the animation to its starting state. The animation's start time is set to the current time. An optional duration can be provided to change the animation's total duration.

```lua
playdate.graphics.animator:reset([duration])
```

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

### Sample Code Execution Time (Lua)

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

The `sample(name, function)` function measures the execution time of a given anonymous function and logs it with a specified name. It requires importing `_CoreLibs/utilities/sampler`. Useful for identifying performance bottlenecks.

```lua
local sampler = require("_CoreLibs/utilities/sampler")
sampler.sample("MyHeavyTask", function()
  -- Code to be profiled
  for i = 1, 10000 do
    math.sin(i)
  end
end)
```

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

### Create Value Interpolation Timer with Playdate

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

Creates a timer that interpolates a value between a start and end point over a specified duration. Easing functions can be applied to control the interpolation curve. Timers start automatically upon creation.

```lua
playdate.timer.new(duration, [startValue, endValue, [easingFunction]])
```

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

### Minimal Video Player with Audio Synchronization (Lua)

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

This Lua code snippet demonstrates a basic video player that synchronizes video frames with audio playback. It initializes the display, graphics, and sound systems, loads a video and audio file, and then updates the video frame based on the audio's current offset in the playdate.update() loop. It requires 'movie.pdv' for video and 'movie.wav' (or similar) for audio.

```lua
local disp = playdate.display
local gfx = playdate.graphics
local snd = playdate.sound

disp.setRefreshRate(0)

local video = gfx.video.new('movie')
video:useScreenContext()
video:renderFrame(0)

local lastframe = 0

local audio, loaderr = snd.sampleplayer.new('movie')

if audio ~= nil then
        audio:play(0)
else
        print(loaderr)
end

function playdate.update()

        local frame = math.floor(audio:getOffset() * video:getFrameRate())

        if frame ~= lastframe then
                video:renderFrame(frame)
                lastframe = frame
        end
end
```

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

### Sample Key Repeat Timer Implementation in Lua

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

Demonstrates how to implement a key repeat timer in Lua for the Playdate SDK. It shows setting up a timer for a button press and removing it on button release, along with the necessary timer update call.

```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 Sprite Size

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

Returns the current width and height of the sprite.

```lua
local width, height = mySprite:getSize()
```

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

### Loading Assets in Playdate

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

Shows examples of loading images and sound files within a Playdate project. Images are loaded using playdate.graphics.image.new() and sounds using playdate.sound.sampleplayer.new(). Paths are relative to the project's source directory.

```lua
-- Load an image
myImage = playdate.graphics.image.new("images/myImageFile")

-- Load a sound
mySound = playdate.sound.sampleplayer.new("sounds/mySoundFile")
```

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

### Get Sprite Z-Index

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

Retrieves the current Z-index value of the sprite.

```lua
local zIndex = mySprite:getZIndex()
```

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

### Get Sprite Position

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

Returns the current x and y coordinates of the sprite.

```lua
local x, y = mySprite:getPosition()
```

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

### Sample _pdxinfo_ File Configuration

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

This snippet shows a sample _pdxinfo_ file, which is a configuration file used by the Playdate SDK to store game metadata. It includes fields like name, author, description, version, and image paths.

```ini
name=b360
author=Panic Inc.
description=When all you have is a ton of bricks, everything looks like a paddle.
bundleID=com.panic.b360
version=1.0
buildNumber=123
imagePath=path/to/launcher/assets
launchSoundPath=path/to/launch/sound/file
contentWarning=This game contains mild realistic violence and bloodshed.
contentWarning2=This game contains flashing content that may not be suitable for photosensitive epilepsy.
```

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

### Copy SamplePlayer Configuration

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

Returns a new SamplePlayer instance that is a duplicate of an existing one. The new player will have the same sample data, volume, and playback rate as the original, allowing for independent control of copies.

```lua
playdate.sound.sampleplayer:copy()
```

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

### Playdate Filesystem Overview

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

Provides an overview of the Playdate filesystem, including accessible directories and file access rules.

```APIDOC
## Playdate Filesystem

### Description
Provides an overview of the Playdate filesystem, including accessible directories and file access rules.

### Accessible Directories
- **App Bundle**: Read-only directory containing your game's assets.
- **Data Directory**: A writable directory unique to your game, used for saving game state and data.

### File Access Rules
- When reading a file, the system first checks the Data directory, then the App bundle.
- Creating or appending to files always occurs in the Data directory.
- `playdate.file.listFiles()` lists files and directories from both the App bundle and the Data directory.
- Access is restricted to these two directories; files outside are not permitted.
```

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

### Other Tilemap Functions

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

Utility functions for getting pixel dimensions and tile sizes.

```APIDOC
## Other Tilemap Functions

### Description
Utility functions for getting pixel dimensions and tile sizes.

### Methods

#### `playdate.graphics.tilemap:getPixelSize()`

*   **Description**: Returns the size of the tilemap in pixels; that is, the size of the image multiplied by the number of rows and columns in the map. Returns multiple values (`width`, `height`).
*   **Method**: `getPixelSize`
*   **Endpoint**: `playdate.graphics.tilemap:getPixelSize()`
*   **Response**:
    *   **Success Response (200)**:
        *   `width` (number) - The width of the tilemap in pixels.
        *   `height` (number) - The height of the tilemap in pixels.

#### `playdate.graphics.tilemap:getTileSize()`

*   **Description**: Returns two values (`width`, `height`), the pixel width and height of an individual tile.
*   **Method**: `getTileSize`
*   **Endpoint**: `playdate.graphics.tilemap:getTileSize()`
*   **Response**:
    *   **Success Response (200)**:
        *   `width` (number) - The pixel width of an individual tile.
        *   `height` (number) - The pixel height of an individual tile.

```

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

### Get Image Size

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

Returns the width and height of an image as a pair of numbers.

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

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

### Playdate Timer Creation and Usage

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

Examples demonstrating how to create and use Playdate's time-based timers for different scenarios, including simple counting and value transitions.

```APIDOC
## Playdate Timer Creation and Usage

### Description
Examples of creating and utilizing Playdate's time-based timers.

### Methods
- **playdate.timer.new(duration, [delay], [callback], [...])**
  Creates a new timer.

### Request Example
```lua
-- Simple timer to count milliseconds
t = playdate.timer.new(1000)

-- Timer for value transition
t = timer(500, 0, 100)

-- Timer with advanced properties
local r = playdate.geometry.rect.new(100, 10, 40, 40)
local t = playdate.timer.new(1000, 10, 150, easingFunctions.inCubic)
t.reverses = true
t.repeats = true
t.reverseEasingFunction = easingFunctions.outQuad
t.updateCallback = function(timer)
	r.y = timer.value
end
```

### Response
#### Success Response (Timer Object)
- **timer** (object) - The newly created timer object.
```

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

### Sprite Collision Setup

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

Functions for defining and managing the collision boundaries of sprites.

```APIDOC
## Sprite Collision Setup

### Description
Functions for defining and managing the collision boundaries of sprites.

### `setCollideRect(x, y, width, height)`
Marks the area of the sprite, relative to its own internal coordinate system, to be checked for collisions with other sprites' collide rects. The coordinate space is relative to the top-left corner of the bounds.

### `setCollideRect(rect)`
Marks the area of the sprite, relative to its own internal coordinate system, to be checked for collisions with other sprites' collide rects. The coordinate space is relative to the top-left corner of the bounds.

### `getCollideRect()`
Returns the sprite’s collide rect set with `setCollideRect()`. Return value is a `playdate.geometry.rect`. Coordinates are relative to the sprite itself.

### `getCollideBounds()`
Returns the sprite’s collide rect as multiple values, (_x_ , _y_ , _width_ , _height_). Coordinates are relative to the sprite itself.

### `clearCollideRect()`
Clears the sprite’s collide rect set with `setCollideRect()`.

### `setCollisionsEnabled(flag)`
Sets the sprite’s _collisionsEnabled_ flag (defaults to true) to `false` in order to temporarily keep a sprite from colliding with any other sprite.

### `collisionsEnabled()`
Returns the sprite’s _collisionsEnabled_ flag.
```

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

### Manage Playdate Timers: Pause, Start, Remove, Reset

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

Provides methods for controlling the lifecycle of Playdate timers. `pause()` stops a timer, `start()` resumes a paused timer, `remove()` disposes of a timer, and `reset()` reverts it to its initial state. Note that timer removal is finalized on the next `updateTimers()` call.

```lua
playdate.timer:pause()
playdate.timer:start()
playdate.timer:remove()
playdate.timer:reset()
```

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

### Control Game Flow with Playdate Functions

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

Provides examples of using playdate.wait(), playdate.stop(), playdate.start(), and playdate.restart() to control game execution, pause updates, and reinitialize the runtime.

```lua
-- Pause game updates for 500 milliseconds
playdate.wait(500)

-- Stop per-frame updates
playdate.stop()

-- Resume per-frame updates
playdate.start()

-- Restart the game with an argument
playdate.restart("start_level 1")
```

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

### HTTP Request Methods

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

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

```APIDOC
## HTTP Request Methods

### Description
These methods are used to send HTTP requests to a server. They handle opening the connection if necessary and queuing the request.

### Methods

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

Opens the connection to the server if it’s not already open (e.g. from a previous request with the given path and additional _headers_ if specified. The _headers_ argument can either be a string containing all of the headers to send (with newlines between individual headers), an array of strings, or a table of key/value pairs.
If the request is successfully queued, the function returns `true`. On error, the function returns `false` and a string indicating the error.

- **path** (string) - Required - The path for the GET request.
- **headers** (string | table<string> | table<string, string>) - Optional - Additional headers to send with the request.

Returns: `boolean` - true on success, false on error. `string` - Error message if an error occurred.

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

Opens the connection to the server if it’s not already open (e.g. from a previous request with keep-alive enabled) and sends the given request with the given path, additional _headers_ if specified, and the provided _data_. The _headers_ argument can either be a string containing all of the headers to send (with newlines between individual headers), an array of strings, or a table of key/value pairs. If there is only one argument after _path_ it is assumed to be _data_.
If the request is successfully queued, the function returns `true`. On error, the function returns `false` and a string indicating the error.

- **path** (string) - Required - The path for the query.
- **headers** (string | table<string> | table<string, string>) - Optional - Additional headers to send with the request.
- **data** (any) - Required - The data to send with the request.

Returns: `boolean` - true on success, false on error. `string` - Error message if an error occurred.

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

Equivalent to calling `playdate.network.http:query()` with _method_ equal to `POST`.

- **path** (string) - Required - The path for the POST request.
- **headers** (string | table<string> | table<string, string>) - Optional - Additional headers to send with the request.
- **data** (any) - Required - The data to send with the request.

Returns: `boolean` - true on success, false on error. `string` - Error message if an error occurred.
```

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

### Command Line CMake Build (Simulator)

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

Builds a Playdate project for the simulator using CMake and Make on the command line. Creates a build directory and generates Makefiles.

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

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

### Playdate SDK: Image Mask Dither and Hole Punch Effect Example

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

This example showcases advanced usage of image masks to create visual effects like dithered transparency and a 'hole punch' cutout. It involves creating an image, manipulating its mask to achieve desired transparency patterns, and then drawing the image with these modified masks.

```lua
-- You can copy and paste this example directly as your main.lua file to see it in action
import "CoreLibs/graphics"

local gfx = playdate.graphics

-- Creating an image with a black circle
local circleDiameter = 25
local circleImage = gfx.image.new(circleDiameter, circleDiameter)
Gfx.pushContext(circleImage)
    gfx.fillCircleInRect(0, 0, circleImage:getSize())
Gfx.popContext()

-- Saving the original mask (the transparency in the corners of the image not covered by the circle)
local circleMask = circleImage:getMaskImage():copy()

-- Copying the original mask to preserve transparent regions around the circle
local ditherMask = circleMask:copy()
-- Drawing into mask with a dither effect
Gfx.pushContext(ditherMask)
    gfx.setColor(gfx.kColorBlack)
    gfx.setDitherPattern(0.5, gfx.image.kDitherTypeBayer8x8)
    gfx.fillRect(0, 0, ditherMask:getSize())
Gfx.popContext()

-- Copying the original mask to preserve transparent regions around the circle
local holeMask = circleMask:copy()
-- Drawing a hole into mask
Gfx.pushContext(holeMask)
    gfx.setColor(gfx.kColorBlack)
    local width, height = holeMask:getSize()
    gfx.fillCircleAtPoint(width/2, height/2, width/4)
Gfx.popContext()

function playdate.update()
    -- Circle is drawn with dithered regions transparent
    circleImage:setMaskImage(ditherMask)
    circleImage:drawAnchored(100, 120, 0.5, 0.5)

    -- Circle is drawn with hole in center
    circleImage:setMaskImage(holeMask)
    circleImage:drawAnchored(200, 120, 0.5, 0.5)

    -- Resetting the original mask returns the circle to normal
    circleImage:setMaskImage(circleMask)
    circleImage:drawAnchored(300, 120, 0.5, 0.5)
end

-- Technical details: Why copy the mask after getting it? :getMaskImage() returns a reference
-- to the mask image. Using :setMaskImage after will update that mask image to a new image, which
-- overwrites the referenced image and the original is lost. That's why we make a copy. Of course,
-- no :copy() calls are necessary if you don't intend to save the original mask.

```

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

### Get Sprite Image

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

Retrieves the current playdate.graphics.image object associated with the sprite, as set by setImage().

```lua
local currentImage = mySprite:getImage()
```

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

### Polygon Point Access and Modification

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

Methods for getting and setting individual points within a polygon.

```APIDOC
## Polygon Point Access and Modification

### Description
Methods for accessing and modifying individual points of a polygon.

### Methods

#### `setPointAt(n, x, y)`
- **Description**: Sets the `n`-th point of the polygon to the coordinates `(x, y)`.
- **Parameters**:
  - **n** (number) - The index of the point to set (0-based).
  - **x** (number) - The new x-coordinate.
  - **y** (number) - The new y-coordinate.

#### `getPointAt(n)`
- **Description**: Returns the `n`-th point of the polygon.
- **Parameters**:
  - **n** (number) - The index of the point to retrieve (0-based).
- **Returns**: A `playdate.geometry.point` object representing the point at the specified index.

### Request Example
```lua
local poly = playdate.geometry.polygon.new(0, 0, 100, 0, 50, 100)

-- Get a point
local firstPoint = poly:getPointAt(0)
print("First point: ", firstPoint)

-- Set a point
poly:setPointAt(1, 120, 10)
print("Second point after set: ", poly:getPointAt(1))
```
```

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

### Grid View Initialization and Drawing (Playdate Lua)

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

This snippet shows how to initialize a new grid view and draw it within a specified rectangle. It requires importing 'CoreLibs/ui' and calling playdate.timer.updateTimers() in the main update function. The drawInRect method is ideal for calling on every update to handle scrolling.

```lua
local myGridView = playdate.ui.gridview.new(cellWidth, cellHeight)

function playdate.update()
  playdate.timer.updateTimers()
  -- ... other update logic ...
  myGridView:drawInRect(x, y, width, height)
end
```

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

### Sprite Positioning

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

Functions to move and get the position of a sprite.

```APIDOC
## Sprite Positioning

### Description
Functions to move and get the position of a sprite.

### Methods

#### moveTo

##### Description
Moves the given sprite to the specified x and y coordinates and resets its bounds based on the bitmap dimensions and center.

##### Signature
`void playdate->sprite->moveTo(LCDSprite *sprite, float x, float y);`

#### moveBy

##### Description
Moves the given sprite by offsetting its current position by dx and dy.

##### Signature
`void playdate->sprite->moveBy(LCDSprite *sprite, float dx, float dy);`

#### getPosition

##### Description
Sets the provided x and y pointers to the current position of the sprite.

##### Signature
`void playdate->sprite->getPosition(LCDSprite *sprite, float *x, float *y);`
```

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

### Restart and Get Launch Arguments (C)

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

Enables restarting the game with optional arguments and retrieving arguments passed during launch. `restart` reinitializes the runtime, and `getLaunchArgs` retrieves the arguments string and optionally the game path.

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

const char* launchArgs = NULL;
const char* gamePath = NULL;
const char* args = playdate->system->getLaunchArgs(&gamePath);
// Use args and gamePath as needed
```

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

### Get Command Line Arguments (Lua)

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

The `playdate.argv` array contains command-line arguments. The first element is the current pdx filename. Additional arguments passed during simulator launch or via `playdate.restart()` are appended.

```lua
print("Current file: " .. playdate.argv[1])
if #playdate.argv > 1 then
  print("Additional arguments:")
  for i, arg in ipairs(playdate.argv) do
    if i > 1 then
      print(arg)
    end
  end
end
```

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

### Get Font Metrics

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

Retrieves the pixel height and width of text when rendered with a specific font instance.

```lua
playdate.graphics.font:getHeight()
playdate.graphics.font:getTextWidth(text)
```

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

### Play Sample

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

Initiates playback of the loaded sample. Playback can be set to repeat a specified number of times, loop indefinitely (until stopped), or play at a custom rate. If no repeat count is specified, it plays once.

```lua
playdate.sound.sampleplayer:play([repeatCount], [rate])
```

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

### Image Table Manipulation

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

Provides methods to get, set, and manage images within an image table.

```APIDOC
## playdate.graphics.imagetable:getImage(n)

### Description
Returns the _n_ -th playdate.graphics.image in the table (ordering left-to-right, top-to-bottom). The first image is at index 1.

### Method
`imagetable:getImage(n: number): playdate.graphics.image | nil`

### Parameters
*   **n** (number) - Required - The index of the image to retrieve (1-based).

### Response
*   **image** (playdate.graphics.image) - The requested image object, or nil if out of bounds.

## playdate.graphics.imagetable:getImage(x,y)

### Description
Returns the image in cell (_x_ ,_y_) in the original bitmap. The first image is at index 1.

### Method
`imagetable:getImage(x: number, y: number): playdate.graphics.image | nil`

### Parameters
*   **x** (number) - Required - The x-coordinate of the cell.
*   **y** (number) - Required - The y-coordinate of the cell.

### Response
*   **image** (playdate.graphics.image) - The requested image object, or nil if out of bounds.

## playdate.graphics.imagetable:setImage(n, image)

### Description
Sets the image at slot _n_ in the image table by creating a reference to the data in _image_.

### Method
`imagetable:setImage(n: number, image: playdate.graphics.image): void`

### Parameters
*   **n** (number) - Required - The slot index to set the image in.
*   **image** (playdate.graphics.image) - Required - The image object to set.

### Request Example
```lua
local img = playdate.graphics.image.new(10, 10)
myTable:setImage(5, img)
```

## playdate.graphics.imagetable:load(path)

### Description
Loads a new image table from the data at _path_ into an already-existing image table, without allocating additional memory. The image table at _path_ must contain images of the same dimensions as the previous.

### Method
`imagetable:load(path: string): (boolean, string | nil)`

### Parameters
*   **path** (string) - Required - The path to the image data to load.

### Response
*   **success** (boolean) - True if the load was successful, false otherwise.
*   **error** (string) - An error message if the load failed (only present if success is false).

### Request Example
```lua
local success, err = myTable:load("new_frames")
if not success then
  print("Failed to load new images: " .. err)
end
```
```

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

### Get Sprite Drawing Center

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

Returns the current x and y fractions representing the sprite's drawing center.

```lua
local centerX, centerY = mySprite:getCenter()
```

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

### Create SamplePlayer from Sample Data

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

Creates a new SamplePlayer instance using pre-loaded sample data. This is useful when the audio data is already in memory or has been processed. The SamplePlayer will then use this provided sample for playback.

```lua
playdate.sound.sampleplayer.new(sample)
```

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

### Building for Device with CMake (C)

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

Commands to configure and build a Playdate C API project for the 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
```

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

### Individual Tile Manipulation

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

Functions for setting and getting the index of individual tiles at specific positions within the tilemap.

```APIDOC
## Individual Tile Manipulation

### Description
Functions for setting and getting the index of individual tiles at specific positions within the tilemap.

### Methods

#### `playdate.graphics.tilemap:setTileAtPosition(x, y, index)`

*   **Description**: Sets the index of the tile at tilemap position (`x`, `y`). `index` is the (1-based) index of the image in the tilemap’s `playdate.graphics.imagetable`.
*   **Method**: `setTileAtPosition`
*   **Endpoint**: `playdate.graphics.tilemap:setTileAtPosition(x, y, index)`
*   **Parameters**:
    *   **Path Parameters**:
        *   `x` (number) - Required - The x-coordinate of the tile position (1-based).
        *   `y` (number) - Required - The y-coordinate of the tile position (1-based).
        *   `index` (number) - Required - The 1-based index of the image in the imagetable.

#### `playdate.graphics.tilemap:getTileAtPosition(x, y)`

*   **Description**: Returns the image index of the tile at the given `x` and `y` coordinate. If `x` or `y` is out of bounds, returns nil.
*   **Method**: `getTileAtPosition`
*   **Endpoint**: `playdate.graphics.tilemap:getTileAtPosition(x, y)`
*   **Parameters**:
    *   **Path Parameters**:
        *   `x` (number) - Required - The x-coordinate of the tile position (1-based).
        *   `y` (number) - Required - The y-coordinate of the tile position (1-based).
*   **Response**:
    *   **Success Response (200)**:
        *   `index` (number) - The 1-based index of the image in the imagetable, or nil if out of bounds.

```
Tokens:
Raw