.dreamm File Specification

As of DREAMM 4.0

This page is an attempt to document DREAMM’s internal text-based game description format. It is a work in progress.

Contents

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

Introduction

DREAMM’s game description files are what power its ability to install, configure, and launch games in a user-friendly manner. The format has evolved greatly over DREAMM’s four releases, as new features have been added or modified to be more powerful.

Game descriptions are stored in text files with a .dreamm extension (earlier releases used a .info extension). Typically, a single file is used to describe one game and all its variants, though it’s also possible to use one file to describe multiple games, or to split one game out into multiple files.

Hacking DREAMM’s existing descriptions

DREAMM’s built-in game support is stored in an internal ZIP file, which you can extract via:

dreamm -extractall ifsdreamm :ifs

This command will extract the contents of the internal ZIP file to a directory called ifsdreamm. In that directory you will find a bunch of stuff, but this document is concerned with the contents of the dreammpack/dreamms subdirectory, which houses all the .dreamm files.

If DREAMM sees a directory named ifsdreamm next to the executable, it will load those files in preference over its internal files. This allows you to easily fiddle with existing definitions. To test whether this is working, go ahead and modify the name at the top of a file representing a game you have installed. Then run DREAMM to see if the change stuck.

Creating new descriptions

If you want to try out new games in DREAMM, you can do so via the -launch command:

dreamm -launch <path/to/exe>

DREAMM will load the executable file at <path/to/exe> and determine if it is a Windows EXE program, a DOS EXE program, a DOS COM program, or a DOS batch file. Based on that information, DREAMM will internally create a mini .dreamm file to try and run the game.

If you’d like to capture a starting point for running that game in the future, you can use the -makedreamm option. When used together with -launch, it causes DREAMM to write the internally-created .dreamm file to the location you specify:

dreamm -makedreamm <path/to/dreammfile> -launch <path/to/exe>

Once you have the .dreamm file, you can begin to modify it as described in this document.

Note that the -makedreamm command must appear before the -launch command, since the launch command will treat anything after it as part of the command line to pass to the game.

After making changes, you can pass the .dreamm file to the -launch command directly:

dreamm -launch <path/to/dreammfile>

and test out the changes without having to recreate the original command line parameters.

The .dreamm files created this way are only useful as starting points or experiments. If you are interested in creating DREAMMPacks to support games, including easy installation and configuration within DREAMM, see the section on Installable DREAMMs once you have your game up and running.

Making changes stick

By default, when using the -launch command, any changes made by the program are lost when DREAMM exits. This is because DREAMM just uses an internal RAM disk to hold modified files.

If you want the program to be able to make changes that persist, you can use the powerful -mount option in conjunction with -launch.

For example, if you want to persist any changes the game makes to the C: drive, you just specify a mount like this:

dreamm -mount rw:C=path/on/host -launch path/to/game

This causes all newly-created or modified files on the C: drive to be written to the specified path/on/host on your host system, rather than to the temporary RAM disk.

Note that the -mount command must appear before the -launch command, since the launch command will treat anything after it as part of the command line to pass to the game.

You can specify multiple -mount options at once, and they can map any part of the virtual drive hierarchy. For example:

dreamm -mount rw:C:\DREAMM=hostpath1 -mount rw:C=hostpath2 -launch path/to/game

would write all changes that were made in the C:\DREAMM subtree to hostpath1, while any other changes to the C drive would be written to hostpath2.

Launching CD-based games

While the basic -launch command works fine for games that install completely to the hard disk and don’t require a CD. However, games that do require a CD will require you to tell DREAMM where the CD-ROM files live. This is also accomplished via the -mount option.

Since DREAMM assumes that your virtual D: drive is the CD-ROM drive, you need to mount the contents of the CD-ROM to the virtual D: drive like so:

dreamm -mount D=path/to/cd -launch path/to/game

DREAMM supports both directories and CD images in the path/to/cd field. CD images are preferred and more likely to succeed because they contain the raw data tracks, CD audio tracks, and metadata such as the volume name, which is frequently checked by games. But if the game doesn’t check for that stuff, a loose collection of files in a directory will work just as well.

Note that the -mount command must appear before the -launch command, since the launch command will treat anything after it as part of the command line to pass to the game.

If you have a CD-based game that can be run directly from the CD, unfortunately you will need to extract the executable to use with the -launch command, since DREAMM currently requires direct access to the executable to determine its characteristics.

Adjusting common parameters

The default .dreamm file that is created when using -launch is configured as follows:

If you want to change these pararameters, you can use -makedreamm to output the .dreamm file and modify things there, or you can use the -property option to specify properties directly from the command-line.

Here are the most common properties you may want to adjust. For more detailed information, plus additional options, see the System Properties documentation:

For example, you can launch with:

dreamm -prop videohw=cga -prop ramkb=640 -prop mips=1.2 -launch path/to/game

to launch a DOS game with CGA hardware, 640KB of RAM, and running closer to a 10MHz 286 speed.

Note that any -prop commands must appear before the -launch command, since the launch command will treat anything after it as part of the command line to pass to the game.

Installable DREAMMs

To make a game installable within DREAMM like the built-in games, you will need to go beyond the minimal .dreamm files created by the -launch command. Those files have several characteristics that make them unsuitable for the general case:

