Aaron Giles

Documentation

This is the official documentation page for DREAMM.

The documentation on this page applies specifically to DREAMM 2.0; if you need it, I’ve archived the documentation for DREAMM 1.0 here.

Contents

There’s a lot to go over, so let’s break things up like this:

• Introduction
• Downloading & Installation
• The DREAMM Game Manager
• Adding Games
• Running the Games
• Audio/Video Systems
• MIDI Configuration
• Upgrading from DREAMM 1.0
• FAQ
• Special Thanks

Introduction

DREAMM is a specialized emulator for playing many of your original DOS (and Windows and FM-Towns) LucasArts games with full fidelity to the original. It is the creation of Aaron Giles.

DREAMM is a backronym for:

DOS
Retro-
Emulation
Arena for
Maniac
Mansion (and other LucasArts Games).

(Yes, DREAMM has outgrown its original acronym a bit, but I like the name, so I’m keeping it.)

The latest version of DREAMM can always be found at the main download page. If public beta releases are available, and you’re interested in seeing future DREAMMiness, check out the beta release page.

Supported Platforms

DREAMM is currently built for 64-bit Windows and MacOS platforms, with native support for both Intel and ARM processors. I hope to eventually have a Linux version as well, but I need to learn a bit more about how to package it up to work across distros.

Windows systems require (I believe) a minimum of Windows 7. I personally haven’t verified it actually runs on anything lower than Windows 10, but have heard reports that it runs well as far back as Windows 7 SP1.

MacOS systems require a minimum of MacOS X 10.15 (Catalina) or later.

Note: 32-bit platform support has been dropped for DREAMM 2.0. There is little demand for it, and 64-bit platforms allow for much more optimal techniques.

DREAMM Technologies

DREAMM makes use of a few outside packages to handle some of the tricky bits. These are all included with DREAMM itself, so you don’t need to install anything more, but I do wish to acknowledge them here.

DREAMM is built with the following libraries:

• YMFM (BSD license) for FM audio emulation in SoundBlaster and FM-Towns
• RtMidi (MIT license) for MIDI port access across platforms
• zlib (zlib license) for compression/decompression of ZIP and PNG file formats

In addition, DREAMM ships with the following dynamic libraries, built unmodified:

• SDL2 (zlib license) for cross-platform graphics and sound
• Munt (LGPL 2.1 License) for Roland MT-32 emulation

The remaining code—including the core x86 emulation, remaining sound chip emulation, video card and other peripheral emulation, plus the DOS, Win32, and FM-Towns OS emulation—are all my own inventions and native to DREAMM.

What’s New in 2.0?

DREAMM has undergone a pretty significant overhaul since its first release. If you’re migrating from 1.0, see the Upgrading from DREAMM 1.0 section. In short, the major changes are:

• Re-wrote DREAMM’s user interface to run on top of SDL2, enabling MacOS support.
• Wrote assembly language versions of my i386 interpreter for both Intel and ARM platforms.
• Added Direct3D emulation support, with a multicore software renderer.
• Introduced support for many new games, including the GrimE engine games, several Star Wars games, and others.
• Expanded support for more demo and alternate versions of games, including my own Windows ports (yes, I now emulate myself).
• Added support for Super VGA output, plus basic joystick controls.
• Added in-game volume controls, plus many other quality-of-life UI improvements.

Supported Games

While DREAMM started out focused on the SCUMM games, it has since expanded its scope to include any LucasArts games that are interesting to me.

This includes of course all the original SCUMM games:

Plus the later GrimE engine games:

Several mid-90s Star Wars games:

And the following miscellaneous games:

Almost all of these games come in a variety of different editions, languages, and versions. I have made a best effort to support as many of them as I have managed to get access to, including demo versions. (Or at least, all the ones that ran on DOS, Windows, or FM-Towns—I’m not a miracle worker!)

Note: DREAMM is focused fairly strictly on “official” releases of the games, so you will find that fan translations or hacks are generally not supported. They may work fine, assuming all the necessary files are present, but DREAMM will not identify them as legitimate at install time. The main exceptions to this are the two “Ultimate Talkie” versions of the Monkey Island games, which I bent the rules for because they are too awesome to ignore.

Downloading & Installation

You can always download the latest official version of DREAMM from https://aarongiles.com/dreamm.

Beta releases, if available, can be found at https://aarongiles.com/dreamm/beta.

Windows Installation

DREAMM is released for Windows in two forms:

Windows EXE Installer. This is the simplest way to install DREAMM on your Windows machine. Just download the EXE file, and double-click it to run the installer. It contains both the Intel- and ARM-native versions of DREAMM, and will automatically install the appropriate one for your system.

Note: The Windows installer requires administrative privileges in order to place DREAMM’s files in your Program Files directory, and to create links in the Start menu, so be prepared to grant permission to proceed.

Windows ZIP Packages. As an alternative, the Windows release of DREAMM is also offered as two ZIP files, one for Intel-based machines, and one for ARM-based machines. Download the appropriate one for your system (most likely the Intel or x64 version), and extract the contents of the ZIP to a folder. From there, you can just double-click and run; no further installation needed.

MacOS Installation

On MacOS, there’s just one download option:

MacOS DMG File. For Mac users, DREAMM is offered as a compressed disk image, or DMG file. Simply download this and double-click it to mount it on your system. Once you do, you’ll see a window in Finder that looks something like the screen to the right.

At this point you have two options. You can either run DREAMM directly by double-clicking the DREAMM icon, or you can drag the DREAMM icon to your Applications folder to install it there. The MacOS DREAMM application is shipped as a universal binary containing both Intel and ARM native versions, so it should work on either system seamlessly.

The DREAMM Game Manager

When you launch DREAMM, you will be presented with DREAMM’s Game Manager, which is your main interface for adding, configuring, and running the games.

Running DREAMM for the First Time

If you have never run DREAMM on your system before, you will be presented with a screen like the one here, inviting you to install games and pointing you to this documentation. Detailed instructions on adding new games are provided below.

From this initial screen you can also access DREAMM Options... which may be of interest if you need to configure DREAMM’s install folder to point to a volume with more space before you install games.

The add games interface can also be accessed even after you’ve added some games, either from the DREAMM Options menu, or via the Alt+A⌘A shortcut.

Tip: After you’ve added some games, you don’t need to return to this screen to add new games. DREAMM’s Game Manager accepts dropped game folders and image files at any time, except while in the midst of processing a previous add operation.

Selecting a Game

Once you have installed one or more games, you will see a screen like this, showing icons for each game installed.

This is the core interface screen for selecting which games to run within DREAMM, and is what you will see by default when you next start DREAMM, with your most-recently-selected game already pre-highlighted.

To configure and run one of the games, you can either click on its icon directly, or navigate to it via the keyboard, using the ← and → keys to change the currently-highlighted icon. Once your desired game is highlighted, click the Configure & Launch button to get started.

From this screen you can also access the DREAMM Options... which are described in detail a bit later, or you can choose to Exit DREAMM directly.

Configure & Launch

After selecting a game, you will be presented with the DREAMM’s game Configure & Launch screen.

By default, the Launch Game button is selected. Clicking that, or just pressing Enter↩ will launch the game within DREAMM. More details on how DREAMM behaves while running a game are provided below.

If you have installed multiple versions of a game, you will see ← and → buttons just above the large icon on the left, along with an indication of which version you are looking at. To switch between versions, either use those buttons, or press the ← or → keys.

In addition to controls for configuration and launching, the bottom half of this screen also provides detailed information about the particular version of the game you are about to run.

The large area at the very bottom is reserved for compatibility-related messages. Normally you’ll just see the text “This game version is fully supported.” However, you may encounter a version with known compatibility issues, as shown in the above screenshot, so keep an eye on that area.

Game-Specific Configuration

Many games offer configuration options, most often regarding which audio and video hardware the game should leverage. These options were typically specified on the command line, or in configuration files read by the game at startup, so it makes sense to set these options here, prior to launch.

To review the game’s current configuration, click the Configure Game... button on the DREAMM Configure & Launch screen. (Games that do not have any such options will deactivate the button, though it will still be visible.)

If the current game has only one set of configuration options, DREAMM will just display a single menu allowing to you select from the available options. If the current game has multiple sets of options, you will first see a menu listing the option categories, as in the menu screenshot above. Once you choose a category, you will be taken to another menu to review the options for that category.

Note: For details on different video and audio hardware options you might see here, see the Audio/Video Systems section of these docs.

More Options

To access some less common game-related options, click the More Options... button on the DREAMM Configure & Launch screen to bring up a menu with additional choices.

At the very top will be the Uninstall Game... option, which gives you the opportunity to uninstall the game, freeing up whatever disk space the game was occupying.

Note: Uninstalling the game only removes the installed files and does not remove any of the data written by the game, so your save games and any other game-related data will still be safe.

The remaining options here all pertain to revealing the location of game-relevant data folders. The Show Install Folder option will open a view of the game’s installation folder in Windows ExplorerFinder. This is effectively a read-only location where the game’s files are located after an install.

Selecting the Show Game Data Folder option will reveal the game’s writable data folder. Whenever the game creates new files or modifies existing ones, they are stored here, in a way that doesn’t modify any of the installed files.

Finally, if you have taken any screenshots within the game, you might see a Show Screenshots Folder option, which will open a window to show any screenshots available.

DREAMM Options

At the bottom of the game selection screen, you’ll find a DREAMM Options... button which brings up a menu of general options and commands. You can also use the Alt+U⌘U or F12 shortcut to bring up this menu at any time in the Game manager.

The items in the top section let you control the Game Manager window presentation. Full Screen Toggle item switches to/from full screen mode, and can also be invoked by pressing Alt+Enter⌘↩ at any time. Below that are options to Grow Video One Step (Alt+Plus⌘+) or Shrink Video One Step (Alt+Minus⌘–), which will adjust your window size in increments of 320×200.

The middle section contains options to access other Game Manager modes. Selecting Manage Install Folder will switch you into the mode that allows you to control where DREAMM installs games, while selecting Add Games (Alt+A⌘A) switches you to DREAMM’s dedicated game adding interface.

The final option in the middle section, Refresh Game List, forces DREAMM to re-evaluate the contents of the install directory. This is useful if you manually make any changes to the available games present.

