a Love2D 11.x simple wrapper library for rendering games with a fixed update rate and chunky pixels

canvas.lua

local floor = math.floor

local canvas = {}
canvas._version = "0.1.0"
canvas.frame, canvas.time = 0, 0
canvas.width = 240
canvas.height = floor(canvas.width / (16 / 9))
canvas.pixelPerfect = true
canvas.backgroundColor = { 0, 0, 0, 1 }
canvas.xOffset, canvas.yOffset = 0, 0

local lag, msPerUpdate = 0, 0
local width, height, xScale, yScale, topLeftX, topLeftY

function canvas.framerate(n)
  if n then
    canvas._framerate = n
    msPerUpdate = 1 / n
  end
  return canvas._framerate
end

canvas.framerate(60)

local function scaleX(x) return (x-topLeftX)/xScale end
local function scaleY(y) return (y-topLeftY)/yScale end

function canvas.getMouseX() return scaleX(love.mouse.getX()) end

function canvas.getMouseY() return scaleY(love.mouse.getY()) end

function canvas.getMousePosition() return canvas.getMouseX(), canvas.getMouseY() end

local function applyIf(f, ...) if f then return f(...) end return end

function love.mousepressed(x, y, ...) applyIf(canvas.mousepressed, scaleX(x), scaleY(y), ...) end
function love.mousemoved(x, y, dx, dy, ...) applyIf(canvas.mousemoved, scaleX(x), scaleY(y), scaleX(dx), scaleY(dy), ...) end
function love.mousereleased(x, y, ...) applyIf(canvas.mousereleased, scaleX(x), scaleY(y), ...) end

local function resize(w, h)
  width, height = w, h
  xScale, yScale = w / canvas.width, h / canvas.height
  if xScale < yScale then yScale = xScale else xScale = yScale end
  if canvas.pixelPerfect then
    xScale, yScale = floor(xScale), floor(yScale)
  end
  topLeftX, topLeftY = (width - canvas.width * xScale) / 2, (height - canvas.height * yScale) / 2
end

function love.load(...)
  canvas._canvas = love.graphics.newCanvas(canvas.width, canvas.height)
  ---@diagnostic disable-next-line: missing-parameter
  canvas._canvas:setFilter "nearest"
  resize(love.graphics.getDimensions())
  love.window.updateMode(width, height, {
    minwidth = canvas.width, minheight = canvas.height,
  })
  applyIf(canvas.load, ...)
end

love.resize = resize

local delta = 0
function love.update(dt)
  delta = dt
  lag = lag + dt
  while lag >= msPerUpdate do
    applyIf(canvas.update)
    lag = lag - msPerUpdate
  end
end

function love.draw()
  if canvas.draw then
    love.graphics.push "all"
    love.graphics.setCanvas(canvas._canvas)
    love.graphics.clear(love.graphics.getBackgroundColor())
    canvas.draw(lag / msPerUpdate)
    love.graphics.setCanvas()
    love.graphics.pop()
  end

  love.graphics.clear(canvas.backgroundColor)
  love.graphics.translate(canvas.xOffset, canvas.yOffset)
  love.graphics.draw(canvas._canvas, topLeftX, topLeftY, 0, xScale, yScale)

  canvas.time = canvas.time + delta
  canvas.frame = canvas.frame + 1
end

return canvas

-- Copyright (c) 2024 @thacuber2a03
--
-- Permission is hereby granted, free of charge, to any person obtaining a copy
-- of this software and associated documentation files (the "Software"), to deal
-- in the Software without restriction, including without limitation the rights
-- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-- copies of the Software, and to permit persons to whom the Software is
-- furnished to do so, subject to the following conditions:
--
-- The above copyright notice and this permission notice shall be included in all
-- copies or substantial portions of the Software.
--
-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-- SOFTWARE.

usage

require the library, and then define the callbacks. the library will do the rest.

API

canvas.load(arg, unfilteredArg)/canvas.update()/canvas.draw(renderAlpha)/canvas.mouse*(...)

canvas' callbacks. you don't need to register them with any function, and canvas
already defines the underlying Love2D callbacks, so you just need to define these.

canvas.frame

the currently rendering frame.

canvas.time

time since the start of the game, in seconds

canvas.width/canvas.height

