Instruction

The Instruction class represents a single Lua VM bytecode instruction, including its opcode, operands, and cross-references to other instructions, constants, and chunks.

Namespace

IronBrew2.Bytecode_Library.IR

Properties

OpCode

Opcode

The operation code specifying what action this instruction performs (e.g., Move, Add, LoadConst, Jmp)

InstructionType

The instruction encoding type: ABC, ABx, AsBx, AsBxC, or Data

ConstantMask

InstructionConstantMask

Bitmask indicating which operands reference constants

int

First operand (typically a register index)

int

Second operand (register, constant, or jump offset depending on opcode)

int

Third operand (register, constant, or unused depending on opcode)

Data

int

Raw instruction data (32-bit encoded instruction)

int

Program counter (instruction index within the chunk)

Line

int

Source line number for debugging

Chunk

Reference to the parent chunk containing this instruction

RefOperands

object[]

Array of 3 object references that operands may point to:

Constants (for LoadConst, GetGlobal, etc.)
Instructions (for Jmp, ForLoop, etc.)
Chunks (for Closure)

BackReferences

List<Instruction>

List of instructions that reference this instruction (e.g., jump targets)

CustomData

CustomInstructionData

Custom data used during obfuscation and VM virtualization

Constructors

Copy Constructor

public Instruction(Instruction other)

Creates a copy of an existing instruction.

other

Instruction

required

The instruction to copy

Create New Instruction

public Instruction(Chunk chunk, Opcode code, params object[] refOperands)

Creates a new instruction with the specified opcode and reference operands.

chunk

Chunk

required

The parent chunk containing this instruction

code

Opcode

required

The operation code for this instruction

refOperands

object[]

Variable-length array of reference operands (Constants, Instructions, or Chunks)

The constructor automatically sets up back-references, so instructions or constants referenced in refOperands will have this instruction added to their BackReferences list.

Methods

UpdateRegisters

public void UpdateRegisters()

Updates the A, B, C, and PC fields based on RefOperands and the instruction’s position in the chunk. This converts high-level references (Constants, Instructions, Chunks) into numeric operand values.

Call this method before serializing instructions to bytecode to ensure operands are encoded correctly.

Opcode-specific behavior:

LoadConst, GetGlobal, SetGlobal: Sets B to the constant’s index
Jmp, ForLoop, ForPrep: Sets B to the relative jump offset
Closure: Sets B to the nested chunk’s index
Arithmetic/Table ops: Adds 256 to B/C if they reference constants

SetupRefs

public void SetupRefs()

Converts numeric operand values (A, B, C) back into RefOperands references. This is the inverse of UpdateRegisters and is called after deserializing bytecode. Opcode-specific behavior:

LoadConst, GetGlobal, SetGlobal: RefOperands[0] = Constants[B]
Jmp, ForLoop, ForPrep: RefOperands[0] = Instructions[PC + B + 1]
Closure: RefOperands[0] = Functions[B]
Arithmetic/Table ops: RefOperands[0/1] = Constants[B/C - 256] if B/C > 255

SetupRefs also registers back-references, adding this instruction to the BackReferences list of any referenced objects.

Instruction Types

ABC

InstructionType

Three operands: A (8 bits), B (9 bits), C (9 bits)

ABx

InstructionType

Two operands: A (8 bits), Bx (18 bits unsigned)

AsBx

InstructionType

Two operands: A (8 bits), sBx (18 bits signed)

AsBxC

InstructionType

Custom type with signed Bx and C operand

Data

InstructionType

Raw data instruction (used after SetList with C=0)

Usage Example

using IronBrew2.Bytecode_Library.IR;
using IronBrew2.Bytecode_Library.Bytecode;

// Create a new instruction
Chunk chunk = new Chunk();
Constant strConst = new Constant { Type = ConstantType.String, Data = "Hello" };
chunk.Constants.Add(strConst);

// LoadConst instruction: load constant into register 0
Instruction loadInstr = new Instruction(chunk, Opcode.LoadConst, strConst);
loadInstr.A = 0; // Destination register
chunk.Instructions.Add(loadInstr);

// Create a jump instruction
Instruction targetInstr = new Instruction(chunk, Opcode.Return);
chunk.Instructions.Add(targetInstr);

Instruction jumpInstr = new Instruction(chunk, Opcode.Jmp, targetInstr);
jumpInstr.A = 0;
chunk.Instructions.Insert(0, jumpInstr);

// Update mappings and registers before serialization
chunk.UpdateMappings();
foreach (var instr in chunk.Instructions)
    instr.UpdateRegisters();

// Check back-references
Console.WriteLine($"Target has {targetInstr.BackReferences.Count} jumps to it");

Working with RefOperands

// Check what an operand references
if (instruction.RefOperands[0] is Constant constant)
{
    Console.WriteLine($"References constant: {constant.Data}");
}
else if (instruction.RefOperands[0] is Instruction target)
{
    Console.WriteLine($"Jumps to PC: {chunk.InstructionMap[target]}");
}
else if (instruction.RefOperands[0] is Chunk function)
{
    Console.WriteLine($"Creates closure for: {function.Name}");
}

Core API

Bytecode Library

VM Generation

Namespace

Properties

Constructors

Copy Constructor

Create New Instruction

Methods

UpdateRegisters

SetupRefs

Instruction Types

Usage Example

Working with RefOperands

See Also

Build docs developers (and LLMs) love

Core API

Bytecode Library

VM Generation

Documentation Index

​Namespace

​Properties

​Constructors

​Copy Constructor

​Create New Instruction

​Methods

​UpdateRegisters

​SetupRefs

​Instruction Types

​Usage Example

​Working with RefOperands

​See Also

Build docs developers (and LLMs) love

Namespace

Properties

Constructors

Copy Constructor

Create New Instruction

Methods

UpdateRegisters

SetupRefs

Instruction Types

Usage Example

Working with RefOperands

See Also