Finally, you’ll see an option to display information About DREAMM. The top lines reveal the current operating system, CPU architecture, and DREAMM version, plus the version of SDL currently being used.

Below that is a couple of lines that tell you how many sound fonts DREAMM has discovered, and also the current state of Roland MT-32 emulation. If you are missing any necessary ROM files, DREAMM will tell you here exactly what is wrong.

Finally, you can click the License Info button to view a list of libraries bundled with DREAMM.

Managing Installation Location

By default, DREAMM installs all games to a subdirectory under the SDL-preferred location for user preferences. This location is typically on your boot disk, but if you’d like to install games to a different location, you can do that by clicking the DREAMM Options... button (or pressing Alt+A⌘A) and choosing Manage Install Folder from the menu.

From this screen you have several options. First, if you’d like to view the contents of the installation folder, click the View Folder button, and DREAMM will open it in Windows ExplorerFinder.

If you’d like to select a new folder, simply locate the folder in Windows ExplorerFinder and drag it onto the DREAMM window. This will direct all future installations to the chosen folder.

If you ever change your mind and wish to revert the location back to its default value, click the Reset to Default button.

Any time you change your install folder, DREAMM will ask if you’d like to open both the current and new locations in Windows ExplorerFinder so that you can move data from the old location to the new one. DREAMM does not do this automatically, so if you want to migrate your existing installs, you’ll need to manually move the folders.

If you do manipulate anything in the install folder by hand outside of DREAMM, you can force a refresh of the available games by either pressing F5, or by clicking the DREAMM Options... button and selecting Refresh Game List from the menu.

Adding Games

The first time you run DREAMM on your system, you will be faced with a screen like this explaining how to add games. (Heck, you might have even arrived here by clicking the link!)

You can also switch to this interface even once you have installed some games by clicking the DREAMM Options... button and selecting Add Games from the menu.

The important thing to understand is that in order to run any of the supported games, you must first let DREAMM install them for you. There are a number of ways to go about this, each explained below.

Tip: You do not have to be on this screen in order to add new games. The techniques below that involve dragging & dropping will work at any time from the Game Manager, except if you are already in the middle of an add operation.

Scanning for Games

The first and easiest thing to do is to click the Search for Games button. DREAMM will scan your system for games it recognizes by looking in the following locations:

• On any removable drives you have (including floppies, CD-ROMs, and USB sticks)
• In the standard location where GOG (aka Good Old Games) installs your purchases
• In the standard location where Steam installs your purchases
• (Windows only) In any folders referenced by the DREAMM 1.0 configuration file

Important: DREAMM requires the original executable file in order to run a game. Many Steam releases and a few GOG releases fail to include this critical file, and so DREAMM won’t be able to identify those games. For more information, see the Missing Executable Files section.

Installing from Folders

If you have the game you want already installed on your system, simply locate the folder where the game lives and drag it onto DREAMM’s window to add it. DREAMM will scan any folder your provide this way for games that it recognizes.

DREAMM will even aggressively scan subdirectories looking for something, so if you have a big LucasArts folder somewhere with all your games in it, you can just drop the whole thing on DREAMM and let it find everything contained therein.

DREAMM can also handle folders that have been compressed together into a ZIP file. Dragging a ZIP file onto DREAMM is the equivalent of dragging the unzipped contents as a folder.

Note: Once again, DREAMM requires the original executable file in order to run a game. If you have previously run your games using ScummVM—which doesn’t require the executable file—then you may find that this file is missing. For more information, see the Missing Executable Files section.

Installing from Disk Images

Another convenient way to install games is to use disk images. These are files containing a raw dump of a complete floppy disk or CD-ROM, and are one of the best ways to back up your precious old original media.

For floppy disk images, DREAMM supports any of the standard “raw” formats: IMG, IMA, VFD.

For CD-ROM images, DREAMM supports both ISO and CUE/BIN files. When working with CUE/BIN images, just provide the CUE files to DREAMM, as the BIN files on their own are not useful for understanding what the image’s contents consist of (though if you do drop the BIN file, DREAMM will make an educated guess for how to find the corresponding CUE file).

To install from disk images, make sure you have all the necessary images together. For example, for a game that came on 5 floppy disks, you would want 5 image files. Then select all of the images together and drag them in a single operation onto DREAMM’s window.

You can also put all the disk images together in one folder and drag that folder onto DREAMM.

DREAMM will look at the collection of images as a whole, trying to find all the necessary files that make up a game. If it finds a complete set of files, it will proceed with the installation.

Installing from Original Media

If you have original floppies or CD-ROMs of the games, you can install from those disks as well, but it requires a bit more work.

If your game resides on a single floppy or CD-ROM, you can simply insert that disk and then drag the drive icon onto DREAMM. It should successfully install directly from the media.

If your game comes on multiple floppies or CDs, then you have two choices. You can either use a utility to create a disk image file of each disk, and then install them as disk images, described above.

Alternatively, you can copy the contents of each disk to its own folder. Then select all the folders and drag them together onto DREAMM in a single operation.

Exact Matches

With luck, when you add your game to DREAMM using one of the mechanisms described above, DREAMM will find that it is an exact match for one of the many versions it knows about. In this case, you’ll see a message like the one to the right, with two options available.