DREAMM’s philosophy is that it should be easy to install games from their original media, as well as from online stores like Steam and GOG. For some games, this is relatively easy to achieve. For others, it will take some hard work!

Below you’ll find some steps that outline what needs to be done to take a .dreamm file from its minimal state into something that can be shared and used more broadly.

Enumerating game files

The first and most important step toward making a proper .dreamm file is to add to it the full list of files needed by the game.

By default, when DREAMM creates a .dreamm file for use with the -launch command, it just creates a single dummy file object within the game variant. This works because the file objects are only relevant at installation time, and when you -launch a game you’re running something that’s already effectively installed.

To support proper installation, DREAMM needs to know the complete list of files required, and where they should live in the installation directory.

The easiest way to generate a list of files is to use DREAMM itself to output the list. From the command line, you can run

dreamm -dirinfo path/to/game

and DREAMM will output a full list of all the files in the directory hierarchy in file object format. These entries can be copied and pasted into your .dreamm file, replacing the dummy file object that DREAMM put there. Note that path/to/game can be a directory on your hard drive, or any other image format that DREAMM supports.

However, this is just a starting point! You will want to curate this list a bit, marking optional files with optional = true, and removing the CRC/size data for unimportant files that might change between releases, like text files. You’ll also want to delete any game-generated files that wouldn’t be present in a fresh install.

If the game has an associated CD-ROM, you will also need to document the files that are on that. You can use the -dirinfo command here as well, just passing the CD image file, to get the list of files. This list should definitely be scrutinized for unnecessary junk as well, like demos, extra programs, etc. that aren’t needed for running the game.

If you have file lists from multiple locations (for example, the game install directory plus a CD), then you will probably want to segregate those games in the install folder. You can do this by modifying the name property on the file objects to place them in specific subdirectories. For example, you could prepend INSTALL\ to the name of all the files that are installed, and CD\ to all the files that were on the CD. If a game has multiple CDs, you will almost certainly want to place each CD’s files into separate directories.

Picking an anchorfile

Once you have your file lists and install directory layout defined, you’ll want to pick an anchorfile.

The anchorfile is a required property set in your variant that is used to optimize DREAMM’s scanning process. It should be the name of a file that is as unique as possible to the particular game, such that if DREAMM sees a file with that name, it knows that it will be worth scanning the directory tree around that file for this game. A bad example would be SETUP.EXE, since that’s a super common and generic name. A better example would be something with the game’s name, like DOOM.WAD.

Anchorfiles can live anywhere within the game’s directory hierarchy. However, by default, DREAMM only searches the directory tree starting where the anchorfile lives. If you want DREAMM to start its search higher up in the tree, specify the anchordepth property, and set it to the number of levels above the anchorfile location where you want the search to begin.

For example, if you had this directory tree, say on the game CD:

\ GAME\ SUBDIR\ ANCHORFILE

then you would want to specify an anchordepth of 2, so that DREAMM will start scanning two levels above the anchorfile, at the GAME directory. If the game also needed some files at the root, you could bump the anchordepth up to 3.

Fixing up the mounts

The next thing to fix up are the mounts. By default, DREAMM creates two mounts:

  1. a read-write mount mapping the root of the C drive to a RAM disk
  2. a read-only mount mapping the rootpath (either C:\DREAMM for DOS games or C:\Program Files\DREAMM\Generic for Windows games) to the host-side directory where the launched executable lives

If you launched the games with one or more additional -mount options, those are included as well ahead of the two default items so that the ones you specified take precedence.

The thing that needs to be fixed are the references to locations on your physical hard disk. Instead, these mounts should be redirected to locations controlled by DREAMM.

For the read/write mount that covers all of the C drive, this is easy: just change the srcpath = ram to srcpath = $(ifsdeltapath). The ifsdeltapath variable is set by DREAMM when starting a game, and points to the location on your host machine where the game-specific deltas are stored. For the most part, there's only a need for this single read-write mount.

For the read-only mount mapping the rootpath, change the srcpath from the hard-coded location on your system to $(ifsinstallpath). You may optionally append additional paths to $(ifsinstallpath) if you located the installation files somewhere else within the install hierarchy.

For any other mounts that are present, you’ll need to fix those up to point to directories relative to $(ifsinstallpath). For example, if your game is CD-based, and you specified that the CD’s directory tree get installed to the CD directory, then you would change the srcpath to point to $(ifsinstallpath)/CD.

In general, you should not leave any mounts that refer to CD image files, and all mounts should be relative to either $(ifsdeltapath) or $(ifsinstallpath).

For more detailed information on the mount objects, see the reference documentation below.

Creating a DREAMMPack

In order for DREAMM to load your .dreamm file automatically and include it as part of the available games, you need to wrap it in a DREAMMPack. DREAMMPacks can be installed via the Manage DREAMMPacks menu option in post-4.0 experimental builds.

A DREAMMPack is just a well-defined directory structure containing one or more .dreamm files along with a special pack.dreamm file that describes the pack as a whole. The directory structure looks like this:

pack.dreamm dreamms/ (one or more .dreamm files) icons/ (zero or more 256x256 ARGB PNG files used for icons) customs/ (zero or more custom PNG files used for overlays)

