Proposal for DOS game package format

From shikadi.net
Jump to: navigation, search

Summary

  • This proposal is to create a single file that stores everything necessary to run a DOS game in an emulator of your choice (or on a real DOS machine.) Each game goes into a separate file.
  • The single file would have a .dos extension and an icon appropriate for the game, so you can just double-click on it to immediately start playing the game - whether you downloaded the .dos file, got it on a USB stick, or have it sitting on your desktop looking like a shortcut to a game. You don't have to "install" the .dos file.
  • It's like all the game's files are put into a single .zip file, but following certain rules so that emulators know what hardware settings to use and which files to run to play the game.
  • You must already have the emulator installed, e.g. DOSBox, or access to a real DOS PC.
  • The emulator must support the .dos format - currently none do, as this is just a proposal. The format is a standard .zip file, so real DOS PCs can use pkunzip to extract the game, just like any other .zip file.
  • Distributing DOS games is messy. Some are .zip files, some are Windows installers, some include DOSBox, some include a DOSBox frontend, and so on. Being able to distribute a single .dos file for each game would be much easier.
  • For simple collections, this could replace the need for a DOSBox front-end. However for larger collections, it is expected that should this proposal gain some traction, front-ends would allow importing .dos files into their libraries. The .dos files contain metadata to help front-ends sort and categorise games.

The rest of this document explains the technical process of how these .dos files should function, where savegames should be stored, and so on.

FAQ

I don't want to have to repackage all my games into .dos files, I like things the way they are!
That's great, then nothing will change for you and this proposal won't affect you in any way. The proposed .dos format is an addition to, and not a replacement for, the way things are done now.
What if I don't want to use .dos files but I start getting games in this format?
As they are standard .zip files, you can simply unzip them and move the content directory to wherever you like and run the game from there.
Are .dos files meant to be archival versions of games?
No, they are intended to be "master" copies, but preconfigured to run in an emulator with no further interaction from a user. The idea is that you can find or purchase a game, download the .dos file, and run it immediately. Typically archivists like to preserve things that are not needed to actually play a game, such as the original installation program. While these are worthy of preservation, they get in the way of someone who just wants to play the game. Archivists also typically prefer to keep the original files distributed by the publisher, so they won't want to repackage these into .dos files anyway, at least not for preservation purposes.
How does DOSBox know which .dos file to use when playing an .ovl mod?
The current proposal is that you must specify both filenames when launching DOSBox. Each package has an ID in metadata.xml, and .ovl files also include a reference there to the ID of the .dos package, so a front-end that keeps a database of game packages will be able to figure this out automatically.

Introduction

Computing power has increased to the point where emulating traditional platforms is not only feasible, but perfectly functional and high performance. The DOSBox emulator does a superb job of emulating the DOS environment, and combined with a number of different front-ends provides an easy way to access DOS games from the 1980s and 1990s.

However packaging and distribution of these games is still somewhat lacking. Typically .zip files or self-extracting DOS .exe files are obtained from various shareware archives and extracted into a "games" folder on the host PC, being careful not to use any long filenames. Then DOSBox is launched and a few DOS commands must be learned to get a game to run. Alternatively a game can be imported into a front-end, however this still requires some effort and metadata such as game titles and genres must be added separately.

This proposal seeks to improve the situation by providing a standardised packaging format for DOS games, which would be directly supported by the DOSBox emulator and its front-ends. The package format would provide all the data necessary to run the game, along with metadata useful for front-ends such as game titles, icons and screenshots, all contained within one single file.

Conventions

In this document, a forward slash ("/") is used as a directory separator on the host machine, while a backslash ("\") is used as a directory separator in the emulated DOS environment. Applications running on the Windows platform may have to replace forward slashes with backslashes when accessing files in the host environment.

While DOSBox is the obvious emulator to use, this package format aims to be emulator-neutral.

Principle of operation

The game data would be placed in a folder, along with configuration and description files. This whole structure would be zipped up into a standard .zip file, but the filename extension would be changed to .dos for easy identification.

These packaged files should be treated like the original disk from a game, and indeed it is hoped that should this package format gain acceptance, those companies still offering their DOS games for purchase would transition to this package format for distribution. For this reason, the .dos package file should be treated as read-only, and it should not be modified. What to do when a game attempts to write data such as saved games or high scores is covered under #Modification below.

Inside this .dos zip package, there would be the following files and folders:

content
Game data files. This folder would typically be mounted as C: in the emulator.
metadata
Information about the game suitable for use by a front-end, described below. Icons, screenshots and other information.
config.ini
Emulator configuration, described below. This controls which hardware is emulated and how to run the game.

Modification

As the .dos package is being treated as a read-only master copy of the game, it should not be modified. However many games do write data, such as configuration settings, high scores and saved games.

Under this proposal, any data a game attempts to write is saved to a separate file, with the same name as the package but with the .sav extension instead. This can be considered an "overlay", in that any files (or disk images) present in the .sav override what is found in the main .dos package. Thus, whenever the game tries to read data from a file, it is first read from the .sav and if it does not exist there, then it is read from the .dos file.

This has the advantage that resetting a game back to its factory default state is as simple as deleting the .sav file. It also opens the possibility of multiple players having different settings or saved games, by each having their own .sav file(s).

The location of the .sav files should be configurable in the DOSBox main config file, and it should default to the user's profile/home directory. This will allow games to be installed centrally with a package manager, and non-admin users will be able to run the games without having write access to the .dos files or the folder they are located in.

The format and folder structure of a .sav file is identical to that of the .dos package, except that the .sav file will have fewer files, as it will only contain those files that have been modified. If a file is modified in the .sav so that it becomes identical to the version in the .dos file again, then it should (but is not required to) be removed from the .sav.

In other words, to merge a .sav into the underlying .dos file, unzip the .dos file, unzip the .sav file in the same location, overwriting any files, then zip up the result into a new .dos file.

Overlays

Many games are now being modified by fans, to create new games based on the original engine. Commander Keen 1, for example, has over 120 different mods available. The original games usually do not allow modified versions to be distributed, so they are typically released as patches. A player makes a copy of the original game, applies the patch, and then has the modified version. Since the original game was never distributed in its modified form (or at all, in the case of games that are not freeware or shareware), there are no legal difficulties.

To accommodate this, it is proposed that the same system used for .sav overlays be extended to allow for an .ovl file that can replace files in an underlying .dos file. Thus, the possible combinations are:

  • base.dos: original game, factory state
  • base.dos + base.sav: original game, with customised settings/savegames
  • base.dos + mod.ovl: modified game, factory state
  • base.dos + mod.ovl + mod.sav: modified game, with customised settings/savegames

Note that when an .ovl overlay is in use, the base .sav is ignored. This is because in a modified game, you don't want to access high scores and saved games from the original version of the game.

Overlays are not intended to provide general patches for games, or to store different versions of games. Typically you don't want to remove a general patch after applying it, so putting it in an overlay is unnecessary. Patches should be applied to the main .dos file, which will produce a .sav with the changes, then the .sav can be merged back into the original .dos file if needed to produce an independent copy with no dependencies. The same goes for different official versions of games - there is no problem distributing these as they are not "modified" (they are official releases) so they can be distributed as a collection of normal .dos files.

Overlays are only needed where you regularly want to switch between playing the base game and the overlay version.

The .ovl format and structure is identical to that of a .sav file. In other words, it contains the same folder structure as a .dos file, but only includes files that have changed. If the config.ini file needs to be modified, then it must appear in full in the .ovl (i.e. the sections are not merged across different package files.)

Emulator configuration

[default]

Default options apply to all launchers unless overridden later.

cpu_min=i8086 | i80286 | i80386 | i486 | i686

This is the minimum processor that must be emulated to run this software. It refers to the instruction set rather than speed. The actual emulated processor may be better than this (subject to cpu_max) however the emulated processor will never be an earlier model than what is specified here. Typically this will be i8086 for simple games, and i80386 for protected-mode games. Use the lowest value that works, even if it would incur a performance penalty.

cpu_max=i8086 | i80286 | i80386 | i486 | i686 | any_x86

This is the latest processor that can be used to run this software. Normally this will be "any_x86" which means any x86-compatible CPU, effectively saying there is no upper limit on the processor type. However specifying a specific CPU here (such as i80286) will remove support for features found in later processors.

speed=4.77 | 6 | 8 | max

This is the speed in MHz the processor should run at, or max if the emulated processor should run as fast as possible. You should specify "max" here unless it causes the game to run too quickly. Only very few games will need a speed listed here, in order to slow them down enough to play. Use 4.77 for an original 8088 XT, and 6 or 8 for an 80286 AT. Values larger than this should rarely be needed as once processor speeds went beyond this point, games began using different methods for governing their speed.

video_min=cga | ega | vga | vesa | vesa2
video_max=cga | ega | vga | vesa | vesa2 | any_vga

These options control which video hardware will be emulated. video_min refers to the minimum requirements for the game. If the game only uses EGA video modes, but will not run at all with the older CGA, then video_min should be set to EGA. In this case video_max is unimportant. If for some reason a game will not work properly on a more recent device, video_max can be used to limit the emulated video device to an older model. The typical video_max will be any_vga which means it doesn't matter what gets emulated as long as it's VGA compatible. Typically this will result in the fastest emulation.

video_max can be used to emulate specific hardware. For example specifying video_max=vga will force DOSBox to use slower, more accurate VGA emulation. This should only be used when a game fails to run with any_vga.

sound=sb:addr=220:irq=5:dma=1:hdma=5,gm:addr=330,pc

Configure the available audio devices. Multiple devices can be specified, separated by commas.

All audio devices supported by a game should be configured where possible, to allow players to change the audio device to suit their preference, using the game's user interface. In the event that two audio devices conflict, the device that comes first in the list will be used.

Code Device Parameters
addr irq dma hdma
sb Sound Blaster Base I/O address (220) IRQ (5) Low DMA channel (1) High DMA channel (5)
gm General MIDI MPU401 address (330) -
gus Gravis Ultrasound Base I/O address (240) IRQ (5) Low DMA channel (3)
adlib Ad Lib -
tandy Tandy Sound System -
disney Disney Sound Source / Covox -
pc PC Speaker -

Other settings typically found in emulators such as mixing sample rates and the location of GM patches are considered user preferences, so do not belong here. They should be set by the front-end or in a system-wide configuration file that applies to all games.

Note that the Sound Blaster is Ad Lib compatible, so do not specify the Ad Lib as an emulated device if the Sound Blaster is present.

network=none | ipx | ip | ne2000:irq=5

Specify what type of network should exist in the emulated environment:

none
No network hardware is present in the emulated environment.
ipx
The IPX API is present, but the underlying hardware device is unspecified (and probably will not be emulated.)
ip
[Not implemented] IP packet driver API is available
ne2000:irq=X
[Not implemented] Emulate an NE2000-compatible device, on the given IRQ.

The actual communication method on the host (e.g. TCP on a specific port) is a user preference and left up to the front-end or global configuration file to control. In the case of DOSBox, a server and client may also have to be specified, but this is beyond the scope of the package format.

mem=63

This controls how much memory is available in the emulated environment, in megabytes. Try to set it as low as practical, e.g. a real-mode game that does not use EMS or XMS only needs mem=1. Some games will use more memory for caching to increase performance, so this value can be increased but should never be set higher than 63. Generally speaking, real-mode games only need values between 1 and 4, while protected mode games will probably perform better with mem=63.

ems=true | false
xms=true | false

These options control whether the Expanded (EMS) and eXtended (XMS) memory interface is present. This should only be enabled for games that actually use it, and of course must be disabled for those games that include their own memory manager (such as Zone 66.)

serial=true | false

Emulate the presence of a serial port, connected to another emulator running the same package. This is used for certain types of multiplayer. The communication method (e.g. TCP on a specific port) is a user preference and left up to the front-end or global configuration file.

Data files

Game files can be made available in a couple of different ways.

drive_X=path[:options]
  • X is the drive letter where the content should appear: a, b, c, d or 0-3 for direct disk access (see below.)
  • path is relative to the root directory inside the .dos file. If path points to a directory, the contents of the directory will be mounted. If path points to a file, it is considered a disk image.
  • options are for hard disk images and allow the geometry to be specified. For floppy disk images, the geometry is determined by the filesize.

Here are some examples. This first example will apply for the vast majority of games:

drive_c=content/

Here, the game package has a folder called "content" and the files inside that are made available as drive C: in the emulator. The trailing slash is optional but recommended, as it makes it clearer that a folder is being mounted rather than a file called "content".

The following examples are for advanced use only, and most games won't need them.

drive_a=content/floppy/
drive_c=content/hdd/

Here, the game package includes a folder called "content" and inside that, another folder called "floppy". The files inside that "floppy" folder are made available as drive A. There is also a folder called "hdd", and the contents of that are made available as drive C.

drive_a=content/booter.img

Here, the floppy disk image "booter.img" is made available as drive A. The exact drive emulated (360kB, 1.44MB, etc.) is based on the size of the image file. There is no drive C: in this environment.

drive_2=content/hdd.img:sectorsize=512:sectors=63:heads=16:cylinders=142

Here the primary hard disk is loaded from "hdd.img" with the given geometry. The emulator makes the image available as a "raw" disk - in the case of DOSBox, a real DOS operating system will have to be booted to read the disk (unless the disk image has an OS installed on it and is directly bootable itself.) It is possible for this image to be partitioned, so it may show up as both drives C and D. The 3 refers to the disk index: 0=first floppy, 1=second floppy, 2=first hard disk, 3=second hard disk.

drive_d=content/cd1.cue,name=content/cd2.cue

Here the CD image specified by "cd1.cue" (found in the "content" folder, inside the game package file) will be mounted as a CD in drive D. When the emulator is told to switch disks (e.g. with a hotkey) the CD drive will switch to "cd2.cue", also located in the game package file's "content" directory. Supplying multiple disk images this way also works with floppy drives.

Launch choices

A launch choice controls what part of the game actually gets loaded. Multiple launch choices are intended for accessing different aspects of the game, such as a setup program or included README program. They are not for trying alternate configurations. Specifically, we want to avoid the situation where a user launches a game, redefines their keys, then tries another launch choice and discovers their custom keys no longer work. If there are different hardware options available then the user should select these within the game itself. If the game has an external setup program, then a launcher should be created for it. This will allow a player to launch the setup, change the settings to their preferred options, then exit and run the game through the default launch option.

The first launch option is the default. It should load the game.

[launch.0]
title=Play
exec=c:\games\duke3d\duke3d.exe

[launch.1]
title=Setup
exec=c:\games\duke3d\setup.exe

[launch.2]
title=Network play
exec=c:\games\duke3d\commit.exe
network=ipx

[launch.3]
title=Play (GUS)
exec=c:\games\zone66\zone66.exe
sound=gus:addr=240:irq=5:dma=3

[launch.4]
title=Play
drive_a=content/booter.img
boot=a
  • launch.0 is first, and it loads the game.
  • launch.1 runs the game's configuration program, allowing options to be set.
  • launch.2 overrides the network option set earlier, to ensure the IPX network is available when the game is launched.
  • launch.3 changes the sound device that is emulated and launches the game with a special command-line parameter to use the new hardware. Normally this is discouraged (the setup launcher should be used to change audio devices) however this game both lacks a setup program, and provides a very different gaming experience with the alternate device (completely different music) so this method is acceptable in this case.
  • launch.4 boots the emulator from drive A, where "booter.img" is mounted. Be aware that in this case the operating system being booted from the disk image is typically unaware of DOSBox devices, so you will probably not be able to mount any directories in this case, only image files.

The current directory is changed to the location of the file given by the exec= parameter, just before running that command. The path and filename are given with respect to the emulated environment, not the filesystem inside the game package file.

If you need to run more than one command to launch a game, or to supply command-line parameters, then the commands should be placed inside a batch file, and the exec= parameter should be given the name of the .bat file instead.

Metadata

In the info directory inside the game package, there should be the following mandatory files: (additional optional files are listed below)

metadata.xml
Game metadata for use by front-ends and cataloguing software.
icon16.png
Small game icon, 16×16 pixels in size. Used in lists.
icon32.png
Medium game icon, 32×32 pixels in size. Used in tiled-icon view.
title.png
Screenshot of the game's title screen.
start.png
Screenshot of the game's starting point. This should be within the first few seconds of the first level in the game. The idea is that this screen is often seen when starting a game from the beginning, so it is likely to be the most recognisable.

It is recommended that both icons be the face of the game's main character where possible, as this is one of the most recognisable images in a game. If there is no main character, try for something the player controls, or would otherwise spend the most time looking at. For example a pinball game might use the ball itself as the icon, if it is quite distinctive.

The two screenshots should be at their native resolution (i.e. don't double-size them.) Typically this will be 320×200 pixels, although it could be 640×400 for 16-colour EGA games or even higher. Front-end authors should ensure the image will be correctly centered and cropped, or shrunk to fit, if needed.

Front-end authors will most likely display the two screenshots when a game is selected, however in a list of games they may choose to display only one. As the title screen does not always convey an accurate indication of what the gameplay will be like, the front-end author may wish to offer the user a choice as to which screenshot is displayed when viewing a list.

The metadata.xml file contains information about the game. This file is not used by the emulator, and exists only for the benefit of front-end or cataloguing software. The file format is as follows:

<!-- The package ID is a unique identifier specific to this version of this
     game.  This code should not change between package revisions.  It is used
     to match .sav and .ovl files back to the base .dos packages.
     The typical format is "<shortname>-<language>-<gameversion>".  In the
     below example the version "sw1.31" refers to the shareware version 1.31,
     as opposed to "reg1.31" which would be the registered version of the same
     revision.
     This ID can be used as a filename, so only use characters permitted in
     Windows filenames (which also covers characters allowed under Linux and
     Mac). -->
<package id="keen1-en-sw1.31">
  <!-- If this were an .ovl overlay, the parent attribute would list the ID of
       the base .dos image, for example:
         <package id="mymod" parent="keen1-en-sw1.31">
    -->
 
  <!-- This is the revision number of this package.  It has nothing to do with
       the version of the game.  Every time the package is changed, even if it's
       only to fix a typo in the metadata, the revision number should be
       incremented by one. -->
  <revision>1</revision>
 
  <!-- This is the platform the game runs on.  For the time being this will
       always be DOS, however this is here to allow the possibility of future
       expansion to other platforms.  A DOSBox-only front-end should refuse
       to import or open a game package if this value is not "DOS". -->
  <platform>DOS</platform>
 
  <!-- This is the language of the game itself.  If the game offers multiple
       languages then this element can be listed multiple times.  If the game
       offers multiple languages but this .dos package does not provide a
       means to change the language (e.g. you are producing one .dos file per
       language) then you should only list the one active language here. -->
  <language>en</language>
 
  <titles>
 
    <!-- The main title is what the player will see when looking for the game in
         a list.  It should be short but contain enough information to uniquely
         identify the game.  Avoid including series names, as they are specified
         below and typically aren't needed to identify a game in a list. -->
    <main lang="en">Keen 1: Marooned on Mars</main>
 
    <!-- The short title should be as short as possible while still being friendly
         and human-readable.  It may be used for space-limited situations like a
         menu of recently played games. -->
    <short lang="en">Keen 1</short>
 
  </titles>
 
  <!-- The collection element holds information about how the game is positioned
       with respect to other games. -->
  <collection>
 
    <!-- A set refers to a collection of games sharing a common main character.
         Typically this will be the name of the game without any subtitle. -->
    <set id="keen">
      <title lang="en">Commander Keen</title>
    </set>
 
    <!-- A series refers to a collection of games within this set.  For example
         six of the Commander Keen games are distributed as trilogies, containing
         three games each.  Here each trilogy is considered a series, as all the
         games in each series/trilogy were released together.
         The index is an integer that refers to the order of this series with
         respect to others.
         Bio Menace has three episodes released as three parts of one storyline,
         so this game effectively only has one series.  In this case the whole
         series section can be left out, unless the series is titled in which case
         the packager may wish to include it. -->
    <series id="vorticons">
      <index>1</index>
      <title lang="en">Invasion of the Vorticons</title>
    </series>
 
    <!-- An episode refers to a collection of games that directly continue on
         from the last, and were released around the same time, with the same game
         engine.  Typically this is used where one episode was released as
         shareware, with another one or two episodes that must be purchased.
         Where a game continues (such as "part 1" and "part 2") but some time has
         elapsed between the releases, that should be considered a different
         series instead (even with only one episode in each series.)
         The index is an integer value that refers to the order of this episode
         within the series.  It is only used when two packages belong to the
         same series. -->
    <episode id="mars">
      <index>1</index>
      <title lang="en">Marooned on Mars</title>
    </episode>
 
    <!-- Additional episodes may be listed where there is an in-game episode
         selection screen. -->
 
  </collection>
 
  <category>
 
    <!-- The genre should come from the following list, so that front-ends can
         display a concise list of genres.  (Best not to have "Platform",
         "Platform game" and "Platformer" as separate entries in the list!)
 
         Board - board game like Monopoly
         Card - card games and tile games like Mahjong
         Demoscene - demo/invite/musicdisk/cracktro - NOT a preview of a normal game
         Driving - driving simulator, car racing, could be first-person or top-down
         Flight - flight simulator, non simulated flight like Terminal Velocity
         FPS - first person shooters like Doom
         Invaders - space invaders or similar games like Raptor, where enemies
                    advance down from the top of the screen
         [Jump 'n Run] - use "Platform"
         Pinball - any pinball regardless of perspective
         Platform - side scrolling platformer
         Pong - bouncing ball and paddle
         Puzzle - puzzle solving, Boulder Dash, etc.
         [Race - see Driving]
         RPG - role playing
         Sport - any sporting game simulator, including golf
         Strategy - requiring planning and forethought, Chess, etc.
         Text - text adventure, incl Space Quest style (graphics with text commands)
 
         There are some non-game genres too:
 
         Art - paint program, graphics editors, ANSI art
         Documentation - information with browser, text files, cheat programs
         Productivity - word processors, office apps, desktop publishing
         Programming - Turbo C, QuickBASIC, etc.
         Presentation - slideshows, advertisement programs, screensavers, see also Demoscene
         OS - bare operating system
         Utility - file managers, shells, etc.
 
         Other genres should be added here as needed to ensure there is
         consistency among different packagers, and to allow
         internationalization efforts to translate the list of genres
         displayed by a front-end.
    -->
    <genre>Platform</genre>
 
    <!-- The multiplayer options specify which, if any, type of multiplayer play is
         available.  Omit any (even all) multiplayer options if the game does not
         support them.  The idea behind these is to allow a front-end to display a
         list of all available games that support a given type of multiplay.
 
         turn: Each player takes full control of the game, one after the other
         shared-screen: All players see the same screen
         split-screen: The screen is split into sections, one per player
         network: Each player uses their own computer (includes via serial cable)
 
         The "max" attribute indicates the maximum number of players who can share
         a game with the given method.
     -->
    <multiplayer type="turn" max="8"/>
    <multiplayer type="shared-screen" max="4"/>
    <multiplayer type="split-screen" max="2"/>
    <multiplayer type="network" max="16"/>
 
  </category>
 
  <!-- Credits are used to record who and which companies worked on the game, to
       allow front-ends to provide features like listing other games by the same
       company or developer.  Try to be as consistent as possible, matching
       character for character names that are already in use. -->
  <credits>
    <publisher>Apogee</publisher>
    <developer>id Software</developer>
  </credits>
 
  <links>
    <!-- A MobyGames link has "http://www.mobygames.com/game/dos/" added at the
         start of the text in this element.  The full link is omitted just in case
         their URL scheme ever changes. -->
    <mobygames>alien-carnage</mobygames>
    <!-- The Wikipedia link is the article title, URL escaped (i.e. the bit
         after "https://en.wikipedia.org/wiki/") -->
    <wikipedia>Alien_Carnage</wikipedia>
  </links>
</package>

Optional files

Additional files can also be included in the info folder, as required:

box-front.jpg, box-back.jpg, box-spine.jpg
Photo, scan, or original digital image of the box artwork.
  • box-front should be suitable for a bookshelf style display where there is lots of space between each shelf item.
  • box-back is likely to only be seen when a user is looking at a particular game, and not in any summary view.
  • box-spine should be suitable for a bookshelf display where only the book spines are visible and there is no space between items. Note that this image should be horizontal rather than vertical (i.e. it is the side of the box as viewed when the box is lying flat on a table.) This allows it to be presented as is, one image below the other as a stack, so that it looks similar to a stack of boxes on a table. It also allows a front-end to rotate the image clockwise 90 degrees to show it like a bookshelf with all the book spines facing out, or even to render a 3D model of the box.
icon.svg
Vector version of the same image used in icon*.png.
shot0000.png through shot9999.png
Additional screenshots
shot0000.txt through shot9999.txt
ASCII text containing a brief caption for each matching screenshot.

Best practices

The following best practices are a guide as to how each game should be packaged to achieve some level of consistency across all games. Sometimes it may not be possible to follow these guides, but the more closely followed these guidelines are, the better the end result for players.

Playability
The game should be playable as quickly as possible on the first run. This means the .dos file should be distributed preconfigured ready to play. Specifically this means things like sound card addresses and IRQs should already be set. The player cannot be expected to know these as they could be set to anything in the distributed config.ini.
Readability
An exception to Playability, where a game offers language selection, this should be made available to the player on the first run. The language will then be saved by the game (creating a .sav file in the process) which should speed up subsequent runs. If it is not possible to separate out the sound card configuration and the language, it is recommended that multiple .dos files be created, one per language. While this creates some redundancy, typically games that exist in multiple languages do so as separate versions, so this will at least provide consistency.
Configurability
All audio devices supported by the game should be configured, however by default the game should be configured to use the one most prevalent at the time. Typically this will be the Sound Blaster. A means should be given for the player to change the audio device, in the following order of preference:
  1. In-game configuration menu
  2. Separate configuration program (e.g. setup.exe) made available as a separate launch item
  3. Separate launch items for different hardware devices
Typically the last option is only required when a game autodetects hardware or uses command-line parameters to control which hardware devices are used.
Interoperability
It is envisaged that the content folder be mapped as drive C:, with the idea being that multiple .dos files could be combined to produce a full DOS system with many installed games and applications. This means that game data files shouldn't go directly into the content folder but rather a subdirectory within. Using Commander Keen's KEEN1.EXE as an example, this file should appear in content/games/keen1/keen1.exe. When content is mounted, this would put the file at C:\GAMES\KEEN1\KEEN1.EXE. The addition of the "games" folder avoids clogging up the root directory of C:, which may become important if hundreds of .dos packages are combined into a single folder tree. Likewise utilities belong in content/util/, applications in content/apps/, and so on. The final folder name ("keen1" in the previous example) does not need to contain version or language identifiers - it is assumed only one version in a single language would be installed in this environment.

Examples

One game split into three episodes, different command to run each episode
Bio Menace has three episodes, each accessed by running a different command. They do not share any data files, so these episodes should NOT be entered as different launchers, but should be packaged as three independent game packages.
One game split into three episodes, in-game episode selection
Jill of the Jungle also has different commands to run each episode, however it has a DOS-based 256-colour graphical episode selection screen. All three episodes should be packaged together, with a single launcher that runs the episode selector.
Network multiplayer
Many games that support network play have a method to launch a network game with the last used settings. If you are packaging a game that can do this, you should include a launcher titled "Network play" that performs this action.
Preconfigured games
Prehistorik can only be reconfigured by deleting the configuration file and launching the game, which includes changing the language. Normally language selection should be left up to the user, however the .dos package best practice is to make the game playable on the first run. So in this case, multiple .dos packages should be produced, one for each language, with each package ready to play.
Multiple devices
Zone 66 has different music tracks for the Sound Blaster and GUS audio devices. However, it lacks the ability to select the preferred audio device (no in-game menu or a setup program.) In this case it is acceptable to have an additional launcher that runs the game with a different audio device present, so that this unique musical content can be accessed.
Game editors
TED5 is a level editor for a number of games, including Commander Keen and Rise of the Triad. While the .dos format really only works for playing games rather than editing them, it would be possible to package up TED5 as an .ovl overlay, with a different overlay for each supported game. This would result in modified level files being saved into the overlay's .sav file, where they could be extracted and a new mod created as an .ovl file. However generally speaking this use-case is not covered by the proposed .dos format.

Possible ideas

These are some ideas floating around that could become reality if the proposal is accepted and implemented.

  • .dos files can be downloaded and run with no further installation once DOSBox is available. The .dos file could even be placed on the desktop and used instead of a shortcut to the game.
  • A shell extension could be written for Windows, which reads the icon files from each package so that the .dos files show up with each game's icon in Windows Explorer. They could even have a little "Z:" overlay (just like shortcuts have the arrow overlay) to show that it is a DOSBox file.
  • em-dosbox could load .dos files from a URL, which would remove the requirement to create a special unique em-dosbox package.

Unanswered questions

Specific hardware

Keen 1 Redux is a 640x480 mod by Lemm, which requires DOSBox to use svga_paradise. Is there a way to specify that a particular type of video card is required to run a package, without tying the format down to a specific emulator? Or is this out of scope for the package format and is deemed too hardware-specific?