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 paid Android packaging commands. Public builds report that the feature is unavailable until the private Android feature pack is installed under private/android.

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>
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.cancelFrame(handle)

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

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)

The optional fontSize defaults to 32 for drawing and measurement.

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.getError()

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

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.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.font.reset()

sys.gl #

const program = sys.gl.createShaderProgram('shader.vert', 'shader.frag')
sys.gl.bindScreen()
program.uniform1f('u_strength', 0.5).drawFullscreen()

const handle = sys.gl.createProgram('shader.vert', 'shader.frag')
const handleFromBytes = sys.gl.createProgramFromBuffer(vertexBytes, fragmentBytes)
sys.gl.destroyProgram(program)
sys.gl.drawFullscreen(program)
sys.gl.drawFullscreenImmediate(program, sourceTexture)
sys.gl.drawRegion(program, x, y, width, height, targetId)
sys.gl.drawRegionImmediate(program, x, y, width, height, targetId)
sys.gl.drawMeshImmediate(program, layout, options)
sys.gl.getLastError()
sys.gl.getProjectDir()

GL operations are immediate. Uniforms include scalar, vector, array, and matrix forms such as setUniform1f, setUniform3fv, and setUniformMatrix4.

createShaderProgram returns a chainable ShaderProgram wrapper around the same immediate GL state. It supports use, uniform1i, uniform1f, uniform2f, uniform3f, uniform4f, uniformMatrix4, texture, canvasTexture, renderTargetTexture, drawFullscreen, drawRegion, and drawMesh. The handle API and object API can be mixed when that keeps setup code readable.

Render targets, buffers, vertex layouts, textures, cubemaps, mesh draws, and instanced 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.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.

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.

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.

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