Instruction

Represents a single Lua bytecode instruction with operands and references

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

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

ConstantMask · InstructionConstantMask

Bitmask indicating which operands reference constants

A · int

First operand (typically a register index)

B · int

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

C · int

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

Data · int

Raw instruction data (32-bit encoded instruction)

PC · int

Program counter (instruction index within the chunk)

Line · int

Source line number for debugging

Chunk · 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}");
}

See Also

• Chunk - Container for instructions
• Deserializer - Decode instructions from bytecode
• Serializer - Encode instructions to bytecode