Click Install This Game to copy all the game’s files into your install directory. Or click Skip This Game if you’ve decided you don’t want to perform an install.

Also notice that the “Found an exact match” text is underlined. In this case, you can click on that text to open up the directory containing the game files DREAMM found (or the directory containing the image files the game was found on) in Windows ExplorerFinder. This is mostly useful if you have dropped a deep tree of directories onto DREAMM for analysis, and want to know which particular directory is being referenced.

Games With Installers

Many of the later games came with a specialized installer that copied and decompressed the files onto your hard disk. DREAMM knows how these installers work and will run them for you.

If you drag a folder or disk images containing an installer program that DREAMM recognizes, DREAMM will show you a message like the one to the right, again giving you two options.

In this case, if you click Install This Game, DREAMM will launch the game’s installer program directly within the Game Manager window. Clicking Skip This Game instead will leave the game uninstalled.

For most games, the installer will ask you to choose where to install the game, or will give you a menu like the one to the left. Ignore any configuration options at this time and focus on performing the install itself.

Select the C: drive as the target for files (the specific diretory doesn’t matter, as long as it’s somewhere on C:), and then let the installer do its job. When finished, exit manually if necessary.

Once the installer exits, DREAMM will examine the contents of the C: drive, identifying any games it knows about. Assuming it finds at least one valid game, it will move the installed data to its final home in your install directory.

Reinstalling Games

If DREAMM detects that you are attempting to install a game that is already installed, it will give you the chance to either skip the install, or to perform a reinstall. In this situation, the default button will change to read Reinstall This Game, as seen in the screenshot to the right.

If you choose to reinstall the game, DREAMM will erase the old installation directory and replace it with a fresh copy of all the files.

Reinstalling does not delete any data that was written during gameplay by the original installation. This operation simply replaces the installed files, while leaving everything else alone.

Unrecognized Games

When scanning a folder or image file for installation, if DREAMM finds all the necessary files, but doesn’t recognize the data in them, it will still allow you to proceed with the installation.

In this case, DREAMM will match what it found against the games it knows about, and will choose the closest match as the name. In addition, it will append an 8-digit code in brackets to the end of the name to identify it as an unknown version.

In many cases, unknown versions will work as expected, but it is also possible that you will encounter issues. In either case, it is best to contact me at dreamm@aarongiles.com to let me know about your alternate version (assuming it is a legitimate release) so it can be added to DREAMM’s internal database.

Tip: If you want to examine the directory or disk image where the game is stored, click the underlined text “Found an unfamiliar set of matching files”, and DREAMM will tell Windows ExplorerFinder to open the game’s source folder.

Missing Executable Files

Because DREAMM emulates games at the CPU level, it requires the original executable files in order to run. This is in contrast to other solutions, like ScummVM, which replace the original executable with their own logic. (For more details on the differences between DREAMM and ScummVM, see the FAQ.)

Unfortunately, this means that games which ship using ScummVM (e.g., many of the GOG and Steam releases) have no need for the original executable files, and frequently—though not always—ship without them.

It is also common to find ScummVM-compatible collections of games with the executable files stripped out.

Because this is a common occurance, DREAMM detects this condition and reports it, as seen in the screenshot above. Unfortunately, there’s no easy solution to this problem. It sure would be nice if GOG and Steam included the original executables across the board!

Tip: If you want to examine the directory or disk image where the game is stored, click the underlined text “Found a partial set of files”, and DREAMM will tell Windows ExplorerFinder to open the game’s source folder.

Running the Games

Once you’ve launched a game, the window will be adjusted to reflect whatever state it was in the last time you ran the game, and the game will begin execution. This section deals with game interaction and configuration.

Game Controls

Keyboard controls in the game should work as expected. The main exception will be that any shortcut keys defined by DREAMM take precedence over the game’s normal keys. Perhaps the most obvious example is the Alt+X shortcut on non-MacOS machines, which overlaps with the exit shortcut Alt+X recognized by the SCUMM games. In this case, it’s ok because they have the same effect.

Mouse controls can vary game-to-game. For games that display a mouse cursor, DREAMM attempts to track your system mouse position and map it to the game’s position. This provides seamless transitions into and out of the window when not running full screen.

Other games, however, track the mouse’s movement at a lower level. In this case, DREAMM “captures” the mouse and hides the mouse pointer. To regain control of the mouse, invoke the user interface via the Alt+U⌘U or F12 shortcut.

Finally, for games that support joystick controls, DREAMM picks out the first joystick it finds and sends the game its axis and button information. At this time there is no way to select one of multiple joysticks or configure how the axes and buttons map to the traditional joystick inputs.

In-Game Menu

At any time when running a game, you can bring up the in-game options menu via the Alt+U⌘U or F12 shortcut. The game will be paused while you navigate the menus, and will resume once they are dismissed. Bringing up the menus also serves to un-capture the mouse input, so if you need to regain control of the mouse from the game, you can invoke the menus to do that.

The first menu item, Options..., will take you to another menu with video and other options, described in greater detail in the next section. You can bring up the options menu directly via the Alt+O⌘O shortcut.

