A High-Performance Virtual Machine for Delphi

🚧 NitroVM is a Work in Progress

NitroVM is currently under active development and evolving quickly. Some features described in this documentation may be incomplete, experimental, or subject to significant changes as the project matures.

We welcome your feedback, ideas, and issue reports — your input will directly influence the direction and quality of NitroVM as we strive to build the ultimate modern Pascal development platform.

Overview

NitroVM is a high-performance, stack-based virtual machine designed specifically for Delphi applications. It provides a flexible and efficient platform for executing custom bytecode with full type safety and comprehensive error handling.

Key Features

• 🚀 High Performance: Optimized execution engine with separate opcode and operand arrays
• 📚 Stack-Based Architecture: Clean, predictable execution model
• 🔧 Fluent Interface: Chainable method calls for elegant code
• 💾 Binary Program Format: Efficient loading and saving with checksums
• 🛡️ Type Safety: Full integration with Delphi's RTTI system
• 🎯 Comprehensive Error Handling: Detailed exception information with VM state
• 📦 Extensible Opcode System: Easy registration of custom operations
• 🔍 Debug Support: Rich debugging information and step-by-step execution

Requirements

• Platform: Windows 64-bit
• Compiler: Delphi 12 Athens or higher

Installation

1. Clone the repository:

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

2. Add the NitroVM.pas unit to your Delphi project

3. Add NitroVM to your uses clause:

uses
  NitroVM;

Quick Start

Basic Usage

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;

Program Persistence

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;

Architecture

Stack Operations

NitroVM uses a stack-based execution model where all operations work with values on the execution stack:

// 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 Registration

Register custom operations with or without operands:

// 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);

Error Handling

NitroVM provides comprehensive error information:

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;

Standard Opcodes

Opcode	Name	Description
0	OP_NOP	No operation
1	OP_STOP	Stop execution
2	OP_ADD	Add two values
3	OP_SUB	Subtract two values
4	OP_MUL	Multiply two values
5	OP_DIV	Divide two values
6	OP_POP	Pop and discard top value
7	OP_DUP	Duplicate top value
8	OP_SWAP	Swap top two values
9	OP_ROT	Rotate top three values
10	OP_PUSH	Push operand value
11	OP_JUMP	Jump to address
12	OP_CALL	Call subroutine
13	OP_LOAD	Load from memory
14	OP_STORE	Store to memory
15	OP_JZ	Jump if zero
16	OP_JNZ	Jump if not zero

File Format

NitroVM uses a binary format (.nvm) with the following structure:

Header (32 bytes)

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)

Data Sections

• Code Section: Encoded opcodes with operand flags
• Data Section: Type-preserved operands (Integer, Double, Boolean, String)

Advanced Features

Step-by-Step Execution

// 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

Program Building

// 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);

VM State Management

// 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

Performance Considerations

• Separate Arrays: Opcodes and operands stored separately for cache efficiency
• Inline Functions: Critical paths use inlined methods
• Minimal Allocations: Efficient memory management with pre-allocated arrays
• Direct Dispatch: Fast opcode handler lookup without virtual calls

🏆 Contributors

Join our growing community of developers building the future of Pascal development!

📄 License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

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.

📞 Support & Community

💬 Community Channels

• 🐛 Issues: GitHub Issues - Bug reports & feature requests
• 💬 Discussions: GitHub Discussions - General questions & ideas
• 💬 Discord: Join our community - Real-time chat & support
• 🐦 Bluesky: @tinybiggames.com - Updates & announcements

🌟 Acknowledgments

• 💖 Built with love for the Delphi community
• 🚀 Focused on practical, real-world usage scenarios
• 🏆 Committed to enterprise-grade quality and performance
• 🌍 Supporting the future of Pascal application development

🎖️ Special Thanks

• Delphi Community - For continued support and feedback
• Beta Testers - Early adopters who helped shape NitroVM
• Contributors - Everyone who has submitted issues, PRs, and improvements

---

Made with ❤️ by tinyBigGAMES™

NitroVM - Powering the next generation of Delphi applications with high-performance virtual machine technology.