🚧 This repository is currently under construction.

JetVM is actively being developed and rapidly evolving. Some features mentioned in this documentation may not yet be fully implemented, and both APIs and internal structure are subject to change as we continue to improve and expand the library.

Your contributions, feedback, and issue reports are highly valued and will help shape NitroVM into the ultimate Pascal development platform!

JetVM is a A high-performance, stack-based virtual machine with native Delphi integration. It bridges the gap between performance and safety. Execute bytecode with configurable validation levels, from maximum speed to fully bounds-checked safe execution.

• Uses native Delphi strings and memory management
• Seamless integration with existing Delphi functions
• Call native Delphi procedures directly from VM code
• Zero external dependencies

• Cache-friendly data layout for hot execution paths
• Multiple validation levels for speed vs safety tradeoffs
• Optimized execution core with selective bounds checking
• Tagged union design for maximum type performance

// Choose your safety level:
TJetVMValidationLevel = (
  vlNone,        // Maximum speed - no checks
  vlBasic,       // Emit-time validation only  
  vlDevelopment, // Stack tracking, type hints
  vlSafe         // Full runtime bounds checking
);

// Beautiful, chainable bytecode generation
VM := TJetVM.Create(vlDevelopment);
try
  VM.LoadInt(42)
    .LoadInt(100)
    .AddInt()
    .StoreLocal(0)
    .CallFunction('PrintResult')
    .Stop()
    .Execute();
finally
  VM.Free;
end;

• Integers: Int64 & UInt64 with full arithmetic
• Strings: Native Delphi string operations (Concat, Length, Copy, Pos, etc.)
• Booleans: Native boolean logic and comparisons
• Pointers: Safe pointer arithmetic and dereferencing
• Arrays: Fixed and dynamic arrays with bounds checking
• Parameters: Pascal-style modes (const, var, out)

• Step-by-step execution for debugging
• Stack and constant inspection
• Instruction disassembly with function names
• Memory allocation tracking
• Comprehensive error messages with PC information

JetVM follows a three-phase architecture:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Fluent API     │───▶│  Bytecode Gen   │───▶│  Execution      │
│  (Build Phase)  │    │  (Compile Phase)│    │  (Runtime Phase)│
└─────────────────┘    └─────────────────┘    └─────────────────┘
        │                       │                       │
        ▼                       ▼                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ TJetValue       │    │ Constants Pool  │    │ Stack Machine   │
│ Type System     │    │ Label Patching  │    │ Function Calls  │
└─────────────────┘    └─────────────────┘    └─────────────────┘

• Performance First: Cache-friendly data structures
• Type Safety: Tagged union system with validation levels
• Native Integration: Seamless Delphi function calls
• Memory Efficiency: Managed/unmanaged type separation
• Developer Experience: Fluent API with comprehensive errors

For detailed architecture documentation, see DEVELOPER-GUIDE.md

• 🔧 Business Rules: Execute complex business logic safely in ERP systems
• 📋 Report Generators: Dynamic report calculation engines with user-defined formulas
• ⚙️ Workflow Automation: Safe script execution in enterprise workflow management
• 🛡️ Security Sandboxing: Run untrusted configuration scripts with configurable safety
• 📊 Data Processing: High-performance data transformation pipelines

• 🎪 Game Scripting: In-game behavior, quests, and event handling systems
• 🏆 Mod Support: Safe user-generated content execution
• 📊 Data-Driven Design: Configuration systems and game rule engines
• ⚙️ Logic Systems: Custom game mechanics and rule processing

• 📚 VM Concepts: Clean, understandable implementation for learning virtual machine design
• ⚡ Algorithm Testing: Controlled performance benchmarking and algorithm prototyping
• 🧪 Language Design: Rapid prototyping of new language features and concepts
• 🎯 Performance Analysis: Isolated execution environments for precise measurements

• 📋 Rule Engines: Execute business rules in a controlled environment
• ⚙️ Configuration Languages: Create domain-specific languages for your applications
• 🛠️ Plugin Systems: Safe execution of third-party plugins and extensions
• 📈 Calculators: Advanced calculation engines with custom functions

