Updated 8 November 2026

System, lifecycle & menu

The main loop callback, lifecycle callbacks, launching games, the system menu, the on-screen keyboard, native plugins, the class system and changes the SDK makes to the Lua environment.

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

Reference

c8b.update

function c8b.update(dt) ... end

Main per-frame callback. Define it in main.lua. After it returns the runtime services file players and closes leftover drawing contexts.

  • Availability: Console (BIOS) and emulator
  • Note: The emulator passes the frame time in seconds as the only argument; the console passes nothing. Do not depend on it.
local gfx = c8b.graphics
function c8b.update()
  gfx.clear()
  gfx.drawText("Hello", 10, 10)
end

core8bit.init

function core8bit.init() ... end

Emulator only: called once after main.lua has run, if defined. The console never calls it (on the console core8bit is the c8b table).

  • Availability: Emulator only

Lifecycle callbacks

c8b.gameWillTerminate

function c8b.gameWillTerminate() ... end

Called before the game is unloaded (exit to launcher or another game). All five lifecycle callbacks are cleared after gameWillTerminate.

  • Availability: Console (BIOS) only
  • Note: Called only on the console.

c8b.gameWillPause

function c8b.gameWillPause() ... end

Called when the system menu opens and before sleep. All five lifecycle callbacks are cleared after gameWillTerminate.

  • Availability: Console (BIOS) only
  • Note: Called only on the console.

c8b.gameDidResume

function c8b.gameDidResume() ... end

Called when the system menu closes and after wake. All five lifecycle callbacks are cleared after gameWillTerminate.

  • Availability: Console (BIOS) only
  • Note: Called only on the console.

c8b.deviceWillSleep

function c8b.deviceWillSleep() ... end

Called before the console sleeps (after gameWillPause). All five lifecycle callbacks are cleared after gameWillTerminate.

  • Availability: Console (BIOS) only
  • Note: Called only on the console.

c8b.deviceDidWake

function c8b.deviceDidWake() ... end

Called after wake (before gameDidResume). All five lifecycle callbacks are cleared after gameWillTerminate.

  • Availability: Console (BIOS) only
  • Note: Called only on the console.

c8b.gameWillResume

c8b.gameWillResume = nil

Field declared by the SDK; nothing calls it. Use gameDidResume.

  • Availability: Console (BIOS) and emulator

Game control

c8b.system.loadGame

c8b.system.loadGame(path)

Requests switching to another game's main.lua at the next frame boundary.

  • Availability: Console (BIOS) and emulator
  • Note: In the emulator this only works in SD-card boot mode.
c8b.system.loadGame("/Games/HelloWorld/main.lua")

c8b.launchGame

c8b.launchGame(path)

Records a launch request (sets globals _C8B_LAUNCH_REQUESTED/_C8B_LAUNCH_PATH).

  • Availability: Console (BIOS) and emulator
  • Note: Has no effect on the console; use c8b.system.loadGame there. In the emulator it works in SD-card boot mode.

c8b.system.launch

c8b.system.launch(path)

Emulator alias of c8b.launchGame.

  • Availability: Emulator only

c8b.returnToLauncher

c8b.returnToLauncher()

Returns to the system launcher.

  • Availability: Console (BIOS) and emulator

c8b.system.exitGame

c8b.system.exitGame()

Console: returns to the launcher (same as c8b.returnToLauncher there).

  • Availability: Console (BIOS) only

c8b.system.exit

c8b.system.exit()

Emulator alias of c8b.returnToLauncher.

  • Availability: Emulator only

c8b.system.returnToLauncher

c8b.system.returnToLauncher()

Emulator alias of c8b.returnToLauncher.

  • Availability: Emulator only

Frame rate and clocks

c8b.getFPS

c8b.getFPS()

Measured frames per second.

  • Returns: number
  • Availability: Console (BIOS) and emulator
  • Note: Returns an integer on the console and a measured float value in the emulator.

c8b.system.getFPS

c8b.system.getFPS()

Same value as c8b.getFPS.

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

c8b.system.getTime

c8b.system.getTime()

Monotonic milliseconds (console: since boot; emulator: host steady clock).

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

c8b.drawFPS

c8b.drawFPS([x=0], [y=0])

Draws the rounded FPS with the current font.

  • Availability: Console (BIOS) and emulator

c8b.setSpeedMode

c8b.setSpeedMode(mode)

Console: requests a CPU clock change at the next frame (0 FULL 480 MHz, 1 HIGH 400, 2 MEDIUM 200, 3 LOW 100). Errors on other values.

  • Availability: Console (BIOS) only

c8b.getSpeedMode

c8b.getSpeedMode()

Console: current and pending speed mode.

  • Returns: current, pending
  • Availability: Console (BIOS) only

c8b.system.setSpeedMode

c8b.system.setSpeedMode(mode)

Same function as c8b.setSpeedMode.

  • Availability: Console (BIOS) only

c8b.system.getSpeedMode

c8b.system.getSpeedMode()

Same function as c8b.getSpeedMode.

  • Returns: current, pending
  • Availability: Console (BIOS) only

c8b.SPEED_FULL

c8b.SPEED_FULL = 0

Console speed-mode constant.

  • Availability: Console (BIOS) only

c8b.SPEED_HIGH

c8b.SPEED_HIGH = 1

Console speed-mode constant.

  • Availability: Console (BIOS) only

c8b.SPEED_MEDIUM

c8b.SPEED_MEDIUM = 2

Console speed-mode constant.

  • Availability: Console (BIOS) only

c8b.SPEED_LOW

c8b.SPEED_LOW = 3

Console speed-mode constant.

  • Availability: Console (BIOS) only

c8b.system.setNetworkIndicator

c8b.system.setNetworkIndicator([on=true])

Console: shows/hides the blinking network icon (reset to on for each game).

  • Availability: Console (BIOS) only

c8b.getLuaHeapStats

c8b.getLuaHeapStats()

Console: memory statistics in KB.

  • Returns: heapUsedKB, heapTotalKB, luaKB, cppKB, cppBlocks
  • Availability: Console (BIOS) only

c8b.system.getLuaHeapStats

c8b.system.getLuaHeapStats()

Same function as c8b.getLuaHeapStats.

  • Returns: 5 numbers
  • Availability: Console (BIOS) only

System menu

c8b.getSystemMenu

c8b.getSystemMenu()

Returns the system-menu object.

  • Availability: Console (BIOS) and emulator
local menu = c8b.getSystemMenu()
menu:addMenuItem("Restart", function() restart() end)

systemMenu:addMenuItem

menu:addMenuItem(title, callback)

Adds an item (max 3). Returns a menu item, or nil, error.

  • Returns: menuItem | nil, err
  • Availability: Console (BIOS) and emulator

systemMenu:addCheckmarkMenuItem

menu:addCheckmarkMenuItem(title, initialValue, callback)

Adds a plain item; initialValue is ignored and no checkmark is shown.

  • Availability: Console (BIOS) and emulator

systemMenu:addOptionsMenuItem

menu:addOptionsMenuItem(title, options, initialValue, callback)

Adds a plain item; options are ignored.

  • Availability: Console (BIOS) and emulator

systemMenu:removeMenuItem

menu:removeMenuItem(item)

Removes an item.

  • Availability: Console (BIOS) and emulator

systemMenu:removeAllMenuItems

menu:removeAllMenuItems()

Removes all custom items.

  • Availability: Console (BIOS) and emulator
item:getTitle()

Title given at creation.

  • Returns: string
  • Availability: Console (BIOS) and emulator
item:setTitle(title)

Does nothing (not supported).

  • Availability: Console (BIOS) and emulator
item:setCallback(fn)

Does nothing (not supported).

  • Availability: Console (BIOS) and emulator

On-screen keyboard (c8b.keyboard)

c8b.keyboard.show

c8b.keyboard.show([text], [title])

Opens the system keyboard with initial text and an optional title (extension).

  • Availability: Console (BIOS) and emulator
  • Note: The on-screen keyboard exists only on the console. In the emulator show() stores the text and calls keyboardDidShowCallback, but no keyboard appears.

c8b.keyboard.hide

c8b.keyboard.hide()

Closes the keyboard (callbacks report the close).

  • Availability: Console (BIOS) and emulator
  • Note: The on-screen keyboard exists only on the console. In the emulator show() stores the text and calls keyboardDidShowCallback, but no keyboard appears.

c8b.keyboard.isVisible

c8b.keyboard.isVisible()

Whether the keyboard is open.

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

c8b.keyboard.text

c8b.keyboard.text

Current text (updated on every key).

  • Availability: Console (BIOS) and emulator

c8b.keyboard.width

c8b.keyboard.width()

Returns 480.

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

c8b.keyboard.setCapitalizationBehavior

c8b.keyboard.setCapitalizationBehavior(...)

Does nothing.

  • Availability: Console (BIOS) and emulator

c8b.keyboard.keyboardDidShowCallback

c8b.keyboard.keyboardDidShowCallback = function() end

Called by show().

  • Availability: Console (BIOS) and emulator

c8b.keyboard.textChangedCallback

c8b.keyboard.textChangedCallback = function(text) end

Called on every key with the text (argument is an extension).

  • Availability: Console (BIOS) and emulator

c8b.keyboard.keyboardWillHideCallback

c8b.keyboard.keyboardWillHideCallback = function(ok, text) end

Called when closed; ok is true for DONE.

  • Availability: Console (BIOS) and emulator

c8b.keyboard.keyboardDidHideCallback

c8b.keyboard.keyboardDidHideCallback = function(text) end

Called after keyboardWillHideCallback.

  • Availability: Console (BIOS) and emulator

Native plugins (plugin)

plugin.load

plugin.load(pathOrName)

Loads a native plugin. Pass the console path (e.g. "plugins/mygame/mygame_plugin.bin"): the console resolves it against the game folder; the emulator strips ".bin", adds the host extension (.dylib/.so/.dll) and searches relative to the game folder and the host SDK root.

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

plugin.init

plugin.init()

Initialises the loaded plugin.

  • Returns: integer (0 = success)
  • Availability: Console (BIOS) and emulator

plugin.update

plugin.update()

Runs one plugin frame.

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

plugin.cleanup

plugin.cleanup()

Unloads/cleans up.

  • Availability: Console (BIOS) and emulator

plugin.call

plugin.call(funcId, ...)

Calls an exported function with integer/number/boolean/string arguments.

  • Returns: integer (-1 if not ready on console)
  • Availability: Console (BIOS) and emulator

plugin.getExports

plugin.getExports()

Export description string.

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

plugin.saveState

plugin.saveState()

Plugin save state.

  • Returns: string or nil
  • Availability: Console (BIOS) and emulator

plugin.loadState

plugin.loadState(data)

Restores a save state.

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

plugin.fullSaveState

plugin.fullSaveState()

Full save state.

  • Returns: string or nil
  • Availability: Console (BIOS) and emulator

plugin.fullLoadState

plugin.fullLoadState(data)

Restores a full state.

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

plugin.isReady

plugin.isReady()

Console only: plugin ready.

  • Returns: boolean
  • Availability: Console (BIOS) only

plugin.getState

plugin.getState()

Console only: state name.

  • Returns: string
  • Availability: Console (BIOS) only

plugin.isLoaded

plugin.isLoaded()

Emulator only.

  • Returns: boolean
  • Availability: Emulator only

plugin.isInitialized

plugin.isInitialized()

Emulator only.

  • Returns: boolean
  • Availability: Emulator only

plugin.loadPath

plugin.loadPath(path)

Emulator only: loads from an explicit path.

  • Returns: boolean
  • Availability: Emulator only

plugin.setWorkingDir

plugin.setWorkingDir(path)

Emulator only: plugin working directory.

  • Availability: Emulator only

Classes and modules

Core8Bit has its own small class system. Every class is a global table created with class(). Classes inherit with extends, instances are created by calling the class, and each instance gets init(...) called once. All SDK types (Sprite, Image, Timer and the rest) are classes too, so your classes can extend them. import loads a game file once, from the game folder first and then from the SDK.

class

class(name) | class(name).extends([Parent])

Defines (or returns) a global class; the class table is stored in _G[name]. Calling the class (or Class.new) creates an instance and runs init(...).

  • Availability: Console (BIOS) and emulator
class("Enemy").extends(Sprite)
function Enemy:init(x, y)
  Enemy.super.init(self)
  self:moveTo(x, y)
end

Class.extends

Class.extends([Parent])

Sets the parent class (default Object); available on every class created with class().

  • Availability: Console (BIOS) and emulator

Object

Object

Root class.

  • Availability: Console (BIOS) and emulator

Object.new

Class.new(...) | Class(...)

Creates an instance and calls init(...).

  • Availability: Console (BIOS) and emulator

Object:className

obj:className()

Class name.

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

Object:isa

obj:isa(Class)

Whether obj inherits from Class.

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

import

import "path"

Runs a module once (dot or slash path; searched in the game folder, then the SDK).

  • Returns: module result or class
  • Availability: Console (BIOS) and emulator

require

require(name)

Loads name.lua from the game folder, then from the SDK modules, and caches the result; falls back to the standard require.

  • Availability: Console (BIOS) and emulator

dofile

dofile(path)

Runs a file through the platform filesystem; nesting depth is limited.

  • Availability: Console (BIOS) and emulator

Lua environment additions

math.pow

math.pow(...)

Polyfill added by the SDK: math.pow(x, y) = x ^ y (Lua 5.1 compatibility).

  • Availability: Console (BIOS) and emulator

math.log10

math.log10(...)

Polyfill added by the SDK: math.log10(x).

  • Availability: Console (BIOS) and emulator

math.ldexp

math.ldexp(...)

Polyfill added by the SDK: math.ldexp(m, e).

  • Availability: Console (BIOS) and emulator

math.frexp

math.frexp(...)

Polyfill added by the SDK: math.frexp(x).

  • Availability: Console (BIOS) and emulator

math.cosh

math.cosh(...)

Polyfill added by the SDK: math.cosh(x).

  • Availability: Console (BIOS) and emulator

math.sinh

math.sinh(...)

Polyfill added by the SDK: math.sinh(x).

  • Availability: Console (BIOS) and emulator

math.tanh

math.tanh(...)

Polyfill added by the SDK: math.tanh(x).

  • Availability: Console (BIOS) and emulator

coroutine.close

coroutine.close(co)

No-op polyfill returning true (runtime is Lua 5.3).

  • Availability: Console (BIOS) and emulator

os.clock

os.clock()

Console: replaced by the runtime (seconds since boot). Emulator: standard Lua os.clock.

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

os.exit

os.exit()

Console: replaced by the runtime; returns to the launcher via c8b.returnToLauncher. Emulator: standard os.exit (quits the emulator).

  • Availability: Console (BIOS) and emulator

Global tables

c8b

c8b

The Core8Bit API table. On both platforms it is the same table as C8B (native flat bindings).

  • Availability: Console (BIOS) and emulator

C8B

C8B

Native binding table (same table as c8b). Flat functions are documented under "Low-level bindings" on each page.

  • Availability: Console (BIOS) and emulator

core8bit

core8bit

Legacy namespace. Console: alias of c8b. Emulator: separate table with update and graphics/display pointing to c8b.graphics/c8b.display.

  • Availability: Console (BIOS) and emulator

Core8Bit

Core8Bit

Console only: alias of c8b.

  • Availability: Console (BIOS) only

Low-level bindings (C8B.*)

C8B.Memory_gc

C8B.Memory_gc()

Runs a full Lua GC; returns the heap size.

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

C8B.Plugin_Call

C8B.Plugin_Call(funcId, ...)

Console: plugin.call(funcId, ...); returns -1 if no plugin is ready.

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

C8B.Plugin_Init

C8B.Plugin_Init()

Console: plugin.init.

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

C8B.Plugin_Load

C8B.Plugin_Load(path)

Console: loads a plugin (path relative to the game folder); same function as plugin.load.

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

C8B.System_sleep

C8B.System_sleep([ms=1000])

Console: blocks for ms milliseconds (default 1000).

  • Availability: Console (BIOS) only

C8B.Keyboard_hide

C8B.Keyboard_hide()

Console: closes it.

  • Availability: Console (BIOS) only

C8B.Keyboard_show

C8B.Keyboard_show([text=""], [title=""])

Console: opens the on-screen keyboard (used by c8b.keyboard.show).

  • Availability: Console (BIOS) only

C8B.Memory_gcTick

C8B.Memory_gcTick()

Runs an incremental GC step.

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

C8B.Plugin_Update

C8B.Plugin_Update()

Console: plugin.update.

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

C8B.Plugin_Cleanup

C8B.Plugin_Cleanup()

Console: plugin.cleanup.

  • Availability: Console (BIOS) only

C8B.Plugin_IsReady

C8B.Plugin_IsReady()

Console: plugin.isReady.

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

C8B.Plugin_GetState

C8B.Plugin_GetState()

Console: plugin.getState.

  • Returns: 1 value(s): string
  • Availability: Console (BIOS) only

C8B.System_loadGame

C8B.System_loadGame(gamePath)

Console: same function as c8b.system.loadGame.

  • Availability: Console (BIOS) only

C8B.Plugin_LoadState

C8B.Plugin_LoadState(data)

Console: plugin.loadState(data).

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

C8B.Plugin_SaveState

C8B.Plugin_SaveState()

Console: plugin.saveState.

  • Returns: 1 value(s): nil, string
  • Availability: Console (BIOS) only

C8B.Memory_getLuaHeap

C8B.Memory_getLuaHeap()

Lua heap size.

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

C8B.Plugin_GetExports

C8B.Plugin_GetExports()

Console: plugin.getExports.

  • Returns: 1 value(s): string
  • Availability: Console (BIOS) only

C8B.Keyboard_isVisible

C8B.Keyboard_isVisible()

Console: whether it is open.

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

C8B.Memory_clearUnused

C8B.Memory_clearUnused()

Frees unused cached assets.

  • Availability: Console (BIOS) and emulator

C8B.SystemMenu_addItem

C8B.SystemMenu_addItem(title, arg2)

Adds a system-menu item with a Lua callback; returns its index or nil.

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

C8B.Memory_getAssetUsed

C8B.Memory_getAssetUsed()

Bytes used by the asset manager.

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

C8B.SystemMenu_isActive

C8B.SystemMenu_isActive()

Whether the system menu is open.

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

C8B.Memory_getAssetCount

C8B.Memory_getAssetCount()

Assets loaded.

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

C8B.Memory_getSdramStats

C8B.Memory_getSdramStats()

SDRAM pool statistics table (nil if unavailable).

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

C8B.Plugin_FullLoadState

C8B.Plugin_FullLoadState(data)

Console: plugin.fullLoadState(data).

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

C8B.Plugin_FullSaveState

C8B.Plugin_FullSaveState()

Console: plugin.fullSaveState.

  • Returns: 1 value(s): nil, string
  • Availability: Console (BIOS) only

C8B.SystemMenu_removeItem

C8B.SystemMenu_removeItem(index)

Removes an item by index.

  • Availability: Console (BIOS) and emulator

C8B.SystemMenu_getItemCount

C8B.SystemMenu_getItemCount()

Number of custom items.

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

C8B.SystemMenu_removeAllItems

C8B.SystemMenu_removeAllItems()

Removes all custom items.

  • Availability: Console (BIOS) and emulator

C8B.System_setNetworkIndicator

C8B.System_setNetworkIndicator([g_netIndicator])

Console: same as c8b.system.setNetworkIndicator.

  • Availability: Console (BIOS) only