The Volume Controls... item is next, and provides one or more volume sliders that let you adjust the output volume of the game’s sound. All games will offer at least a Master Volume slider. Games that have MIDI outputs or CD Audio will show independent sliders for those items, allowing you to control the relative volume of those outputs compared to the rest of the game. Use the Alt+V⌘V shortcut to directly bring up the volume controls.

Note: While the Volume Controls menu is visible, the game will be un-paused. This is important so that you can hear the effects of your changes live. However, it does mean you should be sure to place yourself in a non-dangerous situation before you invoke this menu!

If a Hercules video card is currently configured as your game’s output, you’ll see the Hercules Monitor Color... menu item next. Choose this to bring up a menu where you can select between green, amber, or white as your primary output color. This menu item is hidden if you are using any other type of display.

Below the first divider you will find game-specific configuration options, if any are available. These are the same options that were available on the Configure & Launch screen via Configure Game... button, described above.

Important: Because these configuration options are generally passed on the command line to the game program, altering any of these from within the game will require a restart.

The last group of items starts with the About DREAMM... item, which shows the same about box as described above, but with additional information about the exact version of the game you are currently playing.

The Show Game Data item opens the game’s writable data folder in Windows ExplorerFinder so you can examine the game’s files.

And finally, the Restart Game... and Exit... items behave as you’d expect, providing a mechanism to hard-restart or hard-quit the games (after asking for confirmation first, of course). The short cut combination Alt+X⌘X is bound to the exit command.

Important: Restarting or quitting in via this menu or the Alt+X⌘X shortcut does not involve the game at all, so if you need to save your game first, do so within the game before invoking either of these options.

In-Game Options

You can bring up the In-Game Options menu at any time via the Alt+O⌘O shortcut key. This menu provides common options that affect the game’s behavior while running.

The first item, Automatically Pause in Background controls whether DREAMM pauses gameplay when the game’s window is not the topmost window. If left unchecked, DREAMM will continue to allow the game to run while you do other things on your computer.

The Smooth Graphics option controls the application of epx smoothing to the game’s graphics, which can help ease the blockiness of the original game art, especially at low resolutions. When unchecked, the game’s graphics are output as they originally were. Use the Alt+S⌘S shortcut to toggle this without using the menus for easy before/after comparisons.

The Correct Aspect Ratio option specifies whether DREAMM should stretch the game’s pixels to the correct aspect ratio (4:3), or output them raw. Turning this option on (as it should be!) provides the most accurate overall look to the game’s video, at the expense of some minor scaling artifacts. If you really can’t stand to see any scaling effects, you can leave this option unchecked. The shortcut Alt+A⌘A can be used to bypass the menus and change this setting directly.

Integral Video Scaling controls how DREAMM stretches the game’s video to the window size. If checked, DREAMM will only expand the video in exact multiples of the original size, potentially leaving some black space surrounding the game screen. When turned off, the game’s video will expand to fit the window size completely—while retaining the correct aspect ratio—which may result in minor scaling artifacts. This setting can be toggled directly via the Alt+I⌘I shortcut.

The Full Screen Mode setting’s behavior is fairly obvious. When checked, DREAMM will run the game in full screen mode; otherwise, the game is run in a regular window. The key combination Alt+Enter⌘↩ toggles this setting directly.

Regardless of the Full Screen Mode setting, you can use the Grow Video One Step and Shrink Video One Step commands to alter the game’s visible size in even multiples of the game’s aspect ratio-corrected resolution. For example, if the game is running at 320×200 resolution, and you have “Correct Aspect Ratio” enabled, the aspect ratio-corrected resolution is 320×240, and these commands will step the game’s active area larger or smaller is increments of 320×240. Use the shortcuts Alt+Plus⌘+ and Alt+Minus⌘– to alter the size directly.

In windowed mode, the Grow/Shrink Video One Step options alter the size of the window itself, while in full screen mode they just serve to limit the maximum size of the video. In this case, the smaller video area will be displayed centered in the full screen area with black bars on all sides.

Tip: The Grow/Shrink commands work even if you have “Integral Video Scaling” disabled, so it’s a good way to snap the window size back to an even multiple of the game’s native resolution.

Note: DREAMM saves the window position independently for each game and for the Game Manager itself. For example you can configure the Game Manager to run in a window of a certain size, then configure one game to run full screen, and configure a second game to run in a differently-sized window. When DREAMM switches to each case it will adjust itself according to the last configuration for that specific case.

Finally, the Take Screenshot command, most practically invoked via the Alt+Backspace⌘⌫ shortcut, takes a PNG snapshot of the game’s native video and writes it to the game’s screenshot folder. You can locate the screenshot folder from the Configure & Launch screen.

Audio/Video Systems

This section describes the various audio and video systems you may be able to choose when configuring a game. These apply only to DOS-based games; Windows and FM-Towns have standardized hardware instead.

Each DOS game only supports a certain subset of the video and audio options below. DREAMM knows what is supported and will limit your options to those that are viable for the particular game you are configuring. In addition, some games require extra “add-on” files in order to enable support for additional systems; DREAMM is also aware of these dependencies, and won’t show you options that are missing required files.

Video Systems