• Core Infrastructure: ✅ Production Ready (100% test coverage)
• Value System: ✅ Fully Implemented (54 comprehensive tests)
• Basic Execution: ✅ Stable & Fast (lightning 27ms test execution)
• Advanced Features: 🔄 Active Development (stack, constants, bytecode modules)

• Q1 2025: Complete core test suite (Phases 3-5) ✅ On Track
• Q2 2025: Advanced opcode implementation & optimization
• Q3 2025: Performance benchmarking & real-world integration examples
• Q4 2025: Plugin architecture & ecosystem development tools

Based on current test results:

• VM Creation: Sub-millisecond startup time
• Value Operations: Microsecond-level execution
• Bulk Processing: 10,000+ operations in <5000ms
• Memory Management: Zero leak indicators in stress tests
• Test Execution: 0.28ms average per test (97 tests in 27ms)

• Zero Defects: No bugs detected in tested components
• 100% Pass Rate: All 97 tests consistently passing
• Enterprise Ready: Robust error handling and edge case management
• Memory Safe: Comprehensive bounds checking and leak prevention

See TEST-REPORT.md for detailed performance analysis and quality metrics.

uses
  JetVM;

var
  LVM: TJetVM;
  LResult: TJetValue;
begin
  LVM := TJetVM.Create(vlBasic);
  try
    // Simple arithmetic: 10 + 32 = 42
    LVM.LoadInt(10)
       .LoadInt(32)
       .AddInt()
       .Stop();
       
    LVM.Execute();
    
    // Get result from stack
    LResult := LVM.PeekValue();
    WriteLn('Result: ', LResult.IntValue); // Output: 42
  finally
    LVM.Free;
  end;
end;

// String manipulation with native Delphi functions
LVM.LoadStr('Hello, ')
   .LoadStr('World!')
   .ConcatStr()
   .UpperStr()
   .Stop();
   
LVM.Execute();
LResult := LVM.PeekValue();
WriteLn(LResult.StrValue); // Output: HELLO, WORLD!

// Register a native Delphi function
procedure MyPrintLine(const AVM: TJetVM);
var
  LValue: TJetValue;
begin
  LValue := AVM.PopValue();
  WriteLn('VM Output: ', LValue.StrValue);
end;

// Register and use in VM code
LVM.RegisterNativeFunction('println', @MyPrintLine, [jvtStr]);

LVM.LoadStr('Hello from VM!')
   .CallFunction('println')
   .Stop()
   .Execute();

var
  LLoopStart, LLoopEnd: Integer;
begin
  LLoopStart := LVM.CreateLabel();
  LLoopEnd := LVM.CreateLabel();
  
  // Countdown from 10 to 1
  LVM.LoadInt(10)                    // Counter
     .StoreLocal(0)
     .BindLabel(LLoopStart)          // Loop start
     .LoadLocal(0)                   // Load counter
     .LoadInt(0)
     .EqInt()                        // Check if counter == 0
     .JumpTrue(LLoopEnd)             // Exit if true
     .LoadLocal(0)                   // Load counter
     .CallFunction('println')        // Print it
     .LoadLocal(0)                   // Load counter
     .DecInt()                       // Decrement
     .StoreLocal(0)                  // Store back
     .Jump(LLoopStart)               // Loop back
     .BindLabel(LLoopEnd)            // Loop end
     .Stop();
end;

// Production-ready error handling
function SafeExecuteScript(const AVM: TJetVM): Boolean;
begin
  Result := False;
  try
    AVM.SetValidationLevel(vlSafe);  // Use safe mode for untrusted code
    AVM.Execute();
    Result := True;
  except
    on E: EJetVMError do
    begin
      WriteLn('VM Error: ', E.Message);
      WriteLn('PC: ', AVM.GetPC(), ', SP: ', AVM.GetSP());
      // Handle gracefully
    end;
  end;
end;

DEVELOPER-GUIDE.md contains 12 detailed sections:

TEST-REPORT.md provides comprehensive analysis:

