API Reference #

This page is a compact map of the public developer surface. The generated budo-llm.md file in the repository is the exhaustive source for signatures, edge cases, and WebAssembly import lists. Use this page when you want to remember where something lives.

CLI #

Budo Pro: android-apk and android-aab are Budo Pro commands. During Budo's public launch, the released Budo binaries include them for free; a later release will make them a paid feature. Budo built from source without the private Android feature pack under private/android keeps the commands, which then report that packaging is unavailable.

budo run <DIRECTORY|FILE> [--width N] [--height N] [--title STR] [--fullscreen] [--no-vsync] [--file-root PATH]
budo run --from-input js|ts|lua|wat|wasm [--width N] [--height N] [--title STR] [--fullscreen] [--no-vsync] [--file-root PATH]
budo <DIRECTORY>
budo init <DIRECTORY> [--template ui | --language c [--template canvas|gpu]]
budo web-serve <DIRECTORY>
budo web-export <DIRECTORY> [-o DIR]
budo android-apk <DIRECTORY> [--release|--debug] [--install] [--no-build] [--clean] [-o DIR]
budo android-aab <DIRECTORY> [--release|--debug] [--no-build] [--clean] [-o DIR]
budo budo.d.ts
budo budo-llm.md
budo version          # also --version, -v
budo help

JavaScript globals #

JavaScript and TypeScript apps run in QuickJS. Budo injects sys, console, fetch, and subsystem aliases where documented.

The sys tree contains canvas, transform, path, svg, font, graphics, gl, math, input, window, animation, timer, audio, midi, db, file, network, udp, magneto, device, neural, and capabilities.

sys.animation #

sys.animation.requestFrame(callback)
sys.animation.waitForInput(callback, timeoutMs)
sys.animation.cancelFrame(handle)

Register one frame callback. The callback receives a timestamp in milliseconds.

waitForInput registers the callback like requestFrame, but it runs only on the next input event, canvas resize, or after timeoutMs (optional). Until then the last frame stays on screen and Budo stops drawing: desktop builds sleep on window events and Android renders only when needed. End a frame with waitForInput when nothing animates and requestFrame while something moves; an app with sys.gl passes that draw to the screen after the canvas keeps calling requestFrame.

sys.timer #

sys.timer.once(delay, callback)
sys.timer.every(interval, callback)
sys.timer.clear(id)

JavaScript-only frame-resolution timers.

sys.window #

sys.window.getWidth()
sys.window.getHeight()
sys.window.getDisplayDensity()

Use display density for UI that should keep a stable physical size across devices.

sys.input #

sys.input.get()
sys.input.isKeyDown(scancode)
sys.input.isKeyPressed(scancode)
sys.input.startTextInput({text, selectionStart, selectionEnd, multiline?})
sys.input.updateTextInput({text, selectionStart, selectionEnd, caret:{x,y,width,height}})
sys.input.stopTextInput()

get() returns pointer, pointer list, timing, modifier, focus, committed text, full textEdit replacements, persistent composition, and textInputActive. Apply textEdit before sending the current model back through updateTextInput. Text sessions provide IME composition, selection edits, candidate positioning, and soft-keyboard lifecycle on desktop, web, and Android. Android Back and single-line Done/Return finalize composition into textEdit. Text selections use UTF-16 code units. Scancode queries remain physical and layout-independent.

sys.capabilities #

Capability entries have an available boolean. The main entries are neural, midi, udp, http and sensors.

if (sys.capabilities.udp.available) {
  console.log('UDP enabled');
}

sys.canvas #

