Inside Playdate with C

Allocates heap space if ptr is NULL, else reallocates the given pointer. If size is zero, frees the given pointer.

Calls the log function, outputting an error in red to the console, then pauses execution.

Calls the log function, equivalent to print() in Lua.

title will be the title displayed by the menu item.

Adds a new menu item to the System Menu. When invoked by the user, this menu item will:

Your game can then present an options interface to the player, or take other action, in whatever manner you choose.

Adds a new menu item that can be checked or unchecked by the player.

title will be the title displayed by the menu item.

value should be 0 for unchecked, 1 for checked.

If this menu item is interacted with while the system menu is open, callback will be called when the menu is closed.

Adds a new menu item that allows the player to cycle through a set of options.

title will be the title displayed by the menu item.

options should be an array of strings representing the states this menu item can cycle through. Due to limited horizontal space, the option strings and title should be kept short for this type of menu item.

optionsCount should be the number of items contained in options.

If this menu item is interacted with while the system menu is open, callback will be called when the menu is closed.

Removes the menu item from the system menu.

Removes all custom menu items from the system menu.

Gets or sets the display title of the menu item.

Gets or sets the integer value of the menu item.

For checkmark menu items, 1 means checked, 0 unchecked. For option menu items, the value indicates the array index of the currently selected option.

Gets or sets the userdata value associated with this menu item.

Returns the number of milliseconds since…​some arbitrary point in time. This should present a consistent timebase while a game is running, but the counter will be disabled when the device is sleeping.

Returns the number of seconds (and sets milliseconds if not NULL) elapsed since midnight (hour 0), January 1, 2000.

Resets the high-resolution timer.

Returns the number of seconds since playdate.resetElapsedTime() was called. The value is a floating-point number with microsecond accuracy.

Returns 1 if the global "flipped" system setting is set, otherwise 0.

Returns 1 if the global "reduce flashing" system setting is set, otherwise 0.

Allocates a buffer ret and formats a string. Note that the caller is responsible for freeing ret.

A game can optionally provide an image to be displayed alongside the system menu. bitmap must be a 400x240 LCDBitmap. All important content should be in the left half of the image in an area 200 pixels wide, as the menu will obscure the rest. The right side of the image will be visible briefly as the menu animates in and out.

Optionally, a non-zero xoffset, can be provided. This must be a number between 0 and 200 and will cause the menu image to animate to a position offset left by xoffset pixels as the menu is animated in.

This function could be called in response to the kEventPause event in your implementation of eventHandler().

Replaces the default Lua run loop function with a custom update function. The update function should return a non-zero number to tell the system to update the display, or zero if update isn’t needed.

Calculates the current frames per second and draws that value at x, y.

Returns a value from 0-100 denoting the current level of battery charge. 0 = empty; 100 = full.

Returns the battery’s current voltage level.

Returns a new SoundChannel object.

Frees the given SoundChannel.

Adds a SoundSource to the channel. If a source is not assigned to a channel, it plays on the default global channel.

Removes a SoundSource to the channel. Returns 1 if the source was found in (and removed from) the channel, otherwise 0.

Adds a SoundEffect to the channel.

Removes a SoundEffect from the channel.

Sets the volume for the channel, in the range [0-1].

Gets the volume for the channel, in the range [0-1].

Sets a signal to modulate the channel volume.

Gets a signal modulating the channel volume.

Sets the pan parameter for the channel. Valid values are in the range [-1,1], where -1 is left, 0 is center, and 1 is right.

Sets a signal to modulate the channel pan.

Gets a signal modulating the channel pan.

Creates a new SoundSource using the given data provider callback and adds it to the channel.

This function should fill the passed-in left buffer (and right if it’s a stereo source) with len samples each and return 1, or return 0 if the source is silent through the cycle. The caller takes ownership of the allocated SoundSource, and should free it with

when it is not longer in use.

Returns a signal that follows the volume of the channel before effects are applied.

