.QVM -- Script Bytecode (VM v8.5)

1. Architectural Role & Engine Purpose

The QVM (Innerloop Virtual Machine) file format executes all mission logic, AI behavior state machines, guard alert responses, alarm networks, security cameras, weapon firing logic, and in-engine cutscenes in Project I.G.I.: I'm Going In (2000).

The Innerloop VM was derived from / inspired by the Quake virtual machine, but it is not directly related to it: QVM uses its own LOOP container, its own 49-opcode instruction set, and its own registrar-based native bridging. Despite the shared inspiration, nothing about the bytecode is Quake-compatible.

Innerloop Studios designed a stack-based virtual machine executing bytecode version VM v8.5 (encoded as major version 8, minor version 5). The binary payload is self-contained with its own symbol and string pools, allowing O(1) table lookups and deterministic execution on 32-bit x86 hardware.

2. Binary File Layout & Memory Map Diagram

The QVM file uses a contiguous 32-bit layout where the 60-byte header defines explicit byte offsets and lengths for all five payload sections:

3. Engine Pipeline & Architecture Data Flow Diagram

At runtime, the QVM subsystem operates as an integrated virtual machine embedded directly into the native game loop of IGI.EXE. The script engine dispatches bytecode on every simulation tick:

4. Architectural Mechanics & Engine Implementation Details

The QVM virtual machine uses a stack-oriented evaluation model. Instructions push values onto a 32-bit operand stack and consume them during arithmetic, relational, and control flow operations:

• Stack Width: The operand stack is composed of 32-bit slots. Both 32-bit integers and 32-bit IEEE 754 floating-point values share the same stack slots without runtime tagging.
• O(1) Symbol Resolution: Identifiers and string literals are referenced via 0-based indices into the ITable and STable arrays. During script execution, string lookups require zero hashing or runtime scanning.
• Native Function Bridging: When the bytecode executes a native call (CALL opcode 0x18), it indexes into an internal native registration table in IGI.EXE. Arguments are popped directly from the VM operand stack and passed into native x86 stdcall/cdecl C functions.
• Subroutine Control Flow: Script logic flows through BRA (0x14), conditional BF (0x15) / BT (0x16) branches, JSR (0x17) and RET (0x13). CALL (0x18) stores a 32-bit count followed by that many 32-bit targets, which is how both script subroutines and native engine methods are reached.

5. Binary Header Specification (60 Bytes)

6. C++ Struct Definitions

// QVM Header Definition (60 Bytes)
#pragma pack(push, 1)
struct QvmHeader {
    char     signature[4];  // "LOOP"
    uint32_t ver_major;     // 8
    uint32_t ver_minor;     // 5
    uint32_t of_itable;     // Offset to Identifier Table
    uint32_t of_ivalue;     // Offset to Identifier Strings
    uint32_t sz_itable;     // Size of Identifier Table
    uint32_t sz_ivalue;     // Size of Identifier String Pool
    uint32_t of_stable;     // Offset to String Table
    uint32_t of_svalue;     // Offset to String Values
    uint32_t sz_stable;     // Size of String Table
    uint32_t sz_svalue;     // Size of String Value Pool
    uint32_t of_ctable;     // Offset to Bytecode Section
    uint32_t sz_ctable;     // Size of Bytecode Section
    uint32_t unknown_1;     // Unknown, unused by parser
    uint32_t unknown_2;     // Unknown, unused by parser
};
static_assert(sizeof(QvmHeader) == 60, "QvmHeader must be 60 bytes");
#pragma pack(pop)

7. VM Instruction Set (49 Opcodes)

The VM executes 49 distinct opcodes encoded as single bytes (0x00 – 0x30):