sys.canvas.clear(color)
sys.canvas.drawRect(x, y, width, height)
sys.canvas.drawRoundRect(x, y, width, height, rx, ry)
sys.canvas.drawCircle(cx, cy, radius)
sys.canvas.drawOval(x, y, width, height)
sys.canvas.drawLine(x1, y1, x2, y2)
sys.canvas.drawPoint(x, y)
sys.canvas.drawText(text, x, y, fontSize)
sys.canvas.measureText(text, fontSize)
sys.canvas.measureTextRect(text, fontSize)
sys.canvas.drawArc(x, y, width, height, startAngle, sweepAngle, useCenter)
sys.canvas.readPixels()
sys.canvas.save()
sys.canvas.restore()
sys.canvas.translate(dx, dy)
sys.canvas.rotate(degrees)
sys.canvas.rotate(degrees, px, py)
sys.canvas.scale(sx, sy)
sys.canvas.skew(sx, sy)
sys.canvas.reset()
sys.canvas.clipRect(x, y, width, height)
sys.canvas.clipRoundRect(x, y, width, height, rx, ry)
sys.canvas.clipPath(path)
sys.canvas.saveLayer(alpha, x, y, width, height, backdropBlur)
sys.canvas.drawParagraph(text, x, y, width, fontSize, options)
sys.canvas.measureParagraph(text, width, fontSize, options)
sys.canvas.drawRichText(spans, x, y, width, options)
sys.canvas.measureRichText(spans, width, options)

The optional fontSize defaults to 32 for drawing and measurement.

clipRoundRect and clipPath clip with anti-aliased edges; ry defaults to rx. Undo a clip with restore() after save().

saveLayer(alpha = 255, x?, y?, width?, height?, backdropBlur = 0) draws what follows into an offscreen layer that restore() composites back with one opacity (0–255), so overlapping shapes fade as a group. With a rectangle the layer is clipped to it. A backdropBlur above 0 starts the layer with a blurred copy of what is already drawn below it, for frosted-glass panels:

sys.canvas.save()
sys.canvas.clipRoundRect(x, y, w, h, 16)
sys.canvas.saveLayer(255, x, y, w, h, 24)
sys.canvas.setFillColor('#FFFFFF99')
sys.canvas.drawRect(x, y, w, h)
sys.canvas.restore()
sys.canvas.restore()

drawRichText(spans, x, y, width, options) and measureRichText(spans, width, options) lay out a paragraph made of spans: strings, or { text, size, color, font } objects (font is a name registered with sys.font.load). Lines grow to their largest span and baselines align; options adds size, the default span size, to the paragraph options.

drawParagraph wraps text to width (0 disables wrapping) at spaces and \n, breaking words that are wider than a line. y is the top of the paragraph, not a baseline. options takes align ('left', 'center', 'right'), lineHeight (a multiple of the font size, default 1.25), and maxLines (the last line ends with an ellipsis). Both functions return { width, height, lines }, so measureParagraph can size a layout before drawing.

Colors accept #RRGGBB, #RRGGBBAA, or numeric ARGB.

Canvas paint state #

sys.canvas.setFillColor(color)
sys.canvas.setStrokeColor(color)
sys.canvas.setStrokeWidth(width)
sys.canvas.setAntiAlias(enabled)
sys.canvas.setAlpha(alpha)
sys.canvas.setStrokeCap(cap)
sys.canvas.setStrokeJoin(join)
sys.canvas.setBlendMode(mode)
sys.canvas.setImageFilter(name, ...args)
sys.canvas.setColorFilter(name, ...args)
sys.canvas.setGradient(kind, ...args)
sys.canvas.getError()

Blend modes, image filters, and color filters are advanced Skia APIs.

Gradients replace the paint color for fills, strokes, and text:

sys.canvas.setGradient('linear', x0, y0, x1, y1, ['#2E7D6F', '#8FD3C1'])
sys.canvas.setGradient('radial', cx, cy, radius, ['#FFFFFF', '#FFFFFF00'], [0, 1])
sys.canvas.setGradient('sweep', cx, cy, ['#F00', '#0F0', '#00F', '#F00'])
sys.canvas.setGradient(null)

