🚧 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 JetVM into the ultimate Pascal development platform!

🚀 JetVM - Fast Delphi Virtual Machine

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.

✨ Features

🎯 Native Delphi Integration

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

⚡ Performance-Focused

• 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

🛡️ Configurable Safety

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

🔧 Modern Fluent API

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

🎨 Rich Type System

• Integers: Int64 & UInt64 with full arithmetic
• Strings: Native Delphi string operations (Concat, Length, Copy, Pos, etc.)
• Booleans: Logical operations and flow control
• Pointers: Type-safe pointer operations with bounds checking
• Arrays: Dynamic and fixed arrays with element access

📊 Comprehensive Bytecode Support

• 140+ optimized opcodes covering all core operations
• Fluent assembly interface for readable code generation
• Compile-time validation with detailed error reporting
• Label management with forward reference resolution

🎯 Use Cases

JetVM excels in scenarios requiring safe execution of untrusted code:

• 🎮 Game Scripting: Player mods, AI behaviors, quest systems
• 📊 Data Processing: User-defined calculations, transformations, filters
• 🔌 Plugin Systems: Safe execution of third-party plugins and extensions
• 📈 Calculators: Advanced calculation engines with custom functions

📈 Project Status

🚀 Current State

• Core Infrastructure: ✅ Production Ready (100% test coverage)
• Value System: ✅ Fully Implemented (comprehensive test coverage)
• Stack Operations: ✅ Complete & Validated (comprehensive test coverage)
• Constants Pool: ✅ Complete & Tested (comprehensive test coverage)
• Bytecode Generation: ✅ Complete & Fluent (comprehensive test coverage)

🎯 Development Roadmap

• Q1 2025: Complete core test suite ✅ COMPLETE
• Q2 2025: Advanced opcode implementation & optimization
• Q3 2025: Performance benchmarking & real-world integration examples
• Q4 2025: Plugin architecture & ecosystem development tools

⚡ Performance Benchmarks

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.0003s average per test (1,093 tests in 0.371s)

🏆 Quality Metrics

• Zero Defects: No bugs detected in tested components
• 100% Pass Rate: All 1,093 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.

🚀 Quick Start

Basic Usage

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 Operations

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

Native Function Integration

// 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!')
   .CallNative('println')
   .Stop();
   
LVM.Execute(); // Output: VM Output: Hello from VM!

Advanced: Conditional Logic

// if (x > 10) then result := x * 2 else result := x + 5
LVM.LoadInt(15)        // Load x = 15
   .Dup()              // Duplicate for comparison
   .LoadInt(10)        // Load comparison value
   .GreaterThanInt()   // x > 10?
   .JumpIfFalse('else_branch')
   
   // True branch: x * 2
   .LoadInt(2)
   .MultiplyInt()
   .Jump('end')
   
   .Label('else_branch')
   // False branch: x + 5  
   .LoadInt(5)
   .AddInt()
   
   .Label('end')
   .Stop();

LVM.Execute();
LResult := LVM.PeekValue();
WriteLn('Result: ', LResult.IntValue); // Output: 30

📖 Documentation

📚 Comprehensive Developer Guide

DEVELOPER-GUIDE.md contains 12 detailed sections:

Section	Content	Pages
🏗️ Architecture	Project overview, core features, performance characteristics	📄📄
💎 Value System	TJetValue tagged union, memory layout, type safety	📄📄📄
🛡️ Validation Levels	Performance vs safety, level switching, benchmarks	📄📄
⛓️ Fluent Interface	Bytecode generation, method chaining, complex expressions	📄📄📄
🎯 Execution Model	Stack machine, state management, control flow	📄📄📄
📞 Function System	Native integration, VM functions, parameter modes	📄📄📄
🧠 Memory Management	Automatic cleanup, bounds checking, debugging utilities	📄📄
🎪 Practical Examples	Calculator engines, game scripting, data processing	📄📄📄📄
⚡ Performance Guide	Optimization strategies, validation selection, benchmarking	📄📄
✅ Best Practices	Recommended patterns, anti-patterns, testing strategies	📄📄📄
🐛 Error Handling	Debugging utilities, exception strategies, validation	📄📄
🔌 Integration	Application integration, plugin architecture, web services	📄📄📄

📊 Current Test Coverage Report

TEST-REPORT.md provides comprehensive analysis:

✅ Test Results Summary

• 1,093 tests executed with 100% pass rate
• 0.371 seconds total execution time (0.0003s average per test)
• Zero defects detected in core functionality
• Enterprise-grade stability demonstrated

📋 Component Coverage Matrix

