How It Works

How It Works

EmuDOS is a thin, opinionated frontend over one libretro core. This page covers the pieces underneath the shelf.

The core

EmuDOS runs DOSBox Pure, a libretro build of DOSBox. It's downloaded from the libretro buildbot on first run (Preferences → Downloads) rather than bundled, so it can be updated on its own. EmuDOS hosts the core directly: it implements the libretro environment callbacks, feeds it per-game options, renders its video, and plays its audio.

DOSBox Pure expresses almost everything a game needs through core options (machine, memory, sound card, cycles, MIDI, and more). EmuDOS sets these per game from the game's profile. For the few things core options can't express — exact non-preset cycle counts, custom MOUNT/SET lines, or running a specific program — EmuDOS generates a small DOSBOX.BAT inside the gamebox that runs at the C: prompt.

Gameboxes: the source of truth

Every game is a gamebox — a self-contained folder. The library database is only a rebuildable index over these folders; the gamebox is the truth.

<game>/
  profile.json   curated + your settings (CPU, machine, memory, sound, launch)
  state.json     per-game user state (window size, remembered program, box style)
  content/       the game files (mounted as C:)
  media/         box art (box-front.png, box-3d.png) and manuals
  saves/         save data and save states

Because a gamebox is self-contained, backing up or moving the folder moves the whole game. Two JSON files separate concerns:

• profile.json — the canonical, engine-agnostic configuration that makes a game "just work." It layers a curated base (from the catalog) under your own overrides, so your changes survive catalog updates.
• state.json — per-game user state that isn't part of the curated profile: the last window size, the program you actually ran (so the right one launches next time), and the box-style override.

The curated catalog

The catalog is a shipped database of known-good per-game settings. On import, EmuDOS matches your game against it and seeds the profile with curated defaults; if there's no match, safe defaults are used. The catalog is downloadable and updatable separately from the app, and updates never clobber your per-game overrides.

Importing

Whatever you drop — a folder, a .zip, or a disc image — is turned into a gamebox: the content is copied/extracted in, the program to launch is detected (preferring a title-matching executable, skipping installers and DOS extenders), and art is fetched. Disc images and multi-disc sets have extra handling — see Discs & Windows.

Where your files live

By default everything lives under your user data folder: the downloaded core, the catalog, system files (MT-32 ROMs, SoundFonts), your gameboxes, and screenshots/videos. Because gameboxes are self-contained, the library can always be rebuilt by re-scanning the gameboxes folder.

Distribution

EmuDOS ships as a single self-contained EmuDOS.exe — the .NET runtime and everything else are bundled, so there's nothing to install alongside it.

Building the MT-32 shim (optional)

EmuDOS plays Roland MT-32 music with its own small synth DLL, emudos_mt32.dll, built from munt / mt32emu (LGPL 2.1). The prebuilt DLL is committed and ships with the app, so you don't normally need to build it. To rebuild it from source (under src/native/mt32), install Visual Studio with the C++ workload and run src/native/mt32/build.cmd.