🚧 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

Clone the repository:

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

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

Optional: Include test framework:

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

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

Fork & Clone

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

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'

Add Comprehensive Tests

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

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

tinyBigGAMES/JetVM