Chunk

Represents a Lua function chunk containing bytecode, constants, and nested functions

The Chunk class represents a compiled Lua function, containing all the bytecode instructions, constants, nested functions, and metadata needed to execute the function.

Namespace

IronBrew2.Bytecode_Library.IR

Properties

Name · string

The name of the chunk (function name or source file)

Line · int

Starting line number in the source code

LastLine · int

Ending line number in the source code

UpvalueCount · byte

Number of upvalues referenced by this chunk

ParameterCount · byte

Number of parameters the function accepts

VarargFlag · byte

Flag indicating if the function uses varargs (…)

StackSize · byte

Maximum stack size required for execution

CurrentOffset · int · default: "0"

Current register offset for stack rebasing

CurrentParamOffset · int · default: "0"

Current parameter offset for stack rebasing

Instructions · List<Instruction>

List of bytecode instructions in this chunk

InstructionMap · Dictionary<Instruction, int>

Maps instructions to their index positions for quick lookup

Constants · List<Constant>

List of constant values used by the chunk (strings, numbers, booleans, nil)

ConstantMap · Dictionary<Constant, int>

Maps constants to their index positions for quick lookup

Functions · List<Chunk>

List of nested function chunks (prototypes)

FunctionMap · Dictionary<Chunk, int>

Maps nested chunks to their index positions for quick lookup

Upvalues · List<string>

List of upvalue names

Methods

UpdateMappings

public void UpdateMappings()

Rebuild all mapping dictionaries (InstructionMap, ConstantMap, FunctionMap) based on the current list contents. This should be called after modifying the Instructions, Constants, or Functions lists to ensure mappings are synchronized.

This method clears and rebuilds all three mapping dictionaries, so call it after batch modifications rather than after each individual change.

Rebase

public int Rebase(int offset, int paramOffset = 0)

Adjusts register and parameter indices in all instructions to accommodate stack changes. This is used when merging or inlining chunks.

offset · int · required

The offset to add to register indices

paramOffset · int · default: "0"

The offset to add to parameter indices

returns · int

The ParameterCount of the chunk

The method intelligently distinguishes between parameters and regular stack values when applying offsets, handling each Lua opcode’s specific register requirements.

Usage Example

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

// Deserialize a Lua bytecode file
byte[] bytecode = File.ReadAllBytes("script.luac");
Deserializer deserializer = new Deserializer(bytecode);
Chunk mainChunk = deserializer.DecodeFile();

// Access chunk properties
Console.WriteLine($"Function: {mainChunk.Name}");
Console.WriteLine($"Instructions: {mainChunk.Instructions.Count}");
Console.WriteLine($"Constants: {mainChunk.Constants.Count}");
Console.WriteLine($"Nested functions: {mainChunk.Functions.Count}");

// Modify instructions and update mappings
mainChunk.Instructions.Add(new Instruction(mainChunk, Opcode.Return));
mainChunk.UpdateMappings();

// Rebase registers when inlining
Chunk inlinedChunk = mainChunk.Functions[0];
inlinedChunk.Rebase(mainChunk.StackSize);

Chunk Structure

A Lua chunk follows a hierarchical structure:

Chunk
├── Metadata (Name, Line info, Upvalues, Parameters)
├── Instructions (Bytecode)
├── Constants (Literals used by instructions)
└── Functions (Nested chunks/prototypes)
    └── Each function is itself a Chunk

See Also

• Instruction - Individual bytecode instructions
• Deserializer - Decode chunks from bytecode files
• Serializer - Encode chunks back to bytecode