Adjusted the naming of the library in the Package file.

Sources/PlaydateKit/Display.swift

@@ -0,0 +1,57 @@
+//
+//  Display.swift
+//  Wraps `playdate->display` (pd_api_display.h).
+//
+
+internal import CPlaydate
+
+/// The display API: resolution, refresh rate, scaling, and effects.
+public enum Display {}
+
+extension Display {
+    private static var api: UnsafePointer<playdate_display> { Playdate.displayAPI.unsafelyUnwrapped }
+
+    /// The display width in pixels, taking the current scale into account.
+    public static var width: Int { Int(api.pointee.getWidth.unsafelyUnwrapped()) }
+
+    /// The display height in pixels, taking the current scale into account.
+    public static var height: Int { Int(api.pointee.getHeight.unsafelyUnwrapped()) }
+
+    /// Sets the nominal refresh rate in frames per second. Pass 0 to update
+    /// as fast as possible (the update callback drives the pace).
+    public static func setRefreshRate(_ rate: Float) {
+        api.pointee.setRefreshRate.unsafelyUnwrapped(rate)
+    }
+
+    /// The current nominal refresh rate.
+    public static var refreshRate: Float { api.pointee.getRefreshRate.unsafelyUnwrapped() }
+
+    /// The measured average frames per second.
+    public static var fps: Float { api.pointee.getFPS.unsafelyUnwrapped() }
+
+    /// Draws the frame white-on-black when `true`.
+    public static func setInverted(_ inverted: Bool) {
+        api.pointee.setInverted.unsafelyUnwrapped(inverted ? 1 : 0)
+    }
+
+    /// Sets the display scale factor: 1, 2, 4, or 8.
+    public static func setScale(_ scale: UInt32) {
+        api.pointee.setScale.unsafelyUnwrapped(scale)
+    }
+
+    /// Adds a mosaic effect. Valid values for each axis are 0...3.
+    public static func setMosaic(x: UInt32, y: UInt32) {
+        api.pointee.setMosaic.unsafelyUnwrapped(x, y)
+    }
+
+    /// Flips the display on the given axes.
+    public static func setFlipped(x: Bool, y: Bool) {
+        api.pointee.setFlipped.unsafelyUnwrapped(x ? 1 : 0, y ? 1 : 0)
+    }
+
+    /// Offsets the display by the given amount. Areas outside the frame
+    /// buffer draw black.
+    public static func setOffset(x: Int, y: Int) {
+        api.pointee.setOffset.unsafelyUnwrapped(Int32(x), Int32(y))
+    }
+}

Sources/PlaydateKit/File.swift

