Images, image tables & tilemaps

Images (STI and other formats handled by the native loader), image tables (STA), tilemaps, nine-slices, animation helpers and the Tiled loader.

Conventions on every page: Availability says whether a symbol exists on the console BIOS, the emulator, or both. c8b and C8B are the same table.

Contents#

• Images
  • c8b.graphics.image.new
  • c8b.graphics.image:draw
  • c8b.graphics.image:drawWithSourceRect
  • c8b.graphics.image:drawCentered
  • c8b.graphics.image:drawAnchored
  • c8b.graphics.image:drawScaled
  • c8b.graphics.image:drawScaledWithFlip
  • c8b.graphics.image:drawRotated
  • c8b.graphics.image:drawRotatedScaled
  • c8b.graphics.image:drawTiled
  • c8b.graphics.image:drawTiledLarge
  • c8b.graphics.image:drawScaledTiledLarge
  • c8b.graphics.image:drawFaded
  • c8b.graphics.image:fadedImage
  • c8b.graphics.image:setBilinearFilter
  • c8b.graphics.image:getBilinearFilter
  • c8b.graphics.image:clear
  • c8b.graphics.image:clearWithAlpha
  • c8b.graphics.image:getSize
  • c8b.graphics.image:getWidth
  • c8b.graphics.image:getHeight
  • c8b.graphics.image:getNativeRef
  • c8b.graphics.image:free
  • c8b.graphics.image:getPixelColor
  • c8b.graphics.image:getPixelAlpha
  • c8b.graphics.image:getBytesPerPixel
• Aliases
  • Image
  • ImageTable
• Masks
  • c8b.graphics.image:drawWithMask
  • c8b.graphics.image:setMaskImage
  • c8b.graphics.image:getMaskImage
  • c8b.graphics.image:hasMask
  • c8b.graphics.image:addMask
  • c8b.graphics.image:addMaskL4
  • c8b.graphics.image:getMaskL4
  • c8b.graphics.image:hasMaskL4
  • c8b.graphics.image:fillMaskL4Rect
  • c8b.graphics.image:clearMaskL4
  • c8b.graphics.image:markMaskDirty
  • c8b.graphics.image:beginMaskUpdate
  • c8b.graphics.image:endMaskUpdate
• Dither constants
  • c8b.graphics.image.kDitherTypeNone
  • c8b.graphics.image.kDitherTypeDiagonalLine
  • c8b.graphics.image.kDitherTypeVerticalLine
  • c8b.graphics.image.kDitherTypeHorizontalLine
  • c8b.graphics.image.kDitherTypeScreen
  • c8b.graphics.image.kDitherTypeBayer2x2
  • c8b.graphics.image.kDitherTypeBayer4x4
  • c8b.graphics.image.kDitherTypeBayer8x8
  • c8b.graphics.image.kDitherTypeFloydSteinberg
  • c8b.graphics.image.kDitherTypeBurkes
  • c8b.graphics.image.kDitherTypeAtkinson
• Image tables
  • c8b.graphics.imagetable.new
  • c8b.graphics.imagetable:getImage
  • c8b.graphics.imagetable:getLength
  • c8b.graphics.imagetable:getSize
  • c8b.graphics.imagetable:setUseProxyImage
  • c8b.graphics.imagetable:getNativeRef
  • c8b.graphics.imagetable:free
• Image table frames (objects returned by imagetable:getImage)
  • imageFrame:draw
  • imageFrame:drawScaled
  • imageFrame:drawScaledWithFlip
  • imageFrame:drawRotated
  • imageFrame:drawCentered
  • imageFrame:drawAnchored
  • imageFrame:getSize
  • imageFrame:getWidth
  • imageFrame:getHeight
  • imageFrame:getNativeRef
  • imageFrame:free
• Tilemaps
  • c8b.graphics.tilemap.new
  • c8b.graphics.nativeTilemap.new
  • c8b.graphics.nativeTilemap.removeAll
  • Tilemap.new
  • Tilemap.removeAll
  • Tilemap:setImageTable
  • Tilemap:getImageTable
  • Tilemap:setTiles
  • Tilemap:setTileAtPosition
  • Tilemap:getTileAtPosition
  • Tilemap:setSize
  • Tilemap:getSize
  • Tilemap:getTileWidth
  • Tilemap:getTileHeight
  • Tilemap:getTileSize
  • Tilemap:getPixelSize
  • Tilemap:draw
  • Tilemap:drawIgnoringOffset
  • Tilemap:setIgnoresDrawOffset
  • Tilemap:getIgnoresDrawOffset
  • Tilemap:setParallax
  • Tilemap:getParallax
  • Tilemap:getCollisionRects
• Nine-slice
  • c8b.graphics.nineSlice.new
  • NineSlice.new
  • NineSlice:drawInRect
  • NineSlice:draw
  • NineSlice:getMinSize
  • NineSlice:getSize
• Animation loops
  • c8b.graphics.animation.loop.new
  • AnimationLoop.new
  • AnimationLoop:frame
  • AnimationLoop:image
  • AnimationLoop:draw
  • AnimationLoop:drawCentered
  • AnimationLoop:ended
  • AnimationLoop:isValid
  • AnimationLoop:pause
  • AnimationLoop:resume
  • AnimationLoop:reset
  • AnimationLoop:setDelay
  • AnimationLoop:getDelay
  • AnimationLoop:setLooping
  • AnimationLoop:isLooping
  • AnimationLoop:getFrameCount
• Animators
  • c8b.graphics.animator.new
  • Animator.new
  • Animator.defaultEasing
  • Animator:currentValue
  • Animator:ended
  • Animator:reset
  • Animator:progress
• Tiled (TMJ) loader — require("core8bit.utils.tmj_loader")
  • TmjLoader.load
  • TmjLoader.findLayer
  • TmjLoader.findLayersByType
  • TmjLoader.findObjectByType
  • TmjLoader.findObjectByName
  • TmjLoader.findObjectsByType
  • TmjLoader.getTilesets
  • TmjLoader.createTilemap
  • TmjLoader.getMapPixelSize
• Low-level bindings (C8B.*)
  • C8B.Image_new
  • C8B.Image_draw
  • C8B.Image_free
  • C8B.Image_load
  • C8B.Image_clear
  • C8B.Image_addMask
  • C8B.Image_getSize
  • C8B.Image_hasMask
  • C8B.ImageTable_new
  • C8B.Image_getWidth
  • C8B.ImageTable_free
  • C8B.Image_addMaskL4
  • C8B.Image_drawFaded
  • C8B.Image_drawTiled
  • C8B.Image_getHeight
  • C8B.Image_getMaskL4
  • C8B.Image_hasMaskL4
  • C8B.Image_drawScaled
  • C8B.Image_fadedImage
  • C8B.Image_clearMaskL4
  • C8B.Image_drawRotated
  • C8B.Image_drawWithFlip
  • C8B.Image_drawWithMask
  • C8B.Image_getMaskImage
  • C8B.Image_setMaskImage
  • C8B.NativeTilemap_draw
  • C8B.ImageTable_getImage
  • C8B.Image_endMaskUpdate
  • C8B.Image_getPixelAlpha
  • C8B.Image_getPixelColor
  • C8B.Image_markMaskDirty
  • C8B.Image_newMaskBuffer
  • C8B.ImageTable_drawTiles
  • C8B.ImageTable_getLength
  • C8B.Image_fillMaskL4Rect
  • C8B.NativeTilemap_create
  • C8B.Image_beginMaskUpdate
  • C8B.NativeTilemap_getTile
  • C8B.NativeTilemap_setTile
  • C8B.Image_drawRotatedScaled
  • C8B.Image_getBilinearFilter
  • C8B.Image_setBilinearFilter
  • C8B.Image_drawScaledWithFlip
  • C8B.Image_drawWithSourceRect
  • C8B.Image_drawRotatedScaledEx
  • C8B.Image_newWithColorAndAlpha
  • C8B.NativeTilemap_setImageTable
  • C8B.NativeTilemap_setTilesFromTable
  • C8B.NativeTilemap_drawIgnoringOffset

Images#

c8b.graphics.image.new#

c8b.graphics.image.new(path) | (width, height, [fillColor], [alpha])

Loads an image file (path without extension is resolved by the native loader) or creates an empty image. fillColor is RGB565 (kColorClear = transparent); alpha is 0-15 (4-bit, default 15 when a color is given). On load failure the object has width/height 0.

• Availability: Console (BIOS) and emulator
• Note: On failure it returns an empty object, not nil.

local bg = gfx.image.new("images/background")
local buf = gfx.image.new(64, 64, gfx.kColorClear)

c8b.graphics.image:draw#

image:draw(x, y, [flip])

Draws at the top-left position (floored). flip is a kImage* constant or "flipX"/"flipY"/"flipXY". Honours the image draw mode and draw offset.

• Availability: Console (BIOS) and emulator
• Note: To draw part of the image, use drawWithSourceRect.

c8b.graphics.image:drawWithSourceRect#

image:drawWithSourceRect(x, y, srcX, srcY, srcW, srcH, [flip])

Draws part of the image.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:drawCentered#

image:drawCentered(x, y, [flip])

Draws centred on (x, y).

• Availability: Console (BIOS) and emulator

c8b.graphics.image:drawAnchored#

image:drawAnchored(x, y, ax, ay, [flip])

Draws with anchor (ax, ay) in 0..1.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:drawScaled#

image:drawScaled(x, y, scale, [yscale], [flip])

Draws scaled (nearest neighbour unless bilinear filtering is on).

• Availability: Console (BIOS) and emulator

c8b.graphics.image:drawScaledWithFlip#

image:drawScaledWithFlip(x, y, scaleX, [scaleY], [flip])

Scaled draw with flip.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:drawRotated#

image:drawRotated(x, y, angle, [scale], [yscale])

Draws centred on (x, y) rotated by angle degrees.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:drawRotatedScaled#

image:drawRotatedScaled(x, y, angle, scaleX, [scaleY], [centerX], [centerY], [flip])

Rotated and scaled draw with a custom pivot (default image centre).

• Availability: Console (BIOS) and emulator

c8b.graphics.image:drawTiled#

image:drawTiled(x, y, width, height, [flip])

Tiles the image over a rectangle.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:drawTiledLarge#

image:drawTiledLarge(x, y, [flip])

Draws a large image in chunks sized for the 64 KB fast buffer (falls back to draw for small images).

• Availability: Console (BIOS) and emulator

c8b.graphics.image:drawScaledTiledLarge#

image:drawScaledTiledLarge(x, y, scaleX, [scaleY])

Scaled variant of drawTiledLarge.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:drawFaded#

image:drawFaded(x, y, alpha, [ditherType], [useRgbBlend])

Draws with a dither or RGB-blend fade. ditherType defaults to kDitherTypeBayer4x4.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:fadedImage#

image:fadedImage(alpha, [ditherType], [useRgbBlend])

Returns a new faded image.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:setBilinearFilter#

image:setBilinearFilter(enabled)

Smooth filtering for scaled drawing.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:getBilinearFilter#

image:getBilinearFilter()

Filtering flag.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.graphics.image:clear#

image:clear(color)

Fills the image with an RGB565 color (default 0).

• Availability: Console (BIOS) and emulator

c8b.graphics.image:clearWithAlpha#

image:clearWithAlpha(color, alpha)

Fills the image with color and 4-bit alpha.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:getSize#

image:getSize()

Image size.

• Returns: width, height
• Availability: Console (BIOS) and emulator

c8b.graphics.image:getWidth#

image:getWidth()

Width (0 for an empty object).

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.graphics.image:getHeight#

image:getHeight()

Height.

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.graphics.image:getNativeRef#

image:getNativeRef()

Native image pointer (light userdata).

• Availability: Console (BIOS) and emulator

c8b.graphics.image:free#

image:free()

Frees the native image now (otherwise freed on garbage collection).

• Availability: Console (BIOS) and emulator

c8b.graphics.image:getPixelColor#

image:getPixelColor(x, y)

RGB565 color at a pixel.

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.graphics.image:getPixelAlpha#

image:getPixelAlpha(x, y)

Alpha at a pixel.

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.graphics.image:getBytesPerPixel#

image:getBytesPerPixel()

Always returns 2.

• Returns: 2
• Availability: Console (BIOS) and emulator

Aliases#

Image#

Image

Global Image class; c8b.graphics.image falls back to it, so gfx.image.drawFaded(img, ...) style calls work.

• Availability: Console (BIOS) and emulator

ImageTable#

ImageTable

Global ImageTable class; c8b.graphics.imagetable falls back to it.

• Availability: Console (BIOS) and emulator

Masks#

c8b.graphics.image:drawWithMask#

image:drawWithMask(x, y, mask)

Draws using another image as mask.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:setMaskImage#

image:setMaskImage(mask, [ownsMask])

Attaches a mask image.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:getMaskImage#

image:getMaskImage()

Mask as an Image (owned by this image), or nil.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:hasMask#

image:hasMask()

Whether a mask is attached.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.graphics.image:addMask#

image:addMask([opaque=true])

Creates a mask and returns it as an Image.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:addMaskL4#

image:addMaskL4([opaque=true])

Creates a 4-bit (L4) mask; draw into it with lockFocus and call markMaskDirty.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:getMaskL4#

image:getMaskL4()

Existing L4 mask as an Image, or nil.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:hasMaskL4#

image:hasMaskL4()

Whether an L4 mask exists.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.graphics.image:fillMaskL4Rect#

image:fillMaskL4Rect(x, y, w, h, [value=15])

Fills a rect of the L4 mask (0 transparent .. 15 opaque).

• Availability: Console (BIOS) and emulator

c8b.graphics.image:clearMaskL4#

image:clearMaskL4([value=15])

Fills the whole L4 mask.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:markMaskDirty#

image:markMaskDirty()

Re-merges the L4 mask after drawing into it.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:beginMaskUpdate#

image:beginMaskUpdate()

Defers dirty marking for batches of mask edits.

• Availability: Console (BIOS) and emulator

c8b.graphics.image:endMaskUpdate#

image:endMaskUpdate()

Ends a batch; marks the mask dirty if it changed.

• Availability: Console (BIOS) and emulator

Dither constants#

c8b.graphics.image.kDitherTypeNone#

c8b.graphics.image.kDitherTypeNone = 0

Dither type for setDitherPattern/drawFaded.

• Availability: Console (BIOS) and emulator

c8b.graphics.image.kDitherTypeDiagonalLine#

c8b.graphics.image.kDitherTypeDiagonalLine = 1

Dither type for setDitherPattern/drawFaded.

• Availability: Console (BIOS) and emulator

c8b.graphics.image.kDitherTypeVerticalLine#

c8b.graphics.image.kDitherTypeVerticalLine = 2

Dither type for setDitherPattern/drawFaded.

• Availability: Console (BIOS) and emulator

c8b.graphics.image.kDitherTypeHorizontalLine#

c8b.graphics.image.kDitherTypeHorizontalLine = 3

Dither type for setDitherPattern/drawFaded.

• Availability: Console (BIOS) and emulator

c8b.graphics.image.kDitherTypeScreen#

c8b.graphics.image.kDitherTypeScreen = 4

Dither type for setDitherPattern/drawFaded.

• Availability: Console (BIOS) and emulator

c8b.graphics.image.kDitherTypeBayer2x2#

c8b.graphics.image.kDitherTypeBayer2x2 = 5

Dither type for setDitherPattern/drawFaded.

• Availability: Console (BIOS) and emulator

c8b.graphics.image.kDitherTypeBayer4x4#

c8b.graphics.image.kDitherTypeBayer4x4 = 6

Dither type for setDitherPattern/drawFaded.

• Availability: Console (BIOS) and emulator

c8b.graphics.image.kDitherTypeBayer8x8#

c8b.graphics.image.kDitherTypeBayer8x8 = 7

Dither type for setDitherPattern/drawFaded.

• Availability: Console (BIOS) and emulator

c8b.graphics.image.kDitherTypeFloydSteinberg#

c8b.graphics.image.kDitherTypeFloydSteinberg = 8

Dither type for setDitherPattern/drawFaded.

• Availability: Console (BIOS) and emulator

c8b.graphics.image.kDitherTypeBurkes#

c8b.graphics.image.kDitherTypeBurkes = 9

Dither type for setDitherPattern/drawFaded.

• Availability: Console (BIOS) and emulator

c8b.graphics.image.kDitherTypeAtkinson#

c8b.graphics.image.kDitherTypeAtkinson = 10

Dither type for setDitherPattern/drawFaded.

• Availability: Console (BIOS) and emulator

Image tables#

c8b.graphics.imagetable.new#

c8b.graphics.imagetable.new(path)

Loads an animation/tile sheet (STA format). Returns nil if loading fails.

• Availability: Console (BIOS) and emulator
• Note: Assets must be converted to STA.

local frames = gfx.imagetable.new("images/hero-run")
frames:getImage(1):draw(10, 10)

c8b.graphics.imagetable:getImage#

imagetable:getImage(index)

Returns frame index (1-based) as a frame object, or nil when out of range. Frames are created lazily and cached; each frame keeps its table alive.

• Availability: Console (BIOS) and emulator

c8b.graphics.imagetable:getLength#

imagetable:getLength()

Number of frames.

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.graphics.imagetable:getSize#

imagetable:getSize()

Returns the frame count (not a cell grid size).

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.graphics.imagetable:setUseProxyImage#

imagetable:setUseProxyImage(flag)

When true, getImage returns one shared frame object that is retargeted on every call (less garbage, but do not keep references).

• Availability: Console (BIOS) and emulator

c8b.graphics.imagetable:getNativeRef#

imagetable:getNativeRef()

Native pointer.

• Availability: Console (BIOS) and emulator

c8b.graphics.imagetable:free#

imagetable:free()

Frees the native table now.

• Availability: Console (BIOS) and emulator

Image table frames (objects returned by imagetable:getImage)#

imageFrame:draw#

frame:draw(x, y, [flip])

Draws the frame. Any other Image method (drawFaded, drawTiled, getMaskImage, ...) is forwarded to the Image class.

• Availability: Console (BIOS) and emulator

imageFrame:drawScaled#

frame:drawScaled(x, y, scale, [yscale])

Scaled draw.

• Availability: Console (BIOS) and emulator

imageFrame:drawScaledWithFlip#

frame:drawScaledWithFlip(x, y, scaleX, scaleY, flip)

Scaled draw with flip.

• Availability: Console (BIOS) and emulator

imageFrame:drawRotated#

frame:drawRotated(x, y, angle, [scale], [yscale])

Rotated draw, centred on (x, y).

• Availability: Console (BIOS) and emulator

imageFrame:drawCentered#

frame:drawCentered(x, y, [flip])

Centred draw.

• Availability: Console (BIOS) and emulator

imageFrame:drawAnchored#

frame:drawAnchored(x, y, ax, ay, [flip])

Anchored draw.

• Availability: Console (BIOS) and emulator

imageFrame:getSize#

frame:getSize()

Frame size (width, height).

• Availability: Console (BIOS) and emulator

imageFrame:getWidth#

frame:getWidth()

Frame width.

• Availability: Console (BIOS) and emulator

imageFrame:getHeight#

frame:getHeight()

Frame height.

• Availability: Console (BIOS) and emulator

imageFrame:getNativeRef#

frame:getNativeRef()

Native frame pointer.

• Availability: Console (BIOS) and emulator

imageFrame:free#

frame:free()

No-op: frames belong to their table.

• Availability: Console (BIOS) and emulator

Tilemaps#

c8b.graphics.tilemap.new#

c8b.graphics.tilemap.new([width], [height], [tileWidth=16], [tileHeight=16])

Creates a native-backed Tilemap. The native map is created when width and height are > 0 or on the first setTiles.

• Availability: Console (BIOS) and emulator

local tm = gfx.tilemap.new()
tm:setImageTable(tiles)
tm:setTiles(data, 40)
tm:draw(0, 0)

c8b.graphics.nativeTilemap.new#

c8b.graphics.nativeTilemap.new(width, height, tileW, tileH)

Backwards-compatible alias table; same constructor as tilemap.new.

• Availability: Console (BIOS) and emulator

c8b.graphics.nativeTilemap.removeAll#

c8b.graphics.nativeTilemap.removeAll()

Same function as Tilemap.removeAll.

• Availability: Console (BIOS) and emulator

Tilemap.new#

Tilemap.new(width, height, tileWidth, tileHeight) | Tilemap(...)

Global Tilemap class constructor (same as c8b.graphics.tilemap.new).

• Availability: Console (BIOS) and emulator

Tilemap.removeAll#

Tilemap.removeAll()

Drops the native references of every tilemap (called by sprite.removeAll and on game unload).

• Availability: Console (BIOS) and emulator

Tilemap:setImageTable#

tilemap:setImageTable(imagetable)

Sets the tileset.

• Availability: Console (BIOS) and emulator

Tilemap:getImageTable#

tilemap:getImageTable()

Returns the tileset.

• Availability: Console (BIOS) and emulator

Tilemap:setTiles#

tilemap:setTiles(data, width)

Copies a flat 1-based tile index array into the native map (height = ceil(#data / width)).

• Availability: Console (BIOS) and emulator

Tilemap:setTileAtPosition#

tilemap:setTileAtPosition(col, row, index)

Sets one tile.

• Availability: Console (BIOS) and emulator

Tilemap:getTileAtPosition#

tilemap:getTileAtPosition(col, row)

Gets one tile (0 when no native map).

• Returns: integer
• Availability: Console (BIOS) and emulator

Tilemap:setSize#

tilemap:setSize(width, height, [tileWidth], [tileHeight])

(Re)creates the native map with these dimensions.

• Availability: Console (BIOS) and emulator

Tilemap:getSize#

tilemap:getSize()

Size in tiles.

• Returns: width, height
• Availability: Console (BIOS) and emulator

Tilemap:getTileWidth#

tilemap:getTileWidth()

Tile width.

• Returns: integer
• Availability: Console (BIOS) and emulator

Tilemap:getTileHeight#

tilemap:getTileHeight()

Tile height.

• Returns: integer
• Availability: Console (BIOS) and emulator

Tilemap:getTileSize#

tilemap:getTileSize()

Tile size.

• Returns: width, height
• Availability: Console (BIOS) and emulator

Tilemap:getPixelSize#

tilemap:getPixelSize()

Map size in pixels.

• Returns: width, height
• Availability: Console (BIOS) and emulator

Tilemap:draw#

tilemap:draw(x, y)

Draws at (x, y) plus the draw offset scaled by the parallax factors (unless ignoring the offset).

• Availability: Console (BIOS) and emulator

Tilemap:drawIgnoringOffset#

tilemap:drawIgnoringOffset(x, y)

Draws without the draw offset.

• Availability: Console (BIOS) and emulator

Tilemap:setIgnoresDrawOffset#

tilemap:setIgnoresDrawOffset(flag)

Ignore the draw offset in draw().

• Availability: Console (BIOS) and emulator

Tilemap:getIgnoresDrawOffset#

tilemap:getIgnoresDrawOffset()

Flag.

• Returns: boolean
• Availability: Console (BIOS) and emulator

Tilemap:setParallax#

tilemap:setParallax(x, [y])

Draw-offset multipliers.

• Availability: Console (BIOS) and emulator

Tilemap:getParallax#

tilemap:getParallax()

Parallax factors.

• Returns: x, y
• Availability: Console (BIOS) and emulator

Tilemap:getCollisionRects#

tilemap:getCollisionRects([emptyIDs])

Merges solid tiles (index not 0 and not in emptyIDs) into rectangles (greedy meshing).

• Returns: array of {x, y, width, height}
• Availability: Console (BIOS) and emulator

Nine-slice#

c8b.graphics.nineSlice.new#

c8b.graphics.nineSlice.new(imagePath, innerX, innerY, innerWidth, innerHeight)

Creates a nine-slice from an image; the inner rectangle is the stretchable (tiled) area.

• Availability: Console (BIOS) and emulator

local box = gfx.nineSlice.new("ui/panel", 8, 8, 16, 16)
box:drawInRect(40, 40, 200, 100)

NineSlice.new#

NineSlice.new(imagePath, innerX, innerY, innerWidth, innerHeight)

Global class constructor (same as c8b.graphics.nineSlice.new).

• Availability: Console (BIOS) and emulator

NineSlice:drawInRect#

nineSlice:drawInRect(x, y, width, height)

Draws the nine-slice filling the rectangle (clamped to the minimum size).

• Availability: Console (BIOS) and emulator

NineSlice:draw#

nineSlice:draw(x, y, width, height)

Same function as drawInRect.

• Availability: Console (BIOS) and emulator

NineSlice:getMinSize#

nineSlice:getMinSize()

Smallest drawable size (corner sizes).

• Returns: width, height
• Availability: Console (BIOS) and emulator

NineSlice:getSize#

nineSlice:getSize()

Source image size.

• Returns: width, height
• Availability: Console (BIOS) and emulator

Animation loops#

c8b.graphics.animation.loop.new#

c8b.graphics.animation.loop.new([delay=100], imagetable, [shouldLoop=true])

Frame animation driven by c8b.getCurrentTimeMilliseconds().

• Availability: Console (BIOS) and emulator
• Note: Timing uses the wall clock: on the console without network time it counts from boot; with network time it counts from midnight and wraps at midnight.

local anim = gfx.animation.loop.new(80, frames)
anim:draw(x, y)

AnimationLoop.new#

AnimationLoop.new(delay, imagetable, shouldLoop)

Global class constructor.

• Availability: Console (BIOS) and emulator

AnimationLoop:frame#

loop:frame()

Current 1-based frame.

• Returns: integer
• Availability: Console (BIOS) and emulator

AnimationLoop:image#

loop:image()

Current frame image.

• Availability: Console (BIOS) and emulator

AnimationLoop:draw#

loop:draw(x, y, [flip])

Draws the current frame.

• Availability: Console (BIOS) and emulator

AnimationLoop:drawCentered#

loop:drawCentered(x, y, [flip])

Draws the current frame centred.

• Availability: Console (BIOS) and emulator

AnimationLoop:ended#

loop:ended()

True when a non-looping animation finished.

• Returns: boolean
• Availability: Console (BIOS) and emulator

AnimationLoop:isValid#

loop:isValid()

True when the table has frames.

• Returns: boolean
• Availability: Console (BIOS) and emulator

AnimationLoop:pause#

loop:pause()

Pauses.

• Availability: Console (BIOS) and emulator

AnimationLoop:resume#

loop:resume()

Resumes.

• Availability: Console (BIOS) and emulator

AnimationLoop:reset#

loop:reset()

Restarts from frame 1.

• Availability: Console (BIOS) and emulator

AnimationLoop:setDelay#

loop:setDelay(ms)

Frame delay.

• Availability: Console (BIOS) and emulator

AnimationLoop:getDelay#

loop:getDelay()

Frame delay.

• Returns: number
• Availability: Console (BIOS) and emulator

AnimationLoop:setLooping#

loop:setLooping(flag)

Loop flag.

• Availability: Console (BIOS) and emulator

AnimationLoop:isLooping#

loop:isLooping()

Loop flag.

• Returns: boolean
• Availability: Console (BIOS) and emulator

AnimationLoop:getFrameCount#

loop:getFrameCount()

Frame count.

• Returns: integer
• Availability: Console (BIOS) and emulator

Animators#

c8b.graphics.animator.new#

c8b.graphics.animator.new(duration, startValue, endValue, [easingFunction])

Interpolates a number over duration milliseconds (easing signature f(t, b, c, d)).

• Availability: Console (BIOS) and emulator

local a = gfx.animator.new(500, 0, 100, c8b.easingFunctions.outQuad)
local v = a:currentValue()

Animator.new#

Animator.new(duration, startValue, endValue, [easingFunction])

Global class constructor.

• Availability: Console (BIOS) and emulator

Animator.defaultEasing#

Animator.defaultEasing(t, b, c, d)

Linear easing used when none is given.

• Availability: Console (BIOS) and emulator

Animator:currentValue#

animator:currentValue()

Current interpolated value.

• Returns: number
• Availability: Console (BIOS) and emulator

Animator:ended#

animator:ended()

Whether duration has elapsed.

• Returns: boolean
• Availability: Console (BIOS) and emulator

Animator:reset#

animator:reset()

Restarts the animator.

• Availability: Console (BIOS) and emulator

Animator:progress#

animator:progress()

Progress 0..1.

• Returns: number
• Availability: Console (BIOS) and emulator

Tiled (TMJ) loader — require("core8bit.utils.tmj_loader")#

TmjLoader.load#

TmjLoader.load(path)

Reads and JSON-decodes a Tiled .tmj map (extension optional; also tries ./Assets/). Raises an error on failure. Module is not loaded by default.

• Availability: Console (BIOS) and emulator

TmjLoader.findLayer#

TmjLoader.findLayer(map, name)

Layer by name or nil. Module is not loaded by default.

• Availability: Console (BIOS) and emulator

TmjLoader.findLayersByType#

TmjLoader.findLayersByType(map, type)

Layers of a type ("tilelayer", "objectgroup"). Module is not loaded by default.

• Availability: Console (BIOS) and emulator

TmjLoader.findObjectByType#

TmjLoader.findObjectByType(map, type)

First object of a type. Module is not loaded by default.

• Availability: Console (BIOS) and emulator

TmjLoader.findObjectByName#

TmjLoader.findObjectByName(map, name)

Object by name. Module is not loaded by default.

• Availability: Console (BIOS) and emulator

TmjLoader.findObjectsByType#

TmjLoader.findObjectsByType(map, type)

All objects of a type. Module is not loaded by default.

• Availability: Console (BIOS) and emulator

TmjLoader.getTilesets#

TmjLoader.getTilesets(map)

Tileset info list {name, firstgid, tilecount, tilewidth, tileheight, image}. Module is not loaded by default.

• Availability: Console (BIOS) and emulator

TmjLoader.createTilemap#

TmjLoader.createTilemap(layer, imageTables, [tilesets])

Builds a Tilemap from a tile layer. Only a single tileset is supported: pass a single imagetable (several tilesets raise an error). Load the module with require before use.

• Availability: Console (BIOS) and emulator

TmjLoader.getMapPixelSize#

TmjLoader.getMapPixelSize(map)

Map size in pixels. Module is not loaded by default.

• Availability: Console (BIOS) and emulator

Low-level bindings (C8B.*)#

C8B.Image_new#

C8B.Image_new(width, height)

Native image binding: new.

• Returns: 1 value(s): handle, nil
• Availability: Console (BIOS) and emulator

C8B.Image_draw#

C8B.Image_draw(image, x, y)

Native image binding: draw.

• Availability: Console (BIOS) and emulator

C8B.Image_free#

C8B.Image_free(image)

Native image binding: free.

• Availability: Console (BIOS) and emulator

C8B.Image_load#

C8B.Image_load(path)

Native image binding: load.

• Returns: 1 value(s): handle, nil
• Availability: Console (BIOS) and emulator

C8B.Image_clear#

C8B.Image_clear(image, [color=0])

Native image binding: clear.

• Availability: Console (BIOS) and emulator

C8B.Image_addMask#

C8B.Image_addMask(image, opaque)

Native image binding: add mask.

• Returns: 1 value(s): handle, nil
• Availability: Console (BIOS) and emulator

C8B.Image_getSize#

C8B.Image_getSize(image)

Returns status, width, height (status is the native C8B_Image_getSize result).

• Returns: 3 value(s): integer
• Availability: Console (BIOS) and emulator

C8B.Image_hasMask#

C8B.Image_hasMask(image)

Native image binding: has mask.

• Returns: 1 value(s): boolean
• Availability: Console (BIOS) and emulator

C8B.ImageTable_new#

C8B.ImageTable_new(path)

Native image-table binding: new.

• Returns: 1 value(s): handle, nil
• Availability: Console (BIOS) and emulator

C8B.Image_getWidth#

C8B.Image_getWidth(image)

Native image binding: get width.

• Returns: 1 value(s): integer
• Availability: Console (BIOS) and emulator

C8B.ImageTable_free#

C8B.ImageTable_free(imagetable)

Native image-table binding: free.

• Availability: Console (BIOS) and emulator

C8B.Image_addMaskL4#

C8B.Image_addMaskL4(image, opaque)

Native image binding: add mask l4.

• Returns: 1 value(s): handle, nil
• Availability: Console (BIOS) and emulator

C8B.Image_drawFaded#

C8B.Image_drawFaded(image, x, y, alpha, ditherType, useRgbBlend)

Native image binding: draw faded.

• Availability: Console (BIOS) and emulator

C8B.Image_drawTiled#

C8B.Image_drawTiled(image, x, y, width, height, flip)

Native image binding: draw tiled.

• Availability: Console (BIOS) and emulator

C8B.Image_getHeight#

C8B.Image_getHeight(image)

Native image binding: get height.

• Returns: 1 value(s): integer
• Availability: Console (BIOS) and emulator

C8B.Image_getMaskL4#

C8B.Image_getMaskL4(image)

L4 mask pointer.

• Returns: 1 value(s): handle, nil
• Availability: Console (BIOS) and emulator

C8B.Image_hasMaskL4#

C8B.Image_hasMaskL4(image)

Native image binding: has mask l4.

• Returns: 1 value(s): boolean
• Availability: Console (BIOS) and emulator

C8B.Image_drawScaled#

C8B.Image_drawScaled(image, x, y, scaleX, scaleY)

Native image binding: draw scaled.

• Availability: Console (BIOS) and emulator

C8B.Image_fadedImage#

C8B.Image_fadedImage(image, alpha, ditherType, useRgbBlend)

Native image binding: faded image.

• Returns: 1 value(s): handle, nil
• Availability: Console (BIOS) and emulator

C8B.Image_clearMaskL4#

C8B.Image_clearMaskL4(image, [value=15])

Native image binding: clear mask l4.

• Availability: Console (BIOS) and emulator

C8B.Image_drawRotated#

C8B.Image_drawRotated(image, x, y, degrees)

Native image binding: draw rotated.

• Availability: Console (BIOS) and emulator

C8B.Image_drawWithFlip#

C8B.Image_drawWithFlip(image, x, y, flip)

Native image binding: draw with flip.

• Availability: Console (BIOS) and emulator

C8B.Image_drawWithMask#

C8B.Image_drawWithMask(image, x, y, maskPtr)

Native image binding: draw with mask.

• Availability: Console (BIOS) and emulator

C8B.Image_getMaskImage#

C8B.Image_getMaskImage(image)

Native image binding: get mask image.

• Returns: 1 value(s): handle, nil
• Availability: Console (BIOS) and emulator

C8B.Image_setMaskImage#

C8B.Image_setMaskImage(image, maskPtr, ownsMask)

Native image binding: set mask image.

• Availability: Console (BIOS) and emulator

C8B.NativeTilemap_draw#

C8B.NativeTilemap_draw(tilemap, x, y)

Native native tilemap binding: draw.

• Availability: Console (BIOS) and emulator

C8B.ImageTable_getImage#

C8B.ImageTable_getImage(imagetable, index)

Native image-table binding: get image.

• Returns: 1 value(s): handle, nil
• Availability: Console (BIOS) and emulator

C8B.Image_endMaskUpdate#

C8B.Image_endMaskUpdate(image)

Native image binding: end mask update.

• Availability: Console (BIOS) and emulator

C8B.Image_getPixelAlpha#

C8B.Image_getPixelAlpha(image, x, y)

Native image binding: get pixel alpha.

• Returns: 1 value(s): integer
• Availability: Console (BIOS) and emulator

C8B.Image_getPixelColor#

C8B.Image_getPixelColor(image, x, y)

Native image binding: get pixel color.

• Returns: 1 value(s): integer
• Availability: Console (BIOS) and emulator

C8B.Image_markMaskDirty#

C8B.Image_markMaskDirty(image)

Native image binding: mark mask dirty.

• Availability: Console (BIOS) and emulator

C8B.Image_newMaskBuffer#

C8B.Image_newMaskBuffer(width, height)

Creates an image intended as a mask buffer.

• Returns: 1 value(s): handle, nil
• Availability: Console (BIOS) and emulator

C8B.ImageTable_drawTiles#

C8B.ImageTable_drawTiles(imagetable, screenX, screenY, tileW, tileH, arg6, mapWidth, startCol, startRow, endCol, endRow)

Batched tile drawing: draws the cells startCol..endCol, startRow..endRow of a flat tile-index table (mapWidth columns) using this image table.

• Availability: Console (BIOS) and emulator

C8B.ImageTable_getLength#

C8B.ImageTable_getLength(imagetable)

Native image-table binding: get length.

• Returns: 1 value(s): integer
• Availability: Console (BIOS) and emulator

C8B.Image_fillMaskL4Rect#

C8B.Image_fillMaskL4Rect(image, x, y, w, h, [value=15])

Native image binding: fill mask l4 rect.

• Availability: Console (BIOS) and emulator

C8B.NativeTilemap_create#

C8B.NativeTilemap_create(width, height, tileW, tileH)

Creates a native tilemap userdata (freed by its __gc).

• Returns: 1 value(s): nil, userdata
• Availability: Console (BIOS) and emulator

C8B.Image_beginMaskUpdate#

C8B.Image_beginMaskUpdate(image)

Native image binding: begin mask update.

• Availability: Console (BIOS) and emulator

C8B.NativeTilemap_getTile#

C8B.NativeTilemap_getTile(tilemap, col, row)

Native native tilemap binding: get tile.

• Returns: 1 value(s): integer
• Availability: Console (BIOS) and emulator

C8B.NativeTilemap_setTile#

C8B.NativeTilemap_setTile(tilemap, col, row, tileIndex)

Native native tilemap binding: set tile.

• Availability: Console (BIOS) and emulator

C8B.Image_drawRotatedScaled#

C8B.Image_drawRotatedScaled(image, x, y, degrees, scaleX, scaleY)

Native image binding: draw rotated scaled.

• Availability: Console (BIOS) and emulator

C8B.Image_getBilinearFilter#

C8B.Image_getBilinearFilter(image)

Native image binding: get bilinear filter.

• Returns: 1 value(s): boolean
• Availability: Console (BIOS) and emulator

C8B.Image_setBilinearFilter#

C8B.Image_setBilinearFilter(image, enabled)

Native image binding: set bilinear filter.

• Availability: Console (BIOS) and emulator

C8B.Image_drawScaledWithFlip#

C8B.Image_drawScaledWithFlip(image, x, y, scaleX, scaleY, flip)

Native image binding: draw scaled with flip.

• Availability: Console (BIOS) and emulator

C8B.Image_drawWithSourceRect#

C8B.Image_drawWithSourceRect(image, x, y, srcX, srcY, srcW, srcH, [flip=0])

Native image binding: draw with source rect.

• Availability: Console (BIOS) and emulator

C8B.Image_drawRotatedScaledEx#

C8B.Image_drawRotatedScaledEx(image, x, y, degrees, scaleX, scaleY, centerX, centerY, [flip=0])

Native image binding: draw rotated scaled ex.

• Availability: Console (BIOS) and emulator

C8B.Image_newWithColorAndAlpha#

C8B.Image_newWithColorAndAlpha(width, height, fillColor, alpha)

Native image binding: new with color and alpha.

• Returns: 1 value(s): handle, nil
• Availability: Console (BIOS) and emulator

C8B.NativeTilemap_setImageTable#

C8B.NativeTilemap_setImageTable(tilemap, imagetable)

Native native tilemap binding: set image table.

• Availability: Console (BIOS) and emulator

C8B.NativeTilemap_setTilesFromTable#

C8B.NativeTilemap_setTilesFromTable(tilemap, tiles)

Copies a Lua array of tile indices into the map.

• Availability: Console (BIOS) and emulator

C8B.NativeTilemap_drawIgnoringOffset#

C8B.NativeTilemap_drawIgnoringOffset(tilemap, x, y)

Native native tilemap binding: draw ignoring offset.

• Availability: Console (BIOS) and emulator