Hercules (2 colors) — Black and white (or green or amber) monochrome display using Hercules graphics at a crisp 720×350 resolution. Only a few of the earliest games support this at all, and it’s pretty ugly, but DREAMM supports it for completeness. If this video system is selected, you can configure the monitor color via in the In-Game Menu. Just select Hercules Monitor Color and choose between green, amber, or white as your output color.

CGA (4 colors) — This is the classic 4-color CGA mode, running at 320×200 resolution. It was supported for most of the early games, though by the early 90s better graphics cards were required and support was quickly dropped.

Tandy/PCjr (16 colors) — This is the famous “enhanced” CGA mode that the Tandy 1000 and IBM PCjr supported. Enabling this gets you full 320×200 16-color graphics in some games, though some games configure it to use a super chunky 160×200 video mode instead.

EGA (16 colors, planar) — This mode enables 320×200 16-color graphics like the Tandy option, but draws them using the complicated EGA/VGA “planar” modes. Some games leveraged clever tricks in this mode to improve drawing speed, which you probably won’t notice on a modern machine. Some of the later 256-color games supported running in a “Super EGA” (confusingly called SEGA) mode, which ran high resolution 640×200 16-color graphics using dither patterns to fake 256 colors.

VGA (16/256 colors) — This video card is the most flexible option, containing full EGA support, plus the MCGA 256 color video mode described below. In many early games that used only 16 colors, selecting VGA will be effectively the same as running with EGA, while later games will take advantage of the MCGA-compatible 256 color mode.

MCGA (256 colors) — This is the nice, linear 320×200 video mode that is a staple of VGA games. All the SCUMM games support this mode, dating back to the original Maniac Mansion; however, if the game only has 16 color graphics, it will look the same as EGA or Tandy/PCjr in spite of having access to more colors.

Audio Systems

PC Speaker (1-bit DAC) — The option of last resort, the venerable PC speaker offers a single square wave output. Because it was guaranteed to always be present regardless of your PC’s configuration, many early games offered some speaker sound support, though due to its shrill output, it is largely relegated to sound effects and only very occasional music. Speaker emulation is provided by a simple internal emulator.

Tandy/PCjr (SN76496) — Both the Tandy 1000 and IBM PCjr offered an upgraded sound system based on the Texas Instruments SN76496 chip. This chip offered 3 channels of square waves, plus a fourth channel of noise. Like the PC Speaker, it was mostly used for sound effects and occasional music, but its music is definitely a big improvement. SN76496 emulation is provided by an internal emulator.

GameBlaster (2 × SAA1099) — The Creative GameBlaster was the first big step up in audio quality. It used two SAA1099 chips, each of which supported 6 channels of square waves, for a total of 12 voices. For the few games that supported it, you can definitely hear a much richer sound, and the audio was passable enough for music throughout the game. SA1099 emulation is provided by an internal emulator.

AdLib (OPL) — The AdLib sound card was a popular first-generation sound card that offered FM-based sound, using Yamaha’s YM3812 sound chip. This offered 9 channels of highly configurable sounds, and allowed multiple different “instruments” for the first time. YM3812 emulation is provided by my own YMFM library.

SoundBlaster 16 (OPL3 + PCM) — While the SoundBlaster was primarily known for its digital sound support, it also sported AdLib compatibility via the same Yamaha YM3812. Later versions of the SoundBlaster upgraded to the YMF262, which supported stereo output and 18 channels of sound. SoundBlaster is the only supported digital sound card in DREAMM, so if a game has any digital sounds, it will always be part of your audio configuration. YMF262 emulation is provided by my own YMFM library.

Roland MT-32 — The Roland MT-32 was an external box that acted as a MIDI receiver, and came with a full complement of sampled instruments. Music was sent to the MT-32 via standard MIDI commands, with some special extensions available to support new sounds or modify existing ones. In general, for the DOS-based games that support it, the MT-32 is the optimal way to hear the soundtracks. There are several options available for playback of MT-32 audio in DREAMM, but they are extensive enough to warrant their own section.

General MIDI — General MIDI is a standardized set of instruments that allowed multiple manufacturers the ability to produce compatible sound systems. Just before games entered the fully digital age, General MIDI was the state of the art for music. Like the Roland MT-32, there are several ways to hear General MIDI music in DREAMM. Check out the next section for details.

MIDI Configuration

When you select either Roland MT-32 or General MIDI as part of your audio configuration, you will be shown a secondary menu with several options for how you want DREAMM to play it back.

These options require a bit of explanation, as there is a lot of flexibility and power offered here.

Important: Several of the MIDI configuration options require you to provide one or more files for DREAMM to use in its emulation. DREAMM expects to find these files in its sounddata folder, as described here. Fortunately, in all cases you can simply drag & drop the relevant files onto DREAMM’s Game Manager window (before running a game), and DREAMM will stash them away for later use.

Option 1: Emulation

For the Roland MT-32 only, you have the option of using the munt MT-32 emulator, which does an excellent job of reproducing the original MT-32 audio. DREAMM ships with a version of Munt already installed.

In order to activate the munt option in the menus, you will need to provide two ROM files from the original MT-32 system. To install the ROM files, simply drag & drop them onto DREAMM’s Game Manager window as described at the start of this section.

To verify whether you have all the necessary files, check the information provided in the DREAMM About Box. If everything is in place, it will say “MT-32 Emulation Available”; otherwise, it will tell you which file(s) you are missing.

