Drawing
cls / clearScreen
Clear the screen. With no argument the screen becomes colour 0. Pass a palette index to clear to that colour. clearScreen is another name for cls.
- cls() -> void
- cls(colorIndex) -> void
- clearScreen() -> void
- clearScreen(colorIndex) -> void
Parameters
- colorIndex — Palette color to use.
Returns
- void — No return value.
Examples
-- Clear the screen to colour 0.
cls()
-- Clear the screen to palette colour 8.
cls(8)
-- clearScreen is another name for cls.
clearScreen(8)getPixel
Read the screen framebuffer color index at world coordinates.
- getPixel(x, y) -> int
Parameters
- x — World-space X in pixels.
- y — World-space Y in pixels.
Returns
- int
Examples
-- Read the colour at world position (10, 20).
local color = getPixel(10, 20)drawPixel
Draw a pixel in world coordinates; defaults to the current draw color.
- drawPixel(x, y [, colorIndex]) -> void
Parameters
- x — World-space X in pixels.
- y — World-space Y in pixels.
- [colorIndex] — Optional color; if omitted, uses the current draw color.
Returns
- void — No return value.
Examples
-- Draw one pixel at (10, 20) in the current colour.
drawPixel(10, 20)
-- Draw one pixel at (10, 20) in colour 7.
drawPixel(10, 20, 7)drawPixelScreen
Draw a pixel without camera offset (useful for UI overlays).
- drawPixelScreen(x, y [, colorIndex]) -> void
Parameters
- x — Screen X in pixels (ignores the camera; good for UI).
- y — Screen Y in pixels (ignores the camera; good for UI).
- [colorIndex] — Optional color; if omitted, uses the current draw color.
Returns
- void — No return value.
Examples
-- Draw a pixel at screen position (4, 4). The camera does not move it.
drawPixelScreen(4, 4, 7)drawText
Render bitmap text at the given position and scale. Uses the game custom font from the Font Editor when present (variable glyph widths, optional lowercase, solid or sprite mode). Solid fonts tint with colorIndex; sprite fonts use palette pixel colours and ignore colorIndex. Without a custom font, text is uppercased on the built-in 5×5 font. U+000A (`\n`) starts a new line; line height is font height plus advance gap (built-in: 6×size pixels). `text` may be a number; it is shown with up to 3 decimal places (trailing zeros trimmed).
- drawText(text, x, y [, colorIndex [, size]]) -> void
Parameters
- text — Text to draw.
- x — World-space X in pixels.
- y — World-space Y in pixels.
- [colorIndex] — Optional color; if omitted, uses the current draw color.
- [size] — Optional scale; omit for default size.
Returns
- void — No return value.
Examples
-- Draw the word 'Hi' at (8, 8).
drawText("Hi", 8, 8)
-- Draw 'Hi' in colour 7, at twice the normal size.
drawText("Hi", 8, 8, 7, 2)drawLine
Draw a line segment in world coordinates.
- drawLine(x1, y1, x2, y2 [, colorIndex]) -> void
Parameters
- x1 — Start of the line, X in world pixels.
- y1 — Start of the line, Y in world pixels.
- x2 — End of the line, X in world pixels.
- y2 — End of the line, Y in world pixels.
- [colorIndex] — Optional color; if omitted, uses the current draw color.
Returns
- void — No return value.
Examples
-- Draw a line from (0, 0) to (32, 16).
drawLine(0, 0, 32, 16)
-- Draw that line in colour 7.
drawLine(0, 0, 32, 16, 7)drawRect
Draw a rectangle outline using inclusive x0/y0 to x1/y1 coordinates.
- drawRect(x0, y0, x1, y1 [, colorIndex]) -> void
Parameters
- x0 — Left edge of the rect, X in world pixels.
- y0 — Top edge of the rect, Y in world pixels.
- x1 — Right edge of the rect, X in world pixels.
- y1 — Bottom edge of the rect, Y in world pixels.
- [colorIndex] — Optional color; if omitted, uses the current draw color.
Returns
- void — No return value.
Examples
-- Draw a rectangle outline from (8, 8) to (40, 24).
drawRect(8, 8, 40, 24)
-- Draw that outline in colour 7.
drawRect(8, 8, 40, 24, 7)drawFillRect
Draw a filled rectangle using inclusive x0/y0 to x1/y1 coordinates.
- drawFillRect(x0, y0, x1, y1 [, colorIndex]) -> void
Parameters
- x0 — Left edge of the rect, X in world pixels.
- y0 — Top edge of the rect, Y in world pixels.
- x1 — Right edge of the rect, X in world pixels.
- y1 — Bottom edge of the rect, Y in world pixels.
- [colorIndex] — Optional color; if omitted, uses the current draw color.
Returns
- void — No return value.
Examples
-- Draw a filled rectangle from (8, 8) to (40, 24).
drawFillRect(8, 8, 40, 24)
-- Fill that rectangle in colour 7.
drawFillRect(8, 8, 40, 24, 7)drawCircle
Draw a circle outline in world coordinates.
- drawCircle(x0, y0, radius [, colorIndex]) -> void
Parameters
- x0 — Center of the circle, X in world pixels.
- y0 — Center of the circle, Y in world pixels.
- radius — Radius in pixels.
- [colorIndex] — Optional color; if omitted, uses the current draw color.
Returns
- void — No return value.
Examples
-- Draw a circle outline at (64, 64) with radius 10.
drawCircle(64, 64, 10)
-- Draw that outline in colour 7.
drawCircle(64, 64, 10, 7)drawFillCircle
Draw a filled circle in world coordinates.
- drawFillCircle(x0, y0, radius [, colorIndex]) -> void
Parameters
- x0 — Center of the circle, X in world pixels.
- y0 — Center of the circle, Y in world pixels.
- radius — Radius in pixels.
- [colorIndex] — Optional color; if omitted, uses the current draw color.
Returns
- void — No return value.
Examples
-- Draw a filled circle at (64, 64) with radius 10.
drawFillCircle(64, 64, 10)
-- Fill that circle in colour 7.
drawFillCircle(64, 64, 10, 7)drawOval
Draw an oval/ellipse outline bounded by the given rectangle.
- drawOval(x0, y0, x1, y1 [, colorIndex]) -> void
Parameters
- x0 — Left of the oval box, X in world pixels.
- y0 — Top of the oval box, Y in world pixels.
- x1 — Right of the oval box, X in world pixels.
- y1 — Bottom of the oval box, Y in world pixels.
- [colorIndex] — Optional color; if omitted, uses the current draw color.
Returns
- void — No return value.
Examples
-- Draw an oval outline inside the box from (8, 20) to (48, 36).
drawOval(8, 20, 48, 36)
-- Draw that outline in colour 7.
drawOval(8, 20, 48, 36, 7)drawFillOval
Draw a filled oval/ellipse bounded by the given rectangle.
- drawFillOval(x0, y0, x1, y1 [, colorIndex]) -> void
Parameters
- x0 — Left of the oval box, X in world pixels.
- y0 — Top of the oval box, Y in world pixels.
- x1 — Right of the oval box, X in world pixels.
- y1 — Bottom of the oval box, Y in world pixels.
- [colorIndex] — Optional color; if omitted, uses the current draw color.
Returns
- void — No return value.
Examples
-- Draw a filled oval inside the box from (8, 20) to (48, 36).
drawFillOval(8, 20, 48, 36)
-- Fill that oval in colour 7.
drawFillOval(8, 20, 48, 36, 7)setColor
Set the default draw color used when primitives omit an explicit color.
- setColor(colorIndex) -> void
Parameters
- colorIndex — Palette color to use.
Returns
- void — No return value.
Examples
-- Use palette colour 7 for later drawing that does not pass its own colour.
setColor(7)setFillPattern
Set a 16-bit 4x4 dither pattern used by fill primitives.
- setFillPattern(pattern) -> void
Parameters
- pattern — Fill pattern (16-bit value for the 4×4 dither).
Returns
- void — No return value.
Examples
-- Fill later shapes with this 4×4 pattern instead of a solid colour.
setFillPattern(0xA5A5)resetFillPattern
Reset the active 4x4 fill pattern to solid.
- resetFillPattern() -> void
Returns
- void — No return value.
Examples
-- Fill shapes solid again.
resetFillPattern()setPaletteRemap
Remap palette color c0 to c1 for subsequent draws (primitives, sprites, and map tiles).
- setPaletteRemap(c0, c1) -> void
Parameters
- c0 — Color to replace when drawing.
- c1 — Color to draw instead of c0.
Returns
- void — No return value.
Examples
-- Draw colour 1 as colour 8 from now on.
setPaletteRemap(1, 8)resetPaletteRemap
Reset palette remapping so each color draws as itself.
- resetPaletteRemap() -> void
Returns
- void — No return value.
Examples
-- Draw each palette colour as itself again.
resetPaletteRemap()resetColorTransparency
Reset color transparency so only color 0 is transparent.
- resetColorTransparency() -> void
Returns
- void — No return value.
Examples
-- Make only colour 0 transparent again.
resetColorTransparency()setColorTransparency
Set whether a palette index is treated as transparent when drawing (primitives, sprites, and map tiles).
- setColorTransparency(color [, transparent]) -> void
Parameters
- color — Palette color to set transparent or opaque.
- [transparent] — Optional. If false, that color is solid; if true or omitted, it is treated as transparent.
Returns
- void — No return value.
Examples
-- Treat colour 7 as transparent.
setColorTransparency(7)
-- Make colour 7 solid again.
setColorTransparency(7, false)setClip
Limit drawing to the rectangle specified in world coordinates.
- setClip(x, y, w, h) -> void
Parameters
- x — World-space X in pixels.
- y — World-space Y in pixels.
- w — Clip width in pixels.
- h — Clip height in pixels.
Returns
- void — No return value.
Examples
-- Draw only inside a 32 by 32 box at (16, 16).
setClip(16, 16, 32, 32)resetClip
Reset the clip rectangle to the full screen.
- resetClip() -> void
Returns
- void — No return value.
Examples
-- Draw on the whole screen again.
resetClip()