When releasing DREAMMPacks it is recommended that this file structure be ZIPped and then renamed to have a .dreammpack extension. But during development, a folder of loose files is fine as long as it has this structure.

The pack.dreamm file is pretty minimal and looks like this:

pack[]: name = (friendly name of pack) author = (optional; your name here) link = (optional; link to where you distribute your packs) end

Once your DREAMMPack is installed, DREAMM will load it at startup and treat the games described therein just as it treats its built-in games. To make changes to your .dreamm files, you can either directly edit the installed pack (assuming it was a loose collection of files), or you can edit a working version and then use the Manage DREAMMPacks menu to install that version as an upgrade to your existing pack.

Tips and Tricks

Quite a lot of how to create .dreamm files is based on experience with typical game and installer behaviors. This section attempts to capture some of the common (and less-common) situations that might lead you to a solution.

Debugging Tips

Miscellaneous Tips

.dreamm File Conventions

These are my personal preferences and recommendations, not hard requirements.

Core Concepts

A .dreamm file is a UTF-8 text file.

It is parsed one line at a time, with all leading and trailing whitespace stripped. Thus, line endings are significant, but whitespace on either end is not.

Comments begin with // and continue to the end of the line. Multi-line comments are not supported.

There is no escaping mechanism; instead, built-in variables are provided to cover embedding special characters and whitespace.

Game description files are fundamentally collections of properties and objects, which are described in more detail below.

Properties

Properties are just simple name/value pairs and are defined as:

<property> = <value>

where <property> is the name of the property to set and <value> is what you want to set it to.

Property names can be any sequence of letters, numbers, and underscores.

By convention, known properties defined by DREAMM are all-lowercase. If you specify an all-lowercase property that is not recognized, DREAMM will issue a warning. Game-specific properties should be written in UPPERCASE; these will be fully ignored by DREAMM except for performing substitutions.

Variable Substitution

The values of properties can be substituted in most situations throughout the file. To insert the value of a property, use $(propertyname). For example:

// set a user-defined property VIDEO to be 'vga' VIDEO = vga // set the DREAMM-recognized videohw property to be the value of the VIDEO property videohw = $(VIDEO)

Variable substitution is performed “just in time” when needed at runtime. This means that modifications to properties can happen at a later time and still be effective. This will be an important feature later when it comes to options and conditional behaviors. For example:

// set the VIDEO property to be 'vga' VIDEO = vga // indicate that videohw should be set to the value of VIDEO videohw = $(VIDEO) // change the VIDEO property to 'mcga' VIDEO = mcga // when DREAMM queries the videohw property, it will get back $(VIDEO), // and then substitute the final value of VIDEO which is 'mcga'

Sometimes variables need to be substituted within quoted strings (e.g., within scripts). In this case, you probably want the property value to be escaped, so there is an alternate format for this: $$(propertyname). Example:

// FILEPATH has backslashes, which generally need to be escaped when used in C-like languages FILEPATH = C:\foo\bar\file.txt // hey look, our scripting engine is a C-like language; use $$() to escape the backslashes script = if (file_exists("$$(FILEPATH)")) echo("Found")

Multi-Line Values

There are several situations where supporting longer property values is highly useful. To make this work, DREAMM supports a heredoc-like mechanism that begins with the sequence [[[ and ends with the opposite sequence ]]] on its own line.

<property> = [[[<delimiter> <line-of-text> <line-of-text> ... ]]]

