Opcode Reference

Every instruction is a sequence of ints in the bytecode stream: one opcode int, followed by zero or more operand ints. “Size” below is the total instruction length (opcode + operands), i.e. what getOpCodeOffset() returns and how far PC advances by default.

Control & data movement

Opcode	Mnemonic	Size	Operands	Behavior
`0x01`	`CALL`	2	target offset	Push `PC + 2` onto the return stack, jump to `target offset` (used for `call`)
`0x02`	`POP`	2	variable slot	Pop the stack top into the given variable slot
`0x03`	`PUSH`	3	type tag, value	Push a value onto the stack — see below
`0x04`	`EXEC`	2	function index	Call a native function (`println`, `print`, `inputInt`, `inputStr`) — see Built-in Functions
`0x05`	`JUMP`	2	target offset	Unconditional jump (used for `jump`)
`0xFE`	`RET`	1	—	Pop the return stack and jump there (used for `endroutine`)
`0xFF`	`HLT`	1	—	Halt execution

`PUSH` type tags

The second operand of PUSH selects what the third operand means:

Tag	Meaning
`0x01`	String — third operand is an index into the string pool
`0x02`	Integer literal — third operand is the value itself
`0x03`	Variable — third operand is a variable slot to read from

Arithmetic

All arithmetic opcodes are size 1 (no operands) — they pop two int64 values off the stack, combine them, and push an int64 result. Operand order: the value pushed second (b) is popped first, so a OP b is computed correctly for non-commutative operators.

Opcode	Mnemonic	Operation
`0xA0`	`ADD`	`a + b`
`0xA1`	`SUB`	`a - b`
`0xA2`	`MUL`	`a * b`
`0xA3`	`DIV`	`a / b` (integer division)
`0xA4`	`POW`	`a ^ b`
`0xA5`	`MOD`	`a % b`

Comparison / conditional jump

Size 2 — operand is the offset to jump to if the comparison is false. All pop two values, compare as int64, and either fall through (true) or jump to the operand (false). This is exactly how if blocks compile.

Opcode	Mnemonic	Comparison
`0xB0`	`JEQ`	`==`
`0xB1`	`JGR`	`>`
`0xB2`	`JLS`	`<`
`0xB3`	`JGE`	`>=`
`0xB4`	`JLE`	`<=`
`0xB5`	`JNE`	`!=`

Strings

Opcode	Mnemonic	Size	Behavior
`0xAA`	`JOIN`	1	Pop a count `n`, then pop `n` strings off the stack and concatenate them in original order, push the result — this is what `..` compiles to

Notes

There is no dedicated float arithmetic opcode set yet — TAG_FLOAT exists in the type system (see Bytecode Format) but the current arithmetic opcodes operate on int64_t only.
Unrecognized opcodes cause the VM to print Invalid opcode and halt with an error.

Keyboard shortcuts

The Lumen Book