KBC Opcodes

KBC is a register-based bytecode. The interpreter dispatches **112 opcodes** via a `while`/`when` loop. Each opcode is one byte; operands follow.

This reference is for compiler-plugin authors, tooling builders, and anyone debugging a .ktx bundle. You don't need to know any of this to write @KetoyComposable functions.

Encoding overview

• All multi-byte integers in the instruction stream are big-endian.
• Registers are addressed by single-byte index (u8, 0–255).
• The string pool, function table, modifier table are referenced by 16-bit indices (u16).
• Adapter IDs / constructor IDs / capability IDs are 16-bit shorts.

Loads & moves (0x00–0x0A)

Arithmetic (0x0B–0x1F)

Double: 0x0B–0x0E — ADD_DOUBLE, SUB_DOUBLE, MUL_DOUBLE, DIV_DOUBLE. Int: 0x10–0x15 — ADD_INT, SUB_INT, MUL_INT, DIV_INT, MOD_INT, NEG_INT. Long: 0x16–0x1B — ADD_LONG, SUB_LONG, MUL_LONG, DIV_LONG, MOD_LONG, NEG_LONG. Float: 0x1C–0x1F — ADD_FLOAT, SUB_FLOAT, MUL_FLOAT, DIV_FLOAT.

All three-register form: dst:u8, lhs:u8, rhs:u8 (NEG: dst:u8, src:u8).

Divide-by-zero on DIV_INT / MOD_INT / DIV_LONG / MOD_LONG throws KBCRuntimeException. Float / double divide produces Infinity / NaN per IEEE-754. The Tier-1 JIT skips DIV/MOD opcodes because the exception-wrap contract is non-trivial in DEX.

Comparison & nullability (0x20–0x29)

Control flow (0x30–0x38)

Exception handler type-filtering is currently catch-all (KNOWN_ISSUES #2): the catchTypeIdx is recorded but not matched against the thrown value's type, so multi-catch collapses to the first handler. Rethrow works correctly.

Object model (0x40–0x4B)

Bitwise opcodes were added in 0.3.x to support K2's $default / $changed bitfield merging, which the Compose plugin emits heavily.

Capability calls (0x50–0x52)

After INVOKE_CAPABILITY_SUSPEND, a SUSPEND_POINT typically follows.

Collections (0x60–0x6A)

Coroutines (0x70–0x79)

Compose runtime (0x80–0x88)

Strings (0x90–0x93)

Every + / template / multi-arg concat collapses to one STRING_CONCAT opcode.

Casts & boxing (0xA0–0xAB)

Adapter dispatch (0xB0–0xB1)

The two opcodes that bridge KBC into Compose / typed object construction.

Sparse parameter encoding: only non-default params are encoded. Each appears as (paramIdx: u8, value: KBCValue) where KBCValue is a tag-byte-prefixed payload (see Compose Tokens for the tag space). Slots not encoded resolve via the adapter's source default or the registered paramDefault.

Debug (0xF0–0xF1)

Only emitted with debugMode = true in the Gradle DSL.

Decoding a .ktx file

The ketoy analyze <path> CLI command dumps the section table; pass --json for a machine-readable form. Inside Kotlin:

import dev.ketoy.bundle.KtxReader
import dev.ketoy.bytecode.KBCInstructionDecoder

val bytes = File("main.ktx").readBytes()
val bundle = KtxReader(verifySignature = false).read(bytes)

for ((i, fn) in bundle.functions.withIndex()) {
    println("fn[$i] ${fn.name} — ${fn.code.size} bytes, ${fn.localCount} locals")
    val decoded = KBCInstructionDecoder.decodeAll(fn.code, bundle.stringPool)
    decoded.forEach { println("  $it") }
}

Each KBCInstruction sealed-class variant carries typed operand fields.

Operand layout cheatsheet

Register     u8        (0..255 per function)
String pool  u16 idx   (0..65535)
Function     u16 idx   (0..65535)
Adapter id   u16
Cap id       u16
PC           i32       (byte offset within function code)
Int literal  i32
Long literal i64
Float lit    f32 (4 bytes)
Double lit   f64 (8 bytes)

The full opcode list lives in KBCOpcode.kt; human-readable descriptors in KBCOpcodeInfo.kt; the typed data class variants in KBCInstruction.kt.

Next: .ktx Bundle Format →