Image Functions

Functions for loading and rendering images.

Image Loading

loadImage

Load an image from a URL and associate it with an ID for later drawing.


loadImage(imageId, url)

Parameter	Type	Required	Description
imageId	string	Yes	Unique identifier for this image
url	string	Yes	URL of the image to load

Example:


-- Load images during initialization
loadImage("player", "/plugins/my-plugin/player.png")
loadImage("enemy", "/plugins/my-plugin/enemy.png")
 
-- Later, draw them
drawImage("player", 100, 100, 32, 32)
drawImage("enemy", 200, 100, 32, 32)

preloadImage

Preload an image from a URL. Returns a Promise that resolves when the image is loaded.


preloadImage(imageUrl)

Parameter	Type	Required	Description
imageUrl	string	Yes	URL of the image to preload

Returns: Promise<void> - Resolves when image is loaded

Image Drawing

drawImage

Draw an image with optional transforms. This is a unified function that supports all image operations.


drawImage(imageId, x, y, width?, height?, alpha?, angle?, sourceX?, sourceY?, sourceWidth?, sourceHeight?, centerX?, centerY?)

Parameter	Type	Required	Default	Description
imageId	string	Yes	-	Image ID (from loadImage)
x	number	Yes	-	X position to draw at
y	number	Yes	-	Y position to draw at
width	number	No	original	Width to draw
height	number	No	original	Height to draw
alpha	number	No	1.0	Transparency (0.0-1.0)
angle	number	No	0	Rotation angle in radians
sourceX	number	No	0	Source X for cropping
sourceY	number	No	0	Source Y for cropping
sourceWidth	number	No	full	Source width for cropping
sourceHeight	number	No	full	Source height for cropping
centerX	number	No	width/2	Rotation center X
centerY	number	No	height/2	Rotation center Y

Example:


-- Simple draw
drawImage("player", 100, 100)
 
-- Draw with size
drawImage("player", 100, 100, 64, 64)
 
-- Draw with transparency
drawImage("player", 100, 100, 64, 64, 0.5)
 
-- Draw rotated (45 degrees)
drawImage("player", 100, 100, 64, 64, 1.0, math.pi / 4)
 
-- Draw a portion of a spritesheet
drawImage("tileset", 100, 100, 32, 32, 1.0, 0, 0, 0, 32, 32)

Complete Image Example


-- Sprite display example
print("Loading sprites...")
 
-- Load images
loadImage("player", "/plugins/my-plugin/player.png")
loadImage("tileset", "/plugins/my-plugin/tiles.png")
loadImage("background", "/plugins/my-plugin/bg.jpg")
 
-- Create widget
local widget = createWidget({
  type = "canvas",
  title = "Sprite Display",
  width = 400,
  height = 300
})
 
local function draw()
  -- Draw background
  drawImage("background", 0, 0, 400, 300)
 
  -- Draw a tile from the tileset (tile at row 2, column 3, 32x32 tiles)
  local tileX = 3 * 32
  local tileY = 2 * 32
  drawImage("tileset", 50, 50, 64, 64, 1.0, 0, tileX, tileY, 32, 32)
 
  -- Draw player with transparency
  drawImage("player", 100, 100, 48, 48, 0.9)
 
  -- Draw rotated player (90 degrees)
  drawImage("player", 200, 100, 48, 48, 1.0, math.pi / 2)
end
 
registerWidgetEvent(widget, "resize", function() draw() end)
 
function init()
  draw()
end
 
print("Sprites loaded!")