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