colors holds 2 to 16 colors and the optional stops one 0–1 position per color. Colors blend in OKLab, so transitions stay even and transparent stops do not turn gray. A gradient makes the paint opaque (setAlpha then fades it) and lasts until setGradient(null) or the next setFillColor or setStrokeColor.

sys.path #

const path = sys.path.create()
sys.path.reset(path)
sys.path.moveTo(path, x, y)
sys.path.lineTo(path, x, y)
sys.path.quadTo(path, x1, y1, x2, y2)
sys.path.cubicTo(path, x1, y1, x2, y2, x3, y3)
sys.path.close(path)
sys.path.addRect(path, x, y, width, height)
sys.path.addCircle(path, cx, cy, radius)
sys.path.addSvg(path, d)        // SVG path data; false when it does not parse
sys.canvas.drawPath(path)

sys.svg and sys.font #

const svg = sys.svg.load('icon.svg')
const svgFromBytes = sys.svg.loadFromBuffer(svgBytes)
sys.canvas.drawSvg(svg, x, y, width, height)
sys.svg.destroy(svg)
sys.svg.getWidth(svg)
sys.svg.getHeight(svg)

sys.font.load(path, name)
sys.font.loadFromBuffer(fontBytes, name)
sys.canvas.setFont(name)
sys.canvas.setFont(null)       // back to the default font (nil in Lua)

sys.gl #

const program = sys.gl.createProgram('shader.vert', 'shader.frag')
const fromBytes = sys.gl.createProgramFromBuffer(vertexBytes, fragmentBytes)
sys.gl.bindScreen()
sys.gl.bindRenderTarget(targetId)
sys.gl.setUniform1f(program, 'u_strength', 0.5)
sys.gl.bindTexture2D(program, 'u_image', texture, 1)
sys.gl.bindTexture(program, 'u_scene', targetId, 1)
sys.gl.bindCanvasTexture(program, 'u_ui', canvasTexture, 1)
sys.gl.drawFullscreen(program)
sys.gl.drawFullscreenImmediate(program, sourceTexture)
sys.gl.drawRegion(program, x, y, width, height, targetId)
sys.gl.drawMesh(program, layout, options)
sys.gl.destroyProgram(program)
sys.gl.getLastError()
sys.gl.getProjectDir()

GL operations are immediate. Programs, render targets, buffers, layouts, and textures are numeric handles, and every sys.gl call takes the program handle first. Uniforms include scalar, vector, array, and matrix forms such as setUniform1f, setUniform3fv, and setUniformMatrix4.

Render targets, buffers, vertex layouts, textures, cubemaps, and mesh draws are also available. Resource loaders that normally take project-relative paths also have FromBuffer variants for bytes from file.readBinary(), fetch().arrayBuffer(), or other sources. See Rendering and shaders for the model and budo-llm.md for the full signature list.

sys.graphics #

const surface = sys.graphics.createCanvasTexture(512, 256)
surface.canvas.drawText('HUD', 32, 96, 42)
program.canvasTexture('u_hud', surface, 1).drawFullscreen()
surface.destroy()

Canvas textures are Skia surfaces backed by GL textures and framebuffers. They are useful for drawing text, UI, or vector content into a texture that a shader can sample.

sys.math #

Math helpers mutate caller-owned arrays. Matrix layout is column-major.

sys.math.mat4Identity(out)
sys.math.mat4Multiply(out, a, b)
sys.math.mat4Perspective(out, fovy, aspect, near, far)
sys.math.mat4Ortho(out, left, right, bottom, top, near, far)
sys.math.mat4LookAt(out, eye, target, up)
sys.math.mat4Translate(out, a, v)
sys.math.mat4RotateX(out, a, radians)
sys.math.mat4RotateY(out, a, radians)
sys.math.mat4RotateZ(out, a, radians)
sys.math.mat4Scale(out, a, v)
sys.math.mat4Invert(out, a)
sys.math.mat4Transpose(out, a)
sys.math.vec3Add(out, a, b)
sys.math.vec3Sub(out, a, b)
sys.math.vec3Scale(out, a, scale)
sys.math.vec3Normalize(out, a)
sys.math.vec3Cross(out, a, b)
sys.math.vec3Dot(a, b)
sys.math.vec3Length(a)
sys.math.vec3TransformMat4(out, a, matrix)
sys.math.quatFromAxisAngle(out, axis, radians)
sys.math.quatMultiply(out, a, b)
sys.math.quatSlerp(out, a, b, t)
sys.math.quatToMat4(out, q)

sys.audio #

sys.audio.start()
sys.audio.stop()
sys.audio.isPlaying()
sys.audio.setMasterGain(gain)
sys.audio.getMasterGain()
sys.audio.createOscillator()
sys.audio.destroyOscillator(id)
sys.audio.setOscillatorType(id, type)
sys.audio.setOscillatorFrequency(id, frequency)
sys.audio.setOscillatorGain(id, gain)
sys.audio.setOscillatorDetune(id, cents)
sys.audio.setOscillatorEnvelope(id, attack, decay, sustain, release)
sys.audio.startOscillator(id)
sys.audio.stopOscillator(id)
sys.audio.noteOn(id)
sys.audio.noteOff(id)
sys.audio.createBuffer(sampleRate, channels, samples)
sys.audio.loadBuffer(path)
sys.audio.loadBufferFromBuffer(buffer)
sys.audio.setBufferData(buffer, samplesArray, offset)
sys.audio.destroyBuffer(buffer)
sys.audio.playBuffer(buffer, loop, gain)
sys.audio.stopBuffer(playback)
sys.audio.midiToFreq(note)
sys.audio.getError()

createBuffer allocates an empty mono or stereo PCM buffer. loadBuffer decodes a project-relative WAV, MP3, Ogg Vorbis, or FLAC asset; loadBufferFromBuffer decodes the same formats from an ArrayBuffer. Both return a buffer ID, or -1 on failure. Play either kind of buffer with playBuffer; use getError() after a failed load to inspect the last audio error.

sys.midi #

sys.midi.getInputCount()
sys.midi.getOutputCount()
sys.midi.getInputDevices()
sys.midi.getOutputDevices()
sys.midi.refreshDevices()
sys.midi.onDevicesChanged(callbackOrNull)
sys.midi.openInput(deviceIndex, callback)
sys.midi.closeInput(handle)
sys.midi.openOutput(deviceIndex)
sys.midi.closeOutput(handle)
sys.midi.sendMessage(handle, status, data1, data2)
sys.midi.sendRaw(handle, bytes)
sys.midi.noteOn(handle, channel, note, velocity)
sys.midi.noteOff(handle, channel, note, velocity)
sys.midi.controlChange(handle, channel, control, value)
sys.midi.programChange(handle, channel, program)
sys.midi.pitchBend(handle, channel, value)
sys.midi.channelPressure(handle, channel, pressure)
sys.midi.polyPressure(handle, channel, note, pressure)
sys.midi.createSession(name, port)
sys.midi.connectSession(session, host, port)
sys.midi.destroySession(session)
sys.midi.onSessionMessage(session, callback)
sys.midi.sessionSend(session, status, data1, data2)
sys.midi.sessionSendRaw(session, bytes)
sys.midi.getSessions()

Constants include MIDI message types and common control-change numbers. onDevicesChanged establishes a silent baseline when registered, replaces any previous listener, and accepts null to unsubscribe. On a later topology change the callback runs on the runtime frame thread with {inputs, outputs, generation}. The snapshots are already refreshed and detect device replacement or reordering even when counts remain unchanged.

sys.db, sys.files, sys.assets, fetch, and sys.net.udp #

const db = sys.db.open(name)
sys.db.close(db)
sys.db.execute(db, sql)
sys.db.run(db, sql, ...params)
sys.db.query(db, sql, ...params)
sys.db.lastInsertId(db)
sys.db.getError()