Component	Coverage	Status	Test Count
Core VM & Execution	100%	✅ Complete	89 tests
Memory & Storage	100%	✅ Complete	260 tests
Control Flow	100%	✅ Complete	233 tests
Operations	100%	✅ Complete	182 tests
Data Types	100%	✅ Complete	169 tests
Infrastructure	100%	✅ Complete	54 tests

🎯 Test Distribution by Category

• Memory & Storage: 260 tests (23.8%) - Stack, Registers, Memory, Pointers, Arrays
• Control Flow: 233 tests (21.3%) - Control Flow, Labels, Functions, Parameters
• Operations: 182 tests (16.7%) - Arithmetic, Bitwise, Comparisons, Strings
• Data Types: 169 tests (15.5%) - Values, Type Conversion, Constants
• Core VM: 142 tests (13.0%) - Core, Execution, Validation
• Infrastructure: 54 tests (4.9%) - Bytecode Generation

⚡ Performance Metrics

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

🔧 API Reference

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

🧪 Testing & Quality Assurance

JetVM maintains enterprise-grade quality through comprehensive testing:

✅ Current Test Status

• 1,093 tests with 100% pass rate (Perfect success rate!)
• 0.371 seconds execution time - enables rapid development cycles
• Zero defects detected in core functionality
• Lightning performance - 0.0003s average per test

📋 Test Coverage Breakdown

Component	Tests	Coverage	Status
Arithmetic Operations	44	100%	✅ Production Ready
Array Management	61	100%	✅ All Operations Covered
Bitwise Operations	42	100%	✅ Complete Implementation
Bytecode Generation	54	100%	✅ Fluent Interface Ready
Comparison Operations	46	100%	✅ All Types Validated
Constants Pool	50	100%	✅ Complete Management
Control Flow	79	100%	✅ All Patterns Tested
VM Core & Lifecycle	43	100%	✅ Production Ready
Execution Engine	46	100%	✅ Robust Operation
Function System	69	100%	✅ Native Integration
Label Management	37	100%	✅ Forward References
Memory Management	31	100%	✅ Leak Prevention
Parameter Handling	48	100%	✅ All Modes Tested
Pointer Operations	72	100%	✅ Memory Safety
Register System	48	100%	✅ Complete Access
Stack Operations	48	100%	✅ Fully Validated
String Operations	50	100%	✅ Unicode Support
Type Conversion	69	100%	✅ Safe Casting
Validation System	53	100%	✅ Error Prevention
Value System	50	100%	✅ All Types Covered

🎯 Quality Indicators

• 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

🚀 Test Phases Progress

Phase 1: Core Infrastructure    ✅ 1,093 tests (100% pass)
Phase 2: Advanced Features      ⏳ Planned Q2 2025
Phase 3: Integration Testing    ⏳ Planned Q2 2025
Phase 4: Performance Benchmarks ⏳ Planned Q2 2025

📊 Test Execution

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
# [... 1,093 total tests across 20 fixtures ...]
# ================================================================================
#                            ✅ ALL TESTS PASSED
# ================================================================================
# Tests Found: 1,093 | Tests Passed: 1,093 | Duration: 0.371s

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

📦 Installation

Prerequisites

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

Setup

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;

📚 Documentation Overview

Core Classes & Interfaces

TJetVM - Main Virtual Machine

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

TJetValue - Tagged Union Type System

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

TJetFunctionRegistry - Function Management

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

Instruction Set Categories

Category	Instructions	Description	Examples
Load/Store	LoadInt, LoadStr, StoreLocal, StoreGlobal	Data movement	Variable access
Arithmetic	AddInt, SubInt, MulInt, DivInt, ModInt	Math operations	Calculations
Comparison	EqInt, LtInt, GtInt, EqStr, LtStr	Value comparisons	Conditionals
Control Flow	Jump, JumpTrue, JumpFalse, Call, Return	Program flow	Loops, functions
String Ops	ConcatStr, LenStr, UpperStr, LowerStr	String manipulation	Text processing
Memory	Alloc, FreeMem, MemCopy, LoadPtrInt	Memory management	Pointer operations
Arrays	ArrayGet, ArraySet, ArrayLength	Array operations	Data structures
Functions	CallFunction, RegisterNativeFunction	Function calls	Native integration

🤝 Contributing

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

🚀 Quick Contribution Guide

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

📋 Coding Standards

• 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

🎯 Contribution Areas

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

🌍 Platform Testing Needed

• 🪟 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.

🏆 Contributors

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

📄 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

📚 Documentation & Resources

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

💬 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

❓ Frequently Asked Questions

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.0003s 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.

🌟 Acknowledgments

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

🎖️ Special Thanks

• 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. 🚀