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
- Lifecycle callbacks
- Game control
- Frame rate and clocks
- System menu
- On-screen keyboard (c8b.keyboard)
- Compatibility stubs
- Native plugins (plugin)
- Classes and modules
- Lua environment additions
- Global tables
- Low-level bindings (C8B.*)
C8B.Memory_gcC8B.Plugin_CallC8B.Plugin_InitC8B.Plugin_LoadC8B.System_sleepC8B.Keyboard_hideC8B.Keyboard_showC8B.Memory_gcTickC8B.Plugin_UpdateC8B.Plugin_CleanupC8B.Plugin_IsReadyC8B.Plugin_GetStateC8B.System_loadGameC8B.Plugin_LoadStateC8B.Plugin_SaveStateC8B.Memory_getLuaHeapC8B.Plugin_GetExportsC8B.Keyboard_isVisibleC8B.Memory_clearUnusedC8B.SystemMenu_addItemC8B.Memory_getAssetUsedC8B.SystemMenu_isActiveC8B.Memory_getAssetCountC8B.Memory_getSdramStatsC8B.Plugin_FullLoadStateC8B.Plugin_FullSaveStateC8B.SystemMenu_removeItemC8B.SystemMenu_getItemCountC8B.SystemMenu_removeAllItemsC8B.System_setNetworkIndicator
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
menuItem:getTitle
item:getTitle()
Title given at creation.
- Returns: string
- Availability: Console (BIOS) and emulator
menuItem:setTitle
item:setTitle(title)
Does nothing (not supported).
- Availability: Console (BIOS) and emulator
menuItem:setCallback
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