Option 2: SoundFonts

The next option available to you is to use SoundFonts with DREAMM’s built-in SoundFont synthesizer. Sound fonts have a .sf2 extension, and can be installed from DREAMM’s Game Manager by dragging and dropping them onto DREAMM’s window before running the game. Once installed, DREAMM will detect and offer them as options for playback, both for Roland MT-32 and for General MIDI.

Note: SoundFonts come in all sorts of varieties, so not all SoundFonts are going to work well. Some are very demanding on the CPU, and some just plain don’t sound good in DREAMM. Experiment and share your favorites!

At the very least, you will want to find a good General MIDI SoundFont for use in games that use General MIDI.

DREAMM can also use General MIDI SoundFonts for Roland MT-32 playback by mapping the MT-32 instruments to General MIDI; this is imprecise however. You’ll almost certainly get better results by finding an MT-32 SoundFont, which will attempt to replicate the MT-32 instruments. DREAMM automatically detects whether you’ve configured a GMIDI or MT-32 SoundFont by examining the order of the instruments in the file.

While I can’t claim to have tested a huge variety of SoundFonts, I can at least recommend the fonts I’ve been using:

• General MIDI: Arachno SoundFont
• MT-32: HEDSound MT-32 SoundFont

If you have positive experiences or recommendations of other fonts, feel free to let me know, and I’ll add them to the list!

Option 3: MIDI Ports

Your final option—and the one DREAMM uses if you have provided no SoundFonts or MT-32 ROM files—is to use a MIDI port, which allows DREAMM to send MIDI commands to virtual or external MIDI playback hardware. These options should generally be available to everyone, even if you don’t have an external MIDI device, because both MacOS and Windows provide a built-in virtual MIDI synthesizer that does a respectable job of playing back General MIDI.

In addition to the built-in virtual synthesizer, you may also see options for other software and hardware synthesizers. For example, if you install the munt virtual MIDI driver in your system, it will show up as an entry in this menu; this is an alternative to setting up munt directly as described above, and works just as well. And if you have any real MIDI-capable hardware connected to your system, it should be listed as an option.

When configuring for General MIDI playback, you will just see a simple list of devices. But configuring for Roland MT-32 playback, each device will appear twice: once with (GMIDI Mode) and once with (MT-32 Mode).

For most general purpose devices, you’ll want to select the (GMIDI Mode) variant, which instructs DREAMM to translate the Roland MT-32 commands into General MIDI. However, if you have a real MT-32-compatible device connected to that port, select the MT-32 Mode option instead to send the raw commands in full fidelity to your device. (Yes, this actually works!)

Upgrading From DREAMM 1.0

After DREAMM 1.0 was released, I went back through the system and redid significant portions of it. Part of this was to make it more cross-platform friendly, and part of it was to enable support for more types of games.

This means that if you’re coming from DREAMM 1.0, you’ll find a number of things are different this time around. Here’s a brief summary of the most significant changes:

New configuration format. DREAMM now stores configuration information differently, so the first time you run it, DREAMM will behave as if you had no games installed. Use the Search for Games button to install your previously registered games from DREAMM 1.0.

New game installation procedure. DREAMM 2.0 copies all game data to a central install folder, rather than running the games from wherever the source data lived. This reduces the risk of games randomly disappearing, but does make adding games a bit more heavyweight (and also consumes disk space). If you are running low on disk space, you can change the installation folder to a drive with more room.

Revamped user interface. In order to expand support beyond Windows machines, the core of DREAMM was re-built on top of SDL, rather than using Windows-native controls. This means that the front-end game manager interface is significantly different, so adding and launching games is fairly different now. Also, the menubar is gone from the top of the window, and within the game you need a special key combination (Alt+U⌘U or F12) to gain access to in-game options.

Beyond this, there are a number of smaller tweaks and improvements. Take a bit of time to explore once you get up and running!

Frequently Asked Questions

Why does DREAMM exist?

#1 reason? For fun. As you might have gathered, I’m into writing emulators. Working on MAME these days is way more work and stress than fun, so I thought it was time to move on to something new.

I was inspired after doing an interview with mixnmojo.com about my past Windows ports of the LucasArts SCUMM games. I realized I was still salty after all these years about how they were handled, so I started thinking about how I could resurrect them, at least in spirit.

Thus was born DREAMM, a fully emulated solution for running a curated collection of games, with a friendly user interface to make it approachable.

DREAMM gave me a chance to write a new, high-performance i386 emulator from scratch, plus I got to leverage my existing YMFM library and my personal SoundFont synthesizer engine. It was fun to figure out how to implement enough DOS and Windows system calls to fool the games into thinking they were running on the real thing. And I dusted off my classic Win32 programming skills to write a simple GUI frontend.

For DREAMM’s second release, I got to have even more fun. I wrote fast, hand-crafted assembly language i386 interpreters for both ARM and x86 systems, implemented a full Direct3D software renderer, wrote a new user interface layer, and built it all on top of SDL, meaning it now works on multiple platforms including MacOS.

Can I run DREAMM on Linux?

Not yet, but perhaps sometime soon?

I have compiled for Linux in the past, so it’s possible. I am still working out ways to package a Linux version, and hope to have one out eventually.

