git clone https://github.com/tinyBigGAMES/NitroVM.git

uses
  NitroVM;

uses
  NitroVM;

var
  LVM: TNitroVM;
begin
  LVM := TNitroVM.Create;
  try
    // Register custom opcodes
    LVM.RegisterOpcode(100, procedure(const AVM: TNitroVM)
      begin
        // Custom operation without operand
        AVM.Push(42);
      end);
    
    // Build and execute a program
    LVM.BeginProgram
       .AddInstruction(100)        // Push 42
       .AddInstruction(OP_PUSH, 10) // Push 10
       .AddInstruction(OP_ADD)      // Add: 42 + 10 = 52
       .AddInstruction(OP_STOP)     // Stop execution
       .ExecuteProgram;
    
    // Get result
    WriteLn('Result: ', LVM.Pop.AsInteger); // Output: 52
  finally
    LVM.Free;
  end;
end;

var
  LVM: TNitroVM;
begin
  LVM := TNitroVM.Create;
  try
    // Build program
    LVM.BeginProgram
       .AddInstruction(OP_PUSH, 100)
       .AddInstruction(OP_PUSH, 200)
       .AddInstruction(OP_MUL)
       .AddInstruction(OP_STOP);
    
    // Save to file
    LVM.SaveProgram('myprogram.nvm');
    
    // Load and execute
    LVM.Reset
       .LoadProgram('myprogram.nvm')
       .ExecuteProgram;
    
    WriteLn('Result: ', LVM.Pop.AsInteger); // Output: 20000
  finally
    LVM.Free;
  end;
end;

// Stack manipulation
LVM.Push(TValue.From<Integer>(42))    // Push value
   .Push(TValue.From<String>('Hello')) // Push string
   .Pop(LValue)                       // Pop into variable
   .ClearStack;                       // Clear all values

// Stack inspection
LSize := LVM.StackSize;               // Get current size
LTop := LVM.Peek(0);                  // Peek at top (index 0)
LSecond := LVM.Peek(1);               // Peek at second (index 1)

// Opcode without operand
LVM.RegisterOpcode(200, procedure(const AVM: TNitroVM)
  begin
    // Duplicate top stack value
    AVM.Push(AVM.Peek(0));
  end);

// Opcode with operand
LVM.RegisterOpcode(201, procedure(const AVM: TNitroVM; const AOperand: TValue)
  begin
    // Push the operand value
    AVM.Push(AOperand);
  end);

try
  LVM.ExecuteProgram;
except
  on E: ENVMException do
  begin
    WriteLn('VM Error: ', E.Message);
    WriteLn('Debug Info:');
    WriteLn(E.GetDebugInfo);
    // Shows PC, opcode, stack size, VM state
  end;
end;

Magic: 'NVM1' (4 bytes)
Version: Format version (2 bytes)
Flags: Future use (2 bytes)
CodeSize: Number of opcodes (4 bytes)
DataSize: Number of operands (4 bytes)
EntryPoint: Starting PC (4 bytes)
Checksum: Validation checksum (4 bytes)
Reserved: Future expansion (8 bytes)

// Execute one instruction at a time
while LVM.IsRunning and not LVM.IsHalted do
begin
  LVM.ExecuteStep;
  // Inspect VM state, implement breakpoints, etc.
end;

// Limited execution
LVM.ExecuteUntil(1000); // Execute max 1000 instructions

// Fluent interface for program construction
LVM.BeginProgram
   .AddInstruction(OP_PUSH, 10)
   .AddInstruction(OP_PUSH, 20)
   .AddInstruction(OP_ADD)
   .AddInstruction(OP_DUP)        // Duplicate result
   .AddInstruction(OP_PUSH, 2)
   .AddInstruction(OP_MUL)        // Multiply by 2
   .AddInstruction(OP_STOP);

// Reset VM to initial state
LVM.Reset;

// Check execution state
if LVM.IsRunning then
  WriteLn('VM is executing');

if LVM.IsHalted then
  WriteLn('VM was halted');

// Manual control
LVM.Stop;  // Force halt

BSD 3-Clause License

Copyright ?? 2025-present tinyBigGAMES??? LLC
All Rights Reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice
2. Redistributions in binary form must reproduce the above copyright notice
3. Neither the name of the copyright holder nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.