Returns a signal that follows the volume of the channel after effects are applied.

Sets the playback volume (0.0 - 1.0) for left and right channels of the source.

Gets the playback volume (0.0 - 1.0) for left and right channels of the source.

Returns 1 if the source is currently playing.

Sets a function to be called when the source has finished playing.

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

Loads the sound data from the file at path into an existing AudioSample, sample.

Allocates and returns a new AudioSample, with the sound data loaded in memory. If there is no file at path, the function returns null.

Returns a new AudioSample referencing the given audio data. The sample keeps a pointer to the data instead of copying it, so the data must remain valid while the sample is active. format is one of the following values:

pd_api_sound.h also provides some helper macros and functions:

Frees the given sample.

Returns the length, in seconds, of sample.

Allocates a new FilePlayer.

Frees the given player.

Prepares player to stream the file at path. Returns 1 if the file exists, otherwise 0.

Pauses the file player.

Starts playing the file player. If repeat is greater than one, it loops the given number of times. If zero, it loops endlessly until it is stopped with playdate->sound->fileplayer->stop().

Returns one if player is playing, zero if not.

Sets the buffer length of player to bufferLen seconds;

Returns the length, in seconds, of the file loaded into player.

Sets a function to be called when playback has completed. This is an alias for playdate→sound→source→setFinishCallback().

Returns one if player has underrun, zero if not.

Sets the start and end of the loop region for playback, in seconds. If end is omitted, the end of the file is used.

Sets the current offset in seconds.

Gets the current offset in seconds for player.

Sets the playback rate for the player. 1.0 is normal speed, 0.5 is down an octave, 2.0 is up an octave, etc. Unlike sampleplayers, fileplayers can’t play in reverse (i.e., rate < 0).

Gets the playback rate for player.

If flag evaluates to true, the player will restart playback (after an audible stutter) as soon as data is available.

Sets the playback volume for left and right channels of player.

Gets the left and right channel playback volume for player.

Stops playing the file.

Changes the volume of the fileplayer to left and right over a length of len sample frames, then calls the provided callback (if set).

Returns the length, in seconds, of the sample assigned to player.

Returns one if player is playing a sample, zero if not.

Allocates and returns a new SamplePlayer.

Starts playing the sample in player.

If repeat is greater than one, it loops the given number of times. If zero, it loops endlessly until it is stopped with playdate->sound->sampleplayer->stop(). If negative one, it does ping-pong looping.

Sets the playback rate for the sample. 1.0 is normal speed, 0.5 is down an octave, 2.0 is up an octave, etc.

Sets a function to be called when playback has completed. See sndCallbackProc.

Sets the current offset of the SamplePlayer, in seconds.

Gets the current offset in seconds for player.

When used with a repeat of -1, does ping-pong looping, with a start and end position in frames.

Pauses or resumes playback.

Sets the playback rate for the player. 1.0 is normal speed, 0.5 is down an octave, 2.0 is up an octave, etc.

Gets the playback rate for player.

Assigns sample to player.

Sets the playback volume for left and right channels.

Gets the current left and right channel volume of the sampleplayer.

Stops playing the sample.

Frees the given player.

Creates a new synth object.

Frees a synth object, first removing it from the sound engine if needed.

Sets the waveform of the synth. The SoundWaveform enum contains the following values:

Provides custom waveform generator functions for the synth. synthRenderFunc, the data provider callback, is the only required function. left and right are sample buffers in Q8.24 format. The generator should add its samples to the data already in the buffer. l and r are level values in Q4.28 format, used to scale the samples to follow the synth’s envelope and/or amplitude modulator levels. dl and dr are slope values that should be added to l and r every frame.

Provides a sample for the synth to play. Sample data must be uncompressed PCM, not ADPCM.

Sets the parameters of the synth’s ADSR envelope.

Transposes the synth’s output by the given number of half steps. For example, if the transpose is set to 2 and a C note is played, the synth will output a D instead.

