Opcode Quick Reference

The instruction set on one page. The normative version — with stack effects, errors, and the validator rules — is the opcode reference.

[..., a, b] means b is on top. k = constant index, s = slot, u = upvalue index, t = absolute jump target. Result and argument counts are biased: 0 means MULTRET, n means n-1 values (Lab 17).

Constants and Literals

Op	Operands	Effect
`LOAD_CONST`	`k:u16`	push `constants[k]`
`LOAD_INT`	`n:i32`	push `Integer(n)` — inline, no pool slot
`LOAD_NIL`		push `Nil`
`LOAD_TRUE` / `LOAD_FALSE`		push the boolean

Locals and Stack

Op	Operands	Effect
`GET_LOCAL`	`s:u8`	push `stack[base+s]` — one add, one load
`SET_LOCAL`	`s:u8`	pop into `stack[base+s]`
`POP`	`n:u8`	drop `n` — how a scope closes

Globals

Op	Operands	Effect
`GET_GLOBAL`	`k:u16`	push `globals[constants[k]]`; missing → `Nil`
`SET_GLOBAL`	`k:u16`	pop into the globals table

Upvalues

Op	Operands	Effect
`GET_UPVAL`	`u:u8`	push the upvalue's value (open → stack, closed → heap)
`SET_UPVAL`	`u:u8`	pop into the upvalue
`CLOSE_UPVALS`	`s:u8`	close every open upvalue at or above `base+s`, then truncate

Arithmetic and Unary

Op	Stack	Errors
`ADD` `SUB` `MUL`	`[a,b] → [c]`	non-number operand
`DIV` `POW`	`[a,b] → [Float]`	non-number operand
`IDIV` `MOD`	`[a,b] → [c]`	non-number; integer divisor 0
`CONCAT`	`[a,b] → [Str]`	operand not string/number
`NEG`	`[a] → [b]`	non-number
`NOT`	`[a] → [Bool]`	never errors
`LEN`	`[a] → [Int]`	not a string or table

Comparison

Op	Stack	Errors
`EQ` `NE`	`[a,b] → [Bool]`	never error
`LT` `LE` `GT` `GE`	`[a,b] → [Bool]`	incomparable types

GT/GE exist because Ember guarantees left-to-right operand evaluation and therefore cannot use Lua's operand-swap trick.

Jumps

Op	Operands	Effect
`JUMP`	`t:u32`	`ip = t`
`JUMP_IF_FALSE`	`t:u32`	pop; jump if falsy
`JUMP_IF_FALSE_KEEP`	`t:u32`	peek; jump if falsy; does not pop — for `and`
`JUMP_IF_TRUE_KEEP`	`t:u32`	peek; jump if truthy; does not pop — for `or`

Calls, Returns, Closures

Op	Operands	Effect
`CALL`	`argc:u8, nres:u8`	callee sits below its args; `nres = 0` → all results
`RETURN`	`n:u8`	`n = 0` → all; closes upvalues before truncating
`CLOSURE`	`p:u16`	build a closure from `protos[p]`, capturing per its descriptors

Tables

Op	Operands	Stack
`NEW_TABLE`		`[] → [Table]`
`GET_INDEX`		`[t,k] → [v]`
`SET_INDEX`		`[t,k,v] → []`
`GET_FIELD`	`k:u16`	`[t] → [v]` — constant key; the inline-cache site
`SET_FIELD`	`k:u16`	`[t,v] → []`
`SET_LIST`	`n:u16, off:u32`	`[t,v₁..vₙ] → [t]`
`SELF_FIELD`	`k:u16`	`[t] → [t.k, t]` — evaluates `t` once

Numeric `for`

Op	Operands	Effect
`FOR_PREP`	`t:u32`	validate; convert; compute the iteration count; jump to `t` if zero
`FOR_LOOP`	`t:u32`	decrement the count; advance; jump back to `t` if positive

Counting down is what makes for i = math.maxinteger - 1, math.maxinteger do terminate.

Varargs

Op	Operands	Effect
`VARARG`	`n:u8`	push `n-1` varargs; `0` → all

Validator Rules

code.len() == lines.len()
Constant indices in range
Name operands are string constants
Jump targets ≤ code.len(), and none is u32::MAX (unpatched)
Slot numbers < max_stack
Upvalue indices < upvals.len()
Proto indices in range
The last instruction is a RETURN
Stack-depth abstraction: never negative, agrees at every join, ends at 0

Rule 9 is only tractable because Ember is a stack machine — the same reason the JVM and WebAssembly chose one.

Comparison

	Ember	Lua 5.4	CPython 3.12	JVM	Wasm 1.0
Model	stack	register	stack	stack	stack
Opcodes	~44	83	~120	202	~180
Instruction size	8 B enum	4 B packed	2 B + caches	1–n B	LEB128
Jump targets	absolute	relative	relative	relative	structured
Verification	validator	none	none	full	full

Next: ADR Index.

Open-Source Engineer & Contributor