Win32Emu

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 17 Open GitHub ↗

A Windows 32-bit PE executable emulator for running classic Windows games and applications on modern systems.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Win32Emu

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/archanox/Win32Emu)
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=archanox_Win32Emu&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=archanox_Win32Emu)
[![Codeac](https://static.codeac.io/badges/2-1063646816.svg "Codeac")](https://app.codeac.io/github/archanox/Win32Emu)
[![Codacy Badge](https://app.codacy.com/project/badge/Grade/421f38603fdf478dbffee73008830ade)](https://app.codacy.com/gh/archanox/Win32Emu/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade)
![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/archanox/Win32Emu?utm_source=oss&utm_medium=github&utm_campaign=archanox%2FWin32Emu&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)
[![Qodana](https://github.com/archanox/Win32Emu/actions/workflows/qodana_code_quality.yml/badge.svg)](https://github.com/archanox/Win32Emu/actions/workflows/qodana_code_quality.yml)

A Windows executable emulator for running classic Windows games and applications on modern systems. Supports both 32-bit PE (Win32) and 16-bit NE (Win16) executables.

## Features

- **Cross-Platform**: Runs on Windows, Linux, and macOS (both x86 and ARM)
- **Win32 & Win16 Support**: Runs both 32-bit PE and 16-bit NE executables (Win16 support is experimental)
- **Hardware-Accelerated**: Uses .NET intrinsics for CPU instruction acceleration
- **Modern CPU Support**: Automatically detects and uses SSE, AVX, and NEON instructions
- **Accurate Emulation**: Full x86 CPU and Windows API emulation
- **JIT Caching**: Persistent JIT cache to disk for faster subsequent executions with precompilation support
- **Disc Image Support**: CHD (Compressed Hunks of Data) detection and validation for CD-ROM games

## Components

### Win32Emu.Tools.Tui
Terminal User Interface (TUI) for Win32Emu, optimized for SSH access and mobile terminals.

**Features:**
- 80-column optimized layout for mobile SSH clients
- Game library management
- Interactive debugger integration
- Configuration management
- Works in terminal environments

**Usage:**
```bash
dotnet run --project Win32Emu.Tools.Tui
```

See [Win32Emu.Tools.Tui/README.md](Win32Emu.Tools.Tui/README.md) for more details.

### Win32Emu.Gui
Cross-platform desktop GUI for managing your game library and emulator settings. Built with Avalonia UI.

**Note:** This is now the primary executable for Win32Emu. The standalone CLI has been integrated into this application.

**Features:**
- Game library with thumbnail views
- File picker for adding games
- Emulator configuration (rendering backend, resolution scaling, memory, Windows version)
- One-click game launching
- **CLI mode** with `--nogui` flag for headless operation

**GUI Usage:**
```bash
# Launch the GUI application
Win32Emu.Gui
```

**CLI Usage (with --nogui flag):**
```bash
# Run in command-line mode without GUI
Win32Emu.Gui --nogui <path-to-pe> [options]
```

**CLI Options:**
- `--debug`: Enable enhanced debugging mode with automatic error detection
- `--interactive-debug`: Enable interactive step-through debugger (GDB-like)
- `--gdb-server [port]`: Start GDB server for remote debugging with Ghidra/IDA (default port: 1234)
  - Supports remote file I/O when VFS is initialized (access game files from debugger)
- `--mcp-server`: Enable MCP (Model Context Protocol) server for AI-assisted debugging
  - Allows AI assistants like GitHub Copilot to inspect and control the emulator
  - Provides tools for memory inspection, execution control, and analysis
  - See [docs/guides/MCP_DEBUGGING_GUIDE.md](docs/guides/MCP_DEBUGGING_GUIDE.md) for detailed usage
- `--backend <SDL|GLFW|Vulkan|Metal|Software>`: Select rendering backend (default: SDL)
- `--log-file [path]`: Enable logging to file (auto-generates MD5-based filename if path not provided)
  - Filename format: `<executable>_<md5hash>_<timestamp>.log`
  - Useful for capturing logs when reporting issues
- `--telemetry-console`: Enable OpenTelemetry with console exporter for logging and metrics
- `--telemetry-otlp [endpoint]`: Enable OpenTelemetry with OTLP exporter (default: http://localhost:4317)

**Environment Variables:**
- `WIN32EMU_BACKEND`: Set rendering backend (SDL, GLFW, Vulkan, Metal, or Software)
- `OTEL_EXPORTER_OTLP_ENDPOINT`: OpenTelemetry OTLP endpoint (e.g., `http://localhost:4317`)
  - Automatically enables OpenTelemetry when set
  - Useful for IDE integrations like JetBrains Rider

**CLI Examples:**
```bash
# Run normally (uses SDL backend)
Win32Emu.Gui --nogui game.exe

# Run with GLFW backend (alternative if SDL has issues)
Win32Emu.Gui --nogui game.exe --backend GLFW

# Run with Vulkan backend (uses MoltenVK on macOS)
Win32Emu.Gui --nogui game.exe --backend Vulkan

# Run with Metal backend (macOS only, hardware-accelerated)
Win32Emu.Gui --nogui game.exe --backend Metal

# Run with Software backend (CPU-based, no GPU required)
Win32Emu.Gui --nogui game.exe --backend Software

# Run in headless mode (no display, CI/CD environments)
# Use the provided launcher script that sets SDL_VIDEODRIVER=dummy
./run-headless.sh --nogui game.exe --backend Software

# Or set the environment variable manually
SDL_VIDEODRIVER=dummy Win32Emu.Gui --nogui game.exe --backend Software

# Run with enhanced debugging
Win32Emu.Gui --nogui game.exe --debug

# Run with interactive debugger for step-through debugging
Win32Emu.Gui --nogui game.exe --interactive-debug

# Run with GDB server for debugging in Ghidra or IDA
Win32Emu.Gui --nogui game.exe --gdb-server

# Run with GDB server on custom port
Win32Emu.Gui --nogui game.exe --gdb-server 5678

# Enable file logging (auto-generates filename with MD5 hash)
Win32Emu.Gui --nogui game.exe --log-file

# Enable file logging with custom path
Win32Emu.Gui --nogui game.exe --log-file my_debug.log

# Run with OpenTelemetry console exporter for observability
Win32Emu.Gui --nogui game.exe --telemetry-console

# Run with OpenTelemetry OTLP exporter (for Jaeger, Prometheus, etc.)
Win32Emu.Gui --nogui game.exe --telemetry-otlp http://localhost:4317
```

**Important Note for macOS Users:**
Running with `--nogui` ensures that rendering backends run on the main thread, which is required for proper operation of Metal, SDL, and other graphics APIs on macOS.

**Running in Headless Environments (CI/CD, Docker, SSH):**
For environments without a display (e.g., GitHub Actions, Docker, SSH sessions), use the Software backend with SDL's dummy video driver:

```bash
# Option 1: Use the provided launcher script (recommended)
./run-headless.sh --nogui game.exe --backend Software

# Option 2: Set environment variable manually
SDL_VIDEODRIVER=dummy Win32Emu.Gui --nogui game.exe --backend Software

# Option 3: Export for the entire session
export SDL_VIDEODRIVER=dummy
Win32Emu.Gui --nogui game.exe --backend Software
```

**Note:** The `SDL_VIDEODRIVER` environment variable must be set **before** starting the Win32Emu process. Setting it from within the application is too late because SDL reads it during native library initialization.

See [Win32Emu.Gui/README.md](Win32Emu.Gui/README.md) for more details about the GUI features.

**See Also:**
- [HEADLESS_MODE.md](HEADLESS_MODE.md) - Comprehensive guide for running in headless environments
- [docs/implementation/SILK_NET_MIGRATION.md](docs/implementation/SILK_NET_MIGRATION.md) - Backend system and configuration
- [docs/guides/GHIDRA_DEBUGGING_FAQ.md](docs/guides/GHIDRA_DEBUGGING_FAQ.md) - Troubleshooting "no debugging symbols" and debugging tips
- [docs/guides/DEBUGGING_GUIDE.md](docs/guides/DEBUGGING_GUIDE.md) - Enhanced debugging mode
- [docs/guides/INTERACTIVE_DEBUGGER_GUIDE.md](docs/guides/INTERACTIVE_DEBUGGER_GUIDE.md) - Interactive debugger
- [docs/guides/GDB_SERVER_GUIDE.md](docs/guides/GDB_SERVER_GUIDE.md) - GDB server for Ghidra/IDA integration
- [docs/guides/VFS_DOCUMENTATION.md](docs/guides/VFS_DOCUMENTATION.md) - Virtual File System for game file isolation
- [docs/guides/OPENTELEMETRY_USAGE.md](docs/guides/OPENTELEMETRY_USAGE.md) - OpenTelemetry for logging, metrics, and profiling
- [docs/examples/TELEMETRY_EXAMPLE.md](docs/examples/TELEMETRY_EXAMPLE.md) - Practical examples of using OpenTelemetry
- [docs/guides/RIDER_OPENTELEMETRY_SETUP.md](docs/guides/RIDER_OPENTELEMETRY_SETUP.md) - JetBrains Rider integration guide
- [docs/implementation/JIT_CACHE_IMPLEMENTATION.md](docs/implementation/JIT_CACHE_IMPLEMENTATION.md) - JIT caching to disk for faster emulation
- [docs/examples/JIT_CACHE_EXAMPLES.md](docs/examples/JIT_CACHE_EXAMPLES.md) - JIT cache usage examples and best practices
- [docs/features/CHD_DISC_IMAGE_SUPPORT.md](docs/features/CHD_DISC_IMAGE_SUPPORT.md) - CHD disc image format support
- [docs/implementation/NE_LOADER_IMPLEMENTATION.md](docs/implementation/NE_LOADER_IMPLEMENTATION.md) - Win16 NE format support (experimental)

### Win32Emu.Wasm
Interactive web-based frontend for Win32Emu, built with Blazor WebAssembly.

**Live Demo:** [https://archanox.github.io/Win32Emu/emulator/](https://archanox.github.io/Win32Emu/emulator/)

![Win32Emu WASM Frontend](https://github.com/user-attachments/assets/9d06b66e-c8ca-4f69-904c-b10cec47e291)

**Features:**
- **Browser-Based**: Run the emulator interface directly in your web browser
- **HTML5 Canvas Display**: Dedicated canvas area for DirectDraw output rendering
- **Dual Output Panels**: Separate panels for standard output and debug messages
- **Status Monitoring**: Real-time display of instructions executed, FPS, and audio status
- **File Upload**: Upload Windows PE executables directly from your device
- **Sample Executables**: Built-in DirectDraw test examples (simple_ddraw.exe, hugi.exe) for quick testing
- **Mobile-Friendly**: Test and interact with emulated applications on mobile devices

**Current Status:**
This is a **proof-of-concept** implementation. The Win32Emu core library currently has native dependencies (SDL3, Silk.NET, UnicornEngine) that don't support WebAssembly. To enable full web-based emulation, the following work is needed:

- Create a WASM-compatible rendering backend using HTML5 Canvas and JavaScript interop
- Implement Web Audio API integration for DirectSound emulation
- Adapt CPU emulation to work without native intrinsics or provide fallbacks
- Handle file I/O through browser APIs (IndexedDB, FileSystem API)

**Performance Note:**
WASM mode uses interpreter-based CPU emulation (IcedCpu) which is approximately 870x slower than native JIT compilation. Games with CPU-intensive initialization (e.g., large lookup table generation) may timeout before reaching rendering. For such games, native builds are recommended. See [docs/investigation/IGN_TEAS_TRANSPILED_DIAGNOSIS_SUMMARY.md](docs/investigation/IGN_TEAS_TRANSPILED_DIAGNOSIS_SUMMARY.md) for detailed analysis.

**Use Cases:**
- Test emulator compatibility on mobile devices
- Share emulated applications via URL
- Automated testing with Playwright browser automation
- Quick PE file compatibility checks without installing the native application

**Sample Executables:**
The WASM frontend includes built-in DirectDraw test executables:
- **simple_ddraw.exe**: Basic DirectDraw test with animated pattern (no threading)
- **hugi.exe**: Advanced DirectDraw example from the classic [Hugi 16 article](https://hugi.scene.org/online/coding/hugi%2016%20-%20coddraw.htm) (with double buffering and threading)

These samples can be loaded with one click from the "📦 Sample Executables" section in the WASM interface. Source code and build instructions are available in [retrowin32/exe/cpp/](retrowin32/exe/cpp/).

See [Win32Emu.Wasm/README.md](Win32Emu.Wasm/README.md) for more details.

### Win32Emu (Library)
The core emulation library that powers Win32Emu.Gui. This library provides the `Emulator` class and `EmulatorLauncher` API for embedding Win32 emulation into .NET applications.

## Win16 NE Format Support (Experimental)

Win32Emu now includes experimental support for Win16 NE (New Executable) format applications. This enables running 16-bit Windows installers and games common for Windows 9x through a thunking layer that translates Win16 API calls to Win32 equivalents.

**Status**: 🚧 Experimental - Format loading and Win16→Win32 thunking implemented, full API compatibility in progress

**Supported**:
- ✓ NE format detection and validation
- ✓ Segment table parsing and loading
- ✓ Entry point resolution
- ✓ Resident/non-resident name table parsing
- ✓ Import module identification and relocation
- ✓ Win16 to Win32 module name mapping (KERNEL→KERNEL32, USER→USER32, GDI→GDI32, etc.)
- ✓ Win16 thunking layer with 6 modules (KERNEL, USER, GDI, KEYBOARD, SYSTEM, SOUND)
- ✓ Handle size conversion (16-bit to 32-bit)
- ✓ Parameter forwarding for compatible functions

**Implemented Win16 Modules**:
- **KERNEL** → KERNEL32.DLL (memory, file I/O, strings, module loading)
- **USER** → USER32.DLL (windows, messages, dialogs, menus, input)
- **GDI** → GDI32.DLL (device contexts, drawing, text, bitmaps, fonts)
- **KEYBOARD** → USER32.DLL (keyboard state and configuration)
- **SYSTEM** → KERNEL32.DLL (timers and system time)
- **SOUND** → WINMM.DLL (multimedia and sound playback)

**Known Limitations**:
- ⚠️ Simplified thunking (complex parameter translation may be needed for some functions)
- ⚠️ PASCAL calling convention handled by underlying Win32 implementations
- ⚠️ Far pointer (segment:offset) translation not fully implemented
- ⚠️ Complex Win16-specific structures may need additional marshalling
- ⚠️ NE resource loading is basic

**Example Usage**:
```bash
# Win32Emu automatically detects the format
Win32Emu.Gui --nogui installer16.exe

# The emulator will log:
# [Loader] Detected format: NE
# [Loader] Win16 NE format support is experimental
# [Loader] Registering Win16 thunking modules for NE format executable
# [Win16 Thunk] GLOBALALLOC - forwarding to KERNEL32
```

**For More Information**:
- [Win16 Thunking Implementation Guide](docs/implementation/WIN16_THUNKING_IMPLEMENTATION.md)
- [NE Loader Implementation Guide](docs/implementation/NE_LOADER_IMPLEMENTATION.md)

## Backend System

Win32Emu uses pluggable backends for cross-platform multimedia support:

### Rendering Backends
- **SDL** (default): SDL3-CS - Native Metal on macOS, Vulkan on Linux, DirectX 12 on Windows. Best compatibility, hardware-accelerated
- **GLFW**: Silk.NET.GLFW + OpenGL - Alternative for systems where SDL has issues
- **Vulkan**: Silk.NET.Vulkan - Modern GPU API with cross-platform support (uses MoltenVK on macOS)
- **Metal**: SharpMetal - Native Metal backend for macOS (hardware-accelerated)
- **Software**: SDL3 software renderer - True CPU-only rendering with windowing and event support. No GPU acceleration required, ideal for macOS, debugging, or systems without GPU support

### Audio Backend
- **SDL Audio**: SDL3-CS audio when using SDL backend - Native audio support
- **OpenAL**: Silk.NET.OpenAL - Cross-platform audio support for GLFW/Vulkan backends

### Input Backend
- **SDL Input**: SDL3-CS input when using SDL backend - Keyboard, mouse, and joystick support
- **Silk.NET.Input**: Unified keyboard, mouse, and gamepad support for GLFW/Vulkan backends

**Configuration:**
- Command-line: `--backend SDL`, `--backend GLFW`, `--backend Vulkan`, `--backend Metal`, or `--backend Software`
- Environment variable: `WIN32EMU_BACKEND=SDL`, `WIN32EMU_BACKEND=GLFW`, `WIN32EMU_BACKEND=Vulkan`, `WIN32EMU_BACKEND=Metal`, or `WIN32EMU_BACKEND=Software`
- Programmatic: `BackendFactory.CurrentBackendType = BackendType.SDL;`

See [docs/implementation/SILK_NET_MIGRATION.md](docs/implementation/SILK_NET_MIGRATION.md) for detailed documentation.

## CPU Intrinsics Support

Win32Emu leverages hardware-accelerated SIMD instructions for better performance:

- **x86 hosts**: Uses SSE, SSE2, SSE3, SSE4, AVX, AVX2 instructions
- **ARM hosts**: Uses NEON (AdvSimd) instructions
- **Automatic detection**: CPUID reports accurate host CPU capabilities
- **Fallback support**: Software implementations when intrinsics aren't available

See [docs/implementation/INTRINSICS.md](docs/implementation/INTRINSICS.md) for detailed documentation.

## Event-Driven Messaging System

Win32Emu includes a DispatchR-inspired message handling system for type-safe, zero-allocation Win32 message dispatching:

- **Type-Safe Handlers**: Strongly-typed message classes with compile-time checking
- **Zero Allocation**: Lambda-based handlers avoid heap allocations
- **Extensible**: Easy to register custom message handlers
- **Testable**: Handlers can be tested independently from API implementations

**Example:**
```csharp
// Register a message handler
env.MessageDispatcher.RegisterHandler(WM.COMMAND, msg =>
{
    var cmdMsg = (CommandMessage)msg;
    Console.WriteLine($"Button {cmdMsg.ControlId} clicked!");
    return 0;
});

// Dispatch a message
var message = new CommandMessage(hwnd, wParam, lParam);
env.MessageDispatcher.Dispatch(message);
```

See [docs/implementation/MESSAGE_DISPATCHER_IMPLEMENTATION.md](docs/implementation/MESSAGE_DISPATCHER_IMPLEMENTATION.md) for detailed documentation and examples.

## Building

```bash
dotnet build Win32Emu.sln
```

## Running Tests

```bash
dotnet test Win32Emu.sln
```

### CPU Conformance Test Results

Win32Emu includes comprehensive CPU conformance tests based on the [SingleStepTests/80386](https://github.com/SingleStepTests/80386) test suite - hardware-generated tests that validate CPU implementation against real 386 behavior.

**📊 View live test results:** [CPU Test Results Dashboard](https://archanox.github.io/Win32Emu/)

The dashboard shows:
- Pass/fail status for 941 test files
- Success rate per instruction type
- Detailed failure analysis
- Weekly updates via GitHub Actions

For more information about the test reporter tool, see [Win32Emu.Tools.TestReporter/README.md](Win32Emu.Tools.TestReporter/README.md).

## API Implementation Status

Win32Emu provides comprehensive Win32 API emulation with transparency about implementation status:

**📊 View API Status:** [API Implementation Dashboard](https://archanox.github.io/Win32Emu/)

The dashboard shows:
- All 31 Win32 DLL modules (Kernel32, User32, GDI32, DirectDraw, etc.)
- 1,090 total functions with implementation status
- 84.2% implementation rate (918 implemented, 172 stubs)
- Search and filter by module or function
- Detailed function metadata (ordinal, version, export name)

### Missing Functions Report

**🔍 View Missing Functions:** [Missing Functions Report](https://archanox.github.io/Win32Emu/missing-functions.html)

Compare native Windows ME DLL exports with Win32Emu implementations:
- 27 native DLLs analyzed (KERNEL32, USER32, GDI32, etc.)
- 4,962 total native exports
- 764 implemented (15.4%), 129 stubs (2.6%), 4,069 missing (82.0%)
- Interactive search and filtering
- Detailed per-DLL coverage statistics

**Generate report locally:**
```bash
# Quick generation script
./generate-missing-functions-report.sh

# Or manually
dotnet run --project Win32Emu.Tools.ApiStatusGenerator docs/pages/api-status.json
dotnet run --project Win32Emu.Tools.NativeDllAnalyzer DLLs/WinME docs/pages/api-status.json docs/pages/missing-functions.json
```

See [docs/NATIVE_DLL_ANALYSIS.md](docs/NATIVE_DLL_ANALYSIS.md) for detailed documentation.

### Check Compatibility of Your PE Files

Use the **PeAnalyzer** tool to check if your executable is compatible with Win32Emu:

```bash
# Analyze a PE executable
dotnet run --project Win32Emu.Tools.PeAnalyzer \
  your-game.exe \
  docs/pages/api-status.json
```

**Output:**
```json
{
  "verdict": "PARTIALLY COMPATIBLE - 2 missing function(s)",
  "implementationPercentage": 86.67,
  "dependencies": [
    {
      "dllName": "USER32.DLL",
      "implementedCount": 12,
      "stubCount": 0,
      "missingCount": 0
    }
  ]
}
```

**Features:**
- Uses [PeNet](https://github.com/secana/PeNet) to parse PE import tables
- Cross-references with Win32Emu implementation status
- Shows per-DLL and per-function compatibility
- Identifies missing, stubbed, and implemented functions
- Calculates overall compatibility percentage

For more information, see [Win32Emu.Tools.PeAnalyzer/README.md](Win32Emu.Tools.PeAnalyzer/README.md).

Win32Emu

Today's picks

Was this content helpful?

Recent Feedback

Win32Emu

Today's picks

Was this content helpful?

Recent Feedback

Download README