Sets or gets a signal to modulate the synth’s frequency. The signal is scaled so that a value of 1 doubles the synth pitch (i.e. an octave up) and -1 halves it (an octave down).

Sets or gets a signal to modulate the synth’s output amplitude.

Returns the number of parameters advertised by the synth.

Sets the (0-based) parameter at position num to the given value. Returns 0 if num is not a valid parameter index.

Sets or gets a signal to modulate the parameter at index num.

Plays a note on the synth, at the given frequency. Specify len = -1 to leave the note playing until a subsequent noteOff() call. If when is 0, the note is played immediately, otherwise the note is scheduled for the given time. Use playdate→sound→getCurrentTime() to get the current time.

The same as playNote but uses MIDI note (where 60 = C4) instead of frequency.

Sends a note off event to the synth, either immediately (when = 0) or at the scheduled time.

Sets and gets the playback volume (0.0 - 1.0) for left and right channels of the synth. This is equivalent to

Returns 1 if the synth is currently playing.

Creates a new PDSynthInstrument object.

Frees the given instrument, first removing it from the sound engine if needed.

Adds the given PDSynth to the instrument. The synth will respond to playNote events between rangeState and rangeEnd, inclusive. The transpose argument is in half-step units, and is added to the instrument’s transpose parameter. The function returns 1 if successful, or 0 if the synth is already in another instrument or channel.

The instrument passes the playNote/playMIDINote() event to the synth in its collection that has been off for the longest, or has been playing longest if all synths are currently playing. See also playdate→sound→synth→playNote(). The PDSynth that received the playNote event is returned.

Forwards the noteOff() event to the synth currently playing the given note. See also playdate→sound→synth→noteOff().

Sets the pitch bend and pitch bend range to be applied to the voices in the instrument.

Sets the transpose parameter for all voices in the instrument.

Sends a noteOff event to all voices in the instrument.

Sets and gets the playback volume (0.0 - 1.0) for left and right channels of the synth. This is equivalent to

Returns the number of voices in the instrument currently playing.

Returns a new LFO object, which can be used to modulate sounds. The type argument is one of the following values:

Frees the LFO.

Sets the LFO shape to one of the values given above.

Sets the LFO’s rate, in cycles per second.

Sets the LFO’s phase.

Sets the center or depth of the LFO.

Sets the LFO type to arpeggio, where the given values are in half-steps from the center note. For example, the sequence (0, 4, 7, 12) plays the notes of a major chord.

Provides a custom function for LFO values.

Sets an initial holdoff time for the LFO where the LFO remains at its center value, and a ramp time where the value increases linearly to its maximum depth. Values are in seconds.

If retrigger is on, the LFO’s phase is reset to 0 when a synth using the LFO starts playing a note.

Return the current output value of the LFO.

If global is set, the LFO is continuously updated whether or not it’s currently in use.

Creates a new envelope with the given parameters.

Frees the envelope.

Sets the ADSR parameters of the envelope.

Sets whether to use legato phrasing for the envelope. If the legato flag is set, when the envelope is re-triggered before it’s released, it remains in the sustain phase instead of jumping back to the attack phase.

If retrigger is on, the envelope always starts from 0 when a note starts playing, instead of the current value if it’s active.

Return the current output value of the envelope.

Creates a new effect using the given processing function. bufactive is 1 if samples have been set in the left or right buffers. The function should return 1 if it changed the buffer samples, otherwise 0. left and right (if the effect is on a stereo channel) are sample buffers in Q8.24 format.

Frees the given effect.

Sets the wet/dry mix for the effect. A level of 1 (full wet) replaces the input with the effect output; 0 leaves the effect out of the mix (which is useful if you’re using a delay line with taps and don’t want to hear the delay line itself).

Sets or gets a signal to modulate the effect’s mix level.

Sets or gets a userdata value for the effect.

Creates a new two pole filter effect.

Frees the given filter.

Sets the type of the filter.

Sets the center/corner frequency of the filter. Value is in Hz.

Sets or gets a signal to modulate the effect’s frequency. The signal is scaled so that a value of 1.0 corresponds to half the sample rate.

Sets the filter gain.

Sets the filter resonance.

Sets or gets a signal to modulate the filter resonance.

Creates a new one pole filter.

Frees the filter.

Sets the filter’s single parameter (cutoff frequency) to p. Values above 0 (up to 1) are high-pass, values below 0 (down to -1) are low-pass.

Sets or gets a signal to modulate the filter parameter.

Returns a new BitCrusher effect.

Frees the given effect.

Sets the amount of crushing to amount. Valid values are 0 (no effect) to 1 (quantizing output to 1-bit).

Sets or gets a signal to modulate the crushing amount.

Sets the number of samples to repeat, quantizing the input in time. A value of 0 produces no undersampling, 1 repeats every other sample, etc.

Sets or gets a signal to modulate the undersampling amount.

Returns a new ring modulator effect.

Sets the frequency of the modulation signal.

Sets or gets a signal to modulate the frequency of the ring modulator.

Returns a new overdrive effect.

Frees the given effect.

Sets the gain of the overdrive effect.

Sets the level where the amplified input clips.

Sets or gets a signal to modulate the limit parameter.

Adds an offset to the upper and lower limits to create an asymmetric clipping.

Sets or gets a signal to modulate the offset parameter.

Creates a new delay line effect. The length parameter is given in samples.

Frees the delay line.

Changes the length of the delay line, clearing its contents.

Sets the feedback level of the delay line.

Returns a new tap on the delay line, at the given position. delay must be less than or equal to the length of the delay line.

Frees a tap previously created with playdate→sound→delayLine→addTap(), first removing it from the sound engine if needed.

Sets the position of the tap on the delay line, up to the delay line’s length.

Sets a signal to modulate the tap delay. If the signal is continuous (e.g. an envelope or a triangle LFO, but not a square LFO) playback is sped up or slowed down to compress or expand time.

If the delay line is stereo and flip is set, the tap outputs the delay line’s left channel to its right output and vice versa.

Creates or destroys a SoundSequence object.

If the sequence is empty, attempts to load data from the MIDI file at path into the sequence. Returns 1 on success, 0 on failure.

Starts or stops playing the sequence. finishCallback is an optional function to be called when the sequence finishes playing or is stopped.

Returns 1 if the sequence is currently playing, otherwise 0.

Gets or sets the current time in the sequence, in samples since the start of the file. Note that which step this moves the sequence to depends on the current tempo.

Sets the looping range of the sequence. If loops is 0, the loop repeats endlessly.

Sets or gets the tempo of the sequence, in steps per second.

Returns the length of the longest track in the sequence. See also playdate.sound.track.getLength().

Returns the number of tracks in the sequence.

Adds the given playdate.sound.track to the sequence.

Sets or gets the given SoundTrack object at position idx in the sequence.

Sends a stop signal to all playing notes on all tracks.

Creates a new control signal object.

Frees the given signal.

Clears all events from the given signal.

Adds a value to the signal’s timeline at the given step. If interpolate is set, the value is interpolated between the previous step+value and this one.

Removes the control event at the given step.

Returns the MIDI controller number for this ControlSignal, if it was created from a MIDI file via playdate→sound→sequence→loadMIDIFile().

Returns a new SequenceTrack.

Frees the SequenceTrack.

Sets or gets the PDSynthInstrument assigned to the track.

Adds a single note event to the track.

Removes the event at step playing note.

Clears all notes from the track.

Returns the length, in steps, of the track—​that is, the step where the last note in the track ends.

Returns the internal array index for the first note at the given step.

If the given index is in range, sets the data in the out pointers and returns 1; otherwise, returns 0.

Returns the number of ControlSignal objects in the track.

