A list of helpful libraries and code

Not sure where I picked this function up at or if I wrote it, but I find myself using it all the time. It's very useful to scale a number across two different systems. For instance, if you have a number X that has values ranging from 100 to 500 (x_min and x_max), you can scale this down to a number between 1 and 10 (a and b). This might be useful to generate indexes for a lookup table or scale enemy speed by the player's score, or whatever else you can think of.

-- scale x between a and b, given x's min and max range
-- returns a number between a and b
function linearScaleBetween(_x,_a,_b,_xMin,_xMax)
    return (((_b-_a)*(_x-_xMin))/(_xMax-_xMin))+_a

Another simple method I get a lot of mileage out of is just a random table item generator:

function getRandomTableItem(_table)
    return _table[ math.random( #_table ) ]

I find myself using both of these in every project I make. Enjoy

1 Like

Hey @professir! Good one. In that vein, here are some functions I use that are complementary to the one you shared:

-- Get a version of val that does not spill outside of min and max.
-- Example: clamp(1.5, -1.1, 1.1) returns 1.1
function clamp(val, min, max)
  return val < min and min or val > max and max or val

-- Find number between two numbers (a, b) at t [0, 1]
-- Example: lerp(10, 30, 0.5) returns 20 (halfway between 10 and 30).
function lerp(a, b, t)
  return math.ceil(a * (1 - t) + b * t)

-- Find value [0, 1] between two numbers (a, b) at v
-- Example: invlerp(10, 30, 20) returns 0.5
function invlerp(a, b, v)
  return clamp((v - a) / (b - a), 0, 1)

-- Finds value [0, 1] of input between output.
-- Example: remap(20, 10, 30, 30, 50) returns 40 as 20 is halfway between 10 and 30 and remapped to new range 30 to 50 is 40. This function allows you to remap a value between two ranges.
function remap(input_val, input_min, input_max, output_min, output_max)
  return lerp(output_min, output_max, invlerp(input_min, input_max, input_val))

Here's something I put together after finding myself repeatedly reaching for animated patterns. I'll acknowledge up front that this isn't the best approach when it comes to performance (an imageable would be faster; also, I haven't done any optimization work here yet). That said, it's quick and fun to prototype with. (I'll also plug the Roto utility I made which could be used to export the animated output from this to a sprite sheet as needed.)


Initialize with a table containing the pattern and animation properties (see the full implementation below for a complete list), and then all it takes is one line to apply it when drawing…

-- initialize
local checkerboard = {0xF0F0, 0xF0F0, 0xF0F0, 0xF0F0, 0x0F0F, 0x0F0F, 0x0F0F, 0x0F0F}
self.easyp = EasyPattern {
    pattern       = checkerboard,
    phaseDuration = 1.0,
    phaseFunction = playdate.easingFunctions.inOutCubic,
    -- <list any additional animation params here>

-- in draw function


Here's an example of a simple horizontal conveyor belt effect:

self.easyp = EasyPattern {
    ditherType     = gfx.image.kDitherTypeVerticalLine,
    xPhaseDuration = 0.5

One for a downward stair bounce effect:

self.easyp = EasyPattern {
    pattern        = checkerboard,
    yPhaseDuration = 1.0,
    yPhaseFunction = playdate.easingFunctions.outBounce,
    yReversed      = true,
    scale          = 2

One that pans in a circular motion:

self.easyp = EasyPattern {
    pattern        = checkerboard,
    phaseDuration  = 0.5,
    phaseFunction  = playdate.easingFunctions.inOutSine,
    xPhaseOffset   = 0.25,
    reverses       = true,
    scale          = 2

And finally one that demonstrates a custom easing function. Here I'm generating a "random" Perlin noise movement, which could be used for e.g. simulating leaves rustling.

self.easyp = EasyPattern {
    pattern        = checkerboard,
    xPhaseDuration = 3.5,
    yPhaseDuration = 2.5,
    xPhaseFunction = function(t, b, c, d) return playdate.graphics.perlin(t / d, 1, 2, 3, 3, 0.5) end,
    yPhaseFunction = function(t, b, c, d) return playdate.graphics.perlin(t / d, 4, 5, 6, 3, 0.5) end,
    scale          = 50


The code isn't doing anything especially complicated, but I did get a bit carried away with the parameterization so file length grew quickly. To make it easier to view the code and docs, I threw it up on GitHub:

Any thoughts on optimization are welcome!


Here's a minimal Settings class that handles defaults, fetch, and store on top of Datastore.


function Settings:init(default_settings)
	self.defaults = default_settings or {}
	self.settings = nil

function Settings:set(k, v)
	self.settings[k] = v

function Settings:get(k)
	return self.settings[k]

function Settings:save()
	playdate.datastore.write(self.settings, "settings", true)

function Settings:load()
	self.settings = table.deepcopy(self.defaults)
	local current_settings = playdate.datastore.read("settings") or {}
	for k, v in pairs(current_settings) do
		self.settings[k] = v

An example of how I use it:

-- main.lua

-- I like to keep my settings keys global and descriptive.
SettingKeys = {
  helpEnabled = "help enabled",
  deaths = "death count"

-- Create a global settings object with default values for keys.
settings = Settings({
  [SettingKeys.helpEnabled] = true,
  [SettingKeys.deaths] = 0

-- example.lua
playdate.getSystemMenu():addCheckmarkMenuItem("help", settings:get(SettingKeys.helpEnabled), function(enabled)
  settings:set(SettingKeys.helpEnabled, enabled)


Apologies for the cross-post, but after sharing about a visual debugging tool that I put together I was reminded of this thread and realized it would be a handy place for others to find it, so I'll just drop the link:

1 Like

Thanks for that trick! It's a bit less of a general utility function this way, but you can take the wrapper up one level and use table calling syntax to make it a touch cleaner:

-- craft a well-formed pattern from a list of binary strings
function BitPattern (binaryRows)
    pattern = {}
    for i, binary in ipairs(binaryRows) do
        pattern[i] = tonumber(binary, 2)
    return pattern

local BP = BitPattern

gfx.setPattern( BP {

Okay, one more extension of that same idea…

I don't use alpha channels for patterns often, but I didn't like that they took up so much vertical real estate in the file. This version automatically swizzles the inputs to enable placing the pattern and alpha channel definitions side by side, like so:

gfx.setPattern( BitPattern {
    -- PTTRN        ALPHA
    '10101010',  '00010000',
    '01010101',  '00111000',
    '10101010',  '01111100',
    '01010101',  '11111110',
    '10101010',  '01111100',
    '01010101',  '00111000',
    '10101010',  '00010000',
    '01010101',  '00000000',

This keeps things more compact, and I also find it easier to make sense of since the pattern and alpha channel rows can be compared side-by-side. Here's a function which supports patterns with or without alpha. It's highly specialized to 8x8 patterns, of course, but pretty convenient:

function BitPattern(binaryRows)
    local hasAlpha = #binaryRows == 16
    local pattern = {}
    for i, binaryRow in ipairs(binaryRows) do
        if hasAlpha then
            -- swizzle the rows to produce independent channels from interleaved inputs
            pattern[i//2 + (i % 2 == 0 and 8 or 1)] = tonumber(binaryRow, 2)
            -- no alpha channel, nothing to swizzle
            pattern[i] = tonumber(binaryRow, 2)
    return pattern