@@ -0,0 +1,216 @@
+//
+//  File.swift
+//  Wraps `playdate->file` (pd_api_file.h).
+//
+//  Paths are relative to the game's Data directory (read/write) or the
+//  game's pdx (read-only), per the mode used to open them.
+//
+
+internal import CPlaydate
+
+private var fileAPI: UnsafePointer<playdate_file> { Playdate.fileAPI.unsafelyUnwrapped }
+
+/// The most recent file system error as a thrown error.
+private func lastFileError() -> PlaydateError {
+    PlaydateError(cString: fileAPI.pointee.geterr.unsafelyUnwrapped())
+}
+
+/// The file API: access to the game's Data directory and pdx contents.
+public enum File {}
+
+extension File {
+    // MARK: - Types
+
+    /// How to open a file.
+    public struct Options: OptionSet, Sendable {
+        public let rawValue: UInt32
+        public init(rawValue: UInt32) { self.rawValue = rawValue }
+
+        /// Read from the game pdx, then the Data directory.
+        public static let read = Options(rawValue: UInt32(kFileRead.rawValue))
+        /// Read from the Data directory only.
+        public static let readData = Options(rawValue: UInt32(kFileReadData.rawValue))
+        /// Write to the Data directory, truncating an existing file.
+        public static let write = Options(rawValue: UInt32(kFileWrite.rawValue))
+        /// Write to the Data directory, appending to an existing file.
+        public static let append = Options(rawValue: UInt32(kFileAppend.rawValue))
+
+        var cValue: FileOptions { FileOptions(FileOptions.RawValue(rawValue)) }
+    }
+
+    /// Information about a file or directory, mirroring `FileStat`.
+    public struct Stat: Sendable {
+        public let isDirectory: Bool
+        public let size: UInt32
+        public let modified: System.DateTime
+    }
+
+    /// The origin used by `Handle.seek(to:from:)`.
+    public enum SeekOrigin: Int32, Sendable {
+        case start = 0
+        case current = 1
+        case end = 2
+    }
+
+    // MARK: - Directory operations
+
+    /// Calls `each` with the name of every file in `path`. Subdirectory names
+    /// end in a slash. Throws if the directory does not exist.
+    public static func listFiles(at path: String, showHidden: Bool = false,
+                                 _ each: (String) -> Void) throws(PlaydateError) {
+        let result = withoutActuallyEscaping(each) { each in
+            var callback = each
+            return path.withPlaydateCString { cPath in
+                withUnsafeMutablePointer(to: &callback) { callbackPointer in
+                    fileAPI.pointee.listfiles.unsafelyUnwrapped(cPath, { cName, userdata in
+                        guard let cName, let userdata else { return }
+                        let each = userdata.assumingMemoryBound(to: ((String) -> Void).self).pointee
+                        each(String(playdateCString: cName))
+                    }, callbackPointer, showHidden ? 1 : 0)
+                }
+            }
+        }
+        if result != 0 { throw lastFileError() }
+    }
+
+    /// Information about the file or directory at `path`.
+    public static func stat(_ path: String) throws(PlaydateError) -> Stat {
+        var stat = FileStat()
+        let result = path.withPlaydateCString { fileAPI.pointee.stat.unsafelyUnwrapped($0, &stat) }
+        if result != 0 { throw lastFileError() }
+        return Stat(
+            isDirectory: stat.isdir != 0,
+            size: stat.size,
+            modified: System.DateTime(
+                year: UInt16(stat.m_year), month: UInt8(stat.m_month), day: UInt8(stat.m_day),
+                hour: UInt8(stat.m_hour), minute: UInt8(stat.m_minute), second: UInt8(stat.m_second)))
+    }
+
+    /// Creates a directory (and intermediate directories) in the Data directory.
+    public static func mkdir(_ path: String) throws(PlaydateError) {
+        let result = path.withPlaydateCString { fileAPI.pointee.mkdir.unsafelyUnwrapped($0) }
+        if result != 0 { throw lastFileError() }
+    }
+
+    /// Deletes the file or directory at `path`. Directories require
+    /// `recursive` to be deleted with their contents.
+    public static func unlink(_ path: String, recursive: Bool = false) throws(PlaydateError) {
+        let result = path.withPlaydateCString {
+            fileAPI.pointee.unlink.unsafelyUnwrapped($0, recursive ? 1 : 0)
+        }
+        if result != 0 { throw lastFileError() }
+    }
+
+    /// Renames (moves) a file in the Data directory, overwriting any existing
+    /// file at the destination.
+    public static func rename(from: String, to: String) throws(PlaydateError) {
+        let result = from.withPlaydateCString { cFrom in
+            to.withPlaydateCString { cTo in
+                fileAPI.pointee.rename.unsafelyUnwrapped(cFrom, cTo)
+            }
+        }
+        if result != 0 { throw lastFileError() }
+    }
+
+    // MARK: - Open files
+
+    /// An open file. Wraps `SDFile`. The file is closed on deinit if it has
+    /// not been closed explicitly.
+    public final class Handle {
+        let pointer: UnsafeMutableRawPointer
+        private var isClosed = false
+
+        /// Opens the file at `path`.
+        public init(path: String, mode: Options) throws(PlaydateError) {
+            let pointer = path.withPlaydateCString {
+                fileAPI.pointee.open.unsafelyUnwrapped($0, mode.cValue)
+            }
+            guard let pointer else { throw lastFileError() }
+            self.pointer = pointer
+        }
+
+        deinit {
+            if !isClosed {
+                _ = fileAPI.pointee.close.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// Closes the file. Further operations are invalid.
+        public func close() throws(PlaydateError) {
+            guard !isClosed else { return }
+            isClosed = true
+            if fileAPI.pointee.close.unsafelyUnwrapped(pointer) != 0 { throw lastFileError() }
+        }
+
+        /// Reads up to `buffer.count` bytes into `buffer`. Returns the number
+        /// of bytes read; 0 indicates end of file.
+        public func read(into buffer: UnsafeMutableRawBufferPointer) throws(PlaydateError) -> Int {
+            let result = fileAPI.pointee.read.unsafelyUnwrapped(
+                pointer, buffer.baseAddress, UInt32(buffer.count))
+            if result < 0 { throw lastFileError() }
+            return Int(result)
+        }
+
+        /// Reads up to `length` bytes and returns them.
+        public func read(length: Int) throws(PlaydateError) -> [UInt8] {
+            var bytes = [UInt8](repeating: 0, count: length)
+            let result = bytes.withUnsafeMutableBytes { buffer in
+                fileAPI.pointee.read.unsafelyUnwrapped(pointer, buffer.baseAddress, UInt32(buffer.count))
+            }
+            if result < 0 { throw lastFileError() }
+            bytes.removeLast(length - Int(result))
+            return bytes
+        }
+
+        /// Writes the buffer to the file. Returns the number of bytes written.
+        @discardableResult
+        public func write(_ buffer: UnsafeRawBufferPointer) throws(PlaydateError) -> Int {
+            let result = fileAPI.pointee.write.unsafelyUnwrapped(
+                pointer, buffer.baseAddress, UInt32(buffer.count))
+            if result < 0 { throw lastFileError() }
+            return Int(result)
+        }
+
+        /// Writes the bytes to the file. Returns the number of bytes written.
+        @discardableResult
+        public func write(_ bytes: [UInt8]) throws(PlaydateError) -> Int {
+            let result = bytes.withUnsafeBytes { buffer in
+                fileAPI.pointee.write.unsafelyUnwrapped(pointer, buffer.baseAddress, UInt32(buffer.count))
+            }
+            if result < 0 { throw lastFileError() }
+            return Int(result)
+        }
+
+        /// Writes the string's UTF-8 to the file. Returns the bytes written.
+        @discardableResult
+        public func write(_ string: String) throws(PlaydateError) -> Int {
+            let result = string.withPlaydateUTF8 { bytes, count in
+                fileAPI.pointee.write.unsafelyUnwrapped(pointer, bytes, UInt32(count))
+            }
+            if result < 0 { throw lastFileError() }
+            return Int(result)
+        }
+
+        /// Flushes buffered writes to disk. Returns the bytes written.
+        @discardableResult
+        public func flush() throws(PlaydateError) -> Int {
+            let result = fileAPI.pointee.flush.unsafelyUnwrapped(pointer)
+            if result < 0 { throw lastFileError() }
+            return Int(result)
+        }
+
+        /// The current read/write offset.
+        public func tell() throws(PlaydateError) -> Int {
+            let result = fileAPI.pointee.tell.unsafelyUnwrapped(pointer)
+            if result < 0 { throw lastFileError() }
+            return Int(result)
+        }
+
+        /// Moves the read/write offset to `offset` relative to `origin`.
+        public func seek(to offset: Int, from origin: SeekOrigin = .start) throws(PlaydateError) {
+            if fileAPI.pointee.seek.unsafelyUnwrapped(pointer, Int32(offset), origin.rawValue) != 0 {
+                throw lastFileError()
+            }
+        }
+    }
+}

Sources/PlaydateKit/Graphics.swift

@@ -0,0 +1,423 @@
+//
+//  Graphics.swift
+//  Wraps `playdate->graphics` (pd_api_gfx.h): drawing state, shapes, text,
+//  and raw framebuffer access. Bitmap, font, tilemap, and video wrappers live
+//  in their own files.
+//
+
+internal import CPlaydate
+
+/// The graphics API: drawing, bitmaps, fonts, tilemaps, and video.
+public enum Graphics {}
+
+var gfx: UnsafePointer<playdate_graphics> { Playdate.graphicsAPI.unsafelyUnwrapped }
+
+extension Graphics {
+    // MARK: - Screen constants
+
+    /// The width of the screen in pixels (`LCD_COLUMNS`).
+    public static let columns = 400
+    /// The height of the screen in pixels (`LCD_ROWS`).
+    public static let rows = 240
+    /// The stride of a framebuffer row in bytes (`LCD_ROWSIZE`).
+    public static let rowSize = 52
+
+    // MARK: - Types
+
+    /// An 8×8 two-color pattern: 8 rows of image data followed by 8 rows of mask.
+    public struct Pattern: Sendable {
+        public var bytes: (UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8,
+                           UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8)
+
+        public init(bytes: (UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8,
+                            UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8)) {
+            self.bytes = bytes
+        }
+
+        /// Creates an opaque pattern from 8 rows of image data.
+        public init(rows r: (UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8)) {
+            bytes = (r.0, r.1, r.2, r.3, r.4, r.5, r.6, r.7,
+                     0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff)
+        }
+    }
+
+    /// A drawing color: solid or an 8×8 pattern.
+    public enum Color: Sendable {
+        case black
+        case white
+        case clear
+        case xor
+        case pattern(Pattern)
+
+        /// Materializes the `LCDColor` for the duration of `body`. Pattern
+        /// colors pass a pointer to a temporary, so the value must not be
+        /// stored beyond the call.
+        func withLCDColor<Result>(_ body: (LCDColor) -> Result) -> Result {
+            switch self {
+            case .black: return body(LCDColor(kColorBlack.rawValue))
+            case .white: return body(LCDColor(kColorWhite.rawValue))
+            case .clear: return body(LCDColor(kColorClear.rawValue))
+            case .xor: return body(LCDColor(kColorXOR.rawValue))
+            case .pattern(let pattern):
+                return withUnsafeBytes(of: pattern.bytes) { buffer in
+                    body(LCDColor(UInt(bitPattern: buffer.baseAddress)))
+                }
+            }
+        }
+    }
+
+    /// A solid color, for APIs that cannot take a pattern.
+    public enum SolidColor: UInt32, Sendable {
+        case black = 0
+        case white = 1
+        case clear = 2
+        case xor = 3
+
+        init(_ color: LCDSolidColor) { self = SolidColor(rawValue: UInt32(color.rawValue)) ?? .clear }
+        var cValue: LCDSolidColor { LCDSolidColor(LCDSolidColor.RawValue(rawValue)) }
+    }
+
+    /// How source pixels combine with the destination when drawing.
+    public enum DrawMode: UInt32, Sendable {
+        case copy = 0
+        case whiteTransparent = 1
+        case blackTransparent = 2
+        case fillWhite = 3
+        case fillBlack = 4
+        case xor = 5
+        case nxor = 6
+        case inverted = 7
+
+        init(_ mode: LCDBitmapDrawMode) { self = DrawMode(rawValue: UInt32(mode.rawValue)) ?? .copy }
+        var cValue: LCDBitmapDrawMode { LCDBitmapDrawMode(LCDBitmapDrawMode.RawValue(rawValue)) }
+    }
+
+    /// Mirroring applied when drawing a bitmap.
+    public enum BitmapFlip: UInt32, Sendable {
+        case unflipped = 0
+        case flippedX = 1
+        case flippedY = 2
+        case flippedXY = 3
+
+        init(_ flip: LCDBitmapFlip) { self = BitmapFlip(rawValue: UInt32(flip.rawValue)) ?? .unflipped }
+        var cValue: LCDBitmapFlip { LCDBitmapFlip(LCDBitmapFlip.RawValue(rawValue)) }
+    }
+
+    /// The end cap style used when drawing lines.
+    public enum LineCapStyle: UInt32, Sendable {
+        case butt = 0
+        case square = 1
+        case round = 2
+
+        var cValue: LCDLineCapStyle { LCDLineCapStyle(LCDLineCapStyle.RawValue(rawValue)) }
+    }
+
+    /// The encoding of text passed to the text functions.
+    public enum StringEncoding: UInt32, Sendable {
+        case ascii = 0
+        case utf8 = 1
+        case utf16LittleEndian = 2
+
+        var cValue: PDStringEncoding { PDStringEncoding(PDStringEncoding.RawValue(rawValue)) }
+    }
+
+    /// The winding rule used by `fillPolygon`.
+    public enum PolygonFillRule: UInt32, Sendable {
+        case nonZero = 0
+        case evenOdd = 1
+
+        var cValue: LCDPolygonFillRule { LCDPolygonFillRule(LCDPolygonFillRule.RawValue(rawValue)) }
+    }
+
+    /// How text wraps in `drawText(in:)`.
+    public enum TextWrappingMode: UInt32, Sendable {
+        case clip = 0
+        case character = 1
+        case word = 2
+
+        var cValue: PDTextWrappingMode { PDTextWrappingMode(PDTextWrappingMode.RawValue(rawValue)) }
+    }
+
+    /// Horizontal alignment for `drawText(in:)`.
+    public enum TextAlignment: UInt32, Sendable {
+        case left = 0
+        case center = 1
+        case right = 2
+
+        var cValue: PDTextAlignment { PDTextAlignment(PDTextAlignment.RawValue(rawValue)) }
+    }
+
+    /// An integer rectangle mirroring `LCDRect`. `right` and `bottom` are
+    /// not inclusive.
+    public struct Rect: Sendable {
+        public var left: Int
+        public var right: Int
+        public var top: Int
+        public var bottom: Int
+
+        public init(left: Int, right: Int, top: Int, bottom: Int) {
+            self.left = left
+            self.right = right
+            self.top = top
+            self.bottom = bottom
+        }
+
+        public init(x: Int, y: Int, width: Int, height: Int) {
+            self.init(left: x, right: x + width, top: y, bottom: y + height)
+        }
+
+        init(_ rect: LCDRect) {
+            self.init(left: Int(rect.left), right: Int(rect.right),
+                      top: Int(rect.top), bottom: Int(rect.bottom))
+        }
+
+        var cValue: LCDRect {
+            LCDRect(left: Int32(left), right: Int32(right),
+                    top: Int32(top), bottom: Int32(bottom))
+        }
+
+        public func translated(dx: Int, dy: Int) -> Rect {
+            Rect(left: left + dx, right: right + dx, top: top + dy, bottom: bottom + dy)
+        }
+    }
+
+    // MARK: - Drawing state
+
+    /// Clears the entire display, filling it with `color`.
+    public static func clear(color: Color = .white) {
+        color.withLCDColor { gfx.pointee.clear.unsafelyUnwrapped($0) }
+    }
+
+    /// Sets the background color shown when the display is offset or for
+    /// clear pixels in drawn images.
+    public static func setBackgroundColor(_ color: SolidColor) {
+        gfx.pointee.setBackgroundColor.unsafelyUnwrapped(color.cValue)
+    }
+
+    /// Sets the mode that determines how source pixels combine with the
+    /// destination. Returns the previous mode.
+    @discardableResult
+    public static func setDrawMode(_ mode: DrawMode) -> DrawMode {
+        DrawMode(gfx.pointee.setDrawMode.unsafelyUnwrapped(mode.cValue))
+    }
+
+    /// Offsets all subsequent drawing by (dx, dy).
+    public static func setDrawOffset(dx: Int, dy: Int) {
+        gfx.pointee.setDrawOffset.unsafelyUnwrapped(Int32(dx), Int32(dy))
+    }
+
+    /// Sets the clip rect in world coordinates (affected by the draw offset).
+    public static func setClipRect(x: Int, y: Int, width: Int, height: Int) {
+        gfx.pointee.setClipRect.unsafelyUnwrapped(Int32(x), Int32(y), Int32(width), Int32(height))
+    }
+
+    /// Sets the clip rect in screen coordinates (unaffected by the draw offset).
+    public static func setScreenClipRect(x: Int, y: Int, width: Int, height: Int) {
+        gfx.pointee.setScreenClipRect.unsafelyUnwrapped(Int32(x), Int32(y), Int32(width), Int32(height))
+    }
+
+    public static func clearClipRect() {
+        gfx.pointee.clearClipRect.unsafelyUnwrapped()
+    }
+
+    public static func setLineCapStyle(_ style: LineCapStyle) {
+        gfx.pointee.setLineCapStyle.unsafelyUnwrapped(style.cValue)
+    }
+
+    /// Sets the stencil applied to subsequent drawing. If `tile` is `true`
+    /// the stencil image is tiled, and its width must be a multiple of 32.
+    /// Pass `nil` to clear the stencil.
+    public static func setStencil(_ image: Bitmap?, tile: Bool = false) {
+        gfx.pointee.setStencilImage.unsafelyUnwrapped(image?.pointer, tile ? 1 : 0)
+    }
+
+    /// Pushes a new drawing context targeting `target`, or the display if
+    /// `target` is `nil`.
+    public static func pushContext(_ target: Bitmap? = nil) {
+        gfx.pointee.pushContext.unsafelyUnwrapped(target?.pointer)
+    }
+
+    public static func popContext() {
+        gfx.pointee.popContext.unsafelyUnwrapped()
+    }
+
+    // MARK: - Shapes
+
+    public static func drawLine(x1: Int, y1: Int, x2: Int, y2: Int, width: Int, color: Color) {
+        color.withLCDColor {
+            gfx.pointee.drawLine.unsafelyUnwrapped(Int32(x1), Int32(y1), Int32(x2), Int32(y2), Int32(width), $0)
+        }
+    }
+
+    public static func fillTriangle(x1: Int, y1: Int, x2: Int, y2: Int, x3: Int, y3: Int, color: Color) {
+        color.withLCDColor {
+            gfx.pointee.fillTriangle.unsafelyUnwrapped(Int32(x1), Int32(y1), Int32(x2), Int32(y2),
+                                               Int32(x3), Int32(y3), $0)
+        }
+    }
+
+    public static func drawRect(x: Int, y: Int, width: Int, height: Int, color: Color) {
+        color.withLCDColor {
+            gfx.pointee.drawRect.unsafelyUnwrapped(Int32(x), Int32(y), Int32(width), Int32(height), $0)
+        }
+    }
+
+    public static func fillRect(x: Int, y: Int, width: Int, height: Int, color: Color) {
+        color.withLCDColor {
+            gfx.pointee.fillRect.unsafelyUnwrapped(Int32(x), Int32(y), Int32(width), Int32(height), $0)
+        }
+    }
+
+    public static func drawRoundRect(x: Int, y: Int, width: Int, height: Int, radius: Int,
+                                     lineWidth: Int, color: Color) {
+        color.withLCDColor {
+            gfx.pointee.drawRoundRect.unsafelyUnwrapped(Int32(x), Int32(y), Int32(width), Int32(height),
+                                                Int32(radius), Int32(lineWidth), $0)
+        }
+    }
+
+    public static func fillRoundRect(x: Int, y: Int, width: Int, height: Int, radius: Int, color: Color) {
+        color.withLCDColor {
+            gfx.pointee.fillRoundRect.unsafelyUnwrapped(Int32(x), Int32(y), Int32(width), Int32(height),
+                                                Int32(radius), $0)
+        }
+    }
+
+    /// Draws an ellipse stroked inside the rect. If the angles differ, draws
+    /// an arc from `startAngle` to `endAngle` (clockwise degrees, 0 at top).
+    public static func drawEllipse(x: Int, y: Int, width: Int, height: Int, lineWidth: Int,
+                                   startAngle: Float = 0, endAngle: Float = 0, color: Color) {
+        color.withLCDColor {
+            gfx.pointee.drawEllipse.unsafelyUnwrapped(Int32(x), Int32(y), Int32(width), Int32(height),
+                                              Int32(lineWidth), startAngle, endAngle, $0)
+        }
+    }
+
+    public static func fillEllipse(x: Int, y: Int, width: Int, height: Int,
+                                   startAngle: Float = 0, endAngle: Float = 0, color: Color) {
+        color.withLCDColor {
+            gfx.pointee.fillEllipse.unsafelyUnwrapped(Int32(x), Int32(y), Int32(width), Int32(height),
+                                              startAngle, endAngle, $0)
+        }
+    }
+
+    /// Fills the polygon described by the points, connecting the last point
+    /// back to the first.
+    public static func fillPolygon(points: [(x: Int, y: Int)], color: Color,
+                                   fillRule: PolygonFillRule = .nonZero) {
+        withUnsafeTemporaryAllocation(of: Int32.self, capacity: points.count * 2) { coordinates in
+            var index = 0
+            for point in points {
+                coordinates[index] = Int32(point.x)
+                coordinates[index + 1] = Int32(point.y)
+                index += 2
+            }
+            color.withLCDColor { cColor in
+                gfx.pointee.fillPolygon.unsafelyUnwrapped(Int32(points.count), coordinates.baseAddress,
+                                                  cColor, fillRule.cValue)
+            }
+        }
+    }
+
+    /// Sets the pixel at (x, y) in the current drawing context.
+    public static func setPixel(x: Int, y: Int, color: Color) {
+        color.withLCDColor { gfx.pointee.setPixel.unsafelyUnwrapped(Int32(x), Int32(y), $0) }
+    }
+
+    /// Reads an 8×8 pattern from the bitmap starting at (x, y).
+    public static func colorToPattern(from bitmap: Bitmap, x: Int, y: Int) -> Pattern {
+        var color: LCDColor = 0
+        gfx.pointee.setColorToPattern.unsafelyUnwrapped(&color, bitmap.pointer, Int32(x), Int32(y))
+        var pattern = Pattern(bytes: (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0))
+        if let source = UnsafeRawPointer(bitPattern: UInt(color)) {
+            withUnsafeMutableBytes(of: &pattern.bytes) { destination in
+                destination.copyMemory(from: UnsafeRawBufferPointer(start: source, count: 16))
+            }
+        }
+        return pattern
+    }
+
+    // MARK: - Text
+
+    /// Draws `text` at (x, y) using the current font. Returns the drawn width.
+    @discardableResult
+    public static func drawText(_ text: String, x: Int, y: Int) -> Int {
+        text.withPlaydateUTF8 { bytes, count in
+            Int(gfx.pointee.drawText.unsafelyUnwrapped(bytes, count,
+                                                       kUTF8Encoding, Int32(x), Int32(y)))
+        }
+    }
+
+    /// Draws `text` wrapped and aligned inside the given rectangle.
+    public static func drawText(_ text: String, x: Int, y: Int, width: Int, height: Int,
+                                wrap: TextWrappingMode = .word, align: TextAlignment = .left) {
+        text.withPlaydateUTF8 { bytes, count in
+            gfx.pointee.drawTextInRect.unsafelyUnwrapped(bytes, count, kUTF8Encoding,
+                                                         Int32(x), Int32(y), Int32(width), Int32(height),
+                                                         wrap.cValue, align.cValue)
+        }
+    }
+
+    /// Sets the font used by subsequent text drawing.
+    public static func setFont(_ font: Font) {
+        gfx.pointee.setFont.unsafelyUnwrapped(font.pointer)
+    }
+
+    /// Extra space added between letters, in pixels.
+    public static func setTextTracking(_ tracking: Int) {
+        gfx.pointee.setTextTracking.unsafelyUnwrapped(Int32(tracking))
+    }
+
+    public static var textTracking: Int {
+        Int(gfx.pointee.getTextTracking.unsafelyUnwrapped())
+    }
+
+    /// Adjusts the line height used when drawing multi-line text.
+    public static func setTextLeading(_ lineHeightAdjustment: Int) {
+        gfx.pointee.setTextLeading.unsafelyUnwrapped(Int32(lineHeightAdjustment))
+    }
+
+    // MARK: - Framebuffer
+
+    /// The current working framebuffer. Rows are `rowSize` bytes.
+    /// Call `markUpdatedRows(from:to:)` after writing directly.
+    public static var frame: UnsafeMutablePointer<UInt8>? {
+        gfx.pointee.getFrame.unsafelyUnwrapped()
+    }
+
+    /// The framebuffer currently shown on the display. Rows are `rowSize` bytes.
+    public static var displayFrame: UnsafeMutablePointer<UInt8>? {
+        gfx.pointee.getDisplayFrame.unsafelyUnwrapped()
+    }
+
+    /// A bitmap view of the display framebuffer. Simulator only; `nil` on device.
+    public static var debugBitmap: Bitmap? {
+        guard let getDebugBitmap = gfx.pointee.getDebugBitmap,
+              let pointer = getDebugBitmap() else { return nil }
+        return Bitmap(pointer: pointer, isOwned: false)
+    }
+
+    /// A bitmap referencing the display framebuffer (not a copy).
+    public static var displayBufferBitmap: Bitmap? {
+        guard let pointer = gfx.pointee.getDisplayBufferBitmap.unsafelyUnwrapped() else { return nil }
+        return Bitmap(pointer: pointer, isOwned: false)
+    }
+
+    /// A copy of the working framebuffer as a new bitmap.
+    public static func copyFrameBufferBitmap() -> Bitmap? {
+        guard let pointer = gfx.pointee.copyFrameBufferBitmap.unsafelyUnwrapped() else { return nil }
+        return Bitmap(pointer: pointer, isOwned: true)
+    }
+
+    /// Tells the system which rows (inclusive) were changed by direct
+    /// framebuffer writes and need redisplay.
+    public static func markUpdatedRows(from start: Int, to end: Int) {
+        gfx.pointee.markUpdatedRows.unsafelyUnwrapped(Int32(start), Int32(end))
+    }
+
+    /// Manually flushes the framebuffer to the display. Only needed when
+    /// drawing outside the normal update cycle.
+    public static func display() {
+        gfx.pointee.display.unsafelyUnwrapped()
+    }
+}

Sources/PlaydateKit/GraphicsBitmap.swift

@@ -0,0 +1,221 @@
+//
+//  GraphicsBitmap.swift
+//  Bitmap and BitmapTable wrappers around LCDBitmap / LCDBitmapTable.
+//
+
+internal import CPlaydate
+
+extension Graphics {
+    /// An image that can be drawn to the screen or used as a drawing target.
+    /// Wraps `LCDBitmap`.
+    public final class Bitmap {
+        let pointer: OpaquePointer
+        /// Whether this wrapper owns the underlying `LCDBitmap` and frees it
+        /// on deinit. Bitmaps vended by tables or the system are not owned;
+        /// keep their owner alive while using them.
+        let isOwned: Bool
+
+        init(pointer: OpaquePointer, isOwned: Bool) {
+            self.pointer = pointer
+            self.isOwned = isOwned
+        }
+
+        /// Allocates a new bitmap filled with `backgroundColor`.
+        public convenience init(width: Int, height: Int, backgroundColor: Color = .clear) {
+            let pointer = backgroundColor.withLCDColor {
+                gfx.pointee.newBitmap.unsafelyUnwrapped(Int32(width), Int32(height), $0)
+            }
+            self.init(pointer: pointer.unsafelyUnwrapped, isOwned: true)
+        }
+
+        /// Loads a bitmap from a file in the game's pdx or Data directory.
+        public convenience init(path: String) throws(PlaydateError) {
+            var error: UnsafePointer<CChar>?
+            let pointer = path.withPlaydateCString { gfx.pointee.loadBitmap.unsafelyUnwrapped($0, &error) }
+            guard let pointer else { throw PlaydateError(cString: error) }
+            self.init(pointer: pointer, isOwned: true)
+        }
+
+        deinit {
+            if isOwned {
+                gfx.pointee.freeBitmap.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        // MARK: Properties
+
+        /// The bitmap's dimensions, row stride, and raw pixel/mask storage.
+        /// The pointers are owned by the bitmap.
+        public struct Data {
+            public let width: Int
+            public let height: Int
+            public let rowBytes: Int
+            public let mask: UnsafeMutablePointer<UInt8>?
+            public let data: UnsafeMutablePointer<UInt8>?
+        }
+
+        public var data: Data {
+            var width: Int32 = 0, height: Int32 = 0, rowBytes: Int32 = 0
+            var mask: UnsafeMutablePointer<UInt8>?
+            var data: UnsafeMutablePointer<UInt8>?
+            gfx.pointee.getBitmapData.unsafelyUnwrapped(pointer, &width, &height, &rowBytes, &mask, &data)
+            return Data(width: Int(width), height: Int(height), rowBytes: Int(rowBytes),
+                        mask: mask, data: data)
+        }
+
+        /// Cached dimensions, so `width`/`height` don't pay a full
+        /// `getBitmapData` round-trip per access. Only `load(path:)` can
+        /// change a bitmap's size, which resets the cache.
+        private var cachedSize: (width: Int, height: Int)?
+
+        private var size: (width: Int, height: Int) {
+            if let cachedSize { return cachedSize }
+            let data = self.data
+            let size = (data.width, data.height)
+            cachedSize = size
+            return size
+        }
+
+        public var width: Int { size.width }
+        public var height: Int { size.height }
+
+        /// The color of the pixel at (x, y).
+        public func pixel(x: Int, y: Int) -> SolidColor {
+            SolidColor(gfx.pointee.getBitmapPixel.unsafelyUnwrapped(pointer, Int32(x), Int32(y)))
+        }
+
+        // MARK: Operations
+
+        /// Replaces the bitmap's contents with the image at `path`.
+        public func load(path: String) throws(PlaydateError) {
+            var error: UnsafePointer<CChar>?
+            path.withPlaydateCString { gfx.pointee.loadIntoBitmap.unsafelyUnwrapped($0, pointer, &error) }
+            cachedSize = nil
+            if let error { throw PlaydateError(cString: error) }
+        }
+
+        /// Fills the bitmap with `color`.
+        public func clear(color: Color) {
+            color.withLCDColor { gfx.pointee.clearBitmap.unsafelyUnwrapped(pointer, $0) }
+        }
+
+        public func copy() -> Bitmap {
+            Bitmap(pointer: gfx.pointee.copyBitmap.unsafelyUnwrapped(pointer).unsafelyUnwrapped, isOwned: true)
+        }
+
+        /// Returns a new bitmap rotated by `degrees` (clockwise) and scaled.
+        public func rotated(by degrees: Float, xScale: Float = 1, yScale: Float = 1) -> Bitmap? {
+            var allocatedSize: Int32 = 0
+            guard let rotated = gfx.pointee.rotatedBitmap.unsafelyUnwrapped(
+                pointer, degrees, xScale, yScale, &allocatedSize) else { return nil }
+            return Bitmap(pointer: rotated, isOwned: true)
+        }
+
+        /// Sets a mask image. The mask must match the bitmap's dimensions.
+        @discardableResult
+        public func setMask(_ mask: Bitmap?) -> Bool {
+            gfx.pointee.setBitmapMask.unsafelyUnwrapped(pointer, mask?.pointer) != 0
+        }
+
+        /// The bitmap's mask, if any. The returned bitmap references storage
+        /// owned by this bitmap.
+        public var mask: Bitmap? {
+            guard let mask = gfx.pointee.getBitmapMask.unsafelyUnwrapped(pointer) else { return nil }
+            return Bitmap(pointer: mask, isOwned: false)
+        }
+
+        /// Tests whether the opaque pixels of two bitmaps overlap within
+        /// `rect`, given each bitmap's position and flip.
+        public func checkMaskCollision(x: Int, y: Int, flip: BitmapFlip = .unflipped,
+                                       other: Bitmap, otherX: Int, otherY: Int,
+                                       otherFlip: BitmapFlip = .unflipped,
+                                       in rect: Rect) -> Bool {
+            gfx.pointee.checkMaskCollision.unsafelyUnwrapped(
+                pointer, Int32(x), Int32(y), flip.cValue,
+                other.pointer, Int32(otherX), Int32(otherY), otherFlip.cValue,
+                rect.cValue) != 0
+        }
+
+        // MARK: Drawing
+
+        /// Draws the bitmap with its upper-left corner at (x, y).
+        public func draw(x: Int, y: Int, flip: BitmapFlip = .unflipped) {
+            gfx.pointee.drawBitmap.unsafelyUnwrapped(pointer, Int32(x), Int32(y), flip.cValue)
+        }
+
+        /// Draws the bitmap scaled by (xScale, yScale) with its upper-left
+        /// corner at (x, y).
+        public func drawScaled(x: Int, y: Int, xScale: Float, yScale: Float) {
+            gfx.pointee.drawScaledBitmap.unsafelyUnwrapped(pointer, Int32(x), Int32(y), xScale, yScale)
+        }
+
+        /// Draws the bitmap rotated by `degrees` around its anchor point,
+        /// where (0.5, 0.5) is the center.
+        public func drawRotated(x: Int, y: Int, degrees: Float,
+                                centerX: Float = 0.5, centerY: Float = 0.5,
+                                xScale: Float = 1, yScale: Float = 1) {
+            gfx.pointee.drawRotatedBitmap.unsafelyUnwrapped(pointer, Int32(x), Int32(y), degrees,
+                                                    centerX, centerY, xScale, yScale)
+        }
+
+        /// Tiles the bitmap over the given area.
+        public func tile(x: Int, y: Int, width: Int, height: Int, flip: BitmapFlip = .unflipped) {
+            gfx.pointee.tileBitmap.unsafelyUnwrapped(pointer, Int32(x), Int32(y),
+                                             Int32(width), Int32(height), flip.cValue)
+        }
+    }
+
+    /// A collection of bitmaps loaded from an image table. Wraps `LCDBitmapTable`.
+    public final class BitmapTable {
+        let pointer: OpaquePointer
+
+        init(pointer: OpaquePointer) {
+            self.pointer = pointer
+        }
+
+        /// Allocates a table with room for `count` bitmaps of the given size.
+        public convenience init(count: Int, width: Int, height: Int) {
+            let pointer = gfx.pointee.newBitmapTable.unsafelyUnwrapped(Int32(count), Int32(width), Int32(height))
+            self.init(pointer: pointer.unsafelyUnwrapped)
+        }
+
+        /// Loads an image table from a file.
+        public convenience init(path: String) throws(PlaydateError) {
+            var error: UnsafePointer<CChar>?
+            let pointer = path.withPlaydateCString { gfx.pointee.loadBitmapTable.unsafelyUnwrapped($0, &error) }
+            guard let pointer else { throw PlaydateError(cString: error) }
+            self.init(pointer: pointer)
+        }
+
+        deinit {
+            gfx.pointee.freeBitmapTable.unsafelyUnwrapped(pointer)
+        }
+
+        /// Replaces the table's contents with the image table at `path`.
+        public func load(path: String) throws(PlaydateError) {
+            var error: UnsafePointer<CChar>?
+            path.withPlaydateCString { gfx.pointee.loadIntoBitmapTable.unsafelyUnwrapped($0, pointer, &error) }
+            if let error { throw PlaydateError(cString: error) }
+        }
+
+        /// The bitmap at `index`, or `nil` if out of range. The bitmap
+        /// references storage owned by the table; keep the table alive while
+        /// using it.
+        public func bitmap(at index: Int) -> Bitmap? {
+            guard let bitmap = gfx.pointee.getTableBitmap.unsafelyUnwrapped(pointer, Int32(index)) else {
+                return nil
+            }
+            return Bitmap(pointer: bitmap, isOwned: false)
+        }
+
+        /// The number of bitmaps in the table and the number of cells per row
+        /// of the source image.
+        public var info: (count: Int, cellsWide: Int) {
+            var count: Int32 = 0, width: Int32 = 0
+            gfx.pointee.getBitmapTableInfo.unsafelyUnwrapped(pointer, &count, &width)
+            return (Int(count), Int(width))
+        }
+
+        public var count: Int { info.count }
+    }
+}

Sources/PlaydateKit/GraphicsFont.swift

@@ -0,0 +1,123 @@
+//
+//  GraphicsFont.swift
+//  Font, FontPage, and Glyph wrappers around LCDFont / LCDFontPage / LCDFontGlyph.
+//
+
+internal import CPlaydate
+
+extension Graphics {
+    /// A font loaded from a .pft file. Wraps `LCDFont`.
+    public final class Font {
+        let pointer: OpaquePointer
+        /// Fonts created from in-memory data reference that data; it is kept
+        /// alive here.
+        private let retainedData: UnsafeRawPointer?
+
+        init(pointer: OpaquePointer, retainedData: UnsafeRawPointer? = nil) {
+            self.pointer = pointer
+            self.retainedData = retainedData
+        }
+
+        /// Loads a font from a file.
+        public convenience init(path: String) throws(PlaydateError) {
+            var error: UnsafePointer<CChar>?
+            let pointer = path.withPlaydateCString { gfx.pointee.loadFont.unsafelyUnwrapped($0, &error) }
+            guard let pointer else { throw PlaydateError(cString: error) }
+            self.init(pointer: pointer)
+        }
+
+        /// Creates a font from the contents of a .pft file already in memory.
+        /// The bytes are copied and retained for the font's lifetime.
+        public convenience init?(data: UnsafeRawBufferPointer, wide: Bool = false) {
+            let copy = UnsafeMutableRawPointer.allocate(byteCount: data.count, alignment: 4)
+            copy.copyMemory(from: data.baseAddress.unsafelyUnwrapped, byteCount: data.count)
+            let fontData = OpaquePointer(copy)
+            guard let pointer = gfx.pointee.makeFontFromData.unsafelyUnwrapped(
+                fontData, wide ? 1 : 0, Int32(data.count)) else {
+                copy.deallocate()
+                return nil
+            }
+            self.init(pointer: pointer, retainedData: UnsafeRawPointer(copy))
+        }
+
+        deinit {
+            // Per the C API docs, fonts are freed with the system allocator.
+            System.systemFree(UnsafeMutableRawPointer(pointer))
+            retainedData?.deallocate()
+        }
+
+        /// The font's glyph height in pixels.
+        public var height: Int {
+            Int(gfx.pointee.getFontHeight.unsafelyUnwrapped(pointer))
+        }
+
+        /// The width of `text` when drawn with this font.
+        public func textWidth(_ text: String, tracking: Int = 0) -> Int {
+            text.withPlaydateUTF8 { bytes, count in
+                Int(gfx.pointee.getTextWidth.unsafelyUnwrapped(pointer, bytes, count,
+                                                               kUTF8Encoding, Int32(tracking)))
+            }
+        }
+
+        /// The height of `text` when wrapped to `maxWidth` with this font.
+        public func textHeight(_ text: String, maxWidth: Int, wrap: TextWrappingMode = .word,
+                               tracking: Int = 0, extraLeading: Int = 0) -> Int {
+            text.withPlaydateUTF8 { bytes, count in
+                Int(gfx.pointee.getTextHeightForMaxWidth.unsafelyUnwrapped(
+                    pointer, bytes, count, Int32(maxWidth), kUTF8Encoding,
+                    wrap.cValue, Int32(tracking), Int32(extraLeading)))
+            }
+        }
+
+        /// The page containing glyph data for the character `codepoint`
+        /// belongs to. The page references data owned by the font.
+        public func page(for codepoint: UInt32) -> FontPage? {
+            guard let page = gfx.pointee.getFontPage.unsafelyUnwrapped(pointer, codepoint) else { return nil }
+            return FontPage(pointer: page, font: self)
+        }
+
+        /// The glyph for `codepoint`, with its bitmap and advance.
+        /// The bitmap references data owned by the font.
+        public func glyph(for codepoint: UInt32) -> (glyph: Glyph, bitmap: Bitmap?, advance: Int)? {
+            var bitmap: OpaquePointer?
+            var advance: Int32 = 0
+            guard let glyph = gfx.pointee.getFontGlyph.unsafelyUnwrapped(pointer, codepoint, &bitmap, &advance) else {
+                return nil
+            }
+            return (Glyph(pointer: glyph, font: self),
+                    bitmap.map { Bitmap(pointer: $0, isOwned: false) },
+                    Int(advance))
+        }
+    }
+
+    /// A page of glyphs within a font. Wraps `LCDFontPage`.
+    /// Keep the font alive while using its pages.
+    public struct FontPage {
+        let pointer: OpaquePointer
+        let font: Font
+
+        /// The glyph for `codepoint` within this page, with its bitmap and advance.
+        public func glyph(for codepoint: UInt32) -> (glyph: Glyph, bitmap: Bitmap?, advance: Int)? {
+            var bitmap: OpaquePointer?
+            var advance: Int32 = 0
+            guard let glyph = gfx.pointee.getPageGlyph.unsafelyUnwrapped(pointer, codepoint, &bitmap, &advance) else {
+                return nil
+            }
+            return (Glyph(pointer: glyph, font: font),
+                    bitmap.map { Bitmap(pointer: $0, isOwned: false) },
+                    Int(advance))
+        }
+    }
+
+    /// A single glyph within a font. Wraps `LCDFontGlyph`.
+    /// Keep the font alive while using its glyphs.
+    public struct Glyph {
+        let pointer: OpaquePointer
+        let font: Font
+
+        /// The kerning adjustment between this glyph and the next character.
+        public func kerning(glyphCode: UInt32, nextCode: UInt32) -> Int {
+            Int(gfx.pointee.getGlyphKerning.unsafelyUnwrapped(pointer, glyphCode, nextCode))
+        }
+    }
+}

Sources/PlaydateKit/GraphicsTileMap.swift

@@ -0,0 +1,79 @@
+//
+//  GraphicsTileMap.swift
+//  TileMap wrapper around LCDTileMap (playdate->graphics->tilemap).
+//
+
+internal import CPlaydate
+
+private var tilemapAPI: UnsafePointer<playdate_tilemap> { Playdate.tilemapAPI.unsafelyUnwrapped }
+
+extension Graphics {
+    /// A grid of tiles drawn from a bitmap table. Wraps `LCDTileMap`.
+    public final class TileMap {
+        let pointer: OpaquePointer
+        /// The image table is retained so the tilemap's tiles stay valid.
+        private var retainedImageTable: BitmapTable?
+
+        public init() {
+            pointer = tilemapAPI.pointee.newTilemap.unsafelyUnwrapped().unsafelyUnwrapped
+        }
+
+        deinit {
+            tilemapAPI.pointee.freeTilemap.unsafelyUnwrapped(pointer)
+        }
+
+        /// The bitmap table the tile indexes refer to.
+        public var imageTable: BitmapTable? {
+            get { retainedImageTable }
+            set {
+                retainedImageTable = newValue
+                tilemapAPI.pointee.setImageTable.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+
+        /// Sets the tilemap's size in tiles.
+        public func setSize(tilesWide: Int, tilesHigh: Int) {
+            tilemapAPI.pointee.setSize.unsafelyUnwrapped(pointer, Int32(tilesWide), Int32(tilesHigh))
+        }
+
+        /// The tilemap's size in tiles.
+        public var size: (tilesWide: Int, tilesHigh: Int) {
+            var wide: Int32 = 0, high: Int32 = 0
+            tilemapAPI.pointee.getSize.unsafelyUnwrapped(pointer, &wide, &high)
+            return (Int(wide), Int(high))
+        }
+
+        /// The tilemap's total size in pixels.
+        public var pixelSize: (width: Int, height: Int) {
+            var width: UInt32 = 0, height: UInt32 = 0
+            tilemapAPI.pointee.getPixelSize.unsafelyUnwrapped(pointer, &width, &height)
+            return (Int(width), Int(height))
+        }
+
+        /// Fills the tilemap with `indexes`, `rowWidth` tiles per row. The
+        /// tilemap is resized to fit.
+        public func setTiles(_ indexes: [UInt16], rowWidth: Int) {
+            var indexes = indexes
+            indexes.withUnsafeMutableBufferPointer { buffer in
+                tilemapAPI.pointee.setTiles.unsafelyUnwrapped(pointer, buffer.baseAddress,
+                                                      Int32(buffer.count), Int32(rowWidth))
+            }
+        }
+
+        /// Sets the tile index at position (x, y).
+        public func setTile(x: Int, y: Int, index: UInt16) {
+            tilemapAPI.pointee.setTileAtPosition.unsafelyUnwrapped(pointer, Int32(x), Int32(y), index)
+        }
+
+        /// The tile index at position (x, y), or `nil` if out of bounds.
+        public func tile(x: Int, y: Int) -> Int? {
+            let index = tilemapAPI.pointee.getTileAtPosition.unsafelyUnwrapped(pointer, Int32(x), Int32(y))
+            return index < 0 ? nil : Int(index)
+        }
+
+        /// Draws the tilemap with its upper-left corner at (x, y).
+        public func draw(x: Float, y: Float) {
+            tilemapAPI.pointee.drawAtPoint.unsafelyUnwrapped(pointer, x, y)
+        }
+    }
+}

Sources/PlaydateKit/GraphicsVideo.swift

@@ -0,0 +1,160 @@
+//
+//  GraphicsVideo.swift
+//  VideoPlayer and StreamPlayer wrappers around LCDVideoPlayer /
+//  LCDStreamPlayer (playdate->graphics->video / ->videostream).
+//
+
+internal import CPlaydate
+
+private var videoAPI: UnsafePointer<playdate_video> { Playdate.videoAPI.unsafelyUnwrapped }
+private var streamAPI: UnsafePointer<playdate_videostream> { Playdate.videoStreamAPI.unsafelyUnwrapped }
+
+extension Graphics {
+    /// Plays .pdv video files. Wraps `LCDVideoPlayer`.
+    public final class VideoPlayer {
+        let pointer: OpaquePointer
+        let isOwned: Bool
+        /// Retains the render context bitmap while the player uses it.
+        private var retainedContext: Bitmap?
+
+        init(pointer: OpaquePointer, isOwned: Bool) {
+            self.pointer = pointer
+            self.isOwned = isOwned
+        }
+
+        /// Opens the .pdv file at `path`.
+        public convenience init(path: String) throws(PlaydateError) {
+            let pointer = path.withPlaydateCString { videoAPI.pointee.loadVideo.unsafelyUnwrapped($0) }
+            guard let pointer else {
+                throw PlaydateError(message: "unable to load video: \(path)")
+            }
+            self.init(pointer: pointer, isOwned: true)
+        }
+
+        deinit {
+            if isOwned {
+                videoAPI.pointee.freePlayer.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// Sets the bitmap the video renders into.
+        public func setContext(_ context: Bitmap) throws(PlaydateError) {
+            guard videoAPI.pointee.setContext.unsafelyUnwrapped(pointer, context.pointer) != 0 else {
+                throw PlaydateError(message: error ?? "unable to set video context")
+            }
+            retainedContext = context
+        }
+
+        /// The bitmap the video renders into.
+        public var context: Bitmap? {
+            guard let context = videoAPI.pointee.getContext.unsafelyUnwrapped(pointer) else { return nil }
+            return Bitmap(pointer: context, isOwned: false)
+        }
+
+        /// Renders directly into the display framebuffer.
+        public func useScreenContext() {
+            retainedContext = nil
+            videoAPI.pointee.useScreenContext.unsafelyUnwrapped(pointer)
+        }
+
+        /// Renders frame `frame` into the current context.
+        public func renderFrame(_ frame: Int) throws(PlaydateError) {
+            guard videoAPI.pointee.renderFrame.unsafelyUnwrapped(pointer, Int32(frame)) != 0 else {
+                // Static message: the caller knows the frame it passed, and
+                // interpolating it would pull integer formatting machinery
+                // into the device binary.
+                throw PlaydateError(message: error ?? "unable to render frame")
+            }
+        }
+
+        /// The most recent error message, if any.
+        public var error: String? {
+            String(playdateCString: videoAPI.pointee.getError.unsafelyUnwrapped(pointer))
+        }
+
+        /// The video's dimensions, frame rate, frame count, and current frame.
+        public var info: (width: Int, height: Int, frameRate: Float, frameCount: Int, currentFrame: Int) {
+            var width: Int32 = 0, height: Int32 = 0, frameCount: Int32 = 0, currentFrame: Int32 = 0
+            var frameRate: Float = 0
+            videoAPI.pointee.getInfo.unsafelyUnwrapped(pointer, &width, &height, &frameRate,
+                                               &frameCount, &currentFrame)
+            return (Int(width), Int(height), frameRate, Int(frameCount), Int(currentFrame))
+        }
+    }
+
+    /// Streams video (and audio) from a file or network connection.
+    /// Wraps `LCDStreamPlayer`.
+    public final class StreamPlayer {
+        let pointer: OpaquePointer
+        /// Retains the active source so it outlives the stream.
+        private var retainedSource: AnyObject?
+
+        public init() {
+            pointer = streamAPI.pointee.newPlayer.unsafelyUnwrapped().unsafelyUnwrapped
+        }
+
+        deinit {
+            streamAPI.pointee.freePlayer.unsafelyUnwrapped(pointer)
+        }
+
+        /// Sets the sizes of the stream's video and audio buffers, in bytes.
+        public func setBufferSize(video: Int, audio: Int) {
+            streamAPI.pointee.setBufferSize.unsafelyUnwrapped(pointer, Int32(video), Int32(audio))
+        }
+
+        /// Streams from an open file.
+        public func setFile(_ file: File.Handle) {
+            retainedSource = file
+            streamAPI.pointee.setFile.unsafelyUnwrapped(pointer, file.pointer)
+        }
+
+        /// Streams from an HTTP connection.
+        public func setHTTPConnection(_ connection: Network.HTTPConnection) {
+            retainedSource = connection
+            streamAPI.pointee.setHTTPConnection.unsafelyUnwrapped(pointer, connection.pointer)
+        }
+
+        /// Streams from a TCP connection.
+        public func setTCPConnection(_ connection: Network.TCPConnection) {
+            retainedSource = connection
+            streamAPI.pointee.setTCPConnection.unsafelyUnwrapped(pointer, connection.pointer)
+        }
+
+        /// The player used for the stream's audio track. Owned by the stream.
+        /// The same wrapper is returned on every access, so callbacks
+        /// registered on it stay valid for the stream's lifetime.
+        public var filePlayer: Sound.FilePlayer? {
+            guard let player = streamAPI.pointee.getFilePlayer.unsafelyUnwrapped(pointer) else { return nil }
+            if let cached = cachedFilePlayer, cached.pointer == player {
+                return cached
+            }
+            let wrapper = Sound.FilePlayer(pointer: player, isOwned: false)
+            cachedFilePlayer = wrapper
+            return wrapper
+        }
+
+        private var cachedFilePlayer: Sound.FilePlayer?
+
+        /// The player used for the stream's video track. Owned by the stream.
+        public var videoPlayer: VideoPlayer? {
+            guard let player = streamAPI.pointee.getVideoPlayer.unsafelyUnwrapped(pointer) else { return nil }
+            return VideoPlayer(pointer: player, isOwned: false)
+        }
+
+        /// Advances the stream. Returns `true` if a frame was drawn.
+        @discardableResult
+        public func update() -> Bool {
+            streamAPI.pointee.update.unsafelyUnwrapped(pointer)
+        }
+
+        /// The number of video frames currently buffered.
+        public var bufferedFrameCount: Int {
+            Int(streamAPI.pointee.getBufferedFrameCount.unsafelyUnwrapped(pointer))
+        }
+
+        /// The total number of bytes read from the source.
+        public var bytesRead: UInt32 {
+            streamAPI.pointee.getBytesRead.unsafelyUnwrapped(pointer)
+        }
+    }
+}

Sources/PlaydateKit/JSON.swift

@@ -0,0 +1,295 @@
+//
+//  JSON.swift
+//  Wraps `playdate->json` (pd_api_json.h).
+//
+//  The C decoder is callback-based; this wrapper drives it to build a
+//  complete `Value` tree. The encoder is exposed both as a streaming
+//  `Encoder` and as a one-shot `encode(_:)` of a `Value`.
+//
+
+internal import CPlaydate
+
+private var jsonAPI: UnsafePointer<playdate_json> { Playdate.jsonAPI.unsafelyUnwrapped }
+
+/// The JSON API: decoding to and encoding from a `Value` tree.
+public enum JSON {}
+
+extension JSON {
+    /// A decoded JSON value.
+    public indirect enum Value {
+        case null
+        case bool(Bool)
+        case int(Int)
+        case float(Float)
+        case string(String)
+        case array([Value])
+        case table([String: Value])
+    }
+
+    // MARK: - Decoding
+
+    private final class ValueBox {
+        var value: Value
+        init(_ value: Value) { self.value = value }
+    }
+
+    /// A container under construction. A class, so appends mutate uniquely
+    /// referenced storage in place instead of copying the collection out of
+    /// and back into an enum payload on every element.
+    private final class Container {
+        let isArray: Bool
+        var items: [Value] = []
+        var entries: [String: Value] = [:]
+
+        init(isArray: Bool) { self.isArray = isArray }
+
+        var value: Value { isArray ? .array(items) : .table(entries) }
+    }
+
+    private final class DecodeContext {
+        /// Containers under construction, innermost last.
+        var stack: [Container] = []
+        var errorMessage: String?
+        var errorLine: Int32 = 0
+
+        func append(_ value: Value, key: String?) {
+            guard let container = stack.last else { return }
+            if container.isArray {
+                container.items.append(value)
+            } else if let key {
+                container.entries[key] = value
+            }
+        }
+    }
+
+    /// Converts a C `json_value`, consuming any container box it references.
+    private static func convert(_ value: json_value) -> Value {
+        switch UInt32(bitPattern: Int32(value.type)) {
+        case UInt32(kJSONTrue.rawValue): return .bool(true)
+        case UInt32(kJSONFalse.rawValue): return .bool(false)
+        case UInt32(kJSONInteger.rawValue): return .int(Int(value.data.intval))
+        case UInt32(kJSONFloat.rawValue): return .float(value.data.floatval)
+        case UInt32(kJSONString.rawValue): return .string(String(playdateCString: value.data.stringval) ?? "")
+        case UInt32(kJSONArray.rawValue), UInt32(kJSONTable.rawValue):
+            guard let pointer = value.data.arrayval else { return .null }
+            return Unmanaged<ValueBox>.fromOpaque(pointer).takeRetainedValue().value
+        default: return .null
+        }
+    }
+
+    private static func makeDecoder(context: Unmanaged<DecodeContext>) -> json_decoder {
+        var decoder = json_decoder()
+        decoder.userdata = context.toOpaque()
+        decoder.decodeError = { decoder, error, linenum in
+            guard let userdata = decoder?.pointee.userdata else { return }
+            let context = Unmanaged<DecodeContext>.fromOpaque(userdata).takeUnretainedValue()
+            context.errorMessage = String(playdateCString: error)
+            context.errorLine = linenum
+        }
+        decoder.willDecodeSublist = { decoder, _, type in
+            guard let userdata = decoder?.pointee.userdata else { return }
+            let context = Unmanaged<DecodeContext>.fromOpaque(userdata).takeUnretainedValue()
+            context.stack.append(Container(isArray: type == kJSONArray))
+        }
+        decoder.didDecodeTableValue = { decoder, key, value in
+            guard let userdata = decoder?.pointee.userdata else { return }
+            let context = Unmanaged<DecodeContext>.fromOpaque(userdata).takeUnretainedValue()
+            context.append(JSON.convert(value), key: String(playdateCString: key))
+        }
+        decoder.didDecodeArrayValue = { decoder, _, value in
+            guard let userdata = decoder?.pointee.userdata else { return }
+            let context = Unmanaged<DecodeContext>.fromOpaque(userdata).takeUnretainedValue()
+            context.append(JSON.convert(value), key: nil)
+        }
+        decoder.didDecodeSublist = { decoder, _, _ in
+            guard let userdata = decoder?.pointee.userdata else { return nil }
+            let context = Unmanaged<DecodeContext>.fromOpaque(userdata).takeUnretainedValue()
+            guard let finished = context.stack.popLast() else { return nil }
+            // Handed to the parent container (or the decode outval) as the
+            // sublist's value; consumed by `convert`.
+            return Unmanaged.passRetained(ValueBox(finished.value)).toOpaque()
+        }
+        return decoder
+    }
+
+    /// Decodes a JSON string into a `Value` tree.
+    public static func decode(_ jsonString: String) throws(PlaydateError) -> Value {
+        let context = DecodeContext()
+        let unmanaged = Unmanaged.passUnretained(context)
+        var decoder = makeDecoder(context: unmanaged)
+        var outval = json_value()
+        let ok = jsonString.withPlaydateCString { cString in
+            withExtendedLifetime(context) {
+                jsonAPI.pointee.decodeString.unsafelyUnwrapped(&decoder, cString, &outval) != 0
+            }
+        }
+        guard ok else {
+            // A completed root container may already have been written to
+            // outval before the failure; consume it so its box is not leaked.
+            _ = convert(outval)
+            throw decodeError(context)
+        }
+        return convert(outval)
+    }
+
+    /// Decodes JSON read from an open file into a `Value` tree.
+    public static func decode(file: File.Handle) throws(PlaydateError) -> Value {
+        let context = DecodeContext()
+        var decoder = makeDecoder(context: Unmanaged.passUnretained(context))
+        var reader = json_reader()
+        reader.userdata = Unmanaged.passUnretained(file).toOpaque()
+        reader.read = { userdata, buffer, size in
+            guard let userdata, let buffer else { return -1 }
+            let file = Unmanaged<File.Handle>.fromOpaque(userdata).takeUnretainedValue()
+            let destination = UnsafeMutableRawBufferPointer(start: buffer, count: Int(size))
+            do {
+                let count = try file.read(into: destination)
+                return count > 0 ? Int32(count) : -1
+            } catch {
+                return -1
+            }
+        }
+        var outval = json_value()
+        let ok = withExtendedLifetime(context) {
+            withExtendedLifetime(file) {
+                jsonAPI.pointee.decode.unsafelyUnwrapped(&decoder, reader, &outval) != 0
+            }
+        }
+        guard ok else {
+            // A completed root container may already have been written to
+            // outval before the failure; consume it so its box is not leaked.
+            _ = convert(outval)
+            throw decodeError(context)
+        }
+        return convert(outval)
+    }
+
+    /// Opens and decodes the JSON file at `path`.
+    public static func decodeFile(at path: String) throws(PlaydateError) -> Value {
+        let file = try File.Handle(path: path, mode: [.read, .readData])
+        return try decode(file: file)
+    }
+
+    // Static message: interpolating the line number would pull integer
+    // formatting machinery into every device binary that decodes JSON.
+    private static func decodeError(_ context: DecodeContext) -> PlaydateError {
+        PlaydateError(message: context.errorMessage ?? "JSON decode failed")
+    }
+
+    // MARK: - Encoding
+
+    /// A streaming JSON encoder writing into a string. Wraps `json_encoder`.
+    public final class Encoder {
+        private final class Output {
+            var text = ""
+        }
+
+        private var encoder = json_encoder()
+        private let output = Output()
+
+        public init(pretty: Bool = false) {
+            jsonAPI.pointee.initEncoder.unsafelyUnwrapped(&encoder, { userdata, string, length in
+                guard let userdata, let string else { return }
+                let output = Unmanaged<Output>.fromOpaque(userdata).takeUnretainedValue()
+                let bytes = UnsafeRawBufferPointer(start: string, count: Int(length))
+                output.text += String(decoding: bytes, as: UTF8.self)
+            }, Unmanaged.passUnretained(output).toOpaque(), pretty ? 1 : 0)
+        }
+
+        /// The JSON produced so far.
+        public var json: String { output.text }
+
+        public func startArray() {
+            withUnsafeMutablePointer(to: &encoder) { $0.pointee.startArray.unsafelyUnwrapped($0) }
+        }
+
+        /// Call before writing each array element.
+        public func addArrayMember() {
+            withUnsafeMutablePointer(to: &encoder) { $0.pointee.addArrayMember.unsafelyUnwrapped($0) }
+        }
+
+        public func endArray() {
+            withUnsafeMutablePointer(to: &encoder) { $0.pointee.endArray.unsafelyUnwrapped($0) }
+        }
+
+        public func startTable() {
+            withUnsafeMutablePointer(to: &encoder) { $0.pointee.startTable.unsafelyUnwrapped($0) }
+        }
+
+        /// Call before writing each table value.
+        public func addTableMember(name: String) {
+            name.withPlaydateCString { cName in
+                withUnsafeMutablePointer(to: &encoder) {
+                    $0.pointee.addTableMember.unsafelyUnwrapped($0, cName, Int32(name.utf8.count))
+                }
+            }
+        }
+
+        public func endTable() {
+            withUnsafeMutablePointer(to: &encoder) { $0.pointee.endTable.unsafelyUnwrapped($0) }
+        }
+
+        public func writeNull() {
+            withUnsafeMutablePointer(to: &encoder) { $0.pointee.writeNull.unsafelyUnwrapped($0) }
+        }
+
+        public func writeBool(_ value: Bool) {
+            withUnsafeMutablePointer(to: &encoder) {
+                (value ? $0.pointee.writeTrue : $0.pointee.writeFalse).unsafelyUnwrapped($0)
+            }
+        }
+
+        public func writeInt(_ value: Int) {
+            withUnsafeMutablePointer(to: &encoder) { $0.pointee.writeInt.unsafelyUnwrapped($0, Int32(value)) }
+        }
+
+        public func writeDouble(_ value: Double) {
+            withUnsafeMutablePointer(to: &encoder) { $0.pointee.writeDouble.unsafelyUnwrapped($0, value) }
+        }
+
+        public func writeString(_ value: String) {
+            value.withPlaydateCString { cString in
+                withUnsafeMutablePointer(to: &encoder) {
+                    $0.pointee.writeString.unsafelyUnwrapped($0, cString, Int32(value.utf8.count))
+                }
+            }
+        }
+
+        /// Writes a complete `Value` tree.
+        public func write(_ value: Value) {
+            switch value {
+            case .null:
+                writeNull()
+            case .bool(let bool):
+                writeBool(bool)
+            case .int(let int):
+                writeInt(int)
+            case .float(let float):
+                writeDouble(Double(float))
+            case .string(let string):
+                writeString(string)
+            case .array(let items):
+                startArray()
+                for item in items {
+                    addArrayMember()
+                    write(item)
+                }
+                endArray()
+            case .table(let entries):
+                startTable()
+                for (key, entry) in entries {
+                    addTableMember(name: key)
+                    write(entry)
+                }
+                endTable()
+            }
+        }
+    }
+
+    /// Encodes a `Value` tree as a JSON string.
+    public static func encode(_ value: Value, pretty: Bool = false) -> String {
+        let encoder = Encoder(pretty: pretty)
+        encoder.write(value)
+        return encoder.json
+    }
+}

Sources/PlaydateKit/Lua.swift

@@ -0,0 +1,296 @@
+//
+//  Lua.swift
+//  Wraps `playdate->lua` (pd_api_lua.h).
+//
+//  Lua callbacks are C function pointers without userdata, so functions
+//  registered here must be `@convention(c)` (the `CFunction` typealias), not
+//  capturing closures.
+//
+
+public import CPlaydate
+
+private var luaAPI: UnsafePointer<playdate_lua> { Playdate.luaAPI.unsafelyUnwrapped }
+
+/// The Lua bridge: registering C functions and classes, and exchanging
+/// values with Lua code.
+public enum Lua {}
+
+extension Lua {
+    /// A function callable from Lua. Returns the number of values it pushed
+    /// onto the stack.
+    public typealias CFunction = lua_CFunction
+
+    /// The type of a value on the Lua stack.
+    public enum Kind: UInt32, Sendable {
+        case `nil` = 0
+        case bool = 1
+        case int = 2
+        case float = 3
+        case string = 4
+        case table = 5
+        case function = 6
+        case thread = 7
+        case object = 8
+
+        init(_ type: LuaType) { self = Kind(rawValue: UInt32(type.rawValue)) ?? .nil }
+    }
+
+    /// A constant published on a registered class.
+    public enum ClassValue {
+        case int(name: String, value: UInt32)
+        case float(name: String, value: Float)
+        case string(name: String, value: String)
+    }
+
+    /// Buffers passed to `registerClass`/`addFunction`; the OS may keep
+    /// referencing them, so they are retained for the life of the game.
+    nonisolated(unsafe) private static var retainedBuffers: [UnsafeMutableRawPointer] = []
+
+    private static func retainedCString(_ string: String) -> UnsafePointer<CChar> {
+        let copy = string.copiedPlaydateCString()
+        retainedBuffers.append(UnsafeMutableRawPointer(copy))
+        return UnsafePointer(copy)
+    }
+
+    // MARK: - Registration
+
+    /// Makes `function` callable from Lua as `name` (which may contain dots
+    /// for namespacing, e.g. "mylib.myfunc").
+    public static func addFunction(_ function: CFunction, name: String) throws(PlaydateError) {
+        var error: UnsafePointer<CChar>?
+        let ok = name.withPlaydateCString {
+            luaAPI.pointee.addFunction.unsafelyUnwrapped(function, $0, &error) != 0
+        }
+        if !ok { throw PlaydateError(cString: error) }
+    }
+
+    /// Registers a Lua class named `name` with the given methods and
+    /// constants. When `isStatic` is `true` a plain table of functions is
+    /// created instead of a class.
+    public static func registerClass(name: String,
+                                     functions: [(name: String, function: CFunction)],
+                                     values: [ClassValue] = [],
+                                     isStatic: Bool = false) throws(PlaydateError) {
+        // The registration tables are kept alive permanently: the OS
+        // documents no copying guarantees for them.
+        var registrations: [lua_reg] = functions.map { entry in
+            lua_reg(name: retainedCString(entry.name), func: entry.function)
+        }
+        registrations.append(lua_reg(name: nil, func: nil))
+
+        var constants: [lua_val] = values.map { value in
+            switch value {
+            case .int(let name, let intValue):
+                return lua_val(name: retainedCString(name), type: kInt, v: .init(intval: intValue))
+            case .float(let name, let floatValue):
+                return lua_val(name: retainedCString(name), type: kFloat, v: .init(floatval: floatValue))
+            case .string(let name, let stringValue):
+                return lua_val(name: retainedCString(name), type: kStr,
+                               v: .init(strval: retainedCString(stringValue)))
+            }
+        }
+        constants.append(lua_val(name: nil, type: kInt, v: .init(intval: 0)))
+
+        let registrationsBuffer = UnsafeMutablePointer<lua_reg>.allocate(capacity: registrations.count)
+        registrationsBuffer.initialize(from: registrations, count: registrations.count)
+        retainedBuffers.append(UnsafeMutableRawPointer(registrationsBuffer))
+
+        let constantsBuffer = UnsafeMutablePointer<lua_val>.allocate(capacity: constants.count)
+        constantsBuffer.initialize(from: constants, count: constants.count)
+        retainedBuffers.append(UnsafeMutableRawPointer(constantsBuffer))
+
+        var error: UnsafePointer<CChar>?
+        let ok = name.withPlaydateCString {
+            luaAPI.pointee.registerClass.unsafelyUnwrapped($0, registrationsBuffer,
+                                                   values.isEmpty ? nil : constantsBuffer,
+                                                   isStatic ? 1 : 0, &error) != 0
+        }
+        if !ok { throw PlaydateError(cString: error) }
+    }
+
+    /// Pushes a function onto the stack, e.g. for `setUserValue`.
+    public static func pushFunction(_ function: CFunction) {
+        luaAPI.pointee.pushFunction.unsafelyUnwrapped(function)
+    }
+
+    /// From a class's `__index` callback: looks up the key in the instance
+    /// metatable first. Returns 1 if a value was found.
+    public static func indexMetatable() -> Bool {
+        luaAPI.pointee.indexMetatable.unsafelyUnwrapped() != 0
+    }
+
+    /// Pauses the Lua runtime.
+    public static func stop() {
+        luaAPI.pointee.stop.unsafelyUnwrapped()
+    }
+
+    /// Resumes the Lua runtime.
+    public static func start() {
+        luaAPI.pointee.start.unsafelyUnwrapped()
+    }
+
+    // MARK: - Arguments
+
+    /// The number of arguments the Lua caller passed. Positions are 1-based.
+    public static var argumentCount: Int {
+        Int(luaAPI.pointee.getArgCount.unsafelyUnwrapped())
+    }
+
+    /// The type of the argument at 1-based `position`; for objects, also the
+    /// class name.
+    public static func argumentType(at position: Int) -> (kind: Kind, className: String?) {
+        var className: UnsafePointer<CChar>?
+        let type = luaAPI.pointee.getArgType.unsafelyUnwrapped(Int32(position), &className)
+        return (Kind(type), String(playdateCString: className))
+    }
+
+    public static func argumentIsNil(at position: Int) -> Bool {
+        luaAPI.pointee.argIsNil.unsafelyUnwrapped(Int32(position)) != 0
+    }
+
+    public static func boolArgument(at position: Int) -> Bool {
+        luaAPI.pointee.getArgBool.unsafelyUnwrapped(Int32(position)) != 0
+    }
+
+    public static func intArgument(at position: Int) -> Int {
+        Int(luaAPI.pointee.getArgInt.unsafelyUnwrapped(Int32(position)))
+    }
+
+    public static func floatArgument(at position: Int) -> Float {
+        luaAPI.pointee.getArgFloat.unsafelyUnwrapped(Int32(position))
+    }
+
+    public static func stringArgument(at position: Int) -> String? {
+        String(playdateCString: luaAPI.pointee.getArgString.unsafelyUnwrapped(Int32(position)))
+    }
+
+    /// The argument as raw bytes (which may contain embedded zeros).
+    public static func bytesArgument(at position: Int) -> [UInt8]? {
+        var length = 0
+        guard let bytes = luaAPI.pointee.getArgBytes.unsafelyUnwrapped(Int32(position), &length) else {
+            return nil
+        }
+        let buffer = UnsafeRawBufferPointer(start: bytes, count: length)
+        return [UInt8](buffer)
+    }
+
+    /// The argument as an object instance of class `type`, with the
+    /// `UDObject` handle for retaining it.
+    public static func objectArgument(at position: Int, type: String)
+        -> (object: UnsafeMutableRawPointer?, userdataObject: UDObject?) {
+        var userdataObject: OpaquePointer?
+        // The C API takes a non-const class name but only reads it, so the
+        // stack copy can be passed with a mutating cast.
+        let object = type.withPlaydateCString { cType in
+            luaAPI.pointee.getArgObject.unsafelyUnwrapped(
+                Int32(position), UnsafeMutablePointer(mutating: cType), &userdataObject)
+        }
+        return (object, userdataObject.map { UDObject(pointer: $0) })
+    }
+
+    /// The argument as a bitmap. References an object owned by Lua; retain
+    /// the Lua value while using it.
+    public static func bitmapArgument(at position: Int) -> Graphics.Bitmap? {
+        guard let bitmap = luaAPI.pointee.getBitmap.unsafelyUnwrapped(Int32(position)) else { return nil }
+        return Graphics.Bitmap(pointer: bitmap, isOwned: false)
+    }
+
+    /// The argument as a sprite.
+    public static func spriteArgument(at position: Int) -> Sprite? {
+        guard let sprite = luaAPI.pointee.getSprite.unsafelyUnwrapped(Int32(position)) else { return nil }
+        return Sprite.wrapper(for: sprite)
+    }
+
+    // MARK: - Return values
+
+    public static func pushNil() {
+        luaAPI.pointee.pushNil.unsafelyUnwrapped()
+    }
+
+    public static func push(_ value: Bool) {
+        luaAPI.pointee.pushBool.unsafelyUnwrapped(value ? 1 : 0)
+    }
+
+    public static func push(_ value: Int) {
+        luaAPI.pointee.pushInt.unsafelyUnwrapped(Int32(value))
+    }
+
+    public static func push(_ value: Float) {
+        luaAPI.pointee.pushFloat.unsafelyUnwrapped(value)
+    }
+
+    public static func push(_ value: String) {
+        value.withPlaydateCString { luaAPI.pointee.pushString.unsafelyUnwrapped($0) }
+    }
+
+    public static func push(bytes: [UInt8]) {
+        bytes.withUnsafeBytes { buffer in
+            luaAPI.pointee.pushBytes.unsafelyUnwrapped(
+                buffer.baseAddress?.assumingMemoryBound(to: CChar.self), buffer.count)
+        }
+    }
+
+    public static func push(_ bitmap: Graphics.Bitmap) {
+        luaAPI.pointee.pushBitmap.unsafelyUnwrapped(bitmap.pointer)
+    }
+
+    public static func push(_ sprite: Sprite) {
+        luaAPI.pointee.pushSprite.unsafelyUnwrapped(sprite.pointer)
+    }
+
+    /// Wraps `object` in a Lua instance of class `type` and pushes it, with
+    /// `valueCount` extra user-value slots.
+    @discardableResult
+    public static func pushObject(_ object: UnsafeMutableRawPointer, type: String,
+                                  valueCount: Int = 0) -> UDObject? {
+        // The C API takes a non-const class name but only reads it, so the
+        // stack copy can be passed with a mutating cast.
+        let pointer = type.withPlaydateCString { cType in
+            luaAPI.pointee.pushObject.unsafelyUnwrapped(
+                object, UnsafeMutablePointer(mutating: cType), Int32(valueCount))
+        }
+        guard let pointer else { return nil }
+        return UDObject(pointer: pointer)
+    }
+
+    /// A handle to a Lua-owned object. Wraps `LuaUDObject`.
+    public struct UDObject {
+        let pointer: OpaquePointer
+
+        /// Prevents the object from being garbage-collected until `release()`.
+        @discardableResult
+        public func retain() -> UDObject {
+            UDObject(pointer: luaAPI.pointee.retainObject.unsafelyUnwrapped(pointer).unsafelyUnwrapped)
+        }
+
+        public func release() {
+            luaAPI.pointee.releaseObject.unsafelyUnwrapped(pointer)
+        }
+
+        /// Pops the value on top of the stack and stores it in the object's
+        /// user-value `slot` (1-based).
+        public func setUserValue(slot: UInt32) {
+            luaAPI.pointee.setUserValue.unsafelyUnwrapped(pointer, slot)
+        }
+
+        /// Pushes the value in user-value `slot` onto the stack and returns
+        /// its stack position, or `nil` if there is none.
+        @discardableResult
+        public func getUserValue(slot: UInt32) -> Int? {
+            let position = luaAPI.pointee.getUserValue.unsafelyUnwrapped(pointer, slot)
+            return position == 0 ? nil : Int(position)
+        }
+    }
+
+    // MARK: - Calling Lua
+
+    /// Calls the Lua function `name`. Push the arguments onto the stack
+    /// first. Calling Lua from Swift has overhead; use sparingly.
+    public static func callFunction(_ name: String, argumentCount: Int = 0) throws(PlaydateError) {
+        var error: UnsafePointer<CChar>?
+        let ok = name.withPlaydateCString {
+            luaAPI.pointee.callFunction.unsafelyUnwrapped($0, Int32(argumentCount), &error) != 0
+        }
+        if !ok { throw PlaydateError(cString: error) }
+    }
+}

Sources/PlaydateKit/Network.swift

@@ -0,0 +1,515 @@
+//
+//  Network.swift
+//  Wraps `playdate->network` (pd_api_network.h): HTTP and TCP connections.
+//
+//  The binding stores a back-reference to each connection wrapper in the
+//  underlying object's userdata slot so callbacks can recover the wrapper;
+//  the C userdata slot is therefore reserved by the binding.
+//
+
+internal import CPlaydate
+
+private var networkAPI: UnsafePointer<playdate_network> { Playdate.networkAPI.unsafelyUnwrapped }
+private var httpAPI: UnsafePointer<playdate_http> { Playdate.httpAPI.unsafelyUnwrapped }
+private var tcpAPI: UnsafePointer<playdate_tcp> { Playdate.tcpAPI.unsafelyUnwrapped }
+
+/// The network API: wifi status, HTTP, and TCP.
+public enum Network {}
+
+extension Network {
+    /// A network error code (`PDNetErr`).
+    public enum NetError: Int32, Swift.Error, Sendable {
+        case noDevice = -1
+        case busy = -2
+        case writeError = -3
+        case writeBusy = -4
+        case writeTimeout = -5
+        case readError = -6
+        case readBusy = -7
+        case readTimeout = -8
+        case readOverflow = -9
+        case frameError = -10
+        case badResponse = -11
+        case errorResponse = -12
+        case resetTimeout = -13
+        case bufferTooSmall = -14
+        case unexpectedResponse = -15
+        case notConnectedToAP = -16
+        case notImplemented = -17
+        case connectionClosed = -18
+        case unknown = 1
+
+        init(_ error: PDNetErr) {
+            self = NetError(rawValue: Int32(error.rawValue)) ?? .unknown
+        }
+    }
+
+    /// Throws unless `error` is `NET_OK`.
+    static func check(_ error: PDNetErr) throws(NetError) {
+        if error != NET_OK {
+            throw NetError(error)
+        }
+    }
+
+    /// Converts an error code to `nil` (OK) or a `NetError`.
+    static func optionalError(_ error: PDNetErr) -> NetError? {
+        error == NET_OK ? nil : NetError(error)
+    }
+
+    /// The device's wifi status.
+    public enum WifiStatus: UInt32, Sendable {
+        case notConnected = 0
+        case connected = 1
+        /// A connection was attempted but no configured access point was
+        /// available.
+        case notAvailable = 2
+    }
+
+    public static var status: WifiStatus {
+        WifiStatus(rawValue: UInt32(networkAPI.pointee.getStatus.unsafelyUnwrapped().rawValue)) ?? .notConnected
+    }
+
+    /// Turns the wifi radio on or off. The completion receives `nil` on
+    /// success. Completions of overlapping calls are delivered in call order.
+    public static func setEnabled(_ enabled: Bool, completion: ((NetError?) -> Void)? = nil) {
+        if let completion {
+            setEnabledCompletions.append(completion)
+            networkAPI.pointee.setEnabled.unsafelyUnwrapped(enabled, { error in
+                guard !Network.setEnabledCompletions.isEmpty else { return }
+                let completion = Network.setEnabledCompletions.removeFirst()
+                completion(Network.optionalError(error))
+            })
+        } else {
+            networkAPI.pointee.setEnabled.unsafelyUnwrapped(enabled, nil)
+        }
+    }
+
+    nonisolated(unsafe) private static var setEnabledCompletions: [(NetError?) -> Void] = []
+
+    /// Requests permission to connect to `server`. Shared by HTTP and TCP.
+    fileprivate static func requestAccess(
+        rawRequest: (UnsafePointer<CChar>?, Int32, Bool, UnsafePointer<CChar>?,
+                     (@convention(c) (Bool, UnsafeMutableRawPointer?) -> Void)?,
+                     UnsafeMutableRawPointer?) -> accessReply,
+        server: String, port: Int, useSSL: Bool, purpose: String?,
+        completion: @escaping (Bool) -> Void) -> AccessReply {
+        final class Box {
+            let body: (Bool) -> Void
+            init(_ body: @escaping (Bool) -> Void) { self.body = body }
+        }
+        let box = Unmanaged.passRetained(Box(completion))
+        let trampoline: @convention(c) (Bool, UnsafeMutableRawPointer?) -> Void = { allowed, userdata in
+            guard let userdata else { return }
+            Unmanaged<Box>.fromOpaque(userdata).takeRetainedValue().body(allowed)
+        }
+        let reply = server.withPlaydateCString { cServer in
+            if let purpose {
+                return purpose.withPlaydateCString { cPurpose in
+                    rawRequest(cServer, Int32(port), useSSL, cPurpose, trampoline, box.toOpaque())
+                }
+            } else {
+                return rawRequest(cServer, Int32(port), useSSL, nil, trampoline, box.toOpaque())
+            }
+        }
+        if reply != kAccessAsk {
+            // The callback will not be invoked; balance the retain.
+            box.release()
+        }
+        return AccessReply(rawValue: UInt32(reply.rawValue)) ?? .ask
+    }
+
+    // MARK: - HTTP
+
+    /// An HTTP connection to a server. Wraps `HTTPConnection`.
+    public final class HTTPConnection {
+        let pointer: OpaquePointer
+
+        var headerReceivedCallback: ((HTTPConnection, _ key: String, _ value: String) -> Void)?
+        var headersReadCallback: ((HTTPConnection) -> Void)?
+        var responseCallback: ((HTTPConnection) -> Void)?
+        var requestCompleteCallback: ((HTTPConnection) -> Void)?
+        var connectionClosedCallback: ((HTTPConnection) -> Void)?
+
+        /// Requests permission to connect to `server`. If the reply is
+        /// `.ask`, the completion is called later with the user's answer.
+        @discardableResult
+        public static func requestAccess(server: String, port: Int = 443, useSSL: Bool = true,
+                                         purpose: String? = nil,
+                                         completion: @escaping (Bool) -> Void) -> AccessReply {
+            Network.requestAccess(
+                rawRequest: { httpAPI.pointee.requestAccess.unsafelyUnwrapped($0, $1, $2, $3, $4, $5) },
+                server: server, port: port, useSSL: useSSL, purpose: purpose,
+                completion: completion)
+        }
+
+        /// Opens a connection to `server`. Fails if access has not been
+        /// granted.
+        public init?(server: String, port: Int = 443, useSSL: Bool = true) {
+            let pointer = server.withPlaydateCString {
+                httpAPI.pointee.newConnection.unsafelyUnwrapped($0, Int32(port), useSSL)
+            }
+            guard let pointer else { return nil }
+            self.pointer = pointer
+            httpAPI.pointee.setUserdata.unsafelyUnwrapped(pointer, Unmanaged.passUnretained(self).toOpaque())
+        }
+
+        deinit {
+            httpAPI.pointee.setUserdata.unsafelyUnwrapped(pointer, nil)
+            httpAPI.pointee.release.unsafelyUnwrapped(pointer)
+        }
+
+        private static func wrapper(for pointer: OpaquePointer?) -> HTTPConnection? {
+            guard let pointer,
+                  let userdata = httpAPI.pointee.getUserdata.unsafelyUnwrapped(pointer) else { return nil }
+            return Unmanaged<HTTPConnection>.fromOpaque(userdata).takeUnretainedValue()
+        }
+
+        // MARK: Configuration
+
+        /// The time to wait for the connection to open, in milliseconds.
+        public func setConnectTimeout(milliseconds: Int) {
+            httpAPI.pointee.setConnectTimeout.unsafelyUnwrapped(pointer, Int32(milliseconds))
+        }
+
+        /// Whether to keep the connection open after a request completes.
+        public func setKeepAlive(_ keepAlive: Bool) {
+            httpAPI.pointee.setKeepAlive.unsafelyUnwrapped(pointer, keepAlive)
+        }
+
+        /// Adds a `Range: bytes=start-end` header to future requests.
+        public func setByteRange(start: Int, end: Int) {
+            httpAPI.pointee.setByteRange.unsafelyUnwrapped(pointer, Int32(start), Int32(end))
+        }
+
+        /// The time to wait for incoming data, in milliseconds.
+        public func setReadTimeout(milliseconds: Int) {
+            httpAPI.pointee.setReadTimeout.unsafelyUnwrapped(pointer, Int32(milliseconds))
+        }
+
+        /// The size of the connection's read buffer, in bytes.
+        public func setReadBufferSize(bytes: Int) {
+            httpAPI.pointee.setReadBufferSize.unsafelyUnwrapped(pointer, Int32(bytes))
+        }
+
+        // MARK: Requests
+
+        /// Sends a GET request for `path`. `headers` are raw header lines
+        /// (e.g. "Accept: text/html\r\n").
+        public func get(path: String, headers: String = "") throws(NetError) {
+            let error = path.withPlaydateCString { cPath in
+                headers.withPlaydateCString { cHeaders in
+                    httpAPI.pointee.get.unsafelyUnwrapped(pointer, cPath, cHeaders, headers.utf8.count)
+                }
+            }
+            try Network.check(error)
+        }
+
+        /// Sends a POST request for `path` with the given body.
+        public func post(path: String, headers: String = "", body: [UInt8]) throws(NetError) {
+            let error = path.withPlaydateCString { cPath in
+                headers.withPlaydateCString { cHeaders in
+                    body.withUnsafeBytes { bodyBuffer in
+                        httpAPI.pointee.post.unsafelyUnwrapped(
+                            pointer, cPath, cHeaders, headers.utf8.count,
+                            bodyBuffer.baseAddress?.assumingMemoryBound(to: CChar.self),
+                            bodyBuffer.count)
+                    }
+                }
+            }
+            try Network.check(error)
+        }
+
+        /// Sends a request with an arbitrary HTTP method.
+        public func query(method: String, path: String, headers: String = "",
+                          body: [UInt8] = []) throws(NetError) {
+            let error = method.withPlaydateCString { cMethod in
+                path.withPlaydateCString { cPath in
+                    headers.withPlaydateCString { cHeaders in
+                        body.withUnsafeBytes { bodyBuffer in
+                            httpAPI.pointee.query.unsafelyUnwrapped(
+                                pointer, cMethod, cPath, cHeaders, headers.utf8.count,
+                                bodyBuffer.baseAddress?.assumingMemoryBound(to: CChar.self),
+                                bodyBuffer.count)
+                        }
+                    }
+                }
+            }
+            try Network.check(error)
+        }
+
+        // MARK: Response
+
+        /// The last error on the connection, if any.
+        public var error: NetError? {
+            Network.optionalError(httpAPI.pointee.getError.unsafelyUnwrapped(pointer))
+        }
+
+        /// The number of bytes read of the current response, and the total
+        /// expected (0 if the response has no Content-Length).
+        public var progress: (read: Int, total: Int) {
+            var read: Int32 = 0, total: Int32 = 0
+            httpAPI.pointee.getProgress.unsafelyUnwrapped(pointer, &read, &total)
+            return (Int(read), Int(total))
+        }
+
+        /// The HTTP status code of the response.
+        public var responseStatus: Int {
+            Int(httpAPI.pointee.getResponseStatus.unsafelyUnwrapped(pointer))
+        }
+
+        /// The number of response bytes available to read.
+        public var bytesAvailable: Int {
+            Int(httpAPI.pointee.getBytesAvailable.unsafelyUnwrapped(pointer))
+        }
+
+        /// Reads up to `buffer.count` response bytes. Returns the number of
+        /// bytes read.
+        public func read(into buffer: UnsafeMutableRawBufferPointer) throws(NetError) -> Int {
+            let result = httpAPI.pointee.read.unsafelyUnwrapped(pointer, buffer.baseAddress,
+                                                        UInt32(buffer.count))
+            if result < 0 {
+                throw NetError(rawValue: result) ?? .unknown
+            }
+            return Int(result)
+        }
+
+        /// Reads up to `length` available response bytes.
+        public func read(length: Int) throws(NetError) -> [UInt8] {
+            var bytes = [UInt8](repeating: 0, count: length)
+            let result = bytes.withUnsafeMutableBytes { buffer in
+                httpAPI.pointee.read.unsafelyUnwrapped(pointer, buffer.baseAddress, UInt32(buffer.count))
+            }
+            if result < 0 {
+                throw NetError(rawValue: result) ?? .unknown
+            }
+            bytes.removeLast(length - Int(result))
+            return bytes
+        }
+
+        /// Closes the connection.
+        public func close() {
+            httpAPI.pointee.close.unsafelyUnwrapped(pointer)
+        }
+
+        // MARK: Callbacks
+
+        /// Called for each header line as it arrives.
+        public func setHeaderReceivedCallback(_ callback: ((HTTPConnection, _ key: String, _ value: String) -> Void)?) {
+            headerReceivedCallback = callback
+            if callback != nil {
+                httpAPI.pointee.setHeaderReceivedCallback.unsafelyUnwrapped(pointer, { connection, key, value in
+                    guard let wrapper = HTTPConnection.wrapper(for: connection),
+                          let key = String(playdateCString: key),
+                          let value = String(playdateCString: value) else { return }
+                    wrapper.headerReceivedCallback?(wrapper, key, value)
+                })
+            } else {
+                httpAPI.pointee.setHeaderReceivedCallback.unsafelyUnwrapped(pointer, nil)
+            }
+        }
+
+        /// Called when all headers have been read.
+        public func setHeadersReadCallback(_ callback: ((HTTPConnection) -> Void)?) {
+            headersReadCallback = callback
+            if callback != nil {
+                httpAPI.pointee.setHeadersReadCallback.unsafelyUnwrapped(pointer, { connection in
+                    guard let wrapper = HTTPConnection.wrapper(for: connection) else { return }
+                    wrapper.headersReadCallback?(wrapper)
+                })
+            } else {
+                httpAPI.pointee.setHeadersReadCallback.unsafelyUnwrapped(pointer, nil)
+            }
+        }
+
+        /// Called when response data is available to read.
+        public func setResponseCallback(_ callback: ((HTTPConnection) -> Void)?) {
+            responseCallback = callback
+            if callback != nil {
+                httpAPI.pointee.setResponseCallback.unsafelyUnwrapped(pointer, { connection in
+                    guard let wrapper = HTTPConnection.wrapper(for: connection) else { return }
+                    wrapper.responseCallback?(wrapper)
+                })
+            } else {
+                httpAPI.pointee.setResponseCallback.unsafelyUnwrapped(pointer, nil)
+            }
+        }
+
+        /// Called when the request finishes.
+        public func setRequestCompleteCallback(_ callback: ((HTTPConnection) -> Void)?) {
+            requestCompleteCallback = callback
+            if callback != nil {
+                httpAPI.pointee.setRequestCompleteCallback.unsafelyUnwrapped(pointer, { connection in
+                    guard let wrapper = HTTPConnection.wrapper(for: connection) else { return }
+                    wrapper.requestCompleteCallback?(wrapper)
+                })
+            } else {
+                httpAPI.pointee.setRequestCompleteCallback.unsafelyUnwrapped(pointer, nil)
+            }
+        }
+
+        /// Called when the connection closes.
+        public func setConnectionClosedCallback(_ callback: ((HTTPConnection) -> Void)?) {
+            connectionClosedCallback = callback
+            if callback != nil {
+                httpAPI.pointee.setConnectionClosedCallback.unsafelyUnwrapped(pointer, { connection in
+                    guard let wrapper = HTTPConnection.wrapper(for: connection) else { return }
+                    wrapper.connectionClosedCallback?(wrapper)
+                })
+            } else {
+                httpAPI.pointee.setConnectionClosedCallback.unsafelyUnwrapped(pointer, nil)
+            }
+        }
+    }
+
+    // MARK: - TCP
+
+    /// A TCP connection to a server. Wraps `TCPConnection`.
+    public final class TCPConnection {
+        let pointer: OpaquePointer
+
+        var openCompletion: ((TCPConnection, NetError?) -> Void)?
+        var connectionClosedCallback: ((TCPConnection, NetError?) -> Void)?
+
+        /// Requests permission to connect to `server`. If the reply is
+        /// `.ask`, the completion is called later with the user's answer.
+        @discardableResult
+        public static func requestAccess(server: String, port: Int, useSSL: Bool = true,
+                                         purpose: String? = nil,
+                                         completion: @escaping (Bool) -> Void) -> AccessReply {
+            Network.requestAccess(
+                rawRequest: { tcpAPI.pointee.requestAccess.unsafelyUnwrapped($0, $1, $2, $3, $4, $5) },
+                server: server, port: port, useSSL: useSSL, purpose: purpose,
+                completion: completion)
+        }
+
+        /// Creates a connection to `server`. Fails if access has not been
+        /// granted. Call `open(_:)` to connect.
+        public init?(server: String, port: Int, useSSL: Bool = true) {
+            let pointer = server.withPlaydateCString {
+                tcpAPI.pointee.newConnection.unsafelyUnwrapped($0, Int32(port), useSSL)
+            }
+            guard let pointer else { return nil }
+            self.pointer = pointer
+            tcpAPI.pointee.setUserdata.unsafelyUnwrapped(pointer, Unmanaged.passUnretained(self).toOpaque())
+        }
+
+        deinit {
+            tcpAPI.pointee.setUserdata.unsafelyUnwrapped(pointer, nil)
+            tcpAPI.pointee.release.unsafelyUnwrapped(pointer)
+        }
+
+        private static func wrapper(for pointer: OpaquePointer?) -> TCPConnection? {
+            guard let pointer,
+                  let userdata = tcpAPI.pointee.getUserdata.unsafelyUnwrapped(pointer) else { return nil }
+            return Unmanaged<TCPConnection>.fromOpaque(userdata).takeUnretainedValue()
+        }
+
+        /// The last error on the connection, if any.
+        public var error: NetError? {
+            Network.optionalError(tcpAPI.pointee.getError.unsafelyUnwrapped(pointer))
+        }
+
+        /// The time to wait for the connection to open, in milliseconds.
+        public func setConnectTimeout(milliseconds: Int) {
+            tcpAPI.pointee.setConnectTimeout.unsafelyUnwrapped(pointer, Int32(milliseconds))
+        }
+
+        /// Opens the connection. The completion receives `nil` on success.
+        public func open(_ completion: @escaping (TCPConnection, NetError?) -> Void) throws(NetError) {
+            openCompletion = completion
+            let error = tcpAPI.pointee.open.unsafelyUnwrapped(pointer, { connection, error, _ in
+                guard let wrapper = TCPConnection.wrapper(for: connection) else { return }
+                let completion = wrapper.openCompletion
+                wrapper.openCompletion = nil
+                completion?(wrapper, Network.optionalError(error))
+            }, nil)
+            try Network.check(error)
+        }
+
+        /// Closes the connection.
+        public func close() throws(NetError) {
+            try Network.check(tcpAPI.pointee.close.unsafelyUnwrapped(pointer))
+        }
+
+        /// Called when the connection closes, with the reason if it closed
+        /// due to an error.
+        public func setConnectionClosedCallback(_ callback: ((TCPConnection, NetError?) -> Void)?) {
+            connectionClosedCallback = callback
+            if callback != nil {
+                tcpAPI.pointee.setConnectionClosedCallback.unsafelyUnwrapped(pointer, { connection, error in
+                    guard let wrapper = TCPConnection.wrapper(for: connection) else { return }
+                    wrapper.connectionClosedCallback?(wrapper, Network.optionalError(error))
+                })
+            } else {
+                tcpAPI.pointee.setConnectionClosedCallback.unsafelyUnwrapped(pointer, nil)
+            }
+        }
+
+        /// The time to wait for incoming data, in milliseconds.
+        public func setReadTimeout(milliseconds: Int) {
+            tcpAPI.pointee.setReadTimeout.unsafelyUnwrapped(pointer, Int32(milliseconds))
+        }
+
+        /// The size of the connection's read buffer, in bytes.
+        public func setReadBufferSize(bytes: Int) {
+            tcpAPI.pointee.setReadBufferSize.unsafelyUnwrapped(pointer, Int32(bytes))
+        }
+
+        /// The number of bytes available to read.
+        public var bytesAvailable: Int {
+            Int(tcpAPI.pointee.getBytesAvailable.unsafelyUnwrapped(pointer))
+        }
+
+        /// The number of written bytes not yet sent on the wire.
+        public var sentBytesPending: Int {
+            Int(tcpAPI.pointee.getSentBytesPending.unsafelyUnwrapped(pointer))
+        }
+
+        /// Reads up to `buffer.count` bytes, waiting up to the read timeout.
+        /// Returns the number of bytes read.
+        public func read(into buffer: UnsafeMutableRawBufferPointer) throws(NetError) -> Int {
+            let result = tcpAPI.pointee.read.unsafelyUnwrapped(pointer, buffer.baseAddress, buffer.count)
+            if result < 0 {
+                throw NetError(rawValue: result) ?? .unknown
+            }
+            return Int(result)
+        }
+
+        /// Reads up to `length` bytes, waiting up to the read timeout.
+        public func read(length: Int) throws(NetError) -> [UInt8] {
+            var bytes = [UInt8](repeating: 0, count: length)
+            let result = bytes.withUnsafeMutableBytes { buffer in
+                tcpAPI.pointee.read.unsafelyUnwrapped(pointer, buffer.baseAddress, buffer.count)
+            }
+            if result < 0 {
+                throw NetError(rawValue: result) ?? .unknown
+            }
+            bytes.removeLast(length - Int(result))
+            return bytes
+        }
+
+        /// Writes the buffer to the connection. Returns the number of bytes
+        /// accepted.
+        @discardableResult
+        public func write(_ buffer: UnsafeRawBufferPointer) throws(NetError) -> Int {
+            let result = tcpAPI.pointee.write.unsafelyUnwrapped(pointer, buffer.baseAddress, buffer.count)
+            if result < 0 {
+                throw NetError(rawValue: result) ?? .unknown
+            }
+            return Int(result)
+        }
+
+        /// Writes the bytes to the connection. Returns the number of bytes
+        /// accepted.
+        @discardableResult
+        public func write(_ bytes: [UInt8]) throws(NetError) -> Int {
+            let result = bytes.withUnsafeBytes { buffer in
+                tcpAPI.pointee.write.unsafelyUnwrapped(pointer, buffer.baseAddress, buffer.count)
+            }
+            if result < 0 {
+                throw NetError(rawValue: result) ?? .unknown
+            }
+            return Int(result)
+        }
+    }
+}

Sources/PlaydateKit/PlaydateKit.docc/GettingStarted.md

@@ -0,0 +1,66 @@
+# Getting Started
+
+Bootstrap the bindings from your game's entry point and drive a frame loop.
+
+## Overview
+
+A Playdate game has a single C entry point, `eventHandler`, which the
+firmware calls with a `PlaydateAPI*` and an event code. Export it with
+`@_cdecl`, call ``Playdate/initialize(with:)`` on the first event, and
+install an update callback:
+
+```swift
+import CPlaydate
+import PlaydateKit
+
+@_cdecl("eventHandler")
+func eventHandler(
+    pointer: UnsafeMutableRawPointer,
+    event: PDSystemEvent,
+    argument: UInt32
+) -> Int32 {
+    if case .initialize = SystemEvent(event: event, argument: argument) {
+        Playdate.initialize(with: pointer)   // must happen before anything else
+        Game.shared.start()
+    }
+
+    return 0
+}
+
+final class Game {
+    nonisolated(unsafe) static let shared = Game()
+
+    func start() {
+        Display.setRefreshRate(50)
+
+        System.setUpdateCallback {
+            self.update()
+            return true   // true = redraw the display this frame
+        }
+    }
+
+    func update() {
+        let (_, pushed, _) = System.buttonState
+        if pushed.contains(.a) {
+            System.log("A pressed")
+        }
+
+        Graphics.clear(color: .white)
+        Graphics.drawText("Hello, Playdate", x: 8, y: 8)
+        System.drawFPS()
+    }
+}
+```
+
+## Conventions to know
+
+- **Initialization.** Calling any wrapper before
+  ``Playdate/initialize(with:)`` is a programmer error and will crash.
+- **Errors.** Fallible operations use typed throws — ``PlaydateError``
+  generally, ``Network/NetError`` for network I/O.
+- **Ownership.** A wrapper that creates a C object frees it on `deinit`;
+  keep the wrapper referenced for as long as you use it. Wrappers vending
+  OS-owned objects don't free them — keep the owner alive instead, as
+  documented on each API.
+- **Threading.** The Playdate runtime is single-threaded; don't call the
+  API from other threads.

Sources/PlaydateKit/PlaydateKit.docc/PlaydateKit.md

@@ -0,0 +1,61 @@
+# ``PlaydateKit``
+
+Swift bindings to the Playdate C API.
+
+## Overview
+
+The Playdate C API is delivered as a `PlaydateAPI*` struct of function
+pointers that the firmware hands to your game at launch. This module wraps
+that surface in idiomatic Swift: top-level namespaces per subsystem, wrapper
+types with ownership semantics, closures instead of function-pointer/userdata
+pairs, `OptionSet`s and `enum`s instead of raw constants, and typed `throws`
+for fallible calls.
+
+Call ``Playdate/initialize(with:)`` from your game's `eventHandler` before
+using anything else — see <doc:GettingStarted>.
+
+The bindings are written within the Embedded Swift subset, so the same code
+compiles for the Playdate Simulator and for the device
+(`armv7em-none-none-eabi`).
+
+## Topics
+
+### Essentials
+
+- <doc:GettingStarted>
+- ``Playdate``
+- ``SystemEvent``
+- ``PlaydateError``
+
+### System and display
+
+- ``System``
+- ``Display``
+
+### Drawing
+
+- ``Graphics``
+- ``Rect``
+
+### Sprites
+
+- ``Sprite``
+
+### Audio
+
+- ``Sound``
+
+### Storage
+
+- ``File``
+- ``JSON``
+
+### Connectivity
+
+- ``Network``
+- ``Scoreboards``
+- ``AccessReply``
+
+### Lua interop
+
+- ``Lua``

Sources/PlaydateKit/PlaydateKit.swift

@@ -0,0 +1,168 @@
+//
+//  PlaydateKit.swift
+//  Swift bindings to the Playdate C API.
+//
+//  The C API is delivered as a `PlaydateAPI` struct of function pointers that
+//  the firmware hands to the game's `eventHandler` entry point. Call
+//  `Playdate.initialize(with:)` from that entry point before using any other
+//  API in this module.
+//
+
+public import CPlaydate
+
+/// The raw C API bootstrap. Everything else in this module (System,
+/// Graphics, Sprite, Sound, ...) lives at the top level of the `PlaydateKit`
+/// module and requires `initialize(with:)` to have been called first.
+public enum Playdate {
+    /// The raw C API. Populated by `initialize(with:)`.
+    ///
+    /// Access is unsynchronized: the Playdate runtime is single-threaded and
+    /// the API pointer is written exactly once at startup.
+    public internal(set) nonisolated(unsafe) static var api: PlaydateAPI!
+
+    /// The raw C API pointer handed to `initialize(with:)`, for calls that
+    /// need to pass the `PlaydateAPI*` back to C.
+    public internal(set) nonisolated(unsafe) static var apiPointer: UnsafeMutablePointer<PlaydateAPI>!
+
+    // Sub-API pointers cached once at initialization, so wrapper calls are a
+    // single field load off a pointer instead of re-walking `api` per call.
+    nonisolated(unsafe) static var systemAPI: UnsafePointer<playdate_sys>!
+    nonisolated(unsafe) static var displayAPI: UnsafePointer<playdate_display>!
+    nonisolated(unsafe) static var graphicsAPI: UnsafePointer<playdate_graphics>!
+    nonisolated(unsafe) static var spriteAPI: UnsafePointer<playdate_sprite>!
+    nonisolated(unsafe) static var soundAPI: UnsafePointer<playdate_sound>!
+    nonisolated(unsafe) static var fileAPI: UnsafePointer<playdate_file>!
+    nonisolated(unsafe) static var jsonAPI: UnsafePointer<playdate_json>!
+    nonisolated(unsafe) static var luaAPI: UnsafePointer<playdate_lua>!
+    nonisolated(unsafe) static var scoreboardsAPI: UnsafePointer<playdate_scoreboards>!
+    nonisolated(unsafe) static var networkAPI: UnsafePointer<playdate_network>!
+
+    // Second-level tables, cached for the same reason. Assigned with
+    // optional chaining because partial API tables (e.g. test mocks) may
+    // leave some of them null; using an absent table traps at the call
+    // site, as before.
+    nonisolated(unsafe) static var tilemapAPI: UnsafePointer<playdate_tilemap>!
+    nonisolated(unsafe) static var videoAPI: UnsafePointer<playdate_video>!
+    nonisolated(unsafe) static var videoStreamAPI: UnsafePointer<playdate_videostream>!
+    nonisolated(unsafe) static var channelAPI: UnsafePointer<playdate_sound_channel>!
+    nonisolated(unsafe) static var sourceAPI: UnsafePointer<playdate_sound_source>!
+    nonisolated(unsafe) static var filePlayerAPI: UnsafePointer<playdate_sound_fileplayer>!
+    nonisolated(unsafe) static var sampleAPI: UnsafePointer<playdate_sound_sample>!
+    nonisolated(unsafe) static var samplePlayerAPI: UnsafePointer<playdate_sound_sampleplayer>!
+    nonisolated(unsafe) static var synthAPI: UnsafePointer<playdate_sound_synth>!
+    nonisolated(unsafe) static var instrumentAPI: UnsafePointer<playdate_sound_instrument>!
+    nonisolated(unsafe) static var trackAPI: UnsafePointer<playdate_sound_track>!
+    nonisolated(unsafe) static var sequenceAPI: UnsafePointer<playdate_sound_sequence>!
+    nonisolated(unsafe) static var signalAPI: UnsafePointer<playdate_sound_signal>!
+    nonisolated(unsafe) static var lfoAPI: UnsafePointer<playdate_sound_lfo>!
+    nonisolated(unsafe) static var envelopeAPI: UnsafePointer<playdate_sound_envelope>!
+    nonisolated(unsafe) static var controlSignalAPI: UnsafePointer<playdate_control_signal>!
+    nonisolated(unsafe) static var effectAPI: UnsafePointer<playdate_sound_effect>!
+    nonisolated(unsafe) static var twoPoleFilterAPI: UnsafePointer<playdate_sound_effect_twopolefilter>!
+    nonisolated(unsafe) static var onePoleFilterAPI: UnsafePointer<playdate_sound_effect_onepolefilter>!
+    nonisolated(unsafe) static var bitCrusherAPI: UnsafePointer<playdate_sound_effect_bitcrusher>!
+    nonisolated(unsafe) static var ringModulatorAPI: UnsafePointer<playdate_sound_effect_ringmodulator>!
+    nonisolated(unsafe) static var delayLineAPI: UnsafePointer<playdate_sound_effect_delayline>!
+    nonisolated(unsafe) static var overdriveAPI: UnsafePointer<playdate_sound_effect_overdrive>!
+    nonisolated(unsafe) static var httpAPI: UnsafePointer<playdate_http>!
+    nonisolated(unsafe) static var tcpAPI: UnsafePointer<playdate_tcp>!
+
+    /// Stores the API pointer handed to the game's `eventHandler`.
+    ///
+    /// Call this first, on the `.initialize` event, before using any other
+    /// wrapper in this module.
+    public static func initialize(with pointer: UnsafeMutableRawPointer) {
+        apiPointer = pointer.assumingMemoryBound(to: PlaydateAPI.self)
+        api = apiPointer.pointee
+        systemAPI = api.system
+        displayAPI = api.display
+        graphicsAPI = api.graphics
+        spriteAPI = api.sprite
+        soundAPI = api.sound
+        fileAPI = api.file
+        jsonAPI = api.json
+        luaAPI = api.lua
+        scoreboardsAPI = api.scoreboards
+        networkAPI = api.network
+        tilemapAPI = graphicsAPI?.pointee.tilemap
+        videoAPI = graphicsAPI?.pointee.video
+        videoStreamAPI = graphicsAPI?.pointee.videostream
+        channelAPI = soundAPI?.pointee.channel
+        sourceAPI = soundAPI?.pointee.source
+        filePlayerAPI = soundAPI?.pointee.fileplayer
+        sampleAPI = soundAPI?.pointee.sample
+        samplePlayerAPI = soundAPI?.pointee.sampleplayer
+        synthAPI = soundAPI?.pointee.synth
+        instrumentAPI = soundAPI?.pointee.instrument
+        trackAPI = soundAPI?.pointee.track
+        sequenceAPI = soundAPI?.pointee.sequence
+        signalAPI = soundAPI?.pointee.signal
+        lfoAPI = soundAPI?.pointee.lfo
+        envelopeAPI = soundAPI?.pointee.envelope
+        controlSignalAPI = soundAPI?.pointee.controlsignal
+        effectAPI = soundAPI?.pointee.effect
+        twoPoleFilterAPI = effectAPI?.pointee.twopolefilter
+        onePoleFilterAPI = effectAPI?.pointee.onepolefilter
+        bitCrusherAPI = effectAPI?.pointee.bitcrusher
+        ringModulatorAPI = effectAPI?.pointee.ringmodulator
+        delayLineAPI = effectAPI?.pointee.delayline
+        overdriveAPI = effectAPI?.pointee.overdrive
+        httpAPI = networkAPI?.pointee.http
+        tcpAPI = networkAPI?.pointee.tcp
+    }
+}
+
+/// An error reported by the Playdate OS.
+public struct PlaydateError: Swift.Error, Sendable {
+    public let message: String
+
+    init(message: String) {
+        self.message = message
+    }
+
+    init(cString: UnsafePointer<CChar>?) {
+        self.init(message: String(playdateCString: cString) ?? "unknown error")
+    }
+}
+
+/// The user's answer to a permission request (microphone, network).
+public enum AccessReply: UInt32, Sendable {
+    case ask = 0
+    case deny = 1
+    case allow = 2
+}
+
+/// A Swift view of `PDSystemEvent` with the key code folded into the
+/// key events.
+public enum SystemEvent {
+    case initialize
+    case initializeLua
+    case lock
+    case unlock
+    case pause
+    case resume
+    case terminate
+    case keyPressed(keyCode: UInt32)
+    case keyReleased(keyCode: UInt32)
+    case lowPower
+    case mirrorStarted
+    case mirrorEnded
+
+    public init?(event: PDSystemEvent, argument: UInt32) {
+        switch event {
+        case kEventInit: self = .initialize
+        case kEventInitLua: self = .initializeLua
+        case kEventLock: self = .lock
+        case kEventUnlock: self = .unlock
+        case kEventPause: self = .pause
+        case kEventResume: self = .resume
+        case kEventTerminate: self = .terminate
+        case kEventKeyPressed: self = .keyPressed(keyCode: argument)
+        case kEventKeyReleased: self = .keyReleased(keyCode: argument)
+        case kEventLowPower: self = .lowPower
+        case kEventMirrorStarted: self = .mirrorStarted
+        case kEventMirrorEnded: self = .mirrorEnded
+        default: return nil
+        }
+    }
+}

Sources/PlaydateKit/Scoreboards.swift

@@ -0,0 +1,173 @@
+//
+//  Scoreboards.swift
+//  Wraps `playdate->scoreboards` (pd_api_scoreboards.h).
+//
+//  The C callbacks carry no userdata, so one completion per operation kind
+//  is tracked at a time; starting a second request of the same kind before
+//  the first completes replaces the stored completion.
+//
+
+internal import CPlaydate
+
+private var scoreboardsAPI: UnsafePointer<playdate_scoreboards> { Playdate.scoreboardsAPI.unsafelyUnwrapped }
+
+/// The scoreboards API for games with online leaderboards.
+public enum Scoreboards {}
+
+extension Scoreboards {
+    /// A score on a board.
+    public struct Score {
+        public let rank: UInt32
+        public let value: UInt32
+        public let player: String
+        public let boardID: String?
+
+        init(_ score: PDScore) {
+            rank = score.rank
+            value = score.value
+            player = String(playdateCString: score.player) ?? ""
+            boardID = String(playdateCString: score.boardID)
+        }
+
+        init(_ score: PDListScore, boardID: String?) {
+            rank = score.rank
+            value = score.value
+            player = String(playdateCString: score.player) ?? ""
+            self.boardID = boardID
+        }
+    }
+
+    /// The scores on a board.
+    public struct ScoresList {
+        public let boardID: String
+        public let lastUpdated: UInt32
+        public let playerIncluded: Bool
+        public let limit: UInt32
+        public let scores: [Score]
+
+        init(_ list: PDScoresList) {
+            boardID = String(playdateCString: list.boardID) ?? ""
+            lastUpdated = list.lastUpdated
+            playerIncluded = list.playerIncluded != 0
+            limit = list.limit
+            var scores = [Score]()
+            if let entries = list.scores {
+                scores.reserveCapacity(Int(list.count))
+                for index in 0..<Int(list.count) {
+                    scores.append(Score(entries[index], boardID: boardID))
+                }
+            }
+            self.scores = scores
+        }
+    }
+
+    /// A board belonging to the game.
+    public struct Board {
+        public let boardID: String
+        public let name: String
+
+        init(_ board: PDBoard) {
+            boardID = String(playdateCString: board.boardID) ?? ""
+            name = String(playdateCString: board.name) ?? ""
+        }
+    }
+
+    /// The game's boards.
+    public struct BoardsList {
+        public let lastUpdated: UInt32
+        public let boards: [Board]
+
+        init(_ list: PDBoardsList) {
+            lastUpdated = list.lastUpdated
+            var boards = [Board]()
+            if let entries = list.boards {
+                boards.reserveCapacity(Int(list.count))
+                for index in 0..<Int(list.count) {
+                    boards.append(Board(entries[index]))
+                }
+            }
+            self.boards = boards
+        }
+    }
+
+    nonisolated(unsafe) private static var addScoreCompletion: ((Result<Score, PlaydateError>) -> Void)?
+    nonisolated(unsafe) private static var personalBestCompletion: ((Result<Score, PlaydateError>) -> Void)?
+    nonisolated(unsafe) private static var boardsCompletion: ((Result<BoardsList, PlaydateError>) -> Void)?
+    nonisolated(unsafe) private static var scoresCompletion: ((Result<ScoresList, PlaydateError>) -> Void)?
+
+    /// Submits a score to the board. Returns `false` if the request could
+    /// not be started.
+    @discardableResult
+    public static func addScore(boardID: String, value: UInt32,
+                                completion: @escaping (Result<Score, PlaydateError>) -> Void) -> Bool {
+        addScoreCompletion = completion
+        return boardID.withPlaydateCString { cBoardID in
+            scoreboardsAPI.pointee.addScore.unsafelyUnwrapped(cBoardID, value, { score, errorMessage in
+                let completion = Scoreboards.addScoreCompletion
+                Scoreboards.addScoreCompletion = nil
+                completion?(Scoreboards.result(score, errorMessage))
+            }) != 0
+        }
+    }
+
+    /// Fetches the current player's best score on the board.
+    @discardableResult
+    public static func getPersonalBest(boardID: String,
+                                       completion: @escaping (Result<Score, PlaydateError>) -> Void) -> Bool {
+        personalBestCompletion = completion
+        return boardID.withPlaydateCString { cBoardID in
+            scoreboardsAPI.pointee.getPersonalBest.unsafelyUnwrapped(cBoardID, { score, errorMessage in
+                let completion = Scoreboards.personalBestCompletion
+                Scoreboards.personalBestCompletion = nil
+                completion?(Scoreboards.result(score, errorMessage))
+            }) != 0
+        }
+    }
+
+    /// Fetches the list of the game's boards.
+    @discardableResult
+    public static func getScoreboards(completion: @escaping (Result<BoardsList, PlaydateError>) -> Void) -> Bool {
+        boardsCompletion = completion
+        return scoreboardsAPI.pointee.getScoreboards.unsafelyUnwrapped({ boards, errorMessage in
+            let completion = Scoreboards.boardsCompletion
+            Scoreboards.boardsCompletion = nil
+            guard let boards else {
+                completion?(.failure(PlaydateError(cString: errorMessage)))
+                return
+            }
+            let list = BoardsList(boards.pointee)
+            scoreboardsAPI.pointee.freeBoardsList.unsafelyUnwrapped(boards)
+            completion?(.success(list))
+        }) != 0
+    }
+
+    /// Fetches the scores on the board.
+    @discardableResult
+    public static func getScores(boardID: String,
+                                 completion: @escaping (Result<ScoresList, PlaydateError>) -> Void) -> Bool {
+        scoresCompletion = completion
+        return boardID.withPlaydateCString { cBoardID in
+            scoreboardsAPI.pointee.getScores.unsafelyUnwrapped(cBoardID, { scores, errorMessage in
+                let completion = Scoreboards.scoresCompletion
+                Scoreboards.scoresCompletion = nil
+                guard let scores else {
+                    completion?(.failure(PlaydateError(cString: errorMessage)))
+                    return
+                }
+                let list = ScoresList(scores.pointee)
+                scoreboardsAPI.pointee.freeScoresList.unsafelyUnwrapped(scores)
+                completion?(.success(list))
+            }) != 0
+        }
+    }
+
+    private static func result(_ score: UnsafeMutablePointer<PDScore>?,
+                               _ errorMessage: UnsafePointer<CChar>?) -> Result<Score, PlaydateError> {
+        guard let score else {
+            return .failure(PlaydateError(cString: errorMessage))
+        }
+        let value = Score(score.pointee)
+        scoreboardsAPI.pointee.freeScore.unsafelyUnwrapped(score)
+        return .success(value)
+    }
+}

Sources/PlaydateKit/Sound.swift

@@ -0,0 +1,353 @@
+//
+//  Sound.swift
+//  Wraps `playdate->sound` (pd_api_sound.h): the namespace, top-level audio
+//  functions, and SoundChannel. Sources, signals, synths, and effects live in
+//  their own files.
+//
+
+internal import CPlaydate
+
+var snd: UnsafePointer<playdate_sound> { Playdate.soundAPI.unsafelyUnwrapped }
+
+/// The sound API: channels, players, synths, sequences, and effects.
+public enum Sound {}
+
+extension Sound {
+    /// A note as a MIDI note number, where 60 is middle C. Fractional values
+    /// are valid.
+    public typealias MIDINote = Float
+
+    /// Middle C (`NOTE_C4`).
+    public static let noteC4: MIDINote = 60
+
+    /// The number of audio frames rendered per system audio cycle
+    /// (`AUDIO_FRAMES_PER_CYCLE`).
+    public static let audioFramesPerCycle = 512
+
+    /// Converts a MIDI note to a frequency in Hz.
+    public static func frequency(forNote note: MIDINote) -> Float {
+        pd_noteToFrequency(note)
+    }
+
+    /// Converts a frequency in Hz to a MIDI note.
+    public static func note(forFrequency frequency: Float) -> MIDINote {
+        pd_frequencyToNote(frequency)
+    }
+
+    /// The format of sample data.
+    public enum Format: UInt32, Sendable {
+        case mono8bit = 0
+        case stereo8bit = 1
+        case mono16bit = 2
+        case stereo16bit = 3
+        case monoADPCM = 4
+        case stereoADPCM = 5
+
+        init(_ format: SoundFormat) { self = Format(rawValue: UInt32(format.rawValue)) ?? .mono16bit }
+        var cValue: SoundFormat { SoundFormat(SoundFormat.RawValue(rawValue)) }
+
+        public var isStereo: Bool { rawValue & 1 != 0 }
+        public var is16bit: Bool { rawValue >= 2 && rawValue < 4 }
+        public var bytesPerFrame: Int { Int(SoundFormat_bytesPerFrame(cValue)) }
+    }
+
+    /// The microphone used when recording.
+    public enum MicSource: UInt32, Sendable {
+        case autodetect = 0
+        case internalMic = 1
+        case headset = 2
+    }
+
+    /// The most recent sound error as a thrown error.
+    static func lastError() -> PlaydateError {
+        PlaydateError(cString: snd.pointee.getError.unsafelyUnwrapped())
+    }
+
+    // MARK: - Top-level functions
+
+    /// The audio engine's current time, in frames (44,100 per second).
+    public static var currentTime: UInt32 {
+        snd.pointee.getCurrentTime.unsafelyUnwrapped()
+    }
+
+    /// The most recent audio error message, if any.
+    public static var error: String? {
+        String(playdateCString: snd.pointee.getError.unsafelyUnwrapped())
+    }
+
+    /// Removes a source from its channel.
+    @discardableResult
+    public static func removeSource(_ source: Source) -> Bool {
+        let removed = snd.pointee.removeSource.unsafelyUnwrapped(source.pointer) != 0
+        CallbackSource.release(source)
+        return removed
+    }
+
+    /// Sets a callback that records microphone input. Return `false` from the
+    /// callback to stop recording. Pass `nil` to stop recording immediately.
+    /// The buffer contains mono 16-bit samples.
+    @discardableResult
+    public static func setMicCallback(source: MicSource = .autodetect,
+                                      _ callback: ((UnsafeMutableBufferPointer<Int16>) -> Bool)?) -> Bool {
+        micCallback = callback
+        if callback != nil {
+            return snd.pointee.setMicCallback.unsafelyUnwrapped({ _, buffer, length in
+                let samples = UnsafeMutableBufferPointer(start: buffer, count: Int(length))
+                return Sound.micCallback?(samples) == true ? 1 : 0
+            }, nil, CPlaydate.MicSource(CPlaydate.MicSource.RawValue(source.rawValue))) != 0
+        } else {
+            return snd.pointee.setMicCallback.unsafelyUnwrapped(nil, nil, CPlaydate.MicSource(CPlaydate.MicSource.RawValue(source.rawValue))) != 0
+        }
+    }
+
+    nonisolated(unsafe) private static var micCallback: ((UnsafeMutableBufferPointer<Int16>) -> Bool)?
+
+    /// Asks the user for permission to record from the microphone. `purpose`
+    /// is shown in the permission prompt. The completion receives whether
+    /// access was granted; it is not called if the reply was already
+    /// determined (the returned value is `.deny` or `.allow`).
+    @discardableResult
+    public static func requestMicAccess(purpose: String? = nil,
+                                        _ completion: @escaping (Bool) -> Void) -> AccessReply {
+        final class Box { let body: (Bool) -> Void; init(_ body: @escaping (Bool) -> Void) { self.body = body } }
+        let box = Unmanaged.passRetained(Box(completion))
+        let trampoline: @convention(c) (Bool, UnsafeMutableRawPointer?) -> Void = { allowed, userdata in
+            guard let userdata else { return }
+            let box = Unmanaged<Box>.fromOpaque(userdata).takeRetainedValue()
+            box.body(allowed)
+        }
+        let reply: accessReply
+        if let purpose {
+            reply = purpose.withPlaydateCString {
+                snd.pointee.requestMicAccess.unsafelyUnwrapped($0, trampoline, box.toOpaque())
+            }
+        } else {
+            reply = snd.pointee.requestMicAccess.unsafelyUnwrapped(nil, trampoline, box.toOpaque())
+        }
+        if reply != kAccessAsk {
+            // The callback will not be invoked; balance the retain.
+            box.release()
+        }
+        return AccessReply(rawValue: UInt32(reply.rawValue)) ?? .ask
+    }
+
+    /// The current headphone and headset-microphone state.
+    public static var headphoneState: (headphone: Bool, headsetMic: Bool) {
+        var headphone: Int32 = 0, headsetMic: Int32 = 0
+        snd.pointee.getHeadphoneState.unsafelyUnwrapped(&headphone, &headsetMic, nil)
+        return (headphone != 0, headsetMic != 0)
+    }
+
+    /// Installs a callback invoked when the headphone or headset-mic state
+    /// changes.
+    public static func setHeadphoneChangeCallback(_ callback: ((_ headphone: Bool, _ headsetMic: Bool) -> Void)?) {
+        headphoneChangeCallback = callback
+        if callback != nil {
+            snd.pointee.getHeadphoneState.unsafelyUnwrapped(nil, nil, { headphone, mic in
+                Sound.headphoneChangeCallback?(headphone != 0, mic != 0)
+            })
+        } else {
+            snd.pointee.getHeadphoneState.unsafelyUnwrapped(nil, nil, nil)
+        }
+    }
+
+    nonisolated(unsafe) private static var headphoneChangeCallback: ((Bool, Bool) -> Void)?
+
+    /// Forces audio output to the headphone and/or speaker. When the
+    /// headphone jack drives output and `speaker` is also set, the speaker
+    /// plays too.
+    public static func setOutputsActive(headphone: Bool, speaker: Bool) {
+        snd.pointee.setOutputsActive.unsafelyUnwrapped(headphone ? 1 : 0, speaker ? 1 : 0)
+    }
+
+    /// Adds a callback-based source to the default channel. The callback
+    /// fills the sample buffers and returns `true` if it produced output.
+    /// Buffers hold 16-bit samples; `right` is non-nil only when `stereo`.
+    public static func addSource(stereo: Bool,
+                                 _ callback: @escaping CallbackSource.Callback) -> CallbackSource {
+        let source = CallbackSource(callback: callback)
+        let pointer = snd.pointee.addSource.unsafelyUnwrapped(
+            CallbackSource.trampoline, source.contextPointer, stereo ? 1 : 0)
+        source.adopt(pointer: pointer.unsafelyUnwrapped)
+        return source
+    }
+
+    // MARK: - Channels
+
+    /// A mixer channel holding sources and effects. Wraps `SoundChannel`.
+    public final class Channel {
+        private static var api: UnsafePointer<playdate_sound_channel> { Playdate.channelAPI.unsafelyUnwrapped }
+
+        let pointer: OpaquePointer
+        let isOwned: Bool
+        private var retainedSources: [Source] = []
+        private var retainedEffects: [Effect] = []
+        private var retainedModulators: [SignalValue] = []
+
+        init(pointer: OpaquePointer, isOwned: Bool) {
+            self.pointer = pointer
+            self.isOwned = isOwned
+        }
+
+        /// Creates a new channel. Add it to the sound engine with `add()`.
+        public convenience init() {
+            self.init(pointer: Channel.api.pointee.newChannel.unsafelyUnwrapped().unsafelyUnwrapped,
+                      isOwned: true)
+        }
+
+        deinit {
+            if isOwned {
+                Channel.api.pointee.freeChannel.unsafelyUnwrapped(pointer)
+                // The freed channel no longer pulls its callback sources, so
+                // their trampoline registrations can be released too.
+                for source in retainedSources where source is CallbackSource {
+                    CallbackSource.release(source)
+                }
+            }
+        }
+
+        /// The default channel, which sources are added to unless otherwise
+        /// specified. A single shared wrapper, so resources retained through
+        /// it (sources, effects, modulators) stay alive.
+        public static var `default`: Channel { defaultChannel }
+
+        nonisolated(unsafe) private static let defaultChannel =
+            Channel(pointer: snd.pointee.getDefaultChannel.unsafelyUnwrapped().unsafelyUnwrapped,
+                    isOwned: false)
+
+        nonisolated(unsafe) private static var addedChannels: [Channel] = []
+
+        /// Adds the channel to the sound engine.
+        @discardableResult
+        public func add() -> Bool {
+            let added = snd.pointee.addChannel.unsafelyUnwrapped(pointer) != 0
+            if added, !Channel.addedChannels.contains(where: { $0 === self }) {
+                Channel.addedChannels.append(self)
+            }
+            return added
+        }
+
+        /// Removes the channel from the sound engine.
+        @discardableResult
+        public func remove() -> Bool {
+            let removed = snd.pointee.removeChannel.unsafelyUnwrapped(pointer) != 0
+            Channel.addedChannels.removeAll { $0 === self }
+            return removed
+        }
+
+        /// Adds a source to the channel. A source can only be on one channel.
+        @discardableResult
+        public func addSource(_ source: Source) -> Bool {
+            let added = Channel.api.pointee.addSource.unsafelyUnwrapped(pointer, source.pointer) != 0
+            if added, !retainedSources.contains(where: { $0 === source }) {
+                retainedSources.append(source)
+            }
+            return added
+        }
+
+        @discardableResult
+        public func removeSource(_ source: Source) -> Bool {
+            let removed = Channel.api.pointee.removeSource.unsafelyUnwrapped(pointer, source.pointer) != 0
+            // Only drop the retentions if the source was actually on this
+            // channel; otherwise another channel may still be pulling it.
+            if removed {
+                retainedSources.removeAll { $0 === source }
+                CallbackSource.release(source)
+            }
+            return removed
+        }
+
+        /// Adds a callback-based source to the channel. The callback fills
+        /// the sample buffers and returns `true` if it produced output.
+        public func addCallbackSource(stereo: Bool,
+                                      _ callback: @escaping CallbackSource.Callback) -> CallbackSource {
+            let source = CallbackSource(callback: callback)
+            let pointer = Channel.api.pointee.addCallbackSource.unsafelyUnwrapped(
+                self.pointer, CallbackSource.trampoline, source.contextPointer, stereo ? 1 : 0)
+            source.adopt(pointer: pointer.unsafelyUnwrapped)
+            retainedSources.append(source)
+            return source
+        }
+
+        @discardableResult
+        public func addEffect(_ effect: Effect) -> Bool {
+            let added = Channel.api.pointee.addEffect.unsafelyUnwrapped(pointer, effect.pointer) != 0
+            if added, !retainedEffects.contains(where: { $0 === effect }) {
+                retainedEffects.append(effect)
+            }
+            return added
+        }
+
+        @discardableResult
+        public func removeEffect(_ effect: Effect) -> Bool {
+            let removed = Channel.api.pointee.removeEffect.unsafelyUnwrapped(pointer, effect.pointer) != 0
+            retainedEffects.removeAll { $0 === effect }
+            return removed
+        }
+
+        /// The channel's volume, 0...1.
+        public var volume: Float {
+            get { Channel.api.pointee.getVolume.unsafelyUnwrapped(pointer) }
+            set { Channel.api.pointee.setVolume.unsafelyUnwrapped(pointer, newValue) }
+        }
+
+        /// Modulates the channel's volume.
+        public func setVolumeModulator(_ modulator: SignalValue?) {
+            retain(modulator)
+            Channel.api.pointee.setVolumeModulator.unsafelyUnwrapped(pointer, modulator?.pointer)
+        }
+
+        public var volumeModulator: SignalValue? {
+            SignalValue.wrap(Channel.api.pointee.getVolumeModulator.unsafelyUnwrapped(pointer))
+        }
+
+        /// The channel's stereo pan: -1 (left) to 1 (right).
+        public func setPan(_ pan: Float) {
+            Channel.api.pointee.setPan.unsafelyUnwrapped(pointer, pan)
+        }
+
+        /// Modulates the channel's pan. The signal's range 0...1 maps to
+        /// left...right.
+        public func setPanModulator(_ modulator: SignalValue?) {
+            retain(modulator)
+            Channel.api.pointee.setPanModulator.unsafelyUnwrapped(pointer, modulator?.pointer)
+        }
+
+        public var panModulator: SignalValue? {
+            SignalValue.wrap(Channel.api.pointee.getPanModulator.unsafelyUnwrapped(pointer))
+        }
+
+        /// A signal following the channel's dry (unprocessed) level.
+        public var dryLevelSignal: SignalValue? {
+            SignalValue.wrap(Channel.api.pointee.getDryLevelSignal.unsafelyUnwrapped(pointer))
+        }
+
+        /// A signal following the channel's wet (processed) level.
+        public var wetLevelSignal: SignalValue? {
+            SignalValue.wrap(Channel.api.pointee.getWetLevelSignal.unsafelyUnwrapped(pointer))
+        }
+
+        /// The channel's output as a source, for feeding into another channel.
+        /// The same wrapper is returned on every access, so callbacks
+        /// registered on it stay valid for the channel's lifetime.
+        public var outputAsSource: Source? {
+            guard let source = Channel.api.pointee.getOutputAsSource.unsafelyUnwrapped(pointer) else {
+                return nil
+            }
+            if let cached = cachedOutputSource, cached.pointer == source {
+                return cached
+            }
+            let wrapper = Source(pointer: source, isOwned: false)
+            cachedOutputSource = wrapper
+            return wrapper
+        }
+
+        private var cachedOutputSource: Source?
+
+        private func retain(_ modulator: SignalValue?) {
+            if let modulator, !retainedModulators.contains(where: { $0 === modulator }) {
+                retainedModulators.append(modulator)
+            }
+        }
+    }
+}

Sources/PlaydateKit/SoundEffect.swift

@@ -0,0 +1,393 @@
+//
+//  SoundEffect.swift
+//  SoundEffect wrappers: filters, bitcrusher, ring modulator, delay line,
+//  and overdrive.
+//
+
+internal import CPlaydate
+
+private var effectAPI: UnsafePointer<playdate_sound_effect> { Playdate.effectAPI.unsafelyUnwrapped }
+
+extension Sound {
+    /// An effect that processes a channel's audio: the base class of the
+    /// built-in effects. Wraps `SoundEffect`.
+    public class Effect {
+        /// Processes up to `AUDIO_FRAMES_PER_CYCLE` sample frames in signed
+        /// Q8.24 format. `bufferActive` is `false` when the input buffer is
+        /// silent. Returns `true` if the effect produced output.
+        public typealias Processor = (_ left: UnsafeMutableBufferPointer<Int32>,
+                                      _ right: UnsafeMutableBufferPointer<Int32>?,
+                                      _ bufferActive: Bool) -> Bool
+
+        let pointer: OpaquePointer
+        let isOwned: Bool
+        private var retainedMixModulator: SignalValue?
+        private var processorBox: Unmanaged<ProcessorBox>?
+
+        final class ProcessorBox {
+            let processor: Processor
+            init(_ processor: @escaping Processor) { self.processor = processor }
+        }
+
+        init(pointer: OpaquePointer, isOwned: Bool) {
+            self.pointer = pointer
+            self.isOwned = isOwned
+        }
+
+        /// Creates an effect that processes audio with a Swift callback.
+        public init(processor: @escaping Processor) {
+            let box = Unmanaged.passRetained(ProcessorBox(processor))
+            processorBox = box
+            pointer = effectAPI.pointee.newEffect.unsafelyUnwrapped({ effect, left, right, nsamples, bufactive in
+                guard let effect, let left,
+                      let userdata = effectAPI.pointee.getUserdata.unsafelyUnwrapped(effect) else { return 0 }
+                let box = Unmanaged<ProcessorBox>.fromOpaque(userdata).takeUnretainedValue()
+                let leftBuffer = UnsafeMutableBufferPointer(start: left, count: Int(nsamples))
+                let rightBuffer = right.map { UnsafeMutableBufferPointer(start: $0, count: Int(nsamples)) }
+                return box.processor(leftBuffer, rightBuffer, bufactive != 0) ? 1 : 0
+            }, box.toOpaque()).unsafelyUnwrapped
+            isOwned = true
+        }
+
+        deinit {
+            if isOwned {
+                effectAPI.pointee.freeEffect.unsafelyUnwrapped(pointer)
+            }
+            processorBox?.release()
+        }
+
+        /// The wet/dry mix: 1 is fully processed, 0 fully dry.
+        public func setMix(_ level: Float) {
+            effectAPI.pointee.setMix.unsafelyUnwrapped(pointer, level)
+        }
+
+        public var mixModulator: SignalValue? {
+            get { SignalValue.wrap(effectAPI.pointee.getMixModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retainedMixModulator = newValue
+                effectAPI.pointee.setMixModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+    }
+
+    // MARK: - Two-pole filter
+
+    /// A two-pole IIR filter. Wraps `TwoPoleFilter`.
+    public final class TwoPoleFilter: Effect {
+        private static var api: UnsafePointer<playdate_sound_effect_twopolefilter> { Playdate.twoPoleFilterAPI.unsafelyUnwrapped }
+
+        public enum Kind: UInt32, Sendable {
+            case lowPass = 0
+            case highPass = 1
+            case bandPass = 2
+            case notch = 3
+            case peq = 4
+            case lowShelf = 5
+            case highShelf = 6
+
+            var cValue: TwoPoleFilterType { TwoPoleFilterType(TwoPoleFilterType.RawValue(rawValue)) }
+        }
+
+        private var retainedFrequencyModulator: SignalValue?
+        private var retainedResonanceModulator: SignalValue?
+
+        public init(kind: Kind = .lowPass) {
+            super.init(pointer: TwoPoleFilter.api.pointee.newFilter.unsafelyUnwrapped().unsafelyUnwrapped,
+                       isOwned: true)
+            setKind(kind)
+        }
+
+        deinit {
+            if isOwned {
+                TwoPoleFilter.api.pointee.freeFilter.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        public func setKind(_ kind: Kind) {
+            TwoPoleFilter.api.pointee.setType.unsafelyUnwrapped(pointer, kind.cValue)
+        }
+
+        /// The center/corner frequency, in Hz.
+        public func setFrequency(_ frequency: Float) {
+            TwoPoleFilter.api.pointee.setFrequency.unsafelyUnwrapped(pointer, frequency)
+        }
+
+        public var frequencyModulator: SignalValue? {
+            get { SignalValue.wrap(TwoPoleFilter.api.pointee.getFrequencyModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retainedFrequencyModulator = newValue
+                TwoPoleFilter.api.pointee.setFrequencyModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+
+        /// The gain, used by PEQ and shelf filters.
+        public func setGain(_ gain: Float) {
+            TwoPoleFilter.api.pointee.setGain.unsafelyUnwrapped(pointer, gain)
+        }
+
+        public func setResonance(_ resonance: Float) {
+            TwoPoleFilter.api.pointee.setResonance.unsafelyUnwrapped(pointer, resonance)
+        }
+
+        public var resonanceModulator: SignalValue? {
+            get { SignalValue.wrap(TwoPoleFilter.api.pointee.getResonanceModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retainedResonanceModulator = newValue
+                TwoPoleFilter.api.pointee.setResonanceModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+    }
+
+    // MARK: - One-pole filter
+
+    /// A one-pole low/high-pass filter. Wraps `OnePoleFilter`.
+    public final class OnePoleFilter: Effect {
+        private static var api: UnsafePointer<playdate_sound_effect_onepolefilter> { Playdate.onePoleFilterAPI.unsafelyUnwrapped }
+
+        private var retainedParameterModulator: SignalValue?
+
+        public init() {
+            super.init(pointer: OnePoleFilter.api.pointee.newFilter.unsafelyUnwrapped().unsafelyUnwrapped,
+                       isOwned: true)
+        }
+
+        deinit {
+            if isOwned {
+                OnePoleFilter.api.pointee.freeFilter.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// The filter's cutoff: -1 to 1, where values above 0 are low-pass
+        /// and values below 0 high-pass.
+        public func setParameter(_ parameter: Float) {
+            OnePoleFilter.api.pointee.setParameter.unsafelyUnwrapped(pointer, parameter)
+        }
+
+        public var parameterModulator: SignalValue? {
+            get { SignalValue.wrap(OnePoleFilter.api.pointee.getParameterModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retainedParameterModulator = newValue
+                OnePoleFilter.api.pointee.setParameterModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+    }
+
+    // MARK: - Bit crusher
+
+    /// A bit-crushing and downsampling effect. Wraps `BitCrusher`.
+    public final class BitCrusher: Effect {
+        private static var api: UnsafePointer<playdate_sound_effect_bitcrusher> { Playdate.bitCrusherAPI.unsafelyUnwrapped }
+
+        private var retainedModulators: [SignalValue] = []
+
+        public init() {
+            super.init(pointer: BitCrusher.api.pointee.newBitCrusher.unsafelyUnwrapped().unsafelyUnwrapped,
+                       isOwned: true)
+        }
+
+        deinit {
+            if isOwned {
+                BitCrusher.api.pointee.freeBitCrusher.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// When `true`, `setDepth` values map exponentially to bit depth.
+        public func setExponential(_ flag: Bool) {
+            BitCrusher.api.pointee.setExponential.unsafelyUnwrapped(pointer, flag)
+        }
+
+        /// The amount of crushing, 0 (none) to 1 (quantized to 1 bit).
+        public func setDepth(_ depth: Float) {
+            BitCrusher.api.pointee.setDepth.unsafelyUnwrapped(pointer, depth)
+        }
+
+        public var depthModulator: SignalValue? {
+            get { SignalValue.wrap(BitCrusher.api.pointee.getDepthModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retain(newValue)
+                BitCrusher.api.pointee.setDepthModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+
+        /// The amount of downsampling, 0 (none) to 1 (every sample repeated).
+        public func setDownsampling(_ downsampling: Float) {
+            BitCrusher.api.pointee.setDownsampling.unsafelyUnwrapped(pointer, downsampling)
+        }
+
+        public var downsamplingModulator: SignalValue? {
+            get { SignalValue.wrap(BitCrusher.api.pointee.getDownsamplingModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retain(newValue)
+                BitCrusher.api.pointee.setDownsamplingModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+
+        private func retain(_ modulator: SignalValue?) {
+            if let modulator { retainedModulators.append(modulator) }
+        }
+    }
+
+    // MARK: - Ring modulator
+
+    /// A ring modulator effect. Wraps `RingModulator`.
+    public final class RingModulator: Effect {
+        private static var api: UnsafePointer<playdate_sound_effect_ringmodulator> { Playdate.ringModulatorAPI.unsafelyUnwrapped }
+
+        private var retainedFrequencyModulator: SignalValue?
+
+        public init() {
+            super.init(pointer: RingModulator.api.pointee.newRingmod.unsafelyUnwrapped().unsafelyUnwrapped,
+                       isOwned: true)
+        }
+
+        deinit {
+            if isOwned {
+                RingModulator.api.pointee.freeRingmod.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// The modulation frequency, in Hz.
+        public func setFrequency(_ frequency: Float) {
+            RingModulator.api.pointee.setFrequency.unsafelyUnwrapped(pointer, frequency)
+        }
+
+        public var frequencyModulator: SignalValue? {
+            get { SignalValue.wrap(RingModulator.api.pointee.getFrequencyModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retainedFrequencyModulator = newValue
+                RingModulator.api.pointee.setFrequencyModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+    }
+
+    // MARK: - Delay line
+
+    /// A tap into a delay line; produces audio and can be added to a channel
+    /// as a source. Wraps `DelayLineTap`.
+    public final class DelayLineTap: Source {
+        private static var api: UnsafePointer<playdate_sound_effect_delayline> { Playdate.delayLineAPI.unsafelyUnwrapped }
+
+        /// The delay line is retained so the tap stays valid.
+        private let delayLine: DelayLine
+        private var retainedDelayModulator: SignalValue?
+
+        init(pointer: OpaquePointer, delayLine: DelayLine) {
+            self.delayLine = delayLine
+            super.init(pointer: pointer, isOwned: true)
+        }
+
+        deinit {
+            DelayLineTap.api.pointee.freeTap.unsafelyUnwrapped(pointer)
+        }
+
+        /// The tap's position in the delay line, in frames.
+        public func setDelay(frames: Int) {
+            DelayLineTap.api.pointee.setTapDelay.unsafelyUnwrapped(pointer, Int32(frames))
+        }
+
+        public var delayModulator: SignalValue? {
+            get { SignalValue.wrap(DelayLineTap.api.pointee.getTapDelayModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retainedDelayModulator = newValue
+                DelayLineTap.api.pointee.setTapDelayModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+
+        /// For stereo delay lines: swaps the left and right channels.
+        public func setChannelsFlipped(_ flipped: Bool) {
+            DelayLineTap.api.pointee.setTapChannelsFlipped.unsafelyUnwrapped(pointer, flipped ? 1 : 0)
+        }
+    }
+
+    /// A delay line effect. Wraps `DelayLine`.
+    public final class DelayLine: Effect {
+        private static var api: UnsafePointer<playdate_sound_effect_delayline> { Playdate.delayLineAPI.unsafelyUnwrapped }
+
+        /// Creates a delay line holding `length` frames.
+        public init(length: Int, stereo: Bool = false) {
+            super.init(pointer: DelayLine.api.pointee.newDelayLine.unsafelyUnwrapped(
+                Int32(length), stereo ? 1 : 0).unsafelyUnwrapped, isOwned: true)
+        }
+
+        deinit {
+            if isOwned {
+                DelayLine.api.pointee.freeDelayLine.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// Changes the delay length. Cannot be larger than the line's
+        /// original length.
+        public func setLength(frames: Int) {
+            DelayLine.api.pointee.setLength.unsafelyUnwrapped(pointer, Int32(frames))
+        }
+
+        /// The feedback level, 0...1.
+        public func setFeedback(_ feedback: Float) {
+            DelayLine.api.pointee.setFeedback.unsafelyUnwrapped(pointer, feedback)
+        }
+
+        /// Adds a tap `delay` frames behind the write head. The tap can be
+        /// added to a channel as a sound source.
+        public func addTap(delay: Int) -> DelayLineTap? {
+            guard let tap = DelayLine.api.pointee.addTap.unsafelyUnwrapped(pointer, Int32(delay)) else {
+                return nil
+            }
+            return DelayLineTap(pointer: tap, delayLine: self)
+        }
+    }
+
+    // MARK: - Overdrive
+
+    /// An overdrive/distortion effect. Wraps `Overdrive`.
+    public final class Overdrive: Effect {
+        private static var api: UnsafePointer<playdate_sound_effect_overdrive> { Playdate.overdriveAPI.unsafelyUnwrapped }
+
+        private var retainedModulators: [SignalValue] = []
+
+        public init() {
+            super.init(pointer: Overdrive.api.pointee.newOverdrive.unsafelyUnwrapped().unsafelyUnwrapped,
+                       isOwned: true)
+        }
+
+        deinit {
+            if isOwned {
+                Overdrive.api.pointee.freeOverdrive.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// The input gain applied before clipping.
+        public func setGain(_ gain: Float) {
+            Overdrive.api.pointee.setGain.unsafelyUnwrapped(pointer, gain)
+        }
+
+        /// The level where the amplified input clips.
+        public func setLimit(_ limit: Float) {
+            Overdrive.api.pointee.setLimit.unsafelyUnwrapped(pointer, limit)
+        }
+
+        public var limitModulator: SignalValue? {
+            get { SignalValue.wrap(Overdrive.api.pointee.getLimitModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retain(newValue)
+                Overdrive.api.pointee.setLimitModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+
+        /// A DC offset applied to the input, making the clipping asymmetric.
+        public func setOffset(_ offset: Float) {
+            Overdrive.api.pointee.setOffset.unsafelyUnwrapped(pointer, offset)
+        }
+
+        public var offsetModulator: SignalValue? {
+            get { SignalValue.wrap(Overdrive.api.pointee.getOffsetModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retain(newValue)
+                Overdrive.api.pointee.setOffsetModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+
+        private func retain(_ modulator: SignalValue?) {
+            if let modulator { retainedModulators.append(modulator) }
+        }
+    }
+}

Sources/PlaydateKit/SoundSignal.swift

@@ -0,0 +1,345 @@
+//
+//  SoundSignal.swift
+//  Signal wrappers: PDSynthSignalValue, PDSynthSignal, PDSynthLFO,
+//  PDSynthEnvelope, and ControlSignal.
+//
+
+internal import CPlaydate
+
+extension Sound {
+    /// A value that can modulate a parameter. The base class of `Signal`,
+    /// `LFO`, `Envelope`, and `ControlSignal`. Wraps `PDSynthSignalValue`.
+    public class SignalValue {
+        let pointer: OpaquePointer
+        let isOwned: Bool
+
+        init(pointer: OpaquePointer, isOwned: Bool) {
+            self.pointer = pointer
+            self.isOwned = isOwned
+        }
+
+        /// Wraps a signal value pointer returned by the OS (not owned).
+        static func wrap(_ pointer: OpaquePointer?) -> SignalValue? {
+            guard let pointer else { return nil }
+            return SignalValue(pointer: pointer, isOwned: false)
+        }
+    }
+
+    /// A signal object; also provides custom signals driven by Swift
+    /// callbacks. Wraps `PDSynthSignal`.
+    public final class Signal: SignalValue {
+        private static var api: UnsafePointer<playdate_sound_signal> { Playdate.signalAPI.unsafelyUnwrapped }
+
+        /// Custom signal callbacks.
+        public struct Callbacks {
+            /// Returns the signal's value at the end of the current cycle.
+            /// `ioFrames` is the number of frames until the cycle ends and
+            /// may be lowered to interpolate toward `interpolationValue`.
+            public var step: (_ ioFrames: UnsafeMutablePointer<Int32>?,
+                              _ interpolationValue: UnsafeMutablePointer<Float>?) -> Float
+            /// Called on note-on events. `length` is -1 for indefinite notes.
+            public var noteOn: ((_ note: MIDINote, _ velocity: Float, _ length: Float) -> Void)?
+            /// Called on note-off events. `stopped` is `false` when the note
+            /// is released and `true` when it actually stops playing;
+            /// `offset` is the frame offset within the current cycle.
+            public var noteOff: ((_ stopped: Bool, _ offset: Int) -> Void)?
+
+            public init(step: @escaping (_ ioFrames: UnsafeMutablePointer<Int32>?,
+                                         _ interpolationValue: UnsafeMutablePointer<Float>?) -> Float,
+                        noteOn: ((_ note: MIDINote, _ velocity: Float, _ length: Float) -> Void)? = nil,
+                        noteOff: ((_ stopped: Bool, _ offset: Int) -> Void)? = nil) {
+                self.step = step
+                self.noteOn = noteOn
+                self.noteOff = noteOff
+            }
+        }
+
+        private final class Box {
+            let callbacks: Callbacks
+            init(_ callbacks: Callbacks) { self.callbacks = callbacks }
+        }
+
+        /// Creates a signal driven by the given callbacks.
+        public init(callbacks: Callbacks) {
+            let box = Unmanaged.passRetained(Box(callbacks))
+            let pointer = Signal.api.pointee.newSignal.unsafelyUnwrapped(
+                { userdata, ioFrames, interpolationValue in
+                    guard let userdata else { return 0 }
+                    let box = Unmanaged<Box>.fromOpaque(userdata).takeUnretainedValue()
+                    return box.callbacks.step(ioFrames, interpolationValue)
+                },
+                { userdata, note, velocity, length in
+                    guard let userdata else { return }
+                    let box = Unmanaged<Box>.fromOpaque(userdata).takeUnretainedValue()
+                    box.callbacks.noteOn?(note, velocity, length)
+                },
+                { userdata, stopped, offset in
+                    guard let userdata else { return }
+                    let box = Unmanaged<Box>.fromOpaque(userdata).takeUnretainedValue()
+                    box.callbacks.noteOff?(stopped != 0, Int(offset))
+                },
+                { userdata in
+                    guard let userdata else { return }
+                    Unmanaged<Box>.fromOpaque(userdata).release()
+                },
+                box.toOpaque())
+            super.init(pointer: pointer.unsafelyUnwrapped, isOwned: true)
+        }
+
+        /// Creates a plain signal object wrapping an existing signal value,
+        /// so it can be scaled and offset.
+        public init(value: SignalValue) {
+            let pointer = Signal.api.pointee.newSignalForValue.unsafelyUnwrapped(value.pointer)
+            super.init(pointer: pointer.unsafelyUnwrapped, isOwned: true)
+        }
+
+        override init(pointer: OpaquePointer, isOwned: Bool) {
+            super.init(pointer: pointer, isOwned: isOwned)
+        }
+
+        deinit {
+            if isOwned {
+                Signal.api.pointee.freeSignal.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// The signal's current value.
+        public var value: Float {
+            Signal.api.pointee.getValue.unsafelyUnwrapped(pointer)
+        }
+
+        /// Scales the signal's output.
+        public func setValueScale(_ scale: Float) {
+            Signal.api.pointee.setValueScale.unsafelyUnwrapped(pointer, scale)
+        }
+
+        /// Offsets the signal's output.
+        public func setValueOffset(_ offset: Float) {
+            Signal.api.pointee.setValueOffset.unsafelyUnwrapped(pointer, offset)
+        }
+    }
+
+    // MARK: - LFO
+
+    /// A low-frequency oscillator signal. Wraps `PDSynthLFO`.
+    public final class LFO: SignalValue {
+        private static var api: UnsafePointer<playdate_sound_lfo> { Playdate.lfoAPI.unsafelyUnwrapped }
+
+        /// The oscillator's waveform.
+        public enum Shape: UInt32, Sendable {
+            case square = 0
+            case triangle = 1
+            case sine = 2
+            case sampleAndHold = 3
+            case sawtoothUp = 4
+            case sawtoothDown = 5
+            case arpeggiator = 6
+            case function = 7
+
+            var cValue: LFOType { LFOType(LFOType.RawValue(rawValue)) }
+        }
+
+        var function: ((LFO) -> Float)?
+
+        public init(shape: Shape = .sine) {
+            let pointer = LFO.api.pointee.newLFO.unsafelyUnwrapped(shape.cValue)
+            super.init(pointer: pointer.unsafelyUnwrapped, isOwned: true)
+        }
+
+        deinit {
+            if isOwned {
+                LFO.api.pointee.freeLFO.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        public func setShape(_ shape: Shape) {
+            LFO.api.pointee.setType.unsafelyUnwrapped(pointer, shape.cValue)
+        }
+
+        /// The LFO rate, in cycles per second.
+        public func setRate(_ rate: Float) {
+            LFO.api.pointee.setRate.unsafelyUnwrapped(pointer, rate)
+        }
+
+        /// The current phase, 0...1.
+        public func setPhase(_ phase: Float) {
+            LFO.api.pointee.setPhase.unsafelyUnwrapped(pointer, phase)
+        }
+
+        /// The phase the LFO starts at when a note starts, 0...1.
+        public func setStartPhase(_ phase: Float) {
+            LFO.api.pointee.setStartPhase.unsafelyUnwrapped(pointer, phase)
+        }
+
+        /// The center value of the LFO output.
+        public func setCenter(_ center: Float) {
+            LFO.api.pointee.setCenter.unsafelyUnwrapped(pointer, center)
+        }
+
+        /// The amplitude of the LFO around its center.
+        public func setDepth(_ depth: Float) {
+            LFO.api.pointee.setDepth.unsafelyUnwrapped(pointer, depth)
+        }
+
+        /// For `.arpeggiator` LFOs: the sequence of values (in half-steps)
+        /// to step through.
+        public func setArpeggiation(_ steps: [Float]) {
+            var steps = steps
+            steps.withUnsafeMutableBufferPointer { buffer in
+                LFO.api.pointee.setArpeggiation.unsafelyUnwrapped(pointer, Int32(buffer.count),
+                                                          buffer.baseAddress)
+            }
+        }
+
+        /// For `.function` LFOs: the Swift function providing the value. If
+        /// `interpolate` is `true`, values are interpolated between calls.
+        public func setFunction(interpolate: Bool = false, _ function: @escaping (LFO) -> Float) {
+            self.function = function
+            LFO.api.pointee.setFunction.unsafelyUnwrapped(pointer, { _, userdata in
+                guard let userdata else { return 0 }
+                let lfo = Unmanaged<LFO>.fromOpaque(userdata).takeUnretainedValue()
+                return lfo.function?(lfo) ?? 0
+            }, Unmanaged.passUnretained(self).toOpaque(), interpolate ? 1 : 0)
+        }
+
+        /// Waits `holdoff` seconds after a note starts, then ramps the LFO
+        /// depth up over `rampTime` seconds.
+        public func setDelay(holdoff: Float, rampTime: Float) {
+            LFO.api.pointee.setDelay.unsafelyUnwrapped(pointer, holdoff, rampTime)
+        }
+
+        /// Whether the LFO phase restarts on every new note.
+        public func setRetrigger(_ flag: Bool) {
+            LFO.api.pointee.setRetrigger.unsafelyUnwrapped(pointer, flag ? 1 : 0)
+        }
+
+        /// When `true`, the LFO runs globally instead of per-note.
+        public func setGlobal(_ global: Bool) {
+            LFO.api.pointee.setGlobal.unsafelyUnwrapped(pointer, global ? 1 : 0)
+        }
+
+        /// Seeds the random number generator used by `.sampleAndHold` LFOs.
+        public func setRandomSeed(_ seed: UInt16) {
+            LFO.api.pointee.setRandomSeed.unsafelyUnwrapped(pointer, seed)
+        }
+
+        public var value: Float {
+            LFO.api.pointee.getValue.unsafelyUnwrapped(pointer)
+        }
+    }
+
+    // MARK: - Envelope
+
+    /// An ADSR envelope signal. Wraps `PDSynthEnvelope`.
+    public final class Envelope: SignalValue {
+        private static var api: UnsafePointer<playdate_sound_envelope> { Playdate.envelopeAPI.unsafelyUnwrapped }
+
+        /// Creates an envelope with the given attack and decay times
+        /// (seconds), sustain level (0...1), and release time (seconds).
+        public init(attack: Float = 0, decay: Float = 0, sustain: Float = 1, release: Float = 0) {
+            let pointer = Envelope.api.pointee.newEnvelope.unsafelyUnwrapped(attack, decay, sustain, release)
+            super.init(pointer: pointer.unsafelyUnwrapped, isOwned: true)
+        }
+
+        override init(pointer: OpaquePointer, isOwned: Bool) {
+            super.init(pointer: pointer, isOwned: isOwned)
+        }
+
+        deinit {
+            if isOwned {
+                Envelope.api.pointee.freeEnvelope.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        public func setAttack(_ attack: Float) {
+            Envelope.api.pointee.setAttack.unsafelyUnwrapped(pointer, attack)
+        }
+
+        public func setDecay(_ decay: Float) {
+            Envelope.api.pointee.setDecay.unsafelyUnwrapped(pointer, decay)
+        }
+
+        public func setSustain(_ sustain: Float) {
+            Envelope.api.pointee.setSustain.unsafelyUnwrapped(pointer, sustain)
+        }
+
+        public func setRelease(_ release: Float) {
+            Envelope.api.pointee.setRelease.unsafelyUnwrapped(pointer, release)
+        }
+
+        /// When `true`, a new note while a note is playing does not restart
+        /// the envelope.
+        public func setLegato(_ flag: Bool) {
+            Envelope.api.pointee.setLegato.unsafelyUnwrapped(pointer, flag ? 1 : 0)
+        }
+
+        /// When `true`, a new note restarts the envelope from zero instead of
+        /// its current value.
+        public func setRetrigger(_ flag: Bool) {
+            Envelope.api.pointee.setRetrigger.unsafelyUnwrapped(pointer, flag ? 1 : 0)
+        }
+
+        /// Bends the envelope's segments: 0 is linear, 1 is maximum curvature.
+        public func setCurvature(_ amount: Float) {
+            Envelope.api.pointee.setCurvature.unsafelyUnwrapped(pointer, amount)
+        }
+
+        /// How much note velocity scales the envelope's output.
+        public func setVelocitySensitivity(_ sensitivity: Float) {
+            Envelope.api.pointee.setVelocitySensitivity.unsafelyUnwrapped(pointer, sensitivity)
+        }
+
+        /// Scales the envelope's rate by note: notes above `start` play the
+        /// envelope faster (up to `scaling` at `end` and beyond).
+        public func setRateScaling(_ scaling: Float, start: MIDINote, end: MIDINote) {
+            Envelope.api.pointee.setRateScaling.unsafelyUnwrapped(pointer, scaling, start, end)
+        }
+
+        public var value: Float {
+            Envelope.api.pointee.getValue.unsafelyUnwrapped(pointer)
+        }
+    }
+
+    // MARK: - ControlSignal
+
+    /// A signal whose values are set on a sequence timeline. Wraps
+    /// `ControlSignal`.
+    public final class ControlSignal: SignalValue {
+        private static var api: UnsafePointer<playdate_control_signal> { Playdate.controlSignalAPI.unsafelyUnwrapped }
+
+        public init() {
+            let pointer = ControlSignal.api.pointee.newSignal.unsafelyUnwrapped()
+            super.init(pointer: pointer.unsafelyUnwrapped, isOwned: true)
+        }
+
+        override init(pointer: OpaquePointer, isOwned: Bool) {
+            super.init(pointer: pointer, isOwned: isOwned)
+        }
+
+        deinit {
+            if isOwned {
+                ControlSignal.api.pointee.freeSignal.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        public func clearEvents() {
+            ControlSignal.api.pointee.clearEvents.unsafelyUnwrapped(pointer)
+        }
+
+        /// Adds a value at `step` in the signal's timeline. If `interpolate`
+        /// is `true`, the value ramps from the previous event.
+        public func addEvent(step: Int, value: Float, interpolate: Bool = false) {
+            ControlSignal.api.pointee.addEvent.unsafelyUnwrapped(pointer, Int32(step), value,
+                                                         interpolate ? 1 : 0)
+        }
+
+        public func removeEvent(step: Int) {
+            ControlSignal.api.pointee.removeEvent.unsafelyUnwrapped(pointer, Int32(step))
+        }
+
+        /// The MIDI controller number for signals loaded from a MIDI file.
+        public var midiControllerNumber: Int {
+            Int(ControlSignal.api.pointee.getMIDIControllerNumber.unsafelyUnwrapped(pointer))
+        }
+    }
+}

Sources/PlaydateKit/SoundSource.swift

@@ -0,0 +1,436 @@
+//
+//  SoundSource.swift
+//  SoundSource, FilePlayer, AudioSample, and SamplePlayer wrappers.
+//
+
+internal import CPlaydate
+
+extension Sound {
+    /// A source of audio: the base class of `FilePlayer`, `SamplePlayer`,
+    /// `Synth`, `DelayLineTap`, and `CallbackSource`. Wraps `SoundSource`.
+    public class Source {
+        private static var api: UnsafePointer<playdate_sound_source> { Playdate.sourceAPI.unsafelyUnwrapped }
+
+        /// The underlying C object. Set once, immediately after creation.
+        var pointer: OpaquePointer!
+        let isOwned: Bool
+        var finishCallback: ((Source) -> Void)?
+
+        init(pointer: OpaquePointer?, isOwned: Bool) {
+            self.pointer = pointer
+            self.isOwned = isOwned
+        }
+
+        /// Sets the playback volume for the left and right channels, 0...1.
+        public func setVolume(left: Float, right: Float) {
+            Source.api.pointee.setVolume.unsafelyUnwrapped(pointer, left, right)
+        }
+
+        /// Sets the playback volume of both channels.
+        public func setVolume(_ volume: Float) {
+            setVolume(left: volume, right: volume)
+        }
+
+        /// The playback volume of the left and right channels.
+        public var volume: (left: Float, right: Float) {
+            var left: Float = 0, right: Float = 0
+            Source.api.pointee.getVolume.unsafelyUnwrapped(pointer, &left, &right)
+            return (left, right)
+        }
+
+        public var isPlaying: Bool {
+            Source.api.pointee.isPlaying.unsafelyUnwrapped(pointer) != 0
+        }
+
+        /// Sets a function called when the source finishes playing.
+        public func setFinishCallback(_ callback: ((Source) -> Void)?) {
+            finishCallback = callback
+            if callback != nil {
+                Source.api.pointee.setFinishCallback.unsafelyUnwrapped(pointer, { _, userdata in
+                    guard let userdata else { return }
+                    let source = Unmanaged<Source>.fromOpaque(userdata).takeUnretainedValue()
+                    source.finishCallback?(source)
+                }, Unmanaged.passUnretained(self).toOpaque())
+            } else {
+                Source.api.pointee.setFinishCallback.unsafelyUnwrapped(pointer, nil, nil)
+            }
+        }
+    }
+
+    /// A source that produces audio by calling back into Swift.
+    public final class CallbackSource: Source {
+        /// Fills the sample buffers and returns `true` if output was
+        /// produced. `right` is non-nil only for stereo sources.
+        public typealias Callback = (_ left: UnsafeMutableBufferPointer<Int16>,
+                                     _ right: UnsafeMutableBufferPointer<Int16>?) -> Bool
+
+        let callback: Callback
+
+        /// Every callback source is kept alive here while the C side may
+        /// still invoke its trampoline: from creation until it is removed
+        /// with `Sound.removeSource`/`Channel.removeSource`, or until its
+        /// owning channel is freed.
+        nonisolated(unsafe) static var live: [CallbackSource] = []
+
+        /// Releases the registration added by `adopt(pointer:)`.
+        static func release(_ source: Source) {
+            live.removeAll { $0 === source }
+        }
+
+        init(callback: @escaping Callback) {
+            self.callback = callback
+            super.init(pointer: nil, isOwned: false)
+        }
+
+        var contextPointer: UnsafeMutableRawPointer {
+            Unmanaged.passUnretained(self).toOpaque()
+        }
+
+        static let trampoline: @convention(c) (UnsafeMutableRawPointer?, UnsafeMutablePointer<Int16>?,
+                                               UnsafeMutablePointer<Int16>?, Int32) -> Int32 = { context, left, right, length in
+            guard let context, let left else { return 0 }
+            let source = Unmanaged<CallbackSource>.fromOpaque(context).takeUnretainedValue()
+            let leftBuffer = UnsafeMutableBufferPointer(start: left, count: Int(length))
+            let rightBuffer = right.map { UnsafeMutableBufferPointer(start: $0, count: Int(length)) }
+            return source.callback(leftBuffer, rightBuffer) ? 1 : 0
+        }
+
+        /// Attaches the C object created for this source.
+        func adopt(pointer: OpaquePointer) {
+            self.pointer = pointer
+            CallbackSource.live.append(self)
+        }
+    }
+
+    // MARK: - FilePlayer
+
+    /// Streams audio from a file. Wraps `FilePlayer`.
+    public final class FilePlayer: Source {
+        private static var api: UnsafePointer<playdate_sound_fileplayer> { Playdate.filePlayerAPI.unsafelyUnwrapped }
+
+        var loopCallback: ((FilePlayer) -> Void)?
+        var fadeCallback: ((FilePlayer) -> Void)?
+        var mp3DataSource: ((UnsafeMutableBufferPointer<UInt8>) -> Int)?
+        private var retainedRateModulator: SignalValue?
+
+        override init(pointer: OpaquePointer?, isOwned: Bool) {
+            super.init(pointer: pointer, isOwned: isOwned)
+        }
+
+        public convenience init() {
+            self.init(pointer: FilePlayer.api.pointee.newPlayer.unsafelyUnwrapped().unsafelyUnwrapped,
+                      isOwned: true)
+        }
+
+        /// Creates a player and loads the audio file at `path`.
+        public convenience init(path: String) throws(PlaydateError) {
+            self.init()
+            try load(path: path)
+        }
+
+        deinit {
+            if isOwned {
+                FilePlayer.api.pointee.freePlayer.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// Prepares the player to stream the file at `path`.
+        public func load(path: String) throws(PlaydateError) {
+            let loaded = path.withPlaydateCString {
+                FilePlayer.api.pointee.loadIntoPlayer.unsafelyUnwrapped(pointer, $0) != 0
+            }
+            if !loaded {
+                throw PlaydateError(message: "unable to load audio file: \(path)")
+            }
+        }
+
+        /// Sets the length of the stream buffer, in seconds. Default 0.25.
+        public func setBufferLength(_ seconds: Float) {
+            FilePlayer.api.pointee.setBufferLength.unsafelyUnwrapped(pointer, seconds)
+        }
+
+        /// Starts playback, looping `repeat` times; 0 loops endlessly.
+        @discardableResult
+        public func play(repeat repeatCount: Int = 1) -> Bool {
+            FilePlayer.api.pointee.play.unsafelyUnwrapped(pointer, Int32(repeatCount)) != 0
+        }
+
+        public func pause() {
+            FilePlayer.api.pointee.pause.unsafelyUnwrapped(pointer)
+        }
+
+        public func stop() {
+            FilePlayer.api.pointee.stop.unsafelyUnwrapped(pointer)
+        }
+
+        /// The file's length in seconds.
+        public var length: Float {
+            FilePlayer.api.pointee.getLength.unsafelyUnwrapped(pointer)
+        }
+
+        /// The playback position in seconds.
+        public var offset: Float {
+            get { FilePlayer.api.pointee.getOffset.unsafelyUnwrapped(pointer) }
+            set { FilePlayer.api.pointee.setOffset.unsafelyUnwrapped(pointer, newValue) }
+        }
+
+        /// The playback rate; 1 is normal speed, negative values are not
+        /// supported.
+        public var rate: Float {
+            get { FilePlayer.api.pointee.getRate.unsafelyUnwrapped(pointer) }
+            set { FilePlayer.api.pointee.setRate.unsafelyUnwrapped(pointer, newValue) }
+        }
+
+        /// Loops playback between `start` and `end` (seconds) while playing
+        /// with `repeat` 0. An `end` of 0 means the end of the file.
+        public func setLoopRange(start: Float, end: Float) {
+            FilePlayer.api.pointee.setLoopRange.unsafelyUnwrapped(pointer, start, end)
+        }
+
+        /// Whether playback underran because the file could not be read fast
+        /// enough.
+        public var didUnderrun: Bool {
+            FilePlayer.api.pointee.didUnderrun.unsafelyUnwrapped(pointer) != 0
+        }
+
+        /// Stops playback (instead of looping the buffer) on underrun.
+        public func setStopOnUnderrun(_ flag: Bool) {
+            FilePlayer.api.pointee.setStopOnUnderrun.unsafelyUnwrapped(pointer, flag ? 1 : 0)
+        }
+
+        /// Sets a function called every time playback loops.
+        public func setLoopCallback(_ callback: ((FilePlayer) -> Void)?) {
+            loopCallback = callback
+            if callback != nil {
+                FilePlayer.api.pointee.setLoopCallback.unsafelyUnwrapped(pointer, { _, userdata in
+                    guard let userdata else { return }
+                    let player = Unmanaged<FilePlayer>.fromOpaque(userdata).takeUnretainedValue()
+                    player.loopCallback?(player)
+                }, Unmanaged.passUnretained(self).toOpaque())
+            } else {
+                FilePlayer.api.pointee.setLoopCallback.unsafelyUnwrapped(pointer, nil, nil)
+            }
+        }
+
+        /// Fades the volume to the given levels over `length` sample frames,
+        /// then calls `completion`.
+        public func fadeVolume(left: Float, right: Float, length: Int32,
+                               completion: ((FilePlayer) -> Void)? = nil) {
+            fadeCallback = completion
+            if completion != nil {
+                FilePlayer.api.pointee.fadeVolume.unsafelyUnwrapped(pointer, left, right, length, { _, userdata in
+                    guard let userdata else { return }
+                    let player = Unmanaged<FilePlayer>.fromOpaque(userdata).takeUnretainedValue()
+                    player.fadeCallback?(player)
+                }, Unmanaged.passUnretained(self).toOpaque())
+            } else {
+                FilePlayer.api.pointee.fadeVolume.unsafelyUnwrapped(pointer, left, right, length, nil, nil)
+            }
+        }
+
+        /// Streams MP3 data from a callback instead of a file. The callback
+        /// fills the buffer and returns the number of bytes written; return 0
+        /// to signal the end of the stream.
+        public func setMP3StreamSource(bufferLength: Float,
+                                       _ dataSource: @escaping (UnsafeMutableBufferPointer<UInt8>) -> Int) {
+            mp3DataSource = dataSource
+            FilePlayer.api.pointee.setMP3StreamSource.unsafelyUnwrapped(pointer, { data, bytes, userdata in
+                guard let userdata, let data else { return 0 }
+                let player = Unmanaged<FilePlayer>.fromOpaque(userdata).takeUnretainedValue()
+                let buffer = UnsafeMutableBufferPointer(start: data, count: Int(bytes))
+                return Int32(player.mp3DataSource?(buffer) ?? 0)
+            }, Unmanaged.passUnretained(self).toOpaque(), bufferLength)
+        }
+
+        /// Modulates the playback rate.
+        public var rateModulator: SignalValue? {
+            get { SignalValue.wrap(FilePlayer.api.pointee.getRateModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retainedRateModulator = newValue
+                FilePlayer.api.pointee.setRateModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+    }
+
+    // MARK: - AudioSample
+
+    /// Audio data loaded into memory. Wraps `AudioSample`.
+    public final class AudioSample {
+        private static var api: UnsafePointer<playdate_sound_sample> { Playdate.sampleAPI.unsafelyUnwrapped }
+
+        let pointer: OpaquePointer
+        let isOwned: Bool
+
+        init(pointer: OpaquePointer, isOwned: Bool) {
+            self.pointer = pointer
+            self.isOwned = isOwned
+        }
+
+        /// Allocates a sample buffer with room for `byteCount` bytes.
+        public convenience init(byteCount: Int) {
+            self.init(pointer: AudioSample.api.pointee.newSampleBuffer.unsafelyUnwrapped(
+                Int32(byteCount)).unsafelyUnwrapped, isOwned: true)
+        }
+
+        /// Loads the wav or aiff file at `path`.
+        public convenience init(path: String) throws(PlaydateError) {
+            let pointer = path.withPlaydateCString { AudioSample.api.pointee.load.unsafelyUnwrapped($0) }
+            guard let pointer else {
+                throw PlaydateError(message: "unable to load sample: \(path)")
+            }
+            self.init(pointer: pointer, isOwned: true)
+        }
+
+        /// Creates a sample referencing existing sample data. If
+        /// `freeWhenDone` is `true`, the OS frees `data` when the sample is
+        /// freed; otherwise the caller must keep `data` valid for the
+        /// sample's lifetime.
+        public convenience init?(data: UnsafeMutablePointer<UInt8>, format: Format,
+                                 sampleRate: UInt32, byteCount: Int, freeWhenDone: Bool) {
+            guard let pointer = AudioSample.api.pointee.newSampleFromData.unsafelyUnwrapped(
+                data, format.cValue, sampleRate, Int32(byteCount), freeWhenDone ? 1 : 0) else {
+                return nil
+            }
+            self.init(pointer: pointer, isOwned: true)
+        }
+
+        deinit {
+            if isOwned {
+                AudioSample.api.pointee.freeSample.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// Loads the file at `path` into this sample's buffer.
+        public func load(path: String) throws(PlaydateError) {
+            let loaded = path.withPlaydateCString {
+                AudioSample.api.pointee.loadIntoSample.unsafelyUnwrapped(pointer, $0) != 0
+            }
+            if !loaded {
+                throw PlaydateError(message: "unable to load sample: \(path)")
+            }
+        }
+
+        /// The sample's raw data, format, and rate.
+        public var data: (data: UnsafeMutablePointer<UInt8>?, format: Format,
+                          sampleRate: UInt32, byteLength: UInt32) {
+            var data: UnsafeMutablePointer<UInt8>?
+            var format = kSound16bitMono
+            var sampleRate: UInt32 = 0, byteLength: UInt32 = 0
+            AudioSample.api.pointee.getData.unsafelyUnwrapped(pointer, &data, &format, &sampleRate, &byteLength)
+            return (data, Format(format), sampleRate, byteLength)
+        }
+
+        /// The sample's length in seconds.
+        public var length: Float {
+            AudioSample.api.pointee.getLength.unsafelyUnwrapped(pointer)
+        }
+
+        /// Decompresses an ADPCM sample to 16-bit PCM so it can be used in a
+        /// synth. Returns `false` if there is not enough memory.
+        @discardableResult
+        public func decompress() -> Bool {
+            AudioSample.api.pointee.decompress.unsafelyUnwrapped(pointer) != 0
+        }
+    }
+
+    // MARK: - SamplePlayer
+
+    /// Plays an `AudioSample` from memory. Wraps `SamplePlayer`.
+    public final class SamplePlayer: Source {
+        private static var api: UnsafePointer<playdate_sound_sampleplayer> { Playdate.samplePlayerAPI.unsafelyUnwrapped }
+
+        var loopCallback: ((SamplePlayer) -> Void)?
+        private var retainedSample: AudioSample?
+        private var retainedRateModulator: SignalValue?
+
+        override init(pointer: OpaquePointer?, isOwned: Bool) {
+            super.init(pointer: pointer, isOwned: isOwned)
+        }
+
+        public convenience init() {
+            self.init(pointer: SamplePlayer.api.pointee.newPlayer.unsafelyUnwrapped().unsafelyUnwrapped,
+                      isOwned: true)
+        }
+
+        /// Creates a player for the sample at `path`.
+        public convenience init(path: String) throws(PlaydateError) {
+            self.init()
+            sample = try AudioSample(path: path)
+        }
+
+        deinit {
+            if isOwned {
+                SamplePlayer.api.pointee.freePlayer.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// The sample to play.
+        public var sample: AudioSample? {
+            get { retainedSample }
+            set {
+                retainedSample = newValue
+                SamplePlayer.api.pointee.setSample.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+
+        /// Starts playback at `rate`, looping `repeat` times; 0 loops
+        /// endlessly, -1 loops ping-pong.
+        @discardableResult
+        public func play(repeat repeatCount: Int = 1, rate: Float = 1) -> Bool {
+            SamplePlayer.api.pointee.play.unsafelyUnwrapped(pointer, Int32(repeatCount), rate) != 0
+        }
+
+        public func stop() {
+            SamplePlayer.api.pointee.stop.unsafelyUnwrapped(pointer)
+        }
+
+        public func setPaused(_ paused: Bool) {
+            SamplePlayer.api.pointee.setPaused.unsafelyUnwrapped(pointer, paused ? 1 : 0)
+        }
+
+        /// The sample's length in seconds.
+        public var length: Float {
+            SamplePlayer.api.pointee.getLength.unsafelyUnwrapped(pointer)
+        }
+
+        /// The playback position in seconds.
+        public var offset: Float {
+            get { SamplePlayer.api.pointee.getOffset.unsafelyUnwrapped(pointer) }
+            set { SamplePlayer.api.pointee.setOffset.unsafelyUnwrapped(pointer, newValue) }
+        }
+
+        /// The playback rate; 1 is normal speed, negative plays backward.
+        public var rate: Float {
+            get { SamplePlayer.api.pointee.getRate.unsafelyUnwrapped(pointer) }
+            set { SamplePlayer.api.pointee.setRate.unsafelyUnwrapped(pointer, newValue) }
+        }
+
+        /// Restricts playback to the given range of sample frames.
+        public func setPlayRange(start: Int, end: Int) {
+            SamplePlayer.api.pointee.setPlayRange.unsafelyUnwrapped(pointer, Int32(start), Int32(end))
+        }
+
+        /// Sets a function called every time playback loops.
+        public func setLoopCallback(_ callback: ((SamplePlayer) -> Void)?) {
+            loopCallback = callback
+            if callback != nil {
+                SamplePlayer.api.pointee.setLoopCallback.unsafelyUnwrapped(pointer, { _, userdata in
+                    guard let userdata else { return }
+                    let player = Unmanaged<SamplePlayer>.fromOpaque(userdata).takeUnretainedValue()
+                    player.loopCallback?(player)
+                }, Unmanaged.passUnretained(self).toOpaque())
+            } else {
+                SamplePlayer.api.pointee.setLoopCallback.unsafelyUnwrapped(pointer, nil, nil)
+            }
+        }
+
+        /// Modulates the playback rate.
+        public var rateModulator: SignalValue? {
+            get { SignalValue.wrap(SamplePlayer.api.pointee.getRateModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retainedRateModulator = newValue
+                SamplePlayer.api.pointee.setRateModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+    }
+}

Sources/PlaydateKit/SoundSynth.swift

@@ -0,0 +1,614 @@
+//
+//  SoundSynth.swift
+//  Synth, Instrument, SequenceTrack, and Sequence wrappers.
+//
+
+internal import CPlaydate
+
+extension Sound {
+    /// A synthesizer voice. Wraps `PDSynth`.
+    public final class Synth: Source {
+        private static var api: UnsafePointer<playdate_sound_synth> { Playdate.synthAPI.unsafelyUnwrapped }
+
+        /// The synth's waveform.
+        public enum Waveform: UInt32, Sendable {
+            case square = 0
+            case triangle = 1
+            case sine = 2
+            case noise = 3
+            case sawtooth = 4
+            case poPhase = 5
+            case poDigital = 6
+            case poVosim = 7
+
+            var cValue: SoundWaveform { SoundWaveform(SoundWaveform.RawValue(rawValue)) }
+        }
+
+        /// Custom generator callbacks. Samples are in signed Q8.24 format.
+        public struct Generator {
+            /// Renders up to 256 sample frames into `left` (and `right` for
+            /// stereo generators). `rate` is the per-frame phase step in
+            /// Q0.32 format and `drate` its per-frame change. Returns the
+            /// number of frames rendered.
+            public var render: (_ left: UnsafeMutableBufferPointer<Int32>,
+                                _ right: UnsafeMutableBufferPointer<Int32>?,
+                                _ rate: UInt32, _ drate: Int32) -> Int
+            /// Called when a note starts. `length` is -1 for indefinite notes.
+            public var noteOn: ((_ note: MIDINote, _ velocity: Float, _ length: Float) -> Void)?
+            /// Called when a note is released (`stop == false`) or stopped
+            /// (`stop == true`).
+            public var release: ((_ stop: Bool) -> Void)?
+            /// Sets a generator parameter. Returns `true` if the parameter is
+            /// valid.
+            public var setParameter: ((_ parameter: Int, _ value: Float) -> Bool)?
+
+            public init(render: @escaping (_ left: UnsafeMutableBufferPointer<Int32>,
+                                           _ right: UnsafeMutableBufferPointer<Int32>?,
+                                           _ rate: UInt32, _ drate: Int32) -> Int,
+                        noteOn: ((_ note: MIDINote, _ velocity: Float, _ length: Float) -> Void)? = nil,
+                        release: ((_ stop: Bool) -> Void)? = nil,
+                        setParameter: ((_ parameter: Int, _ value: Float) -> Bool)? = nil) {
+                self.render = render
+                self.noteOn = noteOn
+                self.release = release
+                self.setParameter = setParameter
+            }
+        }
+
+        private final class GeneratorBox {
+            let generator: Generator
+            let stereo: Bool
+            init(_ generator: Generator, stereo: Bool) {
+                self.generator = generator
+                self.stereo = stereo
+            }
+        }
+
+        private var retainedSample: AudioSample?
+        private var retainedModulators: [SignalValue] = []
+
+        override init(pointer: OpaquePointer?, isOwned: Bool) {
+            super.init(pointer: pointer, isOwned: isOwned)
+        }
+
+        public convenience init() {
+            self.init(pointer: Synth.api.pointee.newSynth.unsafelyUnwrapped().unsafelyUnwrapped,
+                      isOwned: true)
+        }
+
+        public convenience init(waveform: Waveform) {
+            self.init()
+            setWaveform(waveform)
+        }
+
+        deinit {
+            if isOwned {
+                Synth.api.pointee.freeSynth.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// Copies the synth (and its generator, if any).
+        public func copy() -> Synth {
+            Synth(pointer: Synth.api.pointee.copy.unsafelyUnwrapped(pointer).unsafelyUnwrapped,
+                  isOwned: true)
+        }
+
+        // MARK: Sound generation
+
+        public func setWaveform(_ waveform: Waveform) {
+            Synth.api.pointee.setWaveform.unsafelyUnwrapped(pointer, waveform.cValue)
+        }
+
+        /// Plays a sample instead of a waveform. A nonzero sustain range
+        /// loops that part of the sample while the note is held.
+        public func setSample(_ sample: AudioSample, sustainStart: UInt32 = 0, sustainEnd: UInt32 = 0) {
+            retainedSample = sample
+            Synth.api.pointee.setSample.unsafelyUnwrapped(pointer, sample.pointer, sustainStart, sustainEnd)
+        }
+
+        /// Uses a wavetable for the synth. `log2size` is the base-2 log of
+        /// each waveform's size (e.g. 8 for 256 samples).
+        public func setWavetable(_ sample: AudioSample, log2size: Int,
+                                 columns: Int, rows: Int) throws(PlaydateError) {
+            retainedSample = sample
+            guard Synth.api.pointee.setWavetable.unsafelyUnwrapped(
+                pointer, sample.pointer, Int32(log2size), Int32(columns), Int32(rows)) != 0 else {
+                throw PlaydateError(message: "invalid wavetable dimensions")
+            }
+        }
+
+        /// Provides audio via custom Swift callbacks.
+        public func setGenerator(stereo: Bool, _ generator: Generator) {
+            let box = Unmanaged.passRetained(GeneratorBox(generator, stereo: stereo))
+            Synth.api.pointee.setGenerator.unsafelyUnwrapped(
+                pointer, stereo ? 1 : 0,
+                { userdata, left, right, nsamples, rate, drate in
+                    guard let userdata, let left else { return 0 }
+                    let box = Unmanaged<GeneratorBox>.fromOpaque(userdata).takeUnretainedValue()
+                    let leftBuffer = UnsafeMutableBufferPointer(start: left, count: Int(nsamples))
+                    let rightBuffer = right.map { UnsafeMutableBufferPointer(start: $0, count: Int(nsamples)) }
+                    return Int32(box.generator.render(leftBuffer, rightBuffer, rate, drate))
+                },
+                { userdata, note, velocity, length in
+                    guard let userdata else { return }
+                    let box = Unmanaged<GeneratorBox>.fromOpaque(userdata).takeUnretainedValue()
+                    box.generator.noteOn?(note, velocity, length)
+                },
+                { userdata, stop in
+                    guard let userdata else { return }
+                    let box = Unmanaged<GeneratorBox>.fromOpaque(userdata).takeUnretainedValue()
+                    box.generator.release?(stop != 0)
+                },
+                { userdata, parameter, value in
+                    guard let userdata else { return 0 }
+                    let box = Unmanaged<GeneratorBox>.fromOpaque(userdata).takeUnretainedValue()
+                    return box.generator.setParameter?(Int(parameter), value) == true ? 1 : 0
+                },
+                { userdata in
+                    guard let userdata else { return }
+                    Unmanaged<GeneratorBox>.fromOpaque(userdata).release()
+                },
+                { userdata in
+                    guard let userdata else { return nil }
+                    let box = Unmanaged<GeneratorBox>.fromOpaque(userdata).takeUnretainedValue()
+                    return Unmanaged.passRetained(GeneratorBox(box.generator, stereo: box.stereo)).toOpaque()
+                },
+                box.toOpaque())
+        }
+
+        // MARK: Envelope
+
+        public func setAttackTime(_ attack: Float) {
+            Synth.api.pointee.setAttackTime.unsafelyUnwrapped(pointer, attack)
+        }
+
+        public func setDecayTime(_ decay: Float) {
+            Synth.api.pointee.setDecayTime.unsafelyUnwrapped(pointer, decay)
+        }
+
+        public func setSustainLevel(_ sustain: Float) {
+            Synth.api.pointee.setSustainLevel.unsafelyUnwrapped(pointer, sustain)
+        }
+
+        public func setReleaseTime(_ release: Float) {
+            Synth.api.pointee.setReleaseTime.unsafelyUnwrapped(pointer, release)
+        }
+
+        /// The synth's amplitude envelope. Owned by the synth.
+        public var envelope: Envelope? {
+            guard let envelope = Synth.api.pointee.getEnvelope.unsafelyUnwrapped(pointer) else { return nil }
+            return Envelope(pointer: envelope, isOwned: false)
+        }
+
+        /// Clears the synth's envelope so it plays at constant volume.
+        public func clearEnvelope() {
+            Synth.api.pointee.clearEnvelope.unsafelyUnwrapped(pointer)
+        }
+
+        // MARK: Modulation
+
+        /// Transposes played notes by `halfSteps` (fractional values allowed).
+        public func setTranspose(_ halfSteps: Float) {
+            Synth.api.pointee.setTranspose.unsafelyUnwrapped(pointer, halfSteps)
+        }
+
+        public var frequencyModulator: SignalValue? {
+            get { SignalValue.wrap(Synth.api.pointee.getFrequencyModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retain(newValue)
+                Synth.api.pointee.setFrequencyModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+
+        public var amplitudeModulator: SignalValue? {
+            get { SignalValue.wrap(Synth.api.pointee.getAmplitudeModulator.unsafelyUnwrapped(pointer)) }
+            set {
+                retain(newValue)
+                Synth.api.pointee.setAmplitudeModulator.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+
+        /// The number of parameters the synth's generator supports.
+        public var parameterCount: Int {
+            Int(Synth.api.pointee.getParameterCount.unsafelyUnwrapped(pointer))
+        }
+
+        /// Sets a generator parameter. Returns `false` if the parameter is
+        /// invalid.
+        @discardableResult
+        public func setParameter(_ parameter: Int, value: Float) -> Bool {
+            Synth.api.pointee.setParameter.unsafelyUnwrapped(pointer, Int32(parameter), value) != 0
+        }
+
+        public func setParameterModulator(_ parameter: Int, _ modulator: SignalValue?) {
+            retain(modulator)
+            Synth.api.pointee.setParameterModulator.unsafelyUnwrapped(pointer, Int32(parameter),
+                                                              modulator?.pointer)
+        }
+
+        public func parameterModulator(_ parameter: Int) -> SignalValue? {
+            SignalValue.wrap(Synth.api.pointee.getParameterModulator.unsafelyUnwrapped(pointer, Int32(parameter)))
+        }
+
+        private func retain(_ modulator: SignalValue?) {
+            if let modulator, !retainedModulators.contains(where: { $0 === modulator }) {
+                retainedModulators.append(modulator)
+            }
+        }
+
+        // MARK: Playing
+
+        /// Plays a note at `frequency` Hz. `length` is in seconds; `nil`
+        /// plays until `noteOff()`. `when` is the audio-clock time to start,
+        /// or 0 for immediately.
+        public func playNote(frequency: Float, velocity: Float = 1,
+                             length: Float? = nil, when: UInt32 = 0) {
+            Synth.api.pointee.playNote.unsafelyUnwrapped(pointer, frequency, velocity, length ?? -1, when)
+        }
+
+        /// Plays a MIDI note, where 60 is middle C.
+        public func playMIDINote(_ note: MIDINote, velocity: Float = 1,
+                                 length: Float? = nil, when: UInt32 = 0) {
+            Synth.api.pointee.playMIDINote.unsafelyUnwrapped(pointer, note, velocity, length ?? -1, when)
+        }
+
+        /// Releases the playing note at time `when`, or immediately if 0.
+        public func noteOff(when: UInt32 = 0) {
+            Synth.api.pointee.noteOff.unsafelyUnwrapped(pointer, when)
+        }
+
+        /// Stops the synth immediately, without playing the release phase.
+        public func stop() {
+            Synth.api.pointee.stop.unsafelyUnwrapped(pointer)
+        }
+    }
+
+    // MARK: - Instrument
+
+    /// A bank of synth voices for playing a sequence track. Wraps
+    /// `PDSynthInstrument`.
+    public final class Instrument {
+        private static var api: UnsafePointer<playdate_sound_instrument> { Playdate.instrumentAPI.unsafelyUnwrapped }
+
+        let pointer: OpaquePointer
+        let isOwned: Bool
+        private var retainedVoices: [Synth] = []
+
+        init(pointer: OpaquePointer, isOwned: Bool) {
+            self.pointer = pointer
+            self.isOwned = isOwned
+        }
+
+        public convenience init() {
+            self.init(pointer: Instrument.api.pointee.newInstrument.unsafelyUnwrapped().unsafelyUnwrapped,
+                      isOwned: true)
+        }
+
+        deinit {
+            if isOwned {
+                Instrument.api.pointee.freeInstrument.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// Adds a voice to the instrument, handling notes in
+        /// `rangeStart...rangeEnd` (0...127 handles all notes), transposed by
+        /// `transpose` half-steps.
+        @discardableResult
+        public func addVoice(_ synth: Synth, rangeStart: MIDINote = 0, rangeEnd: MIDINote = 127,
+                             transpose: Float = 0) -> Bool {
+            let added = Instrument.api.pointee.addVoice.unsafelyUnwrapped(
+                pointer, synth.pointer, rangeStart, rangeEnd, transpose) != 0
+            if added, !retainedVoices.contains(where: { $0 === synth }) {
+                retainedVoices.append(synth)
+            }
+            return added
+        }
+
+        /// Plays a note at `frequency` Hz on an available voice. Returns the
+        /// synth used, if any.
+        @discardableResult
+        public func playNote(frequency: Float, velocity: Float = 1,
+                             length: Float? = nil, when: UInt32 = 0) -> Synth? {
+            let synth = Instrument.api.pointee.playNote.unsafelyUnwrapped(
+                pointer, frequency, velocity, length ?? -1, when)
+            return voice(for: synth)
+        }
+
+        /// Plays a MIDI note on an available voice. Returns the synth used.
+        @discardableResult
+        public func playMIDINote(_ note: MIDINote, velocity: Float = 1,
+                                 length: Float? = nil, when: UInt32 = 0) -> Synth? {
+            let synth = Instrument.api.pointee.playMIDINote.unsafelyUnwrapped(
+                pointer, note, velocity, length ?? -1, when)
+            return voice(for: synth)
+        }
+
+        private func voice(for pointer: OpaquePointer?) -> Synth? {
+            guard let pointer else { return nil }
+            if let voice = retainedVoices.first(where: { $0.pointer == pointer }) {
+                return voice
+            }
+            return Synth(pointer: pointer, isOwned: false)
+        }
+
+        /// Bends played notes by `bend` × the pitch bend range.
+        public func setPitchBend(_ bend: Float) {
+            Instrument.api.pointee.setPitchBend.unsafelyUnwrapped(pointer, bend)
+        }
+
+        public func setPitchBendRange(halfSteps: Float) {
+            Instrument.api.pointee.setPitchBendRange.unsafelyUnwrapped(pointer, halfSteps)
+        }
+
+        public func setTranspose(halfSteps: Float) {
+            Instrument.api.pointee.setTranspose.unsafelyUnwrapped(pointer, halfSteps)
+        }
+
+        /// Releases the voice playing `note` at time `when` (0 = now).
+        public func noteOff(_ note: MIDINote, when: UInt32 = 0) {
+            Instrument.api.pointee.noteOff.unsafelyUnwrapped(pointer, note, when)
+        }
+
+        public func allNotesOff(when: UInt32 = 0) {
+            Instrument.api.pointee.allNotesOff.unsafelyUnwrapped(pointer, when)
+        }
+
+        public func setVolume(left: Float, right: Float) {
+            Instrument.api.pointee.setVolume.unsafelyUnwrapped(pointer, left, right)
+        }
+
+        public var volume: (left: Float, right: Float) {
+            var left: Float = 0, right: Float = 0
+            Instrument.api.pointee.getVolume.unsafelyUnwrapped(pointer, &left, &right)
+            return (left, right)
+        }
+
+        public var activeVoiceCount: Int {
+            Int(Instrument.api.pointee.activeVoiceCount.unsafelyUnwrapped(pointer))
+        }
+    }
+
+    // MARK: - SequenceTrack
+
+    /// A track of notes played by an instrument. Wraps `SequenceTrack`.
+    public final class SequenceTrack {
+        private static var api: UnsafePointer<playdate_sound_track> { Playdate.trackAPI.unsafelyUnwrapped }
+
+        let pointer: OpaquePointer
+        let isOwned: Bool
+        private var retainedInstrument: Instrument?
+
+        init(pointer: OpaquePointer, isOwned: Bool) {
+            self.pointer = pointer
+            self.isOwned = isOwned
+        }
+
+        public convenience init() {
+            self.init(pointer: SequenceTrack.api.pointee.newTrack.unsafelyUnwrapped().unsafelyUnwrapped,
+                      isOwned: true)
+        }
+
+        deinit {
+            if isOwned {
+                SequenceTrack.api.pointee.freeTrack.unsafelyUnwrapped(pointer)
+            }
+        }
+
+        /// The instrument that plays this track's notes.
+        public var instrument: Instrument? {
+            get {
+                if let retainedInstrument { return retainedInstrument }
+                guard let instrument = SequenceTrack.api.pointee.getInstrument.unsafelyUnwrapped(pointer) else {
+                    return nil
+                }
+                return Instrument(pointer: instrument, isOwned: false)
+            }
+            set {
+                retainedInstrument = newValue
+                SequenceTrack.api.pointee.setInstrument.unsafelyUnwrapped(pointer, newValue?.pointer)
+            }
+        }
+
+        /// Adds a note starting at `step`, lasting `length` steps.
+        public func addNote(step: UInt32, length: UInt32, note: MIDINote, velocity: Float = 1) {
+            SequenceTrack.api.pointee.addNoteEvent.unsafelyUnwrapped(pointer, step, length, note, velocity)
+        }
+
+        public func removeNote(step: UInt32, note: MIDINote) {
+            SequenceTrack.api.pointee.removeNoteEvent.unsafelyUnwrapped(pointer, step, note)
+        }
+
+        public func clearNotes() {
+            SequenceTrack.api.pointee.clearNotes.unsafelyUnwrapped(pointer)
+        }
+
+        /// The track's length in steps, including the tail of the last note.
+        public var length: UInt32 {
+            SequenceTrack.api.pointee.getLength.unsafelyUnwrapped(pointer)
+        }
+
+        /// The index of the first note at or after `step`.
+        public func indexForStep(_ step: UInt32) -> Int {
+            Int(SequenceTrack.api.pointee.getIndexForStep.unsafelyUnwrapped(pointer, step))
+        }
+
+        /// The note at `index`, or `nil` if the index is out of range.
+        public func note(at index: Int) -> (step: UInt32, length: UInt32,
+                                            note: MIDINote, velocity: Float)? {
+            var step: UInt32 = 0, length: UInt32 = 0
+            var note: MIDINote = 0
+            var velocity: Float = 0
+            guard SequenceTrack.api.pointee.getNoteAtIndex.unsafelyUnwrapped(
+                pointer, Int32(index), &step, &length, &note, &velocity) != 0 else { return nil }
+            return (step, length, note, velocity)
+        }
+
+        /// The number of control signals on the track.
+        public var controlSignalCount: Int {
+            Int(SequenceTrack.api.pointee.getControlSignalCount.unsafelyUnwrapped(pointer))
+        }
+
+        /// The control signal at `index`. Owned by the track.
+        public func controlSignal(at index: Int) -> ControlSignal? {
+            guard let signal = SequenceTrack.api.pointee.getControlSignal.unsafelyUnwrapped(
+                pointer, Int32(index)) else { return nil }
+            return ControlSignal(pointer: signal, isOwned: false)
+        }
+
+        /// The control signal for MIDI controller `controller`, optionally
+        /// creating it. Owned by the track.
+        public func signalForController(_ controller: Int, create: Bool = false) -> ControlSignal? {
+            guard let signal = SequenceTrack.api.pointee.getSignalForController.unsafelyUnwrapped(
+                pointer, Int32(controller), create ? 1 : 0) else { return nil }
+            return ControlSignal(pointer: signal, isOwned: false)
+        }
+
+        public func clearControlEvents() {
+            SequenceTrack.api.pointee.clearControlEvents.unsafelyUnwrapped(pointer)
+        }
+
+        /// The maximum number of simultaneous notes in the track.
+        public var polyphony: Int {
+            Int(SequenceTrack.api.pointee.getPolyphony.unsafelyUnwrapped(pointer))
+        }
+
+        public var activeVoiceCount: Int {
+            Int(SequenceTrack.api.pointee.activeVoiceCount.unsafelyUnwrapped(pointer))
+        }
+
+        public func setMuted(_ muted: Bool) {
+            SequenceTrack.api.pointee.setMuted.unsafelyUnwrapped(pointer, muted ? 1 : 0)
+        }
+    }
+
+    // MARK: - Sequence
+
+    /// A collection of tracks with tempo and loop control, playable from a
+    /// MIDI file. Wraps `SoundSequence`.
+    public final class Sequence {
+        private static var api: UnsafePointer<playdate_sound_sequence> { Playdate.sequenceAPI.unsafelyUnwrapped }
+
+        let pointer: OpaquePointer
+        private var retainedTracks: [SequenceTrack] = []
+        var finishCallback: ((Sequence) -> Void)?
+
+        public init() {
+            pointer = Sequence.api.pointee.newSequence.unsafelyUnwrapped().unsafelyUnwrapped
+        }
+
+        /// Creates a sequence and loads the MIDI file at `path`.
+        public convenience init(midiFilePath: String) throws(PlaydateError) {
+            self.init()
+            try loadMIDIFile(path: midiFilePath)
+        }
+
+        deinit {
+            Sequence.api.pointee.freeSequence.unsafelyUnwrapped(pointer)
+        }
+
+        public func loadMIDIFile(path: String) throws(PlaydateError) {
+            let loaded = path.withPlaydateCString {
+                Sequence.api.pointee.loadMIDIFile.unsafelyUnwrapped(pointer, $0) != 0
+            }
+            if !loaded {
+                throw PlaydateError(message: "unable to load MIDI file: \(path)")
+            }
+        }
+
+        /// Starts playback. `completion` is called when the sequence finishes.
+        public func play(completion: ((Sequence) -> Void)? = nil) {
+            finishCallback = completion
+            if completion != nil {
+                Sequence.api.pointee.play.unsafelyUnwrapped(pointer, { _, userdata in
+                    guard let userdata else { return }
+                    let sequence = Unmanaged<Sequence>.fromOpaque(userdata).takeUnretainedValue()
+                    sequence.finishCallback?(sequence)
+                }, Unmanaged.passUnretained(self).toOpaque())
+            } else {
+                Sequence.api.pointee.play.unsafelyUnwrapped(pointer, nil, nil)
+            }
+        }
+
+        public func stop() {
+            Sequence.api.pointee.stop.unsafelyUnwrapped(pointer)
+        }
+
+        public var isPlaying: Bool {
+            Sequence.api.pointee.isPlaying.unsafelyUnwrapped(pointer) != 0
+        }
+
+        /// The playback position, in samples.
+        public var time: UInt32 {
+            get { Sequence.api.pointee.getTime.unsafelyUnwrapped(pointer) }
+            set { Sequence.api.pointee.setTime.unsafelyUnwrapped(pointer, newValue) }
+        }
+
+        /// The tempo, in steps per second.
+        public var tempo: Float {
+            get { Sequence.api.pointee.getTempo.unsafelyUnwrapped(pointer) }
+            set { Sequence.api.pointee.setTempo.unsafelyUnwrapped(pointer, newValue) }
+        }
+
+        /// The sequence's length in steps, including the tail of the last note.
+        public var length: UInt32 {
+            Sequence.api.pointee.getLength.unsafelyUnwrapped(pointer)
+        }
+
+        /// Loops the range `loopStart..<loopEnd` (steps) `loops` times while
+        /// playing; 0 loops endlessly.
+        public func setLoops(start: Int, end: Int, count: Int = 0) {
+            Sequence.api.pointee.setLoops.unsafelyUnwrapped(pointer, Int32(start), Int32(end), Int32(count))
+        }
+
+        /// The current step, and the time offset (in samples) into that step.
+        public var currentStep: (step: Int, timeOffset: Int) {
+            var timeOffset: Int32 = 0
+            let step = Sequence.api.pointee.getCurrentStep.unsafelyUnwrapped(pointer, &timeOffset)
+            return (Int(step), Int(timeOffset))
+        }
+
+        /// Moves playback to the given step. If `playNotes` is `true`, notes
+        /// at the position (that started before it) are played.
+        public func setCurrentStep(_ step: Int, timeOffset: Int = 0, playNotes: Bool = false) {
+            Sequence.api.pointee.setCurrentStep.unsafelyUnwrapped(pointer, Int32(step),
+                                                          Int32(timeOffset), playNotes ? 1 : 0)
+        }
+
+        // MARK: Tracks
+
+        public var trackCount: Int {
+            Int(Sequence.api.pointee.getTrackCount.unsafelyUnwrapped(pointer))
+        }
+
+        /// Adds a new track to the sequence. The track is owned by the
+        /// sequence.
+        @discardableResult
+        public func addTrack() -> SequenceTrack {
+            let track = SequenceTrack(
+                pointer: Sequence.api.pointee.addTrack.unsafelyUnwrapped(pointer).unsafelyUnwrapped,
+                isOwned: false)
+            retainedTracks.append(track)
+            return track
+        }
+
+        /// The track at `index`. Owned by the sequence.
+        public func track(at index: Int) -> SequenceTrack? {
+            guard let track = Sequence.api.pointee.getTrackAtIndex.unsafelyUnwrapped(
+                pointer, UInt32(index)) else { return nil }
+            return SequenceTrack(pointer: track, isOwned: false)
+        }
+
+        /// Installs `track` at `index`.
+        public func setTrack(_ track: SequenceTrack, at index: Int) {
+            if !retainedTracks.contains(where: { $0 === track }) {
+                retainedTracks.append(track)
+            }
+            Sequence.api.pointee.setTrackAtIndex.unsafelyUnwrapped(pointer, track.pointer, UInt32(index))
+        }
+
+        /// Releases every playing note in the sequence.
+        public func allNotesOff() {
+            Sequence.api.pointee.allNotesOff.unsafelyUnwrapped(pointer)
+        }
+    }
+}

Sources/PlaydateKit/Sprite.swift

@@ -0,0 +1,655 @@
+//
+//  Sprite.swift
+//  Wraps `playdate->sprite` (pd_api_sprite.h).
+//
+//  The binding stores a back-reference to each `Sprite` wrapper in the
+//  underlying `LCDSprite`'s userdata slot, so callbacks and queries can
+//  recover the wrapper. Do not mix these wrappers with C code that sets its
+//  own sprite userdata; use `Sprite.userdata` for per-sprite storage instead.
+//
+
+internal import CPlaydate
+
+private var spriteAPI: UnsafePointer<playdate_sprite> { Playdate.spriteAPI.unsafelyUnwrapped }
+
+/// A floating-point rectangle mirroring `PDRect`.
+public struct Rect: Sendable {
+    public var x: Float
+    public var y: Float
+    public var width: Float
+    public var height: Float
+
+    public init(x: Float, y: Float, width: Float, height: Float) {
+        self.x = x
+        self.y = y
+        self.width = width
+        self.height = height
+    }
+
+    init(_ rect: PDRect) {
+        self.init(x: rect.x, y: rect.y, width: rect.width, height: rect.height)
+    }
+
+    var cValue: PDRect { PDRect(x: x, y: y, width: width, height: height) }
+}
+
+/// A sprite: a drawable object with position, z-order, and collision
+/// support. Wraps `LCDSprite`. Static members wrap the global sprite
+/// system functions.
+public final class Sprite {
+    let pointer: OpaquePointer
+    let isOwned: Bool
+
+    /// Position in the static `displayList`, or -1 when not in it; makes
+    /// `add()`/`remove()` O(1) instead of scanning the list.
+    private var displayListIndex = -1
+
+    /// Per-sprite callbacks and retained resources.
+    var updateFunction: ((Sprite) -> Void)?
+    var drawFunction: ((Sprite, _ bounds: Rect, _ drawRect: Rect) -> Void)?
+    var collisionResponseFunction: ((Sprite, _ other: Sprite) -> CollisionResponse)?
+    private var retainedImage: Graphics.Bitmap?
+    private var retainedStencil: Graphics.Bitmap?
+    private var retainedTilemap: Graphics.TileMap?
+
+    /// Free-form storage for game use (the C userdata slot is reserved
+    /// by the binding).
+    public var userdata: AnyObject?
+
+    init(pointer: OpaquePointer, isOwned: Bool) {
+        self.pointer = pointer
+        self.isOwned = isOwned
+        // Transient wrappers for sprites created outside the binding must not
+        // store a back-reference: it would dangle once the wrapper is
+        // deallocated, and only owned wrappers clear it in `deinit`.
+        if isOwned {
+            spriteAPI.pointee.setUserdata.unsafelyUnwrapped(pointer, Unmanaged.passUnretained(self).toOpaque())
+        }
+    }
+
+    /// Allocates a new sprite.
+    public convenience init() {
+        self.init(pointer: spriteAPI.pointee.newSprite.unsafelyUnwrapped().unsafelyUnwrapped, isOwned: true)
+    }
+
+    deinit {
+        if isOwned {
+            spriteAPI.pointee.setUserdata.unsafelyUnwrapped(pointer, nil)
+            spriteAPI.pointee.freeSprite.unsafelyUnwrapped(pointer)
+        }
+    }
+
+    /// Returns the Swift wrapper stored in the sprite's userdata, or a
+    /// transient unowned wrapper for sprites created outside the binding.
+    static func wrapper(for pointer: OpaquePointer) -> Sprite {
+        if let userdata = spriteAPI.pointee.getUserdata.unsafelyUnwrapped(pointer) {
+            return Unmanaged<Sprite>.fromOpaque(userdata).takeUnretainedValue()
+        }
+        return Sprite(pointer: pointer, isOwned: false)
+    }
+
+    /// Copies the sprite. Callbacks and retained resources are carried
+    /// over to the copy.
+    public func copy() -> Sprite {
+        let copy = Sprite(pointer: spriteAPI.pointee.copy.unsafelyUnwrapped(pointer).unsafelyUnwrapped,
+                          isOwned: true)
+        copy.updateFunction = updateFunction
+        copy.drawFunction = drawFunction
+        copy.collisionResponseFunction = collisionResponseFunction
+        copy.retainedImage = retainedImage
+        copy.retainedStencil = retainedStencil
+        copy.retainedTilemap = retainedTilemap
+        return copy
+    }
+
+    // MARK: - Types
+
+    /// How a sprite reacts when a collision occurs.
+    public enum CollisionResponse: UInt32, Sendable {
+        case slide = 0
+        case freeze = 1
+        case overlap = 2
+        case bounce = 3
+
+        init(_ response: SpriteCollisionResponseType) {
+            self = CollisionResponse(rawValue: UInt32(response.rawValue)) ?? .freeze
+        }
+        var cValue: SpriteCollisionResponseType { SpriteCollisionResponseType(SpriteCollisionResponseType.RawValue(rawValue)) }
+    }
+
+    /// Information about a single collision, mirroring `SpriteCollisionInfo`.
+    public struct CollisionInfo {
+        /// The sprite being moved.
+        public let sprite: Sprite
+        /// The sprite it collided with.
+        public let other: Sprite
+        /// The collision response used.
+        public let response: CollisionResponse
+        /// `true` if the sprites were overlapping when the collision
+        /// started; `false` if the sprite tunneled through.
+        public let overlaps: Bool
+        /// How far along the movement (0...1) the collision occurred.
+        public let ti: Float
+        /// The difference between the requested and actual positions.
+        public let move: (x: Float, y: Float)
+        /// The collision normal (each component -1, 0, or 1).
+        public let normal: (x: Int, y: Int)
+        /// Where the sprite started touching `other`.
+        public let touch: (x: Float, y: Float)
+        /// The sprite's rect at the moment of the touch.
+        public let spriteRect: Rect
+        /// `other`'s rect at the moment of the touch.
+        public let otherRect: Rect
+
+        init(_ info: SpriteCollisionInfo) {
+            sprite = Sprite.wrapper(for: info.sprite)
+            other = Sprite.wrapper(for: info.other)
+            response = CollisionResponse(info.responseType)
+            overlaps = info.overlaps != 0
+            ti = info.ti
+            move = (info.move.x, info.move.y)
+            normal = (Int(info.normal.x), Int(info.normal.y))
+            touch = (info.touch.x, info.touch.y)
+            spriteRect = Rect(info.spriteRect)
+            otherRect = Rect(info.otherRect)
+        }
+    }
+
+    /// Information about a sprite intersected by a line segment,
+    /// mirroring `SpriteQueryInfo`.
+    public struct QueryInfo {
+        public let sprite: Sprite
+        /// How far along the segment (0...1) the segment enters the sprite.
+        public let ti1: Float
+        /// How far along the segment (0...1) the segment exits the sprite.
+        public let ti2: Float
+        public let entryPoint: (x: Float, y: Float)
+        public let exitPoint: (x: Float, y: Float)
+
+        init(_ info: SpriteQueryInfo) {
+            sprite = Sprite.wrapper(for: info.sprite)
+            ti1 = info.ti1
+            ti2 = info.ti2
+            entryPoint = (info.entryPoint.x, info.entryPoint.y)
+            exitPoint = (info.exitPoint.x, info.exitPoint.y)
+        }
+    }
+
+    // MARK: - Display list
+
+    /// Sprites currently added to the display list, kept alive here.
+    nonisolated(unsafe) private static var displayList: [Sprite] = []
+
+    /// When `true`, all sprites redraw every frame instead of only when
+    /// marked dirty.
+    public static func setAlwaysRedraw(_ flag: Bool) {
+        spriteAPI.pointee.setAlwaysRedraw.unsafelyUnwrapped(flag ? 1 : 0)
+    }
+
+    /// Marks the given screen region as needing a redraw.
+    public static func addDirtyRect(_ rect: Graphics.Rect) {
+        spriteAPI.pointee.addDirtyRect.unsafelyUnwrapped(rect.cValue)
+    }
+
+    /// Draws every sprite in the display list.
+    public static func drawAll() {
+        spriteAPI.pointee.drawSprites.unsafelyUnwrapped()
+    }
+
+    /// Updates and then draws every sprite in the display list.
+    public static func updateAndDrawAll() {
+        spriteAPI.pointee.updateAndDrawSprites.unsafelyUnwrapped()
+    }
+
+    /// The number of sprites in the display list.
+    public static var count: Int {
+        Int(spriteAPI.pointee.getSpriteCount.unsafelyUnwrapped())
+    }
+
+    /// Adds the sprite to the display list.
+    public func add() {
+        spriteAPI.pointee.addSprite.unsafelyUnwrapped(pointer)
+        if displayListIndex < 0 {
+            displayListIndex = Sprite.displayList.count
+            Sprite.displayList.append(self)
+        }
+    }
+
+    /// Removes the sprite from the display list.
+    public func remove() {
+        spriteAPI.pointee.removeSprite.unsafelyUnwrapped(pointer)
+        guard displayListIndex >= 0 else { return }
+        // Swap-remove: the keep-alive list is unordered (the OS keeps the
+        // draw order), so the last sprite can take the vacated slot.
+        let index = displayListIndex
+        let last = Sprite.displayList.removeLast()
+        if last !== self {
+            Sprite.displayList[index] = last
+            last.displayListIndex = index
+        }
+        displayListIndex = -1
+    }
+
+    /// Removes the given sprites from the display list.
+    public static func remove(_ sprites: [Sprite]) {
+        for sprite in sprites { sprite.remove() }
+    }
+
+    /// Removes every sprite from the display list.
+    public static func removeAll() {
+        spriteAPI.pointee.removeAllSprites.unsafelyUnwrapped()
+        for sprite in displayList { sprite.displayListIndex = -1 }
+        displayList = []
+    }
+
+    // MARK: - Geometry
+
+    /// The sprite's bounds. Setting this positions and sizes the sprite.
+    public var bounds: Rect {
+        get { Rect(spriteAPI.pointee.getBounds.unsafelyUnwrapped(pointer)) }
+        set { spriteAPI.pointee.setBounds.unsafelyUnwrapped(pointer, newValue.cValue) }
+    }
+
+    /// Moves the sprite so its anchor point is at (x, y).
+    public func moveTo(x: Float, y: Float) {
+        spriteAPI.pointee.moveTo.unsafelyUnwrapped(pointer, x, y)
+    }
+
+    /// Moves the sprite by (dx, dy).
+    public func moveBy(dx: Float, dy: Float) {
+        spriteAPI.pointee.moveBy.unsafelyUnwrapped(pointer, dx, dy)
+    }
+
+    /// The sprite's anchor position.
+    public var position: (x: Float, y: Float) {
+        var x: Float = 0, y: Float = 0
+        spriteAPI.pointee.getPosition.unsafelyUnwrapped(pointer, &x, &y)
+        return (x, y)
+    }
+
+    /// Sets the sprite's size without changing its image.
+    public func setSize(width: Float, height: Float) {
+        spriteAPI.pointee.setSize.unsafelyUnwrapped(pointer, width, height)
+    }
+
+    /// The anchor point used for positioning, where (0, 0) is the top
+    /// left and (1, 1) the bottom right. Defaults to (0.5, 0.5).
+    public var center: (x: Float, y: Float) {
+        get {
+            var x: Float = 0, y: Float = 0
+            spriteAPI.pointee.getCenter.unsafelyUnwrapped(pointer, &x, &y)
+            return (x, y)
+        }
+        set { spriteAPI.pointee.setCenter.unsafelyUnwrapped(pointer, newValue.x, newValue.y) }
+    }
+
+    /// Draw order: higher values draw on top.
+    public var zIndex: Int16 {
+        get { spriteAPI.pointee.getZIndex.unsafelyUnwrapped(pointer) }
+        set { spriteAPI.pointee.setZIndex.unsafelyUnwrapped(pointer, newValue) }
+    }
+
+    // MARK: - Appearance
+
+    /// Sets the sprite's image, resizing its bounds to match.
+    public func setImage(_ image: Graphics.Bitmap?, flip: Graphics.BitmapFlip = .unflipped) {
+        retainedImage = image
+        spriteAPI.pointee.setImage.unsafelyUnwrapped(pointer, image?.pointer, flip.cValue)
+    }
+
+    /// The sprite's image.
+    public var image: Graphics.Bitmap? {
+        if let retainedImage { return retainedImage }
+        guard let image = spriteAPI.pointee.getImage.unsafelyUnwrapped(pointer) else { return nil }
+        return Graphics.Bitmap(pointer: image, isOwned: false)
+    }
+
+    /// Sets the sprite's tilemap, resizing its bounds to match.
+    public var tilemap: Graphics.TileMap? {
+        get { retainedTilemap }
+        set {
+            retainedTilemap = newValue
+            spriteAPI.pointee.setTilemap.unsafelyUnwrapped(pointer, newValue?.pointer)
+        }
+    }
+
+    /// The mode used to draw the sprite's image.
+    public func setDrawMode(_ mode: Graphics.DrawMode) {
+        spriteAPI.pointee.setDrawMode.unsafelyUnwrapped(pointer, mode.cValue)
+    }
+
+    /// How the sprite's image is mirrored when drawn.
+    public var imageFlip: Graphics.BitmapFlip {
+        get { Graphics.BitmapFlip(spriteAPI.pointee.getImageFlip.unsafelyUnwrapped(pointer)) }
+        set { spriteAPI.pointee.setImageFlip.unsafelyUnwrapped(pointer, newValue.cValue) }
+    }
+
+    /// Sets the stencil applied when drawing the sprite. If `tile` is
+    /// `true` the image width must be a multiple of 32.
+    public func setStencil(_ stencil: Graphics.Bitmap?, tile: Bool = false) {
+        retainedStencil = stencil
+        spriteAPI.pointee.setStencilImage.unsafelyUnwrapped(pointer, stencil?.pointer, tile ? 1 : 0)
+    }
+
+    /// Sets an 8×8 stencil pattern (8 rows of image data).
+    public func setStencilPattern(_ rows: (UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8, UInt8)) {
+        // The tuple is already 8 contiguous bytes; the C side copies the
+        // pattern, so passing the stack storage directly is safe.
+        withUnsafeBytes(of: rows) { buffer in
+            let pattern = UnsafeMutablePointer(
+                mutating: buffer.baseAddress.unsafelyUnwrapped.assumingMemoryBound(to: UInt8.self))
+            spriteAPI.pointee.setStencilPattern.unsafelyUnwrapped(pointer, pattern)
+        }
+    }
+
+    public func clearStencil() {
+        retainedStencil = nil
+        spriteAPI.pointee.clearStencil.unsafelyUnwrapped(pointer)
+    }
+
+    /// Clips the sprite's drawing to `rect` (screen coordinates).
+    public func setClipRect(_ rect: Graphics.Rect) {
+        spriteAPI.pointee.setClipRect.unsafelyUnwrapped(pointer, rect.cValue)
+    }
+
+    public func clearClipRect() {
+        spriteAPI.pointee.clearClipRect.unsafelyUnwrapped(pointer)
+    }
+
+    /// Clips all sprites with z-index in `startZ...endZ` to `rect`.
+    public static func setClipRectsInRange(_ rect: Graphics.Rect, startZ: Int, endZ: Int) {
+        spriteAPI.pointee.setClipRectsInRange.unsafelyUnwrapped(rect.cValue, Int32(startZ), Int32(endZ))
+    }
+
+    public static func clearClipRectsInRange(startZ: Int, endZ: Int) {
+        spriteAPI.pointee.clearClipRectsInRange.unsafelyUnwrapped(Int32(startZ), Int32(endZ))
+    }
+
+    // MARK: - Behavior flags
+
+    /// Whether the sprite's update function is called by `updateAndDrawAll()`.
+    public var updatesEnabled: Bool {
+        get { spriteAPI.pointee.updatesEnabled.unsafelyUnwrapped(pointer) != 0 }
+        set { spriteAPI.pointee.setUpdatesEnabled.unsafelyUnwrapped(pointer, newValue ? 1 : 0) }
+    }
+
+    public var collisionsEnabled: Bool {
+        get { spriteAPI.pointee.collisionsEnabled.unsafelyUnwrapped(pointer) != 0 }
+        set { spriteAPI.pointee.setCollisionsEnabled.unsafelyUnwrapped(pointer, newValue ? 1 : 0) }
+    }
+
+    public var isVisible: Bool {
+        get { spriteAPI.pointee.isVisible.unsafelyUnwrapped(pointer) != 0 }
+        set { spriteAPI.pointee.setVisible.unsafelyUnwrapped(pointer, newValue ? 1 : 0) }
+    }
+
+    /// Marking a sprite opaque tells the system it does not need to redraw
+    /// anything behind it.
+    public func setOpaque(_ flag: Bool) {
+        spriteAPI.pointee.setOpaque.unsafelyUnwrapped(pointer, flag ? 1 : 0)
+    }
+
+    /// Forces the sprite to redraw this frame.
+    public func markDirty() {
+        spriteAPI.pointee.markDirty.unsafelyUnwrapped(pointer)
+    }
+
+    /// Marks part of the sprite (in sprite-local coordinates) as needing
+    /// a redraw.
+    public func markDirty(rect: Rect) {
+        spriteAPI.pointee.markDirtyRect.unsafelyUnwrapped(pointer, rect.cValue)
+    }
+
+    /// An integer tag for identifying sprites (e.g. in collisions).
+    public var tag: UInt8 {
+        get { spriteAPI.pointee.getTag.unsafelyUnwrapped(pointer) }
+        set { spriteAPI.pointee.setTag.unsafelyUnwrapped(pointer, newValue) }
+    }
+
+    /// When `true`, the sprite draws in screen coordinates, ignoring the
+    /// global draw offset.
+    public func setIgnoresDrawOffset(_ flag: Bool) {
+        spriteAPI.pointee.setIgnoresDrawOffset.unsafelyUnwrapped(pointer, flag ? 1 : 0)
+    }
+
+    // MARK: - Callbacks
+
+    /// Sets the function called by `updateAndDrawAll()` for this sprite.
+    public func setUpdateFunction(_ update: ((Sprite) -> Void)?) {
+        updateFunction = update
+        if update != nil {
+            spriteAPI.pointee.setUpdateFunction.unsafelyUnwrapped(pointer, { spritePointer in
+                guard let spritePointer else { return }
+                let sprite = Sprite.wrapper(for: spritePointer)
+                sprite.updateFunction?(sprite)
+            })
+        } else {
+            spriteAPI.pointee.setUpdateFunction.unsafelyUnwrapped(pointer, nil)
+        }
+    }
+
+    /// Sets a custom draw function, called when the sprite needs to draw.
+    /// `bounds` is the sprite's bounds; `drawRect` is the region that
+    /// needs redrawing.
+    public func setDrawFunction(_ draw: ((Sprite, _ bounds: Rect, _ drawRect: Rect) -> Void)?) {
+        drawFunction = draw
+        if draw != nil {
+            spriteAPI.pointee.setDrawFunction.unsafelyUnwrapped(pointer, { spritePointer, bounds, drawRect in
+                guard let spritePointer else { return }
+                let sprite = Sprite.wrapper(for: spritePointer)
+                sprite.drawFunction?(sprite, Rect(bounds), Rect(drawRect))
+            })
+        } else {
+            spriteAPI.pointee.setDrawFunction.unsafelyUnwrapped(pointer, nil)
+        }
+    }
+
+    // MARK: - Collisions
+
+    /// Clears the collision world. Call when changing scenes.
+    public static func resetCollisionWorld() {
+        spriteAPI.pointee.resetCollisionWorld.unsafelyUnwrapped()
+    }
+
+    /// The rect (in sprite-local coordinates) used for collisions.
+    public var collideRect: Rect {
+        get { Rect(spriteAPI.pointee.getCollideRect.unsafelyUnwrapped(pointer)) }
+        set { spriteAPI.pointee.setCollideRect.unsafelyUnwrapped(pointer, newValue.cValue) }
+    }
+
+    public func clearCollideRect() {
+        spriteAPI.pointee.clearCollideRect.unsafelyUnwrapped(pointer)
+    }
+
+    /// Sets the function deciding how this sprite responds when it
+    /// collides with `other`.
+    public func setCollisionResponseFunction(_ filter: ((Sprite, _ other: Sprite) -> CollisionResponse)?) {
+        collisionResponseFunction = filter
+        if filter != nil {
+            spriteAPI.pointee.setCollisionResponseFunction.unsafelyUnwrapped(pointer, { spritePointer, otherPointer in
+                guard let spritePointer, let otherPointer else { return kCollisionTypeFreeze }
+                let sprite = Sprite.wrapper(for: spritePointer)
+                let other = Sprite.wrapper(for: otherPointer)
+                return sprite.collisionResponseFunction?(sprite, other).cValue ?? kCollisionTypeFreeze
+            })
+        } else {
+            spriteAPI.pointee.setCollisionResponseFunction.unsafelyUnwrapped(pointer, nil)
+        }
+    }
+
+    /// Visits and frees a C collision info array.
+    private static func visitCollisions(_ pointer: UnsafeMutablePointer<SpriteCollisionInfo>?,
+                                        count: Int32, _ visit: (CollisionInfo) -> Void) {
+        guard let pointer else { return }
+        for index in 0..<Int(count) {
+            visit(CollisionInfo(pointer[index]))
+        }
+        System.systemFree(pointer)
+    }
+
+    /// Converts and frees a C collision info array.
+    private static func collisionInfos(_ pointer: UnsafeMutablePointer<SpriteCollisionInfo>?,
+                                       count: Int32) -> [CollisionInfo] {
+        var infos = [CollisionInfo]()
+        infos.reserveCapacity(Int(count))
+        visitCollisions(pointer, count: count) { infos.append($0) }
+        return infos
+    }
+
+    /// Returns the collisions that would occur if the sprite moved toward
+    /// (goalX, goalY), without moving it.
+    public func checkCollisions(goalX: Float, goalY: Float)
+        -> (actual: (x: Float, y: Float), collisions: [CollisionInfo]) {
+        var actualX: Float = 0, actualY: Float = 0, count: Int32 = 0
+        let result = spriteAPI.pointee.checkCollisions.unsafelyUnwrapped(
+            pointer, goalX, goalY, &actualX, &actualY, &count)
+        return ((actualX, actualY), Sprite.collisionInfos(result, count: count))
+    }
+
+    /// Like `checkCollisions(goalX:goalY:)`, but visits each collision
+    /// instead of building an array, avoiding per-call allocations.
+    public func checkCollisions(goalX: Float, goalY: Float,
+                                _ visit: (CollisionInfo) -> Void) -> (x: Float, y: Float) {
+        var actualX: Float = 0, actualY: Float = 0, count: Int32 = 0
+        let result = spriteAPI.pointee.checkCollisions.unsafelyUnwrapped(
+            pointer, goalX, goalY, &actualX, &actualY, &count)
+        Sprite.visitCollisions(result, count: count, visit)
+        return (actualX, actualY)
+    }
+
+    /// Moves the sprite toward (goalX, goalY), resolving collisions, and
+    /// returns where it ended up and what it hit.
+    @discardableResult
+    public func moveWithCollisions(goalX: Float, goalY: Float)
+        -> (actual: (x: Float, y: Float), collisions: [CollisionInfo]) {
+        var actualX: Float = 0, actualY: Float = 0, count: Int32 = 0
+        let result = spriteAPI.pointee.moveWithCollisions.unsafelyUnwrapped(
+            pointer, goalX, goalY, &actualX, &actualY, &count)
+        return ((actualX, actualY), Sprite.collisionInfos(result, count: count))
+    }
+
+    /// Like `moveWithCollisions(goalX:goalY:)`, but visits each collision
+    /// instead of building an array, avoiding per-call allocations.
+    @discardableResult
+    public func moveWithCollisions(goalX: Float, goalY: Float,
+                                   _ visit: (CollisionInfo) -> Void) -> (x: Float, y: Float) {
+        var actualX: Float = 0, actualY: Float = 0, count: Int32 = 0
+        let result = spriteAPI.pointee.moveWithCollisions.unsafelyUnwrapped(
+            pointer, goalX, goalY, &actualX, &actualY, &count)
+        Sprite.visitCollisions(result, count: count, visit)
+        return (actualX, actualY)
+    }
+
+    /// Visits and frees a C sprite pointer array.
+    private static func visitSprites(_ pointer: UnsafeMutablePointer<OpaquePointer?>?,
+                                     count: Int32, _ visit: (Sprite) -> Void) {
+        guard let pointer else { return }
+        for index in 0..<Int(count) {
+            if let spritePointer = pointer[index] {
+                visit(wrapper(for: spritePointer))
+            }
+        }
+        System.systemFree(pointer)
+    }
+
+    /// Converts and frees a C sprite pointer array.
+    private static func sprites(_ pointer: UnsafeMutablePointer<OpaquePointer?>?,
+                                count: Int32) -> [Sprite] {
+        var sprites = [Sprite]()
+        sprites.reserveCapacity(Int(count))
+        visitSprites(pointer, count: count) { sprites.append($0) }
+        return sprites
+    }
+
+    /// Sprites with collision rects containing the point.
+    public static func query(atPoint x: Float, _ y: Float) -> [Sprite] {
+        var count: Int32 = 0
+        let result = spriteAPI.pointee.querySpritesAtPoint.unsafelyUnwrapped(x, y, &count)
+        return sprites(result, count: count)
+    }
+
+    /// Like `query(atPoint:_:)`, visiting each sprite without building an
+    /// array.
+    public static func query(atPoint x: Float, _ y: Float, _ visit: (Sprite) -> Void) {
+        var count: Int32 = 0
+        let result = spriteAPI.pointee.querySpritesAtPoint.unsafelyUnwrapped(x, y, &count)
+        visitSprites(result, count: count, visit)
+    }
+
+    /// Sprites with collision rects intersecting the rect.
+    public static func query(inRect x: Float, _ y: Float, width: Float, height: Float) -> [Sprite] {
+        var count: Int32 = 0
+        let result = spriteAPI.pointee.querySpritesInRect.unsafelyUnwrapped(x, y, width, height, &count)
+        return sprites(result, count: count)
+    }
+
+    /// Like `query(inRect:_:width:height:)`, visiting each sprite without
+    /// building an array.
+    public static func query(inRect x: Float, _ y: Float, width: Float, height: Float,
+                             _ visit: (Sprite) -> Void) {
+        var count: Int32 = 0
+        let result = spriteAPI.pointee.querySpritesInRect.unsafelyUnwrapped(x, y, width, height, &count)
+        visitSprites(result, count: count, visit)
+    }
+
+    /// Sprites with collision rects intersecting the line segment.
+    public static func query(alongLine x1: Float, _ y1: Float, _ x2: Float, _ y2: Float) -> [Sprite] {
+        var count: Int32 = 0
+        let result = spriteAPI.pointee.querySpritesAlongLine.unsafelyUnwrapped(x1, y1, x2, y2, &count)
+        return sprites(result, count: count)
+    }
+
+    /// Like `query(alongLine:_:_:_:)`, visiting each sprite without building
+    /// an array.
+    public static func query(alongLine x1: Float, _ y1: Float, _ x2: Float, _ y2: Float,
+                             _ visit: (Sprite) -> Void) {
+        var count: Int32 = 0
+        let result = spriteAPI.pointee.querySpritesAlongLine.unsafelyUnwrapped(x1, y1, x2, y2, &count)
+        visitSprites(result, count: count, visit)
+    }
+
+    /// Like `query(alongLine:)`, with entry/exit information for each sprite.
+    public static func queryInfo(alongLine x1: Float, _ y1: Float,
+                                 _ x2: Float, _ y2: Float) -> [QueryInfo] {
+        var count: Int32 = 0
+        guard let result = spriteAPI.pointee.querySpriteInfoAlongLine.unsafelyUnwrapped(
+            x1, y1, x2, y2, &count) else { return [] }
+        var infos = [QueryInfo]()
+        infos.reserveCapacity(Int(count))
+        for index in 0..<Int(count) {
+            infos.append(QueryInfo(result[index]))
+        }
+        System.systemFree(result)
+        return infos
+    }
+
+    /// Sprites whose collision rects overlap this sprite's.
+    public var overlappingSprites: [Sprite] {
+        var count: Int32 = 0
+        let result = spriteAPI.pointee.overlappingSprites.unsafelyUnwrapped(pointer, &count)
+        return Sprite.sprites(result, count: count)
+    }
+
+    /// Like `overlappingSprites`, visiting each sprite without building an
+    /// array.
+    public func overlappingSprites(_ visit: (Sprite) -> Void) {
+        var count: Int32 = 0
+        let result = spriteAPI.pointee.overlappingSprites.unsafelyUnwrapped(pointer, &count)
+        Sprite.visitSprites(result, count: count, visit)
+    }
+
+    /// All sprites in the display list that overlap another sprite.
+    public static var allOverlappingSprites: [Sprite] {
+        var count: Int32 = 0
+        let result = spriteAPI.pointee.allOverlappingSprites.unsafelyUnwrapped(&count)
+        return sprites(result, count: count)
+    }
+
+    /// Like `allOverlappingSprites`, visiting each sprite without building
+    /// an array.
+    public static func allOverlappingSprites(_ visit: (Sprite) -> Void) {
+        var count: Int32 = 0
+        let result = spriteAPI.pointee.allOverlappingSprites.unsafelyUnwrapped(&count)
+        visitSprites(result, count: count, visit)
+    }
+}

Sources/PlaydateKit/Support.swift

@@ -0,0 +1,91 @@
+//
+//  Support.swift
+//  Internal helpers shared by the wrappers.
+//
+//  C-string conversions are implemented manually (rather than with
+//  `String(cString:)` / `withCString`) so the module stays within the
+//  Embedded Swift subset used for device builds.
+//
+
+internal import CPlaydate
+
+extension String {
+    /// Creates a string by copying a null-terminated UTF-8 C string.
+    init(playdateCString pointer: UnsafePointer<CChar>) {
+        var count = 0
+        while pointer[count] != 0 { count += 1 }
+        let bytes = UnsafeRawBufferPointer(start: pointer, count: count)
+        self = String(decoding: bytes, as: UTF8.self)
+    }
+
+    /// Creates a string from a nullable C string, or `nil` if the pointer is null.
+    init?(playdateCString pointer: UnsafePointer<CChar>?) {
+        guard let pointer else { return nil }
+        self.init(playdateCString: pointer)
+    }
+
+    /// Calls `body` with a temporary null-terminated UTF-8 copy of the
+    /// string. The copy lives on the stack for short strings, so calling
+    /// this in the update loop does not churn the heap.
+    func withPlaydateCString<Result>(_ body: (UnsafePointer<CChar>) -> Result) -> Result {
+        let count = utf8.count
+        return withUnsafeTemporaryAllocation(of: CChar.self, capacity: count + 1) { buffer in
+            var index = 0
+            for byte in utf8 {
+                buffer[index] = CChar(bitPattern: byte)
+                index += 1
+            }
+            buffer[count] = 0
+            return body(buffer.baseAddress.unsafelyUnwrapped)
+        }
+    }
+
+    /// Calls `body` with a temporary buffer of the string's UTF-8 bytes (not
+    /// null-terminated) and its length, for the `(const void*, size_t)` text
+    /// APIs. Stack-allocated for short strings.
+    func withPlaydateUTF8<Result>(_ body: (UnsafeRawPointer, Int) -> Result) -> Result {
+        let count = utf8.count
+        return withUnsafeTemporaryAllocation(of: UInt8.self, capacity: count + 1) { buffer in
+            var index = 0
+            for byte in utf8 {
+                buffer[index] = byte
+                index += 1
+            }
+            return body(UnsafeRawPointer(buffer.baseAddress.unsafelyUnwrapped), count)
+        }
+    }
+
+    /// Copies the string into a newly allocated null-terminated C string.
+    /// The caller owns the memory and must free it with `deallocate()`.
+    func copiedPlaydateCString() -> UnsafeMutablePointer<CChar> {
+        let count = utf8.count
+        let buffer = UnsafeMutablePointer<CChar>.allocate(capacity: count + 1)
+        var index = 0
+        for byte in utf8 {
+            buffer[index] = CChar(bitPattern: byte)
+            index += 1
+        }
+        buffer[count] = 0
+        return buffer
+    }
+}
+
+#if hasFeature(Embedded) && !os(macOS)
+/// The Embedded Swift runtime allocates through `posix_memalign(3)`, which
+/// the Playdate device C library does not provide. Memory comes from
+/// `malloc`, which the SDK's setup code routes to the firmware allocator.
+/// The pointer is later released with plain `free`, so it cannot be offset
+/// to adjust alignment; the firmware allocator's natural alignment has to
+/// satisfy the request, which the precondition asserts.
+@_cdecl("posix_memalign")
+public func posix_memalign(
+    _ memptr: UnsafeMutablePointer<UnsafeMutableRawPointer?>,
+    _ alignment: Int,
+    _ size: Int
+) -> CInt {
+    guard let allocation = malloc(size) else { fatalError() }
+    precondition(Int(bitPattern: allocation) % alignment == 0)
+    memptr.pointee = allocation
+    return 0
+}
+#endif

Sources/PlaydateKit/System.swift

@@ -0,0 +1,485 @@
+//
+//  System.swift
+//  Wraps `playdate->system` (pd_api_sys.h).
+//
+
+internal import CPlaydate
+
+/// The system API: logging, input, time, menu items, and device state.
+public enum System {}
+
+extension System {
+    private static var api: UnsafePointer<playdate_sys> { Playdate.systemAPI.unsafelyUnwrapped }
+
+    // MARK: - Types
+
+    /// The state of the d-pad and face buttons, as an option set.
+    public struct Buttons: OptionSet, Sendable {
+        public let rawValue: UInt32
+        public init(rawValue: UInt32) { self.rawValue = rawValue }
+        init(_ buttons: PDButtons) { self.rawValue = UInt32(buttons.rawValue) }
+        var cValue: PDButtons { PDButtons(PDButtons.RawValue(rawValue)) }
+
+        public static let left = Buttons(kButtonLeft)
+        public static let right = Buttons(kButtonRight)
+        public static let up = Buttons(kButtonUp)
+        public static let down = Buttons(kButtonDown)
+        public static let b = Buttons(kButtonB)
+        public static let a = Buttons(kButtonA)
+    }
+
+    /// Peripherals that can be enabled with `setPeripheralsEnabled(_:)`.
+    public struct Peripherals: OptionSet, Sendable {
+        public let rawValue: UInt32
+        public init(rawValue: UInt32) { self.rawValue = rawValue }
+
+        public static let none = Peripherals([])
+        public static let accelerometer = Peripherals(rawValue: UInt32(kAccelerometer.rawValue))
+        public static let all = Peripherals(rawValue: UInt32(kAllPeripherals.rawValue))
+    }
+
+    /// The system language.
+    public enum Language: UInt32, Sendable {
+        case english = 0
+        case japanese = 1
+        /// Only meaningful as an argument to `localizedText(forKey:language:)`.
+        case system = 2
+
+        init(_ language: PDLanguage) {
+            self = Language(rawValue: UInt32(language.rawValue)) ?? .english
+        }
+        var cValue: PDLanguage { PDLanguage(PDLanguage.RawValue(rawValue)) }
+    }
+
+    /// A calendar date and time, mirroring `PDDateTime`.
+    public struct DateTime: Sendable {
+        public var year: UInt16
+        /// 1...12
+        public var month: UInt8
+        /// 1...31
+        public var day: UInt8
+        /// 1 = Monday ... 7 = Sunday
+        public var weekday: UInt8
+        /// 0...23
+        public var hour: UInt8
+        public var minute: UInt8
+        public var second: UInt8
+
+        public init(year: UInt16, month: UInt8, day: UInt8, weekday: UInt8 = 0,
+                    hour: UInt8, minute: UInt8, second: UInt8) {
+            self.year = year
+            self.month = month
+            self.day = day
+            self.weekday = weekday
+            self.hour = hour
+            self.minute = minute
+            self.second = second
+        }
+
+        init(_ dateTime: PDDateTime) {
+            year = dateTime.year
+            month = dateTime.month
+            day = dateTime.day
+            weekday = dateTime.weekday
+            hour = dateTime.hour
+            minute = dateTime.minute
+            second = dateTime.second
+        }
+
+        var cValue: PDDateTime {
+            PDDateTime(year: year, month: month, day: day, weekday: weekday,
+                       hour: hour, minute: minute, second: second)
+        }
+    }
+
+    /// Battery and power supply state.
+    public struct PowerStatus: OptionSet, Sendable {
+        public let rawValue: UInt32
+        public init(rawValue: UInt32) { self.rawValue = rawValue }
+
+        public static let charging = PowerStatus(rawValue: UInt32(kPDPowerStatusCharging.rawValue))
+        public static let usb = PowerStatus(rawValue: UInt32(kPDPowerStatusUsb.rawValue))
+        public static let screws = PowerStatus(rawValue: UInt32(kPDPowerStatusScrews.rawValue))
+    }
+
+    /// OS, language, and pdx version information, mirroring `PDInfo`.
+    public struct Info: Sendable {
+        public let osVersion: UInt32
+        public let language: Language
+        public let pdxVersion: UInt32
+    }
+
+    // MARK: - Memory
+
+    /// The system allocator. Pass `nil` to allocate, `size` 0 to free.
+    @discardableResult
+    public static func realloc(_ pointer: UnsafeMutableRawPointer?, size: Int) -> UnsafeMutableRawPointer? {
+        api.pointee.realloc.unsafelyUnwrapped(pointer, size)
+    }
+
+    /// Frees memory that the Playdate OS handed to the caller (e.g. strings
+    /// returned by `localizedText(forKey:)`).
+    static func systemFree(_ pointer: UnsafeMutableRawPointer?) {
+        _ = api.pointee.realloc.unsafelyUnwrapped(pointer, 0)
+    }
+
+    // MARK: - Logging
+
+    /// Logs a message to the console (device serial or simulator console).
+    public static func log(_ message: String) {
+        message.withPlaydateCString { cplaydate_log(Playdate.apiPointer, $0) }
+    }
+
+    /// Stops execution and displays the message as a fatal error.
+    public static func error(_ message: String) {
+        message.withPlaydateCString { cplaydate_error(Playdate.apiPointer, $0) }
+    }
+
+    // MARK: - Time
+
+    public static var language: Language { Language(api.pointee.getLanguage.unsafelyUnwrapped()) }
+
+    /// Milliseconds since the game launched. Wraps around after about 49 days.
+    public static var currentTimeMilliseconds: UInt32 {
+        UInt32(api.pointee.getCurrentTimeMilliseconds.unsafelyUnwrapped())
+    }
+
+    /// Seconds (and sub-second milliseconds) since midnight 2000-01-01 UTC.
+    public static var secondsSinceEpoch: (seconds: UInt32, milliseconds: UInt32) {
+        var milliseconds: UInt32 = 0
+        let seconds = withUnsafeMutablePointer(to: &milliseconds) {
+            api.pointee.getSecondsSinceEpoch.unsafelyUnwrapped($0)
+        }
+        return (UInt32(seconds), milliseconds)
+    }
+
+    /// High-resolution timer value, in seconds.
+    public static var elapsedTime: Float { api.pointee.getElapsedTime.unsafelyUnwrapped() }
+
+    public static func resetElapsedTime() { api.pointee.resetElapsedTime.unsafelyUnwrapped() }
+
+    /// Offset from UTC of the user-set timezone, in seconds.
+    public static var timezoneOffset: Int32 { api.pointee.getTimezoneOffset.unsafelyUnwrapped() }
+
+    public static var shouldDisplay24HourTime: Bool {
+        api.pointee.shouldDisplay24HourTime.unsafelyUnwrapped() != 0
+    }
+
+    public static func convertEpochToDateTime(_ epoch: UInt32) -> DateTime {
+        var dateTime = PDDateTime()
+        api.pointee.convertEpochToDateTime.unsafelyUnwrapped(epoch, &dateTime)
+        return DateTime(dateTime)
+    }
+
+    public static func convertDateTimeToEpoch(_ dateTime: DateTime) -> UInt32 {
+        var cValue = dateTime.cValue
+        return api.pointee.convertDateTimeToEpoch.unsafelyUnwrapped(&cValue)
+    }
+
+    /// Blocks execution for the given number of milliseconds.
+    public static func delay(milliseconds: UInt32) {
+        api.pointee.delay.unsafelyUnwrapped(milliseconds)
+    }
+
+    /// Requests the server time. The completion receives the time string or
+    /// an error string. Only one request is tracked at a time; a second call
+    /// before the first completes replaces the stored completion.
+    public static func getServerTime(_ completion: @escaping (_ time: String?, _ error: String?) -> Void) {
+        serverTimeCompletion = completion
+        api.pointee.getServerTime.unsafelyUnwrapped { time, error in
+            let completion = System.serverTimeCompletion
+            System.serverTimeCompletion = nil
+            completion?(String(playdateCString: time), String(playdateCString: error))
+        }
+    }
+
+    nonisolated(unsafe) private static var serverTimeCompletion: ((String?, String?) -> Void)?
+
+    // MARK: - Update loop
+
+    /// Sets the per-frame update callback. Return `true` to redraw the display.
+    public static func setUpdateCallback(_ callback: @escaping () -> Bool) {
+        updateCallback = callback
+        api.pointee.setUpdateCallback.unsafelyUnwrapped({ _ in
+            System.updateCallback?() == true ? 1 : 0
+        }, nil)
+    }
+
+    nonisolated(unsafe) private static var updateCallback: (() -> Bool)?
+
+    /// Draws the current frames-per-second value at the given point.
+    public static func drawFPS(x: Int = 0, y: Int = 0) {
+        api.pointee.drawFPS.unsafelyUnwrapped(Int32(x), Int32(y))
+    }
+
+    // MARK: - Input
+
+    /// The current button state: held, pressed this frame, released this frame.
+    public static var buttonState: (current: Buttons, pushed: Buttons, released: Buttons) {
+        var current = PDButtons(0), pushed = PDButtons(0), released = PDButtons(0)
+        api.pointee.getButtonState.unsafelyUnwrapped(&current, &pushed, &released)
+        return (Buttons(current), Buttons(pushed), Buttons(released))
+    }
+
+    /// Installs a callback invoked for every button press/release. `queueSize`
+    /// sets how many events are buffered between frames. The return value of
+    /// the callback is reserved by the OS; return 0.
+    public static func setButtonCallback(queueSize: Int = 5,
+                                         _ callback: ((_ button: Buttons, _ isDown: Bool, _ when: UInt32) -> Int32)?) {
+        buttonCallback = callback
+        if callback != nil {
+            api.pointee.setButtonCallback.unsafelyUnwrapped({ button, down, when, _ in
+                System.buttonCallback?(Buttons(button), down != 0, when) ?? 0
+            }, nil, Int32(queueSize))
+        } else {
+            api.pointee.setButtonCallback.unsafelyUnwrapped(nil, nil, Int32(queueSize))
+        }
+    }
+
+    nonisolated(unsafe) private static var buttonCallback: ((Buttons, Bool, UInt32) -> Int32)?
+
+    public static func setPeripheralsEnabled(_ peripherals: Peripherals) {
+        api.pointee.setPeripheralsEnabled.unsafelyUnwrapped(PDPeripherals(PDPeripherals.RawValue(peripherals.rawValue)))
+    }
+
+    /// The most recent accelerometer reading, in g. Enable the accelerometer
+    /// with `setPeripheralsEnabled(.accelerometer)` first.
+    public static var accelerometer: (x: Float, y: Float, z: Float) {
+        var x: Float = 0, y: Float = 0, z: Float = 0
+        api.pointee.getAccelerometer.unsafelyUnwrapped(&x, &y, &z)
+        return (x, y, z)
+    }
+
+    /// Degrees the crank moved since the last frame.
+    public static var crankChange: Float { api.pointee.getCrankChange.unsafelyUnwrapped() }
+
+    /// The crank position in degrees; 0 points along the +Y axis.
+    public static var crankAngle: Float { api.pointee.getCrankAngle.unsafelyUnwrapped() }
+
+    public static var isCrankDocked: Bool { api.pointee.isCrankDocked.unsafelyUnwrapped() != 0 }
+
+    /// Disables or enables the crank dock/undock sounds. Returns the previous setting.
+    @discardableResult
+    public static func setCrankSoundsDisabled(_ disabled: Bool) -> Bool {
+        api.pointee.setCrankSoundsDisabled.unsafelyUnwrapped(disabled ? 1 : 0) != 0
+    }
+
+    /// Whether the user has the "flipped" system setting enabled.
+    public static var isFlipped: Bool { api.pointee.getFlipped.unsafelyUnwrapped() != 0 }
+
+    public static func setAutoLockDisabled(_ disabled: Bool) {
+        api.pointee.setAutoLockDisabled.unsafelyUnwrapped(disabled ? 1 : 0)
+    }
+
+    /// Installs a callback invoked when a message is received on the serial port
+    /// via `msg <text>`.
+    public static func setSerialMessageCallback(_ callback: ((String) -> Void)?) {
+        serialMessageCallback = callback
+        if callback != nil {
+            api.pointee.setSerialMessageCallback.unsafelyUnwrapped { data in
+                guard let message = String(playdateCString: data) else { return }
+                System.serialMessageCallback?(message)
+            }
+        } else {
+            api.pointee.setSerialMessageCallback.unsafelyUnwrapped(nil)
+        }
+    }
+
+    nonisolated(unsafe) private static var serialMessageCallback: ((String) -> Void)?
+
+    // MARK: - System menu
+
+    /// An item added to the system menu. Keep no more than three items at once.
+    public final class MenuItem {
+        let pointer: OpaquePointer
+        var onSelect: (MenuItem) -> Void
+        /// Retains C strings passed to the OS for option titles.
+        private var retainedOptionTitles: [UnsafeMutablePointer<CChar>] = []
+
+        fileprivate init?(pointer: OpaquePointer?,
+                          retainedOptionTitles: [UnsafeMutablePointer<CChar>] = [],
+                          onSelect: @escaping (MenuItem) -> Void) {
+            guard let pointer else {
+                for title in retainedOptionTitles { title.deallocate() }
+                return nil
+            }
+            self.pointer = pointer
+            self.retainedOptionTitles = retainedOptionTitles
+            self.onSelect = onSelect
+        }
+
+        /// The menu item's title.
+        public var title: String {
+            get {
+                String(playdateCString: Playdate.systemAPI.pointee.getMenuItemTitle.unsafelyUnwrapped(pointer)) ?? ""
+            }
+            set {
+                newValue.withPlaydateCString {
+                    Playdate.systemAPI.pointee.setMenuItemTitle.unsafelyUnwrapped(pointer, $0)
+                }
+            }
+        }
+
+        /// For checkmark items this is 0 or 1; for option items it is the
+        /// index of the selected option.
+        public var value: Int {
+            get { Int(Playdate.systemAPI.pointee.getMenuItemValue.unsafelyUnwrapped(pointer)) }
+            set { Playdate.systemAPI.pointee.setMenuItemValue.unsafelyUnwrapped(pointer, Int32(newValue)) }
+        }
+
+        /// Convenience view of `value` for checkmark items.
+        public var isChecked: Bool {
+            get { value != 0 }
+            set { value = newValue ? 1 : 0 }
+        }
+
+        fileprivate func deallocateRetainedTitles() {
+            for title in retainedOptionTitles { title.deallocate() }
+            retainedOptionTitles = []
+        }
+    }
+
+    nonisolated(unsafe) private static var liveMenuItems: [MenuItem] = []
+
+    private static let menuItemTrampoline: @convention(c) (UnsafeMutableRawPointer?) -> Void = { userdata in
+        guard let userdata else { return }
+        let item = Unmanaged<MenuItem>.fromOpaque(userdata).takeUnretainedValue()
+        item.onSelect(item)
+    }
+
+    /// Adds a plain menu item to the system menu.
+    @discardableResult
+    public static func addMenuItem(title: String, onSelect: @escaping (MenuItem) -> Void) -> MenuItem? {
+        var item: MenuItem?
+        title.withPlaydateCString { cTitle in
+            let pointer = api.pointee.addMenuItem.unsafelyUnwrapped(cTitle, menuItemTrampoline, nil)
+            item = MenuItem(pointer: pointer, onSelect: onSelect)
+        }
+        return registered(item)
+    }
+
+    /// Adds a menu item with a checkbox.
+    @discardableResult
+    public static func addCheckmarkMenuItem(title: String, isChecked: Bool = false,
+                                            onSelect: @escaping (MenuItem) -> Void) -> MenuItem? {
+        var item: MenuItem?
+        title.withPlaydateCString { cTitle in
+            let pointer = api.pointee.addCheckmarkMenuItem.unsafelyUnwrapped(
+                cTitle, isChecked ? 1 : 0, menuItemTrampoline, nil)
+            item = MenuItem(pointer: pointer, onSelect: onSelect)
+        }
+        return registered(item)
+    }
+
+    /// Adds a menu item that cycles through the given options.
+    @discardableResult
+    public static func addOptionsMenuItem(title: String, options: [String],
+                                          onSelect: @escaping (MenuItem) -> Void) -> MenuItem? {
+        // The OS keeps the option title pointers, so copy and retain them for
+        // the lifetime of the menu item.
+        let copies = options.map { $0.copiedPlaydateCString() }
+        var cOptions: [UnsafePointer<CChar>?] = copies.map { UnsafePointer($0) }
+        var item: MenuItem?
+        title.withPlaydateCString { cTitle in
+            cOptions.withUnsafeMutableBufferPointer { buffer in
+                let pointer = api.pointee.addOptionsMenuItem.unsafelyUnwrapped(
+                    cTitle, buffer.baseAddress, Int32(options.count), menuItemTrampoline, nil)
+                item = MenuItem(pointer: pointer, retainedOptionTitles: copies, onSelect: onSelect)
+            }
+        }
+        return registered(item)
+    }
+
+    /// Registers the wrapper as the item's userdata and keeps it alive.
+    private static func registered(_ item: MenuItem?) -> MenuItem? {
+        guard let item else { return nil }
+        api.pointee.setMenuItemUserdata.unsafelyUnwrapped(
+            item.pointer, Unmanaged.passUnretained(item).toOpaque())
+        liveMenuItems.append(item)
+        return item
+    }
+
+    public static func removeMenuItem(_ item: MenuItem) {
+        api.pointee.removeMenuItem.unsafelyUnwrapped(item.pointer)
+        item.deallocateRetainedTitles()
+        liveMenuItems.removeAll { $0 === item }
+    }
+
+    public static func removeAllMenuItems() {
+        api.pointee.removeAllMenuItems.unsafelyUnwrapped()
+        for item in liveMenuItems { item.deallocateRetainedTitles() }
+        liveMenuItems = []
+    }
+
+    /// Sets a custom image for the pause menu, optionally shifted left by
+    /// `xOffset` (0...200).
+    public static func setMenuImage(_ bitmap: Graphics.Bitmap?, xOffset: Int = 0) {
+        api.pointee.setMenuImage.unsafelyUnwrapped(bitmap?.pointer, Int32(xOffset))
+    }
+
+    // MARK: - Device state
+
+    /// Whether the user has enabled the "reduce flashing" accessibility setting.
+    public static var reduceFlashing: Bool { api.pointee.getReduceFlashing.unsafelyUnwrapped() != 0 }
+
+    /// Battery charge, 0...100.
+    public static var batteryPercentage: Float { api.pointee.getBatteryPercentage.unsafelyUnwrapped() }
+
+    public static var batteryVoltage: Float { api.pointee.getBatteryVoltage.unsafelyUnwrapped() }
+
+    /// Flushes the CPU instruction cache after loading code at runtime.
+    public static func clearICache() { api.pointee.clearICache.unsafelyUnwrapped() }
+
+    /// Quits the current game and restarts it with the given launch arguments.
+    public static func restartGame(launchArguments: String? = nil) {
+        if let launchArguments {
+            launchArguments.withPlaydateCString { api.pointee.restartGame.unsafelyUnwrapped($0) }
+        } else {
+            api.pointee.restartGame.unsafelyUnwrapped(nil)
+        }
+    }
+
+    /// The arguments the game was launched with, and the path of the pdx.
+    public static var launchArguments: (arguments: String?, path: String?) {
+        var path: UnsafePointer<CChar>?
+        let arguments = api.pointee.getLaunchArgs.unsafelyUnwrapped(&path)
+        return (String(playdateCString: arguments), String(playdateCString: path))
+    }
+
+    /// Sends data over the mirror connection. Returns `false` if mirroring is
+    /// not active or the send fails.
+    @discardableResult
+    public static func sendMirrorData(command: UInt8, data: UnsafeMutableRawBufferPointer) -> Bool {
+        api.pointee.sendMirrorData.unsafelyUnwrapped(command, data.baseAddress, Int32(data.count))
+    }
+
+    /// OS, language, and pdx version information.
+    public static var info: Info {
+        let info = api.pointee.getSystemInfo.unsafelyUnwrapped().unsafelyUnwrapped.pointee
+        return Info(osVersion: info.osversion,
+                    language: Language(info.language),
+                    pdxVersion: info.pdxversion)
+    }
+
+    /// Looks up a localized string by key from the game's strings files.
+    public static func localizedText(forKey key: String, language: Language = .system) -> String? {
+        key.withPlaydateCString { cKey in
+            guard let cString = api.pointee.getLocalizedText.unsafelyUnwrapped(cKey, language.cValue) else {
+                return nil
+            }
+            let text = String(playdateCString: cString)
+            systemFree(cString)
+            return text
+        }
+    }
+
+    /// The system volume, 0...1.
+    public static var volume: Float { api.pointee.getVolume.unsafelyUnwrapped() }
+
+    public static var powerStatus: PowerStatus {
+        PowerStatus(rawValue: UInt32(api.pointee.getPowerStatus.unsafelyUnwrapped().rawValue))
+    }
+
+    /// Quits the game and returns to the launcher.
+    public static func exitToLauncher() { api.pointee.exitToLauncher.unsafelyUnwrapped() }
+}