• 97 tests executed with 100% pass rate
• 27ms total execution time (0.28ms average per test)
• Zero defects detected in core functionality
• Enterprise-grade stability demonstrated

• ✅ Phase 1: Core Infrastructure (43 tests) - COMPLETE
• ✅ Phase 2: Values System (54 tests) - COMPLETE
• 🔄 Phase 3: Stack Operations - IN PROGRESS
• ⏳ Phase 4: Constants Pool - PLANNED
• ⏳ Phase 5: Bytecode Generation - PLANNED

• VM Creation: Sub-millisecond startup
• Value Operations: Microsecond-level execution
• Bulk Operations: 10,000+ in <5000ms
• Memory Safety: Zero leak indicators

• Inline Documentation: Comprehensive comments in JetVM.pas
• Interface Definitions: All public methods documented
• Usage Examples: Code samples for every major feature

JetVM maintains enterprise-grade quality through comprehensive testing:

• 97 tests with 100% pass rate (Perfect success rate!)
• 27ms execution time - enables rapid development cycles
• Zero defects detected in core functionality
• Lightning performance - 0.28ms average per test

• Coverage Depth: Comprehensive edge case testing including boundary values
• Assertion Quality: Meaningful validation criteria with specific expected results
• Error Scenarios: Proper exception testing and graceful failure handling
• Performance: Baseline characteristics established for regression detection

Phase 1: Core Infrastructure   ✅ 43 tests (100% pass)
Phase 2: Values System         ✅ 54 tests (100% pass)
Phase 3: Stack Operations      🔄 In Development
Phase 4: Constants Pool        ⏳ Planned Q1 2025
Phase 5: Bytecode Generation   ⏳ Planned Q1 2025
Integration Testing            ⏳ Planned Q2 2025
Performance Benchmarks         ⏳ Planned Q2 2025

Run the comprehensive test suite:

# Execute all tests with custom logger
JetVMTests.exe

# Example output:
# ================================================================================
#                            🚀 JETVM TEST SUITE                            
# ================================================================================
# 📦 JetVM.Test.Core.TTestJetVMCore
# ✓ TestVMCreationDefault
# ✓ TestVMCreationWithValidationLevels
# ✓ TestBasicExecution
# [... 97 total tests ...]
# ================================================================================
#                            ✅ ALL TESTS PASSED
# ================================================================================
# Tests Found: 97 | Tests Passed: 97 | Duration: 27ms

See TEST-REPORT.md for detailed analysis and performance metrics.

• Delphi XE2 or later (requires modern generics, Unicode, and 64-bit support)
• Tested with: Delphi 12 on Windows 11 (24H2)
• Platform Support: Windows (tested and supported)
• Dependencies: None (pure Delphi implementation)

1. Clone the repository:

   git clone https://github.com/tinyBigGAMES/JetVM.git
   cd JetVM

2. Add to your Delphi project:

   • Add JetVM.pas to your project
   • Include JetVM.Defines.inc in your project path
   • Add JetVM to your uses clause

3. Optional: Include test framework:

   // For comprehensive testing (optional)
   uses
     JetVM.Test.Core,
     JetVM.Test.Values,
     JetVM.Test.Logger;  // Custom DUnitX logger

4. Verify installation:

   // Quick verification
   var LVM := TJetVM.Create(vlBasic);
   try
     LVM.LoadInt(42).Stop().Execute();
     Assert(LVM.PopValue().IntValue = 42);
   finally
     LVM.Free;
   end;

// Essential Methods
procedure Execute();              // Run the VM
procedure Step();                 // Single-step execution
procedure Reset();                // Reset VM state
procedure Finalize();             // Finalize bytecode

// State Access
function GetPC(): Integer;        // Program Counter
function GetSP(): Integer;        // Stack Pointer
function IsRunning(): Boolean;    // Execution state

// Stack Operations
procedure PushValue(const AValue: TJetValue);
function PopValue(): TJetValue;
function PeekValue(const AOffset: Integer = 0): TJetValue;