Returns the ControlSignal at index idx.

Returns the ControlSignal for MIDI controller number controller, creating it if the create flag is set and it doesn’t yet exist.

Clears all ControlSignals from the track.

Returns the number of voices currently playing in the track’s instrument.

Returns the maximum number of simultaneously playing notes in the track. (Currently, this value is only set when the track was loaded from a MIDI file. We don’t yet track polyphony for user-created events.)

Mutes or unmutes the track.

Closes the given file handle. Returns 0 on success, or -1 in case of error.

Flushes the output buffer of file immediately. Returns the number of bytes written, or -1 in case of error.

Opens a handle for the file at path. The kFileRead mode opens a file in the game pdx, while kFileReadData searches the game’s data folder; to search the data folder first then fall back on the game pdx, use the bitwise combination kFileRead|kFileReadData.kFileWrite and kFileAppend always write to the data folder. The function returns NULL if a file at path cannot be opened, and playdate->file->geterr() will describe the error. The filesystem has a limit of 64 simultaneous open files.

Reads up to len bytes from the file into the buffer buf. Returns the number of bytes read (0 indicating end of file), or -1 in case of error.

Sets the read/write offset in the given file handle to pos, relative to the whence macro. SEEK_SET is relative to the beginning of the file, SEEK_CUR is relative to the current position of the file pointer, and SEEK_END is relative to the end of the file. Returns 0 on success, -1 on error.

Returns the current read/write offset in the given file handle, or -1 on error.

Writes the buffer of bytes buf to the file. Returns the number of bytes written, or -1 in case of error.

Clears bitmap, filling with the given bgcolor.

Returns a new LCDBitmap that is an exact copy of bitmap.

Returns 1 if any of the opaque pixels in bitmap1 when positioned at x1, y1 with flip1 overlap any of the opaque pixels in bitmap2 at x2, y2 with flip2 within the non-empty rect, or 0 if no pixels overlap or if one or both fall completely outside of rect.

Draws the bitmap with its upper-left corner at location x, y, using the given flip orientation.

Draws the bitmap scaled to xscale and yscale with its upper-left corner at location x, y. Note that flip is not available when drawing scaled bitmaps but negative scale values will achieve the same effect.

Draws the bitmap scaled to xscale and yscale then rotated by degrees with its center as given by proportions centerx and centery at x, y; that is: if centerx and centery are both 0.5 the center of the image is at (x,y), if centerx and centery are both 0 the top left corner of the image (before rotation) is at (x,y), etc.

Frees the given bitmap.

Gets various info about bitmap including its width and height and raw pixel data. The data is 1 bit per pixel packed format, in MSB order; in other words, the high bit of the first byte in data is the top left pixel of the image. If the value returned in hasmask is true, then the mask data follows the image data, beginning at offset rowbytes*height.

Allocates and returns a new LCDBitmap from the file at path. If there is no file at path, the function returns null.

Loads the image at path into the previously allocated bitmap.

Allocates and returns a new width by height LCDBitmap filled with bgcolor.

Draws the bitmap with its upper-left corner at location x, y tiled inside a width by height rectangle.

Returns a new, rotated and scaled LCDBitmap based on the given bitmap.

Sets a mask image for the given bitmap. The set mask must be the same size as the target bitmap.

Gets a mask image for the given bitmap. If the image doesn’t have a mask, getBitmapMask returns NULL.

Returns the idx bitmap in table, If idx is out of bounds, the function returns NULL.

Allocates and returns a new LCDBitmap from the file at path. If there is no file at path, the function returns null.

Loads the imagetable at path into the previously allocated table.

Allocates and returns a new LCDBitmapTable that can hold count width by height LCDBitmaps.

Draws the given text using the provided options. If no font has been set with setFont, the default system font Asheville Sans 14 Light is used.

Returns the height of the given font.

Returns an LCDFontPage object for the given character code. Each LCDFontPage contains information for 256 characters; specifically, if (c1 & ~0xff) == (c2 & ~0xff), then c1 and c2 belong to the same page and the same LCDFontPage can be used to fetch the character data for both instead of searching for the page twice.

Returns an LCDFontGlyph object for character c in LCDFontPage page, and optionally returns the glyph’s bitmap and advance value.

Returns the kerning adjustment between characters c1 and c2 as specified by the font.

Returns the width of the given text in the given font.

Returns the LCDFont object for the font file at path. In case of error, outErr points to a string describing the error.

Draws an ellipse inside the rectangle {x, y, width, height} of width lineWidth (inset from the rectangle bounds). If startAngle != _endAngle, this draws an arc between the given angles. Angles are given in degrees, clockwise from due north.

Fills an ellipse inside the rectangle {x, y, width, height}. If startAngle != _endAngle, this draws a wedge/Pacman between the given angles. Angles are given in degrees, clockwise from due north.

Draws a line from x1, y1 to x2, y2 with a stroke width of width.

Draws a width by height rect at x, y.

Draws a filled width by height rect at x, y.

Draws a filled triangle with points at x1, y1, x2, y2, and x3, y3.

Fills the polygon with vertices at the given coordinates (an array of 2*nPoints ints containing alternating x and y values) using the given color and fill, or winding, rule. See https://en.wikipedia.org/wiki/Nonzero-rule for an explanation of the winding rule.

Clears the entire display, filling it with color.

Sets the background color shown when the display is offset or for clearing dirty areas in the sprite system.

Manually flushes the current frame buffer out to the display. This function is automatically called after each pass through the run loop, so there shouldn’t be any need to call it yourself.

Only valid in the simulator, returns the debug framebuffer as a bitmap. Function is NULL on device.

Returns the raw bits in the display buffer, the last completed frame.

Returns a bitmap containing the contents of the display buffer. The system owns this bitmap—​do not free it!

Returns the current display frame buffer. Rows are 32-bit aligned, so the row stride is 52 bytes, with the extra 2 bytes per row ignored. Bytes are MSB-ordered; i.e., the pixel in column 0 is the 0x80 bit of the first byte of the row.

Returns a copy the contents of the working frame buffer as a bitmap. The caller is responsible for freeing the returned bitmap with playdate->graphics->freeBitmap().

Returns the current language of the system.

After updating pixels in the buffer returned by getFrame(), you must tell the graphics system which rows were updated. This function marks a contiguous range of rows as updated (e.g., markUpdatedRows(0,LCD_ROWS-1) tells the system to update the entire display). Both “start” and “end” are included in the range.

Offsets the origin point for all drawing calls to x, y (can be negative).

This is useful, for example, for centering a "camera" on a sprite that is moving around a world larger than the screen.

Installs a native drawing function for the given sprite.

Sets color to an 8 x 8 pattern using the given bitmap. x, y indicates the top left corner of the 8 x 8 pattern.

Returns the last-read accelerometer data.

Sets the value pointed to by current to a bitmask indicating which buttons are currently down. pushed and released reflect which buttons were pushed or released over the previous update cycle—at the nominal frame rate of 50 ms, fast button presses can be missed if you just poll the instantaneous state.

Returns the current position of the crank, in the range 0-360. Zero is pointing up, and the value increases as the crank moves clockwise, as viewed from the right side of the device.

Returns the angle change of the crank since the last time this function was called. Negative values are anti-clockwise.

Returns 1 or 0 indicating whether or not the crank is folded into the unit.

Decodes a JSON file or string with the given decoder. An instance of json_decoder must implement decodeError. The remaining functions are optional although you’ll probably want to implement at least didDecodeTableValue and didDecodeArrayValue. The outval pointer, if set, contains the value retured from the top-level didDecodeSublist callback.

Note that a whole number encoded to JSON as a float might be decoded as an int. The above convenience functions can be used to convert a json_value to the required type.

Populates the given json_encoder encoder with the functions necessary to encode arbitrary data into a JSON string. userdata is passed as the first argument of the given writeFunc write. When pretty is 1 the string is written with human-readable formatting.

Adds the Lua function f to the Lua runtime, with name name. (name can be a table path using dots, e.g. if name = “mycode.myDrawingFunction” adds the function “myDrawingFunction” to the global table “myCode”.) Returns 1 on success or 0 with an error message in outErr.

Adds the function list reg to the Lua runtime, with the class name name. As above, name can be a table path. The list is terminated with a {NULL, NULL} entry.

Creates a new "class" (i.e., a Lua metatable containing functions) with the given name and adds the given functions and constants to it. If the table is simply a list of functions that won’t be used as a metatable, isstatic should be set to 1 to create a plain table instead of a metatable. Please see C_API/Examples/Array for an example of how to use registerClass to create a Lua table-like object from C.

If a class includes an __index function, it should call this first to check if the indexed variable exists in the metatable. If the indexMetatable() call returns 1, it has located the variable and put it on the stack, and the __index function should return 1 to indicate a value was found. If indexMetatable() doesn’t find a value, the __index function can then do its custom getter magic.

Starts the run loop back up.

Stops the run loop.

Returns the type of the variable at stack position pos. If the type is kTypeObject and outClass is non-NULL, it returns the name of the object’s metatable.

Returns the number of arguments passed to the function.

Returns 1 if the argument at the given position pos is nil.

Returns one if the argument at position pos is true, zero if not.

Returns the argument at position pos as a float.

Returns the argument at position pos as an int.

Returns the argument at position pos as a string.

Returns the argument at position pos as an LCDSprite.

Returns the argument at position pos as a string and sets outlen to its length.

Returns the argument at position pos as an LCDBitmap.

Pushes the int val onto the stack.

Pushes the float val onto the stack.

Pushes the int val onto the stack.

Pushes nil onto the stack.

Pushes the string str onto the stack.

Like pushString(), but pushes an arbitrary byte array to the stack, ignoring \0 characters.

Pushes a lua_CFunction onto the stack.

Pushes the LCDBitmap bitmap onto the stack.

Pushes the LCDSprite sprite onto the stack.

Pushes the given custom object obj onto the stack and returns a pointer to the opaque LuaUDObject. type must match the class name used in playdate->lua->registerClass(). nValues is the number slots to allocate for Lua values.

Checks the object type of the argument at position pos and returns a pointer to it if it’s the correct type. Optionally sets outud to a pointer to the opaque LuaUDObject for the given stack.

Retains the opaque LuaUDObject obj and returns same.

Releases the opaque LuaUDObject obj.

Sets the value of object obj's slot number slot to the value at the top of the stack.

Pushes the value at obj's given slot to the top of the stack and returns its stack position.

Calls the Lua function name and and indicates that nargs number of arguments have already been pushed to the stack for the function to use. name can be a table path using dots, e.g. “playdate.apiVersion”. Returns 1 on success; on failure, returns 0 and puts an error message into the outerr pointer, if it’s set. Calling Lua from C is slow, so use sparingly.

Sets the bounds of the given sprite with bounds.

Returns the bounds of the given sprite as an PDRect;

Moves the given sprite to x, y and resets its bounds based on the bitmap dimensions and center.

Moves the given sprite to by offsetting its current position by dx, dy.

Sets x and y to the current position of sprite.

Sets the given sprite's image to the given bitmap.

Returns the LCDBitmap currently assigned to the given sprite.

Sets the size. The size is used to set the sprite’s bounds when calling moveTo().

Sets the Z order of the given sprite. Higher Z sprites are drawn on top of those with lower Z order.

Returns the Z index of the given sprite.

Sets the tag of the given sprite. This can be useful for identifying sprites or types of sprites when using the collision API.

Returns the tag of the given sprite.

Sets the mode for drawing the sprite’s bitmap.

Flips the bitmap.

Returns the flip setting of the sprite’s bitmap.

Specifies a stencil image to be set on the frame buffer before the sprite is drawn.

Specifies a stencil image to be set on the frame buffer before the sprite is drawn. If tile is set, the stencil will be tiled. Tiled stencils must have width evenly divisible by 32.

Sets the sprite’s stencil to the given pattern.

Clears the sprite’s stencil.

Sets the clipping rectangle for sprite drawing.

Clears the sprite’s clipping rectangle.

Sets the clipping rectangle for all sprites with a Z index within startZ and endZ inclusive.

Clears the clipping rectangle for all sprites with a Z index within startZ and endZ inclusive.

Set the updatesEnabled flag of the given sprite (determines whether the sprite has its update function called). One is true, 0 is false.

Get the updatesEnabled flag of the given sprite.

Set the visible flag of the given sprite (determines whether the sprite has its draw function called). One is true, 0 is false.

Get the visible flag of the given sprite.

Marking a sprite opaque tells the sprite system that it doesn’t need to draw anything underneath the sprite, since it will be overdrawn anyway. If you set an image without a mask/alpha channel on the sprite, it automatically sets the opaque flag.

When flag is set to 1, the given sprite will always redraw.

Forces the given sprite to redraw.

Marks the given dirtyRect (in screen coordinates) as needing a redraw. Graphics drawing functions now call this automatically, adding their drawn areas to the sprite’s dirty list, so there’s usually no need to call this manually.

When flag is set to 1, the sprite will draw in screen coordinates, ignoring the currently-set drawOffset.

This only affects drawing, and should not be used on sprites being used for collisions, which will still happen in world-space.

Sets the update function for the given sprite.

Sets the draw function for the given sprite.

Sets and gets the sprite’s userdata, an arbitrary pointer used for associating the sprite with other data.

Adds the given sprite to the display list, so that it is drawn in the current scene.

Removes the given sprite from the display list.

Removes the given count sized array of sprites from the display list.

Removes all sprites from the display list.

Returns the total number of sprites in the display list.

Draws every sprite in the display list.

Updates and draws every sprite in the display list.

Frees and reallocates internal collision data, resetting everything to its default state.

Set the collisionsEnabled flag of the given sprite (along with the collideRect, this determines whether the sprite participates in collisions). One is true, 0 is false. Set to 1 by default.

Get the collisionsEnabled flag of the given sprite.

Marks the area of the given sprite, relative to its bounds, to be checked for collisions with other sprites' collide rects.

Returns the given sprite’s collide rect.

Clears the given sprite’s collide rect.

Set a callback that returns a SpriteCollisionResponseType for a collision between sprite and other.

Returns the same values as playdate->sprite->moveWithCollisions() but does not actually move the sprite.

Moves the given sprite towards goalX, goalY taking collisions into account and returns an array of SpriteCollisionInfo. len is set to the size of the array and actualX, actualY are set to the sprite’s position after collisions. If no collisions occurred, this will be the same as goalX, goalY.

Returns an array of all sprites with collision rects containing the point at x, y. len is set to the size of the array.

Returns an array of all sprites with collision rects that intersect the width by height rect at x, y. len is set to the size of the array.

Returns an array of all sprites with collision rects that intersect the line connecting x1, y1 and x2, y2. len is set to the size of the array.

Returns an array of SpriteQueryInfo for all sprites with collision rects that intersect the line connecting x1, y1 and x2, y2. len is set to the size of the array. If you don’t need this information, use querySpritesAlongLine() as it will be faster.

Returns an array of sprites that have collide rects that are currently overlapping the given sprite’s collide rect. len is set to the size of the array.

Returns an array of all sprites that have collide rects that are currently overlapping. Each consecutive pair of sprites is overlapping (eg. 0 & 1 overlap, 2 & 3 overlap, etc). len is set to the size of the array.