How is DREAMM different from ScummVM?

One of the biggest differences between DREAMM and ScummVM is in the scope of supported games. While there is a big overlap between the two when it comes to the SCUMM games, DREAMM has opted to expand in the direction of supporting a number of other LucasArts games as well, including several that ran on early Windows systems. Many of these games don’t fit well under ScummVM’s umbrella.

Beyond the scope, there is a difference in philosophy. ScummVM is a modern reinterpretation of the original SPUTM game engine. Its fidelity to the original games is limited to the accuracy of the reverse engineering efforts, combined with how closely the ScummVM developers choose to mimic precise behaviors and details. In general, it does an excellent job at this, and in fact, DREAMM’s existence has revitalized some efforts to improve their fidelity even more. That said, since ScummVM is not actually running the original interpreter engine code, it is difficult to claim 100% perfect reproduction of the original behaviors.

DREAMM, on the other hand, runs the original SPUTM game engine code in an x86 emulator. This means that fidelity to the original depends largely on how accurately DREAMM emulates the well-documented x86 architecture, which is a more tractable thing to prove. Further, it means that you get all the original “chrome” (such as the save/load screens) and behaviors of the original game. Finally, DREAMM provides a streamlined, simple user interface that is customized for running the games.

In the end, for those interested purely in the SCUMM adventure games, the two programs are roughly equivalent. But if you’re interested in other LucasArts games, or enjoy the added fidelity of running the games in an emulator, DREAMM might be closer to what you want. Try them both!

How is DREAMM different from DOSBox?

DOSBox is a generic DOS emulator, and has a lot of similarities to DREAMM in how it is constructed. Both DOSBox and DREAMM emulate an x86 machine and all attached peripherals, and offer a fake implementation of DOS to service requests from the games.

But DREAMM takes this concept further by optimizing its experience and interface around a specific, curated set of games. This means that mouse cursor control is integrated, video updates are done without tearing, and idle time is given back to your system. It also means that DREAMM will help you install your old games into its environment, and will handle all the configuration of video and sound devices.

Finally, DREAMM has the advantage of including a miniature 32-bit Windows implementation as well that allows it to run later games like The Curse of Monkey Island and even early 3D games like Grim Fandango, plus a miniature FM Towns layer that allows it to run the original FM Towns versions of the games that were released for that system.

Why isn’t the source code available?

In general, I support the notion of open source projects, and have made extensive contributions to several, including MAME, YMFM, and others. However, at this time, the source code for DREAMM remains closed. Why?

Part of the reason for this is because DREAMM leverages a number of privately-maintained component libraries I have written over the years, some of which I’m not prepared to share widely yet. In general, the reasoning for this is a mixture of (a) not yet being happy with the state of things, combined with (b) a couple of instances where I believe keeping the code private may pay off for me commerically in the future. (Keep in mind I quit my corporate job and am now doing all my work freelance.)

But probably the biggest reason why I’m not interested in publishing DREAMM’s code at this time is because going open invites collaboration, and for now I don’t really want to work with anyone else on this project. DREAMM is my own creation, and I have lots of plans for what I can do with it going forward. I really just want to explore those directions on my own time and at my own pace, doing all the work myself.

This might seem like an odd reason, but my most enjoyable programming experiences have been when I got the chance to go off and spelunk my way through a set of problems on my own.

I’ve spent most of my career working collaboratively, in both corporations and on large projects. Now that I’m free from involvement in big projects, I’m having a great time just working on my own project without needing to justify decisions or share roadmaps or coordinate with others.

So I’m going to keep it that way, at least for now. That said, there are a couple pieces of DREAMM that I am considering splitting off into separate projects in the not-too-distant future. But if you’re looking for the DREAMM code as a whole to become available, don’t hold your breath.

Where does DREAMM store data?

DREAMM uses the SDL library to pick the preferred location for storing data.

On Windows, this appears to place data under your personal C:\Users\<username>\AppData\Roaming\Aaron Giles\DREAMM folder.

On MacOS, DREAMM’s data will end up in the /Users/<username>/Application Support/Aaron Giles/DREAMM folder.

At the root of that folder, DREAMM maintains a config.json file, containing information about configuration options, window positions, etc. If things get really messed up for some reason, you can try deleting this file.

DREAMM also creates several subfolders here:

• an install folder to hold installation data (unless you've configured it to be stored elsewhere)
• a gamefiles folder to hold any files written by the games
• a sounddata folder to hold SoundFonts and/or MT-32 ROM files
• a screenshots folder to hold any screenshots taken within the game

Why aren’t there more video options?

Other emulators offer lots of (way too many in my opinion) different graphics smoothing and expansion options. For the time being, DREAMM has opted to keep things simple: you can choose to enable aspect ratio correction and/or the original LucasArts EPX graphics smoothing and that’s about it.

Future versions may support a couple of additional options (perhaps a CRT shader or two?), but no, there are no plans to support SuperAdvHQEagleSAI5x or whatever.

Special Thanks

Although DREAMM is my personal project, it would never have gotten to where it is today without the help of many other folks behind the scenes who helped me out with testing, sourcing alternate versions, and providing feedback.

So a big THANK YOU to all these folks: