Aaron Giles
Documentation
This is the official documentation page for DREAMM.
The documentation on this page applies specifically to DREAMM 3.0; if you need it, I’ve archived the documentation for previous versions here: DREAMM 2.1 docs; DREAMM 2.0 docs; DREAMM 1.0 docs.
Contents
There’s a lot to go over, so let’s break things up like this:
- Introduction
- Downloading & Installation
- The DREAMM Game Manager
- DREAMM Options & Tools
- Adding Games
- Running the Games
- Audio/Video Configuration
- MIDI Configuration
- Advanced Configuration
- Command Line Options
- FAQ
- Special Thanks
Introduction
DREAMM is a specialized emulator for playing many of your original DOS, Windows, and FM-Towns LucasArts (and LucasArts-adjacent) 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, MacOS, and Linux platforms, with native support for both Intel and ARM processors.
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.
Linux systems require that you have both libsdl2 and libcurl installed. If you play games on your Linux machine, you are probably already configured to go.
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, including a few non-LucasArts but LucasFilm-related games.
This includes of course all the original SCUMM games:
1987
1988
1989
1990
1990
1991
1992
1993
1993
1995
1995
1997
Plus the later GrimE engine adventure games:
1998
2000
Several mid-90s Star Wars games and multimedia CDs:
1993
1993
1993
1994
1994
1994
1995
1996
1996
1996
1996
1997
1998
1998
1999
A number of Indiana Jones action games:
1989
1989
1992
1996
1999
The full slate of late 80s/early 90s combat simulation games:
1988
1988
1988
1989
1991
And the following miscellaneous games:
1989
1990
1992
1996
1996
1997
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.
What’s New in 3.0?
DREAMM 3.0 is a major release, with a ton of upgrades and improvements under the hood that would be ridiculous to try and enumerate. Instead, here’s a super high-level list of user-facing emulation improvements:
- Support for all remaining LucasArts/LucasFilm DOS games
- Better 16-bit Windows support for installers and screensavers
- Expansion packs and upgraders now supported for most games that had them
- Video output now done with OpenGL, including new support for CRT simulation
- Most DOS games now run in a fixed execution mode for more consistent behavior
- Many new functions implemented in the system BIOS, video BIOS, DOS, and Windows
Plus some improvements to the frontend interface:
- Improved look & feel, with higher resolution graphics and some light animations
- Game selection is now scrollable and supports type-to-find
- Multi-disk game installation now directly supported
- Improved per-game configuration interface
- Advanced configuration options for CPU speed and joystick remapping
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
- minivorbis (MIT license) for OGG Vorbis support
- fmtlib (MIT license) for std::fmt polyfill
- FreeType (FreeType license) for TrueType font rendering
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.
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.
If you have never installed a previous version of DREAMM, the installer will ask if you want to install for All Users or for just the Current User. If you choose All Users, you will need to grant the installer administrator privileges to complete the installation.
Note: Prior versions of DREAMM always installed for All Users, and if the installer sees that previous installation, it will install the new version of DREAMM for All Users as well. If you want to switch to a Current User install, just uninstall the previous version of DREAMM prior to launching the DREAMM 3.0 installer.
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.
Linux Installation
Linux releases come as a simple gzipped tar archive (.tgz) file), with separate release files for each platform, x64 or ARM64. Once downloaded, just run tar -xzvf filename.tgz to extract the contents, then run the included dreamm file to start up DREAMM.
If you don’t have libsdl or libcurl installed, you’ll need to install those first using your distro’s supported tools. In addition, if you have the xdg-utils package installed, you will be able to click on links to web pages or local folders in the UI, which is quite useful.
Data Files
DREAMM uses the SDL library to pick its preferred location for storing configuration data and installed games. Typically, this goes under your user directory:
On Windows, you’ll find it here:
C:\Users\<username>\AppData\Roaming\Aaron Giles\DREAMM
On MacOS, it should be here:
/Users/<username>/Library/Application Support/Aaron Giles/DREAMM
And on Linux systems, it defaults to:
/home/<username>/.local/share/Aaron Giles/DREAMM
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 gamedeltas 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
Note: Versions of DREAMM prior to 3.0 stored modified game files in a gamefiles folder. This was changed in 3.0 because each variant of a game now stores modified files separately due to incompatibilities between versions.
Portable Mode
If you would prefer for DREAMM to store all of its data and installed games next to the DREAMM executable, rather than in one of the locations above, you can make that happen by creating an empty config.json file next to the DREAMM executable.
When DREAMM is launched, it checks to see if there is a config.json next to the executable, and if there is, it treats the directory containing DREAMM as if it were the base of operations for data storage. This means DREAMM will write and update the local config.json file, and create the various subdirectories described above.
With Portable Mode, you can easily copy DREAMM to a USB stick or portable drive, and ensure that all installed games and settings are stored in the same location. Then you can take your portable install to any other computer and run it there without any further shuffling of files.
Standalone Mode
If you’re looking for a more streamlined interface, entirely free of the frontend, you can set up DREAMM to run in Standalone Mode. There are two ways of accomplishing this:
- Copy the dreamm executable (and any support files) into a directory containing a supported game. DREAMM will, if launched from there, auto-detect which game it is next to and run it directly.
- Launch dreamm with a command line parameter specifying a path to a directory containing a supported game. If DREAMM determines that the provided path contains all the necessary files in the right locations for one of its supported games, it will launch directly into the game, bypassing the frontend.
You can use this feature to create shortcuts that launch your games directly, if that’s your preferred way of doing things.
You can also leverage this feature to avoid DREAMM’s behavior of copying the game files to the install directory. For example, if you already have a particular game installed, just pass DREAMM the path to that install and it will run it directly from your already-installed files.
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.
First-Time Launch
If this is your first time launching DREAMM on your system, or if you have not installed any games, 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’s 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.
This add games interface can also be accessed even after you’ve added some games, either from the DREAMM Tools screen, 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 typically see by default when you launch DREAMM, with your most-recently-selected game already pre-highlighted.
If you have more than about a dozen games installed, you will see arrows at the bottom left and right that allow you to scroll the list to see more games. You can also use your mouse wheel to rotate the “carousel” of available games.
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. You can also type the first few letters of a game’s name to navigate there quickly.
Note: Because so many game titles start with “Star Wars”, DREAMM ignores that part of the name when sorting the games, and also when typing a game’s name to select it.
Once your desired game is highlighted, click the button to get started.
From the game selection screen you can also access the DREAMM’s which are described in detail a bit later, or you can choose to directly.
Configure & Launch
After selecting a game, you will be presented with the DREAMM’s game Configure & Launch screen.
By default, the 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.
To return to the main game selection screen, click the button.
Below these buttons you will find a detailed description of the game, including name and exact version. If you have installed multiple versions of the 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, or use your mouse wheel.
The large area at the very bottom offers a tabbed interface with additional options. By default, the STATUS tab will be selected, offering 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.
The other tabs are described in more detail below.
Game 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 CONFIG tab on the DREAMM Configure & Launch screen. You will be presented a list of categories on the left, and a list of links to current settings on the right. Click the link of any setting to change it.
The list of available options varies from game to game, and is often different even between variants of the same game. For more details on the sorts of options available here and what they mean, refer to the Audio/Video Configuration, MIDI Configuration, and Advanced Configuration sections of this documentation.
Managing Game Installs
To manage the installation of your game, click the MANAGE tab on the Configure & Launch screen. Doing so will reveal several options related to the game’s files.
Click the link to run a verification pass on the current game’s installed files. This can be useful to ensure that all required files are still present and unmodified. If the verification fails, you will be given the option to remove the install.
If you have multiple versions of a game installed, you will also find a link, which scans all installed variants in the same way.
If you want to free up the space currently taken up by the selected game, click the link. Once you’ve confirmed your intensions, all of the game’s installed files will be permanently deleted.
Note: Uninstalling the game only deletes the files copied from the game’s original media, and does not remove any of the data written by the game post-install, so your save games and any other game-related data will still be safe.
Accessing Game Data
The final DATA tab available on the Configure & Launch screen offers links to help you easily locate a game’s data files on your system.
By clicking the link, you will be taken to the location where DREAMM stores the unmodified copies of the game data copied from your original installation media.
The link, by contrast, takes you to the location where any new or modified files are written by the game. For some games, this may be empty or just contain configuration settings; for others, it may contain save games or other data. When running, any data in this folder takes precedence over the data in the installation folder.
Finally, if you have taken any screenshots of the currently selected game, you will see a link to , which will open up the location where those screenshots are stored.
About DREAMM
While working within the Game Manager, the current version of DREAMM is shown in the upper-right corner of the screen as a link. Click this link to bring up DREAMM’s About box.
The top pair of lines reveal the current operating system, CPU architecture, and DREAMM version, plus the version of SDL currently being used.
Next up are links to this documentation, an email address where you can send bug reports, and information about supporting this program financially.
Finally, you can click the button to view a list of libraries bundled with DREAMM.
DREAMM Options & Tools
The DREAMM Options & Tools screen allows you to configure global options and make changes affecting DREAMM’s overall operation. When you clock the button, you will presented an interface with separate tabs for OPTIONS and TOOLS, described below.
DREAMM Options
The contents of the OPTIONS tab allow you to modify several of DREAMM’s global settings. Click the link next to each option to either toggle it or bring up a menu of possible options.
VIDEO — toggles the frontend interface between Windowed and Full-Screen mode. This can also be changed at any time via the Alt+Enter⌘↩ key combination. Note that when each game maintains its own full screen setting, so changing this setting only affects the frontend.
KEYBOARD — brings up a menu allowing you to control the keyboard mapping within DREAMM. This has the largest effect on Windows-based games, as DOS games tend to work at the scancode level, which is more related to each key’s physical location on the keyboard.
AUTOPAUSE — toggles DREAMM’s auto-pausing behavior. When set to “Never”, DREAMM will continue running even when switched to the background. When set to “When in Background”, DREAMM will automatically pause the game when another program is brought to the fore.
TELEMETRY — toggles DREAMM’s telemetry on and off. Although many folks dislike any telemetry at all, I hope that you’ll at least review the details of what DREAMM does before reflexively turning it off.
DREAMM Tools
The TOOLS tab on the DREAMM Options & Tools screen hosts several interactive tools for managing games and configuring global features.
Add Games
The link brings you back to the same Add Games screen that you encountered the first time you ran DREAMM. As mentioned in that section, installing games can be done pretty much anywhere within the frontend via drag & drop, and doesn’t necessarily have to be done at this screen. However, accessing this screen does get you access to the multi-disk install tool, as well as links to where to find more games.
All the gory details of adding new games is described below in more detail.
Re-Verify Games
Use the link to initiate a scan of all of your installed games, which will re-verify that all required files are present and unmodified.
When you choose this option, you may be asked whether you want to perform a complete re-verification of all games installed or just ones that have not previously been recognized. (If you only have recognized games installed, you won’t be asked.)
Re-verification can take a while, and for each game can result in one of four outcomes:
- The game is verified successfully; in this case, nothing is reported and the scan continues.
- The game is re-identified as something new; in this case, the game’s folder is renamed appropriately and you are told of the discovery. This is especially likely to happen with some games after upgrading to a new version of DREAMM, since sometimes game IDs are changed as new information is discovered.
- The game is discovered to be a duplicate of another game; in this case, you are given the option of deleting the duplicate, or leaving it alone.
- The game doesn’t match any known titles; in this case, you can choose to delete the folder or leave it alone.
Change Install Folder
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 do that via the link.
From this screen you have several options. First, if you’d like to view the contents of the installation folder, click the button, and DREAMM will open it in Windows ExplorerFinderyour distro’s file browser.
If you’d like to select a new folder, simply locate the folder in Windows ExplorerFinderyour distro’s file browser 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 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 ExplorerFinderyour distro’s file browser 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 pressing F5 on the main game select screen.
Manage Sound Fonts & ROMs
Several of the MIDI-based sound systems that DREAMM supports make use of data provided externally. You can either directly copy the data into DREAMM’s sounddata folder, or you can drag & drop files onto this screen.
There are two types of files that can be added here:
- Sound fonts (.sf2 files) contain sound sample data that can be used for MIDI playback. Once installed, they will be visible as MIDI output options for both MT-32 and GMIDI outputs.
- Roland MT-32 ROMs are binary images of the data included on the original Roland MT-32. These files are required to use the included munt MT-32 emulator, which does an excellent job of reproducing the original MT-32 audio.
The center of this screen shows you how many sound fonts you have installed, and also whether a viable set of MT-32 ROMs are available for Roland MT-32 emulation.
If you wish to directly view/modify the contents of this folder, use the button to open it in Windows ExplorerFinderyour distro’s file browser.
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 going to the DREAMM Options & Tools screen, selecting TOOLS, and clicking the button, or by using the Alt+A⌘A keyboard shortcut.
The important thing to understand is that in order to run any of the supported games within DREAMM, 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 Installed Games
The first and easiest thing to do is to click the link. 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 ISO, CUE/BIN, MDS/MDF, and CCD/IMG files. When working with the latter three types of images, just provide the CUE/MDS/CCD files to DREAMM, as the corresponding BIN/MDF/IMG files on their own are not useful for understanding what the image’s contents consist of (though if you do drop a BIN/MDF file, DREAMM will make an educated guess for how to find the corresponding CUE/MDS 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, DREAMM supports installing directly from those disks as well.
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.
Important: If you are installing a CD-ROM based game that contains CD Audio tracks on it, and you are running on a Mac or on Linux, then you won’t be able to successfully install the full game directly from within DREAMM, because DREAMM cannot access the CD Audio on those platforms. Instead, you will need to use a 3rd party tool to make a CD image in either CUE/BIN, MDS/MDF, or CCD/IMG format, and then follow the directions above for installing from the resulting image file(s).
If your game comes on multiple floppies or CDs, then you have several options.
The first option is to use a 3rd party utility to create a disk image file of each disk, and then install them as disk images, described above.
The second option is to use DREAMM’s multi-disk install helper. To get started with a multi-disk install, simply drag the first disk or disk image onto the Game Manager screen. Alternatively, you can click the link on the Add Games screen.
When DREAMM tells you that it can’t find any complete games, click the button at the bottom, which will initiate a copy of the entire contents of the disk you dragged into a temporary folder.
Once the copy is finished, you will see a completion screen encouraging you to drag the next disk or disk image. At this time you can remove the first disk and insert a new one, dragging it onto DREAMM when ready.
Continue dragging items onto the screen until all items have been copied, then click to tell DREAMM that all data is present. At this point, DREAMM will scan the complete set of files it copied and assemble from them the full game.
Your third and final option is to essentially perform the multi-disk install operation manually. Create a folder for each disk, and manually copy the contents of each disk to a separate folder. Then select all folders and drag them in a single group onto DREAMM to scann.
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 three options available.
Click to copy all the game’s files into your install directory. Click if you’ve decided you don’t want to install this item. Or click to skip this installation and all remaining pending installations as well.
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 ExplorerFinderyour distro’s file browser. 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 DOS/Windows 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 three options.
In this case, if you click , DREAMM will launch the game’s installer program directly within the Game Manager window. Clicking instead will leave the game uninstalled. And clicking skips this installation and all remaining pending installations as well.
For most games, DREAMM knows how to navigate the installer and will do so for you automatically, so you can just sit back and let the installer run without needing puzzle through it. However, if you do wish to tweak the install or see what’s going on, you can tell DREAMM to stand down by holding Shift while clicking the button. This will disable any automatic behaviors built into DREAMM for this install.
If you do opt to install manually, or if you find a game whose installer hasn’t been pre-scripted, the proper way to install is described here.
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.
Regardless of whether you installed manually or let DREAMM do the hard work, 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 , 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 ExplorerFinderyour distro’s file browser 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 ExplorerFinderyour distro’s file browser to open the game’s source folder.
Upgrading Games
Many games were upgraded during their lifetime, and some of the later games even had online patches released which could update older versions to newer, less buggy versions.
DREAMM recognizes quite a few of these upgrade patches. To install them, first navigate within DREAMM’s Game Manager to the exact game version you wish to upgrade. Then simply drag the upgrader’s folder or .EXE onto DREAMM’s Game Manager to run it.
Assuming the upgrader is compatible with the selected game, DREAMM will show a screen like the one shown here, giving you the option to run the upgrader or skip it.
To run the upgrader, DREAMM creates a temporary setup and executes the upgrader exactly as if you were running it on a machine with the original game installed.
As with installers, DREAMM is scripted to run many updaters without any further assistance. However, you can override any scripts by holding the Shift key while clicking the button.
If you do opt to install the upgrade manually, just follow the directions in the upgrader, leaving everything at their default settings, and the upgrade should proceed successfully.
Installing Add-on/Expansion Packs
As of version 3.0, DREAMM is aware of and can install add-on expansion packs. Installing an expansion pack is just like upgrading a game: first, you must navigate within DREAMM’s Game Manager to the exact game version you wish to upgrade. Then drag the add-on pack’s disk image or install files onto DREAMM.
If the add-on requires running an installer, DREAMM will run it much like an upgrade. If it is just a collection of files, DREAMM will copy the files to the proper location.
Once any add-ons have been installed, they will be listed after the game’s version description as depicted here. In this case, Secret Weapons of the Luftwaffe has had 4 separate add-ons installed.
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 attempts to map any joysticks it finds in the most logical way to either the traditional gameport (for DOS games) or Windows DirectX (for Windows games). If you want to map your joystick controls differently from DREAMM’s default, you can via the advanced configuration options, accessible from either the front-end or the in-game menu.
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 a later section. You can bring up the options menu directly via the Alt+O⌘O shortcut.
The Volume Controls... item is next. Selecting this item resumes the game, but pops up at the bottom of the screen one or more volume sliders that let you adjust the output volume of the game’s sound. See the Adjusting Volumes section for more specifics.
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 button, described above.
Important: Because these configuration options (apart from the Advanced 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 Deltas item opens the game’s writable data folder in Windows ExplorerFinderyour distro’s file browser 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 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.
Adjusting Volumes
If you select Volume Controls... from the in-game menu, or use the Alt+V⌘V shortcut, you will see a set of one or more sliders pop up at the bottom of the screen. You can navigate the sliders via the keyboard or mouse.
With the keyboard, use ↑ and ↓ to navigate between different volumes, and use ← and → to increase/descrease the volume. Normally, volumes snap in increments of 3dB, though you can override this by holding Shift while adjusting the values. Press Enter or Esc to dismiss.
With the mouse, click and drag the handle of the slider to adjust the volume. As with keyboard navigation, volume is typically snapped to 3dB increments, with the Shift key overriding this behavior. Click anywhere outside of the volume slider box to dismiss the controls and return mouse control to the game.
Generally, volumes should be set to no more than 0dB, which is considered the maximum. In certain rare circumstances, however, it may be useful to overdrive the sound, so DREAMM allows you to go into positive territory.
To mute sound, drag the slider fully left until it says “MUTED” in gray.
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.
Note: While the Volume Controls menu is visible, the game will still be running live. 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 these controls!
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 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.
The Scaling Effect item toggles between one of three scaling modes: Basic Scaling, Simulated CRT, and epx Smoothing. All three of these effects are discussed in more detail below, in the Scaling Effects section. Use the Alt+S⌘S shortcut to toggle this without using the menus for easy before/after comparisons.
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 266×200, and these commands will step the game’s active area larger or smaller is increments of 266×200. 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.
Scaling Effects
In general, your modern system is running at a resolution significantly higher than these old games, and so DREAMM offers several different options for how to scale up those old pixels. You can toggle between these options via the Alt+S⌘S shortcut anytime while a game is running to see which you like better.
Below is a description of each mode, along with a sample screenshot taken at 4x scale with aspect ratio correction enabled.
Basic Scaling
Basic Scaling offers the most straightforward means of stretching lower resolutions to higher resolutions. Each old pixel is treated as a rectangle and expanded to cover the appropriate number of pixels on your monitor. Any pixel boundaries that straddle two modern pixels are blended with the neighboring pixel.
The end result is very close to “nearest neighbor” scaling, but due to the filtering at pixel edges produces a more uniform result.
CRT Simulation
CRT Simulation is the newest and most complex scaling offered by DREAMM, and is intended to approximate the look of old CRTs. It uses a combination of scanline simulation, horizontal filtering, and a shadow mask overlay to produce an overall effect that serves especially the early EGA games well.
DREAMM’s CRT simulation is aware of which video card you are currently emulating, and alters its behavior to attempt to best match the characteristics of a typical monitor of that era. Thus, even games that look identical between EGA and VGA modes with Basic Scaling may have quite different effects with CRT simulation. In particular, low resolution modes (320×200) running on VGA hardware are “double scanned”, and this will be reflected with CRT simulation enabled, giving two visible scanlines per pixel.
In order to produce convincing effects without moire artifacts, you are strongly encouraged to enable Integral Scaling when using CRT simulation. Also, in order to produce satisfactory results, the output resolution needs to be at least 3× greater than the original resolution. For low resolution games this isn’t hard to achieve at standard HD 1920×1080 resolution, but for higher resolution games running at 640×480 and above, you’ll probably only want to enable this feature on 1440p or 4k displays.
If the output resolution drops below the 3× threshold (or 2× for VGA as a special case), DREAMM will automatically fall back to Basic Scaling.
epx Smoothing
epx Smoothing is DREAMM’s third and final scaling option. This algorithm takes the original source pixels and doubles the resolution, applying simple logic to attempt to smooth out the newly-added pixels. It works fairly well for simple line art, but tends to have little effect on more modern graphics.
The epx algorithm was actually developed by Eric Johnston of LucasArts for his Macintosh ports of the early SCUMM games. I later used the same algorithm for my Windows-based ports. Thus, I consider epx to be a fundamental part of LucasArts history, and support it as a nod for those who want to experience the smoothing effect that Mac and, later, Windows users got to enjoy.
Switching Discs Live
For certain games that shipped on multiple CDs, you will be prompted at some point by the game itself to insert a different disc into your virtual CD-ROM drive. To accommodate this, DREAMM inserts additional options into the in-game menu which allow you to switch in a different virtual disc while the game is running.
For games that need this support, you will see additional menu items labelled “Insert Disc n”, where n ranges from 1 to the number of different discs you might need to insert. Next to each “Insert Disc” item is a checkbox to indicate the currently selected disc number. When the time comes to swap discs, simply bring up the in-game menu and select which disc you wish to insert.
As a quicker alternative, DREAMM also binds shortcuts to the disc switching mechanism. Use Alt+1⌘1 to select the first disc, Alt+2⌘2 to select the 2nd, and so on. When you do, a message will appear at the top of the window to confirm your action.
Note: Not all games that originally shipped on multiple discs need to leverage this mechanism. If DREAMM can install all the files from all discs in such a way that the game doesn’t ever need a disc swap, these options will not be shown. Examples of games that fall into this category include: Star Wars: Rebel Assault II and Indiana Jones and the Infernal Machine, among others.
Audio/Video Configuration
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 offered additional options for how you want DREAMM to play it back.
These options require a fair bit of explanation, and very significantly between various platforms. There is a lot of flexibility and power offered here, so if you care about the quality of your MIDI playback, be sure to read the fine print!
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, DREAMM provides a simple mechanism for installing these files to the correct location via the button. Check out the Manage Sound Fonts & ROMs section for details.
Emulation Options
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 go to the Manage Sound Fonts & ROMs screen and then drag & drop the ROMs onto DREAMM’s window as described at the start of this section.
To verify whether you have all the necessary files, check the information provided on Manage Sound Fonts & ROMs screen. If everything is in place, it will say “MT-32 Emulation Available”; otherwise, it will tell you which file(s) you are missing.
If you are on MacOS only, you will see a MacOS Internal MIDI option in the emulation section. This represents the built-in MIDI synthesizer that comes with MacOS and can be a great default if you don’t have other options available.
Finally, at the bottom, you’ll find the OPL MIDI option, which leverages a built-in mapping of GMIDI commands to a set of emulated OPL chips. The result is roughly what you might have heard if you had loaded the SoundBlaster or Adlib drivers on your Windows 95 system and selected them as your MIDI device, though DREAMM uses multiple OPL chips to ensure there’s enough polyphony available to handle the more dynamic MIDI-based soundtracks.
Note: OPL MIDI is more of a fun experiment than a super-reliable MIDI player. It is also specifically a GMIDI device, so configuring it for your Roland MT-32 output will involve an additional translation step as the Roland instruments are converted into their approximate GMIDI equivalents.
Sound Fonts
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 Manage Sound Fonts & ROMs screen 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
A more extensive list of fonts can be found in the DOSBox Staging documentation. If you have positive experiences or recommendations of other fonts, feel free to let me know, and I’ll add them to the list!
MIDI Ports
Your final option is to use a MIDI port, which allows DREAMM to send MIDI commands to virtual or external MIDI playback hardware. Windows users should always see at least one option here, even if you don’t have an external MIDI device, because the OS provides 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 when 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!)
Advanced Configuration
Both the frontend and in-game menus provide access to “Advanced Configuration” options. In general, you probably won’t need to tweak these, but they are available to play with in case you wish to alter a game’s CPU speed or reconfigure your joystick mapping.
When you opt to perform advanced configuration, you will be presented with a menu of options. The images here show two common scenarios, one for DOS-based games, and a second for Windows-based games.
Although the specific options presented my vary game to game, the first option in the menu will always be either Approximate CPU Speed or Approximate Maximum CPU Speed, and is described below in some detail.
Following that will be a section for joystick configuration. If you’re running a DOS-based game, then you will see a single Gameport Remapping option. If you’re running a Windows-based game, there will be several options here, allowing you to configure 2 joysticks’ worth of axes, buttons, and POV hats.
The section below on Joystick Remapping contains additional details.
CPU Speed
DREAMM runs its virtual CPU in one of two different modes, depending on the game:
Fixed Mode execution sets a certain number of instructions that the CPU must execute each second. All emulated peripherals are timed against the CPU’s instruction count like a clock. If your host machine is not fast enough to execute this many instructions per second, then the emulated system runs more slowly in real time compared to its target.
Timed Mode execution sets a maximum number of instructions that the CPU can execute each second, which may actually be set to “Unlimited”. In this mode, all emulated peripherals are timed against the wall clock time. DREAMM will attempt to run at the maximum speed your host will allow, but will throttle back to stay under the specified maximum.
Both modes of execution have their place. Early DOS games generally prefer Fixed Mode, while later DOS games and Windows games prefer Timed Mode.
The mode of execution that is used for each game is controlled by internal DREAMM configuration, and cannot be changed. However, the specific CPU (maximum) speed can be altered via the Advanced Configuration menu.
If the game is configured for Fixed Mode, you’ll see a menu allowing you to configure the Approximate CPU Speed, similar to the first example on the left.
If the game is configured for Timed Mode, you’ll instead see a menu allowing you to configure the Approximate Maximum CPU Speed, like the second example on the right. Note that some of the lower-speed options are gone, and there is now a Maximum option, which means “run as fast as possible.”
Joystick Remapping
Joystick support in DREAMM comes in two different forms.
For DOS games, DREAMM emulates the traditional gameport interface, which offers four analog axes and four buttons, usually distributed across two joysticks. If you’re configuring a DOS-based game, then you will just have a single Gameport Remapping option available to you from the Advanced Configuration menu.
For Windows games, DREAMM emulates two joysticks, each with up to 6 axes, 10 buttons, and 2 POV hats. In this case you will find separate configuration options available on the Advanced Configuration menu for each joystick’s axes, buttons, and POV hats.
To remap any of the axes or buttons, simply click on the entry or select it via the keyboard. Once selected, you will see a message like the one below, asking you to either wiggle the axis you want to assign, or press the button or key you want to assign.
In case of mapping an axis, you can press the – key prior to moving the axis in order to map it reversed from the normal orientation.
In addition to wiggling an axis or pressing a button or key, you can use one of the three buttons at the bottom for special cases:
- Click to abort the change, leaving the existing mapping as-is.
- Click to remove all mappings for the given axis or button, effectively disabling it.
- Click to restore DREAMM’s default mapping of the selected axis or button.
Command Line Options
If you run DREAMM from the command line, you can specify options that will configure how it runs.
Executing a Game Directly
If you run DREAMM like this:
dreamm <path-to-game>
then DREAMM will scan the provided <path-to-game> directory to see if all the necessary files are present to run one of its known games. If all required files are found, DREAMM will bypass the frontend entirely and immediately begin running the provided game.
Specifying Options
You can also specify override values for various options on the command line:
dreamm -opt <name>=<value> [...]
The various supported options you can specify for <name> match the values from DREAMM's config.json files. Here is a list of some of the more useful ones, along with the valid options for <value>:
| Option Name | Possible Values |
|---|---|
| window/fixaspect | true or false |
| window/fullscreen | true or false |
| window/integral | true or false |
| window/scaling | basic or crt or epx |
The -opt command-line parameter can be used multiple times to specify multiple options. For example:
dreamm -opt window/fullscreen=true -opt window/scaling=crt
Note: Any options specified here apply to all games launched within that session. Thus, it makes the most sense to combine this feature with the direct game launching described above to apply to a single game.
Installing or Upgrading a Game
You can install games from the command line by executing:
dreamm -install <path-to-image-file-or-folder> [...]
This command will scan the provided <path-to-image-file-or-folder> for installable games, exactly as if you had dragged the given folder or file onto DREAMM’s game manager. If you are installing a multi-disk game, you can specify multiple paths one after the other.
You can also install upgrades or addons, via the -upgrade option:
dreamm -upgrade <path-to-game> <path-to-image-file-or-folder> [...]
In this case, the path-to-game must be a valid, recognized game, same as if you were launching it directly from the command line.
Displaying the Version
You can display the version of DREAMM by running:
dreamm -version
In addition to showing the current version information, this will also initiate a network check to see if newer versions are available. If so, this information will be displayed as well.
Miscellaneous Switches
The following switches are available but not commonly used:
| ‑list | Dumps out a list of all supported games and game variants. The list starts with the name of the game, followed by the list of all known game variants, followed by known demos, add-ons, installers, and upgraders, in that order. |
| ‑noconfig | Causes DREAMM to ignore the contents of its config.json file for this session. This might be useful if you want to ensure all settings are at their defaults prior to using -opt to configure things. |
| ‑forcesdl | Tells DREAMM to skip using OpenGL for video rendering and instead use SDL, just like previous versions of DREAMM did. Doing this will disable some CRT scaling effects but otherwise DREAMM should operate basically the same. |
| ‑debug | Invokes DREAMM’s built-in debugger on the next game launch. The debugger is really for my personal use, and is officially unsupported, but you can play with it if you want. Type help for a list of commands. |
| ‑window | Forces DREAMM to run in a window. Equivalent to -opt window/fullscreen=false. |
| ‑fullscreen | Forces DREAMM to run full screen. Equivalent to -opt window/fullscreen=true. |
Frequently Asked Questions
Why does DREAMM exist?
Short Answer: Because I like writing emulators and thought it would be a fun project.
Long Answer: #1 reason? For fun. As you might have gathered, I’m into writing emulators.
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.
Out of this came DREAMM, which was my attempt at re-creating the experience of those Windows SCUMM ports, but using emulation under the hood instead of recompiling the source code.
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 2.0 release, 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.
And for DREAMM 3.0 I got to develop more detailed video emulation, dig into how video BIOSes work, and implement a ton of 16-bit Windows support, plus incorporate animation and add more polish to my frontend, all while digging into the early catalog of LucasArts games (plus a couple of LucasArts-adjacent titles as well).
The project has obviously expanded well beyond my initial idea, but I’m still excited to play with it and expand it into the ultimate way to play pre-Y2K LucasArts games.
How is DREAMM different from ScummVM?
Short Answer: DREAMM runs different games, relying on low-level emulation instead of reverse engineering.
Long Answer: 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.
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?
Short Answer: DREAMM provides a simpler user experience and can run Windows/FM Towns stuff too.
Long Answer: DOSBox is a generic DOS emulator, and has a lot of similarities to DREAMM in how it is constructed under the hood. Both DOSBox and DREAMM emulate an x86 machine and all attached peripherals, and both 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 and idle time is given back to your system. It also means that DREAMM will help you install (and upgrade) your old games into its environment, and it will handle all the configuration of video and sound devices.
Finally, DREAMM has the advantage of including a Windows emulation environment as well that allows it to run a host of early Windows releases, 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 use DREAMM instead of running natively?
Short Answer: DREAMM provides a uniform environment and can run Windows games on MacOS & Linux.
Long Answer: It may seem odd that DREAMM bothers to run some of the 3D Windows games, since both GOG and Steam offer many of these games for sale, with compatibility mechanisms to enable their execution on modern systems.
In reality, however, running many of these older Windows games is far from a smooth experience. Older games tend to force full screen mode and switch resolutions on you, so your desktop is all messed up when you’re finished. Further, reading the forums for these games reveals all sorts of problems with widescreen resolutions, failed downloads, audio issues, and other glitches that don’t exactly provide the greatest experience.
Running these games under DREAMM gives you another option, where you don’t have to fiddle with graphics settings or wrestle with incompatiblities when newer versions of Windows are released and break your games. Games that can run within DREAMM on one system will run the same way on other systems that can run DREAMM.
Further, DREAMM lets you run the games fullscreen or windowed with a simple key toggle, and provides an environment that is much closer to the one the games expect. For example, DREAMM only supports 4:3 aspect resolutions, and only at typical sizes of the era when the games were originally released. Some might call this a limitation, but it is in fact a feature. (Those low-resolution textures don’t look any better at 4k than they do at 1024×768, trust me.)
On top of all this, DREAMM allows MacOS and Linux users a simple, lightweight mechanism for running these games, without having to fire up a general purpose emulator, install a compatible version of Windows, and deal with getting it stable and happy. It’s way easier to get started with DREAMM.
Why isn’t the source code available?
Snarky Short Answer: I’m a selfish bastard who is too dumb to realize the superiority of open source projects.
Actual Short Answer: I don’t feel like collaborating yet, and some of my code isn’t ready to be shared.
Long Answer: 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.
But 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 the code for 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.
Why Isn’t DREAMM Packaged As a FlatPak/AppImage?
Short Answer: DREAMM has light requirements and the situation is annoyingly messy.
Long Answer: Well, to begin with, DREAMM’s requirements are quite minimal: SDL and libcurl, both of which are generally on any gaming-capable Linux machine already. So one of the main advantages of using a package manager—namely dependency management—isn’t really much of an advantage.
Beyond that, I admit to being a bit frustrated that there are so many options (don’t forget there’s also snap, plus each individual distro’s package manager as possibilities), none of which is the obvious “right” answer at this time. I don’t really feel like picking a side, and I definitely don’t feel like tackling more than one option. So for now, I just plan to distribute DREAMM as a simple .tgz file.
What telemetry data does DREAMM send?
Short Answer: DREAMM strictly sends information only regarding (a) version updates, (b) crashes, and (c) unimplemented features.
Long Answer: DREAMM sends limited telemetry back to my personal server to help me understand situations that lead to crashes or graphical issues or unrecognized games. If you wish to opt out of this, you can do so from the DREAMM Options & Tools screen.
Since telemetry is a dirty word for some, I’m opting for full transparency. Here is a complete list of all the situations where telemetry is sent:
- Once, the first time you run a new version of DREAMM. This helps me understand how many people are using the program.
- If an unimplemented feature is encountered during runtime. Some missing features are non-fatal, and the notice will be sent silently; others are fatal and will exit the program. This lets me know if I missed implementing something important.
- If DREAMM crashes due to an invalid memory access or unexpected exception. In some cases I can deduce why the crash happened from the information provided (the register contents and a stack crawl).
- If you install a game version DREAMM doesn’t recognize. This helps me know if I’ve missed any common versions of the games DREAMM runs, so in future versions I can add support for them.
The specific information sent is:
- a unique ID (so I can know how many different machines are hitting each issue)
- the platform you are running (Windows/Mac/Linux)
- the architecture you are running (x64/arm64)
- the version and build date of the dreamm EXE
- the version of SDL you are running
- the ID of the game you are running
- information specific to the event
The unique ID is generated whenever a new config.json file is created, and is based only on the current time and your system clock. No other identifiable information is used when creating it.
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.
In particular, I want to call out:
- Alexander Kaiser, who has tirelessly worked to help track down every last version of LucasArts games we can find, maintaining a vast spreadsheet with compatibility information and bug tracking in DREAMM
- Daniel Albu, who has interviewed me about DREAMM three times now, and allowed me to show off new developments to a wider audience
- John Novak, who encouraged me to add the CRT shader and provided the hand-tweaked parameters that he spent dozens of hours perfecting for DOSBox Staging
In addition to the short list above, I also offer a big THANK YOU to all these folks who have also contributed bug reports, feature suggestions, and general feedback along the way:
(and anyone I may have accidentally left out!)