// Value Types
TJetValueType = (jvtInt, jvtUInt, jvtStr, jvtBool, jvtPointer, 
                jvtArrayInt, jvtArrayUInt, jvtArrayStr, jvtArrayBool);

// Factory Methods
function MakeIntConstant(const AValue: Int64): TJetValue;
function MakeStrConstant(const AValue: string): TJetValue;
// ... additional factory methods

// Function Registration
function RegisterNativeFunction(const AName: string; 
  const AProc: TJetNativeFunction; 
  const AParamTypes: array of TJetValueType;
  const AReturnType: TJetValueType): Integer;

We welcome contributions! Our codebase maintains 100% test coverage and enterprise-grade quality.

1. Fork & Clone

   git clone https://github.com/YOUR_USERNAME/JetVM.git
   cd JetVM

2. Follow Our Standards (See DEVELOPER-GUIDE.md Section 10)

   // Delphi Conventions (CRITICAL)
   var
     LValue: TJetValue;     // Local variables start with 'L'
     LResult: Integer;      // Each variable on separate line
   
   procedure MyProc(const AParam: string);  // Parameters start with 'A'

3. Add Comprehensive Tests

   // Follow existing test patterns
   [Test]
   procedure TestYourNewFeature();
   begin
     Assert.AreEqual(Expected, Actual, 'Meaningful error message');
   end;

4. Ensure Quality

   # All tests must pass
   JetVMTests.exe
   # Expected: 100% pass rate maintained

• Naming: L prefix for locals, A prefix for parameters
• Declarations: Each variable on separate line, no inline var
• Parameters: Always const unless var/out needed
• Testing: Comprehensive tests for all new functionality
• Documentation: Update relevant guides and inline docs

• 🔧 Core Features: New opcodes, optimization improvements
• 📚 Documentation: Examples, tutorials, API documentation
• 🧪 Testing: Additional test cases, performance benchmarks
• 🎨 Tooling: Development utilities, debugging aids
• 🌍 Examples: Real-world usage demonstrations

• 🪟 Windows: ✅ Fully supported and tested
• 🐧 Linux: ❓ Community testing welcome
• 🍎 macOS: ❓ Community testing welcome

Help us expand platform support by testing JetVM on Linux/macOS and reporting results! Since JetVM uses pure Delphi code, it may work on other platforms but needs validation.

Join our growing community of developers building the future of Delphi scripting!

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.

• 📖 DEVELOPER-GUIDE.md - 12-section comprehensive development guide
• 📊 TEST-REPORT.md - Current test coverage & performance metrics
• 🔧 API Reference - Inline documentation in JetVM.pas
• 📋 Examples - Real-world usage patterns in test suites

• 🐛 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

Q: What Delphi versions are supported?
A: Delphi XE2 (2012) or later. Requires modern generics support and 64-bit compilation capabilities. Actively tested with Delphi 12 on Windows 11 (24H2).

Q: What platforms are supported?
A: Currently Windows only (actively developed and tested). While JetVM uses pure Delphi code that may work on Linux/macOS, these platforms are untested and unsupported. Community testing and feedback for other platforms is welcome.

Q: How does performance compare to other VMs?
A: Current benchmarks show sub-millisecond VM creation and microsecond-level value operations (0.28ms average per test). Comprehensive performance benchmarking is planned for Q2 2025. See TEST-REPORT.md for current measured performance data.

Q: Is JetVM suitable for production use?
A: Yes! Core infrastructure has 100% test coverage and zero detected defects.

Q: Can I integrate my existing Delphi functions?
A: Absolutely! Native function integration is a core feature with simple registration.

Q: What's the memory overhead?
A: Minimal. Uses native Delphi types and tagged unions for efficiency.

• 💖 Built with love for the Delphi community
• 🎯 Inspired by modern VM design principles (V8, LuaJIT, .NET CLR)
• 🚀 Focused on practical, real-world usage scenarios
• 🏆 Committed to enterprise-grade quality and performance
• 🌍 Supporting the future of Delphi application development

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

Made with ❤️ by tinyBigGAMES™

Empowering Delphi developers with high-performance, safe scripting capabilities. 🚀