Spice86

What is Spice86?

Spice86 is a tool and emulator targeting real-mode (16-bit) DOS programs. Its primary use case is reverse engineering without source code: you run a DOS binary inside Spice86, let it gather runtime data (memory snapshots and execution-flow traces), then use those data to incrementally replace assembly functions with equivalent C# code — all while keeping the program fully runnable at every stage.

It is implemented in C# / .NET 10 and runs on Windows, macOS, and Linux. Releases are published on NuGet; pre-releases are available on the GitHub Releases page.

Spice86 is a continuation of the original Java Spice86 by Kevin Ferrare.

Reverse Engineering Approach

Rewriting a binary-only program is a divide-and-conquer task. Spice86 structures that process so every step produces a working, testable program:

1. Run the program in Spice86

   Verify it runs correctly. Identify unimplemented hardware if it crashes.

2. Dump runtime data

   On exit (or via monitor dumpall in GDB) Spice86 writes spice86dumpMemoryDump.bin (RAM snapshot) and spice86dumpExecutionFlow.json (function addresses, labels, executed instructions) to a per-executable subdirectory named by SHA-256 hash.

3. Load into Ghidra via the plugin

   The spice86-ghidra-plugin imports the dumps and decompiles functions as C# code ready for use as overrides.

4. Scaffold a .NET project

   Use spice86-dotnet-templates (dotnet new spice86.project) and import the generated C# files.

5. Override functions one at a time

   Implement IOverrideSupplier, register C# methods at segmented addresses via DefineFunction, and run with --UseCodeOverride true. Each replacement is immediately testable.

6. Iterate

   As more functions are rewritten, the emulated code path shrinks. Ultimately the entire program runs natively in C# with no assembly left.

A concrete, fully worked example is the Cryogenic project (Cryo Dune rewrite).

Getting Started

Prerequisites

Install the .NET 10 SDK. No additional runtime dependencies are required on Windows. On Linux, ALSA is used for audio. On macOS, CoreAudio is used.

Install from NuGet (recommended)

dotnet tool install -g Spice86

Build from source

git clone https://github.com/OpenRakis/Spice86.git
cd Spice86/src
dotnet build

Run a DOS executable

# Run an EXE
Spice86 -e path/to/program.exe

# Run a COM file
Spice86 -e path/to/program.com

# Run a BIOS image
Spice86 -e path/to/bios.bin

# Set the C: drive to the directory containing the game files
Spice86 -e game.exe --CDrive /path/to/game/

# Pass arguments to the DOS program
Spice86 -e game.exe --ExeArgs "arg1 arg2"

Dump execution data for reverse engineering

# Dumps go to a subdirectory named with the program's SHA-256 hash
Spice86 -e game.exe --RecordedDataDirectory /path/to/dumps/

# Or set the environment variable
export SPICE86_DUMPS_FOLDER=/path/to/dumps
Spice86 -e game.exe

CLI Options

Core options

Performance

Debugging

Overrides

Memory

Display & UI

Sound

Logging

GDB Integration

Spice86 speaks the GDB remote serial protocol. The GDB server starts automatically on port 10000 (disabled with --GdbPort 0). Use --Debug to pause execution at startup.

Connecting

(gdb) target remote localhost:10000
(gdb) set architecture i8086

GDB uses physical (linear) addresses. Segmented address A000:0000 maps to physical 0xA0000. The $pc variable reflects the physical address of CS:IP.

Common GDB commands

Custom monitor commands

SeerGDB

The SeerGDB GUI client works well with Spice86. A pre-configured project file is provided at doc/spice86.seer. Launch with:

seergdb --project doc/spice86.seer

In Seer, set Settings → Configuration → Assembly → Disassembly Mode to Length for the assembly view to work correctly.

Built-in Debugger

Spice86 includes a UI debugger (documented on the wiki) with the following views:

Code Override System

The override system lets you replace individual DOS assembly functions with C# methods. The emulator calls the C# method when execution reaches the registered address, and then returns to the emulated program using the appropriate return instruction.

Implementing an override supplier

// Register one C# implementation per assembly function
public class MyProgramOverrideSupplier : IOverrideSupplier {
    public IDictionary<SegmentedAddress, FunctionInformation> GenerateFunctionInformations(
        ILoggerService loggerService, Configuration configuration,
        ushort programStartSegment, Machine machine) {
        Dictionary<SegmentedAddress, FunctionInformation> res = new();
        new MyOverrides(res, machine, loggerService, configuration);
        return res;
    }
}

Implementing overrides

public class MyOverrides : CSharpOverrideHelper {
    private GlobalsOnDs _globals;

    public MyOverrides(
        IDictionary<SegmentedAddress, FunctionInformation> functionInformations,
        Machine machine, ILoggerService loggerService, Configuration configuration)
        : base(functionInformations, machine, loggerService, configuration) {
        _globals = new GlobalsOnDs(machine.Memory, machine.CfgCpu.State.SegmentRegisters);
        DefineFunction(0x1ED, 0xA1E8, IncDialogueCount47A8);
        DefineFunction(0x1ED, 0x0100, AddOneToAX);
    }

    private Action IncDialogueCount47A8(int loadOffset) {
        _globals.SetDialogueCount47A8(_globals.GetDialogueCount47A8() + 1);
        return NearRet();
    }

    private Action AddOneToAX(int loadOffset) {
        State.AX++;
        return FarRet();
    }
}

Memory-mapped data structures

public class GlobalsOnDs : MemoryBasedDataStructureWithDsBaseAddress {
    public GlobalsOnDs(IByteReaderWriter memory, SegmentRegisters regs)
        : base(memory, regs) { }

    public int GetDialogueCount47A8() => UInt16[0x47A8];
    public void SetDialogueCount47A8(int value) => UInt16[0x47A8] = (ushort)value;
}

Control-flow return types

Hardware Support

CPU

Memory

Graphics

Input / Peripherals

DOS (Int 21h)

Partial DOS 5.0 interrupt implementation. Covers the subset of calls used by most real-mode games.

Sound Support

Audio playback uses the native platform audio subsystem: WASAPI on Windows, ALSA on Linux, and CoreAudio on macOS. No external audio libraries are required.

Game Compatibility

This list reflects the state as of early 2026. A program crashing usually indicates an unimplemented BIOS/DOS interrupt or a video mode that has not been implemented.

A full and up-to-date list is maintained in COMPATIBILITY.md.

CFG CPU Architecture

Spice86 uses a Control Flow Graph CPU (CfgCpu) rather than a traditional interpreter loop. The graph grows at runtime as the program executes, recording every path taken and every instruction variant observed. Detailed documentation is in doc/cfgcpuReadme.md.

Screenshots

Credits

Core contributors

Spice86 is developed by OpenRakis. It is a port and continuation of the original Java Spice86 by Kevin Ferrare.

Third-party components

Related projects

License

Spice86 is released under the Apache 2.0 license. See NOTICE for third-party attribution.