sys.files.list(path)
sys.files.readText(path)
sys.files.readBinary(path)
sys.files.writeText(path, text)
sys.files.writeBinary(path, bytes)
sys.files.exists(path)
sys.files.isDirectory(path)
sys.files.size(path)
sys.files.pickText(callback, extension?)
sys.files.saveText(suggestedName, text, callback)
sys.files.getError()

// Read-only convenience wrapper over sys.files paths under assets/.
sys.assets.list(path)
sys.assets.readText(path)
sys.assets.readBinary(path)
sys.assets.exists(path)
sys.assets.isDirectory(path)
sys.assets.size(path)
sys.assets.getError()

fetch(url, options)
sys.net.fetch(url, options)

const socket = sys.net.udp.bind(port)
sys.net.udp.getPort(socket)
sys.net.udp.send(socket, host, port, bytes)
sys.net.udp.onMessage(socket, callback)
sys.net.udp.close(socket)

sys.files is the canonical virtual filesystem. Except for a root list(), its paths start with assets/ or files/. sys.assets accepts bundle-relative paths, prepends assets/, exposes no write methods, and shares getError() state with sys.files. Therefore sys.assets.readText('config.json') is equivalent to sys.files.readText('assets/config.json'), while sys.assets.list() is equivalent to sys.files.list('assets'). JS pickText(callback, extension?) opens the platform system picker and returns whether it launched; an extension such as .json filters the picker and is enforced on the selected display name. The callback receives ({name,text}, null) or (null, error), and reads at most 8 MiB. saveText(name, text, callback) opens the platform Save As flow and reports null on success or an error string. Both APIs access locations outside Budo's mounts only through explicit user consent.

Network access is disabled until app.json declares a network policy.

sys.sensors, sys.device, and sys.neural #

sys.sensors.isAvailable()
sys.sensors.hasAccelerometer()
sys.sensors.hasCompass()
sys.sensors.start()
sys.sensors.stop()
sys.sensors.isActive()
sys.sensors.getAccel()
sys.sensors.getCompass()

sys.device.keepScreenOn(enabled)
sys.device.setClipboardText(text)
sys.device.getClipboardText()
sys.device.haptic(kind)
sys.device.getPreferences()
sys.device.setCursor(name)

sys.neural.isAvailable()
sys.neural.getError()
sys.neural.loadModel(path)
sys.neural.loadModelFromBuffer(buffer)
sys.neural.unloadModel(model)
sys.neural.getModelInfo(model)
sys.neural.setInput(model, name, data, shape)
sys.neural.run(model, inputs)
sys.neural.getOutput(model, name)

Neural inference requires ONNX Runtime support and "neural": true in app.json.

getClipboardText() returns null when the clipboard holds no text. Browsers only read the clipboard asynchronously, so on the web it returns the last text copied, cut, or pasted on the page.

haptic(kind) plays light (default), medium, heavy, selection, success, warning, or error feedback; it returns false on devices without haptics (desktop).

getPreferences() returns { darkMode, reducedMotion, highContrast, fontScale, safeArea: { top, right, bottom, left }, keyboardInset }: the system appearance, motion and contrast settings, the text size multiplier, insets (physical pixels) to keep free of notches and system bars, and the height (physical pixels, from the bottom) the on-screen keyboard covers, 0 when it is hidden or on desktop. Lay out above keyboardInset while a text field is focused: budo-ui does it for you. It is cheap to call every frame.

setCursor(name) takes CSS cursor names: default, text, pointer, grab, grabbing, move, ew-resize, ns-resize, nwse-resize, nesw-resize, not-allowed, wait, crosshair, or none.

sys.accessibility #

sys.accessibility.isAvailable()
sys.accessibility.isActive()
sys.accessibility.update(nodes)
sys.accessibility.takeActions()

Budo draws everything itself, so screen readers only know what the app tells them. Publish a flat list of nodes in reading order whenever the UI changes:

sys.accessibility.update([
  { id: 'save', role: 'button', label: 'Save', x, y, width, height },
  { id: 'dark', role: 'switch', label: 'Dark mode', checked: true, x, y, width, height },
  { id: 'level', role: 'slider', label: 'Volume', min: 0, max: 100, rangeValue: 40, value: '40%', x, y, width, height },
])
for (const { id, action, value } of sys.accessibility.takeActions()) {
  // action: 'press', 'focus', 'increment', 'decrement', or 'setValue' (with value)
}

Roles: button, checkbox, radio, switch, slider, textbox, list, listitem, heading, text, combobox, option, tab, image, group, link. Bounds are physical canvas pixels. On the web the nodes become invisible ARIA elements over the canvas; on Android they are exposed to TalkBack; on macOS to VoiceOver. Windows and Linux report isAvailable() === false for now. BUDO_ACCESSIBILITY=1 forces isActive() on macOS, for checking a tree with Accessibility Inspector.

isActive() tells whether a screen reader probably runs (always true on the web, where browsers do not tell), so apps can skip building the tree.

Lua reference #

Lua uses the same sys namespace names for canvas, paint, transform, path, SVG, font, GL, input, window, animation, audio, MIDI, SQLite, files/assets, network, UDP, sensors, device, neural, math, and capabilities.

Differences are language-shaped. Lists are 1-based. fetch is callback-based. readBinary returns a Lua string. Neural tensors are Lua tables. sys.timer is JavaScript-only.

local function frame(timestamp)
  sys.canvas.clear('#101116')
  sys.canvas.setFillColor('#ffffff')
  sys.canvas.drawText('Lua', 32, 64, 24)
  sys.animation.requestFrame(frame)
end

sys.animation.requestFrame(frame)

WebAssembly reference #

WebAssembly imports host functions from env. Names use snake case: canvas_clear, canvas_set_fill_color, transform_translate, path_create, gl_create_program, audio_create_oscillator, db_open, files_read_text, udp_bind, midi_open_input, magneto_get_accel, device_keep_screen_on, neural_load_model, and so on. File import paths start with assets/ or files/. WebAssembly has no sys namespace, so sys.assets does not add a separate import family; use env.files_* with an assets/ path.

String-backed imports take pointer and length pairs. Tensor and pixel APIs copy through exported linear memory. Optional features should be guarded with capability imports or compiled into target-specific modules.

For the complete import list, generate or open budo-llm.md from the same Budo build you ship.

<!-- BEGIN GENERATED API AVAILABILITY -->

Runtime availability #

This section is generated from api/contracts/*.json. Each cell names the guest-visible export; - means that operation is not exposed to that runtime. Platform lists describe where each runtime adapter is registered.

accessibility #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop.

audio #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: unsupported.

canvas #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: web.

canvas_texture #

JavaScript: desktop, android, web; Lua: unsupported; Wasmtime: unsupported; Browser WASM: unsupported.

capabilities #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop.

console #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: unsupported.

device #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: web.

drawing_resources #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: web.

file #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: unsupported.

gl #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: web.

input_window #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: web.

llamacpp #

JavaScript: desktop, android; Lua: desktop, android; Wasmtime: unsupported; Browser WASM: unsupported.

magneto #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: unsupported.

math #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: web.

midi #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: unsupported.

module_lifecycle #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: web.

network #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: web.

neural #

JavaScript: desktop, android; Lua: desktop, android; Wasmtime: desktop; Browser WASM: unsupported.

scheduling #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: web.

sqlite #

JavaScript: desktop, android, web; Lua: desktop, android, web; Wasmtime: desktop; Browser WASM: unsupported.

udp #

JavaScript: desktop, android; Lua: desktop, android; Wasmtime: desktop; Browser WASM: unsupported.

<!-- END GENERATED API AVAILABILITY -->