width and height of the virtual canvas. can only be set once at the start of the file.
defaults: 240/math.floor(canvas.width / (16/9))
16:9 aspect ratio, 240px wide (240x135, TIC-80's resolution -1px of height)

canvas.pixelPerfect

whether to render at a pixel-perfect resolution; fractional scaling will not be performed.
default: true

canvas.backgroundColor

a 4-field table that specifies the color the screen gets painted to before the virtual canvas is drawn.
default: {0, 0, 0, 1} (a black background)

canvas.framerate([n])

sets or gets the rate at which the update function gets called, in frames.
default framerate: 60

canvas.getMouseX()/canvas.getMouseY()

get the X/Y coordinate of the mouse adjusted to be relative to the scale and position of the canvas.

canvas.getMousePosition()

shorthand for canvas.getMouseX(), canvas.getMouseY()

canvas.xOffset/canvas.yOffset

set the x and y offsets of the canvas relative to the center of the window in pixels.
useful for fullscreen effects like screenshakes.
the canvas.getMouse*() functions are not affected by this offset.

canvas._version

the current version of the library as a semver string.

example code

local canvas = require 'canvas'

function canvas.load()
end

function love.keypressed(k)
  if k == "escape" then love.event.quit() end
end

function canvas.update()
end

function canvas.draw()
  love.graphics.clear(0.1, 0.1, 0.1, 1)

  love.graphics.translate(canvas.width / 3, canvas.height / 2)
  love.graphics.circle('line',
    10 * math.sin(canvas.time * math.pi * 2),
    10 * math.cos(canvas.time * math.pi * 1.5),
    10
  )

  love.graphics.translate(canvas.width / 3, 0)
  love.graphics.rotate(canvas.time * math.pi)
  love.graphics.rectangle('line', -10, -10, 20, 20)
end

this will clear the canvas with a shade of gray, draw a moving circle at the left side and a rotating rectangle on the right side.

meta file for ease of use with sumneko_lua:

---@meta

---a Love2D wrapper library for making games with a fixed update rate and chunky pixels.
local canvas = {}

---define this callback to run code after initializing the virtual canvas.
---*don't define `love.load`!!!*
---@type fun(arg: string[], unfilteredArg: string[])
canvas.load = nil

---define this callback to run code every frame.
---*don't define `love.update`!!!*
---@type fun()
canvas.update = nil

---define this callback to draw stuff to the virtual canvas.
---*don't define `love.draw`!!!*
---@type fun(renderAlpha: number)
canvas.draw = nil

---define this callback to detect a mouse press event.
---*don't define love.mousepressed!!!*
---@type fun(x: number, y: number, button: integer, istouch: boolean, presses: integer)
canvas.mousepressed = nil

---define this callback to detect a mouse move event.
---*don't define love.mousemoved!!!*
---@type fun(x: number, y: number, dx: number, dy: number, istouch: boolean)
canvas.mousemoved = nil

---define this callback to detect a mouse release event.
---*don't define love.mousereleased!!!*
---@type fun(x: integer, y: integer, button: integer, istouch: boolean, presses: integer)
canvas.mousereleased = nil

---the currently rendering frame.
---@type integer
canvas.frame = 0

---the time passed since the start of the game in seconds.
---@type number
canvas.time = 0

---the width of the virtual canvas.
---can only be set once at the start of the file.
---@type integer
canvas.width = 240

---the height of the virtual canvas.
---can only be set once at the start of the file.
---@type integer
canvas.height = 240

---the X offset of the canvas relative to the window center, in pixels.
---@type number
canvas.xOffset = 0

---the Y offset of the canvas relative to the window center, in pixels.
---@type number
canvas.yOffset = 0

---whether to render at a pixel-perfect resolution;
---fractional scaling will not be performed.
canvas.pixelPerfect = true

---a 4-field array-like table that specifies the color the screen gets painted to before the virtual canvas is drawn.
---@type number[]
canvas.backgroundColor = { 0, 0, 0, 1 }

---sets/gets the rate at which the update function gets called, in frames.
---default framerate: `60`
---@param n integer?
---@return integer
function canvas.framerate(n) end

---returns the X coordinate of the mouse, adjusted to be relative to the position
---and scale of the canvas.
---@return number
function canvas.getMouseX() end

---returns the Y coordinate of the mouse, adjusted to be relative to the position
---and scale of the canvas.
---@return number
function canvas.getMouseY() end

---shorthand for `getMouseX(), getMouseY()`.
---@return mx number, my number
function canvas.getMousePosition() end

---the current version of the library as a [semver](https://semver.org/) string.
---@type string
canvas._version = nil

return canvas

changelog

format: dd/mm/yyyy

10/11/2024:

• override love.mouse* callbacks

08/11/2024:

• initial release
• limit the maximum size of the window to the maximum size of the virtual canvas
• add getMouseX(), getMouseY(), getMousePosition(), canvas.xOffset and canvas.yOffset
• optimize getMouse*() and virtual canvas drawing