sudo dnf install dosbox-staging
For x86 CPUs the SSE 4.2 instruction set is required.
+From the x86 family of processors, all x86-64 processors are supported.
You can always see what’s cooking on the main branch! 
These snapshot builds might be slow or unstable as they diff --git a/preview/dev/downloads/macos/index.html b/preview/dev/downloads/macos/index.html index fc2d8fc6..914fead5 100644 --- a/preview/dev/downloads/macos/index.html +++ b/preview/dev/downloads/macos/index.html @@ -21,7 +21,7 @@ - + @@ -1138,7 +1138,7 @@
This package is compatible with macOS 10.15 (Catalina) or newer and supports both -Intel and M1 Macs.
+Intel and Apple silicon Macs.Check out the 0.80.1 release notes to learn about the changes and improvements introduced by this release.
For x86 CPUs the SSE 4.2 instruction set is required. For Intel Mac models -that don’t support it, you can try using the partial SSE4.2 emulator -MouSSE.
+This package is compatible with macOS 10.15 (Catalina) or newer and supports +both 64-bit Intel and Apple silicon Macs.
You can always see what’s cooking on the main branch!
These snapshot builds might be slow or unstable as they diff --git a/preview/dev/downloads/release-notes/0.75.0-rc1/index.html b/preview/dev/downloads/release-notes/0.75.0-rc1/index.html index 3fa05c95..599d644e 100644 --- a/preview/dev/downloads/release-notes/0.75.0-rc1/index.html +++ b/preview/dev/downloads/release-notes/0.75.0-rc1/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/downloads/release-notes/0.75.0/index.html b/preview/dev/downloads/release-notes/0.75.0/index.html index cbc969f6..d54f7ad6 100644 --- a/preview/dev/downloads/release-notes/0.75.0/index.html +++ b/preview/dev/downloads/release-notes/0.75.0/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/downloads/release-notes/0.75.1/index.html b/preview/dev/downloads/release-notes/0.75.1/index.html index 40f2539e..fdf8b39a 100644 --- a/preview/dev/downloads/release-notes/0.75.1/index.html +++ b/preview/dev/downloads/release-notes/0.75.1/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/downloads/release-notes/0.75.2/index.html b/preview/dev/downloads/release-notes/0.75.2/index.html index 5c16b09b..2f7719e2 100644 --- a/preview/dev/downloads/release-notes/0.75.2/index.html +++ b/preview/dev/downloads/release-notes/0.75.2/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/downloads/release-notes/0.76.0/index.html b/preview/dev/downloads/release-notes/0.76.0/index.html index 3c76f334..8b5d9479 100644 --- a/preview/dev/downloads/release-notes/0.76.0/index.html +++ b/preview/dev/downloads/release-notes/0.76.0/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/downloads/release-notes/0.77.0/index.html b/preview/dev/downloads/release-notes/0.77.0/index.html index 4f8984d9..63626a41 100644 --- a/preview/dev/downloads/release-notes/0.77.0/index.html +++ b/preview/dev/downloads/release-notes/0.77.0/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/downloads/release-notes/0.77.1/index.html b/preview/dev/downloads/release-notes/0.77.1/index.html index b4fb3869..c25fd7e7 100644 --- a/preview/dev/downloads/release-notes/0.77.1/index.html +++ b/preview/dev/downloads/release-notes/0.77.1/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/downloads/release-notes/0.78.0/index.html b/preview/dev/downloads/release-notes/0.78.0/index.html index edc2f044..f9980324 100644 --- a/preview/dev/downloads/release-notes/0.78.0/index.html +++ b/preview/dev/downloads/release-notes/0.78.0/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/downloads/release-notes/0.78.1/index.html b/preview/dev/downloads/release-notes/0.78.1/index.html index 107b9fd9..5596858d 100644 --- a/preview/dev/downloads/release-notes/0.78.1/index.html +++ b/preview/dev/downloads/release-notes/0.78.1/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/downloads/release-notes/0.79.0/index.html b/preview/dev/downloads/release-notes/0.79.0/index.html index 5610c0ac..024b11e2 100644 --- a/preview/dev/downloads/release-notes/0.79.0/index.html +++ b/preview/dev/downloads/release-notes/0.79.0/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/downloads/release-notes/0.79.1/index.html b/preview/dev/downloads/release-notes/0.79.1/index.html index b7e8b2bd..e80cc7fd 100644 --- a/preview/dev/downloads/release-notes/0.79.1/index.html +++ b/preview/dev/downloads/release-notes/0.79.1/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/downloads/release-notes/0.80.0/index.html b/preview/dev/downloads/release-notes/0.80.0/index.html index d2051bcd..09f41eb0 100644 --- a/preview/dev/downloads/release-notes/0.80.0/index.html +++ b/preview/dev/downloads/release-notes/0.80.0/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/downloads/release-notes/0.80.1/index.html b/preview/dev/downloads/release-notes/0.80.1/index.html index d5b5ca0c..d0c16983 100644 --- a/preview/dev/downloads/release-notes/0.80.1/index.html +++ b/preview/dev/downloads/release-notes/0.80.1/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/downloads/windows/index.html b/preview/dev/downloads/windows/index.html index 68cd79d2..9c0c554a 100644 --- a/preview/dev/downloads/windows/index.html +++ b/preview/dev/downloads/windows/index.html @@ -19,7 +19,7 @@ - + @@ -1221,7 +1221,7 @@
SSE 4.2 instruction set is required for version 0.75.1 or newer.
+From the x86 family of processors, all x86-64 processors are supported.
You can always see what’s cooking on the main branch!
These snapshot builds might be slow or unstable as they diff --git a/preview/dev/get-involved/code-of-conduct/index.html b/preview/dev/get-involved/code-of-conduct/index.html index b093bbd4..67c08d3d 100644 --- a/preview/dev/get-involved/code-of-conduct/index.html +++ b/preview/dev/get-involved/code-of-conduct/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/get-involved/index.html b/preview/dev/get-involved/index.html index 8c7ffa7c..a528c198 100644 --- a/preview/dev/get-involved/index.html +++ b/preview/dev/get-involved/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/getting-started/beneath-a-steel-sky/index.html b/preview/dev/getting-started/beneath-a-steel-sky/index.html index 91267938..f339cef1 100644 --- a/preview/dev/getting-started/beneath-a-steel-sky/index.html +++ b/preview/dev/getting-started/beneath-a-steel-sky/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/getting-started/dark-forces/index.html b/preview/dev/getting-started/dark-forces/index.html index 57e27936..6391ed65 100644 --- a/preview/dev/getting-started/dark-forces/index.html +++ b/preview/dev/getting-started/dark-forces/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/getting-started/enhancing-prince-of-persia/index.html b/preview/dev/getting-started/enhancing-prince-of-persia/index.html index 76da11a4..0a4be3cb 100644 --- a/preview/dev/getting-started/enhancing-prince-of-persia/index.html +++ b/preview/dev/getting-started/enhancing-prince-of-persia/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/getting-started/introduction/index.html b/preview/dev/getting-started/introduction/index.html index 6dcb5921..039ebb8a 100644 --- a/preview/dev/getting-started/introduction/index.html +++ b/preview/dev/getting-started/introduction/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/getting-started/next-steps/index.html b/preview/dev/getting-started/next-steps/index.html index 8371f117..8b796c95 100644 --- a/preview/dev/getting-started/next-steps/index.html +++ b/preview/dev/getting-started/next-steps/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/getting-started/passport-to-adventure/index.html b/preview/dev/getting-started/passport-to-adventure/index.html index c1b7d313..dac6005d 100644 --- a/preview/dev/getting-started/passport-to-adventure/index.html +++ b/preview/dev/getting-started/passport-to-adventure/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/getting-started/prince-of-persia/index.html b/preview/dev/getting-started/prince-of-persia/index.html index df75efa6..2baf3c89 100644 --- a/preview/dev/getting-started/prince-of-persia/index.html +++ b/preview/dev/getting-started/prince-of-persia/index.html @@ -21,7 +21,7 @@ - + diff --git a/preview/dev/index.html b/preview/dev/index.html index a44e369e..41a40b34 100644 --- a/preview/dev/index.html +++ b/preview/dev/index.html @@ -17,7 +17,7 @@ - + diff --git a/preview/dev/search/search_index.json b/preview/dev/search/search_index.json index db79c541..e69a9ac4 100644 --- a/preview/dev/search/search_index.json +++ b/preview/dev/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"about/","title":"About","text":"
DOSBox Staging is a modern continuation of DOSBox with advanced features and current development practices.
It is meant as a (mostly) drop-in replacement for older DOSBox versions\u2014your existing configurations will continue to work, but you will have access to many advanced features.
Because DOSBox Staging comes with sensible defaults, you\u2019ll need to write a lot less configuration than with older DOSBox versions. Most games and application software require no tweaking and will work fine with the stock settings. However, the extensive configuration options and advanced features are available if you wish to dwelve deeper.
"},{"location":"about/#goals","title":"Goals","text":"A summary of technical and feature differences is here.
We plan to add the features listed in the backlog.
"},{"location":"about/#non-goals","title":"Non-goals","text":"Support old operating systems (Windows 9x/Me/XP, OS/2, and Mac OS X 10.5) and limited CPU/memory hardware, which are constraints DOSBox continues to support.
Support the use of Windows 9x/Me in the emulator. Windows 9x/Me emulation is supported by projects such as QEMU and VirtualBox, although DOSBox forks like DOSBox-X and DOSBox Pure also support this. This may change if wanted by the DOSBox Staging community in general.
Pursue hardware accuracy when it impacts the above goals or detracts from the source material, although config options may be added in case of issues. If you need perfect emulation in terms of accuracy, you may look at PCem and its derivatives like 86Box and PCBox, which are examples of cycle-accurate emulators.
Be the fastest DOS emulator on x86 hardware. Linux users interested in emulation speed should look at dosemu2.
Act as a general-purpose DOS operating system. For that, there is FreeDOS.
DOSBox Staging is separate from and not supported by the SourceForge-hosted DOSBox project or its development team, the DOSBox Team.
We acknowledge and are thankful for the work shared by all DOSBox contributors.
"},{"location":"about/#team","title":"Team","text":"This project is maintained by the DOSBox Staging team.
"},{"location":"about/#license","title":"License","text":"Content on this site is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
DOSBox Staging is licensed under a GNU GPL version 2 or later.
"},{"location":"downloads/development-builds/","title":"Development builds","text":"Warning
These are unstable development snapshots intended for testing and showcasing new features; if you want to download a stable build, head on to the Linux, Windows, or macOS download pages.
Build artifacts are hosted on GitHub; you need to be logged in to download them.
Download link Build version Date\u00b9 Windows MSYS2 builds include 64-bit ZIP and Installer with both 64-bit MSYS2 (default) and 64-bit MSVC (optional).
\u00b2 Windows MSVC builds include 32-bit ZIP and 64-bit ZIP.
"},{"location":"downloads/development-builds/#installation-notes","title":"Installation notes","text":"Testing new features might require a manual reset of the configuration file. DOSBox Staging builds use a configuration file named dosbox-staging.conf located in:
~/.config/dosbox/ Windows C:\\Users\\USERNAME>\\AppData\\Local\\DOSBox\\ macOS ~/Library/Preferences/DOSBox/"},{"location":"downloads/development-builds/#linux","title":"Linux","text":"The tarball contains a dynamically-linked x86_64 build; you\u2019ll need additional dependencies installed via your package manager.
"},{"location":"downloads/development-builds/#fedora","title":"Fedora","text":"sudo dnf install SDL2 SDL2_image SDL2_net opusfile\nsudo apt install libsdl2-2.0-0 libsdl2-image-2.0-0 libsdl2-net-2.0-0 libopusfile0\nsudo pacman -S sdl2 sdl2_image sdl2_net opusfile\nWindows executables in snapshot packages are not signed, therefore Windows 10 might prevent the program from starting.
See this guide to learn how to deal with this.
"},{"location":"downloads/development-builds/#macos","title":"macOS","text":"macOS app bundles are not notarized; Apple Gatekeeper will try to prevent the program from running.
See this guide to learn how to deal with this.
"},{"location":"downloads/linux/","title":"Linux builds","text":""},{"location":"downloads/linux/#project-released-tarball","title":"Project-released tarball","text":"Download DOSBox Staging 0.80.1 (tar.xz) sha256: 12582a6496b1a276cd239e6b3d21ddfcd51fd8f9e40a1ebbc0a3800e0636190a
Check out the 0.80.1 release notes to learn about the changes and improvements introduced by this release.
Our pre-compiled builds run on most Linux distributions (x86_64 only for now). They depend on the following packages:
"},{"location":"downloads/linux/#install-dependencies-on-fedora","title":"Install dependencies on Fedora","text":"sudo dnf install SDL2 SDL2_image SDL2_net opusfile\nUbuntu 18.04 or newer, and Debian 9 or newer is required.
sudo apt install libsdl2-2.0-0 libsdl2-image-2.0-0 libsdl2-net-2.0-0 libopusfile0\nsudo pacman -S sdl2 sdl2_image sdl2_net opusfile\nDOSBox Staging is also packaged by external teams, as listed below. These packages may have variations in configuration file locations, filesystem or network restrictions, feature exclusions, and other differences compared to the project-released tarball.
To understand these potential differences, we recommend referring to the repository\u2019s documentation and, if uncertain, comparing against the project-released tarball.
The DOSBox Staging team does not track or document these differences. For issues specific to these packages, please contact the respective repository owners.
"},{"location":"downloads/linux/#containerised-packages","title":"Containerised packages","text":""},{"location":"downloads/linux/#fedora-repository-package","title":"Fedora repository package","text":"sudo dnf install dosbox-staging\nemerge games-emulation/dosbox-staging\nAvailable via Personal Package Archive:
sudo add-apt-repository ppa:feignint/dosbox-staging\nsudo apt-get update\nsudo apt install dosbox-staging\nAvailable via Arch User Repository.
"},{"location":"downloads/linux/#other-repository-packages","title":"Other repository packages","text":""},{"location":"downloads/linux/#steam","title":"Steam","text":"You can easily configure your DOS games on Steam to use DOSBox Staging via Boxtron (a community-developed Steam Play compatibility tool for DOS games).
Boxtron will automatically use dosbox if found in your path, or can be configured to use a specific binary by editing the file ~/.config/boxtron.conf and overriding dosbox.cmd:
cmd = ~/path-to-dosbox-staging/dosbox\nYou can easily configure your DOS games on Retropie to use DOSBox Staging via RetroPie-Setup (select Optional Packages \u2192 DOSBox Staging).
"},{"location":"downloads/linux/#hardware-requirements","title":"Hardware requirements","text":"For x86 CPUs the SSE 4.2 instruction set is required.
"},{"location":"downloads/linux/#development-snapshot-builds","title":"Development snapshot builds","text":"You can always see what\u2019s cooking on the main branch!
These snapshot builds might be slow or unstable as they are designed with developers and testers in mind.
"},{"location":"downloads/linux/#older-builds","title":"Older builds","text":"DOSBox Staging 0.80.0 (tar.xz) sha256: 3022bdd405dc1106007c3505e6a5d083de982d516c9bce499e2c4a02a697a1bd
DOSBox Staging 0.79.1 (tar.xz) sha256: aebf8619bb44934f18d0e219d50c4e2c03b179c37daa67a9b800e7bd3aefc262
DOSBox Staging 0.78.1 (tar.xz) sha256: 8bd2a247ca960f6059276db2b0331f853e16bc8a090722b15f567782542b5fba
DOSBox Staging 0.78.0 (tar.xz) sha256: 085e7cbe350546b3f25b0400c872a2766f9a49d16a5ca8d17a0a93aad6e37709
DOSBox Staging 0.77.1 (tar.xz) sha256: e2d475e4b1f80881ccafc4502b3884c096b51aa2fc2cfe89bb6c2b8ebfb7cc76
DOSBox Staging 0.76.0 (tar.xz) sha256: f8401bcd473d5b664eeb3a90e4dbb4bbf0cef5339adba867f361c00b7de9b2fe
DOSBox Staging 0.76.0 (tar.xz) sha256: b14de58ba0f5dd192398cda58fa439b15512f50d1c88b5ded6f300d4a9212852
DOSBox Staging 0.75.2 (tar.xz) sha256: 0325a1860aea95e8117aa49b041bfd628ab20531a3abc7b0a67aff4c47049465
DOSBox Staging 0.75.1 (tar.xz) sha256: aef22e5ddf93ff826fc2d48a4c8c0b4097d3455525b40be5b3fb443935929c70
DOSBox Staging 0.75.0 (tar.xz) sha256: a28d8ba0481722c8343b7532299c7b9bb9e491c6832d9d05dd4704939287f776
DOSBox Staging 0.75.0-rc1 (tar.xz) sha256: 594ba45280af240cb18b3882f7ffa71169a697eb362b7d7a76c8ccda2b940e84
Of course, you can always build DOSBox Staging straight from the source.
Send us patches if you improve something!
"},{"location":"downloads/macos/","title":"macOS builds","text":"Download DOSBox Staging 0.80.1 Universal Binary (dmg) sha256: 46a256645255e8345981ea357f1416b8ce4bc60a2aba9a86b5122d5075aa7fa9
This package is compatible with macOS 10.15 (Catalina) or newer and supports both Intel and M1 Macs.
Check out the 0.80.1 release notes to learn about the changes and improvements introduced by this release.
Important
macOS uses its Gatekeeper feature to prevent users from running externally-hosted 3rd party software, such as DOSBox Staging. See the section below to learn how to fix it.
"},{"location":"downloads/macos/#homebrew","title":"Homebrew","text":"The Homebrew package is compatible with macOS 10.14 (Mojave) or newer. Learn how to set up Homebrew here.
brew update\nbrew install dosbox-staging\nThe MacPorts package should build on systems as old as macOS 10.6 (Snow Leopard, circa 2009) or newer. Learn how to set up MacPorts here.
sudo port selfupdate\nsudo port install dosbox-staging\nIf you\u2019re running an OS not longer maintained by Apple, then support is on a best-effort basis (as the team runs supported configurations and may not be able to reproduce some issues).
"},{"location":"downloads/macos/#hardware-requirements","title":"Hardware requirements","text":"For x86 CPUs the SSE 4.2 instruction set is required. For Intel Mac models that don\u2019t support it, you can try using the partial SSE4.2 emulator MouSSE.
"},{"location":"downloads/macos/#development-snapshot-builds","title":"Development snapshot builds","text":"You can always see what\u2019s cooking on the main branch!
These snapshot builds might be slow or unstable as they are designed with developers and testers in mind.
"},{"location":"downloads/macos/#apple-gatekeeper","title":"Apple Gatekeeper","text":"You\u2019ll need to do the following when launching DOSBox Staging for the first time (you\u2019ll need to repeat these steps every time after having upgraded to a newer version):
Apple\u2019s Gatekeeper feature only permits the running of notarized software, one aspect of which involves developers making yearly payments to Apple.
As DOSBox Staging is a volunteer effort, we are not in a position to make such payments and therefore ask users to bypass Apple\u2019s Gatekeeper manually.
"},{"location":"downloads/macos/#older-builds","title":"Older builds","text":"DOSBox Staging 0.80.0 Universal binary (dmg) (macOS 10.15 or newer) sha256: 53f12aa63cf9d2a33a46149fb394947c6b12d5ab9b7ba41ee2d7eab1a990fa7a
DOSBox Staging 0.79.1 Universal binary (dmg) (macOS 10.15 or newer) sha256: 52547692be29949747bb8d3b59bf31dd22b4f49178316417cc8f1f468eeab387
DOSBox Staging 0.78.1 Universal binary (dmg) (macOS 10.15 or newer) sha256: b9ddff89e9fc283493580d5fc021b05021a13d90305ae44e2867499b22e359c9
DOSBox Staging 0.78.0 Universal binary (dmg) (macOS 10.15 or newer) sha256: 3997546560af542b7f3b55b1bc890ae4342144a72c21af9880449adf579db88b
DOSBox Staging 0.77.1 x86-64 (dmg) (macOS 10.15 or newer) sha256: 29964d79f0a85d593f8bafd30da854c726594c12474528f46758fc95c05f0c97
DOSBox Staging 0.77.1 ARM64 (dmg) (macOS 11 or newer) sha256: 74a1c84bdda0db25091f749ba7a2e5e93f7849baf130817ea1bc182039bd3698
DOSBox Staging 0.77.0 x86-64 (dmg) (macOS 10.15 or newer) sha256: 3ca859573814b2c50065825c02d8a04eb6d95605830ec3af21de0d64a2e32314
DOSBox Staging 0.77.0 ARM64-testing (dmg) (macOS 11 or newer) sha256: e2eecb52777d5ed836ba1f772fe669c89e94ea9b67777aced5fef5b51051ccaf
DOSBox Staging 0.76.0-3 (dmg) (macOS 10.15 or newer) sha256: f6048fa0e1a33a41f0018cb6d7139c4f7b4a60176bbe6a42f681aa8b5adcb73b
DOSBox Staging 0.76.0 (dmg) (macOS 10.15 or newer) sha256: c9fa7b0bf6410f430b47daeb15a470e0105a147b555d3fbf574514406c71f492
DOSBox Staging 0.75.2 (dmg) (macOS 10.15 or newer) sha256: 272f01aa8598ecf3229d48680aa6ce6e5b88ebd0645b1f92b899bc0159afcf11
DOSBox Staging 0.75.1 (dmg) (macOS 10.15 or newer) sha256: 2508a87c6aceee63da13e4c76159734e3c9ee4e76fb22a3a7c0d66021e71a4eb
DOSBox Staging 0.75.0 (dmg) (macOS 10.15 or newer) sha256: a0038c7401d239934d25517ca5e8e6006cc3f4cb7060f6ace56609d36bca12ef
DOSBox Staging 0.75.0-rc1 (dmg) (macOS 10.15 or newer) sha256: 8a5c12d1b6567d6e981acd76e30dec41a73a699963b714f4f1dcf0fc853fc9f6
Of course, you can always build DOSBox Staging straight from the source.
Send us patches if you improve something!
"},{"location":"downloads/windows/","title":"Windows builds","text":""},{"location":"downloads/windows/#windows-8x-or-newer","title":"Windows 8.x or newer","text":"Download DOSBox Staging 0.80.1 64-bit (Installer) sha256: 94b961f397f3b70a13daf3b573857b5262515e75d490bfc19f019479fe1694f8
Download DOSBox Staging 0.80.1 64-bit (zip) sha256: e7ab98013b55f6fd6db1f529574b8f2905d374225f532ce0905666281cbe32af
Download DOSBox Staging 0.80.1 32-bit (zip) sha256: 63a8c5b084231364961f7c8b6415e44622c5ab9822e49839c2aca1bddd3a9459
Check out the 0.80.1 release notes to learn about the changes and improvements introduced by this release.
Important
If Windows 8.x or Windows 10 prevents you from running DOSBox Staging via Microsoft Defender SmartScreen, see the section below.
"},{"location":"downloads/windows/#windows-7","title":"Windows 7","text":"For 64-bit Windows 7, use the 64-bit MSVC build. It can be optionally selected in the installer and is also available as a portable ZIP archive.
For 32-bit Windows 7, use the 32-bit MSVC build portable ZIP archive
"},{"location":"downloads/windows/#windows-vista","title":"Windows Vista","text":"The official distribution packages only support Windows Vista up to version 0.78.1.
More recent releases can be built from the source by excluding FluidSynth and Slirp support. Please see the Windows MSYS2 build instructions for further details.
"},{"location":"downloads/windows/#hardware-requirements","title":"Hardware requirements","text":"SSE 4.2 instruction set is required for version 0.75.1 or newer.
"},{"location":"downloads/windows/#development-snapshot-builds","title":"Development snapshot builds","text":"You can always see what\u2019s cooking on the main branch!
These snapshot builds might be slow or unstable as they are designed with developers and testers in mind.
"},{"location":"downloads/windows/#microsoft-defender-smartscreen","title":"Microsoft Defender SmartScreen","text":"You\u2019ll need to do the following when launching DOSBox Staging for the first time (you\u2019ll need to repeat these steps every time after having upgraded to a newer version).
"},{"location":"downloads/windows/#method-1","title":"Method 1","text":"Start the application, then click on More info in the appearing dialog. Click the Run anyway button in the second dialog.
"},{"location":"downloads/windows/#method-2","title":"Method 2","text":"In your installation folder, right-click on the dosbox.exe, select Properties, tick Unblock in the appearing dialog, then press Ok.
Starting in Windows 8, Microsoft Defender SmartScreen\u2019s pop-up encumbers the execution of newly-developed applications. To prevent this, developers are expected to pay Microsoft\u2019s EV certification vendors a yearly fee and put the software on Windows Store.
As DOSBox Staging is a volunteer effort, we are not in a position to make such payments. We, therefore, ask users to manually unblock DOSBox Staging and be patient while Microsoft\u2019s Application Reputation Scheme eventually whitelists DOSBox Staging.
"},{"location":"downloads/windows/#custom-install-parameters","title":"Custom install parameters","text":"The installer is built with Inno Setup. For the available command-line install parameters, please see Inno\u2019s documentation page.
"},{"location":"downloads/windows/#older-builds","title":"Older builds","text":"DOSBox Staging 0.80.0 64-bit (Installer) (Windows 7 or newer) sha256: 84445c869e58f6b4591484f6178c7b5b3c8f284bf9460e9afc4502ba842ab039
DOSBox Staging 0.80.0 64-bit (zip) (Windows 7 or newer) sha256: 075be379ed4475615e0e86953eb21f024c74b4cafd6914e9cf5ef40e3d9e26cd
DOSBox Staging 0.79.1 64-bit (installer) (Windows 7 or newer) sha256: 0045ac995ada0af955681983ae86c969a05030c25173618f8b1547a267046a27
DOSBox Staging 0.79.1 64-bit (zip) (Windows 7 or newer) sha256: 8c7045dfea6dc20bb985cff516d2faee51d2ecaf054db60632857b6941d3d648
DOSBox Staging 0.78.1 64-bit (zip) (Windows Vista or newer) sha256: 3c2f408125351154a37e93de8a4bd05d0c722bbf53e1f583909e4ca6c3eb9204
DOSBox Staging with built-in debugger 0.78.1 64-bit (zip) (Windows Vista or newer) sha256: b99f3c354f831ed2b0ed04d215170f696b6fc18285b0c7192c0abab62c41bbc8
DOSBox Staging 0.78.0 64-bit (zip) (Windows Vista or newer) sha256: f13cba664259fdb0db5e32826e13dcded4270557963f6e823a4731129f23a8a3
DOSBox Staging 0.78.0 32-bit (zip) (Windows Vista or newer) sha256: 0ca9201cdf3f3a1576b97b0de0e87280b75c633976f0b179ba33a68d44f5ba56
DOSBox Staging 0.77.1 64-bit (zip) (Windows Vista or newer) sha256: 11ba992ece6d3e4ef2046fcdb6d842da364b69720a921d61fdcc793eb52e7051
DOSBox Staging 0.77.1 32-bit (zip) (Windows Vista or newer) sha256: a34883101486ce2af071a29c6390f2038889fc519e042101284f2a6999d9f0ef
DOSBox Staging 0.77.0 64-bit (zip) (Windows Vista or newer) sha256: cacdac418642fd8c7faf1e5955110c35d0c207392ae20835707fd2a1e1114b82
DOSBox Staging 0.77.0 32-bit (zip) (Windows Vista or newer) sha256: f718d07bab69e3e1be0b28207039cea2746c7e45b8ba7a19b625011f477e609a
DOSBox Staging 0.76.0 32-bit (zip) (Windows Vista or newer) sha256: 646d2f3fa8189e411589fedcb8148a295361693a6ce95d08e06f4a70e5a36b16
DOSBox Staging 0.75.2 64-bit (zip) (Windows Vista or newer) sha256: 09f0ca911813a64b8814880eb6e49ad4dcdac9a5bb9263c4887ad82b71fad292
DOSBox Staging 0.75.2 32-bit (zip) (Windows Vista or newer) sha256: 51dc171ff52ea395c6a22f09ebb98a93974a95c701ca81008368c22a66deced2
DOSBox Staging 0.75.1 64-bit (zip) (Windows Vista or newer) sha256: 80c60c4377ff2882649f113b3cb3bcd407c17acaac344c49fa1fc4229813f012
DOSBox Staging 0.75.1 32-bit (zip) (Windows Vista or newer) sha256: 843c742a348f575862e152e02cf174be0ea1c52bdb6e4bffd65f34af88b566b7
DOSBox Staging 0.75.0 32-bit (zip) (Windows Vista or newer, supports CPUs without SSE4.2) sha256: 69046adcef2ef9920fbba8d40fc9e51f3dd144ba4549787e1816cf1c2ae87d71
DOSBox Staging 0.75.0-rc1 32-bit (zip) (Windows Vista or newer, supports CPUs without SSE4.2) sha256: 738d2ae2101384f2eeaf1895de64cf1b4c76eaf7873de7e15b7f52145dfed7e7
Of course, you can always build DOSBox Staging straight from the source.
Send us patches if you improve something!
"},{"location":"downloads/release-notes/0.75.0-rc1/","title":"0.75.0-RC1 release notes","text":"Release date: 2020-04-22
"},{"location":"downloads/release-notes/0.75.0-rc1/#installation-instructions","title":"Installation instructions","text":"This release is significant for several reasons:
It\u2019s our first stable release. From this point forward, the 0.75.x series will only contain bugfixes.
It kicks off the 0.76 development cycle, for which a number of features are already lined up.
The new project homepage makes the downloads publicly accessible, without the need for a GitHub account.
There\u2019s no human-readable changelog just yet\u2014there are ~1500 commits to comb through. Hopefully, within a couple of days, we\u2019ll be able to write a nice summary with a description of new features, improvements, and bugfixes.
In the meantime, we invite everyone to start testing RC1 builds; there are some rough edges for sure\u2014if you find any bugs, please report them in our bugtracker. You can also ask questions on the #dosbox\u2011staging channel in Luxtorpeda Discord Server.
This release includes all upstream changes until SVN r4336, and 857 Git commits on top of that.
Have fun!
The DOSBox Staging team
"},{"location":"downloads/release-notes/0.75.0/","title":"0.75.0 release notes","text":"Release date: 2020-05-06
"},{"location":"downloads/release-notes/0.75.0/#summary","title":"Summary","text":"This document contains the release notes for DOSBox Staging 0.75. It describes recently added, changed, or deleted features of DOSBox Staging.
All users are encouraged to consult the New features in detail and Known issues sections before using DOSBox Staging, as these describe important interface changes as well as information discovered late in the release cycle or after the release.
"},{"location":"downloads/release-notes/0.75.0/#installation-instructions","title":"Installation instructions","text":"The DOSBox Staging project was created September 15, 2019 as a soft-fork of the SourceForge-based DOSBox project, which is a separate project having its own schedule and development priorities.
"},{"location":"downloads/release-notes/0.75.0/#new-features-in-detail","title":"New features in detail","text":"New features originating from our upstream (DOSBox) are marked with SVN.
"},{"location":"downloads/release-notes/0.75.0/#upgrade-to-sdl-20","title":"Upgrade to SDL 2.0","text":"SDL 2.0 is a major update to the SDL 1.2 codebase, which has been unmaintained since 2013. SDL 2.0 supports more input devices; more output interfaces such as Wayland, and OpenGLES 1 and 2; low-latency audio using OpenSL ES; and improves cross-platform consistency.
The migration to SDL 2.0:
One example includes the new texture output mode, which uses SDL\u2019s 2D hardware-accelerated API rendering to a platform-specific backend.
For example, Windows users can test:
[sdl]\noutput = texture\ntexture_renderer = direct3d11\nmacOS users can try Metal:
[sdl]\noutput = texture\ntexture_renderer = metal\nAnd everyone can use OpenGL as texture backend:
[sdl]\noutput = texture\ntexture_renderer = opengl\nOr just use texture_renderer = auto to let SDL pick the backend appropriate for your operating system.
FLAC, Opus, and MP3 (as well as MP2 and MP1) encoded audio can be imgmounted as CD-DA tracks in DOSBox Staging, in addition to the usual WAV and Vorbis tracks supported by DOSBox. WAV support has been expanded to include Sony\u2019s Wave64 format.
DOSBox Staging also supports tracks having sample resolutions of 24 and 16-bit; sampling rates of 96, 88.2, 48, 44.1, 22.05, and 11.025 kHz; and stereo or mono channel counts (to the extent each codec supports these variations). You can mix-and-match these properties and track types to best suit each track\u2019s content.
The following sample CUE file depicts the use of every codec supported by DOSBox Staging:
FILE \"data.iso\" BINARY\n TRACK 01 MODE1/2048\n INDEX 01 00:00:00\n\nFILE \"track02.opus\" OPUS\n TRACK 02 AUDIO\n PREGAP 00:02:00\n INDEX 01 00:00:00\n\nFILE \"track03.flac\" FLAC\n TRACK 03 AUDIO\n INDEX 01 00:00:00\n\nFILE \"track04.mp3\" MP3\n TRACK 04 AUDIO\n INDEX 01 00:00:00\n\nFILE \"track05.w64\" W64\n TRACK 05 AUDIO\n INDEX 01 00:00:00\n\nFILE \"track06.ogg\" OGG\n TRACK 06 AUDIO\n INDEX 01 00:00:00\n\nFILE \"track07.wav\" WAV\n TRACK 07 AUDIO\n INDEX 01 00:00:00\nFor devices with sufficient storage, we recommend ripping your CD-ROM audio to (lossless) FLAC tracks and adding seek-points using:
flac -8 --output-name=trackXY.flac trackXY.wav\nmetaflac --add-seekpoint=1s trackXY.flac\nFLAC typically achieves between 50% and 35% compression while producing binary-identical output versus WAV files.
For limited-storage devices such as ARM single-board computers, Opus provides state-of-the-art lossy compression that exceeds all other formats, including Apple\u2019s AAC and AAC High-Efficiency formats. Opus allows even further space savings over MP3 or Vorbis track while matching or exceeding them in output quality.
For example, CD-DA tracks consisting of monaural speech can be encoded with:
opusenc --speech --bitrate 24 --downmix-mono trackXY.wav trackXY.opus\nWhen applied to Sierra\u2019s Jones in the Fast Lane audio track, Opus compresses it from 373 MB down to 6.4 MB (98.2% savings in disk space) with no discernible loss in quality.
For CD-DA tracks consisting of sound effects and relatively simple music, Opus does fine with a bitrate between 54 and 70, whereas more complex musical tracks might need a bitrate of up to 84. Experiment and find your sweet spot!
opusenc --bitrate 70 trackXY.wav trackXY.opus\nIf your CD-DA tracks are encoded at 48 kHz (which is Opus\u2019s default internal rate), then feel free to configure DOSBox Staging\u2019s mixer rate to match, which ensures your CD-DA will not be resampled through your audio chain; as your sound card, USB speakers, and HDMI interface all (likely) operate at a native rate of 48 kHz.
[mixer]\nrate = 48000\nPixel-perfect output scales the image by the largest integer multiplier that fits within your monitor\u2019s native resolution. For example, given a 1920\u00d71080 monitor and a 320\u00d7200 game requiring aspect-correction, each of its pixels would be scaled by 4\u00d75 to produce a 1280\u00d71000 image. This preserves the original artwork without any edge blurring.
To enable pixel-perfect output, apply the following settings to the indicated sections of your DOSBox Staging configuration file, as follows:
[sdl]\nfullscreen = true\noutput = texturepp\n[render]\nscaler = none\nglshader = none\nPixel-perfect looks like this on a 1080p screen:
Heroes of Might and Magic II (1996) \u2014 640\u00d7480 with a pixel aspect ratio (PAR) of 1:1, upscaled to 2\u00d72
Wolfenstein 3D (1992) \u2014 320\u00d7200 with a PAR of 1:1.2 (non-square pixels), upscaled to 4\u00d75 with a PAR of 1:1.25
"},{"location":"downloads/release-notes/0.75.0/#resizable-window","title":"Resizable window","text":"Being able to click and drag to resize an application\u2019s window is not a revolutionary feature by any measure; however it\u2019s a welcome addition for DOSBox Staging!
Star Wars: Dark Forces (1995) \u2014 intro playing while the DOSBox window is being resized vigorously
This feature is a work-in-progress: it\u2019s available on Linux by default, and can be enabled for testing on Windows and macOS by setting the following (but note that it does not yet work correctly on these systems):
[sdl]\nwindowresolution = resizable\nOn all systems, the resizable window is only available for output = opengl and glshader = sharp. Support will be expanded to more outputs and shaders in the future versions.
AUTOTYPE is a command-line tool provided by DOSBox Staging that performs scripted keyboard entry into the running DOS program or game.
It can be used to reliably skip intros, provide input to answer initial startup or configuration questions, or conduct a simple demo.
Simply run the command to learn more:
Z:> autotype\nSome games that benefit from AUTOTYPE on startup are listed on the wiki page.
The following default configuration settings were changed to improve the out-of-the-box experience for the majority of games running on modern hardware.
The default video settings now use SDL\u2019s OpenGL rendering backend, apply a 4:3 aspect ratio correction, and scale the image using the sharp OpenGL shader to provide relatively sharp pixels when in fullscreen mode.
Battle Chess (1989) \u2014 at 1080p using the default settings
"},{"location":"downloads/release-notes/0.75.0/#expand-mouse-control-methods","title":"Expand mouse control methods","text":"The prior \u201cautolocking\u201d mouse option used by DOSBox has been renamed in DOSBox Staging to capture_mouse, which is configured using two values defining how the mouse behaves.
The first value defines how the mouse is controlled:
onclick: the mouse will be captured with a click inside the windowonstart: the mouse is captured immediately on start (similar to real DOS)seamless: the mouse will move seamlessly in and out of the window and cannot be capturednomouse: the mouse is disabled and hidden without any input sent to the gameThe second value defines how middle-clicks are handled:
middlegame: middle-clicks are sent to the game (not used to uncapture the mouse)middlerelease: middle-click will uncapture the mouse when windowed (not sent to the game)For example:
[sdl]\ncapture_mouse = onclick middlerelease\nThis will capture the mouse on the first click inside DOSBox Staging\u2019s window, and a middle-click will release the mouse. Note that the prior method to release the mouse still works (pressing Ctrl+F10).
Note
DOSBox Staging defaults to seamless mouse capture both to simplify multi-tasking in windowed-mode and provide a frustration-free experience for new users. However, some games and Windows 3.1 make their own adjustments to the mouse position and will cause an offset-effect. In these cases, we recommend switching to fullscreen (Alt+Enter) or configuring the mouse to capture onclick or onstart.
Important
These options do not affect the mouse behavior in fullscreen (Alt+Enter), as the mouse is always captured.
"},{"location":"downloads/release-notes/0.75.0/#nuked-opl-v18","title":"Nuked OPL v1.8","text":"The cycle-accurate Nuked OPL3 emulator is now used by default; this change improves AdLib and Sound Blaster FM music emulation accuracy.
This improved accuracy comes at the cost of a slightly higher CPU use, which is insignificant for the vast majority of users on typical desktop or laptop hardware.
However, those using DOSBox Staging on old or CPU-limited hardware (capable of 30,000 dosbox \u201ccycles\u201d or less, such as the Raspberry Pi 3) will be served best using the fast OPL emulator (see the oplemu documentation provided in the configuration file).
The built-in CONFIG shell command is a bit old, but a little-known feature allows users to reconfigure DOSBox Staging at runtime. This is a nifty way to change configuration using batch scripts based on user input.
You can now change key bindings at runtime by loading them from a file:
Z:\\> config -set \"sdl mapperfile=<path-to-file>\"\nDOSBox added a number of features to the CONFIG command. To list them all, run:
Z:\\> config /?\nDOSBox Staging\u2019s configuration file location has been updated to comply wit the XDG Base Directory Specification. This means DOSBox Staging will no longer create configuration directories directly in your home directory.
Configuration files are now located in:
~/.config/dosbox/\nUsers can customize the parent (.config/) location by setting the XDG_CONFIG_HOME environment variable, according to the XDG Specification.
The path was slightly changed to avoid spaces in the default configuration filename and to group all configuration files in a single directory:
~/Library/Preferences/DOSBox/\nNo changes; the configuration files are created in:
C:\\Users\\<username>\\AppData\\Local\\DOSBox\\\nYou can map fake phone numbers to Internet addresses which is useful for programs where limitations on phone number input field are too strict. Create a text file with the name specified in phonebookfile entry in the [serial] section in the DOSBox configuration file and add phone-address pairs per line, for example:
5551234 towel.blinkenlights.nl:23\nNow you can dial the specified phone number and the emulated modem will connect to the address it\u2019s mapped to. Note that phone book does not allow any characters in the phone number that are ignored or denied by a real Hayes compatible modem.
"},{"location":"downloads/release-notes/0.75.0/#64-bit-dynamic-recompilation-svn","title":"64-bit dynamic recompilation (SVN)","text":"DOSBox has had dynamic recompilation support for a long time, but it was limited to 32-bit builds. Support for 64-bit dynarec improves CPU emulation speed and quality across the board\u2014this is especially visible to Linux and macOS users1.
Stargunner (1996, freeware) \u2014 running on Linux x86_64 via Boxtron
Before 64-bit dynarec, this game had serious emulation problems resulting in fluctuating emulation speed (sometimes too fast, sometimes too slow - regardless of cycles settings). This game was designed to run with constant 70 FPS and now it runs with constant 70 FPS.
"},{"location":"downloads/release-notes/0.75.0/#cga-improvements","title":"CGA improvements","text":"Maniac Mansion (1988) \u2014 with forced CGA mode: top-left: CGA, default palette; top-right: CGA mono, green tint; bottom-left: CGA composite, early model, default hue; bottom-right: CGA composite, late model, default hue.
"},{"location":"downloads/release-notes/0.75.0/#cga-monochrome-mode","title":"CGA monochrome mode","text":"Many CGA games from the 80\u2019s were designed to support monochromatic cathode-ray tube (CRT) monitors that used either an amber, green, or grayscale-shaded phosphor coating. As such, some games look much better when rendered using a similar monochrome palette. This mode is designed to emulate such displays.
Use machine = cga_mono to turn on the feature. You can switch between green, amber, white, and paper-white palettes at runtime by pressing F11.
Technical artifacts caused by the composite video format were cleverly used by game developers to generate extra colors (versus non-composite CGA) by manipulating pixel positions on the screen. For example, adjacent pixels would be partly \u201caveraged\u201d (through horizontal overlap), producing interposed solid colors or generating rudimentary transparency effects.
Composite mode was added to DOSBox\u2019s CGA emulator in 2012, but was never back-ported to any of its stable releases. Most users are familiar this mode as its commonly included in other DOSBox forks.
Once enabled, you can switch between color and composite modes, early and late CGA models, and adjust the hue at runtime.
Note
The default keybinding for manipulating CGA modes conflict with other essential bindings; it\u2019s advisable to change them if you plan to use this feature. The default key for turning on composite mode is F12.
"},{"location":"downloads/release-notes/0.75.0/#glsl-shader-support-svn","title":"GLSL shader support (SVN)","text":"Shaders written in OpenGL Shading Language (GLSL) offload the task of processing the emulated game\u2019s output to your GPU hardware.
This allows the image to be altered in many ways, such as emulating the analog artifacts (scanlines, shadow masks, and phosphor glow) present in circa-1980s and 90s CRT monitor on modern 1080p and greater LCD panels.
You can can select the shader to use by setting the glshader config param:
[render]\nglshader = sharp\nIt\u2019s also possible to provide your shader implementations by placing .glsl files in the configuration directory:
~/.config/dosbox/glshaders/ macOS ~/Library/Preferences/DOSBox/glshaders/ Windows C:\\Users\\<USERNAME>\\AppData\\Local\\DOSBox\\glshaders\\ E.g. if you put a shader file called test.glsl in your config directory, you can select it as follows:
glshader = test.glsl\nNote
When using a GLSL shader, we recommend setting the scaler type to none to ensure image post-processing is performed exclusively by the shader (and not a mix of the two).
Star Wars\u2122 \u2014 X-Wing: Collector\u2019s CD-ROM Edition (1994) Using CRT-Lottes shader on a 1080p screen; click on the image to enlarge it to see the fine details. This shader is not bundled with DOSBox Staging (yet); you can download it from here.
"},{"location":"downloads/release-notes/0.75.0/#date-and-time-commands-svn","title":"DATE and TIME commands (SVN)","text":"The traditional DATE and TIME DOS commands have been added to DOSBox. This allows the user to change the date seen by the software running inside the emulated environment:
Z:\\> date\nCurrent date: Fri 05/01/2020\nType 'date MM-DD-YYYY' to change.\n\nZ:\\> time\nCurrent time: 11:08:23,34\nNote that while the date can be changed, the time cannot.
This feature is useful for running old batch scripts and bypassing date checks in some old software.
"},{"location":"downloads/release-notes/0.75.0/#mount-overlay-support","title":"Mount overlay support","text":"This feature allows the user to redirect new and changed files to a different location transparently. The files in the overlay and normal drives are merged at startup and kept up to date when the game writes to the disk.
This feature is useful for redirecting save files or configuration files to a different location (e.g. for backup or cloud saves).
Example usage:
Z:\\> mount C real\nDrive C is mounted as local directory real/\n\nZ:\\> mount C backup -t overlay\nOverlay backup/ on drive C mounted.\n\nZ:\\> C:\nC:\\> echo foo > test.txt\n\nC:\\> type TEST.TXT\nfoo\nFile TEST.TXT is written to the directory backup, and not to real.
ddraw) output. Use output = texture, texture_renderer = directx11 instead.overlay output. Use any other output.windowresolution = X%).Migrated the DOSBox source from Apache\u2019s Subversion (SVN) software versioning and revision control system to the Git distributed version-control system using GitHub, while preserving all publicly available project history.
svn/<name>).svn/<tag-name>).Ongoing upstream SVN development work is being imported in a timely manner to the Git branch named svn/trunk.
C++11 language constructs are now allowed.
Implemented a Continuous Integration (CI) system that builds on every code push to provide immediate feedback to developers regarding build-success and warning-counts on:
Windows x86_64 using GCC 32 and 64-bit, Clang 32 and 64-bit, and VisualStudio 64-bit compilers
macOS x86_64 using GCC and Clang compilers
Linux x86_64, ARMv6, ARMv7, IBM LinuxONE, and IBM POWER8 platforms using various versions of GCC and Clang
Added static analysis checks performed by LLVM\u2019s Clang, Synopsys\u2019s Coverity, and VIVA64\u2019s Program Verification Systems (PVS) Studio.
Added dynamic analysis checks performed by Clang\u2019s undefined-behavior (UB) sanitizer and GCC\u2019s UB and address sanitizers.
The CI system includes gated checks that allow maintainers to focus on code functionality and correctness. These automated checks guarantee that new code:
Notable progress has been made in reducing the number of warnings and analysis issues flagged by these tools.
Windows: the build-system was adjusted to allow easy compilation, without manual download or patching of dependencies. We use vcpkg to manage dependencies. The solution file was fixed to work with Visual Studio 2019.
Linux and macOS: implemented a number of small build-system improvements.
Automated the compilation of release-style builds against the latest main and feature branches. These not only save time for testers wanting to verify new features and bugfixes, but also ensures they\u2019re running builds compiled using would-be release settings.
macOS: release binaries are compiled with optimizations supporting Intel Nehalem-based instructions (and newer), as this matches the minimum processor requirements set by macOS Catalina.
Release packages are scanned using up-to-date Antivirus software: ClamAV for Linux and macOS, and Windows Defender for Windows.
The project has published a Code of Conduct along with clear Contributor Guidelines.
windowresolution = resizable when leaving fullscreen.Submit new issues or learn more about existing ones using our bug-tracker.
"},{"location":"downloads/release-notes/0.75.0/#contributors","title":"Contributors","text":"During the DOSBox Staging 0.75 development period:
Library or patch authors, upstream SVN developers, etc.
You can read detailed changelog via Git, e.g. using the following command:
git shortlog ^v0.75.0-pre v0.75.0 --no-merges\nThe following lists those merges performed by maintainers either on behalf of, or making use of, patches or libraries authored by community members (in alphabetic order).
kcgen
Patryk Obara
Peter Veenstra
Changes merged-in to SVN
Add several builtin shaders that mimic the scalers and some extra (jmarsh)
Fix xcmpchg in dyn_x86 core. Allows Quickview to work in that core (jmarsh)
Additional refinements and speed ups (jmarsh)
Switch to a different way to calculate the table offsets (jmarsh)
Fix boundary checks for word/dword memory access. Speeds up dynamic 32 bit core a bit (jmarsh)
Add 64-bit support to dynamic_x86 core from vogons topic 67673 (jmarsh)
Michael Zijlstra
We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
DOSBox Staging 0.75.0 stable Windows build is still 32-bit; Linux and macOS builds are 64-bits.\u00a0\u21a9
Release date: 2020-08-19
"},{"location":"downloads/release-notes/0.75.1/#summary","title":"Summary","text":"This is a small bugfix release from 0.75.x stable branch\u2014it includes a few changes and bugfixes backported from upcoming 0.76.x version.
"},{"location":"downloads/release-notes/0.75.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
Brave souls interested in the latest features can test our work-in-progress 0.76.x\u00a0alpha builds . Please report any issues in our bugtracker.
Also, check out our growing Wiki.
"},{"location":"downloads/release-notes/0.75.1/#new-features-in-detail","title":"New features in detail","text":""},{"location":"downloads/release-notes/0.75.1/#add-support-for-binding-more-controller-axes","title":"Add support for binding more controller axes","text":"Users can now comfortably use both sticks, as commonly found on modern controllers (like DualShock or any Xbox controller). Previously, only one stick could be mapped.
This change does not make old games \u201cmagically\u201d recognize all features of modern controllers. You need to map additional controller events to emulated keyboard, mouse, or joystick events using DOSBox\u2019s keymapper (Ctrl+F1).
This was a highly-requested community patches that wasn\u2019t accepted by the upstream DOSBox project. We\u2019ve included the 10-axes per controller version of the patch in DOSBox Staging.
"},{"location":"downloads/release-notes/0.75.1/#provide-windows-x64-builds","title":"Provide Windows x64 builds","text":"Windows 64-bit builds are now provided alongside 32-bit builds. Additional performance optimizations (WPO) are enabled for both builds. Linux and macOS builds have been similarly optimized using LTO since the 0.75.0 release.
Both Windows builds now require SSE 4.2 instruction set, which is now on par with the Linux and macOS builds that have required SSE 4.2 support since the 0.75.0 release.
Steam Hardware survey indicates that 97.45% users have CPUs supporting SSE 4.2, so your CPU is very likely good enough
"},{"location":"downloads/release-notes/0.75.1/#log-base-address-of-emulated-memory","title":"Log base address of emulated memory","text":"This change was created per request from users of Cheat Engine, but it might be useful for other memory scanners/debuggers as well.
Base memory address of DOS\u2019s emulated memory region is now logged to the console:
MEMORY: Base address: 0x5c758e0\nMEMORY: Using 4096 DOS memory pages (16 MiB)\nUsers previously had to debug the dosbox binary to discover the base address; an easy but tedious process.
"},{"location":"downloads/release-notes/0.75.1/#bugfixes","title":"Bugfixes","text":"Correct CD audio playback for games using single BIN/CUE; fixes a regression in The Secret of Monkey Island. (#385)
Fix build issue for Windows x64 target after VS2019 update. (#389)
Fix a crash happening after bindings for 2 controllers were added and then one controller is disconnected. (#405)
Fix a crash on exit after removing controller actions bound to keyboard events. (#405)
Prevent crash on SDL2 re-creating OpenGL window. (#509)
Provide detailed help for DIR /? command. (#506)
Fix pixel-perfect mode not respecting aspect = false setting. (#544)
You can read detailed changelog via Git, e.g. using the following command:
git shortlog ^v0.75.0 v0.75.1\nWe are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"downloads/release-notes/0.75.2/","title":"0.75.2 release notes","text":"Release date: 2020-10-26
"},{"location":"downloads/release-notes/0.75.2/#summary","title":"Summary","text":"This is a maintenance release from the 0.75.x stable branch.
"},{"location":"downloads/release-notes/0.75.2/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
When emulating monochrome displays (via machine = hercules or machine = cga_mono), the default colour palette can now be set to either white, paperwhite, green, or amber in the configuration file, as follows:
[render]\nmonochrome_palette = amber\nSee: #607
"},{"location":"downloads/release-notes/0.75.2/#raw-mouse-input","title":"Raw mouse input","text":"You can enable this option to bypass the operating system\u2019s mouse acceleration and sensitivity settings. This works in fullscreen or when the mouse is captured in windowed mode.
The option can be set in the [sdl] section of the configuration file:
[sdl]\nraw_mouse_input = true\nThe feature is disabled by default, but some games (e.g. FPS titles, like DOOM or Dark Forces) work better with raw input enabled (especially when used with modern, very sensitive gaming mice).
See: #636
"},{"location":"downloads/release-notes/0.75.2/#bugfixes","title":"Bugfixes","text":"Bundle C++ runtime libraries with Windows builds for users on Windows 7, 8.x, and those who disabled Windows 10 update mechanism. (#675)
Reimplement CLS command to prevent text mode reset. (#639)
Fix whitespace handling in modem ATD command. (#652)
Fix boot failure when using HDD image. (#522)
This release includes numerous fixes affecting our build system and other changes relevant for packaging (contributed by Gentoo packagers, and people preparing Debian, Fedora, and Flatpak packages)\u2014prompt upgrade is recommended.
If you\u2019re packaging DOSBox Staging for your OS, we have a few tips:
We strongly suggest keeping our default binary name: dosbox. DOSBox\u00a0Staging is a drop-in replacement for older DOSBox versions\u2014some existing and popular programs, such as Wine and GUI frontends, depend on the dosbox binary name. It\u2019s also the default name of our man page and appears in the documentation.
You don\u2019t need to generate your own desktop entry, appstream metadata (metainfo.xml), nor package description: please see the relevant files in the contrib/linux/ directory.
We provide desktop icons in scalable or raster formats (optimized for small sizes). Find them in the contrib/icons/ directory.
During the configuration step, remember to add -DNDEBUG to preprocessor flags (it\u2019s important!), as well as using -O3 in both C and C++ compiler flags, for example:
./configure CPPFLAGS=\"-DNDEBUG\" CFLAGS=\"-O3\" CXXFLAGS=\"-O3\"\nOur testing indicates that GCC generates faster binaries than Clang, but use whatever compiler is more appropriate for your OS.
The license is \u201cGNU GPL version 2.0 or later\u201d (SPDX: GPL-2.0-or-later). GitHub does not show \u201cor later\u201d, but our packages should show the proper license info.
To all our package maintainers: thank you!
"},{"location":"downloads/release-notes/0.75.2/#contributors","title":"Contributors","text":""},{"location":"downloads/release-notes/0.75.2/#maintainers","title":"Maintainers","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"downloads/release-notes/0.76.0/","title":"0.76.0 release notes","text":"Release date: 2020-12-03
"},{"location":"downloads/release-notes/0.76.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
This release introduces significant enhancements to the quality of audio emulation (GUS, built-in MIDI, PC speaker), improved support for PowerPC and POWER8 architectures, and a healthy mix of usability, documentation, code quality improvements.
Enjoy!
"},{"location":"downloads/release-notes/0.76.0/#new-features-in-detail","title":"New features in detail","text":""},{"location":"downloads/release-notes/0.76.0/#gravis-ultrasound-emulation-improvements","title":"Gravis UltraSound emulation improvements","text":"Sample from Rise of the Triad (1995). For other comparisons see link.
Using headphones is highly recommended!
GUS emulator Sample (FLAC) Old implementation Your browser does not support theaudio element. New implementation (with improvements) Your browser does not support the audio element. Several changes have been made to the GUS emulation resulting in (sometimes) audible differences, as follows:
Output volume is now typically on-par with other audio devices.
Panning of voices is now performed using constant-power, as described in the Gravis\u2019 SDK documentation. Constant-power panning was originally researched by the British Broadcasting Corporation (BBC) and found to produce the most realistic perception of voice placement on a radial axis from the listener.
When quitting DOSBox Staging, information about the game\u2019s GUS audio stream will be provided, such as the breakdown of 8-bit versus 16-bit samples. A potential suggestion to adjust the game\u2019s GUS mixer level, either upward or downward may also be provided, which you could paste into your game\u2019s startup batch file or [autoexec] section.
We recommend using GUS emulation for the handful of DOS games that natively support the GUS\u2019s multi-voice feature. For a list of these games, see: GUS Native games.
For more details about DOSBox Staging\u2019s GUS support and enhancements, see: GUS\u00a0Enhancements.
For information about constant-power panning, see pages 7 and 8 of the BBC R&D White Paper.
"},{"location":"downloads/release-notes/0.76.0/#built-in-glsl-shaders","title":"Built-in GLSL shaders","text":"Two high-quality shaders that emulate the visual look of an analog CRT monitor are now included:
glshader = crt-easymode-flat: for DOS games using resolutions 640\u00d7400 or higher.glshader = crt-fakelottes-flat: for DOS games using smaller resolutions (e.g. 320\u00d7200).Jazz Jackrabbit (Holiday Hare 1995 Edition) \u2014 showcasing crt-fakelottes-flat
Jazz Jackrabbit (Holiday Hare 1995 Edition) \u2014 showcasing crt-fakelottes-flat (zoomed-in view)
FluidSynth 2.x, a powerful and accurate MIDI synthesizer, has been integrated into DOSBox to directly support MIDI playback. This means you no longer need to use an external MIDI synthesizer (but it\u2019s still possible, of course).
Configure your game to use General MIDI (GM) output on port 330 and update your DOSBOX Staging config as follows to start using it:
[midi]\nmididevice = fluidsynth\nmpu401 = intelligent\n[fluidsynth]\nsoundfont = my-favourite-soundfont.sf2\nDOSBox will look for soundfont files in the soundfonts directory within your configuration directory and in additional platform-specific directories (e.g. /usr/share/soundfonts/ on Linux).
You can also use absolute paths or paths relative to the current working directory (for bundling .sf2 files in game directories).
Some SoundFonts can be \u201clouder\u201d than others, such as Timbres of Heaven. You can provide an optional volume-scaling percentage after the SF2 filename, such as:
soundfont = timbres_of_heaven.sf2 20\nThis will reduce the SoundFont\u2019s volume to 20%.
Most games that play MIDI music provide an in-game volume adjustment, but some games may not save your settings while others may not even allow this adjustment. For these games, use the mixer FSYNTH command to set your desired MIDI output volume either in your startup batch file or the [autoexec] section in the game\u2019s config file, e.g.:
C:\\>mixer FSYNTH 33\nThis is very much a matter of personal opinion. We\u2019ve compiled a list of SoundFont recommendations suitable for DOS gaming on our wiki.
Linux users: if you have the fluid-soundfont installed on your OS, it will be picked up automatically by default.
"},{"location":"downloads/release-notes/0.76.0/#integer-scaling-pixel-perfect-option-for-opengl-output","title":"Integer scaling (pixel-perfect) option for OpenGL output","text":"Integer scaling (aka pixel-perfect mode) is now also available via OpenGL.
You can test integer scaling by setting the following output options:
output = openglpp \u2014 OpenGL + integer scaling. This option is used to provide backwards compatibility with other DOSBox forks.
output = texturepp \u2014 SDL2 texture backend + integer scaling. This option was added in 0.75.0.
These two options behave pretty much the same, except Linux users can enjoy resizable windows with output = openglpp.
Examples running fullscreen on 1080p display:
The Lost Vikings (1993) \u2014 with integer scaling
Epic Pinball (1993) \u2014 with integer scaling
Tip
Integer scaling works best for games that use square pixels; most DOS games use non-square pixels (often using resolution 320\u00d7200 / PAR 5:6)\u2014for those titles sharp-bilinear scaling (DOSBox Staging default setting) works better.
This video essay by Displaced Gamers provides a great explanation:
DOS Gaming Aspect Ratio \u2014 320\u00d7200
The output = openglpp option with windowresolution = resizable is also a good choice for text mode DOS applications as it produces sharp text (but sacrifices the proper DOS font aspect ratio):
Turbo Pascal in windowed mode with pixel-perfect scaling
"},{"location":"downloads/release-notes/0.76.0/#dynamic-recompilation-for-powerpc-and-power8-ppc64le","title":"Dynamic recompilation for PowerPC and POWER8 (ppc64le)","text":"Roughly two years ago jmarsh of the vogons.org forums published a feature-complete dynamic recompilation patch supporting the PowerPC (32-bit) architecture. This was quickly expanded by the community to support the POWER8 (64-bit) architecture as well. Both patches (with slight improvements) were merged to DOSBox Staging.
Shoutout to the AmigaOS community for the help with thoroughly testing this significant PowerPC contribution!
"},{"location":"downloads/release-notes/0.76.0/#quick-edit-and-find-your-configuration-file","title":"Quick-edit and find your configuration file","text":"It can be cumbersome to edit and find your default dosbox-staging.conf file. You might not know where it\u2019s located or it might be hidden away due to certain OS settings.
These two command-line options can help:
dosbox --editconf, opens the .conf file in a text editor.
This option respects the EDITOR environment variable if set to your prefered editor. Otherwise, it uses one of the following: nano, vim, vi, notepad++.exe, or notepad.exe.
dosbox --printconf, prints the path to the .conf file.
The ls (list directory contents) command is widely available across Unix-based operating systems. Most users of modern OSes are more likely to have it in their muscle memory rather than the DIR DOS command.
A very simple implementation of ls has been added that resembles the default operation of GNU ls:
Windows 3.11 listed using dir /w /p \u2014 not enough space to show all files, hard to distinguish between files and directories
The same directory listed using ls \u2014 more efficient utilisation of space in 80\u00d725 DOS text mode, easier to read
Audio speakers work by pushing and pulling their diaphragm at a rate equal to the audio\u2019s frequency.
Physical PC speakers can sometimes be left in a pushed-out or pulled-in state through constant voltage, called DC offset, which typically isn\u2019t a problem on real hardware. However in DOSBox, the PC speaker\u2019s offset samples mix with those from other audio sources such as the Sound Blaster or Adlib, which can:
Cause a pop if the next sample played has a position significantly different from the position of the DC offset.
Harm accurate sound reproduction of other sound devices by moving half the waveform further away from the center line (making it louder) and the other half of the waveform closer to the center line (making it quieter).
This new configuration option, zero_offset under the [speaker] section, defaults to 'auto'. It\u2019s enabled for non-Windows systems and disabled on Windows as some of its audio drivers appear to attempt their own DC offset correction.
For more details about this change, see: #480
For a discussion about Windows 10 performing DC offset correction, see: #625
The game has left the PC speaker in an offset position, which is detected and silently \u201cwound down\u201d in a fraction of a second.
"},{"location":"downloads/release-notes/0.76.0/#audio-pop-and-click-prevention","title":"Audio pop and click prevention","text":"Some games generate audio pops or clicks during startup. We\u2019ve added two changes to reduce these occurences:
On startup, the game greets our ears with an unatural instantaneous pop. In the second image, we see the enveloper briefly in action ramping the instaneous volume to prevent the pop.
For more visuals and detail about the enveloper, see: #442
For a list of many more games that had their pops cleaned up, see: #411
On startup, Lands of Lore: The Throne of Chaos\u2019s audio driver blasts our ears with two instantaneous pops, which are eliminated after suppression.
"},{"location":"downloads/release-notes/0.76.0/#splash-screen-and-help-banner-verbosity-control","title":"Splash screen and help banner verbosity control","text":"The splash screen and its delay, as well as the blue help banner, can now be skipped using the startup_verbosity setting in the [dosbox] section in the config file. The verbosity can be set as follows:
high shows everything: the splash screen, blue help banner, and initial console output.
medium skips just the splash screen and its delay, but still shows the blue help banner and initial console output.
low skips both the splash screen, delay, and blue help banner, but still shows initial console output.
quiet skips all of the above. The first output will either be the command prompt or output from startup executables or batch files.
By default, the verbosity is set to auto, which is either low when an executable or directory is passed on the command-line or high when DOSBox Staging is started without initial commands.
For a visual depiction of the options, see: #477
"},{"location":"downloads/release-notes/0.76.0/#revise-help-messages-for-mount-and-imgmount-commands","title":"Revise help messages for MOUNT and IMGMOUNT commands","text":"These commands are usually thoroughly documented in the manual, but having usage examples at your fingertips is more convenient. Help can be invoked by passing one of the following parameters: /? (DOS style), or -h, --help (GNU style).
Read more in: #729
Revised help messages provide usage examples, common parameter descriptions, and use a limited set of colours to improve readability.
"},{"location":"downloads/release-notes/0.76.0/#improve-telnet-mode-handling-for-modem-emulation","title":"Improve Telnet-mode handling for modem emulation","text":"For those hosting a BBS behind a Telnet interface, you can now pre-configure your serial port in Telnet-mode with the telnet:1 argument, as follows:
[serial]\nserial1 = modem telnet:1 listenport:2323\nFor those dialling BBSs hosted behind a Telnet interface, use the following dial-prefix: AT+NET1DT. In general, the +NET1 or +NET0 AT-command will enable or disable Telnet-mode, respectively.
This change brings Telnet-mode in-line with the Hayes multi-character command specification, which should be compatible with existing BBS software.
For more background about this change, see: #582
When telnet-mode is set according to the remote BBS\u2019s needs, you will experience fast and corruption-free transfers.
"},{"location":"downloads/release-notes/0.76.0/#fix-setting-file-timestamp","title":"Fix setting file timestamp","text":"DOS function 5701h \u201cSet File Time/Date\u201d was implemented.
This corrects a long-standing emulation issue when it comes to date handling of files created in DOS (e.g. when files are being unpacked from an archive). This fixes some game installers and other software that checks file modification times.
"},{"location":"downloads/release-notes/0.76.0/#case-insensitive-paths-handling","title":"Case-insensitive paths handling","text":"Paths passed to commands mount, imgmount, and audio track paths in .cue and .ins files are now treated as case-insensitive, regardless of the operating system.
Fixes numerous issues with running DOS games on Linux or FreeBSD. This change alone corrects the vast majority of Windows-only DOS game releases on GOG or Steam (such as e.g. Settlers II, Redneck Rampage, or Mortal Kombat* series)\u2014users no longer need to manually adjust the paths after unpacking games from Windows installer. This should significantly improve the quality of Lutris installers as well.
"},{"location":"downloads/release-notes/0.76.0/#revise-default-keyboard-shortcuts","title":"Revise default keyboard shortcuts","text":"The default keyboard shortcuts were revised to avoid triggering conflicting OS default shortcuts. We\u2019ve only changed those that that were not typically used by general users.
The list of new default shortcuts are:
Keymapper received tiny usability improvements as well: it displays the keyboard shortcut (binding) for the selected action.
"},{"location":"downloads/release-notes/0.76.0/#monochrome-palette-colour-setting","title":"Monochrome palette colour setting","text":"When emulating monochrome displays (Hercules or CGA/monochrome), the default colour palette can now be selected in the configuration file.
This feature was backported to 0.75.2 release; read more.
"},{"location":"downloads/release-notes/0.76.0/#raw-mouse-input-setting","title":"Raw mouse input setting","text":"User can now bypass the operating system\u2019s mouse acceleration and sensitivity settings. This works in fullscreen or when the mouse is captured in window mode.
This feature was backported to 0.75.2 release; read more.
"},{"location":"downloads/release-notes/0.76.0/#10-axis-controller-support","title":"10-axis controller support","text":"Old joysticks compatible with DOS games can be emulated using modern 10-axis controllers (like DualShock or Xbox controllers).
This feature was backported to 0.75.1 release; read more.
"},{"location":"downloads/release-notes/0.76.0/#log-memory-base-address","title":"Log memory base address","text":"The base memory address of DOS\u2019s emulated memory region is now logged to the console to help some users of external software, such as Cheat Engine.
This feature was backported to 0.75.1 release; read more.
"},{"location":"downloads/release-notes/0.76.0/#bugfixes","title":"Bugfixes","text":"Some notable bugfixes:
dir /p in non-standard text modes. (#528)capture_mouse middlegame setting. (#563)cls command. (#639)Fix Pentium CPUID to indicate CPU without FDIV bug. (#694)
(from SVN) Multiple bugfixes and regression fixes for various games or demoscene productions, such as Clue: Master Detective (1989), (8c002), Pleasure\u2019n Pain demo (8c07c, e9a67), MayDay demo (b6e77), PC Tools 9, and others.
(from SVN) Set Precision Exception in FRNDINT (Round to Integer instruction), to avoid bug when running Borland Pascal pow implementation. (7892b)
(added on 2020-12-04) Windows x64 builds are not available for now due to regression after building in Visual Studio 16.8.2. (#746)
The W^X memory protection (enabled by default via e.g. SELinux) prevents dynamic recompiler from working. (#253)
Keymapper has problems with mapping multiple axes when multiple controllers are plugged in (e.g. notably when using modern joysticks and throttles connected at the same time). (#342)
GLSL shader implementation crashes on certain Intel GPUs on Arch. (#319)
Mapping key scancodes on X11 using xmodmap can break SDL2 ability to detect your keyboard layout and leave you with non-functional keyboard input. Use udev instead of xmodmap to prevent this problem.
Some users of Gnome 3.38.1 experience problems when toggling fullscreen (both X11 and Wayland). This seems to be a Gnome issue; if you experience it as well, please make a report in the bugtracker.
Option gusrate in the [gus] section was removed. The revised Gravis UltraSound emulation implementation made this option obsolete.
Option oplrate in the [sblaster] section was removed. This value is now automatically tied to rate in [mixer] to avoid resampling (so users do not need to manually correlate values for these two options any more).
Project switched to using C++14.
We introduced unit tests (using Google Test framework). At the moment, unit tests are running on Linux only\u2014to build them use --enable-tests configure flag and make test to run them. They are included in CI gating.
Windows x64 builds were added to Visual Studio solution (both Debug and Release profiles).
CI was extended with gating based on MSVC (32-bit and 64-bit builds)
Due to instability and extremely slow installation times MSYS2 was removed from gating CI. It is still included in our daily builds, but we do not recommend using MSYS2 for development.
Linux builds for ARMv6, ARMv7, ARMv8 (AArch64), ppc64le, and s390x architectures were added to our set of daily builds.
We fixed all -Wall -Weffc++ warnings on Linux and macOS and corrected a large number of issues detected via static and dynamic code analysis tools.
When the project started we inherited 1411 warnings from DOSBox; as of November 2020, the builds are finally clean, so it\u2019s easier to make sure we do not introduce new warnings.
"},{"location":"downloads/release-notes/0.76.0/#changes-merged-from-upstream-projects","title":"Changes merged from upstream projects","text":"During DOSBox Staging 0.76 development period we merged 1035 commits, including 55 commits originating from the DOSBox project.
"},{"location":"downloads/release-notes/0.76.0/#maintainers","title":"Maintainers","text":"SVN r4336:r4392
We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"downloads/release-notes/0.77.0/","title":"0.77.0 release notes","text":"Release date: 2021-07-02
"},{"location":"downloads/release-notes/0.77.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
Migrated Staging from autotools to the Meson build system. Those building from source, please see BUILD.md in the repository. See: #854
Added write-xor-execute page support to comply with the latest macOS and SELinux security policies
Thanks to jmarsh and Jonathan Campbell for discussions on vogons. See: #1031
"},{"location":"downloads/release-notes/0.77.0/#variable-expansion-in-the-interactive-dos-shell","title":"Variable expansion in the interactive DOS shell","text":"See: #1059
"},{"location":"downloads/release-notes/0.77.0/#finished-fluidsynth-integration","title":"Finished FluidSynth integration","text":"FluidSynth is now included in all release binaries. See the wiki notes for how to use it. Run MIXER /LISTMIDI in the DOS shell to see your available soundfonts.
Thanks to:
Christian Lestrade for authoring this support in 2005, and all subsequent maintainers.
Meson for adding FluidSynth to the WrapDB.
The MT-32 emulator is now included in all release binaries. See the wiki notes for how to use it. Run MIXER /LISTMIDI in the DOS shell to see the available MT-32 models and versions.
See the list of unmissable MT-32 experiences, courtesy vogons.org forum user Shreddoc and contributors.
Thanks to:
Canadacow for authoring MT-32 emulation in 2003, KingGuppy and Mok for the follow-on work, and SergM who continues to maintain and improve the Munt project today.
Meson for adding libmt32emu to the WrapDB.
Microsoft for adding libmt32emu to Vcpkg.
See the wiki notes for how to use it.
Thanks to JMK for authoring PS/1 Audio emulation in 2008.
"},{"location":"downloads/release-notes/0.77.0/#innovation-ssi-2001-audio-device-support","title":"Innovation SSI-2001 audio device support","text":"See the wiki notes for how to use it.
Thanks to:
Vasyl for authoring SSI-2001 emulation in 2006.
Dag Lem for authoring, and Antti Lankila and Leandro Nini for improving the SID chip emulator.
Replaced the default Ctrl+F1 - F12 hotkeys on macOS with Cmd+F1 - F12 to reduce conflicts with the OS.
Thanks to Antti Peltola, Burrito78, and Kirk Klobe for guidance and testing.
"},{"location":"downloads/release-notes/0.77.0/#translation-improvements","title":"Translation improvements","text":"Added or improved translations for French, Italian, Polish, Russian, and Spanish.
Thanks to Draky50110 (fr), Kappa971 (it), dreamer (po), IlyaIndigo (ru), and Peluchito (es).
"},{"location":"downloads/release-notes/0.77.0/#improved-startup-settings","title":"Improved startup settings","text":"Added splash_only to the startup_verbosity settings. This shows the splash but skips the help banner.
Three relative window sizes, small, medium, or large, are now understood by the windowresolution config setting. These T-shirt sizes correspond to a window that\u2019s 25%, 50%, or 80% of your desktop\u2019s area, regardless of DPI or type of monitor (be it 720p, 1080p, or 4K).
Window resizing using corner-drag is now auto-enabled on all platforms when conditions permit.
"},{"location":"downloads/release-notes/0.77.0/#bugfixes","title":"Bugfixes","text":"The following user-visible bugs were fixed:
Will no longer lose focus on Raspberry Pi when launched fullscreen in an Xorg session. (#995)
Release builds now use dosbox-staging.conf as the primary config file instead of dosbox-staging-git.conf. (#932)
Windows release builds once again mount Opus CD-DA tracks, which was a regression in 0.76. (#885)
AUTOTYPE now works with all games. Until now, a subset of games didn\u2019t respond to its keystrokes. (#942)
Shoulder triggers on some six-axis controllers, such as the PS4 and Logitech\u2019s F310 and F710 controllers, can now be mapped. (#944)
When toggling out of fullscreen mode, in some corner cases this resulted in a blank window. This is now fixed. (#1096)
The 0.77 release includes 920 commits plus 35 commits originating from the DOSBox project.
"},{"location":"downloads/release-notes/0.77.0/#dosbox-staging-members","title":"DOSBox Staging members","text":"The following members actively supported the project during the 0.77 timeframe:
The following authors, co-authors, wiki editors, translators, testers, and bug reporters directly contributed to the 0.77 release:
The following DOSBox authors\u2019 SVN commits (r4393 through r4459) were merged during the 0.77 timeframe:
The following patch or external project authors\u2019 sources were merged during the 0.77 timeframe:
We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
The project maintains original authorship on all commits (including those from upstream, patches, and external projects) to ensure correct attribution is recorded in the version control system.
"},{"location":"downloads/release-notes/0.77.1/","title":"0.77.1 release notes","text":"Release date: 2021-08-28
"},{"location":"downloads/release-notes/0.77.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
The following user-visible bugs were fixed in 0.77.1 (reported-by; fixed-by):
Fix crash when using 32-bit build and the dynamic-core on Windows 10 (Banjo-Oz; kklobe).
Fix crash when using 32-bit build and the dynamic-core on Raspbian (nemo93; kklobe).
Fix degraded joystick control during once-a-month integer time-rollover event (cimarronm).
Fix inability for a program to use its own bundled HELP and CHOICE executables (SmilingSpectre; Wengier).
Fix inability to map joystick events when joysticktype was configured as none (GranMinigun; kcgen).
Fix incorrect setup of the joystick when type configured as 2axis (choum; kcgen).
Fix input control lag on some Windows systems and on macOS when the \u201cMagnet\u201d GUI management program is running (Burrito78; kcgen).
Fix mouse control in Alive \u2013 Behind the Moon (DOSBox SVN r4461/ripsaw8080).
Fix performance regression when building releases on arm-based Linux SBC (mrfixit2001).
Fix potential Tseng ET3000 video mode corruption (DOSBox SVN r4460; ripsaw8080).
Fix resizing of window impacting the debugger TUI on Windows (DOSBox SVN r4462; ripsaw8080).
Fix potential crash when quickly Alt+Tabing on Windows (kklobe).
Fix size and placement of video content when using a resizeable window mode (bmunger; kcgen).
Fix unformattable content in translation files (dreamer; kcgen).
French, German, Italian, Polish, Russian, and Spanish users: move the bundled translations directory into your DOSBox Staging configuration directory.
macOS users
Right click the dosbox-staging.app file and select \u201cShow Package Contents\u201d. The translations folder is inside Contents/resources/.
After the move, you will have:
Linux/home/username/.config/dosbox/translations/ macOS ~/Library/Preferences/DOSBox/translations/ Windows C:\\Users\\<username>\\AppData\\Local\\DOSBox\\translations\\ Load your language on the command-line:
dosbox -lang de\ndosbox -lang es\ndosbox -lang fr\ndosbox -lang it\ndosbox -lang pl\ndosbox -lang ru\nOr via primary or local config file:
[dosbox]\nlanguage = de\n# de, es, fr, it, pl, ru\nTip
Use dosbox -editconf to open your config file.
For future reference, the above is also discussed in the README.
"},{"location":"downloads/release-notes/0.77.1/#thank-you","title":"Thank you","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox Team and the DOSBox-X Team.
DOSBox Staging maintains original authorship on all commits to ensure attribution is recorded in the version control system (git).
"},{"location":"downloads/release-notes/0.78.0/","title":"0.78.0 release notes","text":"Release date: 2021-12-25
"},{"location":"downloads/release-notes/0.78.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
Added Universal binary for macOS, supporting x86-64 and ARM64 (Kirk Klobe) (#1240)
Added a workaround for vsync lag, which is useful for video outputs that enforce vsync (Kirk Klobe) (#1158)
Added window size and placement customizations (John Novak) (#1272)
Added full /help output text for the AUTOTYPE, BOOT, CALL, CHOICE, CLS, COPY, DIR, ECHO, EXIT, GOTO, HELP, IF, INTRO, KEYB, LS, MD/MKDIR, MEM, RD/RMDIR, REN/RENAME, RESCAN, SHIFT, SUBST, and TYPE commands (Wengier) (#1356)
Added MSYS2-based release builds and instuctions for those on Windows using MSYS2 (Sherman Perry) (#1443)
Merged PCjr composite patch by NewRisingSun. Thanks to JKapp76 for testing and feedback (NewRisingSun) (#1122)
Merged CGA composite improvement patch by reenigne, respectively. Thanks to JKapp76 for testing and feedback (reenigne) (#1157)
Added bash-shell completion. See contrib/linux/bash-completion/README for adding this to your shell (FeignInt) (#1200)
Added Loguru, a fast cross-platform logging subsystem. Logs are now time-stamped and warnings are now colorized (Kirk Klobe) (#1225)
Merged S3 video patch by s3freak. This adds more video modes and supports up to 8 MiB of video memory, vmemsize = 8, when using machine = svga_s3. Thanks to Zorix, Grounded0, Brandon Roberts, GranMinigun, Kirk Klobe, and nemo93 for testing (s3freak) (#1244)
Added configurable FluidSynth chorus and reverb settings. Thanks to GranMinigun for the extensive listening tests (kcgen) (#1268)
Added auto-exit. When an executable that\u2019s passed on the command-line exits, then so too will the emulator. This is equivalent to manually adding the -exit command-line flag. Thanks to Burrito78 for testing (kcgen) (#1269)
Added layered and portable configuration file handling. Thanks to JKapp76, Grounded0, and Burrito78 for testing (kcgen)
Added ENet (reliable UDP) as an option for modem and null-modem transport, as well as SERIAL.COM for runtime serial-port configuration (Scott Duensing) (#1398)
Added support for virtual Ethernet and TCP/IP networking via slirp (Jookia) (#1419)
Added support for networking in Windows for Workgroups 3.11 from the shell. Previously networking in WfW was only possible when booting a real MS-DOS installation from a bootable HDD image (Wengier, nanshiki) (#1447)
Added IDE controller support, authored by joncampbell123 of the DOSBox-X project, for CD-ROM image-mounts, which is useful for CD-ROM based games that also happen to need a real DOS environment such as Revell\u2019s car games, like European Racers (joncampbell123, Wengier) (#1451)
Fixed 32-bit dynamic core crashes (Kirk Klobe) (#1205)
Fixed regression when setting windowresolution in the config file. Thanks to arrowgent for the report and testing (kcgen) (#1144)
Fixed hanging in Mortal Kombat Trilogy when joysticktype = none. Thanks to nemo93 for the report and GranMinigun for also testing (kcgen) (#1241)
Fixed regression during shutdown while using the ALSA sequencer. Thanks to AaronBPaden for the report and testing (kcgen) (#1362)
Fixed zero-offset PC Speaker issue on Windows 11. Thanks to ggpettas for reporting (kcgen) (#1389)
Fixed regression that broke video recording. Thanks to Grounded0 for reporting and testing (kcgen) (#1400)
Fixed ability to run an application-provided help.exe|com program. Thanks to SmilingSpectre for reporting (Wengier) (#1136)
Removed VESA modes 320\u00d7200\u00d715/16/24, which were added late in the 90s and were not properly supported by some games (NicknineTheEagle) (#1457)
Translations (de, es, fr, it, pl, and ru) are included with the release package and can be selected using the two-letter country code either via environment variable (LANG=de), config file ([dosbox] language = it), or command-line (-lang ru). See Section 14 in the README file for more details.
To ensure authors are credited for their work, the project records authorship on all commits in the version control system, including all works from the upstream DOSBox project, patch authors, and external projects.
0.78 author Lines changed arrowgent 361 Brandon Roberts 1495 Burrito78 1882 Christer Solskogen 4 Dan Church 2 David Reid 6733 Eli Schwartz 6 GranMinigun 1204 Gregory Pakosz 1178 John Novak 668 Jookia 2296 Kappa971 2773 kcgen 63022 Kirk Klobe 1658 llm 6 NicknineTheEagle 30 Patryk Obara 103 ripsaw8080 59 s3freak 648 Scott Duensing 7330 Sherman Perry 5408 Sjoerd van der Berg 28 Wengier 5430 Yann Collet 2438 ykhwong 7During the 0.78 timeframe, DOSBox SVN commits r4466 through r4471 were merged to the project and authorship is reflected above.
"},{"location":"downloads/release-notes/0.78.0/#wiki-authors","title":"Wiki authors","text":"0.78 wiki author Lines changed Alberto Salvia Novella 164 Burrito78 2 Grounded0 557 John Novak 12 Joshua Fern 30 kcgen 243 Kirk Klobe 2 LowLevelMahn 14 MasterO2 395 nemo93 5370 Tobias Gruetzmacher 5"},{"location":"downloads/release-notes/0.78.0/#financial-contributors","title":"Financial contributors","text":"Antti Peltola: Project sponsor. His combined contribution of 4,000 USD spanning the 2021 period to maintainers and the project has allowed the team to add a dedicated Apple M1 build host. Thank you!
Burrito78: Project backer. Thank you!
To support our work, join the Open Collective.
"},{"location":"downloads/release-notes/0.78.0/#thank-you","title":"Thank you","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"downloads/release-notes/0.78.1/","title":"0.78.1 release notes","text":"Release date: 2022-01-07
"},{"location":"downloads/release-notes/0.78.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
Maintenance changes to 0.78.1 are as follows (reported-by; fixed-by):
Fixed a crash when exiting fullscreen mode and also using OpenGL output (NicknineTheEagle; kcgen)
Fixed a crash and host input lockup when using SDL\u2019s kmsdrm video driver (GranMinigun)
Fixed an early exit bug when using the -exit and -c exit command-line arguments (pheener and d10sfan, kcgen)
Fixed a memory leak when changing one or more serial port types at runtime (kcgen)
Fixed a regression that failed to apply aspect correction when using pixel-perfect output modes (Diduz; kcgen)
Fixed a regression that disabled the keyboard input when using the debugger (LowLevelMahn; kcgen)
Fixed a regression that impacted 32-bit performance on some Windows systems (RaymanXY; Kirk Klobe and kcgen)
Fixed a regression that causes a crash when opening UPX-compressed code-page files (FeralChild64; Wengier)
Improved the modem\u2019s command-mode handling (NicknineTheEagle)
Corrected the modem\u2019s DTR drop delay units from ms to hundredths of a second (NicknineTheEagle)
Reverted the allowance that let the VESA refresh rate use the host rate (RaymanXY; kcgen)
Allowed read-only image mounting for write-protected disk and floppy images (Burrito78; Wengier)
Updated the German messages and config file text (Burrito78)
Updated the Italian messages and config file text (Kappa971)
Fixed a documentation conflict describing the command line\u2019s version flag (arrowgent)
Documented how to install gmock, a dependency added during 0.78.0, on Fedora (oturpe)
Fixed a compilation issue with Loguru on ARM32 using GCC 8 (rtissera; kcgen)
Fixed a compilation issue with older C++17 compilers missing std::filesystem support (jowtron; gulrak and kcgen)
Fixed a build tool-specific bug that exposed the UI when running gmock tests (oturpe and voyageur; brandonrobertz and kcgen)
The MSYS2-built debugger will fail to open if launched from the Windows UI.
As a work-around, run it from within a command console.
Thanks to Sherman Perry for investigating this issue and isolating it
Audio might stutter on some Windows platforms. If your system is affected, adjust the mixer\u2019s settings in your config file as follows:
[mixer]\nblocksize = 1024\nprebuffer = 25\nTip
Run dosbox -editconf to open your config file.
Thanks to Genju for reporting this regression and isolating the solution.
We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"downloads/release-notes/0.79.0/","title":"0.79.0 release notes","text":"Release date: 2022-09-19
"},{"location":"downloads/release-notes/0.79.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
It should run everything that prior versions did.
The default settings will give you improved audio, refined graphical scaling and colour accuracy, more robust mouse handling, and a more usable shell.
There are new and some deprecated config settings: your console log will inform you with orange-coloured warning messages to help you.
For performance-demanding games that use max cycles, it should provide just as much performance (or a bit more) than prior versions.
International users: it should detect your language and keyboard layout on startup. We recommend reading the Localisation section for details.
Repo packagers: learn about bundled resource files and the updated Meson build settings.
Read on for all the details!
"},{"location":"downloads/release-notes/0.79.0/#audio-improvements","title":"Audio improvements","text":""},{"location":"downloads/release-notes/0.79.0/#adlib-gold-surround-module-emulation","title":"AdLib Gold Surround Module emulation","text":"The ultra-rare AdLib Gold surround sound daughterboard is now emulated, which makes it possible to finally enjoy the Dune soundtrack in its full glory! That\u2019s the only game in existence that makes use of the surround module.
The following config is recommended for Dune. The setup utility should auto-detect AdLib Gold and the surround module correctly with these settings.
[sblaster]\nsbtype = sb16\noplmode = opl3gold\nMost DOS-era sound cards feature an output low-pass filter (and sometimes a high-pass filter too) that play an important role in giving their sound its character. DOSBox Staging can now accurately emulate these analog output stage filters for all supported sound devices.
"},{"location":"downloads/release-notes/0.79.0/#sound-blaster","title":"Sound Blaster","text":"For backward compatibility reasons, the sb_filter config parameter defaults to the newly introduced modern filter, which uses the simple linear interpolation method of previous DOSBox versions. To turn on accurate analog output filter emulation, set the sb_filter to auto. This will set the correct filters for each Sound Blaster model depending on the sb_type value. You can also set a model-specific filter manually if you wish, e.g. this is how to use a Sound Blaster 16 but with Sound Blaster Pro filters:
[sblaster]\nsbtype = sb16\nsb_filter = sbpro1\nSome Sound Blaster models can toggle the filter on and off in software; you can force the filter to be always on by setting sb_filter_always_on to true.
OPL and CMS filters are also accurately emulated; please refer to the descriptions of the opl_filter and cms_filter config parameters for further details.
Filters are enabled by default for all small-speaker audio systems (PC Speaker, PS/1 Audio, Tandy, and the various LPT DAC options). Depending on the particular device, these filters either emulate the analog output filters of the original device, or the sound coming out of a small band-limited speaker in an acoustic environment. Either way, the result is a more period-accurate and pleasant listening experience, especially on headphones.
Small-speaker filters are controlled by the following config parameters:
lpt_dac_filterpcspeaker_filterps1audio_dac_filterps1audio_filtertandy_dac_filtertandy_filterAdvanced users can specify custom filter settings for any of the supported sound devices. You can specify either a high-pass filter, a low-pass filter, or both at the same time using the following format
TYPE ORDER FREQ [TYPE ORDER FREQ]\nwhere TYPE can be hpf (high-pass) or lpf (low-pass), ORDER is the order of the filter from 1 to 16 (1st order results in a 6dB per octave slope, 2nd order in a 12dB per octave slope, etc.), and FREQ is the filter\u2019s cutoff frequency in Hz.
For example, to use a 2nd order (12dB/oct) low-pass filter at 8 kHz for the Sound Blaster:
sb_filter = lpf 2 8000\nTo use a 3rd order (18dB/oct) high-pass filter at 120 Hz, and a 1st order (6dB/oct) low-pass filter at 6.5 kHz for the PC Speaker:
pcspeaker_filter = hpf 3 120 lfp 1 6500\nIn addition to the sound devices mentioned above, you can use custom filters even with devices that don\u2019t filter the output in the original hardware (e.g. GUS, MT-32), and the FluidSynth virtual MIDI device via the following config parameters:
fsynth_filtergus_filterinnovation_filtermt32_filterListening to audio material on headphones where certain sounds are only present in either the left or the right channel can be a rather distracting and unpleasant experience. This is most noticeable on certain Dual OPL game soundtracks and tracker music (e.g. MOD, XM, S3M, IT, etc.)
The new crossfeed feature remedies that; by enabling crossfeed in the [mixer] section, a certain percentage of the left channel is mixed into the right, and vice versa. The default crossfeed strength is 40% which is a good general setting, but you can provide a custom percentage value as well (e.g. crossfeed = 55).
The amount of crossfeed can be fine-tuned per individual channels via mixer commands; please type MIXER /? in the DOSBox prompt for further details.
One of the most exciting new audio features is the ability to add reverb (the emulation of real acoustic spaces) and chorus effects to any mixer channel. This can add a lot of atmosphere to dry-sounding synth soundtracks (typically OPL music) and elevate them to a whole new level! Enabling reverb and chorus processing is especially useful for headphone-listening.
The quickest way to enable the reverb effect globally is to put reverb = on in the [mixer] config section. This will add reverb to all synth channels (e.g. PC Speaker, OPL, CMS), and a lesser amount to digital audio channels (e.g. Sound Blaster, GUS). While the default setting works well with most games, it\u2019s highly recommended to experiment with the five available reverb presets to find the optimal setting for each game:
tiny simulates the sound of a small integrated speaker in a domestic room. This preset is specifically tailored for small-speaker audio systems (PC Speaker, Tandy, PS/1 Audio, and LPT DAC devices).
small adds a subtle sense of space; it\u2019s best suited for games that use a single synth (typically OPL) for both the music and the sound effects.
medium is the default preset; it\u2019s a middle-of-the-road setting that works well with a wide variety of games.
large is a large hall-style reverb that is recommended for games that use separate audio channels for music and digital audio (e.g. OPL audio and Sound Blaster digital sound.)
huge is a stronger variant of the large hall preset which is ideal for slower-paced, atmospheric music.
Another way to add a sense of space to the sound is by enabling the chorus effect. This adds stereo movement and increases the perceived stereo width, which is especially noticeable on purely mono signals on headphones (e.g. PC Speaker or OPL2 music). To enable it, just put chorus = on into the [mixer] config section, or select one of the three predefined chorus strength presets (light, normal, and strong).
Similarly to crossfeed, per-channel reverb and chorus settings can be tweaked by mixer commands; please type MIXER /? in the DOSBox prompt for details.
Audio examples
Naturally, you can combine chorus and reverb, and it\u2019s not only possible to do so, but highly recommended for achieving the best results! The below recordings showcase how crossfeed, reverb, chorus, and output stage filters can work in tandem to give old DOS game soundtracks a new life.
The exact settings used for these recordings are documented on the wiki, along with suggested audio configs for many other games. Make sure to check them out and experiment with the settings yourself! \ud83d\ude0e \ud83d\udd09 \ud83c\udfa7
Your browser does not support thevideo element. Alone in the Dark (1992, floppy version) \u2014 introduction
Game Type Audio example Alone in the Dark(floppy version) OPL2 Your browser does not support theaudio element. Warcraft: Orcs & Humans OPL3 Your browser does not support the audio element. Dungeon Master II:The Legend of Skullkeep Dual\u00a0OPL2 Your browser does not support the audio element. Ultima Underworld I: The Stygian Abyss Dual OPL2 Your browser does not support the audio element. Elvira: Mistress of the Dark Dual\u00a0OPL2 Your browser does not support the audio element. Skate or Die! Tandy Your browser does not support the audio element. Zak McKracken and the Alien Mindbenders Tandy Your browser does not support the audio element. Budokan: The Martial Spirit CMS Your browser does not support the audio element The Secret of Monkey Island CMS Your browser does not support the audio element."},{"location":"downloads/release-notes/0.79.0/#master-compressor","title":"Master compressor","text":"An auto-levelling dynamic range compressor has been introduced to the master channel to ensure that the audio output never gets distorted, no matter how high the volume levels are. This is on by default and is virtually transparent when the output is not driven into clipping. However, purists can disable it by setting compressor to off, and then ensure correct non-clipping output levels manually.
The mixer now uses a full 32-bit floating-point processing path internally, which means you can no longer overload individual mixer channels into clipping by using high per-channel volume settings. As long as the summed master output is not clipping, it\u2019s guaranteed that nothing else will.
A fixed high-pass filter at 20 Hz has been introduced right before the final output that gets rid of any DC-offset and subsonic rumble globally.
The MIXER command has received an overhaul too. First of all, the status output looks better, and the following improvements have been made:
Now you can set reverb, chorus, and crossfeed levels per mixer channel; type MIXER /? in the DOSBox prompt for further details.
The FM channel has been renamed to OPL.
The SPKR channel has been renamed to PCSPEAKER.
The sample rate column has been removed (it served no useful purpose, and the displayed values were often technically correct but misleading).
For a high-level overview of the new mixer architecture, please refer to this diagram.
NukedOPL has long been the default OPL mode in Staging. As it\u2019s basically a bit-perfect emulation of the Yamaha YMF262 OPL3 chip, and it runs fast enough even on low-end hardware such as the Raspberry Pi 4, all other less accurate OPL emulation modes have been removed.
"},{"location":"downloads/release-notes/0.79.0/#fluidsynth-configuration-changes","title":"FluidSynth configuration changes","text":""},{"location":"downloads/release-notes/0.79.0/#fluidsynth-reverb-and-chorus","title":"FluidSynth Reverb and Chorus","text":"Due to the introduction of the new mixer-level reverb and chorus effects, the FluidSynth reverb and chorus config parameters have been renamed to fsynth_reverb and fsynth_chorus, respectively.
To maintain backward compatibility with existing configurations, the FluidSynth reverb and chorus effects are enabled by default, so all your SoundFonts will sound just like in previous DOSBox versions. If you enable the mixer-level reverb (or chorus) as well (e.g. by putting reverb = on in the [mixer] section), you would get a second round of reverb (or chorus) processing on the FluidSynth output. This is by design as it allows users the greatest level of control over customising SoundFonts (e.g. some would sound best with the FluidSynth reverb only, some with both, etc.)
Note
In the SF2 format the reverb and chorus amounts are specified on a per-instrument basis, while the mixer-level effects are applied \u201cglobally\u201d to all instruments in the summed FluidSynth output. Therefore, what works best really depends on the particular SoundFont in question and on individual user preference (see this discussion for further technical details).
"},{"location":"downloads/release-notes/0.79.0/#volume-scaling","title":"Volume Scaling","text":"Previously, it was possible to specify a percentage after the SoundFont\u2019s name in the config to adjust its volume (e.g. soundfont = way_too_loud.sf2 30). This was introduced as a workaround for certain loud SoundFonts that tended to clip the mixer channel internally.
With the new floating-pointing mixer signal path, it\u2019s no longer possible to drive any of the mixer channels into clipping, therefore this workaround has been deprecated. Please use standard mixer commands to lower the volume of the FSYNTH channel if you wish to do so.
We\u2019ve integrated ripa\u2019s impulse-model PC speaker patch alongside DOSBox\u2019s existing (discrete-model) PC speaker implementation, which is still the default.
To use it, set the pcspeaker config setting to impulse (or go back to default with discrete).
James-F and VileRancour have mentioned in the linked thread that it generally improves the accuracy of square-wave effects, such as in Commander Keen and Duke Nukem (2D). This patch also can produce sounds when none previously existed, such as in Wizball, as noted by ripsaw8080.
For example, here\u2019s Wizball using the settings below:
[mixer]\nrate = 32000\n[speaker]\npcspeaker = discrete\nvideo element. Wizball (1987) \u2014 using discrete PC speaker emulation
Note
There are some audible regressions and harmonics that still exist in some games, so that\u2019s why this is an alternative and not the default.
"},{"location":"downloads/release-notes/0.79.0/#parallel-port-dac-models-disney-covox-and-stereo-on-1","title":"Parallel port DAC models: Disney, Covox, and Stereo-On-1","text":"Those familiar with DOSBox know that these three devices are emulated with the universal disney = true setting.
Like sbtype, we wanted the model of LPT DAC to be configurable, and so Staging\u2019s deprecated the disney setting in favour of lpt_dac that takes any of the following:
disney, for the Disney Sound Sourcecovox, for the Covox Speech Thingston1, for the Stereo-on-1 DAC deviceoff/none, to disable the DAC (default)This is paired with a corresponding filter setting, lpt_dac_filter, which approximates how the original device sounded. This means that the Disney Sound Source (which included a little speaker inside it) will sound a lot like you might remember.
lpt_dac Examples (ModPlay Pro & Star Control II\u2019s 8-bit Pkunk MOD) disney Your browser does not support the audio element. covox Your browser does not support the audio element. ston1 Your browser does not support the audio element. Like the other audio filters settings, the lpt_dac_filter can be toggled on, off, or customised.
The audio stream can now be manually muted with Ctrl+F8 (or Cmd+F8 on macOS).
You can also mute the audio automatically when DOSBox Staging goes to the background with this config setting:
[sdl]\nmute_when_inactive = true\nOr you can pause emulation entirely when in the background with:
[sdl]\npause_when_inactive = true\nAs DOSBox Staging currently lacks a shader preset system, tweaking shader parameters can only be accomplished by making changes to the shader source files themselves. Previously, you had to restart DOSBox to see the effects of such changes, which made fine-tuning shaders quite cumbersome, to say the least.
Now you can just use the Ctrl+F2 shortcut (Cmd+F2 on macOS) to reload the current shader at any time. Progress! \ud83d\ude0e
"},{"location":"downloads/release-notes/0.79.0/#cga-palette-override","title":"CGA palette override","text":"Now it is possible to override the default, canonical interpretation of the 16-colour CGA/EGA RGBI palette. The feature overrides the CGA colours in any CGA/EGA-like mode, so it even works in CGA/EGA modes with an emulated VGA or TGA (Tandy) graphics adapter.
Several presets have been included (e.g. Amiga and Atari ST colours for Sierra games, and various CGA/EGA monitor emulations), and you can specify custom palettes as well. Make sure to check out the description of the cga_colors config parameter for the list of available presets (you can read more about them here).
Defender of the Crown
tandy-warm emulates the colours as they appear on an actual Tandy monitor, which results in more subdued and pleasant colours. This is especially apparent on the greens.
cga_colors = default
cga_colors = tandy-warm
Gold Rush
The Amiga/Atari ST ports of Sierra AGI games feature a tweaked CGA palette with improved skin tones and sky colours.
cga_colors = default
cga_colors = agi-amigaish
Zak McKracken and the Alien Mindbenders
Now you can play the PC version of this classic adventure with Tandy sound and Commodore 64 colours!
cga_colors = default
cga_colors = colodore
When the image is scaled by non-integer ratios (e.g. when aspect correction is enabled with the default sharp OpenGL shader), previously the interpolation was performed in a gamma-incorrect way, leading to various unwanted artifacts. These were most noticeable on checkerboard dither patterns (used frequently in EGA games), appearing as interference (moir\u00e9) patterns, and on high-contrast antialiased text (e.g. regular black text on white background appeared bold).
macOS notes
All Mac browsers tend to display the below images with incorrect gamma on the built-in MacBook displays, which makes the \u201cbad\u201d images look less wrong, and there are slight interference patterns on the \u201cgood\u201d images. Please download the images and view them in the Preview app instead, which displays them correctly.
Time Quest
Good
Bad
Space Quest III: The Pirates of Pestulon
Good
Bad
Windwalker
Good
Bad
"},{"location":"downloads/release-notes/0.79.0/#high-dpi-on-macos","title":"High DPI on macOS","text":"The backstory: DOSBox Staging uses OpenGL output with the sharp bilinear scaling shader to keep the picture crisp no matter how big or small the image is, and minimise blurring on pixel transitions.
Due to the way macOS handles DPI scaling, the image was drawn at a much lower resolution, usually just a quarter of the window size. Then it was stretched by the system, producing an unpleasantly mushy presentation. But we want our pixels to be so sharp they could cut one\u2019s eyes
Without high DPI support
With high DPI support
Now DOSBox Staging can handle high DPI displays, be it Retina or not, so you and shaders alike can see all the (physical) pixels.
Please note that this is currently experimental: only macOS is currently supported, and we haven\u2019t thoroughly tested multi-display setups. Please report any weird behaviour! Support for Windows will come in the future, and for Linux, it is still uncertain. Also note that due to the way rendering is currently implemented, you may observe lowered performance on higher resolution displays, especially when running off integrated graphics. This might be remedied in the future as well.
"},{"location":"downloads/release-notes/0.79.0/#window-transparency-support","title":"Window transparency support","text":"There might be situations where you want to place the DOSBox Staging window on top of another window while seeing both windows at the same time. Indeed, you can now set the DOSBox Staging window as transparent, with a customised level of window transparency, so that you can see the background window as well. There is a new config option transparency for this, whose valid values are between 0 (no transparency; default) to 90 (high transparency).
DOSBox presents frames when new content is available, which means that sometimes the effective frame rate can vary between 0 FPS (if the screen content isn\u2019t changing) and as fast as the DOS vertical refresh (vblank) rate (typically up to ~70 Hz). We\u2019ll call this presentation mode Variable Frame Rate or VFR.
In addition to VFR, DOSBox Staging supports a Constant Frame Rate (CFR) presentation mode, which presents a constant frame rate defined by the emulated DOS rate, as well as variations on both:
Synced CFR, which presents a constant frame rate but is synchronised with the host\u2019s refresh rate. This presents only the most recently updated frame when the DOS rate exceeds the host rate.
Throttled VFR, which presents a variable frame rate up to the DOS rate throttled to the display\u2019s rate. This presents only the most recently updated frame when the DOS rate exceeds the host rate.
By default, DOSBox Staging inspects runtime conditions and picks the optimal presentation mode.
Synced CFR mode selected due to vsync-enforced video drivers
Although typically not needed, power users might be interested in forcing a given mode or rate, which can be done using the following config settings (which includes detailed descriptions in the conf):
[sdl]\npresentation_mode = auto | cfr | vfr\nhost_rate = auto | sdi | vrr | custom-rate\n[dosbox]\ndos_rate = default | host | custom-rate\nDOSBox did not support the piping operation previously, but DOSBox Staging now brings piping support as how it has worked in DOS and most other operating systems. This allows two or more commands to communicate by passing the output text of one command to another as its input text. For example, commands like ECHO Y | CHOICE will work, so that the Y option will be passed as the input of CHOICE command. Chained piping is also supported, such as DIR | SORT | MORE for displaying sorted directory output one screen at a time (provided that you have the SORT and MORE commands from MS-DOS or FreeDOS in your path). If the current directory and C:\\ are both read-only, the environment variable %TEMP% (or %TMP%) needs to be set within DOS pointing to a writable directory so that piping will work properly (e.g. SET TEMP=C:\\TEMP).
File attributes contain information about how the files should be used, and in DOS these correspond to Archive (A), Read-only (R), Hidden (H), and System (S) attributes. DOSBox Staging now adds support for file attributes through ATTRIB command (type ATTRIB /? for more information about this command) or through DOS API that accesses to file attributes. For example, some game installers and applications make use of file attributes. All file attributes are currently supported except for system and hidden attributes on mounted local drives for non-Windows platforms.
The CHOICE command allows you to choose from a list of options, but sometimes you want to have some default choice if no selection is made within the specific time period. DOSBox Staging now allows you to do this, by specifying the /T option which includes a default choice and the time period in seconds. For example, CHOICE /C:ABC /T:B,2 will default to the choice B (among A, B, and C) if no key press is made within 2 seconds.
Mounting physical CDs is now (re-)implemented in DOSBox Staging for better compatibility with games like Under a Killing Moon, System Shock, and The Pandora Directive. The feature is supported in DOSBox SVN but was forced to be dropped from DOSBox Staging earlier during the SDL2 migration process. We\u2019ve brought it back by using the SDL1 CD support code as an external library, plus restoring the main SDL CD interface from DOSBox.
To use the feature, execute the command mount -cd to list all CD drives and their numbers, and use -usecd NUMBER parameter to specify a CD drive NUMBER, just like you would do in DOSBox SVN. Playing CD audio tracks from physical discs is also supported in Windows as with DOSBox SVN.
You might have encountered the problem previously that you could not mount write-protected disk images, which happened simply because DOSBox Staging required write access to mount disk images.
Sometimes the user may also want to mount a disk image in a read-only manner (so that the content in the disk image will not be changed inside the emulator), even if the disk image itself is not write-protected. We have realised that in either case the requirement for write access is not needed for mounting disk images, so we have added support for mounting them in a read-only manner, either when the disk image files are read-only or when the -ro flag is specified by the users.
The internal Z drive that is automatically mounted when you launch DOSBox Staging is now fully customisable, allowing users to add their own files or programs to the drive by putting them in the drivez subdirectory inside the DOSBox Staging program directory. Files already existing on the Z drive will be replaced by the user-provided ones, e.g. you can use your own MEM.COM or KEYB.COM commands instead of the default ones on the Z drive. Moreover, support for one-level subdirectories has been added, allowing users to better organise their files, resulting in a cleaner-looking Z drive. The drive\u2019s contents can be refreshed via the RESCAN command to reflect any changes made to it at the host OS level.
The IMGMOUNT command allows you to mount disk or CD images, but sometimes you may want to mount multiple images to a single drive, swappable via a keyboard shortcut. Previously you had to specify the names of the all the image files one by one, even if they have some patterns in common (like DISK1.IMG, DISK2.IMG, DISK3.IMG, etc). IMGMOUNT command now supports wildcards for mounting image files, so that you can just specify a file pattern that matches all the image files that you want to include. For example, the command IMGMOUNT a d:\\*.img -t floppy will mount all image files with the IMG extension on D:\\ as floppy images.
Directories can now be automounted, provided the automount config setting is enabled (which it is, by default).
These automount directories are single-letter directories, a through y representing the mounted drive letter (where z is reserved for DOSBox\u2019s drive) placed inside a local drives/ directory, relative to the startup location. This drives/ directory can also be placed in a scanned resource location, like your DOSBox config directory or the release package\u2019s resources/ area.
Each drive can be customised with an accompanying <letter>.conf to define its mount type, label, and path. For example, to mount a local drives/d/ directory as a D: CD-ROM with the label SIERRA, the accompanying d.conf would contain:
[drive]\ntype = cdrom\nlabel = SIERRA\nA bundled Y: automount is provided in the release\u2019s resources/ directory that bundles a couple FreeDOS 3rd party tools (XCOPY.COM, DELTREE.COM, DEBUG.COM) along with an accompanying y.conf to add it to the PATH.
Note
This feature doesn\u2019t yet support image mounts, such as .img, .bin/cue, or .iso.
The 20-year-old FreeDOS code pages (screen fonts) and keyboard layouts were updated to the latest versions, offering countless new definitions for use. See the full list in the following documentation:
Some notable examples:
KEYB bg 3021 \u2014 sets a Bulgarian keyboard layout and code page, with Cyrillic characters encoded according to the MIK standard
KEYB cz489 867 \u2014 a so-called programmer keyboard layout (national characters available with Right Alt+0 - 9) for Czech and Slovak languages, with Kamenick\u00fd character encoding - which was more popular than code page 852
KEYB de 858 \u2014 German keyboard, code page with EUR currency symbol
KEYB hu 3845 \u2014 Hungarian keyboard, CWI-2 character encoding
KEYB pl 668 \u2014 code page specially designed for the Polish language; places national characters on the same positions as standard code page 852 (so it is compatible with current software and text documents), but preserves more table drawing symbols
KEYB pl 667 \u2014 Mazovia encoding for Polish language, used mainly by older business software
The display formats for dates, times, and decimals were previously fixed to the United States style, but this is no longer the case with this new version. Indeed, DOSBox Staging can now display date, time, and decimal formats according to the system locale and country settings, and for example, in the Canadian French locale (country code 2) the date and time will be displayed as 2002-10-01 12:34 instead of 10-01-2002 12:34p as displayed in the United States locale (country code 1). There is a new config option country which allows you to manually specify the country code for the date, time, and decimal formats.
Canadian French locale
United States locale
"},{"location":"downloads/release-notes/0.79.0/#local-language-and-keyboard-layout-detection-improvements","title":"Local language and keyboard layout detection improvements","text":"On macOS and Windows systems, local languages now are more robustly detected and applied.
Note that these can still be manually set using the language and keyboardlayout config settings when needed, or via the KEYB command as mentioned above.
The built-in mouse driver now provides a wheel support for application aware of CuteMouse extensions; examples include Necromancer\u2019s DOS Navigator and Mpxplay.
The original CuteMouse driver version 2.1 is also able to use the PS/2 mouse wheel, just start it with CTMOUSE /o.
Numerous serial (COM port) mice are now emulated:
To enable serial mouse, user the SERIAL 1 mouse command (this will attach it to the COM1 port), or edit the [serial] section of the configuration file. By default, DOSBox Staging tries to determine what kind of mouse the game or application expects.
With serial mouse emulation, Windows 1.01 is finally usable!
"},{"location":"downloads/release-notes/0.79.0/#windows-31-seamless-mouse-integration","title":"Windows 3.1 seamless mouse integration","text":"It is now possible to have a seamless mouse integration using one of the following 3rd party VMware-compatible Windows 3.1 mouse drivers:
VBADOS by javispedro \u2014 this one requires a corresponding DOS mouse driver to be started; this driver also provides seamless mouse integration for a real DOS if booted inside DOSBox Staging
vmwmouse by NattyNarwhal \u2014 does not require any specific DOS driver and has experimental support for mouse wheel, but current version 0.1 has stability problems
For now, only the mouse is supported (no VMware directory sharing, etc.), only using VMware protocol (no VirtualBox-only drivers). Windows 9x VMware mouse driver is not supported.
"},{"location":"downloads/release-notes/0.79.0/#joystick-calibration-hotkeys","title":"Joystick calibration hotkeys","text":"Most DOS games that offer analog joystick control include some form of calibration. However, some games have poor or limited calibration resulting in the joystick\u2019s position drifting or being offset, despite calibration attempts.
To compensate for these rare cases, DOSBox Staging lets you adjust the joystick\u2019s X and Y position parameters in real time by enabling the use_joy_calibration_hotkeys setting in the [joystick] config section.
Once activated, you can tap Ctrl + arrow-keys or Alt + arrow-keys to adjust either the joystick\u2019s scalar multiplier or absolute offset position, respectively. These let you \u201ccounterbalance\u201d calibration issues in real time.
Each tap of the hotkeys will log the calibration values for the given axis. For example:
x_calibration = 0.576211,0.02\ny_calibration = 0.5474,-0.005\nOnce you\u2019ve found the optimal settings for a game, the logged calibration values can be placed in the game\u2019s local config file (so the setting are only active for the affected game). Using the above as an example:
[joystick]\nuse_joy_calibration_hotkeys = false\njoy_x_calibration = 0.576211,0.02\njoy_y_calibration = 0.5474,-0.005\nNote that you can disable the calibration hotkeys once you\u2019ve found settings that work for a problematic game.
Here\u2019s a video showing how the calibration hotkeys \u201cpull\u201d the joystick in various directions:
Your browser does not support thevideo element. The new joystick calibration feature in action
"},{"location":"downloads/release-notes/0.79.0/#general-improvements","title":"General improvements","text":""},{"location":"downloads/release-notes/0.79.0/#command-line-setting-of-configuration-options","title":"Command-line setting of configuration options","text":"Some people may want to temporarily run DOSBox Staging with specified config option(s), and in this new version you can do this with the new -set command-line option when launching DOSBox Staging, instead of having to modify the configuration file before you start DOSBox Staging.
For example, the user can temporarily run DOSBox Staging with the EMS memory disabled with the command line dosbox -set ems=false, overriding the setting in the configuration file.
The -set option can be specified multiple times for different config options, similar to the -c option which can be used multiple times to run multiple commands after DOSBox Staging starts.
Previously, DOSBox Staging was only available as portable zip packages for Windows users, but this has changed in this new version\u2014as a Windows user you can now install DOSBox Staging more easily with the installer, which is especially recommended for new and first-time users. When the installer is used, the installation process will be automated while allowing you to change certain things like the installation folder, and you will be able to launch DOSBox Staging as soon as the installation ends. Shell context menus can also be automatically added for a faster launch of DOSBox Staging from Windows Explorer.
Windows installer welome page
Icons after installation
"},{"location":"downloads/release-notes/0.79.0/#configurable-modem-connect-speeds","title":"Configurable modem connect speeds","text":"The soft-modem\u2019s reported connect speed can be customised using the serial port\u2019s baudrate setting. for example:
serial1 = modem baudrate:2400\nAlthough this doesn\u2019t change the underlying baud rate, it can help satisfy old modem software if it\u2019s unable to handle (or parse) the larger connect values.
"},{"location":"downloads/release-notes/0.79.0/#handling-options-for-memory-faults-in-buggy-games","title":"Handling options for memory faults in buggy games","text":"Extremely rare programming bugs \ud83d\ude09 in some DOS games (and programs) may cause them to accidentally write data beyond their allocated memory region, similar to \u201cpainting outside the lines\u201d. DOSBox is great at catching these instances: it flags the corruption and quits, preventing the program from barreling on and possibly doing more harm such as writing corrupt save games, documents, and so on.
DOSBox Staging defaults to this same behaviour, but adds the [dosbox] mcb_fault_strategy config setting:
deny Report and quit as soon as a fault is detected (default) Game terminates, no risk of subsequent file corruption repair Report and repair up to 100 sequential faults Game continues, but may still be unstable if its developers expected the corruption report Report the corruption and carry on Game continues, but risks further instability and file corruption allow Carry on without reporting Game continues, but risks further instability and file corruption Only consider this if your game is prone to crashing with MCB chain corruption errors reported in the console log.
"},{"location":"downloads/release-notes/0.79.0/#developer-related-improvements","title":"Developer-related improvements","text":""},{"location":"downloads/release-notes/0.79.0/#self-documenting-bit-twiddling-with-bit_view","title":"Self-documenting bit twiddling with bit_view","text":"We\u2019ve implemented a bit_view C++ class using constant expressions to access a subset of a data-field\u2019s bits, allowing them to be read, written, assigned, flipped, cleared, and tested, without the need to for the usual twiddling operations.
Constructing a bit_view is similar to a C bitfield, however unlike C bitfields, bit_views are free from undefined behaviour and have been proven using GCC\u2019s and Clang\u2019s undefined behaviour sanitisers.
There\u2019s more detail and some code examples here.
"},{"location":"downloads/release-notes/0.79.0/#memory-block-and-type-size-simplification","title":"Memory block and type size simplification","text":"The emulated main memory (up to 64 MiB) and the video card\u2019s memory (to up 8 MiB) are both now allocated statically to reduce pressure on heap storage (#1714).
More progress has been made in reducing the use of large variables type-sizes down to purpose-fit sizes per the DOS/hardware specification (typically 8 or 16-bit) (#1721).
"},{"location":"downloads/release-notes/0.79.0/#tracy-profiler-integration","title":"Tracy profiler integration","text":"The Tracy event profiler has been integrated into the build system and basic hooks are in place to log frames and tics. These are only active (and not compiled in) unless Tracy is enabled.
Here\u2019s what it looks like:
Tracy runtime-profiling DOSBox Staging
It can be enabled at build-time with -Dtracy=true. Learn more about it, and how to build the server-side component here: #1749
The MSYS2-based workflow has been brought in line with current best practices, which dramatically improved its build time and lead to us now using it to generate the default Windows release binaries.
"},{"location":"downloads/release-notes/0.79.0/#release-package-shell-script","title":"Release-package shell script","text":"Release packages are now generated using a cross-platform POSIX-compliant shell script. With this logic moved into a script, developers can now easily test the creation of a release package locally, which was previously impossible as that logic only lived in a GitHub-syntax YAML.
"},{"location":"downloads/release-notes/0.79.0/#static-analysis","title":"Static analysis","text":"The team continues to fix and address static analysis issues as flagged by various analysers. Here are our Coverity Scan metrics to-date:
"},{"location":"downloads/release-notes/0.79.0/#translation-status","title":"Translation status","text":"The 0.79.0 configuration file is also in UTF-8 format for the German, Italian, and Polish languages under the package\u2019s resources/translated-0.79-conf-files directory.
The messaging system now supports self-documenting markup syntax, which is much easier to read and maintain compared to the previous ANSI escape sequences.
Old escape-code style New markup styleEscribiendo ^[[34;1mdir^[[0m all\ufffd mostrar\ufffd su contenido. Digita [color=blue]dir[reset] per visualizzarne il contenuto."},{"location":"downloads/release-notes/0.79.0/#notable-fixes","title":"Notable fixes","text":"Fixed Ultima Underworld issues with gaming (high polling rate) mice (#1722)
Fixed lockups and input issues with the debugger on macOS and Linux. Note that for those using the debugger on Linux, we recommend building it with SDL 2.0.18, because some input/interaction bugs exist when using newer SDL versions.
Fixed colours becoming very dim on newer Intel integrated GPUs due to Intel\u2019s OpenGL drivers not properly handling the sRGB linear colour space.
Fixed a memory-read race condition present during the splash-image display, which also reduced start-up time by around 200 ms.
Fixed display of the low-resolution halfline VESA 2.0 mode used by Extreme Assault through the addition of a new vesa_mode config setting value, named halfline.
Named the macOS application \u201cDOSBox Staging.app\u201d per the macOS per Human Interface Guidelines.
Fixed a usability trap door when opening the mapper without mouse support: in these cases, the user was unable to exit the mapper. The mapper now only opens when mouse support is enabled.
John Novak for all the audio enhancements, mixer cleanup, shader improvements, and code reviews
FeralChild64 for the mouse overhaul, code page and layout cleanup and improvements, and code reviews
Wengier for the shell improvements, mount and CLI additions, and Windows installer
Antti Peltola for providing historic resources, documentation help, and project support
shermp for the MSYS2 cleanup, cross-platform packaging script and CI cleanup, ANSI markup system, and code reviews
Kirk Klobe for the debugger fixes, Tracy integration, and paging and memory system refinements
GranMinigun for the HiDPI additions, video chain fixes, and Russian translations
nemo93 for testing 400+ games on the Raspberry Pi
Kappa971 for the Italian and configuration file translations, and leading the translation effort
Burrito78 for the German translation
Thank you to our financial contributors who allow us to purchase hardware, licenses, and other non-trivial expenses to keep the team and project going.
To support our work, donate to our GitHub Sponsors or Open Collective.
"},{"location":"downloads/release-notes/0.79.0/#thank-you","title":"Thank you","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"downloads/release-notes/0.79.1/","title":"0.79.1 release notes","text":"Release date: 2022-09-30
"},{"location":"downloads/release-notes/0.79.1/#summary","title":"Summary","text":"We recommend repository maintainers move to 0.79.1, which should be much easier to package. Details in the Packaging fixes section below.
We recommend users of our zip, dmg, and Windows installer packages upgrade from 0.79.0 to fix some audio and usability bugs.
This maintenance release was made possible by everyone who tried 0.79.0, submitted bugs and pull requests, and tested the updates: thank you!
"},{"location":"downloads/release-notes/0.79.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
Fixed a CD-DA playback regression in Might and Magic 6 when using multi-image mounts (kcgen)
Allowed the Esc key and window-close events to exit from the paused state (Wengier)
Fixed a bug that prevented automounted drives from being used by [autoexec] commands (kcgen)
Fixed an audio filter reset regression flagged in Blues Brothers: Jukebox Adventure (kcgen)
Fixed a 16-bit stereo DMA regression detected when using the Sound Blaster\u2019s modern filter (kcgen)
video element. 303 by Acme \u2014 30fps encoding, 120k cycles, and SB16 using the modern filter
Improved ability to pipe between applications by using Y: as a temporary path (Wengier)
Switched to warning-level logging for MIDI configuration issues (Michael Drueing)
Improved the lookup of resources when XDG variables aren\u2019t set correctly (kcgen, Eli Schwartz)
Updated the Dutch language to use the US keyboard layout by default (Wengier)
Included Xbox compatible controller mapperfiles for 180+ games: conf, wiki (nemo93)
Synced Italian translation (Kappa971)
Dropped non-existant KEYB help messages from translation system (Wengier)
Replaced more escape codes with markup tags in the translations (Robert de Rooy)
Moved the mount type descriptions into the translation system (Wengier)
New Keymapper page with examples for those with Xbox controllers (nemo93)
New FAQ answering questions about audio settings, configuration files, video output, and other topics (nemo93)
Notable additions to the UniVBE, Special keys, Getting started, Suggested audio settings, Config examples, AUTOTYPE candidates, and Games with CD-DA, GUS and MIDI audio pages (nemo93)
Adjusted Meson\u2019s FluidSynth dependency spec to match upstream\u2019s packaging (Kirk Klobe)
Switched Meson to use SpeexDSP from the host first and fallback to wrap (kcgen)
Switched Meson to use shared (instead of static) libraries by default (kcgen)
Fixed installation of resources when using meson install (kcgen, Eli Schwartz)
Packagers will get shared libs and installed resources with these standard steps:
meson setup --prefix /writable/install/path build\nmeson install -C build\nThanks to our financial contributors who allow us to purchase hardware, licenses, and other non-trivial expenses to keep the team and project going.
To support our work, donate to our GitHub Sponsors or Open Collective.
We are grateful for all community contributions as well as the original DOSBox project, upon which DOSBox Staging is based.
"},{"location":"downloads/release-notes/0.80.0/","title":"0.80.0 release notes","text":"Release date: 2022-12-21
"},{"location":"downloads/release-notes/0.80.0/#summary","title":"Summary","text":"ReelMagic DOS games are now playable thanks to the efforts of Jon Dennis, Chris Guthrie, and Joseph Whittaker, with testing and feedback from Vogons users Uka, DonutKing, and Vetz. Mouse emulation has been improved and now supports up to six independent mice, enabling split-screen play in games like The Settlers and The Settlers II. More settings, including video, audio, and mixer effects, can now be changed on the fly. Following macOS, high DPI support on multi-display setups now comes to Windows. A new --working-dir command line flag allows DOSBox Staging to launch from a specific working directory. Repo packagers should note that sdl2_image is now a dependency.
Read on for all the details!
"},{"location":"downloads/release-notes/0.80.0/#how-to-upgrade","title":"How to upgrade","text":"Get started by downloading the latest version and updating your configuration file:
"},{"location":"downloads/release-notes/0.80.0/#downloads","title":"Downloads","text":"Z:\\> prompt, run config -wc to write the new configuration file.Note
Existing settings will be retained, but extraneous comments will be dropped.
Starting with version 0.80, the configuration file is written in the language in which DOSBox Staging was started.
To write an English configuration file, launch with the -lang en command-line flag (to start DOSBox Staging in English) and then (re-)write your configuration file.
DOS ReelMagic games are now playable thanks to Jon Dennis\u2019s patch with help from Chris Guthrie and Joseph Whittaker.
See the [reelmagic] section in your configuration file to enable this. We suggest only enabling ReelMagic emulation on an as-needed basis.
video element. Return to Zork (1995) \u2014 introduction
Jon plans to add DMA support (primarily used by the ReelMagic Windows 3.1x driver and games) when time permits, but most ReelMagic games for DOS are already fully functional and playable.
"},{"location":"downloads/release-notes/0.80.0/#mouse-improvements","title":"Mouse improvements","text":""},{"location":"downloads/release-notes/0.80.0/#dedicated-configuration-section","title":"Dedicated configuration section","text":"The mouse configuration has been moved to its own section and additional options have been added. A tool called mousectl is available on Z: for more detailed per-interface mouse configuration. \u00a0
Multiple physical mice can now be mapped to specific emulated mouse interfaces, enabling two-player split-screen gaming (The Settlers and The Settlers II) using two USB mice on a single computer.
See the wiki article for more details.
Your browser does not support thevideo element. The Settlers II (1996) \u2014 showcasing dual-mouse gaming in action
"},{"location":"downloads/release-notes/0.80.0/#improved-support-for-third-party-int33-windows-mouse-drivers","title":"Improved support for third-party INT33 Windows mouse drivers","text":"javispedro\u2019s INT33 mouse driver for Windows 3.1x is fully supported and no longer requires the use of the separate DOS driver, except when booting from a disk image. The driver also resolves compatibility issues with seamless mouse integration and adds mouse wheel support.
See the wiki article for more details.
"},{"location":"downloads/release-notes/0.80.0/#mouse-related-help-in-the-title-bar","title":"Mouse-related help in the title bar","text":"The title bar now displays some short help about the mouse, such as how it can be captured or released.
"},{"location":"downloads/release-notes/0.80.0/#high-dpi-on-windows","title":"High DPI on Windows","text":"Following macOS, high DPI support now comes to Windows: the DOSBox window should scale nicely along other programs, and retain correct dimensions when moving between monitors with different scaling factors set.
Note
This feature is currently experimental! If you notice any weird behaviour, please report it!
"},{"location":"downloads/release-notes/0.80.0/#ability-to-use-local-configs-via-finder-on-macos","title":"Ability to use local configs via Finder on macOS","text":"A new --working-dir <path> command line parameter has been introduced to make it possible to launch DOSBox Staging using local configs from the Finder on macOS. Previously, you had to use DOSBox from the command line to achieve this. \u00a0
Follow the steps indicated in the DMG package, as shown:
Simply copy the included Start DOSBox Staging.command to any folder that contains a local dosbox.conf and then open it (Start DOSBox Staging.command) in Finder. DOSBox Staging will act as if started from that folder and will pick up the local config. \u00a0
Note
You might be asked to give DOSBox Staging access to the containing folder upon the first launch\u2014just click OK if that dialog comes up.
"},{"location":"downloads/release-notes/0.80.0/#general-improvements","title":"General improvements","text":""},{"location":"downloads/release-notes/0.80.0/#morecom-command","title":"more.com command","text":"The more command is now internally implemented (should be more user-friendly than the original DOS one), and its engine is used for displaying help messages longer than one screen.
video element. more.com \u2014 Better and Improved\u2122
"},{"location":"downloads/release-notes/0.80.0/#on-the-fly-changes","title":"On-the-fly changes","text":"Several settings can be safely adjusted at runtime, including the output video settings, resolution, OpenGL shaders, audio devices, and mixer settings.
Your browser does not support thevideo element. Reconfiguring audio on-the-fly \u2014 changing sound cards in a PC has never been easier!
"},{"location":"downloads/release-notes/0.80.0/#post-rendered-screenshots","title":"Post-rendered screenshots","text":"DOSBox has long provided the Ctrl+F5 hotkey to capture the emulated video card\u2019s image prior to rendering.
DOSBox Staging 0.80 now pairs this with Alt+F5 (or Option+F5 on macOS) to capture the as-seen (post-rendered) image.
"},{"location":"downloads/release-notes/0.80.0/#more-bundled-opengl-shaders","title":"More bundled OpenGL shaders","text":"The balance of usable shaders from Tyrells\u2019 CRT shader collection, as well as GranMinigun\u2019s interpolating Catmull\u2013Rom spline shader have been added.
Launch DOSBox Staging with the --list-glshaders command-line argument to list the available OpenGL shaders. For example:
List of available GLSL shaders\n------------------------------\n\nPath '/usr/src/dosbox-staging/build/resources/glshaders' has:\n |- crt/aperture\n |- crt/caligari\n |- crt/easymode\n |- crt/easymode.tweaked\n |- crt/fakelottes\n |- crt/fakelottes.tweaked\n |- crt/geom\n |- crt/geom.tweaked\n |- crt/hyllian-updated\n |- crt/hyllian\n |- crt/lottes-fast\n |- crt/lottes-fast.subtle+gain\n |- crt/lottes\n |- crt/lottes.tweaked\n |- crt/mattias\n |- crt/pi-vertical\n |- crt/pi\n |- crt/yee64\n |- crt/yeetron\n |- crt/zfast\n |- crt/zfast-composite\n |- interpolation/catmull-rom\n |- interpolation/sharp\n |- scaler/advinterp2x\n |- scaler/advinterp3x\n |- scaler/advmame2x\n |- scaler/advmame3x\n |- scaler/rgb2x\n |- scaler/rgb3x\n |- scaler/scan2x\n |- scaler/scan3x\n |- scaler/tv2x\n `- scaler/tv3x\n--working-dir command line option (#2122)sdd::unique_ptr to manage the video memory (#2116)The mixer\u2019s effects (reverb, chorus, and crossfeed) can now be turned on and off at runtime via the mixer command.
FluidSynth\u2019s specific reverb and chorus configuration settings are now applied and will replace the default values that were previously always applied.
The modem\u2019s call now has a warm-up period where it will discard data. This fixes a bug noted in Duke Nukem 3D where it would fail its initial handshake on the first try.
update-sources.sh script to UTF-8 locale (#2011)config -wc to write UTF-8 file (#1991)mixer.com CLI handling of volume and effect arguments (#2021)bit_views to 8-bit registers to avoid byte-order assumption (#1999)std::filesystem calls (#1995)The title bar is now translatable.
The Brazilian ABNT2 slash and question mark keys are now handled.
Translations are now stored in UTF-8 and converted to the selected DOS codepage, dropping accents if needed, sometimes even performing crude transliterations (for Latin, Greek, and Cyrillic alphabets DOSBox shouldn\u2019t display garbled messages anymore regardless which codepage is selected). This is especially important for languages where more than one incompatible encoding was used in the DOS era. All FreeDOS codepages are supported. Note that only DOSBox Staging\u2019s own messages benefit from this feature.
update-sources.sh script to UTF-8 locale (#2011)tandy and ibm5153 cga_colors config descriptions (#2074)MSG_Add from code page 437 to UTF-8 (#1984)MSG_Add from code page 437 to UTF-8 (#1984)The following wiki articles have been updated:
The new Dual Mouse Gaming page documents how to set up dual-mouse working in The Settlers and The Settlers II.
The Windows 3.1x page was updated with notes on how to set up the improved mouse driver, and more sound drivers.
The new Windows 3.0 page documents how to set up Windows 3.0\u2019s video, sound, MIDI, mouse, and how to print to files.
The new Serial Ports page documents all of the serial port settings.
The Sound Cards page was overhauled with descriptions and configuration help for all supported sound devices.
The Tips & Tricks page was updated with how to generate DOSBox mountable CD-DA content from public domain or Creative Commons licensed YouTube chapters and playlists.
The following commit authors, sponsors, supporters, and backers all invested their time or funds into the 0.80 release effort. Thank you!
Contributors are listed in alphabetic order.
"},{"location":"downloads/release-notes/0.80.0/#080-commit-authors","title":"0.80 commit authors","text":"Sponsors who donated more than 100 USD per month to the project:
Backers who donated more than 5 USD per month to the project:
Thank you for considering supporting our work through a donation on GitHub Sponsors or Open Collective. Your contribution helps us purchase the necessary hardware and licenses to keep our project going.
"},{"location":"downloads/release-notes/0.80.0/#thank-you","title":"Thank you","text":"We are grateful for all community contributions as well as the original DOSBox project, upon which DOSBox Staging is based.
"},{"location":"downloads/release-notes/0.80.1/","title":"0.80.1 release notes","text":"Release date: 2023-01-06
"},{"location":"downloads/release-notes/0.80.1/#summary","title":"Summary","text":"This maintenance release fixes minor issues with the mouse defaults, modem and Ethernet connection handling, and Meson dependencies.
We are also happy to report that the high DPI improvements in the previous 0.80.0 release have been verified on Windows, meaning that high DPI support is now functional on all platforms. Thanks to GranMinigun for this addition!
This maintenance release was made possible by everyone who tried 0.80.0, submitted bugs and pull requests, and tested the updates: thank you!
"},{"location":"downloads/release-notes/0.80.1/#how-to-upgrade","title":"How to upgrade","text":"Get started by downloading the latest version and updating your configuration file:
"},{"location":"downloads/release-notes/0.80.1/#downloads","title":"Downloads","text":"Z:\\> prompt, run config -wc to write the new configuration file.Note
The mouse will now be captured only after the first click inside the window. For users without a windowing environment, the previous capture-on-start behavior will remain unchanged.
The captured mouse will now be centered in the window upon release.
The softmodem now includes a brief warm-up period where it will drop initial unreliable data, similar to hardware modems. This allows Duke Nukem 3D to establish its data connection on the first attempt.
A potential slow memory leak related to closed Ethernet connections has been fixed.
A bug that caused the C: mount to become unlistable after launching DOSBox Staging with a command-line mount while using MORE.COM has been fixed.
The xinput2 library, an optional dependency of ManyMouse, can now be set via the Meson options. For more information, see meson_options.txt.
When compiling on ARM platforms, the SpeexDSP wrap will now correctly check if the host supports NEON instructions, and use them if available.
This maintenance release includes updates to the Dutch, Italian, and Polish translations.
Full PR list of translation improvementsThe following commit authors, sponsors, supporters, and backers invested their time or funds into this maintenance release. Thank you!
"},{"location":"downloads/release-notes/0.80.1/#commit-authors","title":"Commit authors","text":"In alphabetic order:
Sponsors who donated 100+ USD per month to the project:
Backers who donated 5+ USD per month to the project:
Thank you for considering supporting our work through a donation on GitHub Sponsors or Open Collective. Your contribution helps us purchase hardware and cover ongoing expenses to keep the project going.
"},{"location":"downloads/release-notes/0.80.1/#thank-you","title":"Thank you","text":"We are grateful for all community contributions as well as the original DOSBox project, upon which DOSBox Staging is based.
"},{"location":"get-involved/","title":"Get involved","text":""},{"location":"get-involved/#github-repository","title":"GitHub repository","text":"The DOSBox Staging project is hosted on GitHub. Here you\u2019ll find the full source code and various project related documentation. Send us patches if you improve something! \ud83d\ude04
We are grateful for all community contributions as well as the original DOSBox project, upon which DOSBox Staging is based.
"},{"location":"get-involved/#report-an-issue","title":"Report an issue","text":"While we do our best to ensure the quality of our releases, every software has bugs. If you think you\u2019ve spotted one, please report it in our issue tracker (requires a GitHub account).
Alternatively, join our Discord channel to discuss the problem with one of our friendly staff members.
"},{"location":"get-involved/#wiki","title":"Wiki","text":"The DOSBox Staging Wiki hosted on GitHub contains lots of useful tricks & tips, how-to\u2019s, lists, and guides that can help newcomers and more experienced users alike.
We very much recommend perusing it, and if you\u2019ve spotted an error or have something to share, please feel free to contribute to it.
"},{"location":"get-involved/#discord","title":"Discord","text":"Join the team on Discord for a good chat over a virtual beverage of your choice!
We only ask you to adhere to our Code of Conduct so every participant can enjoy the discussion.
"},{"location":"get-involved/#make-a-donation","title":"Make a donation","text":"DOSBox Staging is an entirely volunteer-based effort\u2014we\u2019re not getting paid for our activities. However, we have some running expenses and need to invest in hardware, licenses, and other non-trivial expenses to keep the team and the project going.
If you wish to make a financial contribution to support us, you can do so at our GitHub Sponsors or Open Collective pages.
We are grateful for all donations, no matter how big or small!
"},{"location":"get-involved/code-of-conduct/","title":"Code of conduct","text":"In order to foster a welcoming, positive, and rewarding experience, we as community members pledge to uphold this code of conduct.
Isn\u2019t decent behavior already expected? We want to bring our best to each other as peers, and explicitly documenting our expectations lets us set a high bar for ourselves.
"},{"location":"get-involved/code-of-conduct/#be-excellent-to-each-other","title":"Be excellent to each other","text":"\u201cExcellent\u201d means we:
are wholly inclusive to existing members and newcomers looking to learn or participate. Some may raise questions that have been addressed before. Kindly point them to existing discussions. Everyone was new to a project once.
respect your abilities, interests, and personal differences. Our different talents documenting, testing, coding, reviewing, reporting, and/or evangelizing are all valuable to the project.
make concise and actionable points to respect your time as a volunteer. We respect each other\u2019s time by keeping the signal-to-noise ratio high, staying on-topic, and being a good house guest: every visit we strive to leave the place in better shape than when we arrived.
are kind and assume positive intent, even when we disagree while working towards consensus and achieving the project\u2019s technical goals.
educate and illuminate others with something we know more about. We were all beginners once and can teach and learn through feedback and sharing.
are open to feedback from others, be it technical points, interpersonal tips, or language/wording suggestions.
accept responsibility by apologizing to those affected by our mistakes and graciously accept apologies knowing that mistakes are part of the process.
use words carefully because we may not all understand irony or negative sarcasm. We communicate plainly, and we justify our positions objectively and explicitly.
leave with class, without drama or bitterness, when resigning for any reason. We champion your rights under the terms of the GPL to fork the code and create a new project\u2014just as we stand on the shoulders of those who gave us the right to create this project.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team (see below). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
The project team can be contacted via Discord.
"},{"location":"getting-started/beneath-a-steel-sky/","title":"Beneath a Steel Sky","text":"The next game we\u2019re going to set up is Beneath a Steel Sky, a cyberpunk sci-fi adventure game from 1994. It\u2019s one of the standout timeless classics of the adventure genre, and best of all, Revolution Software released the game as freeware in 2003 (see their accompanying notes here).
"},{"location":"getting-started/beneath-a-steel-sky/#launching-games-more-easily","title":"Launching games more easily","text":"Before we delve into the setup instructions, a few words on launching our growing collection of games more easily. Having to go to its folder whenever we want to launch a game gets old really fast. Here\u2019s how we can skip this step:
WindowsCreate a batch file called Start DOSBox Staging.bat with the following content:
C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox.exe\nThat\u2019s the default installation path chosen by the installer. %USERNAME% is your Windows user name; of course, if you have installed DOSBox Staging to a different folder, you should adjust the path accordingly.
Copy this batch file into your individual game folders and rename them to the names of the games, e.g., Prince of Persia.bat in this example.
Right-click on the batch file icon and select Send to \u2192 Desktop (create shortcut) in the context menu.
Now you can double-click on the new Prince of Persia.bat - Shortcut icon on your desktop to start the game (of course, you can rename the icon to Prince of Persia or whatever you like; this won\u2019t change the name of the batch file it references).
You can rename the Start DOSBox Staging icons in the individual game folders to the names of the games, then you can use Spotlight Search to start a game.
For example, rename Start DOSBox Staging in the Prince of Persia folder to Prince of Persia. Start Spotlight Search by pressing Cmd+Space, then type in \u201cPrince\u201d. The Prince of Persia icon will show up in the search results\u2014you can simply press Enter on it to launch the game.
The easiest way is to create a shell script with the following content (of course, modify the path passed in as the argument of the --working-dir option so it points to your game directory):
#!/bin/bash\ndosbox --working-dir \"~/Documents/DOS Games/Prince of Persia\"\nThen create an icon on your desktop that launches this script, or start it however you like.
"},{"location":"getting-started/beneath-a-steel-sky/#mounting-a-cd-rom-image","title":"Mounting a CD-ROM image","text":"We\u2019re going to set up the liberated \u201ctalkie\u201d CD-ROM version of the game that has full voice-acting. You know the drill; create a new Beneath a Steel Sky subfolder inside your DOS Games folder and the usual drives/c subfolder within it. Then download the ISO CD-ROM image and put it into a cd subfolder inside your Beneath a Steel Sky game folder. The name of the cd subfolder has no special significance; you could put the .iso image anywhere, but it\u2019s good to get into the habit of organising your game files systematically (e.g., you could create a Manual of Extras subfolder too and put the scanned manuals and all other extra files there). It\u2019s a good idea to rename Beneath a Steel Sky (1995)(Virgin).iso to cdrom1.iso; our game folder has the full name of the game anyway.
Speaking of manuals, make sure to get the scan of the Security Manual and the comic book that was included in the boxed version of the game.
For the visually inclined, this is the structure we\u2019ll end up with:
We need to mount the CD image to be able to use it. Our C drive is the hard drive, so we\u2019ll mount the CD-ROM image as the next letter D by convention. This is equivalent to having a CD-ROM drive in our emulated computer assigned to the drive letter D and inserting the game CD into it.
Mounting an image file, such as a floppy or CD-ROM image, is accomplished with the imgmount command. It is pretty simple to use: the first argument is the drive letter (d), the second the path to the CD-ROM image (cd/cdrom1.iso), and the third the type of the image file (-t iso).
So this is what we need to put into our config:
[autoexec]\nimgmount d cd/cdrom1.iso -t iso\nWarning
If you\u2019ve kept the original name of the ISO, you\u2019ll need to enclose it in double quotes because it contains spaces:
imgmount d \"cd/Beneath a Steel Sky (1995)(Virgin).iso\" -t iso\nTip
By always putting your CD-ROM images into the cd subfolder within your game folder and renaming the ISO files to cdrom1.iso, cdrom2.iso, and so on, it\u2019s easier to reuse the mount commands between configs.
You can always run imgmount /? if you need a little reminder on how to use it (although the full list of options can be a little overwhelming).
This is what you should see in the DOSBox Staging window after startup if everything is set up correctly:
Local directory drives/c/ mounted as C drive\nZ:\\>imgmount d cd/cdrom1.iso -t iso\nMSCDEX installed.\nISO image cd/cdrom1.iso mounted as D drive\nZ:\\>_\nMSCDEX is the name of the MS-DOS CD-ROM driver, and the next line just informs us that our CD image is mounted as drive D. Time to get down to business then!
"},{"location":"getting-started/beneath-a-steel-sky/#installing-the-game","title":"Installing the game","text":"Most games that come on CD images need to be installed on the hard drive first. Usually, there\u2019s an executable called INSTALL.EXE or SETUP.EXE in the root directory of the CD (the extension could be .COM or .BAT as well).
Switch to the D drive by executing d: then run the dir command to inspect the contents of the CD:
Volume in drive D is BASS\n Directory of D:\\\n\nINSTALL EXE 28,846 06/15/1994 8:56a\nREADME TXT 1,569 09/08/2005 1:34a\nSKY DNR 40,796 07/07/1994 8:40a\nSKY DSK 72,429,382 07/07/1994 8:40a\nSKY EXE 402,622 07/07/1994 7:21a\nSKY RST 53,720 07/07/1994 7:19a\n 6 file(s) 72,956,935 bytes\n 0 dir(s) 0 bytes free\nOkay, so we\u2019ve got two executables with the .EXE extension and one text file. View README.TXT using the more command (run more README.TXT, then keep pressing Space or Enter to go to the next page, or Ctrl+C to quit). It turns out it just contains some legal notice we don\u2019t really care about. INSTALL.EXE is what we\u2019re after, so let\u2019s run that!
We\u2019re greeted by a pretty standard-looking text-mode installer. Either press any key or wait a few seconds to progress to the second screen where you need to select where the game will be installed:
You can navigate the interface with the cursor keys, Esc, Enter, and the mouse. The default C:\\SKY install location is perfectly fine, so just accept it by pressing Enter.
That will take us to the setup screen where we can select the language of the in-game text (the voice-acting is in English only), and the sound card settings:
English is fine, and the game has auto-detected our sound card correctly (Sound Blaster 16\u2014this is the sound card DOSBox emulates by default), so just accept these settings for now. And now, the counterintuitive part: to finish the installation and save the settings, we need to press the Exit Install button, which will take us to the (guess what?) Exit Install dialog:
Here you need to press the Save Setup button to finalise the settings and exit the installer.
As you can see, this is not exactly a masterclass in user interface design, but it does the job. Expect many DOS-era install and setup utilities to be similarly slightly illogical\u2014often it\u2019s not completely obvious what to do, but it\u2019s not too hard to figure it out with some trial and error.
Anyway, after pressing Save Setup the installer will exit and print out the following instructions:
BENEATH A STEEL SKY has been installed to directory:\n\nC:\\SKY\n\nTo run the game type:\n\nC:\nCD \\SKY\nSKY\nOkey-dokey, let\u2019s do as the computer says! It\u2019s the easiest to put the above commands into the [autoexec] section of our config, but let\u2019s comment the last sky command out for now by preceding it with a # character because we don\u2019t want to start the game just yet:
[autexec]\nimgmount d cd/cdrom1.iso -t iso\nc:\ncd \\sky\n#sky\nSo before we run the game, what is this cd \\sky command? Does it have something to do with the cd subfolder where we put out CD-ROM image, perhaps?
No, that\u2019s just a coincidence. The cd command stands for Change Directory; it is used to change the current directory that\u2019s displayed as part of the DOS prompt. So let\u2019s analyse what these lines we put into the [autoexec] section do:
c:\ncd \\sky\nThe first command c: switches to the C drive (remember, the current drive is the special built-in Z drive when DOSBox starts).
Then the second cd \\sky command changes the current directory to the sky directory at the root level of the C drive. cd sky would work as well because the current directory is the root when we switch to the C drive right after startup.
How do you go up one level to the parent directory? With the cd .. command (two dots means \u201cparent directory\u201d, and a single dot means \u201ccurrent directory\u201d).
C:\\SKY>cd ..\nC:\\>_\nHow do you go straight to the root directory? By executing cd \\ (the \\ backslash character means \u201croot directory\u201d).
C:\\SKY>cd \\\nC:\\>_\nYou can also switch to a nested subdirectory with a single cd command, e.g. if you have a directory called one at the root level which contains a subdirectory two, which in turn contains another subdirectory three, you can switch to three from any directory with the cd \\one\\two\\three command. Note this is an imaginary example:
C:\\SKY>cd \\one\\two\\three\nC:\\ONE\\TWO\\THREE>_\nPlay around a bit with the drive and directory switching commands, then when you had enough, uncomment the last sky command in the [autoexec] section (remove the # character).
Warning
You cannot switch to a different drive with the cd command (e.g., cd z: or cd z won\u2019t work); you must use the drive letter followed by a semicolon (z: in this example)!
After starting the game, don\u2019t watch the intro just yet; press Esc to jump straight to the opening scene. There\u2019s music playing, so far so good. Move the cursor over the door on the right side of the screen, and when it turns into a crosshair and the word \u201cDoor\u201d appears next to it, press the left mouse button to inspect it. Lo and behold, you\u2019ll hear our protagonist speak! But it\u2019s barely audible, the music is just too loud.
There are a couple of ways to fix that. You can press F5 to bring up the game\u2019s options dialog where you can lower the music volume, but that would make the total audio output too quiet. Worse yet, the setting doesn\u2019t get saved, so you\u2019d need to do this every single time when starting up the game.
As we\u2019ve learned before, games with Sound Blaster support tend to use the sound card\u2019s OPL synthesiser for the music and its digital audio capabilities for the speech. As the OPL synth and the digital audio have their dedicated mixer channels, their volumes can be adjusted independently of each other.
\u201cWait a minute, what mixer channels now?!\u201d
Okay, so DOSBox has an integrated audio mixer. All emulated sound cards have their own channels in the mixer, and certain \u201ccomposite\u201d audio devices may have multiple channels. The Sound Blaster is such a composite device, so it has two mixer channels: one for the OPL synthesiser, and one for digital audio.
Execute the mixer command in the DOS prompt to view the current state of the mixer:
The first channel is the MASTER channel; this is the summed output of all other channels and it\u2019s always present. Below that is the CDAUDIO channel, the OPL and PCSPEAKER channels (you can guess these two, right?), and finally, the SB channel, which is for the digital audio output of the Sound Blaster.
The Sound Blaster card and PC speaker are enabled by default; that\u2019s the reason for their channels appearing in the mixer, and the CDAUDIO channel is added automatically whenever we mount a CD-ROM image (because it might also contain audio tracks).
To adjust the volume of any mixer channel, we use the mixer command and pass in the channel\u2019s name as the first argument, and the volume expressed as a percentage value as the second. So, to raise the volume of the SB channel to 500%, we need to execute the following:
mixer sb 500\nBy default, the command prints out the new state of the mixer after the adjustment:
You can combine multiple mixer commands in a single line, e.g., in the below example we\u2019ll set the OPL channel\u2019s volume to 50%, and the SB channel\u2019s to 500%:
mixer opl 50 sb 500\nYou can run mixer /? to see the full list of available mixer commands.
Do we need to perform these mixer adjustments manually every single time before running the game? Of course not; we can simply include them in our [autoexec] section. The extra /noshow argument prevents the mixer from displaying its current state; there\u2019s no need for that in our automated startup script.
[autoexec]\nimgmount D \"cd/cdrom1.iso\" -t iso\nc:\ncd sky\nmixer opl 50 sb 500 /noshow\nsky\nDOSBox emulates the Sound Blaster 16 by default. This card can emulate all earlier Sound Blaster models and offers the widest compatibility with DOS games.
But back in the day, there were more Sound Blaster variants and clones you could shake a stick at, many of them having quite different default volume levels. We simply don\u2019t know what particular model the developers used, so it\u2019s worth experimenting with a few different ones. Let\u2019s start with a first-revision Sound Blaster Pro! Add the following snippet to your config:
[sblaster]\nsbtype = sbpro1\nWe want to hear how the Sound Blaster Pro 1 sounds with the default, unaltered volume levels, so make sure to comment out the previously added mixer command in the [autoexec] section by prefixing it with a # character (Shift+3 on the US keyboard layout):
[autoexec]\nimgmount D \"cd/cdrom1.iso\" -t iso\nc:\ncd sky\n#mixer opl 50 sb 500 /noshow\nsky\nIt seems this simple change alone does the trick; now the speech can be heard clearly over the music and the overall volume level is good too! Of course, you can still fine-tune the individual channel volumes with the mixer command if you wish to do so.
Another option we can try is not letting the game mess around with the OPL and digital audio volumes. Starting from the Sound Blaster Pro, programs can alter the volume levels of the Sound Blaster mixer, but we can disallow that by turning off the sbmixer setting. Comment out the sbtype setting because we want to experiment with our default Sound Blaster 16 model, and leave the mixer command in the [autoexec] section commented out too, of course.
[sblaster]\n#sbtype = sbpro1\nsbmixer = off\nWell, that\u2019s another way of fixing the issue; the volume levels are now perfect!
Warning
Not letting a game adjust volume levels can sometimes backfire, e.g., in a game that intelligently lowers the OPL music level whenever speech is playing. But it\u2019s worth a shot; quite a few games benefit from wrestling the control from them and putting the mixer into \u201cmanual mode\u201d.
"},{"location":"getting-started/beneath-a-steel-sky/#adjusting-the-emulated-cpu-speed","title":"Adjusting the emulated CPU speed","text":"Okay, we\u2019re going to do a little experiment next!
In the opening scene, keep pressing the left mouse button repeatedly on the door, about two times per second, to keep starting and then stopping the speech. You\u2019ll very likely hear audio stuttering and dropouts, ranging from subtle to quite severe, depending on how powerful your computer is. Also, if you did watch the intro video (which I told you to skip for now), you\u2019d hear similar random audio stutterings from time to time.
What\u2019s happening here? Well, DOS gaming spans almost two decades, and there were lots of different CPUs in use during that period, all having wildly different performance, or clock speeds. DOSBox doesn\u2019t emulate any specific CPU but a \u201cgeneric\u201d one. So how does it know at what speed to run a particular game then?
It doesn\u2019t.
To explain what\u2019s going on, we\u2019ll need to understand a few technical details. It won\u2019t hurt too much, I promise!
"},{"location":"getting-started/beneath-a-steel-sky/#real-and-protected-mode","title":"Real and protected mode","text":"DOS games can be divided into two categories: older games, and newer games (who would\u2019ve guessed?) Older games released before about 1993 use something called real mode, while newer games released from 1993 onwards use protected mode. The important distinction here is that most CPU-hungry games are protected mode games (e.g., FPS games and flight simulators), while older pre-1993 real mode games generally have much less demanding performance requirements. Figuring out what exact CPU speed a particular game needs is almost impossible at the emulator level, but detecting whether a game uses real or protected mode is trivial. Therefore, DOSBox does the following automatic speed calibration by default:
For real mode games, it defaults to emulating 3000 CPU instructions per millisecond.
For protected mode games, it emulates as many CPU instructions as it can per millisecond.
The reasoning here is that older games are often sensitive to CPU speed; they might run too fast or misbehave if the CPU is too performant, hence the more conservative setting. Newer, more demanding games, however, benefit from the extra speed advantage and can generally handle faster processors without negative side effects.
While this approach generally gets all games running, manual tweaking of the emulated CPU speed is often required to make any particular game run smoothly. Protected mode games running at the maximum emulable CPU speed are particularly problematic because there might not be enough power left for smooth, glitch-free audio emulation. There\u2019s zero point in emulating a faster CPU than what the game needs as all that extra work could be put to better use\u2014such as smoother audio emulation.
Beyond a Steel Sky is a protected mode game, but how we do know that? Let\u2019s comment out the last sky command in the [autoexec] section to prevent the game from auto-starting, then launch DOSBox Staging in windowed mode. DOSBox itself always starts in real mode, and let\u2019s take a look at the text in the DOSBox window\u2019s title bar! It starts with the following:
DOSBOX - 3000 cycles/ms\nRemember what we learned earlier: in real mode, DOSBox defaults to emulating 3000 CPU instructions, or cycles, per millisecond. The text in the title bar tells us the current cycles value, so indeed, we must be running in real mode now!
Now start the game with the sky command and keep your eyes peeled on the title bar. The text will soon change to the following:
SKY - max 100%\nSKY is the name of the executable that\u2019s running, and what do we see after that? max 100%! That\u2019s the tell-tale sign of a protected mode game because, as mentioned, DOSBox tries to emulate the fastest CPU it can in protected mode.
And that\u2019s the crux of the problem\u2014there\u2019s not enough horsepower left to emulate the time-critical audio output without stuttering and glitches. The solution is kind of obvious: instead of letting DOSBox run amok with the CPU emulation, we\u2019ll restrict it to a reasonable speed.
We do that by specifying the number of CPU instructions, or cycles, to emulate per millisecond with the following config snippet:
[cpu]\ncycles = 12000\nRestart DOSBox Staging and do the \u201cdoor test\u201d again. All the audio glitches are now gone! Well done, time for a beer (or your beverage of choice)!
Real and protected mode
In very simple terms, real mode is a programming model that uses the legacy 16-bit mode of an Intel 386 or later CPU, while protected mode takes full advantage of its capabilities and runs in 32-bit mode. Protected mode is the real deal, but it couldn\u2019t be universally utilised until 386 or better CPUs had gained widespread adoption. That happened around the year 1993; games released from thereon use protected mode almost exclusively.
You can easily spot protected mode games by the presence of so-called DOS extenders in their main game directories. DOS4GW.EXE, PMODEW.EXE, and CWSDPMI.EXE were the most popular ones.
But you don\u2019t need to worry about all that detail as DOSBox will indicate with 100% accuracy whether a game runs in real or protected mode. Just set cycles to auto, then watch the title bar of the DOSBox Staging window while running the game.
Ok, so why 12\u2009000 and not any other number? The game\u2019s manual states that a 386 or better processor is required. Indeed, the game works fine at 6000 cycles which approximates a 386DX CPU running at 33 MHz, but the loading times are a bit on the slow side. Setting cycles to 12\u2009000\u2014which roughly corresponds to a 486DX2/66 with \u201cturbo mode\u201d off, running at 33 MHz\u2014speeds up the loading considerably while not causing any negative side effects. This is not surprising as the DX2/66 was one of the most popular CPUs in the 1990s for gaming. This is what Wikipedia says about it:
The i486DX2-66 was a very popular processor for video game enthusiasts in the early to mid-90s. Often coupled with 4 to 8 MB of RAM and a VLB video card, this CPU was capable of playing virtually every game title available for years after its release, right up to the end of the MS-DOS game era, making it a \u201csweet spot\u201d in terms of CPU performance and longevity.
The following table gives you reasonable rough cycles values for the most popular processors:
Emulated CPU MHz MIPS Approx. cycles 8088 4.77 ~0.3 300 286 8 ~0.7 700 286 12 ~1.5 1500 386SX 20 ~3 3000 386DX 33 ~6 6000 486DX 33 ~12 12\u2009000 486DX2 66 ~25 25\u2009000 Intel Pentium 90 ~50 50\u2009000 Intel Pentium MMX 166 ~100 100\u2009000 Intel Pentium II 300 ~200 200\u2009000Always treat these values only as starting points; as explained previously, accurately emulating the speed of any given processor is not possible due to the \u201cabstract\u201d nature of DOSBox\u2019s CPU emulation approach. But from a practical point of view, this does not matter; you just need to find the optimal cycles value the game works well with.
You can fine-tune the cycles setting while playing the game with the Ctrl+F11 and Ctrl+F12 shortcuts (Cmd+F11 and Cmd+F12 on the Mac); these will increase the cycles value by 10%, or decrease it by 20%, respectively. Once you\u2019ve arrived at a good setting, just update your config according to the cycles value displayed in the DOSBox Staging window\u2019s title bar.
Always try to find the minimum cycles value for each game that gives you an adequate performance to conserve host CPU power and reduce the likelihood of audio glitches\u2014overdoing it only makes things worse. Finally, here\u2019s a list of CPU speed sensitive games that should give you further tips and pointers.
"},{"location":"getting-started/beneath-a-steel-sky/#setting-up-roland-mt-32-sound","title":"Setting up Roland MT-32 sound","text":""},{"location":"getting-started/beneath-a-steel-sky/#installing-the-mt-32-roms","title":"Installing the MT-32 ROMs","text":"You might have noticed the game offers a sound option called \u201cRoland\u201d in its setup utility. What this refers to is the Roland MT-32 family of MIDI sound modules. These were external devices you could connect to your PC that offered far more realistic and higher-quality music than any Sound Blaster or AdLib sound cards were capable of. They were the Cadillacs of DOS gaming audio for a while, and they still sound pretty good even by today\u2019s standards.
DOSBox Staging can emulate all common variants of the MT-32 family, but it requires ROM dumps of the original hardware devices to do so. So first we need to download these ROMs from here as a ZIP package, then copy the contents of the archive into our designated MT\u201132 ROM folder:
WindowsC:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\mt32-roms\\ macOS ~/Library/Preferences/DOSBox/mt32-roms/ Linux ~/.config/dosbox/mt32-roms/ If the above download link doesn\u2019t work, search for \u201cmt32 roms mame\u201d and \u201ccm32l roms mame\u201d in your favourite search engine and you\u2019ll figure out the rest\u2026
After you\u2019ve copied the ROM files into the appropriate location for your platform, start up DOSBox Staging again and run the mixer /listmidi command. This will verify your MT-32 ROM files and print a y character below the MT-32 ROM versions that have been successfully detected. The green y character indicates the currently selected MT-32 version. You should get an output similar to this:
As you might have guessed already, you can tell DOSBox Staging to emulate an MT-32 model of a specific revision; you can read about that on our wiki. But in practice, these two models will cover 99% of your gaming needs:
cm32l Unless a specific MT-32 model is requested, DOSBox Staging emulates the Roland CM-32L by default which gives you the best overall compatibility. This is a 2nd generation MT-32 with 32 additional sound effects that many games make good use of. Certain studios, such as LucasArts, tended to favour the CM-32L, so their games sound a little better on this module. mt32_old Certain older games, most notably the early Sierra adventure catalogue, absolutely need a 1st generation MT-32; they will refuse to work correctly on any other model. For those games, use mt32_old. To enable MT-32 emulation and specify the model you wish to use, insert the following into your config:
[midi]\nmididevice = mt32\n[mt32]\nmodel = cm32l\nHow do you figure out which MT-32 model to use for a particular game? Well, you can\u2019t do that easily without a lot of research and trial and error, but thanks to the tireless work of certain prestigious individuals, you can simply refer to the list of MT-32-compatible computer games that tells you the correct model to use for most well-known games.
Let\u2019s consult the list and see what it says about Beneath a Steel Sky!
Requires CM-series/LAPC-I for proper MT-32 output. Buffer overflows on MT-32 \u2018old\u2019. Combined MT-32/SB output only possible using ScummVM
Well, the list knows best, so we\u2019ll use the CM-32L for our game (as we\u2019ve done in the above config example).
To appreciate the difference, you can try running the game with the mt32_old model after you\u2019ve had it successfully set up for the cm32l. You\u2019ll find the sound effects in the opening scene sound a lot better on the CM-32L.
So now DOSBox Staging emulates the CM-32L, but we also need to set up the game for \u201cRoland sound\u201d. (They could\u2019ve been a bit more precise and told us the game works best with the CM-32L, couldn\u2019t they? It\u2019s not even mentioned in the manual!)
Many games have a dedicated setup utility in the same directory where the main game executable resides. This is usually called SETUP.EXE, SETSOUND.EXE, SOUND.EXE, SOUND.BAT, or something similar. There is no standard, every game is different. You\u2019ll need to poke around a bit; a good starting point is to list all executables in the main game folder with the dir *.exe, dir *.com, and dir *.bat commands and attempt running the most promising-looking ones. The manual might also offer some helpful pointers, and so can the odd text file (.TXT extension) in the installation directory or the root directory of the CD (if the game came on a CD-ROM). Certain games have a combined installer and setup utility usually called INSTALL.EXE or SETUP.EXE which can be slightly disorienting for people with modern sensibilities. You\u2019ll get used to it.
This particular game turns things up a notch and does not copy the installer/setup utility into C:\\SKY as one would rightly expect. To reconfigure the game, you need to run INSTALL.EXE from the CD, so from the D drive (I\u2019ve told you\u2014setting up the game itself is part of the adventure!)
So let\u2019s do that. As we\u2019ve already installed the game on our C drive, we\u2019ll need to press Esc instead of Enter in the first Path Selection Window. Not exactly intuitive, but whatever. Now we\u2019re in the Setup Menu screen where we can change the language and configure the sound options. Select Roland sound, then press the Exit Install and Save Setup buttons to save your settings (don\u2019t even get me started\u2026)
Okay, now the moment of truth: start the game with the sky command. If nothing went sideways, we should hear the much-improved, glorious MT-32 soundtrack! Now we\u2019re cooking with gas!
So let\u2019s inspect our favourite door one more time\u2014hey, where did the voice-over go?! Yeah\u2026 you\u2019ve probably glossed over this little detail in the tip from the MT-32 wiki page:
Combined MT-32/SB output only possible using ScummVM
What this means for us ordinary mortals is that in the original game you can either use MT-32 for music and sound effects, and you get no speech; or you can use Sound Blaster for music, sound effects, and speech. MT-32 music and sound effects with speech via the Sound Blaster\u2014that\u2019s a no-go.
The game has just taught us an important life lesson: you can\u2019t have everything, especially not in the world of older DOS games. You\u2019ll have to pick what you value most: better music and only subtitles, or full voice-acting with a slightly worse soundtrack. I\u2019m opting for the latter, and remember, we can always improve the Sound Blaster / AdLib music by adding chorus and reverb. This will get us a little bit closer to the MT-32 soundtrack:
[mixer]\nreverb = large\nchorus = strong\nWe\u2019re on a roll here; the game seems to provide us with endless education opportunities. We\u2019ll divert our eyes (ears?) from the audio to the graphics next!
If you\u2019ve checked out the comic book included with the game (and you definitely should!) and you have a keen eye for detail, you might have noticed that the images in the intro sequence, which are scanned from the comics, appear vertically stretched on-screen. In fact, they appear exactly 20% taller than they should, which means the artwork was scanned using square pixels, then the stretching happens because of the 1:1.2 pixel aspect ratio of the 320\u00d7200 VGA screen mode (you might want to revisit the detailed explanation to refresh your memory).
Left: Screenshot from the intro with aspect ratio correction disabled (square pixels) Right: The original image from the comic book included with the gameAs we\u2019ve learnt previously, DOSBox Staging enables aspect ratio correction by default to make 320\u00d7200 graphics appear exactly as they would on a 4:3 aspect ratio VGA monitor, which requires pixels to be drawn 20% taller. This is the most sensible default as aspect ratio correction is absolutely needed for the vast majority of DOS games to look correct, but there are exceptions\u2014this game is one of those rare cases. We need to disable aspect ratio correction for such games. With aspect ratio correction disabled, we\u2019ll always get square pixels, no matter what (1:1 pixel aspect ratio).
That\u2019s quite easy to do, and we\u2019re also setting the viewport resolution to 4x scaling, effectively, because the game would appear too blocky when fit to fullscreen:
[render]\naspect = off\nviewport_resolution = 1280x800\nBeneath a Steel Sky with 1280\u00d7800 viewport resolution restriction and aspect ratio correction disabled
Beneath a Steel Sky \u2014 Well, we won\u2019t escape this way\u2026
Of course, this would\u2019ve been a very misguided effort if it had only fixed the intro graphics but not the in-game visuals. Fortunately, it turns out both the intro and the in-game content had been drawn assuming square pixels. For example, note how the floppy icon looks like a tallish rectangle with aspect ratio correction enabled; that\u2019s wrong, floppies should appear as perfect squares. Human figures and circular objects would also appear slightly elongated vertically with aspect ratio correction enabled. Ultimately, we know the game was developed by Revolution, a European studio, and they also released the game for PAL Amigas that have square pixels. We also know that Revolution was very fond of the Amiga, and thus can be considered an Amiga-first developer. For such games, disabling aspect ratio correction is almost always the correct answer.
So, the rules of thumb:
aspect = on
For most games where DOS was the leading platform. This is the DOSBox Staging default, and it ensures the overwhelming majority of DOS games appear correctly out of the box.
For games where the leading platform was the Amiga or Atari ST, but the game was developed by a North American studio for the NTSC standard (or the actual work was performed by a European studio, but it was commissioned by North Americans, and the game was primarily intended for the NTSC-only North American market).
aspect = off
Here\u2019s a non-exclusive list of the most important Amiga-first European studios:
Bitmap Brothers, Bullfrog, Coktel Vision, Core Design, DMA Design, Delphine, Digital Illusions, Firebird, Horror Soft / Adventure Soft, Infogrames, Level 9, Magnetic Scrolls, Ocean, Psygnosis, Revolution, Sensible Software, Silmarils, Team 17, Thalamus, Thalion, Ubisoft
From squares to rectangles
For the vast majority of computer games from the 80s and 90s featuring 2D graphics, the art was created once for the leading platform which was then reused in the various other platform conversions. It was just not economical to draw the graphics multiple times in different aspect ratios and resolutions, hence this was done extremely rarely.
We explained earlier that CRT monitors in the DOS era had a 4:3 aspect ratio, so in 320\u00d7200 mode the pixels had to be 20% taller for the image to completely fill the screen. DOSBox Staging does this aspect ratio correction by default which results in games primarily developed for DOS PCs assuming 1:1.2 pixel aspect ratio to look correct (as the artist intended).
But what about games where the leading platform was the Amiga or the Atari ST, and the game was developed by a European studio? The analog TV standard in Europe was PAL, therefore Amigas sold in Europe were PAL machines that had square pixels in the 320\u00d7256 screen mode, the resolution most commonly used by PAL Amiga games. So what these European studios usually did was to draw the art assuming square pixels, but using only a 320\u00d7200 portion of the 320\u00d7256 total available area. On PAL Amigas the art appeared in the correct aspect ratio, but letterboxed; on NTSC Amigas and DOS PCs that had the 320\u00d7200 low-res screen mode, the art filled the whole screen but appeared slightly stretched vertically (by 20%). No one seemed to complain about this, and they saved a lot of money by not having to draw the art twice, so this became a common practice.
However, now you have the option to enjoy these games in their correct aspect ratio, as per the artists\u2019 original intention by simply disabling DOSBox Staging\u2019s default aspect ratio correction.
Don\u2019t trust the circles!
Even keener observers might notice the image from the intro on the left features a circle that only appears perfect with aspect ratio correction enabled, in which case the image from the comics is stretched. But with aspect ratio correction disabled (as shown above), the circle appears to be a squashed oval, but the image from the comics looks perfect.
The explanation is simple: the person who drew the circle around the scanned image did it assuming 1:1.2 pixel aspect ratio, so it looked like a perfect circle to him on his PC VGA monitor.
That\u2019s a common theme: some games end up with assets added to them during the porting process, which can sometimes result in mixed aspect ratio assets in a single game. Sometimes it\u2019s just impossible to make the game appear correctly using a single fixed pixel aspect ratio, especially if such mixed aspect ratio assets are being displayed on screen at the same time.
Generally, you cannot trust the circles. Sometimes they will appear perfect when the correct aspect ratio is used, sometimes they won\u2019t. It\u2019s much more reliable to judge aspect ratio correctness by looking at common objects, human bodies, and human faces.
"},{"location":"getting-started/beneath-a-steel-sky/#final-configuration","title":"Final configuration","text":"Putting it all together, this is our final config:
[cpu]\ncycles = 12000\n[sdl]\nfullscreen = on\nviewport_resolution = 1280x800\n[render]\naspect = off\n# uncomment for VGA CRT emulation on a 4K display\n#glshader = crt/aperture\n[sblaster]\nsbmixer = off\n[midi]\nmididevice = mt32\n[mt32]\nmodel = cm32l\n[mixer]\nreverb = large\nchorus = strong\n[autoexec]\nimgmount d \"cd/cdrom1.iso\" -t iso\nc:\ncd sky\nsky\nexit\nWith this config, you can switch between Roland MT-32 and Sound Blaster / AdLib sound at will by only reconfiguring the game via INSTALL.EXE\u2014you don\u2019t need to make any further changes to the DOSBox config. In case you\u2019re wondering, enabling reverb and chorus does not add these effects to the MT-32 output by default; that\u2019s undesirable as the MT-32 has its own built-in reverb, so DOSBox Staging is intelligent enough not to apply double reverb to it.
We will continue our trend of featuring a disproportionate amount of LucasArts games in our guide. The game we\u2019ll tackle next is the Star Wars: Dark Forces demo from 1995, an example of the first-person shooter (FPS) genre, featuring fast software-rendered 3D graphics.
"},{"location":"getting-started/dark-forces/#installing-the-game","title":"Installing the game","text":"As per our usual routine, we\u2019ll create a new folder in DOS Games called Dark Forces, and the drives/c subfolder in it. The game demo comes in three ZIP archives, dforces1.zip, dforces2.zip, and dforces3.zip; we\u2019ll need to copy their contents to our virtual C drive. Make sure to download the manual as well.
There\u2019s a README.TXT included with the demo, it\u2019s recommended to read at least the installation and the keyboard shortcuts sections (use more README.TXT). The instructions tell us exactly what we need to do (this is why you should always check out the included text files):
I) INSTRUCTIONS FOR INSTALLING AND RUNNING DARK FORCES DEMO:\n\n1. Create a directory for the demo on your hard drive.\n (ex. C:\\DFDEMO)\n\n2. Extract the demo using PKUNZIP.EXE into the demo\n directory. If you have downloaded one or both of\n the cutscene files, then unzip them as well.\n\n3. From the demo directory, type \"demo\" and RETURN. This will\n bring you to the install menu. From the install menu, follow\n the on-screen instructions. Press \"I\" to install. This will\n take you through through the sound card setup program. When\n the install is finished it will bring you to the options\n menu. From there you type \"1\" to run Dark Forces. In the\n future, in order to get to the options menu, you should\n type \"demo\" from the your demo directory.\nWe actually don\u2019t need that DFDEMO folder, and we\u2019ve already extracted the contents of the three ZIP archives to our root directory on drive C, so just follow the instructions in step 3. Choose the Express Setup option in the sound configuration utility by pressing E, and the rest should be straightforward. The setup program will detect the Sound Blaster 16 correctly and will even play some test sounds.
After the setup has been completed, start the game by running demo again and then pressing the 1 key.
Star Wars: Dark Forces \u2014 Opening scene
"},{"location":"getting-started/dark-forces/#autotype","title":"Autotype","text":"Having to press the 1 key every time we start the game is not the end of the world, but it\u2019s not great either. Luckily, there\u2019s a way to automate that; the handy autotype DOSBox Staging command can simulate keypresses as implied by its name. This is what we need to put into our [autoexec] section to start the game without manual intervention:
[autoexec]\nc:\nautotype -w 0.5 1\ndemo\nexit\nThe first -w 0.5 argument of the autotype command specifies an initial 0.5 second wait time before the \u201cauto-typing\u201d begins. This is followed by the 1 argument which will simulate pressing the 1 key.
That\u2019s it! It\u2019s a simple but very useful feature. Run autotype /? to see the full list of available options and check out the list of AUTOTYPE candidates on our wiki for assorted real-life examples.
Dark Forces uses the 320\u00d7200 / 256-colour VGA screen mode, just like the majority of DOS games from the 90s. This mode uses a fixed 70 Hz screen refresh rate, so if your emulated CPU is fast enough, you can get 70 FPS out of the game.
But there\u2019s a problem: most modern non-variable refresh rate flat screens work at fixed 60 Hz. Luckily, DOSBox Staging intelligently times and drops frames if there\u2019s a mismatch between the refresh rate of the emulated graphics card and the actual refresh rate of your physical monitor. In most cases, this works fine out of the box without you needing to configure anything.
However, even though DOSBox Staging is trying to do its best in such situations, refresh rates will always result in some visible unevenness of motion. This is especially noticeable in games that feature smooth scrolling (e.g., shoot\u2019em up games, platformers, and pinball games), and in fast-paced 3D games, such as Dark Forces.
To achieve smoother motion, we have two options:
Using a variable-refresh rate (VRR) monitor \u2014 Nvidia G-Sync, AMD FreeSync, VESA AdaptiveSync, and Apple ProMotion certified displays all fall into this category. Any monitor that can continuously vary the refresh rate from about 59 to 71 Hz should do the job. DOSBox Staging automatically takes advantage of such displays by default.
Using specific fixed refresh rates on non-VRR monitors \u2014 Even if you\u2019re not a lucky owner of a VRR display, your monitor might support a fixed 70 Hz refresh rate if you create a custom screen mode for it. This is highly monitor dependent, but there\u2019s no harm in trying it out.
Note, however, that depending on the type of game, the 60/70 Hz mismatch might not matter much or at all. For instance, most adventure, strategy, and role-playing games rarely have fast-paced graphics; they generally only update the screen in the low 5-20 FPS range. Running the monitor at 70 Hz results in very little noticeable improvement with these games.
Another important consideration is that most pre-VGA games don\u2019t feature smooth movement in their graphics, so the general unevenness of motion masks the slight judder resulting from the 60/70 Hz mismatch.
For reference, these are the refresh rates of all emulated graphics cards:
Graphics adapter Refresh rate SVGA and VESA 70 Hz or higher \u2014 640\u00d7480 or higher extended and VESA modes VGA 60 Hz \u2014 640\u00d7480 standard mode only70 Hz \u2014 all other standard modes CGA, PCjr, Tandy, EGA 60 Hz Hercules 50 HzCreating custom 60 and 70 Hz screen modes
\u201cCustom resolution\u201d is a bit of a misnomer because what we\u2019re after is creating a new screen mode that uses your monitor\u2019s native resolution, but with a custom refresh rate.
You can create such custom resolutions using the Nvidia Control Panel or with the Custom Resolution Utility (CRU) on Windows. You\u2019ll probably need to enable CVT reduced blanking (CVT-RB or CVT-RBv2) to go up to 70 Hz. For the best results, it\u2019s recommended to use the exact fractional 59.713 Hz and 70.086 Hz refresh rates for the nominal \u201c60 Hz\u201d and \u201c70 Hz\u201d DOS rates, respectively.
The drawback of this approach is that you need to set the appropriate custom resolution before starting DOSBox Staging, and if a game switches between different refresh rates, well, you\u2019re out of luck\u2014these games can only work 100% correctly either on a true VRR display or a real old-school CRT monitor. However, most games only use a single fixed refresh rate, which is usually the standard 70 Hz VGA rate, so this technique is still very practical.
"},{"location":"getting-started/dark-forces/#vertical-syncing","title":"Vertical syncing","text":"Dark Forces synchronises its screen updates to the refresh rate of the emulated VGA card, which is always 70 Hz. This is hardcoded behaviour that cannot be disabled in the game\u2019s configuration.
DOSBox Staging itself also uses vertical syncing by default to synchronise updating the emulated image to the vertical refresh rate of your physical monitor. Without DOSBox-level vsync, fast-paced games such as this one would exhibit a lot of tearing. This is important to understand: to get zero tearing, vertical syncing must be happening both in the game and at the DOSBox level!
Conversely, DOSBox-level vsync only means that the emulated image is output to your physical monitor without flickering and tearing; the emulated DOS game itself might or might not use vertical syncing, and thus might or might not produce tearing artifacts of its own (these artifacts are present when running the game on real hardware too\u2014there\u2019s nothing we can do about them).
You don\u2019t have control over the vertical syncing behaviour in most DOS games. For example, Commander Keen 4\u20136, Doom, and many other FPS games have hardcoded vsync with a fixed 35 FPS cap. These games were programmed with fixed refresh rates in mind from the ground up; trying to disable the vsync or altering the FPS cap would completely break them (but the good news is you can\u2019t do that anyway).
To recap, the following variations are possible when it comes to vsync:
Game uses vsync? DOSBox-level vsync enabled? Result yes yes no tearing no yes some tearing; also present on real hardware yes no bad tearing (in fast-paced games) no no very bad double-tearing (in fast-paced games)As you can see, there is no point in disabling vsync in DOSBox itself, and even with DOSBox vsync enabled you might still get tearing in some games, but that\u2019s just how the games were coded. We can\u2019t \u201cfix\u201d that at the emulator level; that would require making changes to the games\u2019 code. On the other hand, that\u2019s the \u201cauthentic DOS experience\u201d for you!
"},{"location":"getting-started/dark-forces/#setting-the-emulated-cpu-speed","title":"Setting the emulated CPU speed","text":"Hardware-accelerated 3D graphics only became widespread in the second half of the 90s after the end of the DOS era, so most DOS games only use software rendering. Dark Forces is no exception, which means your emulated CPU needs to be fast enough to reach the 70 FPS maximum the game supports.
The game prints out the familiar message of the DOS/4GW DOS extender at startup, which means this is a protected mode game:
DOS/4GW Protected Mode Run-Time Version 1.95\nCopyright (c) Rational Systems, Inc. 1990-1993\nAs we\u2019ve learnt, protected mode games default to using all available CPU power. While this will most likely help achieve a stable 70 FPS (if your computer is powerful enough), running the CPU at maximum speed could starve the audio emulation, leading to audible glitches, clicks, and pops.
To avoid such issues, it\u2019s much preferable to emulate a CPU that is powerful enough to handle 70 FPS but not more. One way to come up with a good cycles number is to start the game with a relatively low cycles setting, say 10\u2009000, then keep increasing it with the Ctrl+F12 shortcut (Cmd+F12 on the Mac) while playing to arrive at the lowest value that results in adequate performance. As a reminder, you can decrease the current cycles value too with the Ctrl+F11 (Cmd+F11) shortcut.
So let\u2019s add the following to our config:
[cpu]\ncycles = 10000\nStart the game and hold the Left or Right key to keep turning around, then increase the cycles value until the motion becomes smooth (again, unless you\u2019re using a VRR monitor or a fixed 70 Hz refresh rate, it will never become completely smooth). Somewhere around 50\u2009000 cycles seems to do the trick, which roughly corresponds to a Pentium 90 based on our table of common processors.
So we\u2019ll go with that setting. You might need to increase this if later levels are more demanding on the CPU, but this is a good starting point:
[cpu]\ncycles = 50000\nRunning out of steam
As you keep increasing the fixed cycles value, the audio will start breaking up, and the motion will become very stuttery after a certain point. This means you\u2019re trying to emulate a faster CPU than your computer can handle. If you\u2019re on a less powerful machine, this unfortunately can happen before reaching the minimum cycles value necessary for a smooth and stable 70 FPS.
You have only two options in this situation: live with a lower cycles setting that results in less than 70 FPS, or buy a more powerful computer with a faster processor that can handle higher cycles values.
Also, make sure you\u2019re not running any other CPU-intensive programs at the same time in the background. Virus scanners, backup software, copying large files to USB storage, heavy network traffic, and even ordinary web browsers with many tabs open can chew up a significant part of your total CPU power. Certain popular chat programs can be very demanding on the CPU too, and, surprisingly, even innocent-looking stuff such as automatic wallpaper changers can have negative effects on the performance of DOSBox.
As a general rule, it\u2019s best to close all other programs if you\u2019re encountering performance issues with DOSBox and try again. Just apply common sense and treat DOSBox as any other performance-intensive modern game.
"},{"location":"getting-started/dark-forces/#setting-up-general-midi-sound","title":"Setting up General MIDI sound","text":"Our previous example game, Beneath A Steel Sky, supports the Roland MT-32 MIDI sound module to provide more realistic-sounding music than what the Sound Blaster\u2019s OPL synthesiser is capable of. Dark Forces, however, was composed for a newer family of MIDI sound modules that support the so-called General MIDI standard.
DOSBox Staging comes with an integrated General MIDI compliant synthesiser called FluidSynth. Unlike the MT-32 emulation, FluidSynth does not attempt to mimic any specific hardware device but a very generic MIDI sound module. This sound module doesn\u2019t have any built-in sounds\u2014you need to load so-called SoundFont files (.sf2 extension) into FluidSynth to get any sound out of it; these contain the instrument definitions and the sound data.
You can read more about the history of MIDI in DOS gaming at the end of this section, but the short practical summary is as follows:
The Roland Sound Canvas SC-55 was the de-facto standard General MIDI sound module until the very end of the DOS years (around 1997).
DOSBox Staging does not emulate the SC-55 directly, but there are SoundFonts you can load into FluidSynth that approximate the sound of the SC-55.
One extra detail is that Roland went a bit beyond the General MIDI standard in their Sound Canvas series; these modules actually support the GS standard, which is basically General MIDI plus some Roland-specific enhancements. Many games use these extra features, and while General MIDI compatible SoundFonts will work with them, for the best results it\u2019s recommended to use GS standard compatible ones.
One such SoundFont is GeneralUser GS; download the latest version, then copy the SoundFont file with the .sf2 extension into its designated folder:
C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\soundfonts\\ macOS ~/Library/Preferences/DOSBox/soundfonts/ Linux ~/.config/dosbox/soundfonts The next step is to configure DOSBox Staging to use this SoundFont for General MIDI playback. The name of the SoundFont might be slightly different if a new version has been released since the writing of this guide; make sure you use the correct filename for the soundfont setting.
[midi]\nmididevice = fluidsynth\n[fluidsynth]\nsoundfont = \"GeneralUser GS v1.471.sf2\"\nThe only thing left to do is to reconfigure the game to use General MIDI for music:
Comment out the autotype command in the [autoexec] section and restart DOSBox.
Press 3 in the startup menu to reconfigure the sound settings, then C to do a custom setup.
Enter the Advanced Menu (it\u2019s above Quit at the bottom).
Select the General MIDI device for Music, and select the default 330 value for the Port setting.
The Digital Sound settings don\u2019t need changing as our Sound Blaster 16 has been auto-detected correctly.
The final configuration should look like this:
Press Enter on the Test Music menu item and you should hear the start of the Imperial March playing with much more realistic instruments!
How to drive a manual
Note that if you try to use Detect in the Music section, the auto-detection will fail and the Music option will revert to None. This can happen with some setup utilities, therefore it\u2019s important to know that the port of the General MIDI device must be set to 330, should the auto-detection fail. This is sometimes called the MPU-401 port, MPU port, or just MIDI port.
Similarly, most games can auto-detect the Sound Blaster settings, but sometimes you need to enter them manually. The default DOSBox settings are port (I/O address) 220, IRQ (interrupt) 7, and DMA channel 1.
It\u2019s worth watching the whole intro at this point to appreciate how much more realistic the General MIDI rendition of this orchestral piece sounds compared to the OPL synth.
Of course, you can always try other GM or GS compatible SoundFonts too\u2014that\u2019s the beauty of General MIDI! FluidR3_GM_GS and Creative Labs 4M GM_4gmgsmt are good candidates as they sound fairly close to the SC-55 sound set. The list of recommended SoundFonts on our wiki should also give you some further pointers on which SoundFonts are worth trying and where to find them.
Note that while some SoundFonts, such as GeneralUser GS, give you overall good results in most games, other SoundFonts might excel in a handful of titles and sound terrible in others. To give you an idea, here\u2019s how the intro music sounds on the original Roland SC-55 hardware versus a few different SoundFonts. As mentioned, GeneralUser GS and Creative 4GMGSMT are the closest in terms of overall balance and character, the rest are rather hit-and-miss. My advice: just pick one that gives you good overall results and stick with it.
Further comparison recordings can be found on our wiki.
Roland SC-55 v1.21 (hardware) Your browser does not support theaudio element. GeneralUser GS Your browser does not support the audio element. Creative 4GMGSMT Your browser does not support the audio element. FluidR3_GM_GS Your browser does not support the audio element. FatBoy Your browser does not support the audio element. Arachno Your browser does not support the audio element. Turn it down, please!
Some SoundFonts are way too loud; if you encounter such a SoundFont, you\u2019ll most likely want to lower the output level of FluidSynth. For example, to scale back the volume to 40%, use the mixer fsynth 40 command. A few SoundFonts are extremely loud\u2014you need to turn the FluidSynth volume down to 10-20% to get usable levels. It\u2019s a mystery what the authors were thinking\u2026
Roland MT-32 is not General MIDI
Do not confuse the Roland MT-32 family of MIDI sound modules with General MIDI modules! Music composed for the MT-32 sounds utterly wrong on a General MIDI module, and vice versa. Yes, they both have \u201cMIDI\u201d in their names, but that only refers to the communication protocol. The MT-32 range of devices are fully programmable synthesisers and most games take advantage of their sound-shaping capabilities, while the General MIDI modules have much more modest synthesis capabilities, but feature more realistic-sounding real-world instruments (the soundtrack of Dark Forces showcases this very well\u2014you just can\u2019t get such realistic orchestral music out of an MT-32).
Whenever you want to configure a new game for MIDI sound, you should consult the list of MT-32-compatible computer games to see if the game was originally composed for the MT-32 or a General MIDI device (typically the SC-55). The original game manuals very rarely give you this info, so you absolutely need this list that contains the hard-earned knowledge of many decades of research and testing.
Quite confusingly, there\u2019s an alarmingly large list of games that falsely claim MT-32 compatibility in their setup utility, but they in fact require a General MIDI module to sound correct. Before you configure any game for MT-32 sound, you should definitely check the list of games that falsely claim MT-32 compatibility too, no matter what the game\u2019s manual says (quite often, the information contained therein is simply wrong).
A brief history of MIDI in DOS gaming
In the beginning, the iconic Roland MT-32 family of devices were the only MIDI sound modules available for DOS games that made realistic-sounding music a possibility. The original MT-32 was released in 1987, and its hegemony ended in 1991 with Roland unleashing its successor, the similarly iconic Roland Sound Canvas SC-55.
The SC-55 was another pioneering effort that shaped DOS gaming history in significant ways: it was the world\u2019s first device to support the General MIDI standard and the GS standard (the latter being Roland\u2019s vendor-specific General MIDI extensions). MIDI in the broadest sense only defines a communication mechanism between MIDI-capable devices (e.g., a sound module and your computer), but remains silent on how the different instruments should sound. General MIDI (GM) remedied this with its 128 standard instrument definitions; for example, you can be sure that on any GM-compliant module instrument #1 is the Acoustic Grand Piano and instrument #36 is the Fretless Bass.
This made interoperation between GM-compliant devices possible. In theory, you could use any General MIDI sound module with any GM-compliant game, and you would get music, and it would sound mostly correct. In practice, that \u201cmostly\u201d part is highly variable and it depends on the musical composition and the particular sound module in use. The thing is, most composers and gamers had the SC-55, establishing it as a de-facto standard (understandably, because it was the very first GM module). Other GM sound modules can render musical compositions written for the SC-55 unbalanced and weird-sounding, depending on how different their instruments sound compared to the \u201cstandard\u201d SC-55.
Another thing that makes compatibility difficult to achieve is that the SC-55 supports not just the GM but also the GS standard, and many games make good use of certain GS-only features. This means that any other General MIDI module that claims \u201cSound Canvas compatibility\u201d also has to implement the GS standard in a manner that sounds very close to the SC-55, which is not always the case.
"},{"location":"getting-started/dark-forces/#dynamic-range-compression","title":"Dynamic range compression","text":"If a game has loud music and you set the output level of your soundcard too high, you\u2019ll get rather unpleasant-sounding distortion and crackling on real hardware. DOSBox Staging has a dynamic range compressor on the master channel that automatically pulls the volume back on loud sounds to prevent such distortion from happening.
You can test this by playing the game for a minute with the GeneralUser GS SoundFont. You might notice a slight \u201cpumping\u201d as the compressor pulls the volume back on loud sound effects; this dips the volume level of the background music as well.
To hear the distortion caused by the loud sounds clearly, disable the master compressor:
[mixer]\ncompressor = off\nOverall, the compressor does a good job of preventing audible distortion up to a certain point, and most users should not think much about it; it just works. But if the master channel is overdriven heavily, the pumping artifacts would be rather distracting, so in that case, it\u2019s better to lower the master volume with the mixer command (e.g., mixer master 50 to set the master volume to 50%). People who are after the best audio quality should also prefer lowering the master volume rather than relying on the compressor.
The sound output of Dark Forces is on the loud side, so we\u2019ll set the output to 50% to make sure the compressor is never engaged:
[autoexec]\nc:\nmixer master 50\nautotype -w 0.5 1\ndemo\nexit\nThe sound setup utility asks us to confirm whether the left and right audio channels should be swapped when setting up digital audio. Weird as it may sound, some Sound Blaster models and clones had \u201creversed stereo\u201d for some inexplicable reason. If people used any of these cards during the development of a game, the stereo image would be reversed on normal cards, and vice versa.
Irrespective of the exact reasons, the fact is that some games with stereo digital audio support have the left and right channels reversed. In affected games, the channels might be reversed on all Sound Blaster variants, or only on certain models.
In the case of Dark Forces, you don\u2019t need to use the \u201creverse stereo\u201d option when emulating a Sound Blaster 16 card (which is the default). However, when using the Sound Blaster Pro 1 model (sbtype = sbpro1), the stereo image needs to be reversed.
But what about games that don\u2019t have such a handy \u201creverse stereo\u201d option in their setup utility? For those games, you can simply reverse the left and right channels of the SB mixer channel with the mixer sb reverse command. (Remember, use mixer /? to list all available commands and options.)
Even after setting the optimal cycles value for the game to limit the emulated CPU speed, you might still hear occasional audio glitches. Why this can happen depends on a lot of factors, but mainly it comes down to the particular hardware, driver, and operating system combination you\u2019re using.
As a last resort, you can try setting larger audio buffers sizes; this usually helps eliminate the occasional clicks and pops. The downside of this is that it will also increase audio latency, meaning that you\u2019ll hear the audio in response to some action with a longer delay (e.g., when shooting with a gun).
The default blocksize value is 1024 on Windows and 512 on macOS and Linux. The default prebuffer size is 25 on Windows and 20 on the other platforms (this is specified in milliseconds). You can experiment with increasing these settings\u2014doubling them is a good start. Generally, prebuffer can be anything, and blocksize should be one of the following values: 256, 512, 1024, 2048, 4096, or 8192.
[mixer]\nblocksize = 2048\nprebuffer = 50\nHere\u2019s the full config of Dark Forces set up for General MIDI sound:
[sdl]\nfullscreen = on\nviewport_resolution = 1120x840\n[cpu]\n# to emulate a Pentium 90\ncycles = 50000\n[midi]\nmididevice = fluidsynth\n[fluidsynth]\nsoundfont = \"GeneralUser GS v1.471.sf2\"\n[autoexec]\nc:\nmixer master 50\nautotype -w 0.5 1\ndemo\nexit\nYou can toggle between windowed and fullscreen mode at any time by pressing Alt+Enter. But what if you always want to play the game in fullscreen? Wouldn\u2019t it be nice to configure DOSBox to start in fullscreen mode?
You can easily do that by setting fullscreen = on in the [sdl] section. Modify your dosbox.conf file so it has the following content, then restart DOSBox Staging.
[sdl]\nfullscreen = on\n[autoexec]\nc:\nprince\nexit\nNote we\u2019ve also added the exit command to the end of the [autoexec] section; with this in place, DOSBox will quit itself after we exit from the game by pressing Ctrl+Q. Not strictly necessary, but a nice touch.
Toggling options
For configuration settings that toggle an option, you can use on, enabled, yes, true or 1 for turning the option on, and off, disabled, no, false or 0 for turning it off.
Making configuration changes
You need to quit and restart DOSBox Staging after updating dosbox.conf for the changes to take effect. We will not mention this every single time from now on.
That\u2019s nice, but depending on the size of your monitor, 320\u00d7200 VGA graphics displayed in fullscreen on a 24\u201d or 27\u201d modern monitor might appear overly blocky. If only we could control the size of the image in fullscreen as easily as we can in windowed mode!
Well, it turns out we can! You can restrict the viewport size by adding the viewport_resolution setting to the [sdl] section. In this case, we\u2019re restricting the viewport to a maximum size of 1120 by 840 pixels. The emulated video output will be sized so it fits within the bounds of this rectangle while keeping the correct aspect ratio.
[sdl]\nfullscreen = on\nviewport_resolution = 1120x840\nWe\u2019re effectively applying a 3.5\u00d7 scaling factor here to the 320\u00d7200 VGA graphics:
Huh, what? Where\u2019s the 840 in our config coming from then?
Computer monitors were originally not widescreen but had a 4:3 aspect ratio, just like old television sets. The complete switch to 16:9 in computer monitors and laptops happened only by the early 2010s. The low-resolution 320\u00d7200 VGA mode was designed to completely fill a 4:3 monitor, but that\u2019s only possible if the pixels are not perfect squares, but slightly tall rectangles. If you do the maths, it turns out they need to be exactly 20% taller for the 320\u00d7200 VGA screen mode (1:1.2 pixel aspect ratio). 700 \u00d7 1.2 = 840, so that\u2019s the explanation.
Prince of Persia in fullscreen with 1120\u00d7840 viewport resolution restriction
In any case, you don\u2019t need to worry about aspect ratio correctness because DOSBox Staging handles that automatically for you out of the box. It\u2019s just good to have some level of understanding of what\u2019s really happening. If you specify 1120x700, that would also work, but because aspect ratio correction is enabled by default, and the image must fit within the bounds of the specified viewport rectangle, the dimensions of the resulting image will be 933 by 700 pixels (because 700 \u00d7 4/3 = 933).
But hey, not everybody likes maths, especially in the middle of a DOS gaming session, so you can also specify the viewport resolution as a percentage of your desktop resolution:
viewport_resolution = 80%\nWhen pixels are not squares
Sadly, this very important fact of computing history that monitors were not widescreen until about 2010 tends to be forgotten nowadays. Older DOSBox versions did not perform aspect ratio correction by default, which certainly did not help matters either. The unfortunate situation is that you\u2019re much more likely to encounter videos and screenshots of DOS games in the wrong aspect ratio (using square pixels) on the Internet today. Well, that\u2019s only true for more recently created content\u2014if you check out old computer magazine from the 1980s and the 90s, most screenshots are shown in the correct aspect ratio (rarely, the magazines got it wrong too\u2026)
In case you\u2019re wondering, pixels are completely square in 640\u00d7480 and higher resolutions (1:1 pixel aspect ratio), but there exist a few more weird screen modes with non-square pixels, e.g., the 640\u00d7350 EGA mode with 1:1.3714 pixel aspect ratio (PAR), the 640\u00d7200 EGA mode with 1:2.4 PAR, and the 720\u00d7348 Hercules graphics mode with 1:1.5517 PAR.
"},{"location":"getting-started/enhancing-prince-of-persia/#graphics-adapter-options","title":"Graphics adapter options","text":"DOSBox emulates an SVGA (Super VGA) display adapter by default, which gives you good compatibility with most DOS games. DOSBox can also emulate all common display adapters from the history of the PC compatibles: the Hercules, CGA, and EGA display adapters, among many others.
Although the VGA standard was introduced in 1987, it took a good five years until it gained widespread adoption. Games had to support all commonly used graphical standards during this transitional period. Prince of Persia, released in 1990, is such a game; it not only supports all common display adapters, but it also correctly auto-detects them. This is in contrast with the majority of DOS games where you need to configure the graphics manually.
"},{"location":"getting-started/enhancing-prince-of-persia/#vga","title":"VGA","text":"The art in Prince of Persia was created for VGA first, so quite naturally the game looks best on a VGA adapter. Most DOS games from the 1990s use the 320\u00d7200 low-resolution VGA mode that allows up to 256 colours to be displayed on the screen, chosen from a palette of 16 million colours.
Prince of Persia in VGA mode with the default settings
"},{"location":"getting-started/enhancing-prince-of-persia/#ega","title":"EGA","text":"Most games with EGA support use the 320\u00d7200 low-resolution EGA mode that has a fixed 16-colour palette.
To run Prince of Persia in EGA mode, you simply need to tell DOSBox to emulate a machine equipped with an EGA adapter. That can be easily done by adding the following configuration snippet:
[dosbox]\nmachine = ega\nThis is how the game looks with the fixed 16-colour EGA palette:
Prince of Persia in EGA mode
That\u2019s nice, but it\u2019s not exactly how the graphics looked on an EGA monitor back in the day. Pre-VGA monitors had visible scanlines, and we can emulate that by enabling an OpenGL shader that emulates the CRT monitors (Cathode-Ray Tube) of the era:
[render]\nglshader = crt/aperture\nThis adds some texture and detail to the image that\u2019s especially apparent on the solid-coloured bricks:
Prince of Persia in EGA mode using the crt/aperture shader
If you have a 4K display, you might want to try the crt/fakelottes.tweaked shader. Another good one is crt/geom.tweaked.
The crt/zfast shader is a good choice for older or integrated graphics cards, and the crt/pi was specifically optimised for the Raspberry Pi.
You can view the full list of included CRT shaders here.
"},{"location":"getting-started/enhancing-prince-of-persia/#cga","title":"CGA","text":"The notorious CGA adapter, the first colour graphics adapter created for the original IBM PC in 1981, is a serious contender for the worst graphics standard ever invented. In its 320\u00d7200 low-resolution mode, 4 colours can be displayed simultaneously on the screen chosen from a number of fixed palettes. Frankly, all combinations look pretty horrible\u2026
But no matter; the game supports it, so we\u2019ll have a look at it. Make the following adjustment to the machine setting, and don\u2019t forget to put on your safety glasses!
[dosbox]\nmachine = cga\nReady? Behold the formidable 4-colour CGA graphics\u2014and what 4 colours those are!
Prince of Persia in CGA mode using the crt/aperture shader
Tip
To compare how the game looks on different graphics adapters, click on one of the CRT shader screenshots to enlarge it, then use the Left and Right arrow keys to switch between the images.
Warning
Screenshots of CRT shaders in action need to be viewed at 100% magnification; otherwise, you might see strange wavy interference patterns on them caused by the browser rescaling the images. These unwanted artifacts can sometimes resemble repeating rainbow-like patterns, and rest assured, that\u2019s not how CRT emulation is supposed to look in DOSBox Staging!
To view a screenshot featuring a CRT shader properly, click on the image to enlarge it, then if your mouse cursor looks like a magnifying glass, click on the image again to display it with 100% magnification.
"},{"location":"getting-started/enhancing-prince-of-persia/#hercules","title":"Hercules","text":"The Hercules display adapter was released in 1982 to expand the text-only IBM PCs with basic graphical capabilities. It only supports monochrome graphics, but at a higher 720\u00d7348 resolution. Can you guess how you can enable it?
[dosbox]\nmachine = hercules\nIf you wish to use a CRT shader, the crt/aperture.mono shader variant has been specifically created for emulating monochrome monitors (it switches off the RGB phosphor and aperture grille emulation of the base crt/aperture shader).
[render]\nglshader = crt/aperture.mono\nPrince of Persia in Hercules mode using the white paletteand the crt/aperture.mono shader
Monochrome monitors came in different colours; DOSBox Staging can emulate all these variations via the monochrome_palette configuration setting. The available colours are white (the default), paperwhite, green, and amber. You can also switch between them while the game is running with the F11 key on Windows and Linux, and Alt+F11 on macOS.
[dosbox]\nmachine = hercules\nmonochrome_palette = amber\nThe slightly squashed aspect ratio is correct in this case; this is exactly how the game would look on a PC equipped with a Hercules card connected to a period-accurate monochrome monitor.
Hercules mode using the amber palette
Hercules mode using the green palette
Only for masochists and archeologists!
The art in DOS games was usually created for the best graphics standard the game supported, then variants for \u201clesser\u201d standards were derived from that. If you were an unlucky person still stuck with a Hercules or CGA adapter in 1990, being able to play Prince of Persia with any graphics surely beat no game at all!
Although we\u2019ve shown how to emulate these earlier graphics standards for completeness\u2019 sake, there\u2019s generally little reason for not playing a DOS game with the best graphics. The list of possible reasons include: a) strong nostalgic feelings towards a particular display adapter; b) research reasons; c) you like your games to look like the user interface of an industrial CNC machine; d) a preference for pain. But hey, who are we to judge?
In any case, preserving all relevant aspects of PC gaming history is important for the DOSBox Staging project, so these display options are always available at your fingertips, should you ever need them.
"},{"location":"getting-started/enhancing-prince-of-persia/#true-vga-emulation","title":"\u201cTrue VGA\u201d emulation","text":"If you\u2019re the lucky owner of a high-resolution monitor with at least 2000 pixels of native vertical resolution (4K or better monitors belong to this category), you can use \u201ctrue VGA\u201d emulation that more accurately resembles the output of an actual CRT VGA monitor.
VGA display adapters have a peculiarity that they display not one but two scanlines per pixel in all low-resolution screen modes that have less than 350 lines. This means the 320\u00d7200 low-resolution VGA mode is really 640\u00d7400, just pixel and line-doubled.
To emulate this, we\u2019ll use a CRT shader and exact 4-times scaling by setting the viewport resolution to 1280\u00d7960. This is important for getting even scanlines, and it doesn\u2019t work on regular 1080p monitors because there\u2019s simply not enough vertical resolution for the shader to work with.
Logical vs physical pixels
Wait a minute, 1280\u00d7960 fits into a 1920x1080 screen, doesn\u2019t it? Why did you say we need a 4K display for this then?
Most operating systems operate in high-DPI mode using a 200% scaling factor on 4K displays. This means that the pixel dimensions used by the applications no longer represent physical pixels, but rather logical or device-independent pixels. On a 4K display, assuming a typical 200% scaling factor, our viewport resolution specified in 1280\u00d7960 logical pixels will translate to 2560\u00d71920 physical pixels. A vertical resolution of 1920 pixels is certainly sufficient for displaying those 400 scanlines; the shader can use 4.8 pixels per scanline to do its magic (generally, you need at least 3 pixels per \u201cemulated scanline\u201d to achieve good results).
These are the relevant configuration settings to enable authentic double-scanned VGA emulation:
[sdl]\nviewport_resolution = 1280x960\n[render]\nglshader = crt/aperture\nHere\u2019s a comparison of how true VGA emulation looks at 4K resolution compared to the standard \u201craw sharp pixel\u201d look (zoom in to appreciate the differences):
Left: \u201cTrue VGA\u201d emulation; Right: default output (\u201craw sharp pixels\u201d)
"},{"location":"getting-started/enhancing-prince-of-persia/#chorus-reverb","title":"Chorus & reverb","text":"We\u2019ve been discussing graphics at great length, but what about sound? Can\u2019t we do something cool to the sound as well?
Yes, we can! DOSBox Staging has an exciting feature to add chorus and reverb effects to the output of any of the emulated sound devices.
Create a new [mixer] section in your config with the following content:
[mixer]\nreverb = large\nchorus = normal\nNow the intro music sounds a lot more spacious and pleasant to listen to, especially through headphones. There\u2019s even some reverb added to the in-game footsteps and sound effects, although to a much lesser extent.
You might want to experiment with the small and medium reverb presets, and the light and strong chorus settings as well.
Purist alert!
To calm the purists among you: adding reverb and chorus to the OPL synthesiser\u2019s output is something you can do on certain Sound Blaster AWE32 and AWE64 models on real hardware too via the standard drivers.
"},{"location":"getting-started/enhancing-prince-of-persia/#auto-pause","title":"Auto-pause","text":"Prince of Persia can be paused by pressing the Esc key during the game. But wouldn\u2019t it be convenient if DOSBox could auto-pause itself whenever you switch to a different window? You can easily achieve that by enabling the pause_when_inactive option in the [sdl] section.
[sdl]\nfullscreen = on\nviewport_resolution = 1120x840\npause_when_inactive = yes\nRestart the game and switch to a different window\u2014DOSBox has paused itself. Switch back to DOSBox\u2014the game resumes. Nifty, isn\u2019t it? This is quite handy for those games that have no pause functionality, or when you need to take a break during a long cutscene that cannot be paused.
"},{"location":"getting-started/enhancing-prince-of-persia/#final-configuration","title":"Final configuration","text":"Below is the full config with all the enhancements we\u2019ve added, including authentic VGA CRT monitor emulation on 4K displays.
[sdl]\nfullscreen = on\nviewport_resolution = 1280x960\npause_when_inactive = yes\n[render]\nglshader = crt/aperture\n[mixer]\nreverb = large\nchorus = normal\n[autoexec]\nc:\nprince\nexit\nIf you\u2019re not on a high-DPI display, just delete the whole [render] section to disable the CRT shader.
Instead of deleting those lines, you can prefix them with a # character (Shift+3 on the US keyboard layout) to turn them into comments.
Comments are lines starting with a # character; DOSBox ignores them when reading the configuration. Normally, you would use them to add, well, comments to your config, but \u201ccommenting out\u201d a line is a quick way to disable it without actually removing the line.
[sdl]\nfullscreen = on\nviewport_resolution = 1280x960\npause_when_inactive = yes\n[render]\n#glshader = crt/aperture\n[mixer]\nreverb = large\nchorus = normal\n[autoexec]\nc:\nprince\nexit\nNote we haven\u2019t commented out the [render] section itself. That\u2019s fine; empty sections are allowed and do no harm.
What if you used a wrong value in your config, made a typo, or misremembered the name of a setting? How would you know about it? Having to triple-check every single character of the config when something goes wrong is not a good prospect\u2026 Fortunately, you don\u2019t have to do that because DOSBox can inform you if something went wrong. It does that via the logs, which is just a continuous stream of timestamped messages in a separate window.
The behaviour of the log window is different on each platform:
WindowsThe log window is opened by default when you start DOSBox Staging . You can hide the log window by passing the -noconsole argument to the DOSBox Staging executable.
DOSBox Staging does not open the log window by default when started via its application icon, or with the Start DOSBox Staging icon you copied from the .dmg installer archive earlier.
To make the log window appear, you need to use another shortcut icon called Start DOSBox Staging (logging), which you can copy into your game folder from the same .dmg archive (note the word \u201clogging\u201d in the name of the icon).
Start DOSBox Staging from the terminal, and the logs will appear there.
Under normal circumstances, the logs contain lots of interesting technical details about what DOSBox Staging is currently doing, what exact settings it uses, and so on. For example, this is the start of the logs when running the game on macOS:
That\u2019s all good and well, but what\u2019s even better, if an invalid configuration setting has been detected, or something went wrong when running the game, DOSBox Staging will inform us about it in the logs!
Let\u2019s now intentionally screw a few things up in the config to trigger some errors:
machine to mcp[sdl] section: no_such_config_param = 42fullscreen to blahx in front of the shader\u2019s nameThis is how the freshly ruined parts of our config should look like:
[sdl]\nfullscreen = blah\nno_such_config_param = 42\n[dosbox]\nmachine = mcp\n[render]\nglshader = xcrt/aperture\nAs expected, we\u2019ll see some warnings and errors in the logs after a restart:
Warnings are yellow, errors are red. Errors are generally reserved for more severe problems. In this example, we have the following:
The first warning tells us that blah is not a valid value for the fullscreen setting, so DOSBox has reset it to its default value of false.
Then it reprimands us about no_such_config_param that we made up.
The third warning complains about an invalid machine value being used (sorry to disappoint, but DOSBox Staging can\u2019t emulate the Master Control Program from Tron yet!)
Then we have an error because we\u2019re trying to use a non-existing shader.
This is followed by yet another rather large warning block that very helpfully lists the names of all available shaders on our system. That\u2019s pretty handy!
This is a common theme with the logs. When DOSBox Staging displays some warnings or errors, these messages often include suggestions and tips to help you resolve the issues. Note that these can appear not only at startup but also during running a game, depending on what DOSBox Staging is currently doing.
While you might prefer to hide the log window for aesthetic reasons, it\u2019s wiser to just let it be so you can take a peek at it if something goes sideways. Without having access to the logs, your chances of fixing problems are significantly reduced as basically you would be just stumbling in the dark. You\u2019ve been warned!
Okay, we\u2019ve pretty much maxed out Prince of Persia for demonstration purposes. Time to move on to another game!
"},{"location":"getting-started/introduction/","title":"Introduction","text":""},{"location":"getting-started/introduction/#foreword","title":"Foreword","text":"Welcome to the DOSBox Staging getting started guide!
This guide will gently introduce you to the wonderful world of DOSBox by setting up a few example games from scratch. It\u2019s written in the spirit of \u201cteaching a man how to fish\u201d\u2014the games are only vehicles to teach you the basics that you can apply to any DOS game you wish to play later. Consequently, the choice of games doesn\u2019t matter that much (although we tried to pick from the all-time classics).
To get the most out of this guide, don\u2019t just read the instructions but perform all the steps yourself! Later chapters build on concepts introduced in previous ones, so do not skip a chapter just because you\u2019re not interested in a particular game! You don\u2019t have to play it if you don\u2019t want to; going through the setup procedure and learning how to troubleshoot various issues is what this is all about. All necessary files will be provided and no familiarity with IBM PCs and the MS-DOS environment is required\u2014everything you need to know will be explained as we go. The only assumption is that you can perform basic everyday computer tasks, such as copying files, unpacking ZIP archives, and editing text files.
The guide has been written so that everyone can follow it with ease, regardless of their operating system of choice (e.g., Windows users probably know what the \u201cC drive\u201d is, and most Linux people are comfortable with using the command line, but these things need to be explained to the Mac folks).
We wish you a pleasant journey and we hope DOSBos Staging will bring you as much joy as we\u2019re having developing it!
"},{"location":"getting-started/introduction/#installing-dosbox-staging","title":"Installing DOSBox Staging","text":"If you already have other versions of DOSBox on your computer, installing DOSBox Staging won\u2019t interfere with them at all. Experienced users can certainly use multiple DOSBox variants on the same machine without problems, but if you\u2019re a beginner, we recommend starting with a clean slate to avoid confusing yourself. Make sure you\u2019ve removed all other DOSBox versions from your machine first, then proceed with the DOSBox Staging installation steps.
WindowsDownload the latest installer from our Windows downloads page, then proceed with the installation. Just accept the default options, don\u2019t change anything.
Make sure to read the section about dealing with Microsoft Defender SmartScreen.
macOSDownload the latest universal binary from our macOS downloads page, then simply drag the DOSBox Staging icon into your Applications folder. Both Intel and M1 Macs are supported.
Don\u2019t delete the .dmg installer disk image just yet\u2014we\u2019ll need it later.
Make sure to read the section about dealing with Apple Gatekeeper.
LinuxPlease check out our Linux downloads page and use the option that best suits your situation and needs.
"},{"location":"getting-started/introduction/#other-stuff-well-need","title":"Other stuff we\u2019ll need","text":"As you follow along, you\u2019ll need to create and edit DOSBox configuration files which are plain text files. While Notepad on Windows or TextEdit on macOS could do the job, it\u2019s preferable to use a better text editor more suited to the task.
WindowsWindows users are recommended to install the free and open-source Notepad++ editor.
Accept the default installer options; this will give you a handy Open with Notepad++ right-click context menu entry in Windows Explorer.
macOSTextMate is a free and open-source text editor for macOS which is perfect for the job.
Tip
When editing DOSBox configuration files in TextMate, it\u2019s best to set syntax highlighting to the Properties file format as shown in the below screenshot (it\u2019s the combo-box to the left of the Tab Size combo-box in the footer).
LinuxWe\u2019re pretty sure Linux users don\u2019t need any help and have their favourite text editors already. And, of course, everyone knows vim is the best!
"},{"location":"getting-started/next-steps/","title":"Next steps","text":""},{"location":"getting-started/next-steps/#thats-all-folks","title":"That\u2019s all, folks!","text":"All good things must come to an end, and this guide is no different!
Congratulations\u2014now you should be able to use DOSBox fairly confidently at a basic level, and we\u2019ve actually touched on quite a few intermediate topics as well. Armed with the basics, now you have a much greater chance to figure things out on your own, and you\u2019ll be able to ask more specific, directed questions from the more experienced members of the community when seeking help.
So what\u2019s next? Try setting up a few more games yourself; peruse the various configuration options in the default configuration; look around on our wiki; familiarise yourself with our feature highlights; read the release notes on our downloads page\u2014there are plenty of learning opportunities if you wish to delve deeper!
If you\u2019re stuck with something, you can always ask questions from the DOSBox Staging team directly on Discord.
Most importantly, experiment, enjoy what classic PC gaming has to offer, and have fun!
"},{"location":"getting-started/next-steps/#further-reading","title":"Further reading","text":"As your interest in DOS gaming grows, you might be interested in learning more about the history of PC gaming and PC hardware in general. Below is a selection of the very best learning resources to get you started!
RetroGrade - The ultimate guide to pre-millennial PC hardwareAn excellent collection of articles that takes you through the most important milestones of early PC hardware history, starting from its humble beginnings in the early 1980s right until the year 2000, covering the DOS era in its entirety and then some more.
DOS DaysThis very comprehensive website contains a great deal of information about DOS-era PC hardware, useful tips on setting up DOS games, and articles and guides on a variety of DOS-related topics. It\u2019s a highly recommended resource, and you\u2019ll inevitably end up here anyway when researching anything DOS-related via your favourite search engine\u2026
Nerdly PleasuresWritten by The Great Hierophant, there\u2019s simply no better resource online that does such extremely thorough and comprehensive deep dives supplanted by original research on a number of interesting DOS gaming related topics.
PhilsComputerLabPhil\u2019s YouTube channel offers a dizzying amount of quality content on a variety of retro-PC related topics with a special focus on actual hardware. Checking out his DOS tutorials and MIDI and wavetable series is a good start, but you can pretty much pick any of his videos at random and I guarantee you\u2019ll learn something interesting. His aptly titled three-and-a-half-hour long (!) Roland MT-32, CM-32L, CM-64, CM-500 Ultimate Tutorial is a work of art\u2014probably there isn\u2019t anything more to say on the subject!
DOSBox game compatibility listIf you\u2019re having problems with a game, it\u2019s worth having a look at the game compatibility list on the old DOSBox website. Although some information there might be outdated (e.g., mentioning DOSBox issues that have long been fixed), some of the comments document important issues present in the original games. That\u2019s one very common trap to fall into, thinking that certain game bugs are caused by emulation and therefore must be fixable at the DOSBox level. Often they\u2019re bugs present in the original games, so you just need to live with them or work around them.
VOGONSAn acronym for Very Old Games On New Systems, this forum is an oasis for all retro-hardware and retro-gaming enthusiasts, mainly focusing on PC compatibles and DOSBox-related things. The combined knowledge of the community on all things DOS and retro-PC is next to none\u2014try asking any obscure question, and there\u2019s a good chance you\u2019ll get a very detailed (and correct!) answer within a few hours.
"},{"location":"getting-started/passport-to-adventure/","title":"Passport to Adventure","text":"Okay, so what we\u2019ll set up next is not a single game, but a collection called Passport to Adventure which contains playable demos of three classic LucasArts point-and-click adventure games: Indiana Jones and the Last Crusade, The Secret of Monkey Island, and Loom. These were the blockbusters of the adventure gaming genre back in the day, and they still offer countless hours of fun if you like puzzle-solving and well-written, intriguing storylines.
But before we begin, let\u2019s discuss something fundamental to DOSBox Staging!
"},{"location":"getting-started/passport-to-adventure/#default-configuration","title":"Default configuration","text":"Have you wondered how do you learn about all the available configuration settings? When you start DOSBox Staging for the very first time, it creates a so-called default configuration file in a standard location with the name dosbox-staging.conf. This file contains the full list of available settings with their default values, plus a short explanatory text for each.
For example, this is the description of the viewport_resolution setting:
Set the viewport size (drawable area) within the window/screen:\n fit: Fit the viewport to the available window/screen (default).\n <custom>: Limit the viewport within to a custom resolution or percentage\n of the desktop. Specified in WxH, N%, N.M%.\n Examples: 960x720 or 50%\nHere are the locations of dosbox-staging.conf on each platform:
C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox-staging.conf macOS ~/Library/Preferences/DOSBox/dosbox-staging.conf Linux ~/.config/dosbox/dosbox-staging.conf Showing the Library folder in Finder
The Library folder is hidden by default in the macOS Finder. To make it visible, go to your home folder in Finder, press Cmd+J to bring up the view options dialog, and then check Show Library Folder.
If you know the exact name of a configuration setting, you can display its explanatory text using the built-in config command. The invocation is config -h followed by a space and the setting\u2019s name. For example:
It is highly recommended to look up the descriptions of the various settings as you encounter them in this guide. That\u2019s a good way to get gradually acquainted with them and further your knowledge about the available options.
"},{"location":"getting-started/passport-to-adventure/#layered-configurations","title":"Layered configurations","text":"In our Prince of Persia example, we created a dosbox.conf configuration file in the game\u2019s folder, then started DOSBox Staging from that folder. In such a scenario, DOSBox loads the default configuration first, then applies the dosbox.conf configuration found in the folder it was started from (the game\u2019s folder), overriding certain default settings.
This layered configuration approach is very useful; you can apply broad, general settings in your default global configuration that will apply to all games, then fine-tune these defaults on a per-game basis via local dosbox.conf configurations in the individual game folders.
As DOSBox Staging comes with sensible defaults, you can keep these local configurations quite minimal, as we\u2019ve already seen. There\u2019s absolutely no need to specify every single setting in your local game-specific config\u2014that would make configurations very cumbersome to manage, plus it would be difficult to see what settings have been changed from their defaults for a particular game.
A word of advice
It\u2019s best not to change the default configuration while you\u2019re still a beginner. Even more experienced DOSBox users are generally better off changing the defaults very sparingly as those settings will affect all games. A few things that you might consider changing globally are perhaps always enabling fullscreen, auto-pausing, and certain audio-related settings (e.g., sample rate and buffer sizes). We\u2019ll examine these later.
"},{"location":"getting-started/passport-to-adventure/#installing-the-game","title":"Installing the game","text":"Ok, so let\u2019s create the subfolder for our second game then! Create another folder in DOS Games next to Prince of Persia and name it Passport to Adventure. Create the drives subfolder in it and the c subfolder in the drives folder.
Download the ZIP archive from the Passport of Adventure item at the Internet Archive, then extract its contents into the c subfolder.
Below is the folder structure you should end up with. As explained before, we\u2019ll create one subfolder within DOS Games for each game, then each game folder will contain its own local dosbox.conf configuration specific to that game, along with its own \u201cemulated C drive\u201d in the drives/c subfolder.
By poking around on the C drive a little bit with the dir command, we\u2019ll quickly realise we only have two executables: INSTALL.BAT and SAMPLER.EXE. But there\u2019s also a README.TXT, so let\u2019s check that one out first!
We can try displaying its contents with the type README.TXT command (remember, use tab-completion), but that\u2019s not too fruitful as the text is longer than a single screen, so the type command will effectively only display the last page. In such cases, we can \u201cpipe\u201d the output of the type command through the more command that will paginate the preceding command\u2019s output. This is done by executing the following:
type README.TXT | more\nThe | is called the \u201cpipe\u201d character\u2014how fitting! You can type it by pressing Shift+\\, which is located above the Enter key on the standard US keyboard.
But there\u2019s an easier way to accomplish the same thing: we can simply execute more README.TXT. You can think of the more command as a more advanced, paginating version of the type command.
Now we can press Enter to advance the text one line at a time, or Space to go to the next page. The command will exit once we\u2019ve reached the end of the file, or we can quit earlier with the Q key. Of course, you can always cheat and read such text files outside of DOSBox, but we wanted to teach you something useful about DOS here.
The file contains important instructions about installing and playing the game, including the list of available keyboard shortcuts, so read it carefully. As it turns out, we\u2019ll only need to run SAMPLER.EXE, so let\u2019s just do that!
If you\u2019re playing the game in windowed mode, you\u2019ll need to click on the DOSBox Staging window first to \u201ccapture\u201d the mouse so you can move the crosshair-shaped in-game cursor.
To \u201crelease\u201d the \u201ccaptured\u201d mouse cursor, middle-click on your mouse, or press the Ctrl+F10 shortcut (Cmd+F10 on macOS). The title bar of the DOSBox Staging window informs you about the current mouse capture state.
It\u2019s also possible to tell DOSBox Staging to start with the mouse captured (this might not work on all operating systems, though):
[mouse]\nmouse_capture = onstart\nThis is a really user-friendly program; you can press F1 at the main screen to read the general instructions, then start a game demo by clicking on one of the three game icons on the left. Pressing F1 during the game displays further game-specific help; make sure you read them if you actually want to play these demos. They\u2019re worth playing even if you intend to play the full games later, as the demos contain slightly different scenes, puzzles, and dialogs, plus some fun easter-eggs.
For people who really don\u2019t like to read: F5 brings up the save/load/quit dialog, and you can pause/unpause the game with the Space key.
Let\u2019s start with the first demo called \u201cIndy\u201d (Indiana Jones and the Last Crusade), mainly because it plays a nice long version of the famous Indiana Jones theme during the intro, and we\u2019re going to investigate the various sound options next!
Indiana Jones and the Last Crusade \u2014 Title screen
Indiana Jones and the Last Crusade \u2014 Opening scene
"},{"location":"getting-started/passport-to-adventure/#sound-options","title":"Sound options","text":""},{"location":"getting-started/passport-to-adventure/#sound-blaster-adlib-sound","title":"Sound Blaster / AdLib sound","text":"The game managed to auto-detect our emulated Sound Blaster card, so what we\u2019re hearing during the intro is AdLib music.
\u201cWhoa, let me stop you right there, dude! You said Sound Blaster, so what\u2019s this AdLib thing now?!\u201d
Okay, we\u2019ll need to understand a few technical details again. Most Sound Blaster cards support at least two sound generation mechanisms:
Playing digitised sounds (sounds recorded from real-world sources, such as speech, sound effects, and sometimes even recorded music). This is referred to as digital audio, digitised sound, sampled audio, PCM audio, or just voice or speech in the game manuals and setup utilities (yes, it\u2019s all over the place; I\u2019m sure there are a dozen more variations out there\u2026)
Playing music and sound effects using a built-in synthesiser. This is usually called AdLib, OPL synthesiser, FM synthesiser, simply just music, or somewhat confusingly Sound Blaster MIDI.
Storing music as a list of instructions for a synthesiser takes very little disk space (think of sheet music), whereas storing digital audio eats disk space for breakfast (think of uncompressed audio files). Consequently, the vast majority of DOS games use some kind of synthesiser for music, and digital audio is generally reserved for sound effects and speech only.
These game demos don\u2019t have any digital sound effects; they all just use the OPL chip of the Sound Blaster for both music and some limited sound effects. The game is clever enough to auto-detect our OPL-equipped Sound Blaster 16 (the default sound card emulated by DOSBox), so we\u2019ll get OPL sound by simply just starting SAMPLER.EXE.
Of course, we can enhance the OPL music by adding reverb and chorus effects to it, just as we\u2019ve done with Prince of Persia. Unless you\u2019re an absolute purist, this is generally a good idea, especially when using headphones. We\u2019ll only need to add a few lines to our config:
[mixer]\nreverb = medium\nchorus = normal\nNote
Prince of Persia can also auto-detect our Sound Blaster 16, but most games are not this clever. As we\u2019ll see in our later game examples, usually we need to manually configure the audio devices using the game\u2019s setup utility.
1-minute Sound Blaster OPL synthesiser crash course
In case you\u2019re wondering:
OPL is just the name of the Yamaha OPL sound synthesiser chip present on most Sound Blaster cards.
AdLib was an early sound card predating Sound Blasters that featured the same OPL chip. Perfect AdLib compatibility was one of the Sound Blasters\u2019 main selling points, therefore in games that support both AdLib and Sound Blaster for synthesised sound, both options will usually yield the exact same results.
The AdLib card, however, had no support for digital audio, so it\u2019s preferable to pick the Sound Blaster option if the game offers both\u2014 you might also get digital speech and sound effects that way.
Sound Blaster MIDI is a weird thing. Most later games after 1992 supported much higher quality MIDI sound modules that used sampled recordings of real-world instruments. Many of these also provided a fallback option to play the same MIDI music via the OPL chip, using synthesised approximations of the same instruments.
FM refers to the type of sound synthesis the OPL chip is doing, which is Frequency Modulation synthesis (or FM synthesis, in short).
The observant among you might have spotted the list of graphics and sound configuration options in README.TXT. Playing with the graphics options is an exercise for the reader; it should be easy to apply what we\u2019ve learned during setting up Prince of Persia.
The sound settings, however, are quite interesting. We can get the executable to print out the list of available options by passing it some invalid argument; SAMPLER /? seems to do the trick:
C:\\>SAMPLER.EXE /?\n Interpreter Verson 4.0.62\nUnknown flag: '/?'\n\nOptions:\n h Hercules(tm) graphics\n c CGA graphics\n t Tandy(tm) graphics\n m MCGA graphics\n e EGA graphics\n v VGA graphics\n k Keyboard\n j Joystick\n mo Mouse\n i Internal speaker\n ts Tandy(tm) sounds\n g Game Blaster(tm) sounds\n a Adlib(tm) sounds\n d Two disk drives\n\nFor example, in order to play with EGA Graphics and a mouse,\ntype: SAMPLER e mo\nOkey-dokey, let\u2019s try the \u201cinternal speaker\u201d option by starting the game with the i command-line argument:
C:\\>SAMPLER.EXE i\nWell, it does sound a lot worse, doesn\u2019t it?
DOSBox emulates the little internal speaker (also known as PC speaker) that was a standard accessory of all PCs for a long time. It was designed to only produce rather primitive bleeps and bloops, but certain games can make it play digitised sound by employing some cunning tricks. In any case, this a bleepy-bloopy type of game\u2026
It\u2019s hard to envision anyone willingly subject themselves to the internal speaker experience when a game supports much better quality sound (even nostalgia can\u2019t be that strong!) But in most games released before about 1988, that\u2019s the only sound option you have.
For such early games, we can make the PC speaker a little more pleasant to listen to by enabling the special tiny reverb preset. This has been specifically designed for small-speaker audio systems; it simulates the sound of a small integrated speaker in a domestic room. The improvement is particularly noticeable with headphones.
[mixer]\nreverb = tiny\nAnother option is the \u201cTandy(tm) sounds\u201d you can select with the ts command-line argument. Let\u2019s try it!
C:\\>SAMPLER.EXE ts\nAaaaand, now there\u2019s no sound at all. Why is that?
Tandy Corporation was an IBM PC clone manufacturer in the 80s; they produced the Tandy line of home computers that were mostly compatible with the standard PCs but also offered improved sound and graphics capabilities. Developers had to specifically support the Tandy to take advantage of these features. There are relatively few such games, but they are worth seeking out as they provide a better experience, especially in the sound department. The games with Tandy & PCjr exclusive graphics and sound list on our wiki should help you find these pre-1990 Tandy specials.
DOSBox can emulate a Tandy machine; we only need to instruct it to do so in our config:
[dosbox]\nmachine = tandy\nEmulating the Tandy will cause the standard DOS font to be a bit different; this is normal, don\u2019t be alarmed by it.
After a restart, we\u2019re finally hearing different synthesised music which sounds definitely better than the PC speaker rendition, but not as good as the OPL music. Interestingly, the Tandy music plays a little bit faster than the other options.
Note
If you started SAMPLER.EXE without providing the ts argument to specifically ask for Tandy sound, the game will auto-detect the Sound Blaster\u2019s OPL synthesiser and prefer it over the Tandy sound. That\u2019s understandable; the game is really good at picking the best available sound device!
As an exercise, you can disable the Sound Blaster emulation altogether with the below config snippet. Then you can start SAMPLER.EXE without any arguments, and the game will use Tandy sound as that\u2019s the best available option (the PC speaker would be the only other alternative):
[sblaster]\nsbtype = none\nThe demos also support the Game Blaster, which is one of the earliest PC sound cards developed by Creative Technologies, the folks responsible for the Sound Blaster family of cards. The Game Blaster was also sold under the name Creative Music System, or just CMS for short.
To enable it, we\u2019ll need to set the emulated Sound Blaster type (sbtype) to Game Blaster (gb), and the game will auto-detect it correctly. As the Game Blaster is the precursor of the Sound Blaster lineup, it kind of makes sense to lump it into the same category under the sbtype setting.
[sblaster]\nsbtype = gb\nThe Game Blaster has a different-sounding synthesiser. Apart from its nice pure sound, another of its characteristics is that the voices play either completely on the left or on the right channel, making the music somewhat difficult to listen to through headphones. This can be easily remedied by enabling the crossfeed option which mixes a certain percentage of the left channel into the right, and vice versa:
[mixer]\ncrossfeed = on\nNaturally, you can combine crossfeed with chorus and reverb, and you can also specify a custom crossfeed amount if you\u2019re not happy with the default value of 40%:
crossfeed = 50\nTry it with headphones; the improvement is very noticeable!
"},{"location":"getting-started/passport-to-adventure/#true-ega-emulation","title":"\u201cTrue EGA\u201d emulation","text":"Many classic graphic adventure games, including most of the early Sierra and LucasArts catalogue and this collection of game demos, feature EGA graphics. The most commonly used EGA screen mode in games is 320\u00d7200 with a fixed 16-colour palette.
EGA monitors had visible \u201cfat\u201d scanlines and the pixels were a bit round, whereas later VGA monitors displayed EGA graphics without strong scanlines, and the pixels appeared as little sharp rectangles. It\u2019s as if EGA monitors had a \u201cbuilt-in filter\u201d that smoothed the image somewhat while adding a subtle texture to it as well, making it more interesting and pleasant to look at. Later VGA cards and monitors \u201cdropped\u201d this filter and were just displaying the \u201craw pixels\u201d without any such effects. This perceptual difference is because of the line-doubling peculiarity of VGA adapters in all low-resolution screen modes, as explained previously.
VGA-style line-doubling changes the feel of EGA graphics, and many prefer the original EGA look. After all, this is what the artists saw on their screens when creating the artwork. Fortunately, as we\u2019ve seen in our Prince of Persia example, you can easily emulate the \u201ctrue EGA\u201d look with shaders if that\u2019s your preference.
It\u2019s also worth restricting the image size to mimic that of a period-correct 14\u201d or 15\u201d monitor (see the detailed explanation here).
[render]\nglshader = crt/aperture\n[sdl]\nviewport_resolution = 1120x840\nIndiana Jones and the Last Crusade \u2014EGA (as displayed by VGA monitors)
Indiana Jones and the Last Crusade \u2014\u201cTrue EGA\u201d emulation
The Secret of Monkey Island \u2014EGA (as displayed by VGA monitors)
The Secret of Monkey Island \u2014\u201cTrue EGA\u201d emulation
Loom \u2014 EGA (as displayed by VGA monitors)
Loom \u2014 \u201cTrue EGA\u201d emulation
On recolouring the classics
Some adventure games that originally supported EGA graphics only also got later VGA remakes. While many of these VGA versions are competent, they rarely reach the artistic genius of the EGA originals, plus often they don\u2019t have the exact same gameplay either. This is especially true for the three classic LucasArts games included in this demo collection. You can check out the comparison and analysis of the EGA versus VGA versions of Indiana Jones and the Last Crusade and Loom here.
In another article, Brian Moriatry, the creator of Loom, shares his opinion about the VGA remake of the game (he calls it \u201can abomination\u201d, so apparently he\u2019s quite unimpressed\u2026)
In any case, the point here is it would be a mistake to outright dismiss the original EGA experiences, thinking they are \u201cinferior\u201d somehow. Even if you might prefer the VGA remakes in the end, you should at least give the EGA originals a chance.
"},{"location":"getting-started/passport-to-adventure/#cpu-sensitive-games","title":"CPU sensitive games","text":"Certain older games, such as these three demos, are sensitive to CPU speed. This can manifest in different ways:
The game may run too fast or may generally act weird if the emulated CPU is too fast (the more common case).
The game may fail the sound card detection and won\u2019t even start up (that\u2019s rarer).
This game falls into the second category. Note we\u2019re talking about the speed of the emulated CPU here, not the speed of the physical CPU in your computer!
DOSBox defaults to emulating 3000 CPU instructions, or cycles, per millisecond. For the more technically inclined among you, this corresponds to ~3 MIPS (Million Instructions Per Second). When running in windowed mode, the text in the title bar informs you about the current cycles value, e.g.:
DOSBOX - 3000 cycles/ms\nLet\u2019s see what happens if we double the emulated CPU speed!
[cpu]\ncycles = 6000\nNow we\u2019re greeted by an error when trying to start the game:
run-time error R6003\n- integer divide by 0\n\nC:\\>\nWe will discuss the CPU speed settings in more detail in the next chapter, but it was worth mentioning this interesting quirk here.
"},{"location":"getting-started/passport-to-adventure/#final-configuration","title":"Final configuration","text":"Here\u2019s the full config with all variations included as comments:
[sdl]\nfullscreen = on\n[dosbox]\n# uncomment for Tandy sound\n#machine = tandy\n[sdl]\nviewport_resolution = 1120x840\n[mouse]\nmouse_capture = onstart\n[render]\nglshader = crt/aperture\n[sblaster]\n# uncomment for Game Blaster audio\n#sbtype = gb\n[mixer]\n# change 'reverb' to 'tiny' for the PC speaker\nreverb = medium\nchorus = normal\ncrossfeed = on\n[autoexec]\nc:\n# use for PC speaker sound\n#sampler i\n# use for Tandy sound\n#sampler ts\nsampler\nexit\nWe will set up the demo version of Prince of Persia, the classic cinematic platformer from 1990 as our first example. It was a landmark game, and it can still provide countless hours of entertainment if you like platformers that require you to exercise that pesky grey matter a bit too.
First of all, we\u2019ll create a new folder for storing all our DOS games. We\u2019ll use DOS Games throughout this guide, but you can pick any name you like. It\u2019s best to create this folder in your regular documents folder so DOSBox Staging has full read and write access to it (don\u2019t put it in a system folder, e.g., Program Files on Windows). Each game will have its dedicated subfolder under DOS Games, so let\u2019s create our first one called Prince of Persia.
Now download pop1.zip from the Prince of Persia demo page and extract its contents into DOS Games/Prince of Persia. The archive contains only two files: pop1.txt (a regular text file) and pop1demo.exe (an MS-DOS executable). Let\u2019s open pop1.txt in our text editor!
It's like an Arabian Nights movie come to life... with you as the star!\nLeap into an exotic labyrinth of heart-stopping action, challenging mazes,\nintrigue and superb animation that's breathtakingly realistic!\n\nThis is a demonstration version which only has limited functionality. To\nobtain the full program, just access GO BB, and order it from our store.\nI\u2019m not quite sold on the \u201cheart-stopping\u201d part, but otherwise sounds intriguing! As indicated by the second paragraph, this is a fully playable demo version that includes only the first two levels of the game. That\u2019s more than enough for our purposes here, and you can always get the full game later.
But there are no further instructions, so what should we do next? Well, setting up old DOS games is not all that dissimilar to solving adventure game puzzles. Getting past these puzzles requires some logical thinking, a little bit of background knowledge, and an element of trial and error is occasionally involved as well. Well, the user manual often helps too if you happen to own the original, or can procure a scanned copy online (most often you can).
Luckily, this is an easy one: executable files (programs or scripts you can start) under MS-DOS have the .EXE, .COM or .BAT file extension, so looking at pop1demo.exe the solution is quite obvious: we\u2019ll need to run this executable file in DOSBox!
Most DOS games need a hard drive as a hard requirement (okay, I\u2019ll show myself to the door\u2026), but DOSBox doesn\u2019t have access to your computer\u2019s hard drive by default where your programs and documents reside\u2014we need to tell it which folder to use as its \u201cvirtual DOS hard drive\u201d. This is called mounting; we mount a folder as the \u201cDOS hard drive\u201d, the contents of which are then available to DOSBox as the C drive. All drives in DOS are assigned to the letters of the English alphabet (just like in Windows) and the C drive is usually your first hard drive.
The recommended way to mount the C drive is to create a drives subfolder inside your game folder. This drives folder is a \u201cmagic\u201d folder with a special purpose: all its subfolders having single-letter names are automatically mounted as DOS drives with the same letter. In our case, we only need a single C drive, so we\u2019ll create a c subfolder inside our drives folder (technically, it does not make a difference if you use uppercase or lowercase C on Windows and macOS; Linux people should use lowercase c). We\u2019ll then copy the files from the pop1.zip archive into drives/c to end up with the following folder structure:
Origins of the C drive
Have you ever wondered where the \u201cC drive\u201d in Windows got its name from? This is something Windows inherited from its MS-DOS heritage (which in turn inherited it from CP/M). In DOS, all drives are assigned letters from A to Z. Most computers of the era had two floppy drives, so letters A and B were reserved for them or other removable media, and the first hard drive partition was usually assigned to the letter C. We no longer have floppy drives in our computers as standard equipment, but this tradition stuck around for backwards-compatibility reasons.
Important
If you\u2019re a Windows user, do not confuse your real C drive where your operating system and programs are stored with the \u201cvirtual DOS C drive\u201d of DOSBox. It is important to understand the distinction between these two as they are completely separate concepts\u2014DOSBox will not see the contents of your real C drive by default (or the contents of any of your other drives, for that matter).
"},{"location":"getting-started/prince-of-persia/#starting-dosbox-staging","title":"Starting DOSBox Staging","text":"Okay, with our C drive set up and ready to go, the next step is to start DOSBox Staging from our DOS Games/Prince of Persia folder. This is accomplished slightly differently on each platform:
Warning
After installing DOSBox Staging, it\u2019s highly recommended to open it once using the Start Menu shortcut of the desktop icon as described here, otherwise the below instructions might not work.
If you have used the installer with the default options to set up DOSBox Staging (and it\u2019s highly recommended to do so while you\u2019re still learning the ropes), simply right-click on the Prince of Persia folder in Windows Explorer and select the Open with DOSBox Staging in the context menu.
Alternatively, you can enter the folder, right-click anywhere on the blank area inside it, then select Open with DOSBox Staging in the context menu.
macOSWarning
After installing DOSBox Staging, you must open it first using its application icon as described here, otherwise the below instructions won\u2019t work.
.dmg image file.Prince of Persia folder.You only need to perform this procedure once when opening the Start DOSBox Staging icon for the first time. After the first launch, you can use it like any other regular icon.
Tip
To avoid having to repeat these steps whenever you set up a new game, copy an icon on which you have already performed this initial procedure into your new game folder, rather than copying the original one from the .dmg file.
Open your favourite terminal, cd into the Prince of Persia directory, then run the dosbox command from there.
Make sure to check with the --version argument that you\u2019re running DOSBox Staging and not some other DOSBox variant:
% dosbox --version\ndosbox-staging, version 0.81.0\n\nCopyright (C) 2020-2022 The DOSBox Staging Team\nLicense: GNU GPL-2.0-or-later <https://www.gnu.org/licenses/gpl-2.0.html>\nAlternatively, create a shell script or a shortcut on your desktop that executes the following command:
dosbox --working-dir <PATH>\n<PATH> is the absolute path of your game directory (Prince of Persia in this case).
You\u2019ll be greeted by the following window when starting DOSBox Staging:
Let\u2019s ignore the polite welcome message for now and focus on the text below the big blue rectangle:
Local directory drives/c/ mounted as C drive\nZ:\\>_\nThe first line is pretty straightforward\u2014it tells us that DOSBox mounted drives/c we created earlier as the \u201cC drive\u201d.
The second line is the DOS prompt. DOS has a command line interface that predates graphical user interfaces we\u2019re accustomed to from modern operating systems. We get DOS to do things by typing in commands, and if manage to do this correctly, DOS will follow our instructions to the letter (pun intended!) DOS is not a multitasking operating system; you can only do a single thing in it at any given point in time.
Let\u2019s analyse the prompt a little bit. It always starts with a letter followed by a semicolon which denotes the current drive. Right after startup, this is always the Z drive. This is a special drive that\u2019s always available; DOSBox stores some of its commands on it\u2014you don\u2019t need to worry about it now.
After the semicolon is the path of the current folder or current directory in DOS terminology. This is currently the root directory of the Z drive as indicated by the \\ (backslash) character. The > character just signifies the end of the prompt, and the blinking underscore (_) character after it is\u2014guess what?\u2014the cursor.
Okay, enough theory, type in C: and then press Enter to switch to the C drive. The prompt should now reflect that we\u2019re in the root directory of the C drive:
Z:\\>c:\nC:\\>_\nType in dir and press Enter to list the contents of the current directory:
C:\\>dir\n Volume in drive C is CDRIVE\n Directory of C:\\\n\nPOP1 TXT 362 07/07/1995 10:12a\nPOP1DEMO EXE 267,420 07/05/1995 9:53a\n 2 file(s) 268,116 bytes\n 0 dir(s) 262,144,000 bytes free\nC:\\>_\nWell, that\u2019s what we put into our virtual C drive, so nothing too spectacular so far. We\u2019ll execute pop1demo.exe next! Type in pop and press the Tab key once to instruct DOSBox to complete the filename for you. This handy feature is called tab completion and it saves you from a lot of typing! Press Tab a few more times and observe how it alternates between POP1.TXT and POP1DEMO.EXE; this makes sense as these are the only two files in the current directory that start with pop.
Okay, let\u2019s make sure POP1DEMO.EXE is displayed in the prompt then press Enter to run this executable file. It turns out this is a self-extracting archive that unpacks its contents into the current directory when you run it. The following will appear (I\u2019ve redacted the list of extracted files):
C:\\>POP1DEMO.EXE\n\nPKSFX (R) FAST! Self Extract Utility Version 2.04g 02-01-93\nCopr. 1989-1993 PKWARE Inc. All Rights Reserved. Shareware version\nPKSFX Reg. U.S. Pat. and Tm. Off.\n\nSearching EXE: C:/POP1DEMO.EXE\n Inflating: CDUNGEON.DAT\n Inflating: DIGISND1.DAT\n\n ...\n\n Inflating: PRINCE.EXE\n\nC:\\>_\nThe more observant among you might have noticed the last entry, PRINCE.EXE. Bingo, that\u2019s our game executable! But let\u2019s pretend we haven\u2019t spotted it; how do we find all executables in the current directory? By issuing the dir command with the *.exe wildcard search pattern!
But instead of typing in dir *.exe, press Up a few times until dir appears in the command line, then type in the rest (Space character followed by *.exe). This handy feature is called command history\u2014you can move forward and backward in the list of previously executed commands with the Down and Up keys, respectively.
Okay, so here\u2019s how the output looks like:
C:\\>dir *.exe\n Volume in drive C is CDRIVE\n Directory of C:\\\n\nPOP1DEMO EXE 267,420 07/05/1995 9:53a\nPRINCE EXE 123,335 03/29/1990 0:00a\n 2 file(s) 390,755 bytes\n 0 dir(s) 262,144,000 bytes free\nC:\\>_\nTip
Alternatively, you can use the ls command that displays the directory contents in a wide list format. This command highlights executable files in green (.EXE, .COM, and .BAT file extensions) and directories (folders) in blue.
FAT filesystem
MS-DOS uses the FAT filesystem that allows up to 8-character filenames, followed optionally by a file extension consisting of a dot and at most three further characters. Filenames can only contain uppercase letters, digits, and certain special characters, such as the dash (-), underscore (_), and the exclamation mark (!).
The two files we originally copied to our drives/c folder had all lowercase filenames (pop1.txt and pop1demo.exe). This does not matter as DOSBox automatically converts all filenames in our drives/c folder to uppercase behind the scenes.
There\u2019s nothing else left to do than to start PRINCE.EXE (type in the letter p, press Tab to auto-complete it to PRINCE.EXE, then press Enter). After a short loading, the title screen will appear and you\u2019ll hear the classic Prince of Persia intro music playing! Don\u2019t press any key yet, just wait and watch the intro sequence until the end to learn about the game\u2019s backstory.
Prince of Persia \u2014 Title screen
Prince of Persia \u2014 Scene from the intro sequence
If you keep watching, the game will enter demo mode, where the protagonist will soon meet his untimely death\u2026 Surely, we can do better than that! Press any key to start the game!
You control the prince with the cursor keys, and you can walk carefully by holding the Shift key. It\u2019s not that hard to figure out the various movement combinations on your own, but reading the Controlling Your Movements section of the user manual should definitely help. The manual also contains helpful hints and a full list of keyboard shortcuts you can use during the game.
This is where the adventure starts!
Congratulations, you\u2019ve got your very first DOS game running in DOSBox Staging! Have some fun, try to find the sword and overcome a few guards, and maybe even attempt to complete the first level.
You can quit the game by pressing Ctrl+Q which will return you to the DOS prompt. There you can use the exit command to close DOSBox. Of course, you can quit DOSBox any time by pressing Alt+F4 on Windows and Linux, or Cmd+Q on macOS.
Note
The Ctrl+Q shortcut for quitting the game is specific to Prince of Persia. Other games might provide completely different mechanisms for exiting to DOS, or perhaps none at all.
How to approach old games
If you\u2019ve only ever played modern games, you\u2019re probably in for a bit of a culture shock! There\u2019s minimal to no handholding in most DOS games from the 1980s and the 90s; you are expected to read the user manual, often there is no in-game tutorial, and the games are generally unforgiving and require a level of dedication from the player that\u2019s uncommon in more modern titles.
However, this does not mean that these games are less fun, on the contrary! The old adage \u201cyou get out what you put in\u201d is certainly true for old DOS games. Many people (including the author of this present article) think that the satisfaction and enjoyment you get when mastering such difficult games have few parallels in the modern gaming landscape.
"},{"location":"getting-started/prince-of-persia/#auto-executing-commands-at-startup","title":"Auto-executing commands at startup","text":"Every time we want to play the game, we need to type in DOS commands to switch to the C drive and run PRINCE.EXE from there. Isn\u2019t there a way to automate this?
There certainly is! We need to create a so-called configuration file that can contain various settings to customise the behaviour of DOSBox, along with a list of commands to auto-execute at startup.
Launch your text editor of choice and create a new plain text file called dosbox.conf inside the Prince of Persia folder with the following content:
[autoexec]\nc:\nprince\nThe commands you want to be executed right after startup should be listed in the aptly titled [autoexec] configuration section, each command in a separate line. Configuration sections are introduced by names enclosed in square brackets; everything that follows belongs to that section.
Warning
Some text editors insist on appending the .txt extension after the filename you enter in their save dialog. This might result in creating a file called dosbox.conf.txt which won\u2019t work. Get to know your text editor and make sure you save the configuration file as dosbox.conf
When DOSBox starts, it looks for this special dosbox.conf file in the folder it was started from, and if it finds it, it configures the DOS environment and DOSBox itself according to its contents. This is handy because we can put a different configuration file into each of our game folders to set them up differently (this is necessary; it\u2019s simply impossible to create a single configuration that would work with all DOS games).
Just to make everything absolutely clear, this is the folder structure we should have at this point (only the first four files are shown in drives/c to save space):
Starting up DOSBox Staging from the Prince of Persia folder should now launch the game right away without any manual intervention!
So far so good\u2014now let\u2019s see how we can use the advanced features offered by DOSBox Staging to our advantage!
DOSBox vs DOSBox Staging
Astute readers might have noticed that the guide sometimes refers to \u201cDOSBox Staging\u201d and sometimes to just \u201cDOSBox\u201d. Why is that?
As explained on our about page, DOSBox Staging is a modern continuation of the original DOSBox project. Technically, DOSBox Staging is an open-source fork of and separate project from the SourceForge-hosted DOSBox project.
Generally, we use \u201cDOSBox Staging\u201d when we discuss features specific to Staging, or when we talk about the DOSBox Staging application, installer, or process itself. But when mentioning base functionality present in the original DOSBox and pretty much all other DOSBox variants, we simply write \u201cDOSBox\u201d. Admittedly, sometimes the distinction gets rather blurry, and seeing \u201cDOSBox Staging\u201d fully typed out everywhere would get old rather quickly!
Using the term \u201cDOSBox\u201d is also a nod to the original DOSBox developers to whom we are grateful for starting this awesome open-source project in the first place!
"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"about/","title":"About","text":"DOSBox Staging is a modern continuation of DOSBox with advanced features and current development practices.
It is meant as a (mostly) drop-in replacement for older DOSBox versions\u2014your existing configurations will continue to work, but you will have access to many advanced features.
Because DOSBox Staging comes with sensible defaults, you\u2019ll need to write a lot less configuration than with older DOSBox versions. Most games and application software require no tweaking and will work fine with the stock settings. However, the extensive configuration options and advanced features are available if you wish to dwelve deeper.
"},{"location":"about/#goals","title":"Goals","text":"A summary of technical and feature differences is here.
We plan to add the features listed in the backlog.
"},{"location":"about/#non-goals","title":"Non-goals","text":"Support old operating systems (Windows 9x/Me/XP, OS/2, and Mac OS X 10.5) and limited CPU/memory hardware, which are constraints DOSBox continues to support.
Support the use of Windows 9x/Me in the emulator. Windows 9x/Me emulation is supported by projects such as QEMU and VirtualBox, although DOSBox forks like DOSBox-X and DOSBox Pure also support this. This may change if wanted by the DOSBox Staging community in general.
Pursue hardware accuracy when it impacts the above goals or detracts from the source material, although config options may be added in case of issues. If you need perfect emulation in terms of accuracy, you may look at PCem and its derivatives like 86Box and PCBox, which are examples of cycle-accurate emulators.
Be the fastest DOS emulator on x86 hardware. Linux users interested in emulation speed should look at dosemu2.
Act as a general-purpose DOS operating system. For that, there is FreeDOS.
DOSBox Staging is separate from and not supported by the SourceForge-hosted DOSBox project or its development team, the DOSBox Team.
We acknowledge and are thankful for the work shared by all DOSBox contributors.
"},{"location":"about/#team","title":"Team","text":"This project is maintained by the DOSBox Staging team.
"},{"location":"about/#license","title":"License","text":"Content on this site is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.
DOSBox Staging is licensed under a GNU GPL version 2 or later.
"},{"location":"downloads/development-builds/","title":"Development builds","text":"Warning
These are unstable development snapshots intended for testing and showcasing new features; if you want to download a stable build, head on to the Linux, Windows, or macOS download pages.
Build artifacts are hosted on GitHub; you need to be logged in to download them.
Download link Build version Date\u00b9 Windows MSYS2 builds include 64-bit ZIP and Installer with both 64-bit MSYS2 (default) and 64-bit MSVC (optional).
\u00b2 Windows MSVC builds include 32-bit ZIP and 64-bit ZIP.
"},{"location":"downloads/development-builds/#installation-notes","title":"Installation notes","text":"Testing new features might require a manual reset of the configuration file. DOSBox Staging builds use a configuration file named dosbox-staging.conf located in:
~/.config/dosbox/ Windows C:\\Users\\USERNAME>\\AppData\\Local\\DOSBox\\ macOS ~/Library/Preferences/DOSBox/"},{"location":"downloads/development-builds/#linux","title":"Linux","text":"The tarball contains a dynamically-linked x86_64 build; you\u2019ll need additional dependencies installed via your package manager.
"},{"location":"downloads/development-builds/#fedora","title":"Fedora","text":"sudo dnf install SDL2 SDL2_image SDL2_net opusfile\nsudo apt install libsdl2-2.0-0 libsdl2-image-2.0-0 libsdl2-net-2.0-0 libopusfile0\nsudo pacman -S sdl2 sdl2_image sdl2_net opusfile\nWindows executables in snapshot packages are not signed, therefore Windows 10 might prevent the program from starting.
See this guide to learn how to deal with this.
"},{"location":"downloads/development-builds/#macos","title":"macOS","text":"macOS app bundles are not notarized; Apple Gatekeeper will try to prevent the program from running.
See this guide to learn how to deal with this.
"},{"location":"downloads/linux/","title":"Linux builds","text":""},{"location":"downloads/linux/#project-released-tarball","title":"Project-released tarball","text":"Download DOSBox Staging 0.80.1 (tar.xz) sha256: 12582a6496b1a276cd239e6b3d21ddfcd51fd8f9e40a1ebbc0a3800e0636190a
Check out the 0.80.1 release notes to learn about the changes and improvements introduced by this release.
Our pre-compiled builds run on most Linux distributions (x86_64 only for now). They depend on the following packages:
"},{"location":"downloads/linux/#install-dependencies-on-fedora","title":"Install dependencies on Fedora","text":"sudo dnf install SDL2 SDL2_image SDL2_net opusfile\nUbuntu 18.04 or newer, and Debian 9 or newer is required.
sudo apt install libsdl2-2.0-0 libsdl2-image-2.0-0 libsdl2-net-2.0-0 libopusfile0\nsudo pacman -S sdl2 sdl2_image sdl2_net opusfile\nDOSBox Staging is also packaged by external teams, as listed below. These packages may have variations in configuration file locations, filesystem or network restrictions, feature exclusions, and other differences compared to the project-released tarball.
To understand these potential differences, we recommend referring to the repository\u2019s documentation and, if uncertain, comparing against the project-released tarball.
The DOSBox Staging team does not track or document these differences. For issues specific to these packages, please contact the respective repository owners.
"},{"location":"downloads/linux/#containerised-packages","title":"Containerised packages","text":""},{"location":"downloads/linux/#fedora-repository-package","title":"Fedora repository package","text":"sudo dnf install dosbox-staging\nemerge games-emulation/dosbox-staging\nAvailable via Personal Package Archive:
sudo add-apt-repository ppa:feignint/dosbox-staging\nsudo apt-get update\nsudo apt install dosbox-staging\nAvailable via Arch User Repository.
"},{"location":"downloads/linux/#other-repository-packages","title":"Other repository packages","text":""},{"location":"downloads/linux/#steam","title":"Steam","text":"You can easily configure your DOS games on Steam to use DOSBox Staging via Boxtron (a community-developed Steam Play compatibility tool for DOS games).
Boxtron will automatically use dosbox if found in your path, or can be configured to use a specific binary by editing the file ~/.config/boxtron.conf and overriding dosbox.cmd:
cmd = ~/path-to-dosbox-staging/dosbox\nYou can easily configure your DOS games on Retropie to use DOSBox Staging via RetroPie-Setup (select Optional Packages \u2192 DOSBox Staging).
"},{"location":"downloads/linux/#hardware-requirements","title":"Hardware requirements","text":"From the x86 family of processors, all x86-64 processors are supported.
"},{"location":"downloads/linux/#development-snapshot-builds","title":"Development snapshot builds","text":"You can always see what\u2019s cooking on the main branch!
These snapshot builds might be slow or unstable as they are designed with developers and testers in mind.
"},{"location":"downloads/linux/#older-builds","title":"Older builds","text":"DOSBox Staging 0.80.0 (tar.xz) sha256: 3022bdd405dc1106007c3505e6a5d083de982d516c9bce499e2c4a02a697a1bd
DOSBox Staging 0.79.1 (tar.xz) sha256: aebf8619bb44934f18d0e219d50c4e2c03b179c37daa67a9b800e7bd3aefc262
DOSBox Staging 0.78.1 (tar.xz) sha256: 8bd2a247ca960f6059276db2b0331f853e16bc8a090722b15f567782542b5fba
DOSBox Staging 0.78.0 (tar.xz) sha256: 085e7cbe350546b3f25b0400c872a2766f9a49d16a5ca8d17a0a93aad6e37709
DOSBox Staging 0.77.1 (tar.xz) sha256: e2d475e4b1f80881ccafc4502b3884c096b51aa2fc2cfe89bb6c2b8ebfb7cc76
DOSBox Staging 0.76.0 (tar.xz) sha256: f8401bcd473d5b664eeb3a90e4dbb4bbf0cef5339adba867f361c00b7de9b2fe
DOSBox Staging 0.76.0 (tar.xz) sha256: b14de58ba0f5dd192398cda58fa439b15512f50d1c88b5ded6f300d4a9212852
DOSBox Staging 0.75.2 (tar.xz) sha256: 0325a1860aea95e8117aa49b041bfd628ab20531a3abc7b0a67aff4c47049465
DOSBox Staging 0.75.1 (tar.xz) sha256: aef22e5ddf93ff826fc2d48a4c8c0b4097d3455525b40be5b3fb443935929c70
DOSBox Staging 0.75.0 (tar.xz) sha256: a28d8ba0481722c8343b7532299c7b9bb9e491c6832d9d05dd4704939287f776
DOSBox Staging 0.75.0-rc1 (tar.xz) sha256: 594ba45280af240cb18b3882f7ffa71169a697eb362b7d7a76c8ccda2b940e84
Of course, you can always build DOSBox Staging straight from the source.
Send us patches if you improve something!
"},{"location":"downloads/macos/","title":"macOS builds","text":"Download DOSBox Staging 0.80.1 Universal Binary (dmg) sha256: 46a256645255e8345981ea357f1416b8ce4bc60a2aba9a86b5122d5075aa7fa9
This package is compatible with macOS 10.15 (Catalina) or newer and supports both Intel and Apple silicon Macs.
Check out the 0.80.1 release notes to learn about the changes and improvements introduced by this release.
Important
macOS uses its Gatekeeper feature to prevent users from running externally-hosted 3rd party software, such as DOSBox Staging. See the section below to learn how to fix it.
"},{"location":"downloads/macos/#homebrew","title":"Homebrew","text":"The Homebrew package is compatible with macOS 10.14 (Mojave) or newer. Learn how to set up Homebrew here.
brew update\nbrew install dosbox-staging\nThe MacPorts package should build on systems as old as macOS 10.6 (Snow Leopard, circa 2009) or newer. Learn how to set up MacPorts here.
sudo port selfupdate\nsudo port install dosbox-staging\nIf you\u2019re running an OS not longer maintained by Apple, then support is on a best-effort basis (as the team runs supported configurations and may not be able to reproduce some issues).
"},{"location":"downloads/macos/#hardware-requirements","title":"Hardware requirements","text":"This package is compatible with macOS 10.15 (Catalina) or newer and supports both 64-bit Intel and Apple silicon Macs.
"},{"location":"downloads/macos/#development-snapshot-builds","title":"Development snapshot builds","text":"You can always see what\u2019s cooking on the main branch!
These snapshot builds might be slow or unstable as they are designed with developers and testers in mind.
"},{"location":"downloads/macos/#apple-gatekeeper","title":"Apple Gatekeeper","text":"You\u2019ll need to do the following when launching DOSBox Staging for the first time (you\u2019ll need to repeat these steps every time after having upgraded to a newer version):
Apple\u2019s Gatekeeper feature only permits the running of notarized software, one aspect of which involves developers making yearly payments to Apple.
As DOSBox Staging is a volunteer effort, we are not in a position to make such payments and therefore ask users to bypass Apple\u2019s Gatekeeper manually.
"},{"location":"downloads/macos/#older-builds","title":"Older builds","text":"DOSBox Staging 0.80.0 Universal binary (dmg) (macOS 10.15 or newer) sha256: 53f12aa63cf9d2a33a46149fb394947c6b12d5ab9b7ba41ee2d7eab1a990fa7a
DOSBox Staging 0.79.1 Universal binary (dmg) (macOS 10.15 or newer) sha256: 52547692be29949747bb8d3b59bf31dd22b4f49178316417cc8f1f468eeab387
DOSBox Staging 0.78.1 Universal binary (dmg) (macOS 10.15 or newer) sha256: b9ddff89e9fc283493580d5fc021b05021a13d90305ae44e2867499b22e359c9
DOSBox Staging 0.78.0 Universal binary (dmg) (macOS 10.15 or newer) sha256: 3997546560af542b7f3b55b1bc890ae4342144a72c21af9880449adf579db88b
DOSBox Staging 0.77.1 x86-64 (dmg) (macOS 10.15 or newer) sha256: 29964d79f0a85d593f8bafd30da854c726594c12474528f46758fc95c05f0c97
DOSBox Staging 0.77.1 ARM64 (dmg) (macOS 11 or newer) sha256: 74a1c84bdda0db25091f749ba7a2e5e93f7849baf130817ea1bc182039bd3698
DOSBox Staging 0.77.0 x86-64 (dmg) (macOS 10.15 or newer) sha256: 3ca859573814b2c50065825c02d8a04eb6d95605830ec3af21de0d64a2e32314
DOSBox Staging 0.77.0 ARM64-testing (dmg) (macOS 11 or newer) sha256: e2eecb52777d5ed836ba1f772fe669c89e94ea9b67777aced5fef5b51051ccaf
DOSBox Staging 0.76.0-3 (dmg) (macOS 10.15 or newer) sha256: f6048fa0e1a33a41f0018cb6d7139c4f7b4a60176bbe6a42f681aa8b5adcb73b
DOSBox Staging 0.76.0 (dmg) (macOS 10.15 or newer) sha256: c9fa7b0bf6410f430b47daeb15a470e0105a147b555d3fbf574514406c71f492
DOSBox Staging 0.75.2 (dmg) (macOS 10.15 or newer) sha256: 272f01aa8598ecf3229d48680aa6ce6e5b88ebd0645b1f92b899bc0159afcf11
DOSBox Staging 0.75.1 (dmg) (macOS 10.15 or newer) sha256: 2508a87c6aceee63da13e4c76159734e3c9ee4e76fb22a3a7c0d66021e71a4eb
DOSBox Staging 0.75.0 (dmg) (macOS 10.15 or newer) sha256: a0038c7401d239934d25517ca5e8e6006cc3f4cb7060f6ace56609d36bca12ef
DOSBox Staging 0.75.0-rc1 (dmg) (macOS 10.15 or newer) sha256: 8a5c12d1b6567d6e981acd76e30dec41a73a699963b714f4f1dcf0fc853fc9f6
Of course, you can always build DOSBox Staging straight from the source.
Send us patches if you improve something!
"},{"location":"downloads/windows/","title":"Windows builds","text":""},{"location":"downloads/windows/#windows-8x-or-newer","title":"Windows 8.x or newer","text":"Download DOSBox Staging 0.80.1 64-bit (Installer) sha256: 94b961f397f3b70a13daf3b573857b5262515e75d490bfc19f019479fe1694f8
Download DOSBox Staging 0.80.1 64-bit (zip) sha256: e7ab98013b55f6fd6db1f529574b8f2905d374225f532ce0905666281cbe32af
Download DOSBox Staging 0.80.1 32-bit (zip) sha256: 63a8c5b084231364961f7c8b6415e44622c5ab9822e49839c2aca1bddd3a9459
Check out the 0.80.1 release notes to learn about the changes and improvements introduced by this release.
Important
If Windows 8.x or Windows 10 prevents you from running DOSBox Staging via Microsoft Defender SmartScreen, see the section below.
"},{"location":"downloads/windows/#windows-7","title":"Windows 7","text":"For 64-bit Windows 7, use the 64-bit MSVC build. It can be optionally selected in the installer and is also available as a portable ZIP archive.
For 32-bit Windows 7, use the 32-bit MSVC build portable ZIP archive
"},{"location":"downloads/windows/#windows-vista","title":"Windows Vista","text":"The official distribution packages only support Windows Vista up to version 0.78.1.
More recent releases can be built from the source by excluding FluidSynth and Slirp support. Please see the Windows MSYS2 build instructions for further details.
"},{"location":"downloads/windows/#hardware-requirements","title":"Hardware requirements","text":"From the x86 family of processors, all x86-64 processors are supported.
"},{"location":"downloads/windows/#development-snapshot-builds","title":"Development snapshot builds","text":"You can always see what\u2019s cooking on the main branch!
These snapshot builds might be slow or unstable as they are designed with developers and testers in mind.
"},{"location":"downloads/windows/#microsoft-defender-smartscreen","title":"Microsoft Defender SmartScreen","text":"You\u2019ll need to do the following when launching DOSBox Staging for the first time (you\u2019ll need to repeat these steps every time after having upgraded to a newer version).
"},{"location":"downloads/windows/#method-1","title":"Method 1","text":"Start the application, then click on More info in the appearing dialog. Click the Run anyway button in the second dialog.
"},{"location":"downloads/windows/#method-2","title":"Method 2","text":"In your installation folder, right-click on the dosbox.exe, select Properties, tick Unblock in the appearing dialog, then press Ok.
Starting in Windows 8, Microsoft Defender SmartScreen\u2019s pop-up encumbers the execution of newly-developed applications. To prevent this, developers are expected to pay Microsoft\u2019s EV certification vendors a yearly fee and put the software on Windows Store.
As DOSBox Staging is a volunteer effort, we are not in a position to make such payments. We, therefore, ask users to manually unblock DOSBox Staging and be patient while Microsoft\u2019s Application Reputation Scheme eventually whitelists DOSBox Staging.
"},{"location":"downloads/windows/#custom-install-parameters","title":"Custom install parameters","text":"The installer is built with Inno Setup. For the available command-line install parameters, please see Inno\u2019s documentation page.
"},{"location":"downloads/windows/#older-builds","title":"Older builds","text":"DOSBox Staging 0.80.0 64-bit (Installer) (Windows 7 or newer) sha256: 84445c869e58f6b4591484f6178c7b5b3c8f284bf9460e9afc4502ba842ab039
DOSBox Staging 0.80.0 64-bit (zip) (Windows 7 or newer) sha256: 075be379ed4475615e0e86953eb21f024c74b4cafd6914e9cf5ef40e3d9e26cd
DOSBox Staging 0.79.1 64-bit (installer) (Windows 7 or newer) sha256: 0045ac995ada0af955681983ae86c969a05030c25173618f8b1547a267046a27
DOSBox Staging 0.79.1 64-bit (zip) (Windows 7 or newer) sha256: 8c7045dfea6dc20bb985cff516d2faee51d2ecaf054db60632857b6941d3d648
DOSBox Staging 0.78.1 64-bit (zip) (Windows Vista or newer) sha256: 3c2f408125351154a37e93de8a4bd05d0c722bbf53e1f583909e4ca6c3eb9204
DOSBox Staging with built-in debugger 0.78.1 64-bit (zip) (Windows Vista or newer) sha256: b99f3c354f831ed2b0ed04d215170f696b6fc18285b0c7192c0abab62c41bbc8
DOSBox Staging 0.78.0 64-bit (zip) (Windows Vista or newer) sha256: f13cba664259fdb0db5e32826e13dcded4270557963f6e823a4731129f23a8a3
DOSBox Staging 0.78.0 32-bit (zip) (Windows Vista or newer) sha256: 0ca9201cdf3f3a1576b97b0de0e87280b75c633976f0b179ba33a68d44f5ba56
DOSBox Staging 0.77.1 64-bit (zip) (Windows Vista or newer) sha256: 11ba992ece6d3e4ef2046fcdb6d842da364b69720a921d61fdcc793eb52e7051
DOSBox Staging 0.77.1 32-bit (zip) (Windows Vista or newer) sha256: a34883101486ce2af071a29c6390f2038889fc519e042101284f2a6999d9f0ef
DOSBox Staging 0.77.0 64-bit (zip) (Windows Vista or newer) sha256: cacdac418642fd8c7faf1e5955110c35d0c207392ae20835707fd2a1e1114b82
DOSBox Staging 0.77.0 32-bit (zip) (Windows Vista or newer) sha256: f718d07bab69e3e1be0b28207039cea2746c7e45b8ba7a19b625011f477e609a
DOSBox Staging 0.76.0 32-bit (zip) (Windows Vista or newer) sha256: 646d2f3fa8189e411589fedcb8148a295361693a6ce95d08e06f4a70e5a36b16
DOSBox Staging 0.75.2 64-bit (zip) (Windows Vista or newer) sha256: 09f0ca911813a64b8814880eb6e49ad4dcdac9a5bb9263c4887ad82b71fad292
DOSBox Staging 0.75.2 32-bit (zip) (Windows Vista or newer) sha256: 51dc171ff52ea395c6a22f09ebb98a93974a95c701ca81008368c22a66deced2
DOSBox Staging 0.75.1 64-bit (zip) (Windows Vista or newer) sha256: 80c60c4377ff2882649f113b3cb3bcd407c17acaac344c49fa1fc4229813f012
DOSBox Staging 0.75.1 32-bit (zip) (Windows Vista or newer) sha256: 843c742a348f575862e152e02cf174be0ea1c52bdb6e4bffd65f34af88b566b7
DOSBox Staging 0.75.0 32-bit (zip) (Windows Vista or newer, supports CPUs without SSE4.2) sha256: 69046adcef2ef9920fbba8d40fc9e51f3dd144ba4549787e1816cf1c2ae87d71
DOSBox Staging 0.75.0-rc1 32-bit (zip) (Windows Vista or newer, supports CPUs without SSE4.2) sha256: 738d2ae2101384f2eeaf1895de64cf1b4c76eaf7873de7e15b7f52145dfed7e7
Of course, you can always build DOSBox Staging straight from the source.
Send us patches if you improve something!
"},{"location":"downloads/release-notes/0.75.0-rc1/","title":"0.75.0-RC1 release notes","text":"Release date: 2020-04-22
"},{"location":"downloads/release-notes/0.75.0-rc1/#installation-instructions","title":"Installation instructions","text":"This release is significant for several reasons:
It\u2019s our first stable release. From this point forward, the 0.75.x series will only contain bugfixes.
It kicks off the 0.76 development cycle, for which a number of features are already lined up.
The new project homepage makes the downloads publicly accessible, without the need for a GitHub account.
There\u2019s no human-readable changelog just yet\u2014there are ~1500 commits to comb through. Hopefully, within a couple of days, we\u2019ll be able to write a nice summary with a description of new features, improvements, and bugfixes.
In the meantime, we invite everyone to start testing RC1 builds; there are some rough edges for sure\u2014if you find any bugs, please report them in our bugtracker. You can also ask questions on the #dosbox\u2011staging channel in Luxtorpeda Discord Server.
This release includes all upstream changes until SVN r4336, and 857 Git commits on top of that.
Have fun!
The DOSBox Staging team
"},{"location":"downloads/release-notes/0.75.0/","title":"0.75.0 release notes","text":"Release date: 2020-05-06
"},{"location":"downloads/release-notes/0.75.0/#summary","title":"Summary","text":"This document contains the release notes for DOSBox Staging 0.75. It describes recently added, changed, or deleted features of DOSBox Staging.
All users are encouraged to consult the New features in detail and Known issues sections before using DOSBox Staging, as these describe important interface changes as well as information discovered late in the release cycle or after the release.
"},{"location":"downloads/release-notes/0.75.0/#installation-instructions","title":"Installation instructions","text":"The DOSBox Staging project was created September 15, 2019 as a soft-fork of the SourceForge-based DOSBox project, which is a separate project having its own schedule and development priorities.
"},{"location":"downloads/release-notes/0.75.0/#new-features-in-detail","title":"New features in detail","text":"New features originating from our upstream (DOSBox) are marked with SVN.
"},{"location":"downloads/release-notes/0.75.0/#upgrade-to-sdl-20","title":"Upgrade to SDL 2.0","text":"SDL 2.0 is a major update to the SDL 1.2 codebase, which has been unmaintained since 2013. SDL 2.0 supports more input devices; more output interfaces such as Wayland, and OpenGLES 1 and 2; low-latency audio using OpenSL ES; and improves cross-platform consistency.
The migration to SDL 2.0:
One example includes the new texture output mode, which uses SDL\u2019s 2D hardware-accelerated API rendering to a platform-specific backend.
For example, Windows users can test:
[sdl]\noutput = texture\ntexture_renderer = direct3d11\nmacOS users can try Metal:
[sdl]\noutput = texture\ntexture_renderer = metal\nAnd everyone can use OpenGL as texture backend:
[sdl]\noutput = texture\ntexture_renderer = opengl\nOr just use texture_renderer = auto to let SDL pick the backend appropriate for your operating system.
FLAC, Opus, and MP3 (as well as MP2 and MP1) encoded audio can be imgmounted as CD-DA tracks in DOSBox Staging, in addition to the usual WAV and Vorbis tracks supported by DOSBox. WAV support has been expanded to include Sony\u2019s Wave64 format.
DOSBox Staging also supports tracks having sample resolutions of 24 and 16-bit; sampling rates of 96, 88.2, 48, 44.1, 22.05, and 11.025 kHz; and stereo or mono channel counts (to the extent each codec supports these variations). You can mix-and-match these properties and track types to best suit each track\u2019s content.
The following sample CUE file depicts the use of every codec supported by DOSBox Staging:
FILE \"data.iso\" BINARY\n TRACK 01 MODE1/2048\n INDEX 01 00:00:00\n\nFILE \"track02.opus\" OPUS\n TRACK 02 AUDIO\n PREGAP 00:02:00\n INDEX 01 00:00:00\n\nFILE \"track03.flac\" FLAC\n TRACK 03 AUDIO\n INDEX 01 00:00:00\n\nFILE \"track04.mp3\" MP3\n TRACK 04 AUDIO\n INDEX 01 00:00:00\n\nFILE \"track05.w64\" W64\n TRACK 05 AUDIO\n INDEX 01 00:00:00\n\nFILE \"track06.ogg\" OGG\n TRACK 06 AUDIO\n INDEX 01 00:00:00\n\nFILE \"track07.wav\" WAV\n TRACK 07 AUDIO\n INDEX 01 00:00:00\nFor devices with sufficient storage, we recommend ripping your CD-ROM audio to (lossless) FLAC tracks and adding seek-points using:
flac -8 --output-name=trackXY.flac trackXY.wav\nmetaflac --add-seekpoint=1s trackXY.flac\nFLAC typically achieves between 50% and 35% compression while producing binary-identical output versus WAV files.
For limited-storage devices such as ARM single-board computers, Opus provides state-of-the-art lossy compression that exceeds all other formats, including Apple\u2019s AAC and AAC High-Efficiency formats. Opus allows even further space savings over MP3 or Vorbis track while matching or exceeding them in output quality.
For example, CD-DA tracks consisting of monaural speech can be encoded with:
opusenc --speech --bitrate 24 --downmix-mono trackXY.wav trackXY.opus\nWhen applied to Sierra\u2019s Jones in the Fast Lane audio track, Opus compresses it from 373 MB down to 6.4 MB (98.2% savings in disk space) with no discernible loss in quality.
For CD-DA tracks consisting of sound effects and relatively simple music, Opus does fine with a bitrate between 54 and 70, whereas more complex musical tracks might need a bitrate of up to 84. Experiment and find your sweet spot!
opusenc --bitrate 70 trackXY.wav trackXY.opus\nIf your CD-DA tracks are encoded at 48 kHz (which is Opus\u2019s default internal rate), then feel free to configure DOSBox Staging\u2019s mixer rate to match, which ensures your CD-DA will not be resampled through your audio chain; as your sound card, USB speakers, and HDMI interface all (likely) operate at a native rate of 48 kHz.
[mixer]\nrate = 48000\nPixel-perfect output scales the image by the largest integer multiplier that fits within your monitor\u2019s native resolution. For example, given a 1920\u00d71080 monitor and a 320\u00d7200 game requiring aspect-correction, each of its pixels would be scaled by 4\u00d75 to produce a 1280\u00d71000 image. This preserves the original artwork without any edge blurring.
To enable pixel-perfect output, apply the following settings to the indicated sections of your DOSBox Staging configuration file, as follows:
[sdl]\nfullscreen = true\noutput = texturepp\n[render]\nscaler = none\nglshader = none\nPixel-perfect looks like this on a 1080p screen:
Heroes of Might and Magic II (1996) \u2014 640\u00d7480 with a pixel aspect ratio (PAR) of 1:1, upscaled to 2\u00d72
Wolfenstein 3D (1992) \u2014 320\u00d7200 with a PAR of 1:1.2 (non-square pixels), upscaled to 4\u00d75 with a PAR of 1:1.25
"},{"location":"downloads/release-notes/0.75.0/#resizable-window","title":"Resizable window","text":"Being able to click and drag to resize an application\u2019s window is not a revolutionary feature by any measure; however it\u2019s a welcome addition for DOSBox Staging!
Star Wars: Dark Forces (1995) \u2014 intro playing while the DOSBox window is being resized vigorously
This feature is a work-in-progress: it\u2019s available on Linux by default, and can be enabled for testing on Windows and macOS by setting the following (but note that it does not yet work correctly on these systems):
[sdl]\nwindowresolution = resizable\nOn all systems, the resizable window is only available for output = opengl and glshader = sharp. Support will be expanded to more outputs and shaders in the future versions.
AUTOTYPE is a command-line tool provided by DOSBox Staging that performs scripted keyboard entry into the running DOS program or game.
It can be used to reliably skip intros, provide input to answer initial startup or configuration questions, or conduct a simple demo.
Simply run the command to learn more:
Z:> autotype\nSome games that benefit from AUTOTYPE on startup are listed on the wiki page.
The following default configuration settings were changed to improve the out-of-the-box experience for the majority of games running on modern hardware.
The default video settings now use SDL\u2019s OpenGL rendering backend, apply a 4:3 aspect ratio correction, and scale the image using the sharp OpenGL shader to provide relatively sharp pixels when in fullscreen mode.
Battle Chess (1989) \u2014 at 1080p using the default settings
"},{"location":"downloads/release-notes/0.75.0/#expand-mouse-control-methods","title":"Expand mouse control methods","text":"The prior \u201cautolocking\u201d mouse option used by DOSBox has been renamed in DOSBox Staging to capture_mouse, which is configured using two values defining how the mouse behaves.
The first value defines how the mouse is controlled:
onclick: the mouse will be captured with a click inside the windowonstart: the mouse is captured immediately on start (similar to real DOS)seamless: the mouse will move seamlessly in and out of the window and cannot be capturednomouse: the mouse is disabled and hidden without any input sent to the gameThe second value defines how middle-clicks are handled:
middlegame: middle-clicks are sent to the game (not used to uncapture the mouse)middlerelease: middle-click will uncapture the mouse when windowed (not sent to the game)For example:
[sdl]\ncapture_mouse = onclick middlerelease\nThis will capture the mouse on the first click inside DOSBox Staging\u2019s window, and a middle-click will release the mouse. Note that the prior method to release the mouse still works (pressing Ctrl+F10).
Note
DOSBox Staging defaults to seamless mouse capture both to simplify multi-tasking in windowed-mode and provide a frustration-free experience for new users. However, some games and Windows 3.1 make their own adjustments to the mouse position and will cause an offset-effect. In these cases, we recommend switching to fullscreen (Alt+Enter) or configuring the mouse to capture onclick or onstart.
Important
These options do not affect the mouse behavior in fullscreen (Alt+Enter), as the mouse is always captured.
"},{"location":"downloads/release-notes/0.75.0/#nuked-opl-v18","title":"Nuked OPL v1.8","text":"The cycle-accurate Nuked OPL3 emulator is now used by default; this change improves AdLib and Sound Blaster FM music emulation accuracy.
This improved accuracy comes at the cost of a slightly higher CPU use, which is insignificant for the vast majority of users on typical desktop or laptop hardware.
However, those using DOSBox Staging on old or CPU-limited hardware (capable of 30,000 dosbox \u201ccycles\u201d or less, such as the Raspberry Pi 3) will be served best using the fast OPL emulator (see the oplemu documentation provided in the configuration file).
The built-in CONFIG shell command is a bit old, but a little-known feature allows users to reconfigure DOSBox Staging at runtime. This is a nifty way to change configuration using batch scripts based on user input.
You can now change key bindings at runtime by loading them from a file:
Z:\\> config -set \"sdl mapperfile=<path-to-file>\"\nDOSBox added a number of features to the CONFIG command. To list them all, run:
Z:\\> config /?\nDOSBox Staging\u2019s configuration file location has been updated to comply wit the XDG Base Directory Specification. This means DOSBox Staging will no longer create configuration directories directly in your home directory.
Configuration files are now located in:
~/.config/dosbox/\nUsers can customize the parent (.config/) location by setting the XDG_CONFIG_HOME environment variable, according to the XDG Specification.
The path was slightly changed to avoid spaces in the default configuration filename and to group all configuration files in a single directory:
~/Library/Preferences/DOSBox/\nNo changes; the configuration files are created in:
C:\\Users\\<username>\\AppData\\Local\\DOSBox\\\nYou can map fake phone numbers to Internet addresses which is useful for programs where limitations on phone number input field are too strict. Create a text file with the name specified in phonebookfile entry in the [serial] section in the DOSBox configuration file and add phone-address pairs per line, for example:
5551234 towel.blinkenlights.nl:23\nNow you can dial the specified phone number and the emulated modem will connect to the address it\u2019s mapped to. Note that phone book does not allow any characters in the phone number that are ignored or denied by a real Hayes compatible modem.
"},{"location":"downloads/release-notes/0.75.0/#64-bit-dynamic-recompilation-svn","title":"64-bit dynamic recompilation (SVN)","text":"DOSBox has had dynamic recompilation support for a long time, but it was limited to 32-bit builds. Support for 64-bit dynarec improves CPU emulation speed and quality across the board\u2014this is especially visible to Linux and macOS users1.
Stargunner (1996, freeware) \u2014 running on Linux x86_64 via Boxtron
Before 64-bit dynarec, this game had serious emulation problems resulting in fluctuating emulation speed (sometimes too fast, sometimes too slow - regardless of cycles settings). This game was designed to run with constant 70 FPS and now it runs with constant 70 FPS.
"},{"location":"downloads/release-notes/0.75.0/#cga-improvements","title":"CGA improvements","text":"Maniac Mansion (1988) \u2014 with forced CGA mode: top-left: CGA, default palette; top-right: CGA mono, green tint; bottom-left: CGA composite, early model, default hue; bottom-right: CGA composite, late model, default hue.
"},{"location":"downloads/release-notes/0.75.0/#cga-monochrome-mode","title":"CGA monochrome mode","text":"Many CGA games from the 80\u2019s were designed to support monochromatic cathode-ray tube (CRT) monitors that used either an amber, green, or grayscale-shaded phosphor coating. As such, some games look much better when rendered using a similar monochrome palette. This mode is designed to emulate such displays.
Use machine = cga_mono to turn on the feature. You can switch between green, amber, white, and paper-white palettes at runtime by pressing F11.
Technical artifacts caused by the composite video format were cleverly used by game developers to generate extra colors (versus non-composite CGA) by manipulating pixel positions on the screen. For example, adjacent pixels would be partly \u201caveraged\u201d (through horizontal overlap), producing interposed solid colors or generating rudimentary transparency effects.
Composite mode was added to DOSBox\u2019s CGA emulator in 2012, but was never back-ported to any of its stable releases. Most users are familiar this mode as its commonly included in other DOSBox forks.
Once enabled, you can switch between color and composite modes, early and late CGA models, and adjust the hue at runtime.
Note
The default keybinding for manipulating CGA modes conflict with other essential bindings; it\u2019s advisable to change them if you plan to use this feature. The default key for turning on composite mode is F12.
"},{"location":"downloads/release-notes/0.75.0/#glsl-shader-support-svn","title":"GLSL shader support (SVN)","text":"Shaders written in OpenGL Shading Language (GLSL) offload the task of processing the emulated game\u2019s output to your GPU hardware.
This allows the image to be altered in many ways, such as emulating the analog artifacts (scanlines, shadow masks, and phosphor glow) present in circa-1980s and 90s CRT monitor on modern 1080p and greater LCD panels.
You can can select the shader to use by setting the glshader config param:
[render]\nglshader = sharp\nIt\u2019s also possible to provide your shader implementations by placing .glsl files in the configuration directory:
~/.config/dosbox/glshaders/ macOS ~/Library/Preferences/DOSBox/glshaders/ Windows C:\\Users\\<USERNAME>\\AppData\\Local\\DOSBox\\glshaders\\ E.g. if you put a shader file called test.glsl in your config directory, you can select it as follows:
glshader = test.glsl\nNote
When using a GLSL shader, we recommend setting the scaler type to none to ensure image post-processing is performed exclusively by the shader (and not a mix of the two).
Star Wars\u2122 \u2014 X-Wing: Collector\u2019s CD-ROM Edition (1994) Using CRT-Lottes shader on a 1080p screen; click on the image to enlarge it to see the fine details. This shader is not bundled with DOSBox Staging (yet); you can download it from here.
"},{"location":"downloads/release-notes/0.75.0/#date-and-time-commands-svn","title":"DATE and TIME commands (SVN)","text":"The traditional DATE and TIME DOS commands have been added to DOSBox. This allows the user to change the date seen by the software running inside the emulated environment:
Z:\\> date\nCurrent date: Fri 05/01/2020\nType 'date MM-DD-YYYY' to change.\n\nZ:\\> time\nCurrent time: 11:08:23,34\nNote that while the date can be changed, the time cannot.
This feature is useful for running old batch scripts and bypassing date checks in some old software.
"},{"location":"downloads/release-notes/0.75.0/#mount-overlay-support","title":"Mount overlay support","text":"This feature allows the user to redirect new and changed files to a different location transparently. The files in the overlay and normal drives are merged at startup and kept up to date when the game writes to the disk.
This feature is useful for redirecting save files or configuration files to a different location (e.g. for backup or cloud saves).
Example usage:
Z:\\> mount C real\nDrive C is mounted as local directory real/\n\nZ:\\> mount C backup -t overlay\nOverlay backup/ on drive C mounted.\n\nZ:\\> C:\nC:\\> echo foo > test.txt\n\nC:\\> type TEST.TXT\nfoo\nFile TEST.TXT is written to the directory backup, and not to real.
ddraw) output. Use output = texture, texture_renderer = directx11 instead.overlay output. Use any other output.windowresolution = X%).Migrated the DOSBox source from Apache\u2019s Subversion (SVN) software versioning and revision control system to the Git distributed version-control system using GitHub, while preserving all publicly available project history.
svn/<name>).svn/<tag-name>).Ongoing upstream SVN development work is being imported in a timely manner to the Git branch named svn/trunk.
C++11 language constructs are now allowed.
Implemented a Continuous Integration (CI) system that builds on every code push to provide immediate feedback to developers regarding build-success and warning-counts on:
Windows x86_64 using GCC 32 and 64-bit, Clang 32 and 64-bit, and VisualStudio 64-bit compilers
macOS x86_64 using GCC and Clang compilers
Linux x86_64, ARMv6, ARMv7, IBM LinuxONE, and IBM POWER8 platforms using various versions of GCC and Clang
Added static analysis checks performed by LLVM\u2019s Clang, Synopsys\u2019s Coverity, and VIVA64\u2019s Program Verification Systems (PVS) Studio.
Added dynamic analysis checks performed by Clang\u2019s undefined-behavior (UB) sanitizer and GCC\u2019s UB and address sanitizers.
The CI system includes gated checks that allow maintainers to focus on code functionality and correctness. These automated checks guarantee that new code:
Notable progress has been made in reducing the number of warnings and analysis issues flagged by these tools.
Windows: the build-system was adjusted to allow easy compilation, without manual download or patching of dependencies. We use vcpkg to manage dependencies. The solution file was fixed to work with Visual Studio 2019.
Linux and macOS: implemented a number of small build-system improvements.
Automated the compilation of release-style builds against the latest main and feature branches. These not only save time for testers wanting to verify new features and bugfixes, but also ensures they\u2019re running builds compiled using would-be release settings.
macOS: release binaries are compiled with optimizations supporting Intel Nehalem-based instructions (and newer), as this matches the minimum processor requirements set by macOS Catalina.
Release packages are scanned using up-to-date Antivirus software: ClamAV for Linux and macOS, and Windows Defender for Windows.
The project has published a Code of Conduct along with clear Contributor Guidelines.
windowresolution = resizable when leaving fullscreen.Submit new issues or learn more about existing ones using our bug-tracker.
"},{"location":"downloads/release-notes/0.75.0/#contributors","title":"Contributors","text":"During the DOSBox Staging 0.75 development period:
Library or patch authors, upstream SVN developers, etc.
You can read detailed changelog via Git, e.g. using the following command:
git shortlog ^v0.75.0-pre v0.75.0 --no-merges\nThe following lists those merges performed by maintainers either on behalf of, or making use of, patches or libraries authored by community members (in alphabetic order).
kcgen
Patryk Obara
Peter Veenstra
Changes merged-in to SVN
Add several builtin shaders that mimic the scalers and some extra (jmarsh)
Fix xcmpchg in dyn_x86 core. Allows Quickview to work in that core (jmarsh)
Additional refinements and speed ups (jmarsh)
Switch to a different way to calculate the table offsets (jmarsh)
Fix boundary checks for word/dword memory access. Speeds up dynamic 32 bit core a bit (jmarsh)
Add 64-bit support to dynamic_x86 core from vogons topic 67673 (jmarsh)
Michael Zijlstra
We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
DOSBox Staging 0.75.0 stable Windows build is still 32-bit; Linux and macOS builds are 64-bits.\u00a0\u21a9
Release date: 2020-08-19
"},{"location":"downloads/release-notes/0.75.1/#summary","title":"Summary","text":"This is a small bugfix release from 0.75.x stable branch\u2014it includes a few changes and bugfixes backported from upcoming 0.76.x version.
"},{"location":"downloads/release-notes/0.75.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
Brave souls interested in the latest features can test our work-in-progress 0.76.x\u00a0alpha builds . Please report any issues in our bugtracker.
Also, check out our growing Wiki.
"},{"location":"downloads/release-notes/0.75.1/#new-features-in-detail","title":"New features in detail","text":""},{"location":"downloads/release-notes/0.75.1/#add-support-for-binding-more-controller-axes","title":"Add support for binding more controller axes","text":"Users can now comfortably use both sticks, as commonly found on modern controllers (like DualShock or any Xbox controller). Previously, only one stick could be mapped.
This change does not make old games \u201cmagically\u201d recognize all features of modern controllers. You need to map additional controller events to emulated keyboard, mouse, or joystick events using DOSBox\u2019s keymapper (Ctrl+F1).
This was a highly-requested community patches that wasn\u2019t accepted by the upstream DOSBox project. We\u2019ve included the 10-axes per controller version of the patch in DOSBox Staging.
"},{"location":"downloads/release-notes/0.75.1/#provide-windows-x64-builds","title":"Provide Windows x64 builds","text":"Windows 64-bit builds are now provided alongside 32-bit builds. Additional performance optimizations (WPO) are enabled for both builds. Linux and macOS builds have been similarly optimized using LTO since the 0.75.0 release.
Both Windows builds now require SSE 4.2 instruction set, which is now on par with the Linux and macOS builds that have required SSE 4.2 support since the 0.75.0 release.
Steam Hardware survey indicates that 97.45% users have CPUs supporting SSE 4.2, so your CPU is very likely good enough
"},{"location":"downloads/release-notes/0.75.1/#log-base-address-of-emulated-memory","title":"Log base address of emulated memory","text":"This change was created per request from users of Cheat Engine, but it might be useful for other memory scanners/debuggers as well.
Base memory address of DOS\u2019s emulated memory region is now logged to the console:
MEMORY: Base address: 0x5c758e0\nMEMORY: Using 4096 DOS memory pages (16 MiB)\nUsers previously had to debug the dosbox binary to discover the base address; an easy but tedious process.
"},{"location":"downloads/release-notes/0.75.1/#bugfixes","title":"Bugfixes","text":"Correct CD audio playback for games using single BIN/CUE; fixes a regression in The Secret of Monkey Island. (#385)
Fix build issue for Windows x64 target after VS2019 update. (#389)
Fix a crash happening after bindings for 2 controllers were added and then one controller is disconnected. (#405)
Fix a crash on exit after removing controller actions bound to keyboard events. (#405)
Prevent crash on SDL2 re-creating OpenGL window. (#509)
Provide detailed help for DIR /? command. (#506)
Fix pixel-perfect mode not respecting aspect = false setting. (#544)
You can read detailed changelog via Git, e.g. using the following command:
git shortlog ^v0.75.0 v0.75.1\nWe are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"downloads/release-notes/0.75.2/","title":"0.75.2 release notes","text":"Release date: 2020-10-26
"},{"location":"downloads/release-notes/0.75.2/#summary","title":"Summary","text":"This is a maintenance release from the 0.75.x stable branch.
"},{"location":"downloads/release-notes/0.75.2/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
When emulating monochrome displays (via machine = hercules or machine = cga_mono), the default colour palette can now be set to either white, paperwhite, green, or amber in the configuration file, as follows:
[render]\nmonochrome_palette = amber\nSee: #607
"},{"location":"downloads/release-notes/0.75.2/#raw-mouse-input","title":"Raw mouse input","text":"You can enable this option to bypass the operating system\u2019s mouse acceleration and sensitivity settings. This works in fullscreen or when the mouse is captured in windowed mode.
The option can be set in the [sdl] section of the configuration file:
[sdl]\nraw_mouse_input = true\nThe feature is disabled by default, but some games (e.g. FPS titles, like DOOM or Dark Forces) work better with raw input enabled (especially when used with modern, very sensitive gaming mice).
See: #636
"},{"location":"downloads/release-notes/0.75.2/#bugfixes","title":"Bugfixes","text":"Bundle C++ runtime libraries with Windows builds for users on Windows 7, 8.x, and those who disabled Windows 10 update mechanism. (#675)
Reimplement CLS command to prevent text mode reset. (#639)
Fix whitespace handling in modem ATD command. (#652)
Fix boot failure when using HDD image. (#522)
This release includes numerous fixes affecting our build system and other changes relevant for packaging (contributed by Gentoo packagers, and people preparing Debian, Fedora, and Flatpak packages)\u2014prompt upgrade is recommended.
If you\u2019re packaging DOSBox Staging for your OS, we have a few tips:
We strongly suggest keeping our default binary name: dosbox. DOSBox\u00a0Staging is a drop-in replacement for older DOSBox versions\u2014some existing and popular programs, such as Wine and GUI frontends, depend on the dosbox binary name. It\u2019s also the default name of our man page and appears in the documentation.
You don\u2019t need to generate your own desktop entry, appstream metadata (metainfo.xml), nor package description: please see the relevant files in the contrib/linux/ directory.
We provide desktop icons in scalable or raster formats (optimized for small sizes). Find them in the contrib/icons/ directory.
During the configuration step, remember to add -DNDEBUG to preprocessor flags (it\u2019s important!), as well as using -O3 in both C and C++ compiler flags, for example:
./configure CPPFLAGS=\"-DNDEBUG\" CFLAGS=\"-O3\" CXXFLAGS=\"-O3\"\nOur testing indicates that GCC generates faster binaries than Clang, but use whatever compiler is more appropriate for your OS.
The license is \u201cGNU GPL version 2.0 or later\u201d (SPDX: GPL-2.0-or-later). GitHub does not show \u201cor later\u201d, but our packages should show the proper license info.
To all our package maintainers: thank you!
"},{"location":"downloads/release-notes/0.75.2/#contributors","title":"Contributors","text":""},{"location":"downloads/release-notes/0.75.2/#maintainers","title":"Maintainers","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"downloads/release-notes/0.76.0/","title":"0.76.0 release notes","text":"Release date: 2020-12-03
"},{"location":"downloads/release-notes/0.76.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
This release introduces significant enhancements to the quality of audio emulation (GUS, built-in MIDI, PC speaker), improved support for PowerPC and POWER8 architectures, and a healthy mix of usability, documentation, code quality improvements.
Enjoy!
"},{"location":"downloads/release-notes/0.76.0/#new-features-in-detail","title":"New features in detail","text":""},{"location":"downloads/release-notes/0.76.0/#gravis-ultrasound-emulation-improvements","title":"Gravis UltraSound emulation improvements","text":"Sample from Rise of the Triad (1995). For other comparisons see link.
Using headphones is highly recommended!
GUS emulator Sample (FLAC) Old implementation Your browser does not support theaudio element. New implementation (with improvements) Your browser does not support the audio element. Several changes have been made to the GUS emulation resulting in (sometimes) audible differences, as follows:
Output volume is now typically on-par with other audio devices.
Panning of voices is now performed using constant-power, as described in the Gravis\u2019 SDK documentation. Constant-power panning was originally researched by the British Broadcasting Corporation (BBC) and found to produce the most realistic perception of voice placement on a radial axis from the listener.
When quitting DOSBox Staging, information about the game\u2019s GUS audio stream will be provided, such as the breakdown of 8-bit versus 16-bit samples. A potential suggestion to adjust the game\u2019s GUS mixer level, either upward or downward may also be provided, which you could paste into your game\u2019s startup batch file or [autoexec] section.
We recommend using GUS emulation for the handful of DOS games that natively support the GUS\u2019s multi-voice feature. For a list of these games, see: GUS Native games.
For more details about DOSBox Staging\u2019s GUS support and enhancements, see: GUS\u00a0Enhancements.
For information about constant-power panning, see pages 7 and 8 of the BBC R&D White Paper.
"},{"location":"downloads/release-notes/0.76.0/#built-in-glsl-shaders","title":"Built-in GLSL shaders","text":"Two high-quality shaders that emulate the visual look of an analog CRT monitor are now included:
glshader = crt-easymode-flat: for DOS games using resolutions 640\u00d7400 or higher.glshader = crt-fakelottes-flat: for DOS games using smaller resolutions (e.g. 320\u00d7200).Jazz Jackrabbit (Holiday Hare 1995 Edition) \u2014 showcasing crt-fakelottes-flat
Jazz Jackrabbit (Holiday Hare 1995 Edition) \u2014 showcasing crt-fakelottes-flat (zoomed-in view)
FluidSynth 2.x, a powerful and accurate MIDI synthesizer, has been integrated into DOSBox to directly support MIDI playback. This means you no longer need to use an external MIDI synthesizer (but it\u2019s still possible, of course).
Configure your game to use General MIDI (GM) output on port 330 and update your DOSBOX Staging config as follows to start using it:
[midi]\nmididevice = fluidsynth\nmpu401 = intelligent\n[fluidsynth]\nsoundfont = my-favourite-soundfont.sf2\nDOSBox will look for soundfont files in the soundfonts directory within your configuration directory and in additional platform-specific directories (e.g. /usr/share/soundfonts/ on Linux).
You can also use absolute paths or paths relative to the current working directory (for bundling .sf2 files in game directories).
Some SoundFonts can be \u201clouder\u201d than others, such as Timbres of Heaven. You can provide an optional volume-scaling percentage after the SF2 filename, such as:
soundfont = timbres_of_heaven.sf2 20\nThis will reduce the SoundFont\u2019s volume to 20%.
Most games that play MIDI music provide an in-game volume adjustment, but some games may not save your settings while others may not even allow this adjustment. For these games, use the mixer FSYNTH command to set your desired MIDI output volume either in your startup batch file or the [autoexec] section in the game\u2019s config file, e.g.:
C:\\>mixer FSYNTH 33\nThis is very much a matter of personal opinion. We\u2019ve compiled a list of SoundFont recommendations suitable for DOS gaming on our wiki.
Linux users: if you have the fluid-soundfont installed on your OS, it will be picked up automatically by default.
"},{"location":"downloads/release-notes/0.76.0/#integer-scaling-pixel-perfect-option-for-opengl-output","title":"Integer scaling (pixel-perfect) option for OpenGL output","text":"Integer scaling (aka pixel-perfect mode) is now also available via OpenGL.
You can test integer scaling by setting the following output options:
output = openglpp \u2014 OpenGL + integer scaling. This option is used to provide backwards compatibility with other DOSBox forks.
output = texturepp \u2014 SDL2 texture backend + integer scaling. This option was added in 0.75.0.
These two options behave pretty much the same, except Linux users can enjoy resizable windows with output = openglpp.
Examples running fullscreen on 1080p display:
The Lost Vikings (1993) \u2014 with integer scaling
Epic Pinball (1993) \u2014 with integer scaling
Tip
Integer scaling works best for games that use square pixels; most DOS games use non-square pixels (often using resolution 320\u00d7200 / PAR 5:6)\u2014for those titles sharp-bilinear scaling (DOSBox Staging default setting) works better.
This video essay by Displaced Gamers provides a great explanation:
DOS Gaming Aspect Ratio \u2014 320\u00d7200
The output = openglpp option with windowresolution = resizable is also a good choice for text mode DOS applications as it produces sharp text (but sacrifices the proper DOS font aspect ratio):
Turbo Pascal in windowed mode with pixel-perfect scaling
"},{"location":"downloads/release-notes/0.76.0/#dynamic-recompilation-for-powerpc-and-power8-ppc64le","title":"Dynamic recompilation for PowerPC and POWER8 (ppc64le)","text":"Roughly two years ago jmarsh of the vogons.org forums published a feature-complete dynamic recompilation patch supporting the PowerPC (32-bit) architecture. This was quickly expanded by the community to support the POWER8 (64-bit) architecture as well. Both patches (with slight improvements) were merged to DOSBox Staging.
Shoutout to the AmigaOS community for the help with thoroughly testing this significant PowerPC contribution!
"},{"location":"downloads/release-notes/0.76.0/#quick-edit-and-find-your-configuration-file","title":"Quick-edit and find your configuration file","text":"It can be cumbersome to edit and find your default dosbox-staging.conf file. You might not know where it\u2019s located or it might be hidden away due to certain OS settings.
These two command-line options can help:
dosbox --editconf, opens the .conf file in a text editor.
This option respects the EDITOR environment variable if set to your prefered editor. Otherwise, it uses one of the following: nano, vim, vi, notepad++.exe, or notepad.exe.
dosbox --printconf, prints the path to the .conf file.
The ls (list directory contents) command is widely available across Unix-based operating systems. Most users of modern OSes are more likely to have it in their muscle memory rather than the DIR DOS command.
A very simple implementation of ls has been added that resembles the default operation of GNU ls:
Windows 3.11 listed using dir /w /p \u2014 not enough space to show all files, hard to distinguish between files and directories
The same directory listed using ls \u2014 more efficient utilisation of space in 80\u00d725 DOS text mode, easier to read
Audio speakers work by pushing and pulling their diaphragm at a rate equal to the audio\u2019s frequency.
Physical PC speakers can sometimes be left in a pushed-out or pulled-in state through constant voltage, called DC offset, which typically isn\u2019t a problem on real hardware. However in DOSBox, the PC speaker\u2019s offset samples mix with those from other audio sources such as the Sound Blaster or Adlib, which can:
Cause a pop if the next sample played has a position significantly different from the position of the DC offset.
Harm accurate sound reproduction of other sound devices by moving half the waveform further away from the center line (making it louder) and the other half of the waveform closer to the center line (making it quieter).
This new configuration option, zero_offset under the [speaker] section, defaults to 'auto'. It\u2019s enabled for non-Windows systems and disabled on Windows as some of its audio drivers appear to attempt their own DC offset correction.
For more details about this change, see: #480
For a discussion about Windows 10 performing DC offset correction, see: #625
The game has left the PC speaker in an offset position, which is detected and silently \u201cwound down\u201d in a fraction of a second.
"},{"location":"downloads/release-notes/0.76.0/#audio-pop-and-click-prevention","title":"Audio pop and click prevention","text":"Some games generate audio pops or clicks during startup. We\u2019ve added two changes to reduce these occurences:
On startup, the game greets our ears with an unatural instantaneous pop. In the second image, we see the enveloper briefly in action ramping the instaneous volume to prevent the pop.
For more visuals and detail about the enveloper, see: #442
For a list of many more games that had their pops cleaned up, see: #411
On startup, Lands of Lore: The Throne of Chaos\u2019s audio driver blasts our ears with two instantaneous pops, which are eliminated after suppression.
"},{"location":"downloads/release-notes/0.76.0/#splash-screen-and-help-banner-verbosity-control","title":"Splash screen and help banner verbosity control","text":"The splash screen and its delay, as well as the blue help banner, can now be skipped using the startup_verbosity setting in the [dosbox] section in the config file. The verbosity can be set as follows:
high shows everything: the splash screen, blue help banner, and initial console output.
medium skips just the splash screen and its delay, but still shows the blue help banner and initial console output.
low skips both the splash screen, delay, and blue help banner, but still shows initial console output.
quiet skips all of the above. The first output will either be the command prompt or output from startup executables or batch files.
By default, the verbosity is set to auto, which is either low when an executable or directory is passed on the command-line or high when DOSBox Staging is started without initial commands.
For a visual depiction of the options, see: #477
"},{"location":"downloads/release-notes/0.76.0/#revise-help-messages-for-mount-and-imgmount-commands","title":"Revise help messages for MOUNT and IMGMOUNT commands","text":"These commands are usually thoroughly documented in the manual, but having usage examples at your fingertips is more convenient. Help can be invoked by passing one of the following parameters: /? (DOS style), or -h, --help (GNU style).
Read more in: #729
Revised help messages provide usage examples, common parameter descriptions, and use a limited set of colours to improve readability.
"},{"location":"downloads/release-notes/0.76.0/#improve-telnet-mode-handling-for-modem-emulation","title":"Improve Telnet-mode handling for modem emulation","text":"For those hosting a BBS behind a Telnet interface, you can now pre-configure your serial port in Telnet-mode with the telnet:1 argument, as follows:
[serial]\nserial1 = modem telnet:1 listenport:2323\nFor those dialling BBSs hosted behind a Telnet interface, use the following dial-prefix: AT+NET1DT. In general, the +NET1 or +NET0 AT-command will enable or disable Telnet-mode, respectively.
This change brings Telnet-mode in-line with the Hayes multi-character command specification, which should be compatible with existing BBS software.
For more background about this change, see: #582
When telnet-mode is set according to the remote BBS\u2019s needs, you will experience fast and corruption-free transfers.
"},{"location":"downloads/release-notes/0.76.0/#fix-setting-file-timestamp","title":"Fix setting file timestamp","text":"DOS function 5701h \u201cSet File Time/Date\u201d was implemented.
This corrects a long-standing emulation issue when it comes to date handling of files created in DOS (e.g. when files are being unpacked from an archive). This fixes some game installers and other software that checks file modification times.
"},{"location":"downloads/release-notes/0.76.0/#case-insensitive-paths-handling","title":"Case-insensitive paths handling","text":"Paths passed to commands mount, imgmount, and audio track paths in .cue and .ins files are now treated as case-insensitive, regardless of the operating system.
Fixes numerous issues with running DOS games on Linux or FreeBSD. This change alone corrects the vast majority of Windows-only DOS game releases on GOG or Steam (such as e.g. Settlers II, Redneck Rampage, or Mortal Kombat* series)\u2014users no longer need to manually adjust the paths after unpacking games from Windows installer. This should significantly improve the quality of Lutris installers as well.
"},{"location":"downloads/release-notes/0.76.0/#revise-default-keyboard-shortcuts","title":"Revise default keyboard shortcuts","text":"The default keyboard shortcuts were revised to avoid triggering conflicting OS default shortcuts. We\u2019ve only changed those that that were not typically used by general users.
The list of new default shortcuts are:
Keymapper received tiny usability improvements as well: it displays the keyboard shortcut (binding) for the selected action.
"},{"location":"downloads/release-notes/0.76.0/#monochrome-palette-colour-setting","title":"Monochrome palette colour setting","text":"When emulating monochrome displays (Hercules or CGA/monochrome), the default colour palette can now be selected in the configuration file.
This feature was backported to 0.75.2 release; read more.
"},{"location":"downloads/release-notes/0.76.0/#raw-mouse-input-setting","title":"Raw mouse input setting","text":"User can now bypass the operating system\u2019s mouse acceleration and sensitivity settings. This works in fullscreen or when the mouse is captured in window mode.
This feature was backported to 0.75.2 release; read more.
"},{"location":"downloads/release-notes/0.76.0/#10-axis-controller-support","title":"10-axis controller support","text":"Old joysticks compatible with DOS games can be emulated using modern 10-axis controllers (like DualShock or Xbox controllers).
This feature was backported to 0.75.1 release; read more.
"},{"location":"downloads/release-notes/0.76.0/#log-memory-base-address","title":"Log memory base address","text":"The base memory address of DOS\u2019s emulated memory region is now logged to the console to help some users of external software, such as Cheat Engine.
This feature was backported to 0.75.1 release; read more.
"},{"location":"downloads/release-notes/0.76.0/#bugfixes","title":"Bugfixes","text":"Some notable bugfixes:
dir /p in non-standard text modes. (#528)capture_mouse middlegame setting. (#563)cls command. (#639)Fix Pentium CPUID to indicate CPU without FDIV bug. (#694)
(from SVN) Multiple bugfixes and regression fixes for various games or demoscene productions, such as Clue: Master Detective (1989), (8c002), Pleasure\u2019n Pain demo (8c07c, e9a67), MayDay demo (b6e77), PC Tools 9, and others.
(from SVN) Set Precision Exception in FRNDINT (Round to Integer instruction), to avoid bug when running Borland Pascal pow implementation. (7892b)
(added on 2020-12-04) Windows x64 builds are not available for now due to regression after building in Visual Studio 16.8.2. (#746)
The W^X memory protection (enabled by default via e.g. SELinux) prevents dynamic recompiler from working. (#253)
Keymapper has problems with mapping multiple axes when multiple controllers are plugged in (e.g. notably when using modern joysticks and throttles connected at the same time). (#342)
GLSL shader implementation crashes on certain Intel GPUs on Arch. (#319)
Mapping key scancodes on X11 using xmodmap can break SDL2 ability to detect your keyboard layout and leave you with non-functional keyboard input. Use udev instead of xmodmap to prevent this problem.
Some users of Gnome 3.38.1 experience problems when toggling fullscreen (both X11 and Wayland). This seems to be a Gnome issue; if you experience it as well, please make a report in the bugtracker.
Option gusrate in the [gus] section was removed. The revised Gravis UltraSound emulation implementation made this option obsolete.
Option oplrate in the [sblaster] section was removed. This value is now automatically tied to rate in [mixer] to avoid resampling (so users do not need to manually correlate values for these two options any more).
Project switched to using C++14.
We introduced unit tests (using Google Test framework). At the moment, unit tests are running on Linux only\u2014to build them use --enable-tests configure flag and make test to run them. They are included in CI gating.
Windows x64 builds were added to Visual Studio solution (both Debug and Release profiles).
CI was extended with gating based on MSVC (32-bit and 64-bit builds)
Due to instability and extremely slow installation times MSYS2 was removed from gating CI. It is still included in our daily builds, but we do not recommend using MSYS2 for development.
Linux builds for ARMv6, ARMv7, ARMv8 (AArch64), ppc64le, and s390x architectures were added to our set of daily builds.
We fixed all -Wall -Weffc++ warnings on Linux and macOS and corrected a large number of issues detected via static and dynamic code analysis tools.
When the project started we inherited 1411 warnings from DOSBox; as of November 2020, the builds are finally clean, so it\u2019s easier to make sure we do not introduce new warnings.
"},{"location":"downloads/release-notes/0.76.0/#changes-merged-from-upstream-projects","title":"Changes merged from upstream projects","text":"During DOSBox Staging 0.76 development period we merged 1035 commits, including 55 commits originating from the DOSBox project.
"},{"location":"downloads/release-notes/0.76.0/#maintainers","title":"Maintainers","text":"SVN r4336:r4392
We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"downloads/release-notes/0.77.0/","title":"0.77.0 release notes","text":"Release date: 2021-07-02
"},{"location":"downloads/release-notes/0.77.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
Migrated Staging from autotools to the Meson build system. Those building from source, please see BUILD.md in the repository. See: #854
Added write-xor-execute page support to comply with the latest macOS and SELinux security policies
Thanks to jmarsh and Jonathan Campbell for discussions on vogons. See: #1031
"},{"location":"downloads/release-notes/0.77.0/#variable-expansion-in-the-interactive-dos-shell","title":"Variable expansion in the interactive DOS shell","text":"See: #1059
"},{"location":"downloads/release-notes/0.77.0/#finished-fluidsynth-integration","title":"Finished FluidSynth integration","text":"FluidSynth is now included in all release binaries. See the wiki notes for how to use it. Run MIXER /LISTMIDI in the DOS shell to see your available soundfonts.
Thanks to:
Christian Lestrade for authoring this support in 2005, and all subsequent maintainers.
Meson for adding FluidSynth to the WrapDB.
The MT-32 emulator is now included in all release binaries. See the wiki notes for how to use it. Run MIXER /LISTMIDI in the DOS shell to see the available MT-32 models and versions.
See the list of unmissable MT-32 experiences, courtesy vogons.org forum user Shreddoc and contributors.
Thanks to:
Canadacow for authoring MT-32 emulation in 2003, KingGuppy and Mok for the follow-on work, and SergM who continues to maintain and improve the Munt project today.
Meson for adding libmt32emu to the WrapDB.
Microsoft for adding libmt32emu to Vcpkg.
See the wiki notes for how to use it.
Thanks to JMK for authoring PS/1 Audio emulation in 2008.
"},{"location":"downloads/release-notes/0.77.0/#innovation-ssi-2001-audio-device-support","title":"Innovation SSI-2001 audio device support","text":"See the wiki notes for how to use it.
Thanks to:
Vasyl for authoring SSI-2001 emulation in 2006.
Dag Lem for authoring, and Antti Lankila and Leandro Nini for improving the SID chip emulator.
Replaced the default Ctrl+F1 - F12 hotkeys on macOS with Cmd+F1 - F12 to reduce conflicts with the OS.
Thanks to Antti Peltola, Burrito78, and Kirk Klobe for guidance and testing.
"},{"location":"downloads/release-notes/0.77.0/#translation-improvements","title":"Translation improvements","text":"Added or improved translations for French, Italian, Polish, Russian, and Spanish.
Thanks to Draky50110 (fr), Kappa971 (it), dreamer (po), IlyaIndigo (ru), and Peluchito (es).
"},{"location":"downloads/release-notes/0.77.0/#improved-startup-settings","title":"Improved startup settings","text":"Added splash_only to the startup_verbosity settings. This shows the splash but skips the help banner.
Three relative window sizes, small, medium, or large, are now understood by the windowresolution config setting. These T-shirt sizes correspond to a window that\u2019s 25%, 50%, or 80% of your desktop\u2019s area, regardless of DPI or type of monitor (be it 720p, 1080p, or 4K).
Window resizing using corner-drag is now auto-enabled on all platforms when conditions permit.
"},{"location":"downloads/release-notes/0.77.0/#bugfixes","title":"Bugfixes","text":"The following user-visible bugs were fixed:
Will no longer lose focus on Raspberry Pi when launched fullscreen in an Xorg session. (#995)
Release builds now use dosbox-staging.conf as the primary config file instead of dosbox-staging-git.conf. (#932)
Windows release builds once again mount Opus CD-DA tracks, which was a regression in 0.76. (#885)
AUTOTYPE now works with all games. Until now, a subset of games didn\u2019t respond to its keystrokes. (#942)
Shoulder triggers on some six-axis controllers, such as the PS4 and Logitech\u2019s F310 and F710 controllers, can now be mapped. (#944)
When toggling out of fullscreen mode, in some corner cases this resulted in a blank window. This is now fixed. (#1096)
The 0.77 release includes 920 commits plus 35 commits originating from the DOSBox project.
"},{"location":"downloads/release-notes/0.77.0/#dosbox-staging-members","title":"DOSBox Staging members","text":"The following members actively supported the project during the 0.77 timeframe:
The following authors, co-authors, wiki editors, translators, testers, and bug reporters directly contributed to the 0.77 release:
The following DOSBox authors\u2019 SVN commits (r4393 through r4459) were merged during the 0.77 timeframe:
The following patch or external project authors\u2019 sources were merged during the 0.77 timeframe:
We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
The project maintains original authorship on all commits (including those from upstream, patches, and external projects) to ensure correct attribution is recorded in the version control system.
"},{"location":"downloads/release-notes/0.77.1/","title":"0.77.1 release notes","text":"Release date: 2021-08-28
"},{"location":"downloads/release-notes/0.77.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
The following user-visible bugs were fixed in 0.77.1 (reported-by; fixed-by):
Fix crash when using 32-bit build and the dynamic-core on Windows 10 (Banjo-Oz; kklobe).
Fix crash when using 32-bit build and the dynamic-core on Raspbian (nemo93; kklobe).
Fix degraded joystick control during once-a-month integer time-rollover event (cimarronm).
Fix inability for a program to use its own bundled HELP and CHOICE executables (SmilingSpectre; Wengier).
Fix inability to map joystick events when joysticktype was configured as none (GranMinigun; kcgen).
Fix incorrect setup of the joystick when type configured as 2axis (choum; kcgen).
Fix input control lag on some Windows systems and on macOS when the \u201cMagnet\u201d GUI management program is running (Burrito78; kcgen).
Fix mouse control in Alive \u2013 Behind the Moon (DOSBox SVN r4461/ripsaw8080).
Fix performance regression when building releases on arm-based Linux SBC (mrfixit2001).
Fix potential Tseng ET3000 video mode corruption (DOSBox SVN r4460; ripsaw8080).
Fix resizing of window impacting the debugger TUI on Windows (DOSBox SVN r4462; ripsaw8080).
Fix potential crash when quickly Alt+Tabing on Windows (kklobe).
Fix size and placement of video content when using a resizeable window mode (bmunger; kcgen).
Fix unformattable content in translation files (dreamer; kcgen).
French, German, Italian, Polish, Russian, and Spanish users: move the bundled translations directory into your DOSBox Staging configuration directory.
macOS users
Right click the dosbox-staging.app file and select \u201cShow Package Contents\u201d. The translations folder is inside Contents/resources/.
After the move, you will have:
Linux/home/username/.config/dosbox/translations/ macOS ~/Library/Preferences/DOSBox/translations/ Windows C:\\Users\\<username>\\AppData\\Local\\DOSBox\\translations\\ Load your language on the command-line:
dosbox -lang de\ndosbox -lang es\ndosbox -lang fr\ndosbox -lang it\ndosbox -lang pl\ndosbox -lang ru\nOr via primary or local config file:
[dosbox]\nlanguage = de\n# de, es, fr, it, pl, ru\nTip
Use dosbox -editconf to open your config file.
For future reference, the above is also discussed in the README.
"},{"location":"downloads/release-notes/0.77.1/#thank-you","title":"Thank you","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox Team and the DOSBox-X Team.
DOSBox Staging maintains original authorship on all commits to ensure attribution is recorded in the version control system (git).
"},{"location":"downloads/release-notes/0.78.0/","title":"0.78.0 release notes","text":"Release date: 2021-12-25
"},{"location":"downloads/release-notes/0.78.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
Added Universal binary for macOS, supporting x86-64 and ARM64 (Kirk Klobe) (#1240)
Added a workaround for vsync lag, which is useful for video outputs that enforce vsync (Kirk Klobe) (#1158)
Added window size and placement customizations (John Novak) (#1272)
Added full /help output text for the AUTOTYPE, BOOT, CALL, CHOICE, CLS, COPY, DIR, ECHO, EXIT, GOTO, HELP, IF, INTRO, KEYB, LS, MD/MKDIR, MEM, RD/RMDIR, REN/RENAME, RESCAN, SHIFT, SUBST, and TYPE commands (Wengier) (#1356)
Added MSYS2-based release builds and instuctions for those on Windows using MSYS2 (Sherman Perry) (#1443)
Merged PCjr composite patch by NewRisingSun. Thanks to JKapp76 for testing and feedback (NewRisingSun) (#1122)
Merged CGA composite improvement patch by reenigne, respectively. Thanks to JKapp76 for testing and feedback (reenigne) (#1157)
Added bash-shell completion. See contrib/linux/bash-completion/README for adding this to your shell (FeignInt) (#1200)
Added Loguru, a fast cross-platform logging subsystem. Logs are now time-stamped and warnings are now colorized (Kirk Klobe) (#1225)
Merged S3 video patch by s3freak. This adds more video modes and supports up to 8 MiB of video memory, vmemsize = 8, when using machine = svga_s3. Thanks to Zorix, Grounded0, Brandon Roberts, GranMinigun, Kirk Klobe, and nemo93 for testing (s3freak) (#1244)
Added configurable FluidSynth chorus and reverb settings. Thanks to GranMinigun for the extensive listening tests (kcgen) (#1268)
Added auto-exit. When an executable that\u2019s passed on the command-line exits, then so too will the emulator. This is equivalent to manually adding the -exit command-line flag. Thanks to Burrito78 for testing (kcgen) (#1269)
Added layered and portable configuration file handling. Thanks to JKapp76, Grounded0, and Burrito78 for testing (kcgen)
Added ENet (reliable UDP) as an option for modem and null-modem transport, as well as SERIAL.COM for runtime serial-port configuration (Scott Duensing) (#1398)
Added support for virtual Ethernet and TCP/IP networking via slirp (Jookia) (#1419)
Added support for networking in Windows for Workgroups 3.11 from the shell. Previously networking in WfW was only possible when booting a real MS-DOS installation from a bootable HDD image (Wengier, nanshiki) (#1447)
Added IDE controller support, authored by joncampbell123 of the DOSBox-X project, for CD-ROM image-mounts, which is useful for CD-ROM based games that also happen to need a real DOS environment such as Revell\u2019s car games, like European Racers (joncampbell123, Wengier) (#1451)
Fixed 32-bit dynamic core crashes (Kirk Klobe) (#1205)
Fixed regression when setting windowresolution in the config file. Thanks to arrowgent for the report and testing (kcgen) (#1144)
Fixed hanging in Mortal Kombat Trilogy when joysticktype = none. Thanks to nemo93 for the report and GranMinigun for also testing (kcgen) (#1241)
Fixed regression during shutdown while using the ALSA sequencer. Thanks to AaronBPaden for the report and testing (kcgen) (#1362)
Fixed zero-offset PC Speaker issue on Windows 11. Thanks to ggpettas for reporting (kcgen) (#1389)
Fixed regression that broke video recording. Thanks to Grounded0 for reporting and testing (kcgen) (#1400)
Fixed ability to run an application-provided help.exe|com program. Thanks to SmilingSpectre for reporting (Wengier) (#1136)
Removed VESA modes 320\u00d7200\u00d715/16/24, which were added late in the 90s and were not properly supported by some games (NicknineTheEagle) (#1457)
Translations (de, es, fr, it, pl, and ru) are included with the release package and can be selected using the two-letter country code either via environment variable (LANG=de), config file ([dosbox] language = it), or command-line (-lang ru). See Section 14 in the README file for more details.
To ensure authors are credited for their work, the project records authorship on all commits in the version control system, including all works from the upstream DOSBox project, patch authors, and external projects.
0.78 author Lines changed arrowgent 361 Brandon Roberts 1495 Burrito78 1882 Christer Solskogen 4 Dan Church 2 David Reid 6733 Eli Schwartz 6 GranMinigun 1204 Gregory Pakosz 1178 John Novak 668 Jookia 2296 Kappa971 2773 kcgen 63022 Kirk Klobe 1658 llm 6 NicknineTheEagle 30 Patryk Obara 103 ripsaw8080 59 s3freak 648 Scott Duensing 7330 Sherman Perry 5408 Sjoerd van der Berg 28 Wengier 5430 Yann Collet 2438 ykhwong 7During the 0.78 timeframe, DOSBox SVN commits r4466 through r4471 were merged to the project and authorship is reflected above.
"},{"location":"downloads/release-notes/0.78.0/#wiki-authors","title":"Wiki authors","text":"0.78 wiki author Lines changed Alberto Salvia Novella 164 Burrito78 2 Grounded0 557 John Novak 12 Joshua Fern 30 kcgen 243 Kirk Klobe 2 LowLevelMahn 14 MasterO2 395 nemo93 5370 Tobias Gruetzmacher 5"},{"location":"downloads/release-notes/0.78.0/#financial-contributors","title":"Financial contributors","text":"Antti Peltola: Project sponsor. His combined contribution of 4,000 USD spanning the 2021 period to maintainers and the project has allowed the team to add a dedicated Apple M1 build host. Thank you!
Burrito78: Project backer. Thank you!
To support our work, join the Open Collective.
"},{"location":"downloads/release-notes/0.78.0/#thank-you","title":"Thank you","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"downloads/release-notes/0.78.1/","title":"0.78.1 release notes","text":"Release date: 2022-01-07
"},{"location":"downloads/release-notes/0.78.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
Maintenance changes to 0.78.1 are as follows (reported-by; fixed-by):
Fixed a crash when exiting fullscreen mode and also using OpenGL output (NicknineTheEagle; kcgen)
Fixed a crash and host input lockup when using SDL\u2019s kmsdrm video driver (GranMinigun)
Fixed an early exit bug when using the -exit and -c exit command-line arguments (pheener and d10sfan, kcgen)
Fixed a memory leak when changing one or more serial port types at runtime (kcgen)
Fixed a regression that failed to apply aspect correction when using pixel-perfect output modes (Diduz; kcgen)
Fixed a regression that disabled the keyboard input when using the debugger (LowLevelMahn; kcgen)
Fixed a regression that impacted 32-bit performance on some Windows systems (RaymanXY; Kirk Klobe and kcgen)
Fixed a regression that causes a crash when opening UPX-compressed code-page files (FeralChild64; Wengier)
Improved the modem\u2019s command-mode handling (NicknineTheEagle)
Corrected the modem\u2019s DTR drop delay units from ms to hundredths of a second (NicknineTheEagle)
Reverted the allowance that let the VESA refresh rate use the host rate (RaymanXY; kcgen)
Allowed read-only image mounting for write-protected disk and floppy images (Burrito78; Wengier)
Updated the German messages and config file text (Burrito78)
Updated the Italian messages and config file text (Kappa971)
Fixed a documentation conflict describing the command line\u2019s version flag (arrowgent)
Documented how to install gmock, a dependency added during 0.78.0, on Fedora (oturpe)
Fixed a compilation issue with Loguru on ARM32 using GCC 8 (rtissera; kcgen)
Fixed a compilation issue with older C++17 compilers missing std::filesystem support (jowtron; gulrak and kcgen)
Fixed a build tool-specific bug that exposed the UI when running gmock tests (oturpe and voyageur; brandonrobertz and kcgen)
The MSYS2-built debugger will fail to open if launched from the Windows UI.
As a work-around, run it from within a command console.
Thanks to Sherman Perry for investigating this issue and isolating it
Audio might stutter on some Windows platforms. If your system is affected, adjust the mixer\u2019s settings in your config file as follows:
[mixer]\nblocksize = 1024\nprebuffer = 25\nTip
Run dosbox -editconf to open your config file.
Thanks to Genju for reporting this regression and isolating the solution.
We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"downloads/release-notes/0.79.0/","title":"0.79.0 release notes","text":"Release date: 2022-09-19
"},{"location":"downloads/release-notes/0.79.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
It should run everything that prior versions did.
The default settings will give you improved audio, refined graphical scaling and colour accuracy, more robust mouse handling, and a more usable shell.
There are new and some deprecated config settings: your console log will inform you with orange-coloured warning messages to help you.
For performance-demanding games that use max cycles, it should provide just as much performance (or a bit more) than prior versions.
International users: it should detect your language and keyboard layout on startup. We recommend reading the Localisation section for details.
Repo packagers: learn about bundled resource files and the updated Meson build settings.
Read on for all the details!
"},{"location":"downloads/release-notes/0.79.0/#audio-improvements","title":"Audio improvements","text":""},{"location":"downloads/release-notes/0.79.0/#adlib-gold-surround-module-emulation","title":"AdLib Gold Surround Module emulation","text":"The ultra-rare AdLib Gold surround sound daughterboard is now emulated, which makes it possible to finally enjoy the Dune soundtrack in its full glory! That\u2019s the only game in existence that makes use of the surround module.
The following config is recommended for Dune. The setup utility should auto-detect AdLib Gold and the surround module correctly with these settings.
[sblaster]\nsbtype = sb16\noplmode = opl3gold\nMost DOS-era sound cards feature an output low-pass filter (and sometimes a high-pass filter too) that play an important role in giving their sound its character. DOSBox Staging can now accurately emulate these analog output stage filters for all supported sound devices.
"},{"location":"downloads/release-notes/0.79.0/#sound-blaster","title":"Sound Blaster","text":"For backward compatibility reasons, the sb_filter config parameter defaults to the newly introduced modern filter, which uses the simple linear interpolation method of previous DOSBox versions. To turn on accurate analog output filter emulation, set the sb_filter to auto. This will set the correct filters for each Sound Blaster model depending on the sb_type value. You can also set a model-specific filter manually if you wish, e.g. this is how to use a Sound Blaster 16 but with Sound Blaster Pro filters:
[sblaster]\nsbtype = sb16\nsb_filter = sbpro1\nSome Sound Blaster models can toggle the filter on and off in software; you can force the filter to be always on by setting sb_filter_always_on to true.
OPL and CMS filters are also accurately emulated; please refer to the descriptions of the opl_filter and cms_filter config parameters for further details.
Filters are enabled by default for all small-speaker audio systems (PC Speaker, PS/1 Audio, Tandy, and the various LPT DAC options). Depending on the particular device, these filters either emulate the analog output filters of the original device, or the sound coming out of a small band-limited speaker in an acoustic environment. Either way, the result is a more period-accurate and pleasant listening experience, especially on headphones.
Small-speaker filters are controlled by the following config parameters:
lpt_dac_filterpcspeaker_filterps1audio_dac_filterps1audio_filtertandy_dac_filtertandy_filterAdvanced users can specify custom filter settings for any of the supported sound devices. You can specify either a high-pass filter, a low-pass filter, or both at the same time using the following format
TYPE ORDER FREQ [TYPE ORDER FREQ]\nwhere TYPE can be hpf (high-pass) or lpf (low-pass), ORDER is the order of the filter from 1 to 16 (1st order results in a 6dB per octave slope, 2nd order in a 12dB per octave slope, etc.), and FREQ is the filter\u2019s cutoff frequency in Hz.
For example, to use a 2nd order (12dB/oct) low-pass filter at 8 kHz for the Sound Blaster:
sb_filter = lpf 2 8000\nTo use a 3rd order (18dB/oct) high-pass filter at 120 Hz, and a 1st order (6dB/oct) low-pass filter at 6.5 kHz for the PC Speaker:
pcspeaker_filter = hpf 3 120 lfp 1 6500\nIn addition to the sound devices mentioned above, you can use custom filters even with devices that don\u2019t filter the output in the original hardware (e.g. GUS, MT-32), and the FluidSynth virtual MIDI device via the following config parameters:
fsynth_filtergus_filterinnovation_filtermt32_filterListening to audio material on headphones where certain sounds are only present in either the left or the right channel can be a rather distracting and unpleasant experience. This is most noticeable on certain Dual OPL game soundtracks and tracker music (e.g. MOD, XM, S3M, IT, etc.)
The new crossfeed feature remedies that; by enabling crossfeed in the [mixer] section, a certain percentage of the left channel is mixed into the right, and vice versa. The default crossfeed strength is 40% which is a good general setting, but you can provide a custom percentage value as well (e.g. crossfeed = 55).
The amount of crossfeed can be fine-tuned per individual channels via mixer commands; please type MIXER /? in the DOSBox prompt for further details.
One of the most exciting new audio features is the ability to add reverb (the emulation of real acoustic spaces) and chorus effects to any mixer channel. This can add a lot of atmosphere to dry-sounding synth soundtracks (typically OPL music) and elevate them to a whole new level! Enabling reverb and chorus processing is especially useful for headphone-listening.
The quickest way to enable the reverb effect globally is to put reverb = on in the [mixer] config section. This will add reverb to all synth channels (e.g. PC Speaker, OPL, CMS), and a lesser amount to digital audio channels (e.g. Sound Blaster, GUS). While the default setting works well with most games, it\u2019s highly recommended to experiment with the five available reverb presets to find the optimal setting for each game:
tiny simulates the sound of a small integrated speaker in a domestic room. This preset is specifically tailored for small-speaker audio systems (PC Speaker, Tandy, PS/1 Audio, and LPT DAC devices).
small adds a subtle sense of space; it\u2019s best suited for games that use a single synth (typically OPL) for both the music and the sound effects.
medium is the default preset; it\u2019s a middle-of-the-road setting that works well with a wide variety of games.
large is a large hall-style reverb that is recommended for games that use separate audio channels for music and digital audio (e.g. OPL audio and Sound Blaster digital sound.)
huge is a stronger variant of the large hall preset which is ideal for slower-paced, atmospheric music.
Another way to add a sense of space to the sound is by enabling the chorus effect. This adds stereo movement and increases the perceived stereo width, which is especially noticeable on purely mono signals on headphones (e.g. PC Speaker or OPL2 music). To enable it, just put chorus = on into the [mixer] config section, or select one of the three predefined chorus strength presets (light, normal, and strong).
Similarly to crossfeed, per-channel reverb and chorus settings can be tweaked by mixer commands; please type MIXER /? in the DOSBox prompt for details.
Audio examples
Naturally, you can combine chorus and reverb, and it\u2019s not only possible to do so, but highly recommended for achieving the best results! The below recordings showcase how crossfeed, reverb, chorus, and output stage filters can work in tandem to give old DOS game soundtracks a new life.
The exact settings used for these recordings are documented on the wiki, along with suggested audio configs for many other games. Make sure to check them out and experiment with the settings yourself! \ud83d\ude0e \ud83d\udd09 \ud83c\udfa7
Your browser does not support thevideo element. Alone in the Dark (1992, floppy version) \u2014 introduction
Game Type Audio example Alone in the Dark(floppy version) OPL2 Your browser does not support theaudio element. Warcraft: Orcs & Humans OPL3 Your browser does not support the audio element. Dungeon Master II:The Legend of Skullkeep Dual\u00a0OPL2 Your browser does not support the audio element. Ultima Underworld I: The Stygian Abyss Dual OPL2 Your browser does not support the audio element. Elvira: Mistress of the Dark Dual\u00a0OPL2 Your browser does not support the audio element. Skate or Die! Tandy Your browser does not support the audio element. Zak McKracken and the Alien Mindbenders Tandy Your browser does not support the audio element. Budokan: The Martial Spirit CMS Your browser does not support the audio element The Secret of Monkey Island CMS Your browser does not support the audio element."},{"location":"downloads/release-notes/0.79.0/#master-compressor","title":"Master compressor","text":"An auto-levelling dynamic range compressor has been introduced to the master channel to ensure that the audio output never gets distorted, no matter how high the volume levels are. This is on by default and is virtually transparent when the output is not driven into clipping. However, purists can disable it by setting compressor to off, and then ensure correct non-clipping output levels manually.
The mixer now uses a full 32-bit floating-point processing path internally, which means you can no longer overload individual mixer channels into clipping by using high per-channel volume settings. As long as the summed master output is not clipping, it\u2019s guaranteed that nothing else will.
A fixed high-pass filter at 20 Hz has been introduced right before the final output that gets rid of any DC-offset and subsonic rumble globally.
The MIXER command has received an overhaul too. First of all, the status output looks better, and the following improvements have been made:
Now you can set reverb, chorus, and crossfeed levels per mixer channel; type MIXER /? in the DOSBox prompt for further details.
The FM channel has been renamed to OPL.
The SPKR channel has been renamed to PCSPEAKER.
The sample rate column has been removed (it served no useful purpose, and the displayed values were often technically correct but misleading).
For a high-level overview of the new mixer architecture, please refer to this diagram.
NukedOPL has long been the default OPL mode in Staging. As it\u2019s basically a bit-perfect emulation of the Yamaha YMF262 OPL3 chip, and it runs fast enough even on low-end hardware such as the Raspberry Pi 4, all other less accurate OPL emulation modes have been removed.
"},{"location":"downloads/release-notes/0.79.0/#fluidsynth-configuration-changes","title":"FluidSynth configuration changes","text":""},{"location":"downloads/release-notes/0.79.0/#fluidsynth-reverb-and-chorus","title":"FluidSynth Reverb and Chorus","text":"Due to the introduction of the new mixer-level reverb and chorus effects, the FluidSynth reverb and chorus config parameters have been renamed to fsynth_reverb and fsynth_chorus, respectively.
To maintain backward compatibility with existing configurations, the FluidSynth reverb and chorus effects are enabled by default, so all your SoundFonts will sound just like in previous DOSBox versions. If you enable the mixer-level reverb (or chorus) as well (e.g. by putting reverb = on in the [mixer] section), you would get a second round of reverb (or chorus) processing on the FluidSynth output. This is by design as it allows users the greatest level of control over customising SoundFonts (e.g. some would sound best with the FluidSynth reverb only, some with both, etc.)
Note
In the SF2 format the reverb and chorus amounts are specified on a per-instrument basis, while the mixer-level effects are applied \u201cglobally\u201d to all instruments in the summed FluidSynth output. Therefore, what works best really depends on the particular SoundFont in question and on individual user preference (see this discussion for further technical details).
"},{"location":"downloads/release-notes/0.79.0/#volume-scaling","title":"Volume Scaling","text":"Previously, it was possible to specify a percentage after the SoundFont\u2019s name in the config to adjust its volume (e.g. soundfont = way_too_loud.sf2 30). This was introduced as a workaround for certain loud SoundFonts that tended to clip the mixer channel internally.
With the new floating-pointing mixer signal path, it\u2019s no longer possible to drive any of the mixer channels into clipping, therefore this workaround has been deprecated. Please use standard mixer commands to lower the volume of the FSYNTH channel if you wish to do so.
We\u2019ve integrated ripa\u2019s impulse-model PC speaker patch alongside DOSBox\u2019s existing (discrete-model) PC speaker implementation, which is still the default.
To use it, set the pcspeaker config setting to impulse (or go back to default with discrete).
James-F and VileRancour have mentioned in the linked thread that it generally improves the accuracy of square-wave effects, such as in Commander Keen and Duke Nukem (2D). This patch also can produce sounds when none previously existed, such as in Wizball, as noted by ripsaw8080.
For example, here\u2019s Wizball using the settings below:
[mixer]\nrate = 32000\n[speaker]\npcspeaker = discrete\nvideo element. Wizball (1987) \u2014 using discrete PC speaker emulation
Note
There are some audible regressions and harmonics that still exist in some games, so that\u2019s why this is an alternative and not the default.
"},{"location":"downloads/release-notes/0.79.0/#parallel-port-dac-models-disney-covox-and-stereo-on-1","title":"Parallel port DAC models: Disney, Covox, and Stereo-On-1","text":"Those familiar with DOSBox know that these three devices are emulated with the universal disney = true setting.
Like sbtype, we wanted the model of LPT DAC to be configurable, and so Staging\u2019s deprecated the disney setting in favour of lpt_dac that takes any of the following:
disney, for the Disney Sound Sourcecovox, for the Covox Speech Thingston1, for the Stereo-on-1 DAC deviceoff/none, to disable the DAC (default)This is paired with a corresponding filter setting, lpt_dac_filter, which approximates how the original device sounded. This means that the Disney Sound Source (which included a little speaker inside it) will sound a lot like you might remember.
lpt_dac Examples (ModPlay Pro & Star Control II\u2019s 8-bit Pkunk MOD) disney Your browser does not support the audio element. covox Your browser does not support the audio element. ston1 Your browser does not support the audio element. Like the other audio filters settings, the lpt_dac_filter can be toggled on, off, or customised.
The audio stream can now be manually muted with Ctrl+F8 (or Cmd+F8 on macOS).
You can also mute the audio automatically when DOSBox Staging goes to the background with this config setting:
[sdl]\nmute_when_inactive = true\nOr you can pause emulation entirely when in the background with:
[sdl]\npause_when_inactive = true\nAs DOSBox Staging currently lacks a shader preset system, tweaking shader parameters can only be accomplished by making changes to the shader source files themselves. Previously, you had to restart DOSBox to see the effects of such changes, which made fine-tuning shaders quite cumbersome, to say the least.
Now you can just use the Ctrl+F2 shortcut (Cmd+F2 on macOS) to reload the current shader at any time. Progress! \ud83d\ude0e
"},{"location":"downloads/release-notes/0.79.0/#cga-palette-override","title":"CGA palette override","text":"Now it is possible to override the default, canonical interpretation of the 16-colour CGA/EGA RGBI palette. The feature overrides the CGA colours in any CGA/EGA-like mode, so it even works in CGA/EGA modes with an emulated VGA or TGA (Tandy) graphics adapter.
Several presets have been included (e.g. Amiga and Atari ST colours for Sierra games, and various CGA/EGA monitor emulations), and you can specify custom palettes as well. Make sure to check out the description of the cga_colors config parameter for the list of available presets (you can read more about them here).
Defender of the Crown
tandy-warm emulates the colours as they appear on an actual Tandy monitor, which results in more subdued and pleasant colours. This is especially apparent on the greens.
cga_colors = default
cga_colors = tandy-warm
Gold Rush
The Amiga/Atari ST ports of Sierra AGI games feature a tweaked CGA palette with improved skin tones and sky colours.
cga_colors = default
cga_colors = agi-amigaish
Zak McKracken and the Alien Mindbenders
Now you can play the PC version of this classic adventure with Tandy sound and Commodore 64 colours!
cga_colors = default
cga_colors = colodore
When the image is scaled by non-integer ratios (e.g. when aspect correction is enabled with the default sharp OpenGL shader), previously the interpolation was performed in a gamma-incorrect way, leading to various unwanted artifacts. These were most noticeable on checkerboard dither patterns (used frequently in EGA games), appearing as interference (moir\u00e9) patterns, and on high-contrast antialiased text (e.g. regular black text on white background appeared bold).
macOS notes
All Mac browsers tend to display the below images with incorrect gamma on the built-in MacBook displays, which makes the \u201cbad\u201d images look less wrong, and there are slight interference patterns on the \u201cgood\u201d images. Please download the images and view them in the Preview app instead, which displays them correctly.
Time Quest
Good
Bad
Space Quest III: The Pirates of Pestulon
Good
Bad
Windwalker
Good
Bad
"},{"location":"downloads/release-notes/0.79.0/#high-dpi-on-macos","title":"High DPI on macOS","text":"The backstory: DOSBox Staging uses OpenGL output with the sharp bilinear scaling shader to keep the picture crisp no matter how big or small the image is, and minimise blurring on pixel transitions.
Due to the way macOS handles DPI scaling, the image was drawn at a much lower resolution, usually just a quarter of the window size. Then it was stretched by the system, producing an unpleasantly mushy presentation. But we want our pixels to be so sharp they could cut one\u2019s eyes
Without high DPI support
With high DPI support
Now DOSBox Staging can handle high DPI displays, be it Retina or not, so you and shaders alike can see all the (physical) pixels.
Please note that this is currently experimental: only macOS is currently supported, and we haven\u2019t thoroughly tested multi-display setups. Please report any weird behaviour! Support for Windows will come in the future, and for Linux, it is still uncertain. Also note that due to the way rendering is currently implemented, you may observe lowered performance on higher resolution displays, especially when running off integrated graphics. This might be remedied in the future as well.
"},{"location":"downloads/release-notes/0.79.0/#window-transparency-support","title":"Window transparency support","text":"There might be situations where you want to place the DOSBox Staging window on top of another window while seeing both windows at the same time. Indeed, you can now set the DOSBox Staging window as transparent, with a customised level of window transparency, so that you can see the background window as well. There is a new config option transparency for this, whose valid values are between 0 (no transparency; default) to 90 (high transparency).
DOSBox presents frames when new content is available, which means that sometimes the effective frame rate can vary between 0 FPS (if the screen content isn\u2019t changing) and as fast as the DOS vertical refresh (vblank) rate (typically up to ~70 Hz). We\u2019ll call this presentation mode Variable Frame Rate or VFR.
In addition to VFR, DOSBox Staging supports a Constant Frame Rate (CFR) presentation mode, which presents a constant frame rate defined by the emulated DOS rate, as well as variations on both:
Synced CFR, which presents a constant frame rate but is synchronised with the host\u2019s refresh rate. This presents only the most recently updated frame when the DOS rate exceeds the host rate.
Throttled VFR, which presents a variable frame rate up to the DOS rate throttled to the display\u2019s rate. This presents only the most recently updated frame when the DOS rate exceeds the host rate.
By default, DOSBox Staging inspects runtime conditions and picks the optimal presentation mode.
Synced CFR mode selected due to vsync-enforced video drivers
Although typically not needed, power users might be interested in forcing a given mode or rate, which can be done using the following config settings (which includes detailed descriptions in the conf):
[sdl]\npresentation_mode = auto | cfr | vfr\nhost_rate = auto | sdi | vrr | custom-rate\n[dosbox]\ndos_rate = default | host | custom-rate\nDOSBox did not support the piping operation previously, but DOSBox Staging now brings piping support as how it has worked in DOS and most other operating systems. This allows two or more commands to communicate by passing the output text of one command to another as its input text. For example, commands like ECHO Y | CHOICE will work, so that the Y option will be passed as the input of CHOICE command. Chained piping is also supported, such as DIR | SORT | MORE for displaying sorted directory output one screen at a time (provided that you have the SORT and MORE commands from MS-DOS or FreeDOS in your path). If the current directory and C:\\ are both read-only, the environment variable %TEMP% (or %TMP%) needs to be set within DOS pointing to a writable directory so that piping will work properly (e.g. SET TEMP=C:\\TEMP).
File attributes contain information about how the files should be used, and in DOS these correspond to Archive (A), Read-only (R), Hidden (H), and System (S) attributes. DOSBox Staging now adds support for file attributes through ATTRIB command (type ATTRIB /? for more information about this command) or through DOS API that accesses to file attributes. For example, some game installers and applications make use of file attributes. All file attributes are currently supported except for system and hidden attributes on mounted local drives for non-Windows platforms.
The CHOICE command allows you to choose from a list of options, but sometimes you want to have some default choice if no selection is made within the specific time period. DOSBox Staging now allows you to do this, by specifying the /T option which includes a default choice and the time period in seconds. For example, CHOICE /C:ABC /T:B,2 will default to the choice B (among A, B, and C) if no key press is made within 2 seconds.
Mounting physical CDs is now (re-)implemented in DOSBox Staging for better compatibility with games like Under a Killing Moon, System Shock, and The Pandora Directive. The feature is supported in DOSBox SVN but was forced to be dropped from DOSBox Staging earlier during the SDL2 migration process. We\u2019ve brought it back by using the SDL1 CD support code as an external library, plus restoring the main SDL CD interface from DOSBox.
To use the feature, execute the command mount -cd to list all CD drives and their numbers, and use -usecd NUMBER parameter to specify a CD drive NUMBER, just like you would do in DOSBox SVN. Playing CD audio tracks from physical discs is also supported in Windows as with DOSBox SVN.
You might have encountered the problem previously that you could not mount write-protected disk images, which happened simply because DOSBox Staging required write access to mount disk images.
Sometimes the user may also want to mount a disk image in a read-only manner (so that the content in the disk image will not be changed inside the emulator), even if the disk image itself is not write-protected. We have realised that in either case the requirement for write access is not needed for mounting disk images, so we have added support for mounting them in a read-only manner, either when the disk image files are read-only or when the -ro flag is specified by the users.
The internal Z drive that is automatically mounted when you launch DOSBox Staging is now fully customisable, allowing users to add their own files or programs to the drive by putting them in the drivez subdirectory inside the DOSBox Staging program directory. Files already existing on the Z drive will be replaced by the user-provided ones, e.g. you can use your own MEM.COM or KEYB.COM commands instead of the default ones on the Z drive. Moreover, support for one-level subdirectories has been added, allowing users to better organise their files, resulting in a cleaner-looking Z drive. The drive\u2019s contents can be refreshed via the RESCAN command to reflect any changes made to it at the host OS level.
The IMGMOUNT command allows you to mount disk or CD images, but sometimes you may want to mount multiple images to a single drive, swappable via a keyboard shortcut. Previously you had to specify the names of the all the image files one by one, even if they have some patterns in common (like DISK1.IMG, DISK2.IMG, DISK3.IMG, etc). IMGMOUNT command now supports wildcards for mounting image files, so that you can just specify a file pattern that matches all the image files that you want to include. For example, the command IMGMOUNT a d:\\*.img -t floppy will mount all image files with the IMG extension on D:\\ as floppy images.
Directories can now be automounted, provided the automount config setting is enabled (which it is, by default).
These automount directories are single-letter directories, a through y representing the mounted drive letter (where z is reserved for DOSBox\u2019s drive) placed inside a local drives/ directory, relative to the startup location. This drives/ directory can also be placed in a scanned resource location, like your DOSBox config directory or the release package\u2019s resources/ area.
Each drive can be customised with an accompanying <letter>.conf to define its mount type, label, and path. For example, to mount a local drives/d/ directory as a D: CD-ROM with the label SIERRA, the accompanying d.conf would contain:
[drive]\ntype = cdrom\nlabel = SIERRA\nA bundled Y: automount is provided in the release\u2019s resources/ directory that bundles a couple FreeDOS 3rd party tools (XCOPY.COM, DELTREE.COM, DEBUG.COM) along with an accompanying y.conf to add it to the PATH.
Note
This feature doesn\u2019t yet support image mounts, such as .img, .bin/cue, or .iso.
The 20-year-old FreeDOS code pages (screen fonts) and keyboard layouts were updated to the latest versions, offering countless new definitions for use. See the full list in the following documentation:
Some notable examples:
KEYB bg 3021 \u2014 sets a Bulgarian keyboard layout and code page, with Cyrillic characters encoded according to the MIK standard
KEYB cz489 867 \u2014 a so-called programmer keyboard layout (national characters available with Right Alt+0 - 9) for Czech and Slovak languages, with Kamenick\u00fd character encoding - which was more popular than code page 852
KEYB de 858 \u2014 German keyboard, code page with EUR currency symbol
KEYB hu 3845 \u2014 Hungarian keyboard, CWI-2 character encoding
KEYB pl 668 \u2014 code page specially designed for the Polish language; places national characters on the same positions as standard code page 852 (so it is compatible with current software and text documents), but preserves more table drawing symbols
KEYB pl 667 \u2014 Mazovia encoding for Polish language, used mainly by older business software
The display formats for dates, times, and decimals were previously fixed to the United States style, but this is no longer the case with this new version. Indeed, DOSBox Staging can now display date, time, and decimal formats according to the system locale and country settings, and for example, in the Canadian French locale (country code 2) the date and time will be displayed as 2002-10-01 12:34 instead of 10-01-2002 12:34p as displayed in the United States locale (country code 1). There is a new config option country which allows you to manually specify the country code for the date, time, and decimal formats.
Canadian French locale
United States locale
"},{"location":"downloads/release-notes/0.79.0/#local-language-and-keyboard-layout-detection-improvements","title":"Local language and keyboard layout detection improvements","text":"On macOS and Windows systems, local languages now are more robustly detected and applied.
Note that these can still be manually set using the language and keyboardlayout config settings when needed, or via the KEYB command as mentioned above.
The built-in mouse driver now provides a wheel support for application aware of CuteMouse extensions; examples include Necromancer\u2019s DOS Navigator and Mpxplay.
The original CuteMouse driver version 2.1 is also able to use the PS/2 mouse wheel, just start it with CTMOUSE /o.
Numerous serial (COM port) mice are now emulated:
To enable serial mouse, user the SERIAL 1 mouse command (this will attach it to the COM1 port), or edit the [serial] section of the configuration file. By default, DOSBox Staging tries to determine what kind of mouse the game or application expects.
With serial mouse emulation, Windows 1.01 is finally usable!
"},{"location":"downloads/release-notes/0.79.0/#windows-31-seamless-mouse-integration","title":"Windows 3.1 seamless mouse integration","text":"It is now possible to have a seamless mouse integration using one of the following 3rd party VMware-compatible Windows 3.1 mouse drivers:
VBADOS by javispedro \u2014 this one requires a corresponding DOS mouse driver to be started; this driver also provides seamless mouse integration for a real DOS if booted inside DOSBox Staging
vmwmouse by NattyNarwhal \u2014 does not require any specific DOS driver and has experimental support for mouse wheel, but current version 0.1 has stability problems
For now, only the mouse is supported (no VMware directory sharing, etc.), only using VMware protocol (no VirtualBox-only drivers). Windows 9x VMware mouse driver is not supported.
"},{"location":"downloads/release-notes/0.79.0/#joystick-calibration-hotkeys","title":"Joystick calibration hotkeys","text":"Most DOS games that offer analog joystick control include some form of calibration. However, some games have poor or limited calibration resulting in the joystick\u2019s position drifting or being offset, despite calibration attempts.
To compensate for these rare cases, DOSBox Staging lets you adjust the joystick\u2019s X and Y position parameters in real time by enabling the use_joy_calibration_hotkeys setting in the [joystick] config section.
Once activated, you can tap Ctrl + arrow-keys or Alt + arrow-keys to adjust either the joystick\u2019s scalar multiplier or absolute offset position, respectively. These let you \u201ccounterbalance\u201d calibration issues in real time.
Each tap of the hotkeys will log the calibration values for the given axis. For example:
x_calibration = 0.576211,0.02\ny_calibration = 0.5474,-0.005\nOnce you\u2019ve found the optimal settings for a game, the logged calibration values can be placed in the game\u2019s local config file (so the setting are only active for the affected game). Using the above as an example:
[joystick]\nuse_joy_calibration_hotkeys = false\njoy_x_calibration = 0.576211,0.02\njoy_y_calibration = 0.5474,-0.005\nNote that you can disable the calibration hotkeys once you\u2019ve found settings that work for a problematic game.
Here\u2019s a video showing how the calibration hotkeys \u201cpull\u201d the joystick in various directions:
Your browser does not support thevideo element. The new joystick calibration feature in action
"},{"location":"downloads/release-notes/0.79.0/#general-improvements","title":"General improvements","text":""},{"location":"downloads/release-notes/0.79.0/#command-line-setting-of-configuration-options","title":"Command-line setting of configuration options","text":"Some people may want to temporarily run DOSBox Staging with specified config option(s), and in this new version you can do this with the new -set command-line option when launching DOSBox Staging, instead of having to modify the configuration file before you start DOSBox Staging.
For example, the user can temporarily run DOSBox Staging with the EMS memory disabled with the command line dosbox -set ems=false, overriding the setting in the configuration file.
The -set option can be specified multiple times for different config options, similar to the -c option which can be used multiple times to run multiple commands after DOSBox Staging starts.
Previously, DOSBox Staging was only available as portable zip packages for Windows users, but this has changed in this new version\u2014as a Windows user you can now install DOSBox Staging more easily with the installer, which is especially recommended for new and first-time users. When the installer is used, the installation process will be automated while allowing you to change certain things like the installation folder, and you will be able to launch DOSBox Staging as soon as the installation ends. Shell context menus can also be automatically added for a faster launch of DOSBox Staging from Windows Explorer.
Windows installer welome page
Icons after installation
"},{"location":"downloads/release-notes/0.79.0/#configurable-modem-connect-speeds","title":"Configurable modem connect speeds","text":"The soft-modem\u2019s reported connect speed can be customised using the serial port\u2019s baudrate setting. for example:
serial1 = modem baudrate:2400\nAlthough this doesn\u2019t change the underlying baud rate, it can help satisfy old modem software if it\u2019s unable to handle (or parse) the larger connect values.
"},{"location":"downloads/release-notes/0.79.0/#handling-options-for-memory-faults-in-buggy-games","title":"Handling options for memory faults in buggy games","text":"Extremely rare programming bugs \ud83d\ude09 in some DOS games (and programs) may cause them to accidentally write data beyond their allocated memory region, similar to \u201cpainting outside the lines\u201d. DOSBox is great at catching these instances: it flags the corruption and quits, preventing the program from barreling on and possibly doing more harm such as writing corrupt save games, documents, and so on.
DOSBox Staging defaults to this same behaviour, but adds the [dosbox] mcb_fault_strategy config setting:
deny Report and quit as soon as a fault is detected (default) Game terminates, no risk of subsequent file corruption repair Report and repair up to 100 sequential faults Game continues, but may still be unstable if its developers expected the corruption report Report the corruption and carry on Game continues, but risks further instability and file corruption allow Carry on without reporting Game continues, but risks further instability and file corruption Only consider this if your game is prone to crashing with MCB chain corruption errors reported in the console log.
"},{"location":"downloads/release-notes/0.79.0/#developer-related-improvements","title":"Developer-related improvements","text":""},{"location":"downloads/release-notes/0.79.0/#self-documenting-bit-twiddling-with-bit_view","title":"Self-documenting bit twiddling with bit_view","text":"We\u2019ve implemented a bit_view C++ class using constant expressions to access a subset of a data-field\u2019s bits, allowing them to be read, written, assigned, flipped, cleared, and tested, without the need to for the usual twiddling operations.
Constructing a bit_view is similar to a C bitfield, however unlike C bitfields, bit_views are free from undefined behaviour and have been proven using GCC\u2019s and Clang\u2019s undefined behaviour sanitisers.
There\u2019s more detail and some code examples here.
"},{"location":"downloads/release-notes/0.79.0/#memory-block-and-type-size-simplification","title":"Memory block and type size simplification","text":"The emulated main memory (up to 64 MiB) and the video card\u2019s memory (to up 8 MiB) are both now allocated statically to reduce pressure on heap storage (#1714).
More progress has been made in reducing the use of large variables type-sizes down to purpose-fit sizes per the DOS/hardware specification (typically 8 or 16-bit) (#1721).
"},{"location":"downloads/release-notes/0.79.0/#tracy-profiler-integration","title":"Tracy profiler integration","text":"The Tracy event profiler has been integrated into the build system and basic hooks are in place to log frames and tics. These are only active (and not compiled in) unless Tracy is enabled.
Here\u2019s what it looks like:
Tracy runtime-profiling DOSBox Staging
It can be enabled at build-time with -Dtracy=true. Learn more about it, and how to build the server-side component here: #1749
The MSYS2-based workflow has been brought in line with current best practices, which dramatically improved its build time and lead to us now using it to generate the default Windows release binaries.
"},{"location":"downloads/release-notes/0.79.0/#release-package-shell-script","title":"Release-package shell script","text":"Release packages are now generated using a cross-platform POSIX-compliant shell script. With this logic moved into a script, developers can now easily test the creation of a release package locally, which was previously impossible as that logic only lived in a GitHub-syntax YAML.
"},{"location":"downloads/release-notes/0.79.0/#static-analysis","title":"Static analysis","text":"The team continues to fix and address static analysis issues as flagged by various analysers. Here are our Coverity Scan metrics to-date:
"},{"location":"downloads/release-notes/0.79.0/#translation-status","title":"Translation status","text":"The 0.79.0 configuration file is also in UTF-8 format for the German, Italian, and Polish languages under the package\u2019s resources/translated-0.79-conf-files directory.
The messaging system now supports self-documenting markup syntax, which is much easier to read and maintain compared to the previous ANSI escape sequences.
Old escape-code style New markup styleEscribiendo ^[[34;1mdir^[[0m all\ufffd mostrar\ufffd su contenido. Digita [color=blue]dir[reset] per visualizzarne il contenuto."},{"location":"downloads/release-notes/0.79.0/#notable-fixes","title":"Notable fixes","text":"Fixed Ultima Underworld issues with gaming (high polling rate) mice (#1722)
Fixed lockups and input issues with the debugger on macOS and Linux. Note that for those using the debugger on Linux, we recommend building it with SDL 2.0.18, because some input/interaction bugs exist when using newer SDL versions.
Fixed colours becoming very dim on newer Intel integrated GPUs due to Intel\u2019s OpenGL drivers not properly handling the sRGB linear colour space.
Fixed a memory-read race condition present during the splash-image display, which also reduced start-up time by around 200 ms.
Fixed display of the low-resolution halfline VESA 2.0 mode used by Extreme Assault through the addition of a new vesa_mode config setting value, named halfline.
Named the macOS application \u201cDOSBox Staging.app\u201d per the macOS per Human Interface Guidelines.
Fixed a usability trap door when opening the mapper without mouse support: in these cases, the user was unable to exit the mapper. The mapper now only opens when mouse support is enabled.
John Novak for all the audio enhancements, mixer cleanup, shader improvements, and code reviews
FeralChild64 for the mouse overhaul, code page and layout cleanup and improvements, and code reviews
Wengier for the shell improvements, mount and CLI additions, and Windows installer
Antti Peltola for providing historic resources, documentation help, and project support
shermp for the MSYS2 cleanup, cross-platform packaging script and CI cleanup, ANSI markup system, and code reviews
Kirk Klobe for the debugger fixes, Tracy integration, and paging and memory system refinements
GranMinigun for the HiDPI additions, video chain fixes, and Russian translations
nemo93 for testing 400+ games on the Raspberry Pi
Kappa971 for the Italian and configuration file translations, and leading the translation effort
Burrito78 for the German translation
Thank you to our financial contributors who allow us to purchase hardware, licenses, and other non-trivial expenses to keep the team and project going.
To support our work, donate to our GitHub Sponsors or Open Collective.
"},{"location":"downloads/release-notes/0.79.0/#thank-you","title":"Thank you","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"downloads/release-notes/0.79.1/","title":"0.79.1 release notes","text":"Release date: 2022-09-30
"},{"location":"downloads/release-notes/0.79.1/#summary","title":"Summary","text":"We recommend repository maintainers move to 0.79.1, which should be much easier to package. Details in the Packaging fixes section below.
We recommend users of our zip, dmg, and Windows installer packages upgrade from 0.79.0 to fix some audio and usability bugs.
This maintenance release was made possible by everyone who tried 0.79.0, submitted bugs and pull requests, and tested the updates: thank you!
"},{"location":"downloads/release-notes/0.79.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
Fixed a CD-DA playback regression in Might and Magic 6 when using multi-image mounts (kcgen)
Allowed the Esc key and window-close events to exit from the paused state (Wengier)
Fixed a bug that prevented automounted drives from being used by [autoexec] commands (kcgen)
Fixed an audio filter reset regression flagged in Blues Brothers: Jukebox Adventure (kcgen)
Fixed a 16-bit stereo DMA regression detected when using the Sound Blaster\u2019s modern filter (kcgen)
video element. 303 by Acme \u2014 30fps encoding, 120k cycles, and SB16 using the modern filter
Improved ability to pipe between applications by using Y: as a temporary path (Wengier)
Switched to warning-level logging for MIDI configuration issues (Michael Drueing)
Improved the lookup of resources when XDG variables aren\u2019t set correctly (kcgen, Eli Schwartz)
Updated the Dutch language to use the US keyboard layout by default (Wengier)
Included Xbox compatible controller mapperfiles for 180+ games: conf, wiki (nemo93)
Synced Italian translation (Kappa971)
Dropped non-existant KEYB help messages from translation system (Wengier)
Replaced more escape codes with markup tags in the translations (Robert de Rooy)
Moved the mount type descriptions into the translation system (Wengier)
New Keymapper page with examples for those with Xbox controllers (nemo93)
New FAQ answering questions about audio settings, configuration files, video output, and other topics (nemo93)
Notable additions to the UniVBE, Special keys, Getting started, Suggested audio settings, Config examples, AUTOTYPE candidates, and Games with CD-DA, GUS and MIDI audio pages (nemo93)
Adjusted Meson\u2019s FluidSynth dependency spec to match upstream\u2019s packaging (Kirk Klobe)
Switched Meson to use SpeexDSP from the host first and fallback to wrap (kcgen)
Switched Meson to use shared (instead of static) libraries by default (kcgen)
Fixed installation of resources when using meson install (kcgen, Eli Schwartz)
Packagers will get shared libs and installed resources with these standard steps:
meson setup --prefix /writable/install/path build\nmeson install -C build\nThanks to our financial contributors who allow us to purchase hardware, licenses, and other non-trivial expenses to keep the team and project going.
To support our work, donate to our GitHub Sponsors or Open Collective.
We are grateful for all community contributions as well as the original DOSBox project, upon which DOSBox Staging is based.
"},{"location":"downloads/release-notes/0.80.0/","title":"0.80.0 release notes","text":"Release date: 2022-12-21
"},{"location":"downloads/release-notes/0.80.0/#summary","title":"Summary","text":"ReelMagic DOS games are now playable thanks to the efforts of Jon Dennis, Chris Guthrie, and Joseph Whittaker, with testing and feedback from Vogons users Uka, DonutKing, and Vetz. Mouse emulation has been improved and now supports up to six independent mice, enabling split-screen play in games like The Settlers and The Settlers II. More settings, including video, audio, and mixer effects, can now be changed on the fly. Following macOS, high DPI support on multi-display setups now comes to Windows. A new --working-dir command line flag allows DOSBox Staging to launch from a specific working directory. Repo packagers should note that sdl2_image is now a dependency.
Read on for all the details!
"},{"location":"downloads/release-notes/0.80.0/#how-to-upgrade","title":"How to upgrade","text":"Get started by downloading the latest version and updating your configuration file:
"},{"location":"downloads/release-notes/0.80.0/#downloads","title":"Downloads","text":"Z:\\> prompt, run config -wc to write the new configuration file.Note
Existing settings will be retained, but extraneous comments will be dropped.
Starting with version 0.80, the configuration file is written in the language in which DOSBox Staging was started.
To write an English configuration file, launch with the -lang en command-line flag (to start DOSBox Staging in English) and then (re-)write your configuration file.
DOS ReelMagic games are now playable thanks to Jon Dennis\u2019s patch with help from Chris Guthrie and Joseph Whittaker.
See the [reelmagic] section in your configuration file to enable this. We suggest only enabling ReelMagic emulation on an as-needed basis.
video element. Return to Zork (1995) \u2014 introduction
Jon plans to add DMA support (primarily used by the ReelMagic Windows 3.1x driver and games) when time permits, but most ReelMagic games for DOS are already fully functional and playable.
"},{"location":"downloads/release-notes/0.80.0/#mouse-improvements","title":"Mouse improvements","text":""},{"location":"downloads/release-notes/0.80.0/#dedicated-configuration-section","title":"Dedicated configuration section","text":"The mouse configuration has been moved to its own section and additional options have been added. A tool called mousectl is available on Z: for more detailed per-interface mouse configuration. \u00a0
Multiple physical mice can now be mapped to specific emulated mouse interfaces, enabling two-player split-screen gaming (The Settlers and The Settlers II) using two USB mice on a single computer.
See the wiki article for more details.
Your browser does not support thevideo element. The Settlers II (1996) \u2014 showcasing dual-mouse gaming in action
"},{"location":"downloads/release-notes/0.80.0/#improved-support-for-third-party-int33-windows-mouse-drivers","title":"Improved support for third-party INT33 Windows mouse drivers","text":"javispedro\u2019s INT33 mouse driver for Windows 3.1x is fully supported and no longer requires the use of the separate DOS driver, except when booting from a disk image. The driver also resolves compatibility issues with seamless mouse integration and adds mouse wheel support.
See the wiki article for more details.
"},{"location":"downloads/release-notes/0.80.0/#mouse-related-help-in-the-title-bar","title":"Mouse-related help in the title bar","text":"The title bar now displays some short help about the mouse, such as how it can be captured or released.
"},{"location":"downloads/release-notes/0.80.0/#high-dpi-on-windows","title":"High DPI on Windows","text":"Following macOS, high DPI support now comes to Windows: the DOSBox window should scale nicely along other programs, and retain correct dimensions when moving between monitors with different scaling factors set.
Note
This feature is currently experimental! If you notice any weird behaviour, please report it!
"},{"location":"downloads/release-notes/0.80.0/#ability-to-use-local-configs-via-finder-on-macos","title":"Ability to use local configs via Finder on macOS","text":"A new --working-dir <path> command line parameter has been introduced to make it possible to launch DOSBox Staging using local configs from the Finder on macOS. Previously, you had to use DOSBox from the command line to achieve this. \u00a0
Follow the steps indicated in the DMG package, as shown:
Simply copy the included Start DOSBox Staging.command to any folder that contains a local dosbox.conf and then open it (Start DOSBox Staging.command) in Finder. DOSBox Staging will act as if started from that folder and will pick up the local config. \u00a0
Note
You might be asked to give DOSBox Staging access to the containing folder upon the first launch\u2014just click OK if that dialog comes up.
"},{"location":"downloads/release-notes/0.80.0/#general-improvements","title":"General improvements","text":""},{"location":"downloads/release-notes/0.80.0/#morecom-command","title":"more.com command","text":"The more command is now internally implemented (should be more user-friendly than the original DOS one), and its engine is used for displaying help messages longer than one screen.
video element. more.com \u2014 Better and Improved\u2122
"},{"location":"downloads/release-notes/0.80.0/#on-the-fly-changes","title":"On-the-fly changes","text":"Several settings can be safely adjusted at runtime, including the output video settings, resolution, OpenGL shaders, audio devices, and mixer settings.
Your browser does not support thevideo element. Reconfiguring audio on-the-fly \u2014 changing sound cards in a PC has never been easier!
"},{"location":"downloads/release-notes/0.80.0/#post-rendered-screenshots","title":"Post-rendered screenshots","text":"DOSBox has long provided the Ctrl+F5 hotkey to capture the emulated video card\u2019s image prior to rendering.
DOSBox Staging 0.80 now pairs this with Alt+F5 (or Option+F5 on macOS) to capture the as-seen (post-rendered) image.
"},{"location":"downloads/release-notes/0.80.0/#more-bundled-opengl-shaders","title":"More bundled OpenGL shaders","text":"The balance of usable shaders from Tyrells\u2019 CRT shader collection, as well as GranMinigun\u2019s interpolating Catmull\u2013Rom spline shader have been added.
Launch DOSBox Staging with the --list-glshaders command-line argument to list the available OpenGL shaders. For example:
List of available GLSL shaders\n------------------------------\n\nPath '/usr/src/dosbox-staging/build/resources/glshaders' has:\n |- crt/aperture\n |- crt/caligari\n |- crt/easymode\n |- crt/easymode.tweaked\n |- crt/fakelottes\n |- crt/fakelottes.tweaked\n |- crt/geom\n |- crt/geom.tweaked\n |- crt/hyllian-updated\n |- crt/hyllian\n |- crt/lottes-fast\n |- crt/lottes-fast.subtle+gain\n |- crt/lottes\n |- crt/lottes.tweaked\n |- crt/mattias\n |- crt/pi-vertical\n |- crt/pi\n |- crt/yee64\n |- crt/yeetron\n |- crt/zfast\n |- crt/zfast-composite\n |- interpolation/catmull-rom\n |- interpolation/sharp\n |- scaler/advinterp2x\n |- scaler/advinterp3x\n |- scaler/advmame2x\n |- scaler/advmame3x\n |- scaler/rgb2x\n |- scaler/rgb3x\n |- scaler/scan2x\n |- scaler/scan3x\n |- scaler/tv2x\n `- scaler/tv3x\n--working-dir command line option (#2122)sdd::unique_ptr to manage the video memory (#2116)The mixer\u2019s effects (reverb, chorus, and crossfeed) can now be turned on and off at runtime via the mixer command.
FluidSynth\u2019s specific reverb and chorus configuration settings are now applied and will replace the default values that were previously always applied.
The modem\u2019s call now has a warm-up period where it will discard data. This fixes a bug noted in Duke Nukem 3D where it would fail its initial handshake on the first try.
update-sources.sh script to UTF-8 locale (#2011)config -wc to write UTF-8 file (#1991)mixer.com CLI handling of volume and effect arguments (#2021)bit_views to 8-bit registers to avoid byte-order assumption (#1999)std::filesystem calls (#1995)The title bar is now translatable.
The Brazilian ABNT2 slash and question mark keys are now handled.
Translations are now stored in UTF-8 and converted to the selected DOS codepage, dropping accents if needed, sometimes even performing crude transliterations (for Latin, Greek, and Cyrillic alphabets DOSBox shouldn\u2019t display garbled messages anymore regardless which codepage is selected). This is especially important for languages where more than one incompatible encoding was used in the DOS era. All FreeDOS codepages are supported. Note that only DOSBox Staging\u2019s own messages benefit from this feature.
update-sources.sh script to UTF-8 locale (#2011)tandy and ibm5153 cga_colors config descriptions (#2074)MSG_Add from code page 437 to UTF-8 (#1984)MSG_Add from code page 437 to UTF-8 (#1984)The following wiki articles have been updated:
The new Dual Mouse Gaming page documents how to set up dual-mouse working in The Settlers and The Settlers II.
The Windows 3.1x page was updated with notes on how to set up the improved mouse driver, and more sound drivers.
The new Windows 3.0 page documents how to set up Windows 3.0\u2019s video, sound, MIDI, mouse, and how to print to files.
The new Serial Ports page documents all of the serial port settings.
The Sound Cards page was overhauled with descriptions and configuration help for all supported sound devices.
The Tips & Tricks page was updated with how to generate DOSBox mountable CD-DA content from public domain or Creative Commons licensed YouTube chapters and playlists.
The following commit authors, sponsors, supporters, and backers all invested their time or funds into the 0.80 release effort. Thank you!
Contributors are listed in alphabetic order.
"},{"location":"downloads/release-notes/0.80.0/#080-commit-authors","title":"0.80 commit authors","text":"Sponsors who donated more than 100 USD per month to the project:
Backers who donated more than 5 USD per month to the project:
Thank you for considering supporting our work through a donation on GitHub Sponsors or Open Collective. Your contribution helps us purchase the necessary hardware and licenses to keep our project going.
"},{"location":"downloads/release-notes/0.80.0/#thank-you","title":"Thank you","text":"We are grateful for all community contributions as well as the original DOSBox project, upon which DOSBox Staging is based.
"},{"location":"downloads/release-notes/0.80.1/","title":"0.80.1 release notes","text":"Release date: 2023-01-06
"},{"location":"downloads/release-notes/0.80.1/#summary","title":"Summary","text":"This maintenance release fixes minor issues with the mouse defaults, modem and Ethernet connection handling, and Meson dependencies.
We are also happy to report that the high DPI improvements in the previous 0.80.0 release have been verified on Windows, meaning that high DPI support is now functional on all platforms. Thanks to GranMinigun for this addition!
This maintenance release was made possible by everyone who tried 0.80.0, submitted bugs and pull requests, and tested the updates: thank you!
"},{"location":"downloads/release-notes/0.80.1/#how-to-upgrade","title":"How to upgrade","text":"Get started by downloading the latest version and updating your configuration file:
"},{"location":"downloads/release-notes/0.80.1/#downloads","title":"Downloads","text":"Z:\\> prompt, run config -wc to write the new configuration file.Note
The mouse will now be captured only after the first click inside the window. For users without a windowing environment, the previous capture-on-start behavior will remain unchanged.
The captured mouse will now be centered in the window upon release.
The softmodem now includes a brief warm-up period where it will drop initial unreliable data, similar to hardware modems. This allows Duke Nukem 3D to establish its data connection on the first attempt.
A potential slow memory leak related to closed Ethernet connections has been fixed.
A bug that caused the C: mount to become unlistable after launching DOSBox Staging with a command-line mount while using MORE.COM has been fixed.
The xinput2 library, an optional dependency of ManyMouse, can now be set via the Meson options. For more information, see meson_options.txt.
When compiling on ARM platforms, the SpeexDSP wrap will now correctly check if the host supports NEON instructions, and use them if available.
This maintenance release includes updates to the Dutch, Italian, and Polish translations.
Full PR list of translation improvementsThe following commit authors, sponsors, supporters, and backers invested their time or funds into this maintenance release. Thank you!
"},{"location":"downloads/release-notes/0.80.1/#commit-authors","title":"Commit authors","text":"In alphabetic order:
Sponsors who donated 100+ USD per month to the project:
Backers who donated 5+ USD per month to the project:
Thank you for considering supporting our work through a donation on GitHub Sponsors or Open Collective. Your contribution helps us purchase hardware and cover ongoing expenses to keep the project going.
"},{"location":"downloads/release-notes/0.80.1/#thank-you","title":"Thank you","text":"We are grateful for all community contributions as well as the original DOSBox project, upon which DOSBox Staging is based.
"},{"location":"get-involved/","title":"Get involved","text":""},{"location":"get-involved/#github-repository","title":"GitHub repository","text":"The DOSBox Staging project is hosted on GitHub. Here you\u2019ll find the full source code and various project related documentation. Send us patches if you improve something! \ud83d\ude04
We are grateful for all community contributions as well as the original DOSBox project, upon which DOSBox Staging is based.
"},{"location":"get-involved/#report-an-issue","title":"Report an issue","text":"While we do our best to ensure the quality of our releases, every software has bugs. If you think you\u2019ve spotted one, please report it in our issue tracker (requires a GitHub account).
Alternatively, join our Discord channel to discuss the problem with one of our friendly staff members.
"},{"location":"get-involved/#wiki","title":"Wiki","text":"The DOSBox Staging Wiki hosted on GitHub contains lots of useful tricks & tips, how-to\u2019s, lists, and guides that can help newcomers and more experienced users alike.
We very much recommend perusing it, and if you\u2019ve spotted an error or have something to share, please feel free to contribute to it.
"},{"location":"get-involved/#discord","title":"Discord","text":"Join the team on Discord for a good chat over a virtual beverage of your choice!
We only ask you to adhere to our Code of Conduct so every participant can enjoy the discussion.
"},{"location":"get-involved/#make-a-donation","title":"Make a donation","text":"DOSBox Staging is an entirely volunteer-based effort\u2014we\u2019re not getting paid for our activities. However, we have some running expenses and need to invest in hardware, licenses, and other non-trivial expenses to keep the team and the project going.
If you wish to make a financial contribution to support us, you can do so at our GitHub Sponsors or Open Collective pages.
We are grateful for all donations, no matter how big or small!
"},{"location":"get-involved/code-of-conduct/","title":"Code of conduct","text":"In order to foster a welcoming, positive, and rewarding experience, we as community members pledge to uphold this code of conduct.
Isn\u2019t decent behavior already expected? We want to bring our best to each other as peers, and explicitly documenting our expectations lets us set a high bar for ourselves.
"},{"location":"get-involved/code-of-conduct/#be-excellent-to-each-other","title":"Be excellent to each other","text":"\u201cExcellent\u201d means we:
are wholly inclusive to existing members and newcomers looking to learn or participate. Some may raise questions that have been addressed before. Kindly point them to existing discussions. Everyone was new to a project once.
respect your abilities, interests, and personal differences. Our different talents documenting, testing, coding, reviewing, reporting, and/or evangelizing are all valuable to the project.
make concise and actionable points to respect your time as a volunteer. We respect each other\u2019s time by keeping the signal-to-noise ratio high, staying on-topic, and being a good house guest: every visit we strive to leave the place in better shape than when we arrived.
are kind and assume positive intent, even when we disagree while working towards consensus and achieving the project\u2019s technical goals.
educate and illuminate others with something we know more about. We were all beginners once and can teach and learn through feedback and sharing.
are open to feedback from others, be it technical points, interpersonal tips, or language/wording suggestions.
accept responsibility by apologizing to those affected by our mistakes and graciously accept apologies knowing that mistakes are part of the process.
use words carefully because we may not all understand irony or negative sarcasm. We communicate plainly, and we justify our positions objectively and explicitly.
leave with class, without drama or bitterness, when resigning for any reason. We champion your rights under the terms of the GPL to fork the code and create a new project\u2014just as we stand on the shoulders of those who gave us the right to create this project.
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team (see below). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
The project team can be contacted via Discord.
"},{"location":"getting-started/beneath-a-steel-sky/","title":"Beneath a Steel Sky","text":"The next game we\u2019re going to set up is Beneath a Steel Sky, a cyberpunk sci-fi adventure game from 1994. It\u2019s one of the standout timeless classics of the adventure genre, and best of all, Revolution Software released the game as freeware in 2003 (see their accompanying notes here).
"},{"location":"getting-started/beneath-a-steel-sky/#launching-games-more-easily","title":"Launching games more easily","text":"Before we delve into the setup instructions, a few words on launching our growing collection of games more easily. Having to go to its folder whenever we want to launch a game gets old really fast. Here\u2019s how we can skip this step:
WindowsCreate a batch file called Start DOSBox Staging.bat with the following content:
C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox.exe\nThat\u2019s the default installation path chosen by the installer. %USERNAME% is your Windows user name; of course, if you have installed DOSBox Staging to a different folder, you should adjust the path accordingly.
Copy this batch file into your individual game folders and rename them to the names of the games, e.g., Prince of Persia.bat in this example.
Right-click on the batch file icon and select Send to \u2192 Desktop (create shortcut) in the context menu.
Now you can double-click on the new Prince of Persia.bat - Shortcut icon on your desktop to start the game (of course, you can rename the icon to Prince of Persia or whatever you like; this won\u2019t change the name of the batch file it references).
You can rename the Start DOSBox Staging icons in the individual game folders to the names of the games, then you can use Spotlight Search to start a game.
For example, rename Start DOSBox Staging in the Prince of Persia folder to Prince of Persia. Start Spotlight Search by pressing Cmd+Space, then type in \u201cPrince\u201d. The Prince of Persia icon will show up in the search results\u2014you can simply press Enter on it to launch the game.
The easiest way is to create a shell script with the following content (of course, modify the path passed in as the argument of the --working-dir option so it points to your game directory):
#!/bin/bash\ndosbox --working-dir \"~/Documents/DOS Games/Prince of Persia\"\nThen create an icon on your desktop that launches this script, or start it however you like.
"},{"location":"getting-started/beneath-a-steel-sky/#mounting-a-cd-rom-image","title":"Mounting a CD-ROM image","text":"We\u2019re going to set up the liberated \u201ctalkie\u201d CD-ROM version of the game that has full voice-acting. You know the drill; create a new Beneath a Steel Sky subfolder inside your DOS Games folder and the usual drives/c subfolder within it. Then download the ISO CD-ROM image and put it into a cd subfolder inside your Beneath a Steel Sky game folder. The name of the cd subfolder has no special significance; you could put the .iso image anywhere, but it\u2019s good to get into the habit of organising your game files systematically (e.g., you could create a Manual of Extras subfolder too and put the scanned manuals and all other extra files there). It\u2019s a good idea to rename Beneath a Steel Sky (1995)(Virgin).iso to cdrom1.iso; our game folder has the full name of the game anyway.
Speaking of manuals, make sure to get the scan of the Security Manual and the comic book that was included in the boxed version of the game.
For the visually inclined, this is the structure we\u2019ll end up with:
We need to mount the CD image to be able to use it. Our C drive is the hard drive, so we\u2019ll mount the CD-ROM image as the next letter D by convention. This is equivalent to having a CD-ROM drive in our emulated computer assigned to the drive letter D and inserting the game CD into it.
Mounting an image file, such as a floppy or CD-ROM image, is accomplished with the imgmount command. It is pretty simple to use: the first argument is the drive letter (d), the second the path to the CD-ROM image (cd/cdrom1.iso), and the third the type of the image file (-t iso).
So this is what we need to put into our config:
[autoexec]\nimgmount d cd/cdrom1.iso -t iso\nWarning
If you\u2019ve kept the original name of the ISO, you\u2019ll need to enclose it in double quotes because it contains spaces:
imgmount d \"cd/Beneath a Steel Sky (1995)(Virgin).iso\" -t iso\nTip
By always putting your CD-ROM images into the cd subfolder within your game folder and renaming the ISO files to cdrom1.iso, cdrom2.iso, and so on, it\u2019s easier to reuse the mount commands between configs.
You can always run imgmount /? if you need a little reminder on how to use it (although the full list of options can be a little overwhelming).
This is what you should see in the DOSBox Staging window after startup if everything is set up correctly:
Local directory drives/c/ mounted as C drive\nZ:\\>imgmount d cd/cdrom1.iso -t iso\nMSCDEX installed.\nISO image cd/cdrom1.iso mounted as D drive\nZ:\\>_\nMSCDEX is the name of the MS-DOS CD-ROM driver, and the next line just informs us that our CD image is mounted as drive D. Time to get down to business then!
"},{"location":"getting-started/beneath-a-steel-sky/#installing-the-game","title":"Installing the game","text":"Most games that come on CD images need to be installed on the hard drive first. Usually, there\u2019s an executable called INSTALL.EXE or SETUP.EXE in the root directory of the CD (the extension could be .COM or .BAT as well).
Switch to the D drive by executing d: then run the dir command to inspect the contents of the CD:
Volume in drive D is BASS\n Directory of D:\\\n\nINSTALL EXE 28,846 06/15/1994 8:56a\nREADME TXT 1,569 09/08/2005 1:34a\nSKY DNR 40,796 07/07/1994 8:40a\nSKY DSK 72,429,382 07/07/1994 8:40a\nSKY EXE 402,622 07/07/1994 7:21a\nSKY RST 53,720 07/07/1994 7:19a\n 6 file(s) 72,956,935 bytes\n 0 dir(s) 0 bytes free\nOkay, so we\u2019ve got two executables with the .EXE extension and one text file. View README.TXT using the more command (run more README.TXT, then keep pressing Space or Enter to go to the next page, or Ctrl+C to quit). It turns out it just contains some legal notice we don\u2019t really care about. INSTALL.EXE is what we\u2019re after, so let\u2019s run that!
We\u2019re greeted by a pretty standard-looking text-mode installer. Either press any key or wait a few seconds to progress to the second screen where you need to select where the game will be installed:
You can navigate the interface with the cursor keys, Esc, Enter, and the mouse. The default C:\\SKY install location is perfectly fine, so just accept it by pressing Enter.
That will take us to the setup screen where we can select the language of the in-game text (the voice-acting is in English only), and the sound card settings:
English is fine, and the game has auto-detected our sound card correctly (Sound Blaster 16\u2014this is the sound card DOSBox emulates by default), so just accept these settings for now. And now, the counterintuitive part: to finish the installation and save the settings, we need to press the Exit Install button, which will take us to the (guess what?) Exit Install dialog:
Here you need to press the Save Setup button to finalise the settings and exit the installer.
As you can see, this is not exactly a masterclass in user interface design, but it does the job. Expect many DOS-era install and setup utilities to be similarly slightly illogical\u2014often it\u2019s not completely obvious what to do, but it\u2019s not too hard to figure it out with some trial and error.
Anyway, after pressing Save Setup the installer will exit and print out the following instructions:
BENEATH A STEEL SKY has been installed to directory:\n\nC:\\SKY\n\nTo run the game type:\n\nC:\nCD \\SKY\nSKY\nOkey-dokey, let\u2019s do as the computer says! It\u2019s the easiest to put the above commands into the [autoexec] section of our config, but let\u2019s comment the last sky command out for now by preceding it with a # character because we don\u2019t want to start the game just yet:
[autexec]\nimgmount d cd/cdrom1.iso -t iso\nc:\ncd \\sky\n#sky\nSo before we run the game, what is this cd \\sky command? Does it have something to do with the cd subfolder where we put out CD-ROM image, perhaps?
No, that\u2019s just a coincidence. The cd command stands for Change Directory; it is used to change the current directory that\u2019s displayed as part of the DOS prompt. So let\u2019s analyse what these lines we put into the [autoexec] section do:
c:\ncd \\sky\nThe first command c: switches to the C drive (remember, the current drive is the special built-in Z drive when DOSBox starts).
Then the second cd \\sky command changes the current directory to the sky directory at the root level of the C drive. cd sky would work as well because the current directory is the root when we switch to the C drive right after startup.
How do you go up one level to the parent directory? With the cd .. command (two dots means \u201cparent directory\u201d, and a single dot means \u201ccurrent directory\u201d).
C:\\SKY>cd ..\nC:\\>_\nHow do you go straight to the root directory? By executing cd \\ (the \\ backslash character means \u201croot directory\u201d).
C:\\SKY>cd \\\nC:\\>_\nYou can also switch to a nested subdirectory with a single cd command, e.g. if you have a directory called one at the root level which contains a subdirectory two, which in turn contains another subdirectory three, you can switch to three from any directory with the cd \\one\\two\\three command. Note this is an imaginary example:
C:\\SKY>cd \\one\\two\\three\nC:\\ONE\\TWO\\THREE>_\nPlay around a bit with the drive and directory switching commands, then when you had enough, uncomment the last sky command in the [autoexec] section (remove the # character).
Warning
You cannot switch to a different drive with the cd command (e.g., cd z: or cd z won\u2019t work); you must use the drive letter followed by a semicolon (z: in this example)!
After starting the game, don\u2019t watch the intro just yet; press Esc to jump straight to the opening scene. There\u2019s music playing, so far so good. Move the cursor over the door on the right side of the screen, and when it turns into a crosshair and the word \u201cDoor\u201d appears next to it, press the left mouse button to inspect it. Lo and behold, you\u2019ll hear our protagonist speak! But it\u2019s barely audible, the music is just too loud.
There are a couple of ways to fix that. You can press F5 to bring up the game\u2019s options dialog where you can lower the music volume, but that would make the total audio output too quiet. Worse yet, the setting doesn\u2019t get saved, so you\u2019d need to do this every single time when starting up the game.
As we\u2019ve learned before, games with Sound Blaster support tend to use the sound card\u2019s OPL synthesiser for the music and its digital audio capabilities for the speech. As the OPL synth and the digital audio have their dedicated mixer channels, their volumes can be adjusted independently of each other.
\u201cWait a minute, what mixer channels now?!\u201d
Okay, so DOSBox has an integrated audio mixer. All emulated sound cards have their own channels in the mixer, and certain \u201ccomposite\u201d audio devices may have multiple channels. The Sound Blaster is such a composite device, so it has two mixer channels: one for the OPL synthesiser, and one for digital audio.
Execute the mixer command in the DOS prompt to view the current state of the mixer:
The first channel is the MASTER channel; this is the summed output of all other channels and it\u2019s always present. Below that is the CDAUDIO channel, the OPL and PCSPEAKER channels (you can guess these two, right?), and finally, the SB channel, which is for the digital audio output of the Sound Blaster.
The Sound Blaster card and PC speaker are enabled by default; that\u2019s the reason for their channels appearing in the mixer, and the CDAUDIO channel is added automatically whenever we mount a CD-ROM image (because it might also contain audio tracks).
To adjust the volume of any mixer channel, we use the mixer command and pass in the channel\u2019s name as the first argument, and the volume expressed as a percentage value as the second. So, to raise the volume of the SB channel to 500%, we need to execute the following:
mixer sb 500\nBy default, the command prints out the new state of the mixer after the adjustment:
You can combine multiple mixer commands in a single line, e.g., in the below example we\u2019ll set the OPL channel\u2019s volume to 50%, and the SB channel\u2019s to 500%:
mixer opl 50 sb 500\nYou can run mixer /? to see the full list of available mixer commands.
Do we need to perform these mixer adjustments manually every single time before running the game? Of course not; we can simply include them in our [autoexec] section. The extra /noshow argument prevents the mixer from displaying its current state; there\u2019s no need for that in our automated startup script.
[autoexec]\nimgmount D \"cd/cdrom1.iso\" -t iso\nc:\ncd sky\nmixer opl 50 sb 500 /noshow\nsky\nDOSBox emulates the Sound Blaster 16 by default. This card can emulate all earlier Sound Blaster models and offers the widest compatibility with DOS games.
But back in the day, there were more Sound Blaster variants and clones you could shake a stick at, many of them having quite different default volume levels. We simply don\u2019t know what particular model the developers used, so it\u2019s worth experimenting with a few different ones. Let\u2019s start with a first-revision Sound Blaster Pro! Add the following snippet to your config:
[sblaster]\nsbtype = sbpro1\nWe want to hear how the Sound Blaster Pro 1 sounds with the default, unaltered volume levels, so make sure to comment out the previously added mixer command in the [autoexec] section by prefixing it with a # character (Shift+3 on the US keyboard layout):
[autoexec]\nimgmount D \"cd/cdrom1.iso\" -t iso\nc:\ncd sky\n#mixer opl 50 sb 500 /noshow\nsky\nIt seems this simple change alone does the trick; now the speech can be heard clearly over the music and the overall volume level is good too! Of course, you can still fine-tune the individual channel volumes with the mixer command if you wish to do so.
Another option we can try is not letting the game mess around with the OPL and digital audio volumes. Starting from the Sound Blaster Pro, programs can alter the volume levels of the Sound Blaster mixer, but we can disallow that by turning off the sbmixer setting. Comment out the sbtype setting because we want to experiment with our default Sound Blaster 16 model, and leave the mixer command in the [autoexec] section commented out too, of course.
[sblaster]\n#sbtype = sbpro1\nsbmixer = off\nWell, that\u2019s another way of fixing the issue; the volume levels are now perfect!
Warning
Not letting a game adjust volume levels can sometimes backfire, e.g., in a game that intelligently lowers the OPL music level whenever speech is playing. But it\u2019s worth a shot; quite a few games benefit from wrestling the control from them and putting the mixer into \u201cmanual mode\u201d.
"},{"location":"getting-started/beneath-a-steel-sky/#adjusting-the-emulated-cpu-speed","title":"Adjusting the emulated CPU speed","text":"Okay, we\u2019re going to do a little experiment next!
In the opening scene, keep pressing the left mouse button repeatedly on the door, about two times per second, to keep starting and then stopping the speech. You\u2019ll very likely hear audio stuttering and dropouts, ranging from subtle to quite severe, depending on how powerful your computer is. Also, if you did watch the intro video (which I told you to skip for now), you\u2019d hear similar random audio stutterings from time to time.
What\u2019s happening here? Well, DOS gaming spans almost two decades, and there were lots of different CPUs in use during that period, all having wildly different performance, or clock speeds. DOSBox doesn\u2019t emulate any specific CPU but a \u201cgeneric\u201d one. So how does it know at what speed to run a particular game then?
It doesn\u2019t.
To explain what\u2019s going on, we\u2019ll need to understand a few technical details. It won\u2019t hurt too much, I promise!
"},{"location":"getting-started/beneath-a-steel-sky/#real-and-protected-mode","title":"Real and protected mode","text":"DOS games can be divided into two categories: older games, and newer games (who would\u2019ve guessed?) Older games released before about 1993 use something called real mode, while newer games released from 1993 onwards use protected mode. The important distinction here is that most CPU-hungry games are protected mode games (e.g., FPS games and flight simulators), while older pre-1993 real mode games generally have much less demanding performance requirements. Figuring out what exact CPU speed a particular game needs is almost impossible at the emulator level, but detecting whether a game uses real or protected mode is trivial. Therefore, DOSBox does the following automatic speed calibration by default:
For real mode games, it defaults to emulating 3000 CPU instructions per millisecond.
For protected mode games, it emulates as many CPU instructions as it can per millisecond.
The reasoning here is that older games are often sensitive to CPU speed; they might run too fast or misbehave if the CPU is too performant, hence the more conservative setting. Newer, more demanding games, however, benefit from the extra speed advantage and can generally handle faster processors without negative side effects.
While this approach generally gets all games running, manual tweaking of the emulated CPU speed is often required to make any particular game run smoothly. Protected mode games running at the maximum emulable CPU speed are particularly problematic because there might not be enough power left for smooth, glitch-free audio emulation. There\u2019s zero point in emulating a faster CPU than what the game needs as all that extra work could be put to better use\u2014such as smoother audio emulation.
Beyond a Steel Sky is a protected mode game, but how we do know that? Let\u2019s comment out the last sky command in the [autoexec] section to prevent the game from auto-starting, then launch DOSBox Staging in windowed mode. DOSBox itself always starts in real mode, and let\u2019s take a look at the text in the DOSBox window\u2019s title bar! It starts with the following:
DOSBOX - 3000 cycles/ms\nRemember what we learned earlier: in real mode, DOSBox defaults to emulating 3000 CPU instructions, or cycles, per millisecond. The text in the title bar tells us the current cycles value, so indeed, we must be running in real mode now!
Now start the game with the sky command and keep your eyes peeled on the title bar. The text will soon change to the following:
SKY - max 100%\nSKY is the name of the executable that\u2019s running, and what do we see after that? max 100%! That\u2019s the tell-tale sign of a protected mode game because, as mentioned, DOSBox tries to emulate the fastest CPU it can in protected mode.
And that\u2019s the crux of the problem\u2014there\u2019s not enough horsepower left to emulate the time-critical audio output without stuttering and glitches. The solution is kind of obvious: instead of letting DOSBox run amok with the CPU emulation, we\u2019ll restrict it to a reasonable speed.
We do that by specifying the number of CPU instructions, or cycles, to emulate per millisecond with the following config snippet:
[cpu]\ncycles = 12000\nRestart DOSBox Staging and do the \u201cdoor test\u201d again. All the audio glitches are now gone! Well done, time for a beer (or your beverage of choice)!
Real and protected mode
In very simple terms, real mode is a programming model that uses the legacy 16-bit mode of an Intel 386 or later CPU, while protected mode takes full advantage of its capabilities and runs in 32-bit mode. Protected mode is the real deal, but it couldn\u2019t be universally utilised until 386 or better CPUs had gained widespread adoption. That happened around the year 1993; games released from thereon use protected mode almost exclusively.
You can easily spot protected mode games by the presence of so-called DOS extenders in their main game directories. DOS4GW.EXE, PMODEW.EXE, and CWSDPMI.EXE were the most popular ones.
But you don\u2019t need to worry about all that detail as DOSBox will indicate with 100% accuracy whether a game runs in real or protected mode. Just set cycles to auto, then watch the title bar of the DOSBox Staging window while running the game.
Ok, so why 12\u2009000 and not any other number? The game\u2019s manual states that a 386 or better processor is required. Indeed, the game works fine at 6000 cycles which approximates a 386DX CPU running at 33 MHz, but the loading times are a bit on the slow side. Setting cycles to 12\u2009000\u2014which roughly corresponds to a 486DX2/66 with \u201cturbo mode\u201d off, running at 33 MHz\u2014speeds up the loading considerably while not causing any negative side effects. This is not surprising as the DX2/66 was one of the most popular CPUs in the 1990s for gaming. This is what Wikipedia says about it:
The i486DX2-66 was a very popular processor for video game enthusiasts in the early to mid-90s. Often coupled with 4 to 8 MB of RAM and a VLB video card, this CPU was capable of playing virtually every game title available for years after its release, right up to the end of the MS-DOS game era, making it a \u201csweet spot\u201d in terms of CPU performance and longevity.
The following table gives you reasonable rough cycles values for the most popular processors:
Emulated CPU MHz MIPS Approx. cycles 8088 4.77 ~0.3 300 286 8 ~0.7 700 286 12 ~1.5 1500 386SX 20 ~3 3000 386DX 33 ~6 6000 486DX 33 ~12 12\u2009000 486DX2 66 ~25 25\u2009000 Intel Pentium 90 ~50 50\u2009000 Intel Pentium MMX 166 ~100 100\u2009000 Intel Pentium II 300 ~200 200\u2009000Always treat these values only as starting points; as explained previously, accurately emulating the speed of any given processor is not possible due to the \u201cabstract\u201d nature of DOSBox\u2019s CPU emulation approach. But from a practical point of view, this does not matter; you just need to find the optimal cycles value the game works well with.
You can fine-tune the cycles setting while playing the game with the Ctrl+F11 and Ctrl+F12 shortcuts (Cmd+F11 and Cmd+F12 on the Mac); these will increase the cycles value by 10%, or decrease it by 20%, respectively. Once you\u2019ve arrived at a good setting, just update your config according to the cycles value displayed in the DOSBox Staging window\u2019s title bar.
Always try to find the minimum cycles value for each game that gives you an adequate performance to conserve host CPU power and reduce the likelihood of audio glitches\u2014overdoing it only makes things worse. Finally, here\u2019s a list of CPU speed sensitive games that should give you further tips and pointers.
"},{"location":"getting-started/beneath-a-steel-sky/#setting-up-roland-mt-32-sound","title":"Setting up Roland MT-32 sound","text":""},{"location":"getting-started/beneath-a-steel-sky/#installing-the-mt-32-roms","title":"Installing the MT-32 ROMs","text":"You might have noticed the game offers a sound option called \u201cRoland\u201d in its setup utility. What this refers to is the Roland MT-32 family of MIDI sound modules. These were external devices you could connect to your PC that offered far more realistic and higher-quality music than any Sound Blaster or AdLib sound cards were capable of. They were the Cadillacs of DOS gaming audio for a while, and they still sound pretty good even by today\u2019s standards.
DOSBox Staging can emulate all common variants of the MT-32 family, but it requires ROM dumps of the original hardware devices to do so. So first we need to download these ROMs from here as a ZIP package, then copy the contents of the archive into our designated MT\u201132 ROM folder:
WindowsC:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\mt32-roms\\ macOS ~/Library/Preferences/DOSBox/mt32-roms/ Linux ~/.config/dosbox/mt32-roms/ If the above download link doesn\u2019t work, search for \u201cmt32 roms mame\u201d and \u201ccm32l roms mame\u201d in your favourite search engine and you\u2019ll figure out the rest\u2026
After you\u2019ve copied the ROM files into the appropriate location for your platform, start up DOSBox Staging again and run the mixer /listmidi command. This will verify your MT-32 ROM files and print a y character below the MT-32 ROM versions that have been successfully detected. The green y character indicates the currently selected MT-32 version. You should get an output similar to this:
As you might have guessed already, you can tell DOSBox Staging to emulate an MT-32 model of a specific revision; you can read about that on our wiki. But in practice, these two models will cover 99% of your gaming needs:
cm32l Unless a specific MT-32 model is requested, DOSBox Staging emulates the Roland CM-32L by default which gives you the best overall compatibility. This is a 2nd generation MT-32 with 32 additional sound effects that many games make good use of. Certain studios, such as LucasArts, tended to favour the CM-32L, so their games sound a little better on this module. mt32_old Certain older games, most notably the early Sierra adventure catalogue, absolutely need a 1st generation MT-32; they will refuse to work correctly on any other model. For those games, use mt32_old. To enable MT-32 emulation and specify the model you wish to use, insert the following into your config:
[midi]\nmididevice = mt32\n[mt32]\nmodel = cm32l\nHow do you figure out which MT-32 model to use for a particular game? Well, you can\u2019t do that easily without a lot of research and trial and error, but thanks to the tireless work of certain prestigious individuals, you can simply refer to the list of MT-32-compatible computer games that tells you the correct model to use for most well-known games.
Let\u2019s consult the list and see what it says about Beneath a Steel Sky!
Requires CM-series/LAPC-I for proper MT-32 output. Buffer overflows on MT-32 \u2018old\u2019. Combined MT-32/SB output only possible using ScummVM
Well, the list knows best, so we\u2019ll use the CM-32L for our game (as we\u2019ve done in the above config example).
To appreciate the difference, you can try running the game with the mt32_old model after you\u2019ve had it successfully set up for the cm32l. You\u2019ll find the sound effects in the opening scene sound a lot better on the CM-32L.
So now DOSBox Staging emulates the CM-32L, but we also need to set up the game for \u201cRoland sound\u201d. (They could\u2019ve been a bit more precise and told us the game works best with the CM-32L, couldn\u2019t they? It\u2019s not even mentioned in the manual!)
Many games have a dedicated setup utility in the same directory where the main game executable resides. This is usually called SETUP.EXE, SETSOUND.EXE, SOUND.EXE, SOUND.BAT, or something similar. There is no standard, every game is different. You\u2019ll need to poke around a bit; a good starting point is to list all executables in the main game folder with the dir *.exe, dir *.com, and dir *.bat commands and attempt running the most promising-looking ones. The manual might also offer some helpful pointers, and so can the odd text file (.TXT extension) in the installation directory or the root directory of the CD (if the game came on a CD-ROM). Certain games have a combined installer and setup utility usually called INSTALL.EXE or SETUP.EXE which can be slightly disorienting for people with modern sensibilities. You\u2019ll get used to it.
This particular game turns things up a notch and does not copy the installer/setup utility into C:\\SKY as one would rightly expect. To reconfigure the game, you need to run INSTALL.EXE from the CD, so from the D drive (I\u2019ve told you\u2014setting up the game itself is part of the adventure!)
So let\u2019s do that. As we\u2019ve already installed the game on our C drive, we\u2019ll need to press Esc instead of Enter in the first Path Selection Window. Not exactly intuitive, but whatever. Now we\u2019re in the Setup Menu screen where we can change the language and configure the sound options. Select Roland sound, then press the Exit Install and Save Setup buttons to save your settings (don\u2019t even get me started\u2026)
Okay, now the moment of truth: start the game with the sky command. If nothing went sideways, we should hear the much-improved, glorious MT-32 soundtrack! Now we\u2019re cooking with gas!
So let\u2019s inspect our favourite door one more time\u2014hey, where did the voice-over go?! Yeah\u2026 you\u2019ve probably glossed over this little detail in the tip from the MT-32 wiki page:
Combined MT-32/SB output only possible using ScummVM
What this means for us ordinary mortals is that in the original game you can either use MT-32 for music and sound effects, and you get no speech; or you can use Sound Blaster for music, sound effects, and speech. MT-32 music and sound effects with speech via the Sound Blaster\u2014that\u2019s a no-go.
The game has just taught us an important life lesson: you can\u2019t have everything, especially not in the world of older DOS games. You\u2019ll have to pick what you value most: better music and only subtitles, or full voice-acting with a slightly worse soundtrack. I\u2019m opting for the latter, and remember, we can always improve the Sound Blaster / AdLib music by adding chorus and reverb. This will get us a little bit closer to the MT-32 soundtrack:
[mixer]\nreverb = large\nchorus = strong\nWe\u2019re on a roll here; the game seems to provide us with endless education opportunities. We\u2019ll divert our eyes (ears?) from the audio to the graphics next!
If you\u2019ve checked out the comic book included with the game (and you definitely should!) and you have a keen eye for detail, you might have noticed that the images in the intro sequence, which are scanned from the comics, appear vertically stretched on-screen. In fact, they appear exactly 20% taller than they should, which means the artwork was scanned using square pixels, then the stretching happens because of the 1:1.2 pixel aspect ratio of the 320\u00d7200 VGA screen mode (you might want to revisit the detailed explanation to refresh your memory).
Left: Screenshot from the intro with aspect ratio correction disabled (square pixels) Right: The original image from the comic book included with the gameAs we\u2019ve learnt previously, DOSBox Staging enables aspect ratio correction by default to make 320\u00d7200 graphics appear exactly as they would on a 4:3 aspect ratio VGA monitor, which requires pixels to be drawn 20% taller. This is the most sensible default as aspect ratio correction is absolutely needed for the vast majority of DOS games to look correct, but there are exceptions\u2014this game is one of those rare cases. We need to disable aspect ratio correction for such games. With aspect ratio correction disabled, we\u2019ll always get square pixels, no matter what (1:1 pixel aspect ratio).
That\u2019s quite easy to do, and we\u2019re also setting the viewport resolution to 4x scaling, effectively, because the game would appear too blocky when fit to fullscreen:
[render]\naspect = off\nviewport_resolution = 1280x800\nBeneath a Steel Sky with 1280\u00d7800 viewport resolution restriction and aspect ratio correction disabled
Beneath a Steel Sky \u2014 Well, we won\u2019t escape this way\u2026
Of course, this would\u2019ve been a very misguided effort if it had only fixed the intro graphics but not the in-game visuals. Fortunately, it turns out both the intro and the in-game content had been drawn assuming square pixels. For example, note how the floppy icon looks like a tallish rectangle with aspect ratio correction enabled; that\u2019s wrong, floppies should appear as perfect squares. Human figures and circular objects would also appear slightly elongated vertically with aspect ratio correction enabled. Ultimately, we know the game was developed by Revolution, a European studio, and they also released the game for PAL Amigas that have square pixels. We also know that Revolution was very fond of the Amiga, and thus can be considered an Amiga-first developer. For such games, disabling aspect ratio correction is almost always the correct answer.
So, the rules of thumb:
aspect = on
For most games where DOS was the leading platform. This is the DOSBox Staging default, and it ensures the overwhelming majority of DOS games appear correctly out of the box.
For games where the leading platform was the Amiga or Atari ST, but the game was developed by a North American studio for the NTSC standard (or the actual work was performed by a European studio, but it was commissioned by North Americans, and the game was primarily intended for the NTSC-only North American market).
aspect = off
Here\u2019s a non-exclusive list of the most important Amiga-first European studios:
Bitmap Brothers, Bullfrog, Coktel Vision, Core Design, DMA Design, Delphine, Digital Illusions, Firebird, Horror Soft / Adventure Soft, Infogrames, Level 9, Magnetic Scrolls, Ocean, Psygnosis, Revolution, Sensible Software, Silmarils, Team 17, Thalamus, Thalion, Ubisoft
From squares to rectangles
For the vast majority of computer games from the 80s and 90s featuring 2D graphics, the art was created once for the leading platform which was then reused in the various other platform conversions. It was just not economical to draw the graphics multiple times in different aspect ratios and resolutions, hence this was done extremely rarely.
We explained earlier that CRT monitors in the DOS era had a 4:3 aspect ratio, so in 320\u00d7200 mode the pixels had to be 20% taller for the image to completely fill the screen. DOSBox Staging does this aspect ratio correction by default which results in games primarily developed for DOS PCs assuming 1:1.2 pixel aspect ratio to look correct (as the artist intended).
But what about games where the leading platform was the Amiga or the Atari ST, and the game was developed by a European studio? The analog TV standard in Europe was PAL, therefore Amigas sold in Europe were PAL machines that had square pixels in the 320\u00d7256 screen mode, the resolution most commonly used by PAL Amiga games. So what these European studios usually did was to draw the art assuming square pixels, but using only a 320\u00d7200 portion of the 320\u00d7256 total available area. On PAL Amigas the art appeared in the correct aspect ratio, but letterboxed; on NTSC Amigas and DOS PCs that had the 320\u00d7200 low-res screen mode, the art filled the whole screen but appeared slightly stretched vertically (by 20%). No one seemed to complain about this, and they saved a lot of money by not having to draw the art twice, so this became a common practice.
However, now you have the option to enjoy these games in their correct aspect ratio, as per the artists\u2019 original intention by simply disabling DOSBox Staging\u2019s default aspect ratio correction.
Don\u2019t trust the circles!
Even keener observers might notice the image from the intro on the left features a circle that only appears perfect with aspect ratio correction enabled, in which case the image from the comics is stretched. But with aspect ratio correction disabled (as shown above), the circle appears to be a squashed oval, but the image from the comics looks perfect.
The explanation is simple: the person who drew the circle around the scanned image did it assuming 1:1.2 pixel aspect ratio, so it looked like a perfect circle to him on his PC VGA monitor.
That\u2019s a common theme: some games end up with assets added to them during the porting process, which can sometimes result in mixed aspect ratio assets in a single game. Sometimes it\u2019s just impossible to make the game appear correctly using a single fixed pixel aspect ratio, especially if such mixed aspect ratio assets are being displayed on screen at the same time.
Generally, you cannot trust the circles. Sometimes they will appear perfect when the correct aspect ratio is used, sometimes they won\u2019t. It\u2019s much more reliable to judge aspect ratio correctness by looking at common objects, human bodies, and human faces.
"},{"location":"getting-started/beneath-a-steel-sky/#final-configuration","title":"Final configuration","text":"Putting it all together, this is our final config:
[cpu]\ncycles = 12000\n[sdl]\nfullscreen = on\nviewport_resolution = 1280x800\n[render]\naspect = off\n# uncomment for VGA CRT emulation on a 4K display\n#glshader = crt/aperture\n[sblaster]\nsbmixer = off\n[midi]\nmididevice = mt32\n[mt32]\nmodel = cm32l\n[mixer]\nreverb = large\nchorus = strong\n[autoexec]\nimgmount d \"cd/cdrom1.iso\" -t iso\nc:\ncd sky\nsky\nexit\nWith this config, you can switch between Roland MT-32 and Sound Blaster / AdLib sound at will by only reconfiguring the game via INSTALL.EXE\u2014you don\u2019t need to make any further changes to the DOSBox config. In case you\u2019re wondering, enabling reverb and chorus does not add these effects to the MT-32 output by default; that\u2019s undesirable as the MT-32 has its own built-in reverb, so DOSBox Staging is intelligent enough not to apply double reverb to it.
We will continue our trend of featuring a disproportionate amount of LucasArts games in our guide. The game we\u2019ll tackle next is the Star Wars: Dark Forces demo from 1995, an example of the first-person shooter (FPS) genre, featuring fast software-rendered 3D graphics.
"},{"location":"getting-started/dark-forces/#installing-the-game","title":"Installing the game","text":"As per our usual routine, we\u2019ll create a new folder in DOS Games called Dark Forces, and the drives/c subfolder in it. The game demo comes in three ZIP archives, dforces1.zip, dforces2.zip, and dforces3.zip; we\u2019ll need to copy their contents to our virtual C drive. Make sure to download the manual as well.
There\u2019s a README.TXT included with the demo, it\u2019s recommended to read at least the installation and the keyboard shortcuts sections (use more README.TXT). The instructions tell us exactly what we need to do (this is why you should always check out the included text files):
I) INSTRUCTIONS FOR INSTALLING AND RUNNING DARK FORCES DEMO:\n\n1. Create a directory for the demo on your hard drive.\n (ex. C:\\DFDEMO)\n\n2. Extract the demo using PKUNZIP.EXE into the demo\n directory. If you have downloaded one or both of\n the cutscene files, then unzip them as well.\n\n3. From the demo directory, type \"demo\" and RETURN. This will\n bring you to the install menu. From the install menu, follow\n the on-screen instructions. Press \"I\" to install. This will\n take you through through the sound card setup program. When\n the install is finished it will bring you to the options\n menu. From there you type \"1\" to run Dark Forces. In the\n future, in order to get to the options menu, you should\n type \"demo\" from the your demo directory.\nWe actually don\u2019t need that DFDEMO folder, and we\u2019ve already extracted the contents of the three ZIP archives to our root directory on drive C, so just follow the instructions in step 3. Choose the Express Setup option in the sound configuration utility by pressing E, and the rest should be straightforward. The setup program will detect the Sound Blaster 16 correctly and will even play some test sounds.
After the setup has been completed, start the game by running demo again and then pressing the 1 key.
Star Wars: Dark Forces \u2014 Opening scene
"},{"location":"getting-started/dark-forces/#autotype","title":"Autotype","text":"Having to press the 1 key every time we start the game is not the end of the world, but it\u2019s not great either. Luckily, there\u2019s a way to automate that; the handy autotype DOSBox Staging command can simulate keypresses as implied by its name. This is what we need to put into our [autoexec] section to start the game without manual intervention:
[autoexec]\nc:\nautotype -w 0.5 1\ndemo\nexit\nThe first -w 0.5 argument of the autotype command specifies an initial 0.5 second wait time before the \u201cauto-typing\u201d begins. This is followed by the 1 argument which will simulate pressing the 1 key.
That\u2019s it! It\u2019s a simple but very useful feature. Run autotype /? to see the full list of available options and check out the list of AUTOTYPE candidates on our wiki for assorted real-life examples.
Dark Forces uses the 320\u00d7200 / 256-colour VGA screen mode, just like the majority of DOS games from the 90s. This mode uses a fixed 70 Hz screen refresh rate, so if your emulated CPU is fast enough, you can get 70 FPS out of the game.
But there\u2019s a problem: most modern non-variable refresh rate flat screens work at fixed 60 Hz. Luckily, DOSBox Staging intelligently times and drops frames if there\u2019s a mismatch between the refresh rate of the emulated graphics card and the actual refresh rate of your physical monitor. In most cases, this works fine out of the box without you needing to configure anything.
However, even though DOSBox Staging is trying to do its best in such situations, refresh rates will always result in some visible unevenness of motion. This is especially noticeable in games that feature smooth scrolling (e.g., shoot\u2019em up games, platformers, and pinball games), and in fast-paced 3D games, such as Dark Forces.
To achieve smoother motion, we have two options:
Using a variable-refresh rate (VRR) monitor \u2014 Nvidia G-Sync, AMD FreeSync, VESA AdaptiveSync, and Apple ProMotion certified displays all fall into this category. Any monitor that can continuously vary the refresh rate from about 59 to 71 Hz should do the job. DOSBox Staging automatically takes advantage of such displays by default.
Using specific fixed refresh rates on non-VRR monitors \u2014 Even if you\u2019re not a lucky owner of a VRR display, your monitor might support a fixed 70 Hz refresh rate if you create a custom screen mode for it. This is highly monitor dependent, but there\u2019s no harm in trying it out.
Note, however, that depending on the type of game, the 60/70 Hz mismatch might not matter much or at all. For instance, most adventure, strategy, and role-playing games rarely have fast-paced graphics; they generally only update the screen in the low 5-20 FPS range. Running the monitor at 70 Hz results in very little noticeable improvement with these games.
Another important consideration is that most pre-VGA games don\u2019t feature smooth movement in their graphics, so the general unevenness of motion masks the slight judder resulting from the 60/70 Hz mismatch.
For reference, these are the refresh rates of all emulated graphics cards:
Graphics adapter Refresh rate SVGA and VESA 70 Hz or higher \u2014 640\u00d7480 or higher extended and VESA modes VGA 60 Hz \u2014 640\u00d7480 standard mode only70 Hz \u2014 all other standard modes CGA, PCjr, Tandy, EGA 60 Hz Hercules 50 HzCreating custom 60 and 70 Hz screen modes
\u201cCustom resolution\u201d is a bit of a misnomer because what we\u2019re after is creating a new screen mode that uses your monitor\u2019s native resolution, but with a custom refresh rate.
You can create such custom resolutions using the Nvidia Control Panel or with the Custom Resolution Utility (CRU) on Windows. You\u2019ll probably need to enable CVT reduced blanking (CVT-RB or CVT-RBv2) to go up to 70 Hz. For the best results, it\u2019s recommended to use the exact fractional 59.713 Hz and 70.086 Hz refresh rates for the nominal \u201c60 Hz\u201d and \u201c70 Hz\u201d DOS rates, respectively.
The drawback of this approach is that you need to set the appropriate custom resolution before starting DOSBox Staging, and if a game switches between different refresh rates, well, you\u2019re out of luck\u2014these games can only work 100% correctly either on a true VRR display or a real old-school CRT monitor. However, most games only use a single fixed refresh rate, which is usually the standard 70 Hz VGA rate, so this technique is still very practical.
"},{"location":"getting-started/dark-forces/#vertical-syncing","title":"Vertical syncing","text":"Dark Forces synchronises its screen updates to the refresh rate of the emulated VGA card, which is always 70 Hz. This is hardcoded behaviour that cannot be disabled in the game\u2019s configuration.
DOSBox Staging itself also uses vertical syncing by default to synchronise updating the emulated image to the vertical refresh rate of your physical monitor. Without DOSBox-level vsync, fast-paced games such as this one would exhibit a lot of tearing. This is important to understand: to get zero tearing, vertical syncing must be happening both in the game and at the DOSBox level!
Conversely, DOSBox-level vsync only means that the emulated image is output to your physical monitor without flickering and tearing; the emulated DOS game itself might or might not use vertical syncing, and thus might or might not produce tearing artifacts of its own (these artifacts are present when running the game on real hardware too\u2014there\u2019s nothing we can do about them).
You don\u2019t have control over the vertical syncing behaviour in most DOS games. For example, Commander Keen 4\u20136, Doom, and many other FPS games have hardcoded vsync with a fixed 35 FPS cap. These games were programmed with fixed refresh rates in mind from the ground up; trying to disable the vsync or altering the FPS cap would completely break them (but the good news is you can\u2019t do that anyway).
To recap, the following variations are possible when it comes to vsync:
Game uses vsync? DOSBox-level vsync enabled? Result yes yes no tearing no yes some tearing; also present on real hardware yes no bad tearing (in fast-paced games) no no very bad double-tearing (in fast-paced games)As you can see, there is no point in disabling vsync in DOSBox itself, and even with DOSBox vsync enabled you might still get tearing in some games, but that\u2019s just how the games were coded. We can\u2019t \u201cfix\u201d that at the emulator level; that would require making changes to the games\u2019 code. On the other hand, that\u2019s the \u201cauthentic DOS experience\u201d for you!
"},{"location":"getting-started/dark-forces/#setting-the-emulated-cpu-speed","title":"Setting the emulated CPU speed","text":"Hardware-accelerated 3D graphics only became widespread in the second half of the 90s after the end of the DOS era, so most DOS games only use software rendering. Dark Forces is no exception, which means your emulated CPU needs to be fast enough to reach the 70 FPS maximum the game supports.
The game prints out the familiar message of the DOS/4GW DOS extender at startup, which means this is a protected mode game:
DOS/4GW Protected Mode Run-Time Version 1.95\nCopyright (c) Rational Systems, Inc. 1990-1993\nAs we\u2019ve learnt, protected mode games default to using all available CPU power. While this will most likely help achieve a stable 70 FPS (if your computer is powerful enough), running the CPU at maximum speed could starve the audio emulation, leading to audible glitches, clicks, and pops.
To avoid such issues, it\u2019s much preferable to emulate a CPU that is powerful enough to handle 70 FPS but not more. One way to come up with a good cycles number is to start the game with a relatively low cycles setting, say 10\u2009000, then keep increasing it with the Ctrl+F12 shortcut (Cmd+F12 on the Mac) while playing to arrive at the lowest value that results in adequate performance. As a reminder, you can decrease the current cycles value too with the Ctrl+F11 (Cmd+F11) shortcut.
So let\u2019s add the following to our config:
[cpu]\ncycles = 10000\nStart the game and hold the Left or Right key to keep turning around, then increase the cycles value until the motion becomes smooth (again, unless you\u2019re using a VRR monitor or a fixed 70 Hz refresh rate, it will never become completely smooth). Somewhere around 50\u2009000 cycles seems to do the trick, which roughly corresponds to a Pentium 90 based on our table of common processors.
So we\u2019ll go with that setting. You might need to increase this if later levels are more demanding on the CPU, but this is a good starting point:
[cpu]\ncycles = 50000\nRunning out of steam
As you keep increasing the fixed cycles value, the audio will start breaking up, and the motion will become very stuttery after a certain point. This means you\u2019re trying to emulate a faster CPU than your computer can handle. If you\u2019re on a less powerful machine, this unfortunately can happen before reaching the minimum cycles value necessary for a smooth and stable 70 FPS.
You have only two options in this situation: live with a lower cycles setting that results in less than 70 FPS, or buy a more powerful computer with a faster processor that can handle higher cycles values.
Also, make sure you\u2019re not running any other CPU-intensive programs at the same time in the background. Virus scanners, backup software, copying large files to USB storage, heavy network traffic, and even ordinary web browsers with many tabs open can chew up a significant part of your total CPU power. Certain popular chat programs can be very demanding on the CPU too, and, surprisingly, even innocent-looking stuff such as automatic wallpaper changers can have negative effects on the performance of DOSBox.
As a general rule, it\u2019s best to close all other programs if you\u2019re encountering performance issues with DOSBox and try again. Just apply common sense and treat DOSBox as any other performance-intensive modern game.
"},{"location":"getting-started/dark-forces/#setting-up-general-midi-sound","title":"Setting up General MIDI sound","text":"Our previous example game, Beneath A Steel Sky, supports the Roland MT-32 MIDI sound module to provide more realistic-sounding music than what the Sound Blaster\u2019s OPL synthesiser is capable of. Dark Forces, however, was composed for a newer family of MIDI sound modules that support the so-called General MIDI standard.
DOSBox Staging comes with an integrated General MIDI compliant synthesiser called FluidSynth. Unlike the MT-32 emulation, FluidSynth does not attempt to mimic any specific hardware device but a very generic MIDI sound module. This sound module doesn\u2019t have any built-in sounds\u2014you need to load so-called SoundFont files (.sf2 extension) into FluidSynth to get any sound out of it; these contain the instrument definitions and the sound data.
You can read more about the history of MIDI in DOS gaming at the end of this section, but the short practical summary is as follows:
The Roland Sound Canvas SC-55 was the de-facto standard General MIDI sound module until the very end of the DOS years (around 1997).
DOSBox Staging does not emulate the SC-55 directly, but there are SoundFonts you can load into FluidSynth that approximate the sound of the SC-55.
One extra detail is that Roland went a bit beyond the General MIDI standard in their Sound Canvas series; these modules actually support the GS standard, which is basically General MIDI plus some Roland-specific enhancements. Many games use these extra features, and while General MIDI compatible SoundFonts will work with them, for the best results it\u2019s recommended to use GS standard compatible ones.
One such SoundFont is GeneralUser GS; download the latest version, then copy the SoundFont file with the .sf2 extension into its designated folder:
C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\soundfonts\\ macOS ~/Library/Preferences/DOSBox/soundfonts/ Linux ~/.config/dosbox/soundfonts The next step is to configure DOSBox Staging to use this SoundFont for General MIDI playback. The name of the SoundFont might be slightly different if a new version has been released since the writing of this guide; make sure you use the correct filename for the soundfont setting.
[midi]\nmididevice = fluidsynth\n[fluidsynth]\nsoundfont = \"GeneralUser GS v1.471.sf2\"\nThe only thing left to do is to reconfigure the game to use General MIDI for music:
Comment out the autotype command in the [autoexec] section and restart DOSBox.
Press 3 in the startup menu to reconfigure the sound settings, then C to do a custom setup.
Enter the Advanced Menu (it\u2019s above Quit at the bottom).
Select the General MIDI device for Music, and select the default 330 value for the Port setting.
The Digital Sound settings don\u2019t need changing as our Sound Blaster 16 has been auto-detected correctly.
The final configuration should look like this:
Press Enter on the Test Music menu item and you should hear the start of the Imperial March playing with much more realistic instruments!
How to drive a manual
Note that if you try to use Detect in the Music section, the auto-detection will fail and the Music option will revert to None. This can happen with some setup utilities, therefore it\u2019s important to know that the port of the General MIDI device must be set to 330, should the auto-detection fail. This is sometimes called the MPU-401 port, MPU port, or just MIDI port.
Similarly, most games can auto-detect the Sound Blaster settings, but sometimes you need to enter them manually. The default DOSBox settings are port (I/O address) 220, IRQ (interrupt) 7, and DMA channel 1.
It\u2019s worth watching the whole intro at this point to appreciate how much more realistic the General MIDI rendition of this orchestral piece sounds compared to the OPL synth.
Of course, you can always try other GM or GS compatible SoundFonts too\u2014that\u2019s the beauty of General MIDI! FluidR3_GM_GS and Creative Labs 4M GM_4gmgsmt are good candidates as they sound fairly close to the SC-55 sound set. The list of recommended SoundFonts on our wiki should also give you some further pointers on which SoundFonts are worth trying and where to find them.
Note that while some SoundFonts, such as GeneralUser GS, give you overall good results in most games, other SoundFonts might excel in a handful of titles and sound terrible in others. To give you an idea, here\u2019s how the intro music sounds on the original Roland SC-55 hardware versus a few different SoundFonts. As mentioned, GeneralUser GS and Creative 4GMGSMT are the closest in terms of overall balance and character, the rest are rather hit-and-miss. My advice: just pick one that gives you good overall results and stick with it.
Further comparison recordings can be found on our wiki.
Roland SC-55 v1.21 (hardware) Your browser does not support theaudio element. GeneralUser GS Your browser does not support the audio element. Creative 4GMGSMT Your browser does not support the audio element. FluidR3_GM_GS Your browser does not support the audio element. FatBoy Your browser does not support the audio element. Arachno Your browser does not support the audio element. Turn it down, please!
Some SoundFonts are way too loud; if you encounter such a SoundFont, you\u2019ll most likely want to lower the output level of FluidSynth. For example, to scale back the volume to 40%, use the mixer fsynth 40 command. A few SoundFonts are extremely loud\u2014you need to turn the FluidSynth volume down to 10-20% to get usable levels. It\u2019s a mystery what the authors were thinking\u2026
Roland MT-32 is not General MIDI
Do not confuse the Roland MT-32 family of MIDI sound modules with General MIDI modules! Music composed for the MT-32 sounds utterly wrong on a General MIDI module, and vice versa. Yes, they both have \u201cMIDI\u201d in their names, but that only refers to the communication protocol. The MT-32 range of devices are fully programmable synthesisers and most games take advantage of their sound-shaping capabilities, while the General MIDI modules have much more modest synthesis capabilities, but feature more realistic-sounding real-world instruments (the soundtrack of Dark Forces showcases this very well\u2014you just can\u2019t get such realistic orchestral music out of an MT-32).
Whenever you want to configure a new game for MIDI sound, you should consult the list of MT-32-compatible computer games to see if the game was originally composed for the MT-32 or a General MIDI device (typically the SC-55). The original game manuals very rarely give you this info, so you absolutely need this list that contains the hard-earned knowledge of many decades of research and testing.
Quite confusingly, there\u2019s an alarmingly large list of games that falsely claim MT-32 compatibility in their setup utility, but they in fact require a General MIDI module to sound correct. Before you configure any game for MT-32 sound, you should definitely check the list of games that falsely claim MT-32 compatibility too, no matter what the game\u2019s manual says (quite often, the information contained therein is simply wrong).
A brief history of MIDI in DOS gaming
In the beginning, the iconic Roland MT-32 family of devices were the only MIDI sound modules available for DOS games that made realistic-sounding music a possibility. The original MT-32 was released in 1987, and its hegemony ended in 1991 with Roland unleashing its successor, the similarly iconic Roland Sound Canvas SC-55.
The SC-55 was another pioneering effort that shaped DOS gaming history in significant ways: it was the world\u2019s first device to support the General MIDI standard and the GS standard (the latter being Roland\u2019s vendor-specific General MIDI extensions). MIDI in the broadest sense only defines a communication mechanism between MIDI-capable devices (e.g., a sound module and your computer), but remains silent on how the different instruments should sound. General MIDI (GM) remedied this with its 128 standard instrument definitions; for example, you can be sure that on any GM-compliant module instrument #1 is the Acoustic Grand Piano and instrument #36 is the Fretless Bass.
This made interoperation between GM-compliant devices possible. In theory, you could use any General MIDI sound module with any GM-compliant game, and you would get music, and it would sound mostly correct. In practice, that \u201cmostly\u201d part is highly variable and it depends on the musical composition and the particular sound module in use. The thing is, most composers and gamers had the SC-55, establishing it as a de-facto standard (understandably, because it was the very first GM module). Other GM sound modules can render musical compositions written for the SC-55 unbalanced and weird-sounding, depending on how different their instruments sound compared to the \u201cstandard\u201d SC-55.
Another thing that makes compatibility difficult to achieve is that the SC-55 supports not just the GM but also the GS standard, and many games make good use of certain GS-only features. This means that any other General MIDI module that claims \u201cSound Canvas compatibility\u201d also has to implement the GS standard in a manner that sounds very close to the SC-55, which is not always the case.
"},{"location":"getting-started/dark-forces/#dynamic-range-compression","title":"Dynamic range compression","text":"If a game has loud music and you set the output level of your soundcard too high, you\u2019ll get rather unpleasant-sounding distortion and crackling on real hardware. DOSBox Staging has a dynamic range compressor on the master channel that automatically pulls the volume back on loud sounds to prevent such distortion from happening.
You can test this by playing the game for a minute with the GeneralUser GS SoundFont. You might notice a slight \u201cpumping\u201d as the compressor pulls the volume back on loud sound effects; this dips the volume level of the background music as well.
To hear the distortion caused by the loud sounds clearly, disable the master compressor:
[mixer]\ncompressor = off\nOverall, the compressor does a good job of preventing audible distortion up to a certain point, and most users should not think much about it; it just works. But if the master channel is overdriven heavily, the pumping artifacts would be rather distracting, so in that case, it\u2019s better to lower the master volume with the mixer command (e.g., mixer master 50 to set the master volume to 50%). People who are after the best audio quality should also prefer lowering the master volume rather than relying on the compressor.
The sound output of Dark Forces is on the loud side, so we\u2019ll set the output to 50% to make sure the compressor is never engaged:
[autoexec]\nc:\nmixer master 50\nautotype -w 0.5 1\ndemo\nexit\nThe sound setup utility asks us to confirm whether the left and right audio channels should be swapped when setting up digital audio. Weird as it may sound, some Sound Blaster models and clones had \u201creversed stereo\u201d for some inexplicable reason. If people used any of these cards during the development of a game, the stereo image would be reversed on normal cards, and vice versa.
Irrespective of the exact reasons, the fact is that some games with stereo digital audio support have the left and right channels reversed. In affected games, the channels might be reversed on all Sound Blaster variants, or only on certain models.
In the case of Dark Forces, you don\u2019t need to use the \u201creverse stereo\u201d option when emulating a Sound Blaster 16 card (which is the default). However, when using the Sound Blaster Pro 1 model (sbtype = sbpro1), the stereo image needs to be reversed.
But what about games that don\u2019t have such a handy \u201creverse stereo\u201d option in their setup utility? For those games, you can simply reverse the left and right channels of the SB mixer channel with the mixer sb reverse command. (Remember, use mixer /? to list all available commands and options.)
Even after setting the optimal cycles value for the game to limit the emulated CPU speed, you might still hear occasional audio glitches. Why this can happen depends on a lot of factors, but mainly it comes down to the particular hardware, driver, and operating system combination you\u2019re using.
As a last resort, you can try setting larger audio buffers sizes; this usually helps eliminate the occasional clicks and pops. The downside of this is that it will also increase audio latency, meaning that you\u2019ll hear the audio in response to some action with a longer delay (e.g., when shooting with a gun).
The default blocksize value is 1024 on Windows and 512 on macOS and Linux. The default prebuffer size is 25 on Windows and 20 on the other platforms (this is specified in milliseconds). You can experiment with increasing these settings\u2014doubling them is a good start. Generally, prebuffer can be anything, and blocksize should be one of the following values: 256, 512, 1024, 2048, 4096, or 8192.
[mixer]\nblocksize = 2048\nprebuffer = 50\nHere\u2019s the full config of Dark Forces set up for General MIDI sound:
[sdl]\nfullscreen = on\nviewport_resolution = 1120x840\n[cpu]\n# to emulate a Pentium 90\ncycles = 50000\n[midi]\nmididevice = fluidsynth\n[fluidsynth]\nsoundfont = \"GeneralUser GS v1.471.sf2\"\n[autoexec]\nc:\nmixer master 50\nautotype -w 0.5 1\ndemo\nexit\nYou can toggle between windowed and fullscreen mode at any time by pressing Alt+Enter. But what if you always want to play the game in fullscreen? Wouldn\u2019t it be nice to configure DOSBox to start in fullscreen mode?
You can easily do that by setting fullscreen = on in the [sdl] section. Modify your dosbox.conf file so it has the following content, then restart DOSBox Staging.
[sdl]\nfullscreen = on\n[autoexec]\nc:\nprince\nexit\nNote we\u2019ve also added the exit command to the end of the [autoexec] section; with this in place, DOSBox will quit itself after we exit from the game by pressing Ctrl+Q. Not strictly necessary, but a nice touch.
Toggling options
For configuration settings that toggle an option, you can use on, enabled, yes, true or 1 for turning the option on, and off, disabled, no, false or 0 for turning it off.
Making configuration changes
You need to quit and restart DOSBox Staging after updating dosbox.conf for the changes to take effect. We will not mention this every single time from now on.
That\u2019s nice, but depending on the size of your monitor, 320\u00d7200 VGA graphics displayed in fullscreen on a 24\u201d or 27\u201d modern monitor might appear overly blocky. If only we could control the size of the image in fullscreen as easily as we can in windowed mode!
Well, it turns out we can! You can restrict the viewport size by adding the viewport_resolution setting to the [sdl] section. In this case, we\u2019re restricting the viewport to a maximum size of 1120 by 840 pixels. The emulated video output will be sized so it fits within the bounds of this rectangle while keeping the correct aspect ratio.
[sdl]\nfullscreen = on\nviewport_resolution = 1120x840\nWe\u2019re effectively applying a 3.5\u00d7 scaling factor here to the 320\u00d7200 VGA graphics:
Huh, what? Where\u2019s the 840 in our config coming from then?
Computer monitors were originally not widescreen but had a 4:3 aspect ratio, just like old television sets. The complete switch to 16:9 in computer monitors and laptops happened only by the early 2010s. The low-resolution 320\u00d7200 VGA mode was designed to completely fill a 4:3 monitor, but that\u2019s only possible if the pixels are not perfect squares, but slightly tall rectangles. If you do the maths, it turns out they need to be exactly 20% taller for the 320\u00d7200 VGA screen mode (1:1.2 pixel aspect ratio). 700 \u00d7 1.2 = 840, so that\u2019s the explanation.
Prince of Persia in fullscreen with 1120\u00d7840 viewport resolution restriction
In any case, you don\u2019t need to worry about aspect ratio correctness because DOSBox Staging handles that automatically for you out of the box. It\u2019s just good to have some level of understanding of what\u2019s really happening. If you specify 1120x700, that would also work, but because aspect ratio correction is enabled by default, and the image must fit within the bounds of the specified viewport rectangle, the dimensions of the resulting image will be 933 by 700 pixels (because 700 \u00d7 4/3 = 933).
But hey, not everybody likes maths, especially in the middle of a DOS gaming session, so you can also specify the viewport resolution as a percentage of your desktop resolution:
viewport_resolution = 80%\nWhen pixels are not squares
Sadly, this very important fact of computing history that monitors were not widescreen until about 2010 tends to be forgotten nowadays. Older DOSBox versions did not perform aspect ratio correction by default, which certainly did not help matters either. The unfortunate situation is that you\u2019re much more likely to encounter videos and screenshots of DOS games in the wrong aspect ratio (using square pixels) on the Internet today. Well, that\u2019s only true for more recently created content\u2014if you check out old computer magazine from the 1980s and the 90s, most screenshots are shown in the correct aspect ratio (rarely, the magazines got it wrong too\u2026)
In case you\u2019re wondering, pixels are completely square in 640\u00d7480 and higher resolutions (1:1 pixel aspect ratio), but there exist a few more weird screen modes with non-square pixels, e.g., the 640\u00d7350 EGA mode with 1:1.3714 pixel aspect ratio (PAR), the 640\u00d7200 EGA mode with 1:2.4 PAR, and the 720\u00d7348 Hercules graphics mode with 1:1.5517 PAR.
"},{"location":"getting-started/enhancing-prince-of-persia/#graphics-adapter-options","title":"Graphics adapter options","text":"DOSBox emulates an SVGA (Super VGA) display adapter by default, which gives you good compatibility with most DOS games. DOSBox can also emulate all common display adapters from the history of the PC compatibles: the Hercules, CGA, and EGA display adapters, among many others.
Although the VGA standard was introduced in 1987, it took a good five years until it gained widespread adoption. Games had to support all commonly used graphical standards during this transitional period. Prince of Persia, released in 1990, is such a game; it not only supports all common display adapters, but it also correctly auto-detects them. This is in contrast with the majority of DOS games where you need to configure the graphics manually.
"},{"location":"getting-started/enhancing-prince-of-persia/#vga","title":"VGA","text":"The art in Prince of Persia was created for VGA first, so quite naturally the game looks best on a VGA adapter. Most DOS games from the 1990s use the 320\u00d7200 low-resolution VGA mode that allows up to 256 colours to be displayed on the screen, chosen from a palette of 16 million colours.
Prince of Persia in VGA mode with the default settings
"},{"location":"getting-started/enhancing-prince-of-persia/#ega","title":"EGA","text":"Most games with EGA support use the 320\u00d7200 low-resolution EGA mode that has a fixed 16-colour palette.
To run Prince of Persia in EGA mode, you simply need to tell DOSBox to emulate a machine equipped with an EGA adapter. That can be easily done by adding the following configuration snippet:
[dosbox]\nmachine = ega\nThis is how the game looks with the fixed 16-colour EGA palette:
Prince of Persia in EGA mode
That\u2019s nice, but it\u2019s not exactly how the graphics looked on an EGA monitor back in the day. Pre-VGA monitors had visible scanlines, and we can emulate that by enabling an OpenGL shader that emulates the CRT monitors (Cathode-Ray Tube) of the era:
[render]\nglshader = crt/aperture\nThis adds some texture and detail to the image that\u2019s especially apparent on the solid-coloured bricks:
Prince of Persia in EGA mode using the crt/aperture shader
If you have a 4K display, you might want to try the crt/fakelottes.tweaked shader. Another good one is crt/geom.tweaked.
The crt/zfast shader is a good choice for older or integrated graphics cards, and the crt/pi was specifically optimised for the Raspberry Pi.
You can view the full list of included CRT shaders here.
"},{"location":"getting-started/enhancing-prince-of-persia/#cga","title":"CGA","text":"The notorious CGA adapter, the first colour graphics adapter created for the original IBM PC in 1981, is a serious contender for the worst graphics standard ever invented. In its 320\u00d7200 low-resolution mode, 4 colours can be displayed simultaneously on the screen chosen from a number of fixed palettes. Frankly, all combinations look pretty horrible\u2026
But no matter; the game supports it, so we\u2019ll have a look at it. Make the following adjustment to the machine setting, and don\u2019t forget to put on your safety glasses!
[dosbox]\nmachine = cga\nReady? Behold the formidable 4-colour CGA graphics\u2014and what 4 colours those are!
Prince of Persia in CGA mode using the crt/aperture shader
Tip
To compare how the game looks on different graphics adapters, click on one of the CRT shader screenshots to enlarge it, then use the Left and Right arrow keys to switch between the images.
Warning
Screenshots of CRT shaders in action need to be viewed at 100% magnification; otherwise, you might see strange wavy interference patterns on them caused by the browser rescaling the images. These unwanted artifacts can sometimes resemble repeating rainbow-like patterns, and rest assured, that\u2019s not how CRT emulation is supposed to look in DOSBox Staging!
To view a screenshot featuring a CRT shader properly, click on the image to enlarge it, then if your mouse cursor looks like a magnifying glass, click on the image again to display it with 100% magnification.
"},{"location":"getting-started/enhancing-prince-of-persia/#hercules","title":"Hercules","text":"The Hercules display adapter was released in 1982 to expand the text-only IBM PCs with basic graphical capabilities. It only supports monochrome graphics, but at a higher 720\u00d7348 resolution. Can you guess how you can enable it?
[dosbox]\nmachine = hercules\nIf you wish to use a CRT shader, the crt/aperture.mono shader variant has been specifically created for emulating monochrome monitors (it switches off the RGB phosphor and aperture grille emulation of the base crt/aperture shader).
[render]\nglshader = crt/aperture.mono\nPrince of Persia in Hercules mode using the white paletteand the crt/aperture.mono shader
Monochrome monitors came in different colours; DOSBox Staging can emulate all these variations via the monochrome_palette configuration setting. The available colours are white (the default), paperwhite, green, and amber. You can also switch between them while the game is running with the F11 key on Windows and Linux, and Alt+F11 on macOS.
[dosbox]\nmachine = hercules\nmonochrome_palette = amber\nThe slightly squashed aspect ratio is correct in this case; this is exactly how the game would look on a PC equipped with a Hercules card connected to a period-accurate monochrome monitor.
Hercules mode using the amber palette
Hercules mode using the green palette
Only for masochists and archeologists!
The art in DOS games was usually created for the best graphics standard the game supported, then variants for \u201clesser\u201d standards were derived from that. If you were an unlucky person still stuck with a Hercules or CGA adapter in 1990, being able to play Prince of Persia with any graphics surely beat no game at all!
Although we\u2019ve shown how to emulate these earlier graphics standards for completeness\u2019 sake, there\u2019s generally little reason for not playing a DOS game with the best graphics. The list of possible reasons include: a) strong nostalgic feelings towards a particular display adapter; b) research reasons; c) you like your games to look like the user interface of an industrial CNC machine; d) a preference for pain. But hey, who are we to judge?
In any case, preserving all relevant aspects of PC gaming history is important for the DOSBox Staging project, so these display options are always available at your fingertips, should you ever need them.
"},{"location":"getting-started/enhancing-prince-of-persia/#true-vga-emulation","title":"\u201cTrue VGA\u201d emulation","text":"If you\u2019re the lucky owner of a high-resolution monitor with at least 2000 pixels of native vertical resolution (4K or better monitors belong to this category), you can use \u201ctrue VGA\u201d emulation that more accurately resembles the output of an actual CRT VGA monitor.
VGA display adapters have a peculiarity that they display not one but two scanlines per pixel in all low-resolution screen modes that have less than 350 lines. This means the 320\u00d7200 low-resolution VGA mode is really 640\u00d7400, just pixel and line-doubled.
To emulate this, we\u2019ll use a CRT shader and exact 4-times scaling by setting the viewport resolution to 1280\u00d7960. This is important for getting even scanlines, and it doesn\u2019t work on regular 1080p monitors because there\u2019s simply not enough vertical resolution for the shader to work with.
Logical vs physical pixels
Wait a minute, 1280\u00d7960 fits into a 1920x1080 screen, doesn\u2019t it? Why did you say we need a 4K display for this then?
Most operating systems operate in high-DPI mode using a 200% scaling factor on 4K displays. This means that the pixel dimensions used by the applications no longer represent physical pixels, but rather logical or device-independent pixels. On a 4K display, assuming a typical 200% scaling factor, our viewport resolution specified in 1280\u00d7960 logical pixels will translate to 2560\u00d71920 physical pixels. A vertical resolution of 1920 pixels is certainly sufficient for displaying those 400 scanlines; the shader can use 4.8 pixels per scanline to do its magic (generally, you need at least 3 pixels per \u201cemulated scanline\u201d to achieve good results).
These are the relevant configuration settings to enable authentic double-scanned VGA emulation:
[sdl]\nviewport_resolution = 1280x960\n[render]\nglshader = crt/aperture\nHere\u2019s a comparison of how true VGA emulation looks at 4K resolution compared to the standard \u201craw sharp pixel\u201d look (zoom in to appreciate the differences):
Left: \u201cTrue VGA\u201d emulation; Right: default output (\u201craw sharp pixels\u201d)
"},{"location":"getting-started/enhancing-prince-of-persia/#chorus-reverb","title":"Chorus & reverb","text":"We\u2019ve been discussing graphics at great length, but what about sound? Can\u2019t we do something cool to the sound as well?
Yes, we can! DOSBox Staging has an exciting feature to add chorus and reverb effects to the output of any of the emulated sound devices.
Create a new [mixer] section in your config with the following content:
[mixer]\nreverb = large\nchorus = normal\nNow the intro music sounds a lot more spacious and pleasant to listen to, especially through headphones. There\u2019s even some reverb added to the in-game footsteps and sound effects, although to a much lesser extent.
You might want to experiment with the small and medium reverb presets, and the light and strong chorus settings as well.
Purist alert!
To calm the purists among you: adding reverb and chorus to the OPL synthesiser\u2019s output is something you can do on certain Sound Blaster AWE32 and AWE64 models on real hardware too via the standard drivers.
"},{"location":"getting-started/enhancing-prince-of-persia/#auto-pause","title":"Auto-pause","text":"Prince of Persia can be paused by pressing the Esc key during the game. But wouldn\u2019t it be convenient if DOSBox could auto-pause itself whenever you switch to a different window? You can easily achieve that by enabling the pause_when_inactive option in the [sdl] section.
[sdl]\nfullscreen = on\nviewport_resolution = 1120x840\npause_when_inactive = yes\nRestart the game and switch to a different window\u2014DOSBox has paused itself. Switch back to DOSBox\u2014the game resumes. Nifty, isn\u2019t it? This is quite handy for those games that have no pause functionality, or when you need to take a break during a long cutscene that cannot be paused.
"},{"location":"getting-started/enhancing-prince-of-persia/#final-configuration","title":"Final configuration","text":"Below is the full config with all the enhancements we\u2019ve added, including authentic VGA CRT monitor emulation on 4K displays.
[sdl]\nfullscreen = on\nviewport_resolution = 1280x960\npause_when_inactive = yes\n[render]\nglshader = crt/aperture\n[mixer]\nreverb = large\nchorus = normal\n[autoexec]\nc:\nprince\nexit\nIf you\u2019re not on a high-DPI display, just delete the whole [render] section to disable the CRT shader.
Instead of deleting those lines, you can prefix them with a # character (Shift+3 on the US keyboard layout) to turn them into comments.
Comments are lines starting with a # character; DOSBox ignores them when reading the configuration. Normally, you would use them to add, well, comments to your config, but \u201ccommenting out\u201d a line is a quick way to disable it without actually removing the line.
[sdl]\nfullscreen = on\nviewport_resolution = 1280x960\npause_when_inactive = yes\n[render]\n#glshader = crt/aperture\n[mixer]\nreverb = large\nchorus = normal\n[autoexec]\nc:\nprince\nexit\nNote we haven\u2019t commented out the [render] section itself. That\u2019s fine; empty sections are allowed and do no harm.
What if you used a wrong value in your config, made a typo, or misremembered the name of a setting? How would you know about it? Having to triple-check every single character of the config when something goes wrong is not a good prospect\u2026 Fortunately, you don\u2019t have to do that because DOSBox can inform you if something went wrong. It does that via the logs, which is just a continuous stream of timestamped messages in a separate window.
The behaviour of the log window is different on each platform:
WindowsThe log window is opened by default when you start DOSBox Staging . You can hide the log window by passing the -noconsole argument to the DOSBox Staging executable.
DOSBox Staging does not open the log window by default when started via its application icon, or with the Start DOSBox Staging icon you copied from the .dmg installer archive earlier.
To make the log window appear, you need to use another shortcut icon called Start DOSBox Staging (logging), which you can copy into your game folder from the same .dmg archive (note the word \u201clogging\u201d in the name of the icon).
Start DOSBox Staging from the terminal, and the logs will appear there.
Under normal circumstances, the logs contain lots of interesting technical details about what DOSBox Staging is currently doing, what exact settings it uses, and so on. For example, this is the start of the logs when running the game on macOS:
That\u2019s all good and well, but what\u2019s even better, if an invalid configuration setting has been detected, or something went wrong when running the game, DOSBox Staging will inform us about it in the logs!
Let\u2019s now intentionally screw a few things up in the config to trigger some errors:
machine to mcp[sdl] section: no_such_config_param = 42fullscreen to blahx in front of the shader\u2019s nameThis is how the freshly ruined parts of our config should look like:
[sdl]\nfullscreen = blah\nno_such_config_param = 42\n[dosbox]\nmachine = mcp\n[render]\nglshader = xcrt/aperture\nAs expected, we\u2019ll see some warnings and errors in the logs after a restart:
Warnings are yellow, errors are red. Errors are generally reserved for more severe problems. In this example, we have the following:
The first warning tells us that blah is not a valid value for the fullscreen setting, so DOSBox has reset it to its default value of false.
Then it reprimands us about no_such_config_param that we made up.
The third warning complains about an invalid machine value being used (sorry to disappoint, but DOSBox Staging can\u2019t emulate the Master Control Program from Tron yet!)
Then we have an error because we\u2019re trying to use a non-existing shader.
This is followed by yet another rather large warning block that very helpfully lists the names of all available shaders on our system. That\u2019s pretty handy!
This is a common theme with the logs. When DOSBox Staging displays some warnings or errors, these messages often include suggestions and tips to help you resolve the issues. Note that these can appear not only at startup but also during running a game, depending on what DOSBox Staging is currently doing.
While you might prefer to hide the log window for aesthetic reasons, it\u2019s wiser to just let it be so you can take a peek at it if something goes sideways. Without having access to the logs, your chances of fixing problems are significantly reduced as basically you would be just stumbling in the dark. You\u2019ve been warned!
Okay, we\u2019ve pretty much maxed out Prince of Persia for demonstration purposes. Time to move on to another game!
"},{"location":"getting-started/introduction/","title":"Introduction","text":""},{"location":"getting-started/introduction/#foreword","title":"Foreword","text":"Welcome to the DOSBox Staging getting started guide!
This guide will gently introduce you to the wonderful world of DOSBox by setting up a few example games from scratch. It\u2019s written in the spirit of \u201cteaching a man how to fish\u201d\u2014the games are only vehicles to teach you the basics that you can apply to any DOS game you wish to play later. Consequently, the choice of games doesn\u2019t matter that much (although we tried to pick from the all-time classics).
To get the most out of this guide, don\u2019t just read the instructions but perform all the steps yourself! Later chapters build on concepts introduced in previous ones, so do not skip a chapter just because you\u2019re not interested in a particular game! You don\u2019t have to play it if you don\u2019t want to; going through the setup procedure and learning how to troubleshoot various issues is what this is all about. All necessary files will be provided and no familiarity with IBM PCs and the MS-DOS environment is required\u2014everything you need to know will be explained as we go. The only assumption is that you can perform basic everyday computer tasks, such as copying files, unpacking ZIP archives, and editing text files.
The guide has been written so that everyone can follow it with ease, regardless of their operating system of choice (e.g., Windows users probably know what the \u201cC drive\u201d is, and most Linux people are comfortable with using the command line, but these things need to be explained to the Mac folks).
We wish you a pleasant journey and we hope DOSBos Staging will bring you as much joy as we\u2019re having developing it!
"},{"location":"getting-started/introduction/#installing-dosbox-staging","title":"Installing DOSBox Staging","text":"If you already have other versions of DOSBox on your computer, installing DOSBox Staging won\u2019t interfere with them at all. Experienced users can certainly use multiple DOSBox variants on the same machine without problems, but if you\u2019re a beginner, we recommend starting with a clean slate to avoid confusing yourself. Make sure you\u2019ve removed all other DOSBox versions from your machine first, then proceed with the DOSBox Staging installation steps.
WindowsDownload the latest installer from our Windows downloads page, then proceed with the installation. Just accept the default options, don\u2019t change anything.
Make sure to read the section about dealing with Microsoft Defender SmartScreen.
macOSDownload the latest universal binary from our macOS downloads page, then simply drag the DOSBox Staging icon into your Applications folder. Both Intel and M1 Macs are supported.
Don\u2019t delete the .dmg installer disk image just yet\u2014we\u2019ll need it later.
Make sure to read the section about dealing with Apple Gatekeeper.
LinuxPlease check out our Linux downloads page and use the option that best suits your situation and needs.
"},{"location":"getting-started/introduction/#other-stuff-well-need","title":"Other stuff we\u2019ll need","text":"As you follow along, you\u2019ll need to create and edit DOSBox configuration files which are plain text files. While Notepad on Windows or TextEdit on macOS could do the job, it\u2019s preferable to use a better text editor more suited to the task.
WindowsWindows users are recommended to install the free and open-source Notepad++ editor.
Accept the default installer options; this will give you a handy Open with Notepad++ right-click context menu entry in Windows Explorer.
macOSTextMate is a free and open-source text editor for macOS which is perfect for the job.
Tip
When editing DOSBox configuration files in TextMate, it\u2019s best to set syntax highlighting to the Properties file format as shown in the below screenshot (it\u2019s the combo-box to the left of the Tab Size combo-box in the footer).
LinuxWe\u2019re pretty sure Linux users don\u2019t need any help and have their favourite text editors already. And, of course, everyone knows vim is the best!
"},{"location":"getting-started/next-steps/","title":"Next steps","text":""},{"location":"getting-started/next-steps/#thats-all-folks","title":"That\u2019s all, folks!","text":"All good things must come to an end, and this guide is no different!
Congratulations\u2014now you should be able to use DOSBox fairly confidently at a basic level, and we\u2019ve actually touched on quite a few intermediate topics as well. Armed with the basics, now you have a much greater chance to figure things out on your own, and you\u2019ll be able to ask more specific, directed questions from the more experienced members of the community when seeking help.
So what\u2019s next? Try setting up a few more games yourself; peruse the various configuration options in the default configuration; look around on our wiki; familiarise yourself with our feature highlights; read the release notes on our downloads page\u2014there are plenty of learning opportunities if you wish to delve deeper!
If you\u2019re stuck with something, you can always ask questions from the DOSBox Staging team directly on Discord.
Most importantly, experiment, enjoy what classic PC gaming has to offer, and have fun!
"},{"location":"getting-started/next-steps/#further-reading","title":"Further reading","text":"As your interest in DOS gaming grows, you might be interested in learning more about the history of PC gaming and PC hardware in general. Below is a selection of the very best learning resources to get you started!
RetroGrade - The ultimate guide to pre-millennial PC hardwareAn excellent collection of articles that takes you through the most important milestones of early PC hardware history, starting from its humble beginnings in the early 1980s right until the year 2000, covering the DOS era in its entirety and then some more.
DOS DaysThis very comprehensive website contains a great deal of information about DOS-era PC hardware, useful tips on setting up DOS games, and articles and guides on a variety of DOS-related topics. It\u2019s a highly recommended resource, and you\u2019ll inevitably end up here anyway when researching anything DOS-related via your favourite search engine\u2026
Nerdly PleasuresWritten by The Great Hierophant, there\u2019s simply no better resource online that does such extremely thorough and comprehensive deep dives supplanted by original research on a number of interesting DOS gaming related topics.
PhilsComputerLabPhil\u2019s YouTube channel offers a dizzying amount of quality content on a variety of retro-PC related topics with a special focus on actual hardware. Checking out his DOS tutorials and MIDI and wavetable series is a good start, but you can pretty much pick any of his videos at random and I guarantee you\u2019ll learn something interesting. His aptly titled three-and-a-half-hour long (!) Roland MT-32, CM-32L, CM-64, CM-500 Ultimate Tutorial is a work of art\u2014probably there isn\u2019t anything more to say on the subject!
DOSBox game compatibility listIf you\u2019re having problems with a game, it\u2019s worth having a look at the game compatibility list on the old DOSBox website. Although some information there might be outdated (e.g., mentioning DOSBox issues that have long been fixed), some of the comments document important issues present in the original games. That\u2019s one very common trap to fall into, thinking that certain game bugs are caused by emulation and therefore must be fixable at the DOSBox level. Often they\u2019re bugs present in the original games, so you just need to live with them or work around them.
VOGONSAn acronym for Very Old Games On New Systems, this forum is an oasis for all retro-hardware and retro-gaming enthusiasts, mainly focusing on PC compatibles and DOSBox-related things. The combined knowledge of the community on all things DOS and retro-PC is next to none\u2014try asking any obscure question, and there\u2019s a good chance you\u2019ll get a very detailed (and correct!) answer within a few hours.
"},{"location":"getting-started/passport-to-adventure/","title":"Passport to Adventure","text":"Okay, so what we\u2019ll set up next is not a single game, but a collection called Passport to Adventure which contains playable demos of three classic LucasArts point-and-click adventure games: Indiana Jones and the Last Crusade, The Secret of Monkey Island, and Loom. These were the blockbusters of the adventure gaming genre back in the day, and they still offer countless hours of fun if you like puzzle-solving and well-written, intriguing storylines.
But before we begin, let\u2019s discuss something fundamental to DOSBox Staging!
"},{"location":"getting-started/passport-to-adventure/#default-configuration","title":"Default configuration","text":"Have you wondered how do you learn about all the available configuration settings? When you start DOSBox Staging for the very first time, it creates a so-called default configuration file in a standard location with the name dosbox-staging.conf. This file contains the full list of available settings with their default values, plus a short explanatory text for each.
For example, this is the description of the viewport_resolution setting:
Set the viewport size (drawable area) within the window/screen:\n fit: Fit the viewport to the available window/screen (default).\n <custom>: Limit the viewport within to a custom resolution or percentage\n of the desktop. Specified in WxH, N%, N.M%.\n Examples: 960x720 or 50%\nHere are the locations of dosbox-staging.conf on each platform:
C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox-staging.conf macOS ~/Library/Preferences/DOSBox/dosbox-staging.conf Linux ~/.config/dosbox/dosbox-staging.conf Showing the Library folder in Finder
The Library folder is hidden by default in the macOS Finder. To make it visible, go to your home folder in Finder, press Cmd+J to bring up the view options dialog, and then check Show Library Folder.
If you know the exact name of a configuration setting, you can display its explanatory text using the built-in config command. The invocation is config -h followed by a space and the setting\u2019s name. For example:
It is highly recommended to look up the descriptions of the various settings as you encounter them in this guide. That\u2019s a good way to get gradually acquainted with them and further your knowledge about the available options.
"},{"location":"getting-started/passport-to-adventure/#layered-configurations","title":"Layered configurations","text":"In our Prince of Persia example, we created a dosbox.conf configuration file in the game\u2019s folder, then started DOSBox Staging from that folder. In such a scenario, DOSBox loads the default configuration first, then applies the dosbox.conf configuration found in the folder it was started from (the game\u2019s folder), overriding certain default settings.
This layered configuration approach is very useful; you can apply broad, general settings in your default global configuration that will apply to all games, then fine-tune these defaults on a per-game basis via local dosbox.conf configurations in the individual game folders.
As DOSBox Staging comes with sensible defaults, you can keep these local configurations quite minimal, as we\u2019ve already seen. There\u2019s absolutely no need to specify every single setting in your local game-specific config\u2014that would make configurations very cumbersome to manage, plus it would be difficult to see what settings have been changed from their defaults for a particular game.
A word of advice
It\u2019s best not to change the default configuration while you\u2019re still a beginner. Even more experienced DOSBox users are generally better off changing the defaults very sparingly as those settings will affect all games. A few things that you might consider changing globally are perhaps always enabling fullscreen, auto-pausing, and certain audio-related settings (e.g., sample rate and buffer sizes). We\u2019ll examine these later.
"},{"location":"getting-started/passport-to-adventure/#installing-the-game","title":"Installing the game","text":"Ok, so let\u2019s create the subfolder for our second game then! Create another folder in DOS Games next to Prince of Persia and name it Passport to Adventure. Create the drives subfolder in it and the c subfolder in the drives folder.
Download the ZIP archive from the Passport of Adventure item at the Internet Archive, then extract its contents into the c subfolder.
Below is the folder structure you should end up with. As explained before, we\u2019ll create one subfolder within DOS Games for each game, then each game folder will contain its own local dosbox.conf configuration specific to that game, along with its own \u201cemulated C drive\u201d in the drives/c subfolder.
By poking around on the C drive a little bit with the dir command, we\u2019ll quickly realise we only have two executables: INSTALL.BAT and SAMPLER.EXE. But there\u2019s also a README.TXT, so let\u2019s check that one out first!
We can try displaying its contents with the type README.TXT command (remember, use tab-completion), but that\u2019s not too fruitful as the text is longer than a single screen, so the type command will effectively only display the last page. In such cases, we can \u201cpipe\u201d the output of the type command through the more command that will paginate the preceding command\u2019s output. This is done by executing the following:
type README.TXT | more\nThe | is called the \u201cpipe\u201d character\u2014how fitting! You can type it by pressing Shift+\\, which is located above the Enter key on the standard US keyboard.
But there\u2019s an easier way to accomplish the same thing: we can simply execute more README.TXT. You can think of the more command as a more advanced, paginating version of the type command.
Now we can press Enter to advance the text one line at a time, or Space to go to the next page. The command will exit once we\u2019ve reached the end of the file, or we can quit earlier with the Q key. Of course, you can always cheat and read such text files outside of DOSBox, but we wanted to teach you something useful about DOS here.
The file contains important instructions about installing and playing the game, including the list of available keyboard shortcuts, so read it carefully. As it turns out, we\u2019ll only need to run SAMPLER.EXE, so let\u2019s just do that!
If you\u2019re playing the game in windowed mode, you\u2019ll need to click on the DOSBox Staging window first to \u201ccapture\u201d the mouse so you can move the crosshair-shaped in-game cursor.
To \u201crelease\u201d the \u201ccaptured\u201d mouse cursor, middle-click on your mouse, or press the Ctrl+F10 shortcut (Cmd+F10 on macOS). The title bar of the DOSBox Staging window informs you about the current mouse capture state.
It\u2019s also possible to tell DOSBox Staging to start with the mouse captured (this might not work on all operating systems, though):
[mouse]\nmouse_capture = onstart\nThis is a really user-friendly program; you can press F1 at the main screen to read the general instructions, then start a game demo by clicking on one of the three game icons on the left. Pressing F1 during the game displays further game-specific help; make sure you read them if you actually want to play these demos. They\u2019re worth playing even if you intend to play the full games later, as the demos contain slightly different scenes, puzzles, and dialogs, plus some fun easter-eggs.
For people who really don\u2019t like to read: F5 brings up the save/load/quit dialog, and you can pause/unpause the game with the Space key.
Let\u2019s start with the first demo called \u201cIndy\u201d (Indiana Jones and the Last Crusade), mainly because it plays a nice long version of the famous Indiana Jones theme during the intro, and we\u2019re going to investigate the various sound options next!
Indiana Jones and the Last Crusade \u2014 Title screen
Indiana Jones and the Last Crusade \u2014 Opening scene
"},{"location":"getting-started/passport-to-adventure/#sound-options","title":"Sound options","text":""},{"location":"getting-started/passport-to-adventure/#sound-blaster-adlib-sound","title":"Sound Blaster / AdLib sound","text":"The game managed to auto-detect our emulated Sound Blaster card, so what we\u2019re hearing during the intro is AdLib music.
\u201cWhoa, let me stop you right there, dude! You said Sound Blaster, so what\u2019s this AdLib thing now?!\u201d
Okay, we\u2019ll need to understand a few technical details again. Most Sound Blaster cards support at least two sound generation mechanisms:
Playing digitised sounds (sounds recorded from real-world sources, such as speech, sound effects, and sometimes even recorded music). This is referred to as digital audio, digitised sound, sampled audio, PCM audio, or just voice or speech in the game manuals and setup utilities (yes, it\u2019s all over the place; I\u2019m sure there are a dozen more variations out there\u2026)
Playing music and sound effects using a built-in synthesiser. This is usually called AdLib, OPL synthesiser, FM synthesiser, simply just music, or somewhat confusingly Sound Blaster MIDI.
Storing music as a list of instructions for a synthesiser takes very little disk space (think of sheet music), whereas storing digital audio eats disk space for breakfast (think of uncompressed audio files). Consequently, the vast majority of DOS games use some kind of synthesiser for music, and digital audio is generally reserved for sound effects and speech only.
These game demos don\u2019t have any digital sound effects; they all just use the OPL chip of the Sound Blaster for both music and some limited sound effects. The game is clever enough to auto-detect our OPL-equipped Sound Blaster 16 (the default sound card emulated by DOSBox), so we\u2019ll get OPL sound by simply just starting SAMPLER.EXE.
Of course, we can enhance the OPL music by adding reverb and chorus effects to it, just as we\u2019ve done with Prince of Persia. Unless you\u2019re an absolute purist, this is generally a good idea, especially when using headphones. We\u2019ll only need to add a few lines to our config:
[mixer]\nreverb = medium\nchorus = normal\nNote
Prince of Persia can also auto-detect our Sound Blaster 16, but most games are not this clever. As we\u2019ll see in our later game examples, usually we need to manually configure the audio devices using the game\u2019s setup utility.
1-minute Sound Blaster OPL synthesiser crash course
In case you\u2019re wondering:
OPL is just the name of the Yamaha OPL sound synthesiser chip present on most Sound Blaster cards.
AdLib was an early sound card predating Sound Blasters that featured the same OPL chip. Perfect AdLib compatibility was one of the Sound Blasters\u2019 main selling points, therefore in games that support both AdLib and Sound Blaster for synthesised sound, both options will usually yield the exact same results.
The AdLib card, however, had no support for digital audio, so it\u2019s preferable to pick the Sound Blaster option if the game offers both\u2014 you might also get digital speech and sound effects that way.
Sound Blaster MIDI is a weird thing. Most later games after 1992 supported much higher quality MIDI sound modules that used sampled recordings of real-world instruments. Many of these also provided a fallback option to play the same MIDI music via the OPL chip, using synthesised approximations of the same instruments.
FM refers to the type of sound synthesis the OPL chip is doing, which is Frequency Modulation synthesis (or FM synthesis, in short).
The observant among you might have spotted the list of graphics and sound configuration options in README.TXT. Playing with the graphics options is an exercise for the reader; it should be easy to apply what we\u2019ve learned during setting up Prince of Persia.
The sound settings, however, are quite interesting. We can get the executable to print out the list of available options by passing it some invalid argument; SAMPLER /? seems to do the trick:
C:\\>SAMPLER.EXE /?\n Interpreter Verson 4.0.62\nUnknown flag: '/?'\n\nOptions:\n h Hercules(tm) graphics\n c CGA graphics\n t Tandy(tm) graphics\n m MCGA graphics\n e EGA graphics\n v VGA graphics\n k Keyboard\n j Joystick\n mo Mouse\n i Internal speaker\n ts Tandy(tm) sounds\n g Game Blaster(tm) sounds\n a Adlib(tm) sounds\n d Two disk drives\n\nFor example, in order to play with EGA Graphics and a mouse,\ntype: SAMPLER e mo\nOkey-dokey, let\u2019s try the \u201cinternal speaker\u201d option by starting the game with the i command-line argument:
C:\\>SAMPLER.EXE i\nWell, it does sound a lot worse, doesn\u2019t it?
DOSBox emulates the little internal speaker (also known as PC speaker) that was a standard accessory of all PCs for a long time. It was designed to only produce rather primitive bleeps and bloops, but certain games can make it play digitised sound by employing some cunning tricks. In any case, this a bleepy-bloopy type of game\u2026
It\u2019s hard to envision anyone willingly subject themselves to the internal speaker experience when a game supports much better quality sound (even nostalgia can\u2019t be that strong!) But in most games released before about 1988, that\u2019s the only sound option you have.
For such early games, we can make the PC speaker a little more pleasant to listen to by enabling the special tiny reverb preset. This has been specifically designed for small-speaker audio systems; it simulates the sound of a small integrated speaker in a domestic room. The improvement is particularly noticeable with headphones.
[mixer]\nreverb = tiny\nAnother option is the \u201cTandy(tm) sounds\u201d you can select with the ts command-line argument. Let\u2019s try it!
C:\\>SAMPLER.EXE ts\nAaaaand, now there\u2019s no sound at all. Why is that?
Tandy Corporation was an IBM PC clone manufacturer in the 80s; they produced the Tandy line of home computers that were mostly compatible with the standard PCs but also offered improved sound and graphics capabilities. Developers had to specifically support the Tandy to take advantage of these features. There are relatively few such games, but they are worth seeking out as they provide a better experience, especially in the sound department. The games with Tandy & PCjr exclusive graphics and sound list on our wiki should help you find these pre-1990 Tandy specials.
DOSBox can emulate a Tandy machine; we only need to instruct it to do so in our config:
[dosbox]\nmachine = tandy\nEmulating the Tandy will cause the standard DOS font to be a bit different; this is normal, don\u2019t be alarmed by it.
After a restart, we\u2019re finally hearing different synthesised music which sounds definitely better than the PC speaker rendition, but not as good as the OPL music. Interestingly, the Tandy music plays a little bit faster than the other options.
Note
If you started SAMPLER.EXE without providing the ts argument to specifically ask for Tandy sound, the game will auto-detect the Sound Blaster\u2019s OPL synthesiser and prefer it over the Tandy sound. That\u2019s understandable; the game is really good at picking the best available sound device!
As an exercise, you can disable the Sound Blaster emulation altogether with the below config snippet. Then you can start SAMPLER.EXE without any arguments, and the game will use Tandy sound as that\u2019s the best available option (the PC speaker would be the only other alternative):
[sblaster]\nsbtype = none\nThe demos also support the Game Blaster, which is one of the earliest PC sound cards developed by Creative Technologies, the folks responsible for the Sound Blaster family of cards. The Game Blaster was also sold under the name Creative Music System, or just CMS for short.
To enable it, we\u2019ll need to set the emulated Sound Blaster type (sbtype) to Game Blaster (gb), and the game will auto-detect it correctly. As the Game Blaster is the precursor of the Sound Blaster lineup, it kind of makes sense to lump it into the same category under the sbtype setting.
[sblaster]\nsbtype = gb\nThe Game Blaster has a different-sounding synthesiser. Apart from its nice pure sound, another of its characteristics is that the voices play either completely on the left or on the right channel, making the music somewhat difficult to listen to through headphones. This can be easily remedied by enabling the crossfeed option which mixes a certain percentage of the left channel into the right, and vice versa:
[mixer]\ncrossfeed = on\nNaturally, you can combine crossfeed with chorus and reverb, and you can also specify a custom crossfeed amount if you\u2019re not happy with the default value of 40%:
crossfeed = 50\nTry it with headphones; the improvement is very noticeable!
"},{"location":"getting-started/passport-to-adventure/#true-ega-emulation","title":"\u201cTrue EGA\u201d emulation","text":"Many classic graphic adventure games, including most of the early Sierra and LucasArts catalogue and this collection of game demos, feature EGA graphics. The most commonly used EGA screen mode in games is 320\u00d7200 with a fixed 16-colour palette.
EGA monitors had visible \u201cfat\u201d scanlines and the pixels were a bit round, whereas later VGA monitors displayed EGA graphics without strong scanlines, and the pixels appeared as little sharp rectangles. It\u2019s as if EGA monitors had a \u201cbuilt-in filter\u201d that smoothed the image somewhat while adding a subtle texture to it as well, making it more interesting and pleasant to look at. Later VGA cards and monitors \u201cdropped\u201d this filter and were just displaying the \u201craw pixels\u201d without any such effects. This perceptual difference is because of the line-doubling peculiarity of VGA adapters in all low-resolution screen modes, as explained previously.
VGA-style line-doubling changes the feel of EGA graphics, and many prefer the original EGA look. After all, this is what the artists saw on their screens when creating the artwork. Fortunately, as we\u2019ve seen in our Prince of Persia example, you can easily emulate the \u201ctrue EGA\u201d look with shaders if that\u2019s your preference.
It\u2019s also worth restricting the image size to mimic that of a period-correct 14\u201d or 15\u201d monitor (see the detailed explanation here).
[render]\nglshader = crt/aperture\n[sdl]\nviewport_resolution = 1120x840\nIndiana Jones and the Last Crusade \u2014EGA (as displayed by VGA monitors)
Indiana Jones and the Last Crusade \u2014\u201cTrue EGA\u201d emulation
The Secret of Monkey Island \u2014EGA (as displayed by VGA monitors)
The Secret of Monkey Island \u2014\u201cTrue EGA\u201d emulation
Loom \u2014 EGA (as displayed by VGA monitors)
Loom \u2014 \u201cTrue EGA\u201d emulation
On recolouring the classics
Some adventure games that originally supported EGA graphics only also got later VGA remakes. While many of these VGA versions are competent, they rarely reach the artistic genius of the EGA originals, plus often they don\u2019t have the exact same gameplay either. This is especially true for the three classic LucasArts games included in this demo collection. You can check out the comparison and analysis of the EGA versus VGA versions of Indiana Jones and the Last Crusade and Loom here.
In another article, Brian Moriatry, the creator of Loom, shares his opinion about the VGA remake of the game (he calls it \u201can abomination\u201d, so apparently he\u2019s quite unimpressed\u2026)
In any case, the point here is it would be a mistake to outright dismiss the original EGA experiences, thinking they are \u201cinferior\u201d somehow. Even if you might prefer the VGA remakes in the end, you should at least give the EGA originals a chance.
"},{"location":"getting-started/passport-to-adventure/#cpu-sensitive-games","title":"CPU sensitive games","text":"Certain older games, such as these three demos, are sensitive to CPU speed. This can manifest in different ways:
The game may run too fast or may generally act weird if the emulated CPU is too fast (the more common case).
The game may fail the sound card detection and won\u2019t even start up (that\u2019s rarer).
This game falls into the second category. Note we\u2019re talking about the speed of the emulated CPU here, not the speed of the physical CPU in your computer!
DOSBox defaults to emulating 3000 CPU instructions, or cycles, per millisecond. For the more technically inclined among you, this corresponds to ~3 MIPS (Million Instructions Per Second). When running in windowed mode, the text in the title bar informs you about the current cycles value, e.g.:
DOSBOX - 3000 cycles/ms\nLet\u2019s see what happens if we double the emulated CPU speed!
[cpu]\ncycles = 6000\nNow we\u2019re greeted by an error when trying to start the game:
run-time error R6003\n- integer divide by 0\n\nC:\\>\nWe will discuss the CPU speed settings in more detail in the next chapter, but it was worth mentioning this interesting quirk here.
"},{"location":"getting-started/passport-to-adventure/#final-configuration","title":"Final configuration","text":"Here\u2019s the full config with all variations included as comments:
[sdl]\nfullscreen = on\n[dosbox]\n# uncomment for Tandy sound\n#machine = tandy\n[sdl]\nviewport_resolution = 1120x840\n[mouse]\nmouse_capture = onstart\n[render]\nglshader = crt/aperture\n[sblaster]\n# uncomment for Game Blaster audio\n#sbtype = gb\n[mixer]\n# change 'reverb' to 'tiny' for the PC speaker\nreverb = medium\nchorus = normal\ncrossfeed = on\n[autoexec]\nc:\n# use for PC speaker sound\n#sampler i\n# use for Tandy sound\n#sampler ts\nsampler\nexit\nWe will set up the demo version of Prince of Persia, the classic cinematic platformer from 1990 as our first example. It was a landmark game, and it can still provide countless hours of entertainment if you like platformers that require you to exercise that pesky grey matter a bit too.
First of all, we\u2019ll create a new folder for storing all our DOS games. We\u2019ll use DOS Games throughout this guide, but you can pick any name you like. It\u2019s best to create this folder in your regular documents folder so DOSBox Staging has full read and write access to it (don\u2019t put it in a system folder, e.g., Program Files on Windows). Each game will have its dedicated subfolder under DOS Games, so let\u2019s create our first one called Prince of Persia.
Now download pop1.zip from the Prince of Persia demo page and extract its contents into DOS Games/Prince of Persia. The archive contains only two files: pop1.txt (a regular text file) and pop1demo.exe (an MS-DOS executable). Let\u2019s open pop1.txt in our text editor!
It's like an Arabian Nights movie come to life... with you as the star!\nLeap into an exotic labyrinth of heart-stopping action, challenging mazes,\nintrigue and superb animation that's breathtakingly realistic!\n\nThis is a demonstration version which only has limited functionality. To\nobtain the full program, just access GO BB, and order it from our store.\nI\u2019m not quite sold on the \u201cheart-stopping\u201d part, but otherwise sounds intriguing! As indicated by the second paragraph, this is a fully playable demo version that includes only the first two levels of the game. That\u2019s more than enough for our purposes here, and you can always get the full game later.
But there are no further instructions, so what should we do next? Well, setting up old DOS games is not all that dissimilar to solving adventure game puzzles. Getting past these puzzles requires some logical thinking, a little bit of background knowledge, and an element of trial and error is occasionally involved as well. Well, the user manual often helps too if you happen to own the original, or can procure a scanned copy online (most often you can).
Luckily, this is an easy one: executable files (programs or scripts you can start) under MS-DOS have the .EXE, .COM or .BAT file extension, so looking at pop1demo.exe the solution is quite obvious: we\u2019ll need to run this executable file in DOSBox!
Most DOS games need a hard drive as a hard requirement (okay, I\u2019ll show myself to the door\u2026), but DOSBox doesn\u2019t have access to your computer\u2019s hard drive by default where your programs and documents reside\u2014we need to tell it which folder to use as its \u201cvirtual DOS hard drive\u201d. This is called mounting; we mount a folder as the \u201cDOS hard drive\u201d, the contents of which are then available to DOSBox as the C drive. All drives in DOS are assigned to the letters of the English alphabet (just like in Windows) and the C drive is usually your first hard drive.
The recommended way to mount the C drive is to create a drives subfolder inside your game folder. This drives folder is a \u201cmagic\u201d folder with a special purpose: all its subfolders having single-letter names are automatically mounted as DOS drives with the same letter. In our case, we only need a single C drive, so we\u2019ll create a c subfolder inside our drives folder (technically, it does not make a difference if you use uppercase or lowercase C on Windows and macOS; Linux people should use lowercase c). We\u2019ll then copy the files from the pop1.zip archive into drives/c to end up with the following folder structure:
Origins of the C drive
Have you ever wondered where the \u201cC drive\u201d in Windows got its name from? This is something Windows inherited from its MS-DOS heritage (which in turn inherited it from CP/M). In DOS, all drives are assigned letters from A to Z. Most computers of the era had two floppy drives, so letters A and B were reserved for them or other removable media, and the first hard drive partition was usually assigned to the letter C. We no longer have floppy drives in our computers as standard equipment, but this tradition stuck around for backwards-compatibility reasons.
Important
If you\u2019re a Windows user, do not confuse your real C drive where your operating system and programs are stored with the \u201cvirtual DOS C drive\u201d of DOSBox. It is important to understand the distinction between these two as they are completely separate concepts\u2014DOSBox will not see the contents of your real C drive by default (or the contents of any of your other drives, for that matter).
"},{"location":"getting-started/prince-of-persia/#starting-dosbox-staging","title":"Starting DOSBox Staging","text":"Okay, with our C drive set up and ready to go, the next step is to start DOSBox Staging from our DOS Games/Prince of Persia folder. This is accomplished slightly differently on each platform:
Warning
After installing DOSBox Staging, it\u2019s highly recommended to open it once using the Start Menu shortcut of the desktop icon as described here, otherwise the below instructions might not work.
If you have used the installer with the default options to set up DOSBox Staging (and it\u2019s highly recommended to do so while you\u2019re still learning the ropes), simply right-click on the Prince of Persia folder in Windows Explorer and select the Open with DOSBox Staging in the context menu.
Alternatively, you can enter the folder, right-click anywhere on the blank area inside it, then select Open with DOSBox Staging in the context menu.
macOSWarning
After installing DOSBox Staging, you must open it first using its application icon as described here, otherwise the below instructions won\u2019t work.
.dmg image file.Prince of Persia folder.You only need to perform this procedure once when opening the Start DOSBox Staging icon for the first time. After the first launch, you can use it like any other regular icon.
Tip
To avoid having to repeat these steps whenever you set up a new game, copy an icon on which you have already performed this initial procedure into your new game folder, rather than copying the original one from the .dmg file.
Open your favourite terminal, cd into the Prince of Persia directory, then run the dosbox command from there.
Make sure to check with the --version argument that you\u2019re running DOSBox Staging and not some other DOSBox variant:
% dosbox --version\ndosbox-staging, version 0.81.0\n\nCopyright (C) 2020-2022 The DOSBox Staging Team\nLicense: GNU GPL-2.0-or-later <https://www.gnu.org/licenses/gpl-2.0.html>\nAlternatively, create a shell script or a shortcut on your desktop that executes the following command:
dosbox --working-dir <PATH>\n<PATH> is the absolute path of your game directory (Prince of Persia in this case).
You\u2019ll be greeted by the following window when starting DOSBox Staging:
Let\u2019s ignore the polite welcome message for now and focus on the text below the big blue rectangle:
Local directory drives/c/ mounted as C drive\nZ:\\>_\nThe first line is pretty straightforward\u2014it tells us that DOSBox mounted drives/c we created earlier as the \u201cC drive\u201d.
The second line is the DOS prompt. DOS has a command line interface that predates graphical user interfaces we\u2019re accustomed to from modern operating systems. We get DOS to do things by typing in commands, and if manage to do this correctly, DOS will follow our instructions to the letter (pun intended!) DOS is not a multitasking operating system; you can only do a single thing in it at any given point in time.
Let\u2019s analyse the prompt a little bit. It always starts with a letter followed by a semicolon which denotes the current drive. Right after startup, this is always the Z drive. This is a special drive that\u2019s always available; DOSBox stores some of its commands on it\u2014you don\u2019t need to worry about it now.
After the semicolon is the path of the current folder or current directory in DOS terminology. This is currently the root directory of the Z drive as indicated by the \\ (backslash) character. The > character just signifies the end of the prompt, and the blinking underscore (_) character after it is\u2014guess what?\u2014the cursor.
Okay, enough theory, type in C: and then press Enter to switch to the C drive. The prompt should now reflect that we\u2019re in the root directory of the C drive:
Z:\\>c:\nC:\\>_\nType in dir and press Enter to list the contents of the current directory:
C:\\>dir\n Volume in drive C is CDRIVE\n Directory of C:\\\n\nPOP1 TXT 362 07/07/1995 10:12a\nPOP1DEMO EXE 267,420 07/05/1995 9:53a\n 2 file(s) 268,116 bytes\n 0 dir(s) 262,144,000 bytes free\nC:\\>_\nWell, that\u2019s what we put into our virtual C drive, so nothing too spectacular so far. We\u2019ll execute pop1demo.exe next! Type in pop and press the Tab key once to instruct DOSBox to complete the filename for you. This handy feature is called tab completion and it saves you from a lot of typing! Press Tab a few more times and observe how it alternates between POP1.TXT and POP1DEMO.EXE; this makes sense as these are the only two files in the current directory that start with pop.
Okay, let\u2019s make sure POP1DEMO.EXE is displayed in the prompt then press Enter to run this executable file. It turns out this is a self-extracting archive that unpacks its contents into the current directory when you run it. The following will appear (I\u2019ve redacted the list of extracted files):
C:\\>POP1DEMO.EXE\n\nPKSFX (R) FAST! Self Extract Utility Version 2.04g 02-01-93\nCopr. 1989-1993 PKWARE Inc. All Rights Reserved. Shareware version\nPKSFX Reg. U.S. Pat. and Tm. Off.\n\nSearching EXE: C:/POP1DEMO.EXE\n Inflating: CDUNGEON.DAT\n Inflating: DIGISND1.DAT\n\n ...\n\n Inflating: PRINCE.EXE\n\nC:\\>_\nThe more observant among you might have noticed the last entry, PRINCE.EXE. Bingo, that\u2019s our game executable! But let\u2019s pretend we haven\u2019t spotted it; how do we find all executables in the current directory? By issuing the dir command with the *.exe wildcard search pattern!
But instead of typing in dir *.exe, press Up a few times until dir appears in the command line, then type in the rest (Space character followed by *.exe). This handy feature is called command history\u2014you can move forward and backward in the list of previously executed commands with the Down and Up keys, respectively.
Okay, so here\u2019s how the output looks like:
C:\\>dir *.exe\n Volume in drive C is CDRIVE\n Directory of C:\\\n\nPOP1DEMO EXE 267,420 07/05/1995 9:53a\nPRINCE EXE 123,335 03/29/1990 0:00a\n 2 file(s) 390,755 bytes\n 0 dir(s) 262,144,000 bytes free\nC:\\>_\nTip
Alternatively, you can use the ls command that displays the directory contents in a wide list format. This command highlights executable files in green (.EXE, .COM, and .BAT file extensions) and directories (folders) in blue.
FAT filesystem
MS-DOS uses the FAT filesystem that allows up to 8-character filenames, followed optionally by a file extension consisting of a dot and at most three further characters. Filenames can only contain uppercase letters, digits, and certain special characters, such as the dash (-), underscore (_), and the exclamation mark (!).
The two files we originally copied to our drives/c folder had all lowercase filenames (pop1.txt and pop1demo.exe). This does not matter as DOSBox automatically converts all filenames in our drives/c folder to uppercase behind the scenes.
There\u2019s nothing else left to do than to start PRINCE.EXE (type in the letter p, press Tab to auto-complete it to PRINCE.EXE, then press Enter). After a short loading, the title screen will appear and you\u2019ll hear the classic Prince of Persia intro music playing! Don\u2019t press any key yet, just wait and watch the intro sequence until the end to learn about the game\u2019s backstory.
Prince of Persia \u2014 Title screen
Prince of Persia \u2014 Scene from the intro sequence
If you keep watching, the game will enter demo mode, where the protagonist will soon meet his untimely death\u2026 Surely, we can do better than that! Press any key to start the game!
You control the prince with the cursor keys, and you can walk carefully by holding the Shift key. It\u2019s not that hard to figure out the various movement combinations on your own, but reading the Controlling Your Movements section of the user manual should definitely help. The manual also contains helpful hints and a full list of keyboard shortcuts you can use during the game.
This is where the adventure starts!
Congratulations, you\u2019ve got your very first DOS game running in DOSBox Staging! Have some fun, try to find the sword and overcome a few guards, and maybe even attempt to complete the first level.
You can quit the game by pressing Ctrl+Q which will return you to the DOS prompt. There you can use the exit command to close DOSBox. Of course, you can quit DOSBox any time by pressing Alt+F4 on Windows and Linux, or Cmd+Q on macOS.
Note
The Ctrl+Q shortcut for quitting the game is specific to Prince of Persia. Other games might provide completely different mechanisms for exiting to DOS, or perhaps none at all.
How to approach old games
If you\u2019ve only ever played modern games, you\u2019re probably in for a bit of a culture shock! There\u2019s minimal to no handholding in most DOS games from the 1980s and the 90s; you are expected to read the user manual, often there is no in-game tutorial, and the games are generally unforgiving and require a level of dedication from the player that\u2019s uncommon in more modern titles.
However, this does not mean that these games are less fun, on the contrary! The old adage \u201cyou get out what you put in\u201d is certainly true for old DOS games. Many people (including the author of this present article) think that the satisfaction and enjoyment you get when mastering such difficult games have few parallels in the modern gaming landscape.
"},{"location":"getting-started/prince-of-persia/#auto-executing-commands-at-startup","title":"Auto-executing commands at startup","text":"Every time we want to play the game, we need to type in DOS commands to switch to the C drive and run PRINCE.EXE from there. Isn\u2019t there a way to automate this?
There certainly is! We need to create a so-called configuration file that can contain various settings to customise the behaviour of DOSBox, along with a list of commands to auto-execute at startup.
Launch your text editor of choice and create a new plain text file called dosbox.conf inside the Prince of Persia folder with the following content:
[autoexec]\nc:\nprince\nThe commands you want to be executed right after startup should be listed in the aptly titled [autoexec] configuration section, each command in a separate line. Configuration sections are introduced by names enclosed in square brackets; everything that follows belongs to that section.
Warning
Some text editors insist on appending the .txt extension after the filename you enter in their save dialog. This might result in creating a file called dosbox.conf.txt which won\u2019t work. Get to know your text editor and make sure you save the configuration file as dosbox.conf
When DOSBox starts, it looks for this special dosbox.conf file in the folder it was started from, and if it finds it, it configures the DOS environment and DOSBox itself according to its contents. This is handy because we can put a different configuration file into each of our game folders to set them up differently (this is necessary; it\u2019s simply impossible to create a single configuration that would work with all DOS games).
Just to make everything absolutely clear, this is the folder structure we should have at this point (only the first four files are shown in drives/c to save space):
Starting up DOSBox Staging from the Prince of Persia folder should now launch the game right away without any manual intervention!
So far so good\u2014now let\u2019s see how we can use the advanced features offered by DOSBox Staging to our advantage!
DOSBox vs DOSBox Staging
Astute readers might have noticed that the guide sometimes refers to \u201cDOSBox Staging\u201d and sometimes to just \u201cDOSBox\u201d. Why is that?
As explained on our about page, DOSBox Staging is a modern continuation of the original DOSBox project. Technically, DOSBox Staging is an open-source fork of and separate project from the SourceForge-hosted DOSBox project.
Generally, we use \u201cDOSBox Staging\u201d when we discuss features specific to Staging, or when we talk about the DOSBox Staging application, installer, or process itself. But when mentioning base functionality present in the original DOSBox and pretty much all other DOSBox variants, we simply write \u201cDOSBox\u201d. Admittedly, sometimes the distinction gets rather blurry, and seeing \u201cDOSBox Staging\u201d fully typed out everywhere would get old rather quickly!
Using the term \u201cDOSBox\u201d is also a nod to the original DOSBox developers to whom we are grateful for starting this awesome open-source project in the first place!
"}]} \ No newline at end of file diff --git a/preview/dev/sitemap.xml b/preview/dev/sitemap.xml index 2c13d361..1030f4dd 100644 --- a/preview/dev/sitemap.xml +++ b/preview/dev/sitemap.xml @@ -2,142 +2,142 @@