Any text that is included between the opening [[[ sequence and the end of that first line will be used as the <delimiter> between each subsequent line of text. (This differs from a traditional heredoc where the text following the opening delimiter becomes the ending delimiter.)

For each <line-of-text> processed, any comments are trimmed, and then all leading/trailing whitepace is trimmed. If the resulting line is not empty, it is appended to the result, with the <delimiter> inserted between lines.

Careful use of the <delimiter> can produce several useful effects, as in the examples below:

// this example produces a string 'ABC' with no spaces // in this case, the delimiter is empty // note that leading/trailing whitespace is trimmed for each line nodelim = [[[ A B C ]]] // here we set the delimiter to be a carriage return plus linefeed // this produces a string with a newline between each line linedelim = [[[$(CRLF) line1 line2 ]]] // in this example we use the string " and " as a delimiter // note the use of the $(SP) substitution to insert explicit spaces that might otherwise be trimmed // we also make use of comments within the string // this produces the string: "Paul and John and Ringo" anddelim = [[[$(SP)and$(SP) Paul // this comment gets trimmed, along with the whitespace before it John // George -- this commmented out line ends up empty and thus discarded Ringo ]]]

Objects

Objects are structured collections of properties and possibly other objects. Objects are introduced by a keyword, followed by either an empty pair of brackets [] or a bracketed id [id], followed by a colon.

If the colon is followed by a line ending, then the object is a multi-line object. Multi-line objects require each property or inner object to be specified on a separate line. A final end marker is used to indicate the end of the object.

Simple objects can also be specified more compactly in a single line form. In single-line objects, multiple properties can be specified, each separated by a semicolon, immediately following the object introduction. Note that single-line objects cannot have inner objects, so if you need those, you must define them in a multi-line object.

Here are some example objects to show the basic format:

// this is a simple single-line object, with no id // properties are separated by semicolons dynamicfile[]: path = D:\$(CDLABEL); attributes = 8; contents = $(NULL) // here is the same object as a multi-line object dynamicfile[]: path = D:\$(CDLABEL) attributes = 8 contents = $(NULL) end // this a config object with an id of 'sound' // note that there is a single 'title' property plus // two inner 'option' objects, each defined as a single-line object config[sound]: title = Sound Configuration option[speaker]: name = $(SPEAKER_NAME); audiohw = speaker option[adlib]: name = $(ADLIB_NAME); audiohw = adlib; priority = 1 end

Conditional Objects

Many objects support a condition property that allows you to control whether or not that object is manifested. The condition is a simple C-syntax expression that is evaluated as true if the result of evaulating the expression is non-zero.

Typical conditions are a boolean combination of one or more properties. In addition, there are several functions can be used to query the environment that the system will be running:

FunctionDescription
file_exists(<path>) Returns true if the file specified by <path> exists in the virtual filesystem. This is useful for enabling options based on the presence of certain installed files.
file_size(<path>) Returns the size of the file specified by <path> in the virtual filesystem, or 0 if not found.
is_game() Returns true if the base variant being run is a full game.
is_demo() Returns true if the base variant being run is a demo.
is_installer() Returns true if the base variant being run is an installer.
is_upgrader() Returns true if the base variant being run is an upgrader.
is_dos() Returns true if the base variant being run has specified a DOS environment.
is_windows() Returns true if the base variant being run has specified a Windows environment.
is_fmtowns() Returns true if the base variant being run has specified an FM-Towns environment.

Below is an example of how conditions can be used in practice:

// define some user properties HAS_VIDEO = true VIDEO_ENABLED = false DRIVERPATH = C:\driver config[video]: // combine properties here using C-style expressions condition = $(HAS_VIDEO) && $(VIDEO_ENABLED) option[vga]: name = $(VGA_NAME) videohw = vga // test for the presence of a file; note the $$() syntax // so that the DRIVERPATH is escaped for use within the string condition = file_exists("$$(DRIVERPATH)\\vga.drv") end end

File Structure

A .dreamm file consists of one or more desc objects, each of which is its own little world. Each desc object contains properties and objects, some of which may contain additional object types.

Object Hierarchy

Here is a reference for the hierarchy of supported objects:

desc[id]: // base descriptor // // these objects are global to the descriptor // mount[]: // one or more mounted directories/images in the virtual filesystem config[id]: // zero or more configuration options option[id]: // one or more options within a configuration configutil[id]: // zero or more configuration utilities dynamicfile[]: // zero or more dynamically-generated files idle[]: // zero or more idle loop catchers warning[id]: // zero or more warning messages script[id]: // zero or more script contexts scraper[id]: // zero or more screen scraper descriptions charset[id]: // zero or more character set definitions image[id]: // zero or more image identification descriptions mode[mode]: // one or more video modes string[id]: // zero or more string identification descriptions mode[mode]: // one or more video modes // // these objects are all variants of different types // game|demo|addon|installer|upgrader|fragment[id]: // one or more variants file[]: // zero or more files

Built-In Variables

DREAMM has a collection of standard variables available to all files.

General-Purpose Substitutes
$(NULL) An empty string
$(SP) A single space character (ASCII 0x20)
$(SPACE) A single space character (ASCII 0x20)
$(CR) Carriage Return character (ASCII 0x0D)
$(LF) Newline character (ASCII 0x0A)
$(CRLF) Carriage Return plus Newline
$(TAB) Tab character (ASCII 0x09)
$(SEMI) Semicolon character (ASCII 0x3B)
$(QUOT) Double quote character (ASCII 0x22)
$(DSLASH) Two forward slashes
$(NBSP) A non-breaking space character (Unicode 0xA0)
$(NBHY) A non-breaking hyphen character (Unicode 0x2011)
Common User Interface Strings
$(HERCULES_NAME) "Hercules (2 colors)"
$(CGA_NAME) "CGA (4 colors)"
$(TVIDEO_NAME) "Tandy/PCjr (16 colors)"
$(EGA_NAME) "EGA (16 colors, planar)"
$(VGA_NAME) "VGA (16/256 colors)"
$(MCGA_NAME) "MCGA (256 colors)"
$(SVGA_NAME) "Super VGA"
$(SPEAKER_NAME) "PC speaker (1-bit DAC)"
$(TAUDIO_NAME) "Tandy/PCjr (SN76496)"
$(CMS_NAME) "CMS/GameBlaster (2×SAA1099)"
$(ADLIB_NAME) "AdLib (OPL)"
$(SB16_NAME) "SoundBlaster 16 (OPL3 + PCM)"
$(MT32_NAME) "Roland MT-32"
$(GMIDI_NAME) "General MIDI"
CPU Speed Strings
$(MIPS_FMTOWNS) "1.5"
$(MIPS_FMTOWNS_LATER) "2.5"
$(MIPS_286_10) "1.2"
$(MIPS_386SX_20) "3.1"
$(MIPS_386DX_33) "6.0"
$(MIPS_486SX_25) "9.1"
$(MIPS_486DX_33) "12.0"
$(MIPS_486DX2_50) "18.0"
$(MIPS_486DX2_66) "23.8"
$(MIPS_486DX4_100) "33.4"
$(MIPS_P75) "43.5"
$(MIPS_P100) "60"
$(MIPS_MAX) "1000"

System Properties

When starting a game in DREAMM, all the properties are assembled into a final property set in the following manner:

  1. Properties from the root of the desc object become the starting point.
  2. Properties from the selected base variant object are applied on top.
  3. Properties from any addon objects that are part of the current game are applied on top of that.
  4. Properties from any mount objects that are valid and whose condition is true are applied.
  5. Properties from any config objects that are valid and whose condition is true are applied.
  6. Properties from the selected option objects in each config are applied.

This final set of properties is then queried by the game to control certain parameters of execution. The list below describes each property, its potential values, and what it controls.

PropertyMeaning
altkeys Optional for all systems.
Specifies which Alt keys are used by the game, to prevent DREAMM from using them. Use * to indicate the F12 key. For example, altkeys=at1* tells DREAMM to disable its internal Alt-A, Alt-T, and Alt-1 shortcuts, as well as the F12 key.
audiohw Optional for all systems.
Specifies the audio hardware installed on the system. Supported values are: speaker, cms, adlib, sb16, mt32, or gmidi. Multiple systems can be installed at once by combining with a + separator. For example mt32+sb16. To enable Tandy/PCjr audio use machine=tandy.
drivetypes Optional for all systems.
Specifies what type of drive is associated with each drive letter. This is a string of single characters per drive, going from A-Z. Each letter can be one of: F to include a floppy drive; C to indicate a CD-ROM drive, H to indicate a hard disk drive, or any other letter to indicate unmapped. The default value is FFHC, which maps A: and B: to floppy disks, C: to a hard disk, and D: to a CD-ROM drive.
fastmovs Optional for all systems.
Specifies whether to optimize REP MOVS operations. This is useful for reducing CPU requirements on some games, but can produce compatibility issues.
fixdivover Optional for all systems.
Specifies whether to detect and attempt to fix divide overflow errors. It is not uncommon for older DOS games to hit these when running on systems much faster than they were designed for.
launch Required for all systems.
Specifies the full command line to execute, including any parameters. Typically this uses the $(rootpath) variable as the path. Windows-based games should always use quotes around the path to the executable.
machine Required for all systems.
Specifies the type of machine to emulate. Supported values are pc, tandy, or fmtowns.
mips Required for all systems.
Specifies the emulated CPU speed in millions of instructions per second. This value can be fractional. Rather than putting raw values here, you should use one of the built-in variables, as these line up with the options presented in the Advanced Configuration menu. Any values of 60 or below automatically put DREAMM into “fixed execution mode”, which creates more consistent timing. Values above 60 will run in “timed execution mode”, which has more variability but can run at higher speeds.
nothrottle Optional for all systems.
Specifies the number of emulated seconds to run without throttling (synchronizing to real time) at startup. This can be used with games that have a long startup time to help reduce the wait.
osenv Required for all systems.
Specifies the operating system to emulate. Supported values are dos, windows, or fmtowns. The name can be followed by a space and then a version number. For dos, the version should be in the form <major>.<minor>. For windows, the version should be <major>.<minor>.<build>; or you can use one of the following shortcuts: 95, 98, 98SE, Me, NT3.1, NT3.5, NT3.51, NT4, 2000, XP.
rootpath Required for all systems.
Specifies the path within the virtual filesystem that will be the “current directory” when launching the game.

These properties only apply to dos systems:

PropertyMeaning
ramkb Required for dos and fmtowns systems.
Specifies the amount of RAM the emulated system has, in kilobytes. If this value is 1024 or less, DREAMM disables EMS/XMS in DOS programs.
gameport Optional for dos systems.
Specifies one or more comma-separated option overrides for the emulated gameport. Possible values include: timed to force emulated timing (this is the default when running in “fixed execution mode”; see mips above). counted to disable emulated timing and just return values based on the number of times the gameport is read. swapped to swap joystick 1 and 2, for games that only talk to joystick 2. extended to replace joystick 2 with additional axes and buttons from joystick 1.
videohw Required for dos systems.
Specifies the video hardware installed on the system. Supported values are: hercules, cga, ega, vga, or svga. To represent Tandy/PCjr video modes, use machine=tandy and specify cga here.

These properties only apply to windows systems:

PropertyMeaning
locale Optional for windows systems.
Specifies the system locale when launching a game. Only these locales are currently supported: en-US, de-DE, fr-FR, es-ES_tradnl, it-IT, ja-JP, zh-CN, zh-TW, ko-KR.
maxfps Optional for windows systems.
Specifies the maximum frame rate for emulated video modes. By default, video modes run at typical refresh rates; however, for some games it may be beneficial to limit this to improve compatibility or reduce CPU load.
wincrop Optional for windows systems.
Specifies whether or not to crop the desktop to the size of the topmost window. This can be used to achieve a more focused effect on games which do not take up the full screen.
winres Optional for windows systems.
Specifies the desktop resolution at startup, in form of <width>x<height>x<depth>. Valid depths are: 8, 16, or 32. If <depth> is not specified, it is assumed to be 32. The dimensions specified must match one of the supported video modes: 640x480, 800x600, 1024x768, 1280x960, 1280x1024, or 1600x1200.

Objects

desc Objects

The desc object is the outermost object and serves to contain all global properties and shared objects.

All desc objects must have a bracketed id. This id is used as a unique identifier of the desc, and thus must be unique among all files processed. It is used as the directory name for installs and game deltas, so it should only contain characters that are commonly permitted in filenames. By convention the id is of the form <companyid>-<gamename>.

The following <companyid> values have been defined:

idCompany
hasHasbro Interactive
lecLucasfilm Games/LucasArts Entertainment Company
lllLucas Learning Ltd
msftMicrosoft
mindMindscape
paiParroty Interactive
solSierra Online
swtThe Software Toolworks

In addition to the properties described below, desc objects can hold a number of different objects:

desc objects recognize the following unique properties:

PropertyMeaning
filter Optional.
Specifies a comma-separated set of categories to which the game belongs. This is used for filtering on the main game selection screen.
icon Optional.
Specifies the filename of the icon to associate with this game. Icons are loaded from the icon directory of the DREAMM’s internal file system, and should be 256×256 pixel PNG files. If the icon is not found or not specified, a generic icon is substituted. Note that DREAMM groups games on its main selection screen by the icon name provided here, not by desc id.
name Required.
Specifies the display name of the game. This is reflected in the final System Properties as descname.
other properties Optional.
Any other user-specified properties here are valid, and are stored. These can be System Properties or user-defined properties (in ALL_CAPS).

variant Objects

Variant objects are actually not called “variant” in the file. Rather, variant is an umbrella definition for the following object types: game, demo, installer, upgrader, addon, and fragment. Below is a description of each type:

Variant objects can contain both System Properties and user-defined properties, which take precedence over properties in the desc object. If a game or demo variant has one or more addon variants applied, then the properties in the addons take precedence over properties in the base variant.

Apart from properties, variants must contain one or more file objects. These describe the set of files needed to run the game, and how they should be laid out in the installation directory.

The following properties are defined for variants:

PropertyMeaning
anchordepth Optional.
Specifies the number of directory levels above the location of the anchorfile that should be included when searching for a game’s files. If not specified, then DREAMM will start the search in the directory where the anchorfile was found.
anchorfile Required.
Specifies a single filename that can be used as a quick check to decide whether to do a more thorough scan when installing a game. Typically this should be the most uniquely-named file specified for this variant.
imports Optional.
Specifies a comma-separated list of other variant ids whose properties and objects you wish to import. Objects defined in the current variant take precedence over imported items. Imports can be used to describe variants that differ from other variants by just a few files. Multiple imports can also be used to assemble a variant from fragments and/or other variants.
installid Required for installer variants only.
Specifies the id of the variant that will be installed.
name Required for all non-fragment variants.
Specifies the display name of the variant. This is reflected in the final System Properties as varname.
upgradeids Required for upgrader and addon objects only.
Specifies a comma-separated list of variant ids that can be targeted by the upgrade. Each id can be a simple variant id or a combination of multiple variants connected by a + separator (e.g., game+required-addon). ids can also start with a ! to indicate that the upgrader cannot target any game with that variant (e.g., !incompatible-addon).
other properties Optional.
Any other user-specified properties here are valid, and are stored. These can be System Properties or user-defined properties (in ALL_CAPS), and will override any such properties defined in the containing desc object.

mount Objects

Mount objects describe the virtual filesystem that is presented to the game. By default, the virtual filesystem is empty, so at least one mount is required.

The virtual filesystem is super flexible, and thus so are mounts. The easiest way to think about it is that for each file access, take the directory where the file lives and work from the first mount toward the last until a mount is found whose virtual path (aka vpath) includes the file’s directory.

Note that multiple mounts can cover the same directory. For example, you could have one mount whose vpath is C:\, and a second mount whose vpath is C:\gamedir. If a game queries all the files in C:\gamedir then it will include all the files in the first mount under the gamedir subdirectory (if it exists), combined with all the files in the root of the second mount.

For read operations — enumerating files, opening read-only files, querying attributes — DREAMM will scan all mounts, top-to-bottom, until it finds a match. For the specific case of enumerating files, DREAMM will continue scanning over all mounts that match; however, in general DREAMM stops at the first match.

For write operations — creating a new file, creating directories, renaming files, deleting files — DREAMM will also scan top-to-bottom, but will only consider writable mounts. For the specific case of opening an existing file in read-write mode, if that file is first found on a non-writable mount, DREAMM will perform a copy-on-write operation to the first matching writable mount.

In general, writable mounts should be listed at the top. Consider these to be “catch-all” locations for any modifications, allowing the other mounts below it to maintain their integrity.

Here is an example set of mounts:

// the first mount catches all writes to the C: drive in the ~/hd path on the host system mount[]: vpath = C:\; srcpath = ~/hd; writable = true // the second mount is a read-only mount that points to the game's installation directory // and maps to the directory described by the 'rootpath' property mount[]: vpath = $(rootpath); srcpath = /path/to/game/install // the third mount is a read-only mount that maps the contents of the cdrom.cue image to // the root of the D: drive mount[]: vpath = D:\; srcpath = /path/to/game/cdrom.cue

Regardless of operating system, DREAMM always treats the A: and B: drives as floppy discs, the C: drive as a hard disk, and the D: drive as a CD-ROM, unless overridden by the drivetypes property.

The following properties are defined for mounts:

PropertyMeaning
condition Optional.
Specifies the condition under which to process this mount. See Conditional Objects for more detail.
disc Optional.
Specifies the virtual disc number that includes this mount. By default, mounts are visible no matter which disc is selected. However, if you are emulating a multi-game disc and the game really needs it to appear as multiple discs, you can organize your installation files and mark certain paths as being from certain discs with this property. For an example, see the lec-grimm.dreamm file from DREAMM’s internal file system.
optional Optional.
Specifies a Boolean true/false to indicate whether this mount is optional. Normally, if the srcpath cannot be found, DREAMM will fail to launch. Marking a mount as optional means that DREAMM will silently fail and move on to the next mount.
srcpath Required.
Specifies the location (either directory or image file) in your host file system that will map to the vpath in the virtual filesystem. If you prefix the name with ifs: then the path references DREAMM’s internal file system. If you set this value to ram then DREAMM will create a virtual RAM disk and store all changes there; the contents will be lost when DREAMM exits.
subpath Optional.
Specifies the path within srcpath that will be mapped. This is useful if srcpath points to a disk image, and you want to map a subdirectory within that image.
vpath Required.
Specifies the path in the virtual filesystem where the mount will populate.
writable Optional.
Specifies a Boolean true/false to indicate whether this mount is writable. By default, mounts are read-only unless explicitly specified to be otherwise with this property.
other properties Optional.
Any other user-specified properties here are valid, and are stored. These can be System Properties or user-defined properties (in ALL_CAPS), and will override any such properties defined in the containing desc object and any active variant objects. Note that these properties will not be applied if the mount’s condition was evaluated to be false, or if the mount doesn’t exist and the optional property is set to true.

dynamicfile Objects

Dynamicfile objects allow you to generate temporary files within the filesystem that contain whatever data you wish.

Dynamicfiles are created immediately after all the mount objects are set up, and generate files in a temporary RAM-based filesystem. These files can be opened/modified by the game, but any changes will be lost upon exit.

Here are a few example uses of dynamicfiles:

// this creates a volume label (attributes = 8) for the D: drive called MYGAME dynamicfile[]: path = D:\MYGAME; attributes = 8; contents = $(NULL) // this creates a text file with a few registry keys defined // note that variable substitution is applied within the contents REGKEY = HKEY_LOCAL_MACHINE\SOFTWARE\LucasArts Entertainment Company LLC\Grim Fandango\v1.0 dynamicfile[]: path = C:\REGISTRY.REG contents = [[[$(CRLF) REGEDIT4 [$(REGKEY)] "CD Path"="D:" "Executable"="$$(rootpath)\\GRIMFANDANGO.EXE" ]]] end // this creates a binary configuration file WDRV = 0x53 0x42 0x31 0x36 0x2e 0x57 0x44 0x52 0x00 0x00 0x00 0x00 0x00 0x00 WDINFO = 0x20 0x02 0x00 0x00 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff 0xff MDRV = 0x46 0x4d 0x34 0x2e 0x4d 0x44 0x52 0x00 0x00 0x00 0x00 0x00 0x00 0x00 dynamicfile[]: path = $(rootpath)\IMUSE.INI contents = [[[ [[BINARY:$(MDRV)]] [[BINARY:$(WDRV)]] [[BINARY:0x01 0x00 0x00 0x00]] [[BINARY:$(WDRV) $(WDINFO) 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0]] ]]] end

The following properties are defined for dynamicfile objects:

PropertyMeaning
attributes Optional.
Specifies the attributes of the file. In general, you only need this if creating a volume label in the root of a volume, in which case you would specify attributes = 8.
condition Optional.
Specifies the condition under which to process this entry. See Conditional Objects for more detail.
contents Required.
The contents of the file. This can be just a regular string, in which case the data is written as-is. You can also include binary data by writing: [[BINARY:<data>]]. For <data> you can specify individual byte values, separated by spaces. You can also indicate values are words, dwords, or qwords by prepending a W:, D:, or Q: prefix before a number.
path Required.
Specifies the path where the dynamic file should live. It can be anywhere in the filesystem; subdirectories, if needed, will be created up to include the given path.

file Objects

File objects describe the details of all the files required to run a game. DREAMM uses the list of file objects when scanning for and installing new games.

To match a folder or disc image against the current list of supported game variants, DREAMM will scan all the files present looking for a filename that matches the anchorfile property associated with the particular variant. If this is found, then it will scan that directory and all subdirectories looking for a complete set of files that match the list of file objects. If the variant specifies an anchordepth greater than 0, then DREAMM starts the scan that many levels up the hierarchy; this allows for using a more unique anchorfile name that exists deeper in the directory structure.

The process of matching files against the list of file objects is fairly involved, but basically boils down to looking for, in order of preference:

  1. A file with the same name and matching CRC/size.
  2. Any file with a matching CRC/size.
  3. A file with the same name but different CRC/size (this is assumed to be a modified or unknown variant).

If no file can be found that satisfies the above requirements, and the file is required, then the match fails.

An additional important detail is that any path specified in the file object's name field is relative to the installation path. This means that the set of file objects should describe the final layout of the files as they will appear the install directory. This layout does not necessarily correspond to the layout of the files on the source discs; DREAMM’s search algorithm is responsible for shuffling things to match your desired final layout.

Below are some examples to show how files are used:

game[test1]: // a normal file entry; it will be copied to the install path under the FOO\BAR directory file[]: crc = f812ee1e; size = 27688; name = FOO\BAR\FILE1.DAT // an optional file; it will be copied if present, but will not fail if not found file[]: crc = 6a2882cb; size = 446494; name = FOO\BAR\FILE2.DAT; optional = true // a file that must exist but can have any size or any CRC file[]: name = FOO\BAR\FILE3.DAT // a file that has a bunch of garbage after the first 313536 bytes file[]: crc = d00ebfb1; size = 313536; name = FOO\BAR\FILE4.DAT; truncate = true // a CDDA description for a disc that has 9 audio tracks file[]: name = CDDA.SOU; cdda = 146/143/178/148/145/146/59/79/39 end game[test2]: // import properties and file objects from test1 above imports = test1 // this version has a different FILE1.DAT file[]: crc = ea0d8d23; size = 30452; name = FOO\BAR\FILE1.DAT // this version has FILE2.DAT but it was renamed to FOOBAR2.DAT file[]: crc = 6a2882cb; size = 446494; name = FOO\BAR\FOOBAR2.DAT; replace = FOO\BAR\FILE2.DAT // this version doesn't need FILE3.DAT file[]: remove = FOO\BAR\FILE3.DAT end

The following properties are defined for file objects:

PropertyMeaning
cdda Optional.
Specifies a slash-separated list of track lengths, starting with track 2. This field should only be used with files named CDDA.SOU, which represent raw ripped audio tracks. Lengths are specified as seconds, and DREAMM has a fairly generous fuzzy match against the lengths.
crc Optional.
Specifies the CRC of the file contents, as an 8-digit hex string. If not specified, then any file matching the filename portion of the name property will be considered a potential match.
exactonly Optional.
Specifies a Boolean true/false value indicating whether DREAMM should consider a file with a matching name only if its CRC and size match exactly the provided crc and size fields. This is for the unusual case where there are multiple files with matching names (for example, two files with the same name but different contents on two separate discs), and provides some guardrails against DREAMM getting these files mixed up during its matching process.
name Required, unless the remove property is specified.
Specifies the path where the file will be copied to in the final installation folder.
optional Optional.
Specifies a Boolean true/false value indicating whether the file is required. If an optional file is found, it is copied to the install folder; however, if it is missing, DREAMM will just ignore the file.
remove Optional.
Specifies a filename that should be removed from the current list of file objects. This is useful when used in conjunction with the import property, when you want to modify the file list of the imported entries to remove a particular file. This property is generally used on its own, as the only property for its file object.
replace Optional.
Specifies a filename that should be replaced with the current file entry. This works much like remove except that it still expects a name property to specify the replacement filename, along with other properties describing the replacement file.
size Optional.
Specifies the size of the file, in bytes. If not specified, then any file matching the filename portion of the name property will be considered a potential match.
truncate Optional.
Specifies a Boolean true/false value indicating whether a truncated version of the file should be considered. This flag is only rarely used, and is specifically for the case where some copy protection mechanisms create fake extra-long files. When present, if DREAMM finds a file whose name matches, and whose size is larger than the specified size, it will re-compute the file CRC with only the first size bytes included to see if that produces a match. If it does match, then only the first size bytes are copied.

Generic Game Templates

Generic DOS Template

// // Generic DOS launch template // search for ### and modify to suit // desc[generic]: // // configure these variables // INSTALL_PATH = C:\GAME ### the virtual path where the game files should appear to be installed EXE_NAME = GAME.EXE ### the name of the game's executable (can be a .COM or .BAT file as well) HOST_INSTALL_PATH = . ### the path on your host system where the files really live HOST_DELTA_PATH = ram ### the path on your host system where changes should go, or 'ram' to ignore HOST_CDROM_PATH = $(NULL) ### the path on your host system to the CD-ROM image, or $(NULL) if none // // system properties // // friendly name for game name = ### My Game's Name // regular PC running DOS machine = pc osenv = dos // rootpath is the "current directory" when launching rootpath = $(INSTALL_PATH) // we presume that the EXE lives in the rootpath launch = $(rootpath)\$(EXE_NAME) // automatically fix divide overflow errors fixdivover = true // set the CPU speed; see the list of options mips = $(MIPS_P100) // RAM size; default is 16MB ramkb = 16384 // audio hardware; specify speaker, cms, adlib, sb16, mt32, or gmidi, // or a combination like sb16+mt32 audiohw = sb16 // video hardware; specify hercules, cga, mcga, ega, vga, or svga videohw = svga // // environment configuration // script[env]: code = [[[$(CRLF) // use this to configure any environment variables // env_set("VARIABLE", "VALUE"); ]]] end // // filesystem // mount[]: vpath = C:\; srcpath = $(HOST_DELTA_PATH); writable = true mount[]: vpath = $(rootpath); srcpath = $(HOST_INSTALL_PATH) mount[]: vpath = D:\; srcpath = $(HOST_CDROM_PATH); condition = "$(HOST_CDROM_PATH)" != "" // // dummy game description // game[generic]: name = generic // the anchorfile and file objects don't matter unless you're setting // it up for DREAMM to formally install the game anchorfile = DUMMY.TXT file[]: name = DUMMY.TXT end end