Updated 7 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

Compatibility stubs

c8b.setAutoLockDisabled

c8b.setAutoLockDisabled(flag)

Does nothing.

  • Availability: Console (BIOS) and emulator

c8b.setGCScaling

c8b.setGCScaling(min, max)

Does nothing.

  • Availability: Console (BIOS) and emulator

c8b.setMinimumGCTime

c8b.setMinimumGCTime(ms)

Does nothing.

  • Availability: Console (BIOS) and emulator

c8b.getReduceFlashing

c8b.getReduceFlashing()

Always false.

  • Availability: Console (BIOS) and emulator

c8b.clearConsole

c8b.clearConsole()

Does nothing.

  • 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

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