-DOSBox Staging 0.80.1 32-bit (Portable ZIP)
+
DOSBox Staging 0.80.1 32-bit (Portable ZIP) (Windows 8 or newer)
sha256: 63a8c5b084231364961f7c8b6415e44622c5ab9822e49839c2aca1bddd3a9459
diff --git a/preview/dev/search/search_index.json b/preview/dev/search/search_index.json
index fef856e..38be213 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 a (mostly) drop-in replacement for older DOSBox versions\u2014your existing configurations will continue to work, and you will have access to many advanced features.
DOSBox Staging comes with sensible defaults, so you\u2019ll need to write a lot less configuration than with older DOSBox versions. Most games and applications 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 delve deeper. Please refer to the Feature highlights on our front page to learn more about these.
The key features for developers are summarised here.
"},{"location":"about/#goals","title":"Goals","text":" - Faithfully emulate the DOS operating environment running on IBM PC compatibles and the IBM PCjr, with the primary goal of running all PC Booter, DOS and Windows 3.x games released in the 1981\u20132000 period. Running applications and demoscene productions or more recent DOS software is a secondary objective.
- Improve the out-of-the-box experience.
- Provide a self-contained emulator that requires no extra legacy or \u201cmodern retro\u201d hardware to function.
- Focus on supporting up-to-date, current operating systems and modern hardware.
- Implement new features and quality-of-life improvements.
- Deliver a consistent cross-platform experience.
- Leverage upstream and community developments in DOSBox.
- Encourage new contributors by removing barriers to entry.
- Prioritise code quality to minimise technical debt and ease maintenance. This generally means following the Staging Coding Style Guide and best practices such as the C++ Core Guidelines.
"},{"location":"about/#non-goals","title":"Non-goals","text":" -
Support old, end-of-life operating systems (e.g., Windows 7 or older, OS/2, Mac OS X 10.5 or older) and limited CPU/memory hardware, which are constraints the original DOSBox continues to support.
-
Support legacy or \u201cmodern retro\u201d hardware. DOSBox Staging is a self-contained emulator; its aim is to emulate all PC hardware it supports in software. Legacy and retro hardware are not supported (e.g., ISA boards, CRT monitors, RetroWave OPL3 and similar devices, etc.).
-
Support the use of Windows 9x/Me in the emulator. Windows 9x/Me emulation is supported by projects such as QEMU, VirtualBox and the DOSBox-X and DOSBox Pure forks.
-
Pursue hardware accuracy above all else. If you\u2019re after a more faithful emulation of an entire PC, look into MartyPC, PCem, 86Box, PCBox, QEMU or VirtualBox (although DOSBox Staging often matches or surpasses the graphics and especially audio emulation fidelity of these other 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.
"},{"location":"about/#relationship-to-the-original-dosbox-project","title":"Relationship to the original DOSBox project","text":"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":"about/#data-privacy-policy","title":"Data privacy policy","text":"DOSBox Staging never collects any personal information about you or your computer, and it never connects to the Internet or any network without you asking it to do so in the first place (e.g., by running BBS software or playing multiplayer DOS games over Ethernet).
"},{"location":"about/#disclaimer","title":"Disclaimer","text":"Free for personal use, but no warranties!
Although we do our best to emulate the DOS environment and legacy IBM PC hardware as accurately as we can, we cannot guarantee DOSBox Staging has zero bugs or can run every single DOS software ever written 100% correctly.
Under no circumstances should DOSBox Staging be used for professional applications, especially where DOS software malfunctioning due to emulation bugs or inaccuracies could result in significant financial loss, data loss, or putting living beings at risk.
Neither the members of the DOSBox Staging team nor our contributors can be held responsible for such unfortunate accidents resulting from the misuse of our software. DOSBox Staging is intended for personal use only in low-stakes scenarios, such as playing DOS games, watching demoscene productions, or researching the history of IBM PC compatibles and the DOS software catalogue.
If you disregard this and get into trouble, you\u2019re on your own!
IEEE 754 80-bit extended precision floating point emulation
One particularly risky area is engineering software that requires accurate 80-bit extended precision x87 FPU emulation to function correctly. Support for 80-bit floats is not available on all platforms that DOSBox Staging runs on. The logs will warn you about this at startup:
FPU: Using reduced-precision floating-point\n
Do note, however, that the lack of such log messages does not imply or guarantee bug-free operation!
"},{"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.
"},{"location":"get-involved/code-of-conduct/#reporting-issues","title":"Reporting issues","text":"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/","title":"Index","text":"Dummy page for redirecting links to to top-level sections
"},{"location":"getting-started/advanced-graphics-options/","title":"Advanced graphics options","text":""},{"location":"getting-started/advanced-graphics-options/#aspect-ratios-square-pixels-black-borders","title":"Aspect ratios, square pixels & black borders","text":"Okay, let\u2019s tackle the pressing question every second person wants an answer for: why doesn\u2019t the image fill the screen completely? And why are there black borders around it? (Well, that\u2019s two questions, but never mind.)
Computer monitors were originally not widescreen but had a 4:3 display 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 CRT screen. When displaying such 4:3 aspect ratio content on a 16:9 modern flat panel, you\u2019ll get black bars on the sides of the image. This is called pillarboxing.
Pillarboxing in action: black bars fill the extra spacewhen the aspect ratio of the screen and the image do not match
Hang on a second, something is not right here! 320:200 can be simplified to 16:10, which is quite close to 16:9, which means 320\u00d7200 resolution content should fill a 16:9 screen almost completely with only very minor pillarboxing! Sure, that would be true if the pixels of the 320\u00d7200 VGA mode were perfect little squares, but they are not. How so?
As mentioned, 320\u00d7200 graphics completely fill the screen on a 4:3 aspect ratio CRT\u2014but that\u2019s only possible if the pixels are not perfect squares, but slightly tall rectangles. With square pixels, you\u2019d get some letterboxing below the image (the horizontal version of pillarboxing) as shown in the below image. If you do the maths, it turns out the pixels need to be exactly 20% taller than wide.
Left: 320\u00d7200 pixel image with square pixels on a 4:3 monitor\u2014there is some letterboxing below the image; Right: the same image with 20% taller pixels on the same monitor\u2014the image fills the screen completely
Here\u2019s how to derive it: 4:3 can be rewritten as 320:240 if you multiply both the numerator and denominator by 80. Then 240 divided by 200 is 1.2, so the pixel aspect ratio is 1:1.2, which can be rewritten as 5:6. (Pixel aspect ratio, or PAR in short, is the mathematical ratio that describes how the width of a pixel compares to its height.)
But hey, not everybody likes maths, especially not in the middle of a gaming session! Most of the time, you won\u2019t need to worry about aspect ratio correctness because DOSBox Staging handles that automatically for you. There is a small but significant number of games though where forcing square pixels yields better results as we\u2019ve seen in our Beneath the Steel Sky example.
When 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 any old computer magazine from the 1980s and the \u201990s, most screenshots are shown in the correct aspect ratio (but 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 video modes with non-square pixels, e.g., the 640\u00d7350 EGA mode with 1:1.3714 PAR, the 640\u00d7200 EGA mode (1:2.4 PAR), and the 720\u00d7348 Hercules graphics mode (1:1.5517 PAR).
"},{"location":"getting-started/advanced-graphics-options/#integer-scaling","title":"Integer scaling","text":"That explains the black bars on the sides, but what about the letterboxing we sometimes see above and below the image? Why doesn\u2019t the graphics fill the screen vertically and why does it change size, depending on the DOS video mode?
Again, we need a little history lesson to understand what\u2019s going on. CRT monitors did not have a fixed pixel grid like modern flat panels; they were a lot more flexible and could display any resolution within the physical limits of the monitor. They did not even have discrete \u201cpixels\u201d in the sense that modern flat panels do\u2014the image was literally projected onto the screen, similarly to how a movie projector works.
Modern flat screens, however, do have a fixed native resolution. The scanlines of the emulated CRT image need to \u201cline up\u201d with this fixed pixel grid vertically, otherwise we might get interference artifacts. These usually manifest as wavy vertical patterns and look rather unpleasant. When DOSBox Staging enlarges the emulated image to fill the screen, by default it constrains the vertical scaling factor to integer values. This ensures perfect alignment with the native pixel grid of the display. The horizontal direction is rarely a problem, so non-integer horizontal scaling factors are generally fine.
Assuming a 4K monitor with 3840\u00d72160 native resolution, the 320\u00d7200 VGA mode double-scanned to 640\u00d7400 will be enlarged by a factor of 5 vertically. The horizontal scaling factor will be 5 \u00d7 4/3 = 6.6667 to maintain the correct 4:3 aspect ratio of the upscaled image. This results in a final output of 2667\u00d72000 pixels. Those 160 unused pixels in the vertical direction account for the slight letterboxing above and below the image.
Now, the higher your monitor resolution, the more you can get away with using non-integer vertical scaling ratios. It\u2019s just that enabling vertical integer scaling by default is the only surefire way to completely avoid ugly interference artifacts on everybody\u2019s monitors out-of-the-box. If you play games in fullscreen on a 4K screen, you can safely disable integer scaling without any adverse effects up to the 640\u00d7480 VGA resolution. Just put the following into your config:
[render]\ninteger_scaling = off\n
If you don\u2019t have a 4K monitor or you like to play your games in windowed mode, you\u2019ll need to experiment a bit\u2014some monitor resolution, window size, and DOS video mode combinations look fine without integer scaling, some will result in interference patterns.
"},{"location":"getting-started/advanced-graphics-options/#sharp-pixels","title":"Sharp pixels","text":"\u201cOkay, enough blabbering about all those near-extinct, mythical cathode-ray tube contraptions, grandpa. Can\u2019t you just give us sharp pixels and be done with it?\u201d
Sure thing, kiddo. Just put this into your config:
[render]\nglshader = sharp\n
By default, integer scaling is disabled when the sharp shader is selected, so if you want to re-enable it, you\u2019ll need to add another line:
[render]\nglshader = sharp\ninteger_scaling = vertical\n
This will yield 100% sharp pixels vertically, no matter what. Horizontally, there might be a 1-pixel-wide interpolation band at the sides of some pixels, depending on the DOS video mode and the upscale factor. This is the best possible compromise between maintaining the correct aspect ratio, even horizontal pixel widths, and good overall sharpness.
The resulting image has quite acceptable horizontal sharpness at 1080p, and from 1440p upwards, you\u2019ll be hard-pressed to notice the occasional 1-pixel interpolation band\u2026 unless you\u2019re literally pressing your nose against the monitor to give those pixels a deep inspection (well, how about not doing that then? )
"},{"location":"getting-started/advanced-graphics-options/#custom-viewport-resolution","title":"Custom viewport resolution","text":"That\u2019s very nice and all, but now the graphics look as if it was constructed from brightly coloured little bricks at fullscreen on a 24\u201d or larger modern display!
Well, 14\u201d VGA monitors were still the most affordable and thus most popular option until the mid-1990s, close to the end of the DOS era. Before that, CGA and EGA monitors were typically 12\u201d or 14\u201d, and monochrome Hercules monitors only 10\u201d or 12\u201d. And these are just the \u201cnominal\u201d diagonal screen sizes\u2014the actual visible area was about 1.5 to 2 inches smaller!
To emulate the physical image size you\u2019d get on a typical 14\u201d VGA monitor, you\u2019d need to restrict the output to about 960\u00d7720 on a modern 24\u201d widescreen display with a 16:9 aspect ratio (assuming the same normal viewing distance). You want the resulting image to measure about 12 inches (30 cm) diagonally for the most authentic results. But alas, that would be a tad too small for most people. 960\u00d7720 would result in a non-integer vertical scale factor, anyway, which is to be avoided. It\u2019s best to bump it up to 1067\u00d7800 then:
[render]\nviewport = 1067x800\n
The viewport size is specified in logical units (more on that below). You can also specify the viewport size restriction as a percentage of the size of your desktop:
[render]\nviewport = 89%\n
The video output will be sized to fit within the bounds of this rectangle while keeping the correct aspect ratio. If integer scaling is also enabled, the resulting image might become smaller than the specified viewport size.
Why 89% in this example? Because that\u2019s a magic number that will result in optimal image sizes for DOS resolutions between 320\u00d7200 and 640\u00d7480 on most common modern displays. With integer scaling enabled, 320\u00d7200 content will have the physical image size you\u2019d get on a 15\u201d CRT, and 640x480 what you\u2019d get on a big 19\u201d beast. These are reasonable upper maximums that can be considered \u201cbig screen mode\u201d for DOS-era standards, yielding the best overall compromise between \u201cmodern sensibilities\u201d and the authentic original experience. You go higher than this, the graphics will start looking overly blocky from a normal viewing distance.
No, DOS games did not look like Roman mosaics\u2026
Running DOS games in fullscreen on a modern 24\u201d widescreen display is equivalent to playing them on a 21\u201d CRT monitor! Those huge beasts were used by (and most importantly, priced for) professionals, so extremely few gamers and enthusiasts saw low-resolution art blown up to look like Roman mosaics back in the day. Even yours truly performed all the tricks in the book to shrink 320\u00d7200 DOS games as much as possible on his 19\u201d CRT in the early 2000s\u2026
Logical units vs pixels
Most operating systems operate in high DPI mode using a 200% scaling factor on 4K displays and use \u201cunscaled\u201d logical units for specifying window dimensions. The viewport setting adopts the same approach; the viewport size must be always specified in logical units.
For example, on a 4K display, a viewport resolution specified as 1280x960 logical units will translate to 2560\u00d71920 physical pixels (assuming a typical 200% scaling factor). Then on 1080p with a 100% scaling factor, it will simply translate to 1280\u00d7960 pixels.
The magic of 89% explained
This is hardcore mode\u2014only the brave and the mathematically inclined shall prevail! \ud83e\udd13 \ud83e\udde0 \ud83d\udcda
-
Assuming a 1920\u00d71080 desktop resolution, viewport = 89% will restrict the maximum viewport size to 1709\u00d7961 logical units.
-
The viewport size is a potential. With integer scaling disabled and aspect ratio correction enabled, for a 4:3 aspect ratio DOS image you\u2019d get a 1281\u00d7961 image in logical units (because 1281 / 961 \u2248 4/3).
-
This would result in 1281\u00d7961 pixels on 1080p monitors, then on 4K monitors with 200% DPI scaling, the resulting image would be 2562\u00d71922 pixels.
-
With integer scaling enabled and assuming a 320\u00d7200 VGA resolution double-scanned to 640\u00d7400, dividing 961 by 400 gives us 2.4025, so a 2x vertical integer scaling factor will be used. The resulting image will be 1067\u00d7800 on 1080p and 2133\u00d71600 on 4K. The image should measure about 14.4\u201d diagonally (about 35 cm) on your monitor, which is a little bit above the viewable size of a typical 15\u201d CRT.
-
For the 640\u00d7480 VGA mode, 961 / 480 \u2248 2.0021, so a 2x vertical integer scaling factor will be used again. The resulting image will be 1280\u00d7960 on 1080p and 2560\u00d71920 on 4K. The resulting image should measure about 17.3\u201d diagonally (about 42 cm) on your monitor, which is almost spot on the viewable size of a typical 19\u201d CRT.
Q.E.D.
"},{"location":"getting-started/advanced-graphics-options/#custom-aspect-ratios","title":"Custom aspect ratios","text":"Psssst\u2026 Don\u2019t tell anyone, but DOSBox Staging features a hidden \u201cscrew the developer\u2019s intent\u201d switch as well (also known as \u201cLOL what aspect ratio?\u201d mode). To unleash its formidable powers, put this casually into your config when no one\u2019s looking:
[render]\naspect = stretch\n
DOSBox Staging will now happily trample over any authentic aspect ratios and stretch the image to the full extents of the viewport. Keep resizing the window and see what happens. Whoopee! Now you can play Prince of Persia completely stretched to a widescreen monitor like a barbarian!
Jokes aside, this mode might come in handy when playing text adventures in fullscreen; it\u2019s hard to argue the correct aspect ratio matters much for those games. The same reasoning can also be applied to more abstract graphical games (although opinions on that are somewhat divisive\u2026)
You can also specify custom aspect ratios in the form of horizontal and vertical \u201cstretch factors\u201d. This emulates the horizontal and vertical stretch controls of CRT monitors. For example, we can correct the squashed look of the Hercules graphics in Prince of Persia with the following magic incantations:
[render]\naspect = stretch\nviewport = relative 112% 173%\n
Prince of Persia in Hercules mode with custom stretch factors to make the image fill our 4:3 \u201cemulated CRT screen\u201d
"},{"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 about launching our growing collection of games more easily. Having to navigate to the game\u2019s folder whenever we want to launch it gets old really fast. Here\u2019s how we can skip this step:
Windows -
Create a batch file called Start DOSBox Staging.bat with the following content:
C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox.exe\n
That\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.
-
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).
macOS 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.
Linux The easiest way is to create a shell script with the following content (of course, modify the path passed in with the --working-dir option so it points to your game directory):
#!/bin/bash\ndosbox --working-dir \"~/Documents/DOS Games/Prince of Persia\"\n
Then 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 then the usual drives/c subfolder within it. Download the ISO CD-ROM image from the Beneath a Steel Sky item at the Internet Archive 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 or Extras subfolder too for the scanned manuals and other extra files). 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\n
Warning
If you\u2019ve decided to keep 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\n
Tip
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 /? or help imgmount if you need a little reminder on how to use the command (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:\\>_\n
MSCDEX 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!
Always mount CD-ROM images with imgmount
While you could mount CD-ROM images outside of DOSBox with other programs too (e.g., Daemon Tools, ImgDrive, WinCDEmu, or the built-in Windows 10/11 ISO mounting feature), these alternative approaches often lead to compatibility problems. That\u2019s because these tools don\u2019t emulate the MSCDEX MS-DOS driver that DOS games expect.
For a trouble-free life, always just use the built-in imgmount command. There\u2019s nothing to be gained from using these 3rd party mounting tools for DOS games.
"},{"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\n
Okay, 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). 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\u2019ll need to select the installation path:
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 that by pressing Enter.
The installer will take us now to the setup screen where we can select the language of the in-game text (the voice-acting is English-only), and the sound 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 either. Reading the manual or some trial and error might help too.
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\n\nTo run the game type:\n\nC:\nCD \\SKY\nSKY\n
Alrighty, 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\n
"},{"location":"getting-started/beneath-a-steel-sky/#changing-the-current-directory","title":"Changing the current directory","text":"So 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\n
The 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:\\>_\n
How do you go straight to the root directory? By executing cd \\ (the \\ backslash character means \u201croot directory\u201d).
C:\\SKY>cd \\\nC:\\>_\n
You 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>_\n
Play around a bit with the drive and directory switching commands, then when you\u2019ve 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)!
"},{"location":"getting-started/beneath-a-steel-sky/#adjusting-volume-levels","title":"Adjusting volume levels","text":"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 at 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 why their channels appear in the mixer, and the CDAUDIO channel is added automatically whenever we mount a CD-ROM image (as it might 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\n
By 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\u2019re setting the OPL channel\u2019s volume to 50%, and the SB channel\u2019s to 500%:
mixer opl 50 sb 500\n
You can run mixer /? or help 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\n
"},{"location":"getting-started/beneath-a-steel-sky/#changing-the-emulated-sound-blaster-model","title":"Changing the emulated Sound Blaster model","text":"DOSBox 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 have 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\n
We 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:
[autoexec]\nimgmount D \"cd/cdrom1.iso\" -t iso\nc:\ncd sky\n#mixer opl 50 sb 500 /noshow\nsky\n
It 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.
"},{"location":"getting-started/beneath-a-steel-sky/#disabling-the-sound-blaster-mixer","title":"Disabling the Sound Blaster mixer","text":"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 card\u2019s internal 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\n
Well, that\u2019s another way of fixing the issue; the volume levels are now perfect!
When the game knows best
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, but no hard feelings), you must have heard 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\n
Remember 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% cycles/ms\n
SKY 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\n
Restart 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. These extenders also print out some fairly characteristic messages as they start up when launching the game, so they\u2019re easy to recognise.
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.
"},{"location":"getting-started/beneath-a-steel-sky/#finding-the-correct-speed-for-a-game","title":"Finding the correct speed for a game","text":"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\u2009000 Always 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 much\u2014you 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 card. They were the Cadillacs of DOS gaming audio for a while, they were priced accordingly, and they still sound excellent 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:
Windows C:\\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:
"},{"location":"getting-started/beneath-a-steel-sky/#selecting-the-mt-32-version","title":"Selecting the MT-32 version","text":"As you might have guessed already, you can tell DOSBox Staging to emulate an MT-32 model of a specific revision; you can read all 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. Some studios, such as LucasArts, tended to favour the CM-32L, so their games sound a little bit better on this module. mt32_old Most older games, most notably the entire early Sierra adventure catalogue, absolutely need a 1st generation MT-32; they will refuse to work correctly on any other model or at least sound incorrect. 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\n[mt32]\nmodel = cm32l\n
How 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.
"},{"location":"getting-started/beneath-a-steel-sky/#configuring-the-game-for-mt-32","title":"Configuring the game for MT-32","text":"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 or the ls command, 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 combined installer-and-setup utility into C:\\SKY as one would rightly expect. To reconfigure the game, you\u2019ll need to run INSTALL.EXE from the CD, so from the D drive (I\u2019ve told you\u2014setting up the game itself is often 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\u2014the computer says no, buddy.
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 enhance 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\n
"},{"location":"getting-started/beneath-a-steel-sky/#aspect-ratio-correction","title":"Aspect ratio correction","text":"We\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 (just trust me on that for a moment).
So where\u2019s this magical 20% vertical stretch factor coming from? DOSBox Staging enables aspect ratio correction by default to make 320\u00d7200 graphics appear exactly as it 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. One of the tell-tale signs is that the artwork in the intro was scanned using square pixels, and 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, or PAR). All this is explained in a lot more detail in the advanced graphics options chapter at the end.
Left: Screenshot from the intro with aspect ratio correction disabled (square pixels) Right: The original image from the comic book included with the game That\u2019s quite easy to do, and we\u2019re also setting the viewport resolution to 4x integer scaling, effectively, because the game would appear too blocky when fit to fullscreen:
[render]\naspect = off\nviewport = 1280x800\n
Beneath a Steel Sky with aspect ratio correction disabled
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 primarily developed for DOS. This is the DOSBox Staging default, and it ensures the overwhelming majority of DOS games appear correctly out of the box.
-
For games primarily developed for the Amiga or Atari ST by a North American studio for the NTSC standard. (Note that even if the work was performed by a European studio, but it was commissioned by North Americans, that usually means the game was primarily intended for the NTSC-only North American market, so you need aspect ratio correction.)
aspect = off
- For most games primarily developed by European studios for the Amiga or Atari ST.
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 1980s and \u201990s featuring 2D graphics, the art was created once for the \u201cleading platform\u201d 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\u2019ve 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). We\u2019ll get to the detailed mathematical derivation of the 1:1.2 PAR in the last chapter.
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 economically motivated compromise 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/#arcade-monitor-emulation","title":"Arcade monitor emulation","text":"Now that we brought up the Amiga, it\u2019s worthwhile mentioning a special feature of the CRT emulation which is not quite authentic, but still a lot of fun!
Home computer and arcade monitors (also known as 15 kHz monitors), such as the Commodore monitors typically used with Amiga computers, were quite different from VGA CRTs. They displayed low-resolution content with thick scanlines, similary to EGA monitors, and they were a lot less sharp. While this wasn\u2019t great for displaying text and spreadsheets, it made low-resolution pixel art appear in a more favourable light.
We can enable this special fantasy mode with the following setting:
[render]\nglshader = crt-auto-arcade\n
Now you can play the game with Amiga-like graphics and MT-32 or OPL sound from a strange parallel universe! \ud83d\ude0e
Beneath a Steel Sky from a parellel universe running on an Amiga in 256 colour mode
"},{"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\n[sdl]\nfullscreen = on\n\n[render]\naspect = off\nviewport = 1280x800\n\n# uncomment for arcade monitor emulation\n#glshader = crt-auto-arcade\n\n[sblaster]\nsbmixer = off\n\n[midi]\nmididevice = mt32\n\n[mt32]\nmodel = cm32l\n\n[mixer]\nreverb = large\nchorus = strong\n\n[autoexec]\nimgmount d \"cd/cdrom1.iso\" -t iso\nc:\ncd sky\nsky\nexit\n
With 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 and chorus, so DOSBox Staging is intelligent enough not to apply these effects twice on its output.
"},{"location":"getting-started/enhancing-prince-of-persia/","title":"Enhancing Prince of Persia","text":""},{"location":"getting-started/enhancing-prince-of-persia/#fullscreen-mode","title":"Fullscreen mode","text":"You 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 make DOSBox start in fullscreen right away?
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\n[autoexec]\nc:\nprince\nexit\n
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.
Note we\u2019ve also added the exit command to the end of the [autoexec] section; with this in place, DOSBox Staging will quit after we exit from the game by pressing Ctrl+Q. Not strictly necessary, but a nice touch.
Making configuration changes
Every time you modify dosbox.conf, you need to restart DOSBox Staging for the changes to take effect. We will not mention this every single time from now on.
You can do this by closing the DOSBox Staging application and then starting it again. But there is a better way: simply press Ctrl+Alt+Home! This is a homage to the Ctrl+Alt+Del \u201cthree-finger salute\u201d way of soft-rebooting IBM PCs.
If you\u2019re on macOS, you\u2019ll need to press Cmd+Option+Home instead, and if Apple has decided for you that your MacBook doesn\u2019t need a Home key, Cmd+Option+Fn+Left should do the trick.
"},{"location":"getting-started/enhancing-prince-of-persia/#graphics-options","title":"Graphics options","text":"DOSBox emulates an SVGA (Super VGA) display adapter by default; this 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 adapters among several 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 (we\u2019ll discuss how to do that too in later chapters).
"},{"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. This video mode allows up to 256 colours to be displayed simultaneously on the screen from a total palette of 16 million colours.
This is how the start of the game looks with the authentic CRT emulation feature which is enabled by default. As mentioned previously, make sure to view all screenshots at 100% magnification to avoid weird artifacts caused by the browser rescaling the image.
Prince of Persia in VGA mode with the default settings
But wait a minute, this doesn\u2019t look like anything I\u2019m used to from console emulators. Where are those visible thick scanlines?
VGA display adapters have a peculiarity in that they display not one but two scanlines per pixel in low-resolution video modes having less than about 350 lines of vertical resolution. This means the 320\u00d7200 VGA mode is really 640\u00d7400, just pixel and line-doubled. In fact, the vast majority of VGA monitors from the 1980s and \u201990s are incapable of displaying \u201ctrue\u201d 200-line graphics, so it\u2019s physically impossible to get the \u201cthick scanline\u201d arcade and home computer monitor look on a real VGA CRT.
Double-scanned VGA emulation looks stellar on a 4K monitor and even on 1440p, but on 1080p, there is simply not enough vertical resolution to accurately represent all those 400 tightly-packed scanlines. Therefore, the best thing the CRT emulation can do on 1080p and lower is to fake that double-scanned look so it looks approximately similar to the real thing.
Aspect ratio correction
Computer monitors were originally not widescreen but had a 4:3 display aspect ratio, just like old television sets. DOS games were normally designed to completely fill a 4:3 CRT screen. DOSBox Staging displays the emulated image in the correct aspect ratio by default, which means you\u2019ll see pillarboxing (vertical black bars) at the two sides in fullscreen on modern widescreen displays. This is normal.
However, there is also letterboxing (horizontal black bars) above and below the image. We\u2019ll explain why that\u2019s necessary in the last advanced graphics options chapter. Feel free to take a detour if you wish to gain an understanding of these details now.
Alternatively, if you\u2019re on a 4K (UHD, 3840x2160) or better screen, you can put this into your [render] section to get rid of pillarboxing altogether:
[render]\ninteger_scaling = off\n
"},{"location":"getting-started/enhancing-prince-of-persia/#ega","title":"EGA","text":"The next graphics adapter the game supports is the EGA adapter released in 1984. The EGA standard was quite popular until the early 1990s because VGA cards were initially prohibitively expensive for most hobbyists. The majority of 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\n
This is how the game looks with the fixed 16-colour EGA palette. Unlike VGA, EGA monitors can display true 320\u00d7200 resolution with the well-known thick scanline look.
Prince of Persia in EGA mode\u2014EGA monitors can display 200-line modes without line doubling, so we\u2019ll get the \u201cfat scanline\u201d look
"},{"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, only 4 colours can be displayed simultaneously on the screen chosen from a small number of fixed palettes. Frankly, all combinations look pretty horrifying\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 goggles!
[dosbox]\nmachine = cga\n
Ready? Behold the formidable 4-colour CGA graphics\u2014and what 4 colours those are! Similarly to EGA, CGA is capable of displaying true 200-line modes.
Prince of Persia in CGA mode. Yeah, it\u2019s not pretty\u2026
Tip
To compare how the game looks on different graphics adapters, click on one of the screenshots to enlarge it, then use the Left and Right arrow keys to switch between the images.
"},{"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\n
Here\u2019s how it looks. Oldschool! The 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 (but we\u2019ll examine some advanced techniques on how to fix that).
Prince of Persia in Hercules mode using the default amber palette
Monochrome monitors come in different colours and DOSBox Staging can emulate all these variations via the monochrome_palette setting. The available options are amber (the default), green, white, and paperwhite.
[render]\nmonochrome_palette = green\n
You can also cycle between these while the game is running with the F11 key.
Hercules mode using the green palette
Hercules mode using the white 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 not to play a DOS game with the best graphics. The list of possible reasons includes a) nostalgic feelings towards a particular display adapter; b) research purposes; c) you like your games to look like the user interface of an industrial CNC machine; d) a strong 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/#sharp-pixels","title":"Sharp pixels","text":"If you really prefer sharp pixels over authentic CRT emulation, you only need to add a single line to the [render] config section:
[render]\nglshader = sharp\n
That\u2019s it! Switching to the sharp shader will also make the image fill the screen vertically, so no more letterboxing. The reason for this (and a lot more) will be explained in the advanced graphics options chapter.
Keep in mind, though, that the rest of the guide assumes you\u2019re using the CRT emulation.
"},{"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\n
Now 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 too with the standard drivers.
"},{"location":"getting-started/enhancing-prince-of-persia/#joystick-support","title":"Joystick support","text":"Okay, so if we want to play the game with the keyboard, we need to press Ctrl+K to enter keyboard mode every single time we start the game. As mentioned, that\u2019s because by default DOSBox Staging either lets you use your gamepad as the joystick, or it emulates a PC joystick even if you don\u2019t have a physical game controller plugged in. Either way, the game will always \u201csee\u201d a joystick at startup and will therefore auto-switch to joystick mode.
From this follows that if we disable the joystick in the config, the game will have no other choice than to default to keyboard mode:
[joystick]\njoysticktype = disabled\n
But if you want to play the game with your gamepad instead, you can do that too! DOSBox Staging auto-maps most common game controllers, so you can control the game with the left analog stick and the X button out-of-the-box with most gamepads.
You\u2019ll need to hit diagonals often to jump and crouch. If your left stick can only move in a circle, the following setting might make this easier:
[joystick]\ncircularinput = on\n
You can also adjust the deadzone of your stick if you experience controller drift. It\u2019s 10% by default, so let\u2019s increase it to 15% instead:
[joystick]\ndeadzone = 15\n
The PC is not a console
Note that Prince of Persia requires a lot of precise control, so playing it with the analog stick makes the game quite a bit harder and somewhat frustrating. This is a common theme with many DOS games; most of them were really optimised for keyboard controls, or require you to use the keyboard anyway to perform some essential actions.
While playing DOS games from the couch with a controller in your hand might be cool, for the best results, just stick with the keyboard controls. Apart from some space and flight simulators, joystick support was often an afterthought in DOS games.
Issues with multiple controllers
You might get some weird behaviour or even crashes if you have multiple game controllers plugged in. If that\u2019s the case, please disconnect all game controllers except the one you want to use and restart DOSBox Staging. We\u2019re aiming to improve multi-controller support in the future.
"},{"location":"getting-started/enhancing-prince-of-persia/#pausing-the-game","title":"Pausing the game","text":"Prince of Persia can be paused by pressing the Esc key during the game. That\u2019s nice, but not all games have such built-in pause functionality.
Luckily, DOSBox has a pause feature that you can activate in any game with the Alt+Pause shortcut (Cmd+P on macOS), then unpause by pressing the same shortcut again.
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]\npause_when_inactive = yes\n
Restart the game and switch to a different window\u2014DOSBox will pause itself. Switch back to DOSBox\u2014the game will resume. Nifty, isn\u2019t it?
Pause gotchas
All input is disabled in the manually paused state\u2014the only thing you can do is press the pause shortcut again to unpause the emulator. In windowed mode, the paused state is indicated in the DOSBox Staging window\u2019s title bar.
"},{"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:
[sdl]\nfullscreen = on\npause_when_inactive = yes\n\n[mixer]\nreverb = large\nchorus = normal\n\n[autoexec]\nc:\nprince\nexit\n
"},{"location":"getting-started/enhancing-prince-of-persia/#configuration-comments","title":"Configuration comments","text":"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\npause_when_inactive = yes\n\n[joystick]\n# if you prefer the keyboard; remove it if you want to play with your gamepad\njoysticktype = disabled\n\n# optional gamepad adjustments\n#circularinput = on\n#deadzone = 15\n\n[render]\n# for 4K+ monitors only\n#integer_scaling = off\n\n[mixer]\nreverb = large\nchorus = normal\n\n[autoexec]\nc:\nprince\nexit\n
Note we haven\u2019t commented out the [render] section itself. That\u2019s fine; empty sections are allowed and do no harm.
"},{"location":"getting-started/enhancing-prince-of-persia/#inspecting-the-logs","title":"Inspecting the logs","text":"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 Staging can inform you if something goes wrong. It does that via the logs, which are just a continuous stream of timestamped messages in a separate window.
The behaviour of the log window is different on each platform:
Windows The 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.
macOS 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).
Note
Remember, for the first time you\u2019ll need to right-click or Ctrl-click on this icon, select the topmost Open menu item, then press the Open button in the appearing dialog. After the first start, you can simply double-click on it.
Linux 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 is 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:
- Set
machine to mcp - Include a bogus config setting in the
[sdl] section: no_such_config_param = 42 - Set
fullscreen to blah - Put the letter
x in front of the shader\u2019s name
This is how the freshly ruined parts of our config should look like:
[sdl]\nfullscreen = blah\nno_such_config_param = 42\n\n[dosbox]\nmachine = mcp\n\n[render]\nglshader = xsharp\n
As 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 Staging has reverted 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. Although it\u2019s primarily intended for newcomers unfamiliar with DOSBox and DOS emulation, it\u2019s a recommended read for people already comfortable with other DOSBox variants but not DOSBox Staging. And even if you\u2019re a long-time Staging user, we\u2019re quite certain you will learn a few new useful things and techniques from it.
The guide has been 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. For example. Windows users probably know what the \u201cC drive\u201d is, and most Linux people are comfortable using the command line, but these things need to be explained to the Mac folks.
We wish you a pleasant journey and we hope DOSBox 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":"You must use the latest stable version of DOSBox Staging for this guide. If you already have other versions of DOSBox on your computer, installing DOSBox Staging won\u2019t interfere with them at all. Experienced users can 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.
Windows Download the latest installer from our Windows releases 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.
macOS Download the latest universal binary from our macOS releases page, then simply drag the DOSBox Staging icon into your Applications folder. Both Intel and Apple silicon are supported.
Don\u2019t delete the .dmg installer disk image just yet\u2014we\u2019ll need it later.
Linux Please check out our Linux releases 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.
Windows We recommend Windows users 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.
macOS TextMate 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 status bar).
Linux We\u2019re pretty sure Linux users don\u2019t need any help and have their favourite text editors at hand already. And, of course, everybody knows vim is the best!
"},{"location":"getting-started/introduction/#a-note-for-existing-dosbox-staging-users","title":"A note for existing DOSBox Staging users","text":"If you already have DOSBox Staging installed on your computer, or if you have used it in the past but have uninstalled it, most likely you have a primary configuration file named dosbox-staging.conf somewhere on your drive (this is sometimes also referred to as the default or global configuration).
The guide assumes the default settings of the latest stable release, so it\u2019s highly recommended to remove any existing primary configuration files first (but make sure to back them up). If the primary config file does not exist in an platform-specific location, DOSBox Staging will create it on the first launch. If it exists, it will be used, but the defaults of some settings might have changed between releases, or you might have tweaked some settings yourself. These differences may render the instructions in the guide invalid as the default settings are assumed.
This is where the primary config is located per platform:
Windows C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox-staging.conf macOS ~/Library/Preferences/DOSBox/dosbox-staging.conf Linux ~/.config/dosbox/dosbox-staging.conf You can also execute DOSBox Staging with the --printconf option to have the location of the primary config printed to your console.
To back up your existing primary config, you can simply change the extension of dosbox-staging.conf from .conf to .bak. DOSBox Staging will write a brand new primary config containing the current defaults the next time you start it.
"},{"location":"getting-started/introduction/#portable-mode-notes","title":"Portable mode notes","text":"If you\u2019ve been using DOSBox Staging in portable mode, dosbox-staging.conf is located in the same folder as your DOSBox Staging executable. In that case, it\u2019s recommended to back up your existing primary config, and then create a new empty dosbox-staging.conf file in the executable folder. DOSBox Staging will write the new defaults to the empty dosbox-staging.conf file on the first launch.
"},{"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 Staging 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 primary configuration file; look around on our wiki; familiarise yourself with our feature highlights; read the release notes on our releases 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 community 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 hardware An 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 Days This 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 Pleasures Written 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.
PhilsComputerLab Phil\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 list If 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.
VOGONS An 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/#primary-configuration","title":"Primary 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 primary 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 and a short description for each.
For example, this is the start of the description of the viewport setting:
Set the viewport size (maximum drawable area). The video output is always\ncontained within the viewport while taking the configured aspect ratio into\naccount (see 'aspect'). Possible values:\n fit: Fit the viewport into the available window/screen (default).\n There might be padding (black areas) around the image with\n 'integer_scaling' enabled.\n WxH: Set a fixed viewport size in WxH format in logical units\n (e.g., 960x720). The specified size must not be larger than\n the desktop. If it's larger than the window size, it's\n scaled to fit within the window.\n ...\n
Here are the locations of dosbox-staging.conf on each platform:
Windows 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.
"},{"location":"getting-started/passport-to-adventure/#online-help","title":"Online help","text":"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 <setting_name>.
However, if the description is longer than what can fit into a single screen, this is not too fruitful as the config command will effectively only display the last page. In such cases, we can \u201cpipe\u201d the output of the config command through the more command that will paginate the preceding command\u2019s output. For example, this is how to display the description of the viewport setting which is rather long:
config -h viewport | more\n
The | 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.
This is how the output of the command looks like:
When piping the output through more, you can press Space to go to the next page, Enter to advance to the next line, or Q to quit the viewer, as the bottom line indicates. The viewer will also automatically quit once we\u2019ve reached the end of the output.
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 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 we started DOSBox Staging from that folder. In such a scenario, DOSBox loads the primary configuration first, then applies the local dosbox.conf configuration found in the folder it was started from (the game\u2019s folder). Because of this loading order, you can override any primary config setting in your local config.
This layered configuration approach is very useful; you can apply broad, general settings in your primary configuration that will apply to all games, then fine-tune these defaults on a per-game basis via local dosbox.conf configs in the individual game folders. Because of this, the primary configuration is sometimes also referred to as the default or global configuration.
As DOSBox Staging comes with sensible defaults, you can keep these local configs 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 very 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 primary configuration while you\u2019re still a beginner. Even more experienced DOSBox users are generally better off changing the primary configuration very sparingly as those settings will affect all games.
A few things that you might want to consider setting globally in the primary config include enabling fullscreen mode, turning on auto-pausing, integer scaling and shader defaults, and certain MIDI and audio-related settings (e.g., sample rate, buffer sizes, volume levels, etc.) 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.
"},{"location":"getting-started/passport-to-adventure/#examining-text-files","title":"Examining text files","text":"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 we\u2019ll only see the end of the file that way because it\u2019s longer than a single page. Good thing we\u2019ve just learned about the more command, so let\u2019s put it to good use by executing the following:
type README.TXT | more\n
Now we can read the whole file, starting from the beginning. 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.
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!
"},{"location":"getting-started/passport-to-adventure/#mouse-capture","title":"Mouse capture","text":"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\n
"},{"location":"getting-started/passport-to-adventure/#playing-the-game","title":"Playing the game","text":"This is a really user-friendly program; you can press F1 on 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 dialogues, 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 or even lossless 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 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\n
Note
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.
-
FM refers to the type of sound synthesis the OPL chip is doing, which is Frequency Modulation synthesis (or FM synthesis, in short).
-
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 result.
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 by doing so.
-
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.
All in all, the terms OPL, AdLib, and FM are used interchangeably in practice, and usually they refer to the exact same thing.
"},{"location":"getting-started/passport-to-adventure/#pc-speaker-sound","title":"PC speaker sound","text":"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 while 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\n
Okey-dokey, let\u2019s try the \u201cinternal speaker\u201d option by starting the game with the i command-line argument:
C:\\>SAMPLER.EXE i\n
Well, 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 coerce it to 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 subjecting 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\n
"},{"location":"getting-started/passport-to-adventure/#tandy-sound","title":"Tandy sound","text":"Another option is the \u201cTandy(tm) sounds\u201d you can select with the ts command-line argument. Let\u2019s try it!
C:\\>SAMPLER.EXE ts\n
Aaaaand, now there\u2019s no sound at all. Why is that?
Tandy Corporation was an IBM PC clone manufacturer in the 1980s; they produced the Tandy line of home computers that were mostly compatible with 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 enhanced Tandy & PCjr graphics and sound page on our wiki should help you find these pre-1990 Tandy specials.
DOSBox can emulate a Tandy machine\u2014we only need to instruct it to do so in our config:
[dosbox]\nmachine = tandy\n
Emulating the Tandy will cause the standard DOS font to be a bit different; this is normal, so 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 sound 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\n
"},{"location":"getting-started/passport-to-adventure/#game-blaster-cms-sound","title":"Game Blaster / CMS sound","text":"The 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\n
The 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\n
Naturally, you can combine crossfeed with chorus and reverb. You can also set crossfeed to light, normal, or strong according to your preference, or specify a custom crossfeed amount as a percentage from 0% (no crossfeed) to 100% (collapse the stereo image to mono):
crossfeed = 50\n
Try 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 offered backward compatibility with EGA graphics, although this was not full compatibility but a kind of emulation: 320\u00d7200 EGA graphics were simply line and pixel-doubled to 640\u00d7400.
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. Because of this, the authentic CRT emulation feature displays EGA graphics with the \u201ctrue EGA look\u201d out of the box with the glshader = crt-auto setting.
However, if you grew up with a VGA-equipped PC, then you only ever saw EGA games double-scanned. To appease such people, you can instruct DOSBox Staging to emulate a double-scanning VGA card in all screen modes with the crt-auto-machine setting:
[render]\nglshader = crt-auto-machine\n
Technically, this setting instructs DOSBox Staging to always emulate a CRT monitor appropriate for the configured machine type which is VGA by default.
The below screenshots illustrate the difference between the \u201ctrue EGA\u201d and \u201cEGA as displayed on VGA\u201d look:
Indiana Jones and the Last Crusade \u2014EGA as displayed on VGA monitors
Indiana Jones and the Last Crusade \u2014\u201cTrue EGA\u201d emulation
The Secret of Monkey Island \u2014EGA as displayed on VGA monitors
The Secret of Monkey Island \u2014\u201cTrue EGA\u201d emulation
Loom \u2014 EGA as displayed on 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/#authentic-image-size","title":"Authentic image size","text":"DOS games appear overly blocky at fullscreen on 24\u201d or larger modern monitors. This is not how people experienced these games back in the day. Typical monitor sizes were 14-15\u201d throughout the 320\u00d7200 VGA era, and 17-19\u201d for the brief 640\u00d7480 SVGA period at the end of the DOS days.
We can make the image a bit smaller with the following setting:
[render]\nviewport = 89%\n
This will result in an image size that is the best compromise between \u201cmodern sensibilities\u201d and the authentic original experience. It\u2019s still on the large end of the spectrum, but not overly so. If you go higher than this, the graphics will start looking overly blocky from a normal viewing distance.
The rationale behind the \u201cmagic 89% value\u201d is explained in detail in the last advanced graphics options chapter.
"},{"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\n
Let\u2019s see what happens if we double the emulated CPU speed!
[cpu]\ncycles = 6000\n
Now we\u2019re greeted by an error when trying to start the game:
run-time error R6003\n- integer divide by 0\n\nC:\\>\n
We 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\n[dosbox]\n# uncomment for Tandy sound\n#machine = tandy\n\n[mouse]\nmouse_capture = onstart\n\n[render]\nviewport = 89%\n# uncomment for double-scanned VGA CRT emulation\n#glshader = crt-auto-machine\n\n[sblaster]\n# uncomment for Game Blaster audio\n#sbtype = gb\n\n[mixer]\n# change 'reverb' to 'tiny' for the PC speaker\nreverb = medium\nchorus = normal\ncrossfeed = on\n\n[autoexec]\nc:\n# use for PC speaker sound\n#sampler i\n\n# use for Tandy sound\n#sampler ts\n\nsampler\nexit\n
"},{"location":"getting-started/setting-up-prince-of-persia/","title":"Setting up Prince of Persia","text":""},{"location":"getting-started/setting-up-prince-of-persia/#first-steps","title":"First steps","text":"We 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.\n
I\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; 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. Looking at pop1demo.exe the solution is quite obvious: we\u2019ll need to run this executable file in DOSBox!
"},{"location":"getting-started/setting-up-prince-of-persia/#the-c-drive","title":"The C drive","text":"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 whether you use uppercase or lowercase C on Windows and macOS but it does in Linux). 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/setting-up-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:
Windows 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, and then select Open with DOSBox Staging in the context menu.
macOS - Mount the DOSBox Staging installer
.dmg image file. - Copy the Start DOSBox Staging icon from the appearing window into the
Prince of Persia folder. - Right-click or Ctrl-click the icon, then select the topmost Open menu item.
- A dialog with the following text will appear: macOS cannot verify the developer of \u201cStart DOSBox Staging\u201d. Are you sure you want to open it?
- Press the Open button.
- A dialog will open, asking for permission to allow DOSBox Staging access to your Documents folder. Click on the OK button.
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.
Linux 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>\n
Alternatively, 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).
"},{"location":"getting-started/setting-up-prince-of-persia/#installing-the-game","title":"Installing the game","text":"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:\\>_\n
The 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:\\>_\n
Type 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:\\>_\n
Well, 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.
DOS filenames
DOS filenames are always uppercase and are limited to 8 characters, plus an optional 3-character file extension. It does not matter whether you type in lowercase or uppercase letters because DOS will always convert them to uppercase before dealing with your input. Tab completion always uses uppercase because\u2026 I guess it just looks nice?
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:\\>_\n
The 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. Best of all, the command history is preserved across DOSBox Staging restarts.
Okay, so here\u2019s what 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:\\>_\n
Tip
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 (nothing to do with body weight) 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.
"},{"location":"getting-started/setting-up-prince-of-persia/#starting-the-game","title":"Starting the game","text":"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.
Running DOS programs
To run executable files (files with the .EXE, .COM or .BAT file extension) it\u2019s enough to type in the filename only, without the extension. So you could have started the game with the prince command as well.
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!
This particular game supports both the keyboard and the joystick. DOSBox Staging emulates a joystick by default, even if you don\u2019t have a physical game controller plugged in. The game is clever enough to auto-detect that and switches to joystick mode at the start. Okay, so let\u2019s switch to keyboard mode instead by pressing Ctrl+K!
You can control the prince with the cursor keys. Hold down the Shift key to walk carefully. 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 available keyboard shortcuts.
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, 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 \u201990s; 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/setting-up-prince-of-persia/#authentic-crt-monitor-emulation","title":"Authentic CRT monitor emulation","text":"DOSBox Staging includes a cathode-ray tube (CRT) monitor emulation feature which is enabled by default. It strives to achieve authentic, period-correct results; the look of PC CRT monitors from the 1980s and 1990s has been painstakingly recreated via shaders as accurately as current technology allows. These monitors exhibit certain characteristic peculiarities when displaying low-resolution graphics; you can think of them as \u201cbuilt-in filters\u201d that can never be disabled. Artists of the era had to embrace and work with these peculiarities, and people playing DOS games on their CRTs saw the art through the same \u201cfilters\u201d as the artists.
For this reason, many people who grew up with CRTs think that once these filters are \u201cdigitally removed\u201d by drawing the pixels as sharp little rectangles on modern flat screens, the art looks bland, sterile, and loses its \u201canalog magic\u201d. That\u2019s the main reason behind enabling the CRT emulation by default, to give people a chance to see the art of DOS games in their full glory as the developers intended.
The remarkable thing about the feature is that it\u2019s \u201czero config\u201d\u2014it automatically adapts to the changing circumstances to always produce the correct CRT look based on the emulated graphics adapter, the current DOS video mode, the window size, and the native resolution of your monitor. You don\u2019t need to think about it or tinker with it, It Just Works\u2122
We\u2019ll showcase the authentic CRT emulation throughout the guide, but if you prefer sharp pixels, we\u2019ll explain how to achieve that in the next chapter.
Proper viewing of screenshots
Screenshots of CRT shaders in action need to be viewed at 100% magnification; otherwise, you might see strange wavy interference patterns 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 at 100% magnification.
"},{"location":"getting-started/setting-up-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 that?
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\n
The 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 with the .conf extension only 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 say \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.
"},{"location":"getting-started/star-wars-dark-forces/","title":"Star Wars: Dark Forces","text":"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/star-wars-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.\n
We 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/star-wars-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\n
The first -w 0.5 argument of the autotype command specifies an initial half-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.
"},{"location":"getting-started/star-wars-dark-forces/#display-refresh-rate","title":"Display refresh rate","text":"Dark Forces uses the 320\u00d7200 256-colour VGA screen mode, just like the majority of DOS games from the 1990s. 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 a fixed 60 Hz rate. 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 the graphics standards emulated by DOSBox Staging:
Graphics standard 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 Hz Creating 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 still has a lot of practical utility.
"},{"location":"getting-started/star-wars-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 tries to automatically detect the conditions where enabling vertical syncing is beneficial 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, so there\u2019s nothing we can do about them at the emulator level).
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, even with DOSBox-level 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. Many pre-rendered cutscenes and FMV games tear really badly on real hardware too on CRTs\u2014that\u2019s the \u201cauthentic DOS experience\u201d for you!
Manually configuring vsync is a complex advanced topic for power users only, so it\u2019s beyond the scope of this beginner\u2019s guide. If you\u2019re feeling brave, look into the presentation_mode, vsync, vsync_skip, host_rate, and dos_rate settings for further details, but it\u2019s unlikely you\u2019ll be able to improve the automatically chosen settings unless you really know what you\u2019re doing (and it\u2019s really easy to make the situation a lot worse by misconfiguring things).
"},{"location":"getting-started/star-wars-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 1990s 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\n
As 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 just powerful enough to handle 70 FPS but not more powerful. 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\n
Start 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 CPU speeds.
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\n
Running 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 achieving a smooth and stable 70 FPS rate.
You have only two options in that 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 chunk 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 switchers 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. This might seem counterintuitive as we\u2019re running decades-old software here, but emulation can be very demanding on your computer.
"},{"location":"getting-started/star-wars-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:
Windows 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\n[fluidsynth]\nsoundfont = \"GeneralUser GS v1.471.sf2\"\n
The 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. It\u2019s best to do this in your primary config, then you never need to think about it again.
Further comparison recordings can be found on our wiki.
Roland SC-55 v1.21 (hardware) Your browser does not support the audio 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 its output level. The best way to do so is by including an additional percentage volume value after the SoundFont\u2019s name in the config, e.g.:
[fluidsynth]\nsoundfont = Arachno.sf2 40\n
This will scale back the volume to 40%. A few SoundFonts are extremely loud\u2014you need to turn the 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 often sounds utterly wrong on a General MIDI device, 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 programmable synthesisers and most MT-32 supporting games take advantage of that to create custom sounds. In contrast, General MIDI modules are generally weaker in the synthesis front but feature more realistic-sounding real-world instruments. The soundtrack of Dark Forces showcases this very well\u2014you can\u2019t get such realistic orchestral music out of an MT-32.
Whenever you configure a game for MIDI sound, you should consult the List of MT-32-compatible computer games first. This contains the hard-earned knowledge of many decades of research and tells you which MIDI module to use for a particular game. The original game manuals very rarely give you this info, and even if they do, the information is often wrong. So you absolutely need this list.
Quite confusingly, there\u2019s a large list of games that claim MT-32 compatibility but only sound correct on a General MIDI module. Make sure to check the List of games that falsely claim MT-32 compatibility as well before configuring any game for MT-32 sound.
A brief history of MIDI in DOS gaming
The iconic Roland MT-32 released in 1987 was the first sound module that made realistic-sounding music in DOS games a possibility. In 1991, Roland released its successor, the iconic Roland Sound Canvas SC-55.
The SC-55 shaped DOS gaming history in significant ways: it was the world\u2019s first device to support the General MIDI standard. MIDI only defines a communication mechanism between MIDI-capable devices (e.g., a sound module and your computer). But it remains silent on how the different instruments should sound. General MIDI (GM) remedied this with its 128 standard instrument definitions. For example, on any GM-compliant module, instrument #1 is always the Acoustic Grand Piano and instrument #36 is the Fretless Bass.
This made interoperation between GM-compliant devices possible. You could use any General MIDI sound module with any GM-compliant game, and you would get music. The music would sound mostly correct, but this depends on the musical composition and the particular sound module. Most composers and gamers had the SC-55, establishing it as a de facto standard. This means music could sound unbalanced and weird on other GM sound modules if they deviated too much from the \u201cgold standard\u201d SC-55 sound.
Additionally, the SC-55 also supports the General Standard (Roland GS, or only GS in short), which is Roland\u2019s vendor-specific General MIDI extension. Many games make good use of these extra features and sound wrong in their absence. This means that alternative MIDI modules need to support both the GM and the GS standards to sound correct with DOS games.
The Yamaha DB50XG and MU-series (e.g., MU50, MU80, MU100, etc.) are such MIDI modules. They can be viewed as more modern-sounding and higher-quality takes on the original SC-55. They offer excellent SC-55 compatibility but with a more polished and punchy sonic character. In fact, many prefer them to the SC-55 in certain DOS games. If you are curious about how these Yamaha modules stack up against the SC-55, this article might be of interest.
"},{"location":"getting-started/star-wars-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 distortions.
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\n
Overall, 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\n
"},{"location":"getting-started/star-wars-dark-forces/#reverse-stereo","title":"Reverse stereo","text":"The 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. This will only reverse the digital sound output of the Sound Blaster.
(Remember, you can use mixer /? or help mixer to view the mixer command\u2019s help.)
"},{"location":"getting-started/star-wars-dark-forces/#minimising-audio-glitches","title":"Minimising audio glitches","text":"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 it mainly 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 but blocksize must be one of the following values: 256, 512, 1024, 2048, 4096, or 8192.
[mixer]\nblocksize = 2048\nprebuffer = 50\n
"},{"location":"getting-started/star-wars-dark-forces/#final-configuration","title":"Final configuration","text":"Here\u2019s the full config of Dark Forces set up for General MIDI sound:
[sdl]\nfullscreen = on\n\n[cpu]\n# to emulate a Pentium 90\ncycles = 50000\n\n[mixer]\ncompressor = off\n\n[midi]\nmididevice = fluidsynth\n\n[fluidsynth]\n# not needed if you set this in the primary config\nsoundfont = \"GeneralUser GS v1.471.sf2\"\n\n[autoexec]\nc:\nmixer master 50\nautotype -w 0.5 1\ndemo\nexit\n
"},{"location":"releases/","title":"Index","text":"Dummy page for redirecting links to to top-level sections
"},{"location":"releases/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 Windows, macOS, or Linux download pages.
Build artifacts are hosted on GitHub; you need to be logged in to GitHub to download them.
Download link Build version Date \u00b9 Windows builds include x86_64 installer and portable ZIP packages, and the experimental ARM64 portable ZIP package.
\u00b2 macOS builds include Intel, Apple silicon, and universal binary package.
\u00b3 We provide a statically linked x86_64 Linux package (only depends on C/C++, ALSA, and OpenGL system libraries).
"},{"location":"releases/development-builds/#installation-notes","title":"Installation notes","text":""},{"location":"releases/development-builds/#windows","title":"Windows","text":"Windows executables in snapshot packages are not signed, therefore Windows 10 or later might prevent the program from starting.
See this guide to learn how to deal with this.
"},{"location":"releases/development-builds/#macos","title":"macOS","text":"macOS development builds are not notarized (but the public releases are); Apple Gatekeeper will try to prevent the program from running.
See this guide to learn how to deal with this.
"},{"location":"releases/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":"releases/development-builds/#fedora","title":"Fedora","text":"sudo dnf install SDL2 SDL2_net opusfile\n
"},{"location":"releases/development-builds/#debian-ubuntu","title":"Debian, Ubuntu","text":"sudo apt install libsdl2-2.0-0 libsdl2-net-2.0-0 libopusfile0\n
"},{"location":"releases/development-builds/#arch-manjaro","title":"Arch, Manjaro","text":"sudo pacman -S sdl2 sdl2_net opusfile\n
"},{"location":"releases/development-builds/#upgrading-your-primary-configuration","title":"Upgrading your primary configuration","text":"Testing new features might require a manual reset of the configuration file.
Since config settings might get renamed, altered, or deprecated between builds, it\u2019s best to let DOSBox Staging write the new default primary config on the first launch, then reapply your old settings manually.
Start by backing up your existing primary config. This is where to find it on each platform:
Windows C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox-staging.conf macOS ~/Library/Preferences/DOSBox/dosbox-staging.conf Linux ~/.config/dosbox/dosbox-staging.conf You can also execute DOSBox Staging with the --printconf option to have the location of the primary config printed to your console.
After backing up the existing primary config, simply start the new version\u2014a new dosbox-staging.conf will be written containing the new defaults and updated setting descriptions.
Portable mode notes
In portable mode, dosbox-staging.conf resides in the same folder as your DOSBox Staging executable. The migration steps for portable mode users are as follows:
- Unpack the new version into a new folder (this is important).
- Create a new empty
dosbox-staging.conf file in the new folder to enable portable mode. - Launch the new version.
DOSBox Staging will write the new defaults to the empty dosbox-staging.conf file. After this, you carry over your settings from the old primary config manually.
"},{"location":"releases/development-builds/#after-upgrading","title":"After upgrading","text":"Look for deprecation warnings in the logs (in yellow or orange colours) and update your configs accordingly.
"},{"location":"releases/linux/","title":"Linux releases","text":""},{"location":"releases/linux/#current-stable-version","title":"Current stable version","text":"Download DOSBox Staging 0.81.2 (x86_64) sha256: c47f1767ae1371666f40e3a4e13272da5c5a98c9c6f355b4fb82bac0d3911a68
Our pre-compiled builds run on most desktop Linux distributions (x86_64 only for now). They only depend on the C/C++, ALSA, and OpenGL system libraries.
Please run the install-icons.sh script included with the release to install the application icons.
Check out the 0.81.2 release notes to learn about the changes and improvements introduced in this release.
If you\u2019re new to DOSBox Staging, we highly recommend following the Getting started guide.
"},{"location":"releases/linux/#0820-release-candidate","title":"0.82.0 release candidate","text":"Release candidate warning
Release candidates are intended for experienced early adopters willing to help us stabilise the next DOSBox Staging version for the final release. Regular users should download the current stable version instead.
0.82.0-RC1
- Download DOSBox Staging 0.82.0-RC1 (x86_x64) sha256: 0e62472dd28a6c613ec60a6bf34493d33638d475796baf39b2f62946e548be87
Check out the 0.82.0-RC release notes to learn about the changes and improvements introduced in this release.
"},{"location":"releases/linux/#hardware-requirements","title":"Hardware requirements","text":"From the x86 family of processors, a processor with SSSE3 (Supplemental Streaming SIMD Extensions 3) is required.
"},{"location":"releases/linux/#external-repository-packages","title":"External repository packages","text":"DOSBox 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":"releases/linux/#containerised-packages","title":"Containerised packages","text":""},{"location":"releases/linux/#fedora-repository-package","title":"Fedora repository package","text":"sudo dnf install dosbox-staging\n
"},{"location":"releases/linux/#gentoo-repository-package","title":"Gentoo repository package","text":"emerge games-emulation/dosbox-staging\n
"},{"location":"releases/linux/#ubuntu-and-mint-repository-package","title":"Ubuntu and Mint repository package","text":"Available via Personal Package Archive:
sudo add-apt-repository ppa:feignint/dosbox-staging\nsudo apt-get update\nsudo apt install dosbox-staging\n
"},{"location":"releases/linux/#arch-and-manjaro-repository-package","title":"Arch and Manjaro repository package","text":"Available via Arch User Repository.
"},{"location":"releases/linux/#nixos-repository-package","title":"NixOS repository package","text":"Available via NixOS or Home Manager. Add the following to your configuration.nix file:
For NixOS:
environment.systemPackages = with pkgs; [\n dosbox-staging\n];\n
For Home Manager:
home.packages = with pkgs; [\n dosbox-staging\n];\n
Then rebuild your system with: nixos-rebuild switch
"},{"location":"releases/linux/#other-repository-packages","title":"Other repository packages","text":""},{"location":"releases/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\n
"},{"location":"releases/linux/#retropie-package","title":"RetroPie package","text":"You can easily configure your DOS games on Retropie to use DOSBox Staging via RetroPie-Setup (select Optional Packages \u2192 DOSBox Staging).
"},{"location":"releases/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":"releases/linux/#older-releases","title":"Older releases","text":" -
DOSBox Staging 0.81.1 (tar.xz) sha256: 5aee92774569cf1e39ade3fccff03994464d17b396b0ae98360af61e9d37cba7
-
DOSBox Staging 0.81.0 (tar.xz) sha256: 034b08a941a7fd0279a81b10af620999c569f7e81b786e7f4b59a0b94e46d399
-
DOSBox Staging 0.80.1 (tar.xz) sha256: 12582a6496b1a276cd239e6b3d21ddfcd51fd8f9e40a1ebbc0a3800e0636190a
-
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
"},{"location":"releases/linux/#building-from-source","title":"Building from source","text":"Of course, you can always build DOSBox Staging straight from the source.
Send us patches if you improve something!
"},{"location":"releases/macos/","title":"macOS releases","text":""},{"location":"releases/macos/#current-stable-version","title":"Current stable version","text":"Download DOSBox Staging 0.81.2 Universal Binary (dmg) sha256: 718968485a0418ead3434285e3a6ab4853914d29d38e14289711af1b2152368e
DOSBos Staging requires macOS 10.15 (Catalina) or later, and supports both Intel and Apple silicon Macs.
Check out the 0.81.2 release notes to learn about the changes and improvements introduced by this release.
If you\u2019re new to DOSBox Staging, we highly recommend following the Getting started guide.
"},{"location":"releases/macos/#0820-release-candidate","title":"0.82.0 release candidate","text":"Release candidate warning
Release candidates are intended for experienced early adopters willing to help us stabilise the next DOSBox Staging version for the final release. Regular users should download the current stable version instead.
0.82.0-RC1
- Download DOSBox Staging 0.82.0-RC1 Universal Binary (dmg) sha256: 10fcca738862b7165c347185d2513005a41147b364dd60af5d79d1193bc29234
Check out the 0.82.0-RC release notes to learn about the changes and improvements introduced in this release.
"},{"location":"releases/macos/#hardware-requirements","title":"Hardware requirements","text":"The latest release is compatible with macOS 10.15 (Catalina) or newer and supports both 64-bit Intel and Apple silicon Macs.
"},{"location":"releases/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\n
"},{"location":"releases/macos/#macports","title":"MacPorts","text":"The 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\n
If 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":"releases/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":"releases/macos/#apple-gatekeeper","title":"Apple Gatekeeper","text":"For releases before 0.81.0 and the development snapshot builds, you\u2019ll need to do the following when launching DOSBox Staging for the first time.
You\u2019ll need to repeat these steps after upgrading to a more recent development build.
"},{"location":"releases/macos/#macos-sequoia-15","title":"macOS Sequoia 15","text":" - Open the DOSBox Staging app, then click Done in the appearing dialog.
- Follow these instructions to allow launching DOSBox Staging in the Privacy & Security tab in System Settings.
"},{"location":"releases/macos/#macos-sonoma-14-or-earlier","title":"macOS Sonoma 14 or earlier","text":" - Ctrl click (or right-click) on the DOSBox Staging app, then click Open.
- Click OK to close the appearing dialog.
- Open the app a second time\u2014now Gatekeeper will show an Open button. Press this to launch DOSBox Staging.
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 were not in a position to make such payments prior to version 0.81.0, and therefore asked users to bypass Apple\u2019s Gatekeeper manually.
Read the first section of this Apple Support article for further info.
"},{"location":"releases/macos/#older-releases","title":"Older releases","text":" -
DOSBox Staging 0.81.1 Universal Binary (dmg) (macOS 10.15 or newer) sha256: 0f89f42d93c39fe96634934e19ef5a9f0a6978d6568e853e95c3f2154b9dbe9c
-
DOSBox Staging 0.81.0 Universal Binary (dmg) (macOS 10.15 or newer) sha256: 5d3cec60552b2a34caa70702b35bdf9ce591cf0b03143802351725a7c729d9fe
-
DOSBox Staging 0.80.1 Universal Binary (dmg) (macOS 10.15 or newer) sha256: 46a256645255e8345981ea357f1416b8ce4bc60a2aba9a86b5122d5075aa7fa9
-
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
"},{"location":"releases/macos/#building-from-source","title":"Building from source","text":"Of course, you can always build DOSBox Staging straight from the source.
Send us patches if you improve something!
"},{"location":"releases/windows/","title":"Windows releases","text":""},{"location":"releases/windows/#current-stable-version","title":"Current stable version","text":" - Download DOSBox Staging 0.81.2 (x86_64, Installer) sha256: 7c23512666f694420e5e2612742de5fb64b32d336e54359b65fd21e7107ef51c
- Download DOSBox Staging 0.81.2 (x86_64, Portable ZIP) sha256: d7ec6054ae58d287c3ad5fbf4c3df732ea3fd75ae828c8f4481fcf7c6203d168
DOSBox Staging requires 64-bit Windows 8, 10, or 11.
Check out the 0.81.2 release notes to learn about the changes and improvements introduced in this release.
If you\u2019re new to DOSBox Staging, we highly recommend following the Getting started guide.
Important
If Windows Security prevents you from running DOSBox Staging via Windows Defender SmartScreen (the built-in Windows antivirus), please follow these instructions.
"},{"location":"releases/windows/#0820-release-candidate","title":"0.82.0 release candidate","text":"Release candidate warning
Release candidates are intended for experienced early adopters willing to help us stabilise the next DOSBox Staging version for the final release. Regular users should download the current stable version instead.
0.82.0-RC1
-
Download DOSBox Staging 0.82.0-RC1 (x86_64, Installer) sha256: 6a29f4ecb307abbb6b67d4c1fa2f34a11a016afe025d16b3b153ba99d3ff20c9
-
Download DOSBox Staging 0.82.0-RC1 (x86_64, Portable ZIP) sha256: e58ee94c5845641b7d67ad11e7aaf2f616cedb0adc947f98380150cddd6935f8
Check out the 0.82.0-RC release notes to learn about the changes and improvements introduced in this release.
"},{"location":"releases/windows/#hardware-requirements","title":"Hardware requirements","text":"An x86 processor with SSSE3 (Supplemental Streaming SIMD Extensions 3) is required.
"},{"location":"releases/windows/#legacy-windows-support","title":"Legacy Windows support","text":"If you\u2019re still on a legacy Windows version, you can use the following older releases. Note these earlier version come with zero official support; the core team won\u2019t be able to help you if you run into issues. Our recommendation will always be to upgrade your Windows and use the latest stable version.
"},{"location":"releases/windows/#windows-810-32-bit","title":"Windows 8/10 32-bit","text":"The official distribution packages only support 32-bit Windows 8 or 10 up to version 0.80.1:
-
For 32-bit Windows 8 or 10, use the 0.80.1 portable ZIP package.
-
For 64-bit Windows 8 or 10, use the current stable version.
"},{"location":"releases/windows/#windows-7","title":"Windows 7","text":"The official distribution packages only support Windows 7 up to version 0.80.1:
-
For 64-bit Windows 7, use the 0.80.1 installer and select the MSVC build, or the 0.81.1 portable ZIP package.
-
For 32-bit Windows 7, use the 0.80.1 portable ZIP package.
"},{"location":"releases/windows/#windows-vista","title":"Windows Vista","text":"The official distribution packages only support Windows Vista up to version 0.78.1.
"},{"location":"releases/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":"releases/windows/#experimental-windows-arm64-builds","title":"Experimental Windows ARM64 builds","text":"We started providing experimental Windows ARM64 packages for devices such as the Snapdragon X Elite. Note we don\u2019t provide any official support for these builds yet.
The ARM64 packages can be downloaded from our development builds page.
"},{"location":"releases/windows/#windows-defender","title":"Windows Defender","text":"Windows Defender (the built-in Windows antivirus starting from Windows 8) might prevent you from running DOSBox Staging when you start it for the first time.
This is a false positive; DOSBox Staging has no malicious code whatsoever, just antivirus software tend to be mistakenly flag emulators as \u201cmalware\u201d.
If this happens, please follow the below steps to grant Windows permission to run DOSBox Staging. You may need to repeat these steps after upgrading to a newer version.
"},{"location":"releases/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.
Consider also performing Method 3 to make DOSBox Staging start up faster.
"},{"location":"releases/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.
Consider also performing Method 3 to make DOSBox Staging start up faster.
"},{"location":"releases/windows/#method-3","title":"Method 3","text":"Add an exclusion to Windows Security to whitelist the DOSBox Staging executable or the folder in which it resides. We recommend doing so even if you\u2019ve already performed either of the previous methods, as it can eliminate the 3\u20135 second startup delay caused by the real-time antivirus scan.
See the steps on how to do this here and here.
"},{"location":"releases/windows/#explanation","title":"Explanation","text":"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":"releases/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":"releases/windows/#older-releases","title":"Older releases","text":" -
DOSBox Staging 0.81.1 (Installer) sha256: 4bb5e63bfef41d4a6ee8f7af3b8c5ee6756987c4247197db0b16d888c6ac0705
-
DOSBox Staging 0.81.1 (Portable ZIP) sha256: cb45e4e56b85cac7b8b1eb63a1bbd93430a226215a5c04f2700076c279d10e12
-
DOSBox Staging 0.81.0 (Installer) sha256: 7de2cbdd8b320017dcf904c3df58b15088047954b053757c870279cbbb301393
-
DOSBox Staging 0.81.0 (Portable ZIP) sha256: ce772a963716d63610e6cb0e817b16f1b5a3cbfd3d5ad802726ddd583f32b79d
-
DOSBox Staging 0.80.1 64-bit (Installer) sha256: 94b961f397f3b70a13daf3b573857b5262515e75d490bfc19f019479fe1694f8
-
DOSBox Staging 0.80.1 64-bit (Portable ZIP) sha256: e7ab98013b55f6fd6db1f529574b8f2905d374225f532ce0905666281cbe32af
-
DOSBox Staging 0.80.1 32-bit (Portable ZIP) sha256: 63a8c5b084231364961f7c8b6415e44622c5ab9822e49839c2aca1bddd3a9459
-
DOSBox Staging 0.80.0 64-bit (Installer) (Windows 7 or newer) sha256: 84445c869e58f6b4591484f6178c7b5b3c8f284bf9460e9afc4502ba842ab039
-
DOSBox Staging 0.80.0 64-bit (Portable 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 (Portable ZIP) (Windows 7 or newer) sha256: 8c7045dfea6dc20bb985cff516d2faee51d2ecaf054db60632857b6941d3d648
-
DOSBox Staging 0.78.1 64-bit (Portable ZIP) (Windows Vista or newer) sha256: 3c2f408125351154a37e93de8a4bd05d0c722bbf53e1f583909e4ca6c3eb9204
-
DOSBox Staging with built-in debugger 0.78.1 64-bit (Portable ZIP) (Windows Vista or newer) sha256: b99f3c354f831ed2b0ed04d215170f696b6fc18285b0c7192c0abab62c41bbc8
-
DOSBox Staging 0.78.0 64-bit (Portable ZIP) (Windows Vista or newer) sha256: f13cba664259fdb0db5e32826e13dcded4270557963f6e823a4731129f23a8a3
-
DOSBox Staging 0.78.0 32-bit (Portable ZIP) (Windows Vista or newer) sha256: 0ca9201cdf3f3a1576b97b0de0e87280b75c633976f0b179ba33a68d44f5ba56
-
DOSBox Staging 0.77.1 64-bit (Portable ZIP) (Windows Vista or newer) sha256: 11ba992ece6d3e4ef2046fcdb6d842da364b69720a921d61fdcc793eb52e7051
-
DOSBox Staging 0.77.1 32-bit (Portable ZIP) (Windows Vista or newer) sha256: a34883101486ce2af071a29c6390f2038889fc519e042101284f2a6999d9f0ef
-
DOSBox Staging 0.77.0 64-bit (Portable ZIP) (Windows Vista or newer) sha256: cacdac418642fd8c7faf1e5955110c35d0c207392ae20835707fd2a1e1114b82
-
DOSBox Staging 0.77.0 32-bit (Portable ZIP) (Windows Vista or newer) sha256: f718d07bab69e3e1be0b28207039cea2746c7e45b8ba7a19b625011f477e609a
-
DOSBox Staging 0.76.0 32-bit (Portable ZIP) (Windows Vista or newer) sha256: 646d2f3fa8189e411589fedcb8148a295361693a6ce95d08e06f4a70e5a36b16
-
DOSBox Staging 0.75.2 64-bit (Portable ZIP) (Windows Vista or newer) sha256: 09f0ca911813a64b8814880eb6e49ad4dcdac9a5bb9263c4887ad82b71fad292
-
DOSBox Staging 0.75.2 32-bit (Portable ZIP) (Windows Vista or newer) sha256: 51dc171ff52ea395c6a22f09ebb98a93974a95c701ca81008368c22a66deced2
-
DOSBox Staging 0.75.1 64-bit (Portable ZIP) (Windows Vista or newer) sha256: 80c60c4377ff2882649f113b3cb3bcd407c17acaac344c49fa1fc4229813f012
-
DOSBox Staging 0.75.1 32-bit (Portable ZIP) (Windows Vista or newer) sha256: 843c742a348f575862e152e02cf174be0ea1c52bdb6e4bffd65f34af88b566b7
-
DOSBox Staging 0.75.0 32-bit (Portable ZIP) (Windows Vista or newer, supports CPUs without SSE4.2) sha256: 69046adcef2ef9920fbba8d40fc9e51f3dd144ba4549787e1816cf1c2ae87d71
-
DOSBox Staging 0.75.0-rc1 32-bit (Portable ZIP) (Windows Vista or newer, supports CPUs without SSE4.2) sha256: 738d2ae2101384f2eeaf1895de64cf1b4c76eaf7873de7e15b7f52145dfed7e7
"},{"location":"releases/windows/#building-from-source","title":"Building from source","text":"Of course, you can always build DOSBox Staging straight from the source.
Send us patches if you improve something!
"},{"location":"releases/release-notes/0.75.0-rc1/","title":"0.75.0-RC1 release notes","text":"Release date: 2020-04-22
"},{"location":"releases/release-notes/0.75.0-rc1/#installation-instructions","title":"Installation instructions","text":" - Linux (or Steam on Linux)
- Windows
- macOS
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":"releases/release-notes/0.75.0/","title":"0.75.0 release notes","text":"Release date: 2020-05-06
"},{"location":"releases/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":"releases/release-notes/0.75.0/#installation-instructions","title":"Installation instructions","text":" - Linux (or Steam on Linux)
- Windows
- macOS
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":"releases/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":"releases/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:
- Dropped 3,211 lines of SDL 1.2 code in place of 1,664 lines, for just under a 50% reduction in code-size.
- Eliminated several OS-specific branches and all SDL1-specific kludges.
- Eased support for modern graphic APIs, and opened the field for new features and improvements.
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\n
macOS users can try Metal:
[sdl]\noutput = texture\ntexture_renderer = metal\n
And everyone can use OpenGL as texture backend:
[sdl]\noutput = texture\ntexture_renderer = opengl\n
Or just use texture_renderer = auto to let SDL pick the backend appropriate for your operating system.
"},{"location":"releases/release-notes/0.75.0/#support-flac-opus-and-mp3-cd-da-tracks","title":"Support FLAC, Opus, and MP3 CD-DA tracks","text":"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\n
For 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\n
FLAC 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\n
When 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\n
If 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\n
"},{"location":"releases/release-notes/0.75.0/#pixel-perfect-scaling-mode","title":"Pixel-perfect scaling mode","text":"Pixel-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\n[render]\nscaler = none\nglshader = none\n
Pixel-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":"releases/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\n
On 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.
"},{"location":"releases/release-notes/0.75.0/#autotype-command","title":"AUTOTYPE command","text":"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\n
Some games that benefit from AUTOTYPE on startup are listed on the wiki page.
"},{"location":"releases/release-notes/0.75.0/#changed-rendering-defaults","title":"Changed rendering defaults","text":"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":"releases/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 game
The 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\n
This 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":"releases/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).
"},{"location":"releases/release-notes/0.75.0/#reload-key-bindings-at-runtime","title":"Reload key bindings at runtime","text":"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.
"},{"location":"releases/release-notes/0.75.0/#reloading-key-bindings","title":"Reloading key bindings","text":"You can now change key bindings at runtime by loading them from a file:
Z:\\> config -set \"sdl mapperfile=<path-to-file>\"\n
"},{"location":"releases/release-notes/0.75.0/#other-new-options-svn","title":"Other new options (SVN)","text":"DOSBox added a number of features to the CONFIG command. To list them all, run:
Z:\\> config /?\n
"},{"location":"releases/release-notes/0.75.0/#configuration-file-locations","title":"Configuration file locations","text":""},{"location":"releases/release-notes/0.75.0/#linux","title":"Linux","text":"DOSBox 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/\n
Users can customize the parent (.config/) location by setting the XDG_CONFIG_HOME environment variable, according to the XDG Specification.
"},{"location":"releases/release-notes/0.75.0/#macos","title":"macOS","text":"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/\n
"},{"location":"releases/release-notes/0.75.0/#windows","title":"Windows","text":"No changes; the configuration files are created in:
C:\\Users\\<username>\\AppData\\Local\\DOSBox\\\n
"},{"location":"releases/release-notes/0.75.0/#modem-phonebook","title":"Modem phonebook","text":"You 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\n
Now 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":"releases/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":"releases/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":"releases/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.
"},{"location":"releases/release-notes/0.75.0/#cga-composite-mode-svn","title":"CGA Composite mode (SVN)","text":"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":"releases/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\n
It\u2019s also possible to provide your shader implementations by placing .glsl files in the configuration directory:
Linux ~/.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\n
Note
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":"releases/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\n
Note 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":"releases/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\n
File TEST.TXT is written to the directory backup, and not to real.
"},{"location":"releases/release-notes/0.75.0/#overview-of-changes","title":"Overview of changes","text":""},{"location":"releases/release-notes/0.75.0/#removed-features","title":"Removed features","text":" - DOSBox Staging does not run on Operating System/2 (OS/2) or derivatives.
- DOSBox Staging does not run on Windows XP or earlier Windows versions.
- Removed support for old DirectDraw (
ddraw) output. Use output = texture, texture_renderer = directx11 instead. - Removed support for old
overlay output. Use any other output. - Removed support for relative window size (
windowresolution = X%). - Removed support for 64-bit Zip Motion Blocks Video (ZMBV) codec (old 32-bit codec still works).
- Removed support for CD-DA playback from physical disks. It is still possible to install games distributed on CDs by mounting them as directories (#260)
- Removed CD-DA playback support for tracks using the Audio Interchange File Format AIFF audio codec.
"},{"location":"releases/release-notes/0.75.0/#development-changes","title":"Development changes","text":" -
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.
- Active SVN branch paths were imported as Git branches (named
svn/<name>). - SVN tag paths were imported as Git lightweight tags (named
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:
- builds cleanly on all supported platforms and compilers,
- adds no new compiler warnings, and
- adds no new static or dynamic analysis issues.
-
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.
"},{"location":"releases/release-notes/0.75.0/#known-issues","title":"Known issues","text":" - Inconsistent minimum window size with
windowresolution = resizable when leaving fullscreen. - Windows, macOS: Window content is not refreshed when resizing.
- Windows, macOS: Emulation stops when moving or resizing window.
- Linux: Wayland crashes (Wayland support is \u201cexperimental\u201d at the moment).
- Linux: Splash screen is sometimes transparent or corrupted on KDE.
Submit new issues or learn more about existing ones using our bug-tracker.
"},{"location":"releases/release-notes/0.75.0/#contributors","title":"Contributors","text":"During the DOSBox Staging 0.75 development period:
- 11 DOSBox Staging contributors submitted 208 pull requests comprised of 780 commits written by 18 authors.
- 69 DOSBox Staging issues were reported and addressed.
- 54 DOSBox Staging wiki updates were made.
- Three DOSBox (SVN) maintainers committed 76 changes written by 5 authors. These changes have been incorporated into DOSBox Staging.
"},{"location":"releases/release-notes/0.75.0/#maintainers","title":"Maintainers","text":" - Patryk Obara
- kcgen
- Anton Shepelev (ant-222)
"},{"location":"releases/release-notes/0.75.0/#direct-contributors","title":"Direct contributors","text":" - Anton Shepelev (ant-222)
- Joshua Fern
- kcgen
- Marco Maccaferri
- NicknineTheEagle
- Nopey Nope
- numberZero
- Patrick McMorris
- Patryk Obara
- Troy Campbell
- Wouter Wijsman
"},{"location":"releases/release-notes/0.75.0/#testers-and-wiki-contributors","title":"Testers and wiki contributors","text":" - GranMinigun
- kas1e
- nemo93
- rderooy
"},{"location":"releases/release-notes/0.75.0/#indirect-contributors","title":"Indirect contributors","text":"Library or patch authors, upstream SVN developers, etc.
- Alexey Khokholov (nukeykt)
- Arthur Ouellet
- David Reid
- jmarsh
- NY00123
- Peter Veenstra
- ripsaw8080
- Ryan C. Gordon
- Sean Barrett
- Sjoerd van der Berg
- VileRancour
- Yann Collet
"},{"location":"releases/release-notes/0.75.0/#changelog","title":"Changelog","text":"You can read detailed changelog via Git, e.g. using the following command:
git shortlog ^v0.75.0-pre v0.75.0 --no-merges\n
"},{"location":"releases/release-notes/0.75.0/#merged-in-community-patches-and-libraries","title":"Merged-in community patches and libraries","text":"The 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
- Add built-in xxHash (v0.7.3) (Yann Collet)
- Add built-in Vorbis codec: (v1.17) (Sean Barrett)
- Add built-in SDL_sound r599 (LGPL) (Ryan C. Gordon)
- Add built-in C++ object serializer (Arthur Cuellet)
- Add built-in FLAC codec: dr_flac v0.12.11 (David Reid)
- Add built-in MP3 codec: dr_mp3 v0.6.4 (David Reid)
- Add built-in WAV codec: dr_wav v0.12.1 (David Reid)
Patryk Obara
- Replace SDL 1.2 with SDL 2.0 (based on work of NY00123)
- Add Nuked OPL3 emulator v1.8 (Alexey Khokholov)
Peter Veenstra
Changes merged-in to SVN
- Add OpenGL shader support (ny00123 and refined by jmarsh)
-
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)
- Fix some issues with commit 4282 (Patryk Obara and 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
- Add cga_mono machine (VileRancour)
"},{"location":"releases/release-notes/0.75.0/#thank-you","title":"Thank you","text":"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
"},{"location":"releases/release-notes/0.75.1/","title":"0.75.1 release notes","text":"Release date: 2020-08-19
"},{"location":"releases/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":"releases/release-notes/0.75.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
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":"releases/release-notes/0.75.1/#new-features-in-detail","title":"New features in detail","text":""},{"location":"releases/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":"releases/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":"releases/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)\n
Users previously had to debug the dosbox binary to discover the base address; an easy but tedious process.
"},{"location":"releases/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)
"},{"location":"releases/release-notes/0.75.1/#contributors","title":"Contributors","text":""},{"location":"releases/release-notes/0.75.1/#maintainers","title":"Maintainers","text":""},{"location":"releases/release-notes/0.75.1/#direct-contributors","title":"Direct contributors","text":" - Expack3
- kcgen
- nemo93
- Patryk Obara
- WengierWu
"},{"location":"releases/release-notes/0.75.1/#indirect-contributors","title":"Indirect contributors","text":""},{"location":"releases/release-notes/0.75.1/#changelog","title":"Changelog","text":"You can read detailed changelog via Git, e.g. using the following command:
git shortlog ^v0.75.0 v0.75.1\n
"},{"location":"releases/release-notes/0.75.1/#thank-you","title":"Thank you","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"releases/release-notes/0.75.2/","title":"0.75.2 release notes","text":"Release date: 2020-10-26
"},{"location":"releases/release-notes/0.75.2/#summary","title":"Summary","text":"This is a maintenance release from the 0.75.x stable branch.
"},{"location":"releases/release-notes/0.75.2/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.75.2/#new-features-in-detail","title":"New features in detail","text":""},{"location":"releases/release-notes/0.75.2/#select-monochrome-palette-colour","title":"Select monochrome palette colour","text":"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\n
See: #607
"},{"location":"releases/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\n
The 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":"releases/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)
"},{"location":"releases/release-notes/0.75.2/#notes-for-packagers","title":"Notes for packagers","text":"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\"\n
-
Our 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":"releases/release-notes/0.75.2/#contributors","title":"Contributors","text":""},{"location":"releases/release-notes/0.75.2/#maintainers","title":"Maintainers","text":" - Patryk Obara
- kcgen
- nemo93
"},{"location":"releases/release-notes/0.75.2/#contributors_1","title":"Contributors","text":" - Bernard Cafarelli
- David Heidelberg
- Feignint
- MasterO2
- NicknineTheEagle
- WengierWu
"},{"location":"releases/release-notes/0.75.2/#thank-you","title":"Thank you","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"releases/release-notes/0.76.0/","title":"0.76.0 release notes","text":"Release date: 2020-12-03
"},{"location":"releases/release-notes/0.76.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.76.0/#summary","title":"Summary","text":"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":"releases/release-notes/0.76.0/#new-features-in-detail","title":"New features in detail","text":""},{"location":"releases/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 the audio 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":"releases/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)
"},{"location":"releases/release-notes/0.76.0/#built-in-midi-support-via-fluidsynth","title":"Built-in MIDI support via FluidSynth","text":"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\n[fluidsynth]\nsoundfont = my-favourite-soundfont.sf2\n
DOSBox 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).
"},{"location":"releases/release-notes/0.76.0/#fine-grained-midi-level-controls","title":"Fine-grained MIDI level controls","text":"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\n
This 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\n
"},{"location":"releases/release-notes/0.76.0/#what-soundfont-should-i-use","title":"What soundfont should I use?","text":"This 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":"releases/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":"releases/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":"releases/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.
"},{"location":"releases/release-notes/0.76.0/#ls-command","title":"LS command","text":"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:
- Fits as many directory entries as possible on the screen
- Differentiates directories, executables, and plain files using color
- Prints files in lowercase and directories in uppercase, Norton Commander style
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
"},{"location":"releases/release-notes/0.76.0/#rapid-dc-offset-correction-for-the-emulated-pc-speaker","title":"Rapid DC offset correction for the emulated PC speaker","text":"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":"releases/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:
- Initial audio by all emulated devices is fed through a 15-ms envelope specifically timed to prevent unnatural electronic pops and clicks, yet fast enough to ensure that sharp-attack natural sounds (such as a cymbal crash) are not affected.
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
- Some games test their interface to the Sound Blaster 16 using one or more small \u201cjunk\u201d DMA transfers. Unfortunately on actual hardware, these result in startup clicks and pops, which can be jarring when using a headset. We now suppress these initial junk transfers.
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":"releases/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":"releases/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":"releases/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\n
For 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":"releases/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":"releases/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":"releases/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:
- Alt+Enter \u2013 Switch between fullscreen and window mode
- Alt+Pause \u2013 Pause/Unpause emulator
- Ctrl+F1 \u2013 Start the keymapper
- Ctrl+F4 \u2013 Change between mounted floppy/CD images
- Ctrl+F5 \u2013 Save a screenshot
- Ctrl+F6 \u2013 Start/Stop recording sound output to a wave file
- Ctrl+F7 \u2013 Start/Stop recording video output to a zmbv file
- Ctrl+F9 \u2013 Shutdown emulator
- Ctrl+F10 \u2013 Capture/Release the mouse
- Ctrl+F11 \u2013 Slow down emulation
- Ctrl+F12 \u2013 Speed up emulation
- Ctrl+Alt+Home \u2013 Restart emulator
- Hold Alt+F12 \u2013 Fast forward
Keymapper received tiny usability improvements as well: it displays the keyboard shortcut (binding) for the selected action.
"},{"location":"releases/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":"releases/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":"releases/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":"releases/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":"releases/release-notes/0.76.0/#bugfixes","title":"Bugfixes","text":"Some notable bugfixes:
- Prevent SDL2 crash on exit when using Wayland. (#336)
- Fix sound effects in Prince of Persia on Tandy. (#457)
- Prevent crash on SDL2 re-creating OpenGL window. (#510)
- Fix
dir /p in non-standard text modes. (#528) - Prevent injection of spurious newlines in autoexec and bat files. (#536)
- Fix
capture_mouse middlegame setting. (#563) - Fix a CD-DA roll-over bug when calculating PCM frames. (#569)
- Fix boot failure from an image mounted as C:. (#589)
- Fix memory leak in the modem phone book. (#622)
- Fix
cls command. (#639) - Increase default DOS file limit for emulation of program Subiekt 4. (#656)
-
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)
"},{"location":"releases/release-notes/0.76.0/#known-issues","title":"Known issues","text":" -
(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.
"},{"location":"releases/release-notes/0.76.0/#removed-features","title":"Removed features","text":" -
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).
"},{"location":"releases/release-notes/0.76.0/#notes-for-developers","title":"Notes for developers","text":" -
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":"releases/release-notes/0.76.0/#changes-merged-from-upstream-projects","title":"Changes merged from upstream projects","text":" - Merge DOSBox SVN changes up to revision 4392
- Sync dr_mp3 v0.6.11 from upstream
- Sync dr_flac v0.12.13 from upstream
- Sync dr_wav v0.12.4 from upstream
- Sync xxhash 0.8.0 from upstream
- Sync stb header v2.36 from upstream
- Sync stb_vorbis v1.19 from upstream
"},{"location":"releases/release-notes/0.76.0/#contributors","title":"Contributors","text":"During DOSBox Staging 0.76 development period we merged 1035 commits, including 55 commits originating from the DOSBox project.
"},{"location":"releases/release-notes/0.76.0/#maintainers","title":"Maintainers","text":" - Patryk Obara
- kcgen
- nemo93
"},{"location":"releases/release-notes/0.76.0/#direct-contributors","title":"Direct contributors","text":" - Affonso Amendola
- Bernard Cafarelli
- cfoesch
- ClassicHasClass
- David Heidelberg
- drfiemost
- Edward Betts
- Erlotinib
- Expack3
- Feignint
- Jonathan Campbell
- MasterO2
- NicknineTheEagle
- Nikos Chantziaras
- Robert de Rooy
- Troy Campbell
- Tyrell Sassen
- Vladimir Serbinenko
- Wengier
"},{"location":"releases/release-notes/0.76.0/#dosbox-contributors","title":"DOSBox contributors","text":"SVN r4336:r4392
- Harekiet
- jmarsh
- Jonathan Campbell
- NewRisingSun
- Qbix
- ripsaw8080
"},{"location":"releases/release-notes/0.76.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":"releases/release-notes/0.77.0/","title":"0.77.0 release notes","text":"Release date: 2021-07-21
"},{"location":"releases/release-notes/0.77.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.77.0/#significant-changes","title":"Significant changes","text":""},{"location":"releases/release-notes/0.77.0/#migrated-to-the-meson-build-system","title":"Migrated to the Meson build system","text":"Migrated Staging from autotools to the Meson build system. Those building from source, please see BUILD.md in the repository. See: #854
"},{"location":"releases/release-notes/0.77.0/#macos-and-selinux-security-policy-compliance","title":"macOS and SELinux security policy compliance","text":"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":"releases/release-notes/0.77.0/#variable-expansion-in-the-interactive-dos-shell","title":"Variable expansion in the interactive DOS shell","text":"See: #1059
"},{"location":"releases/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.
"},{"location":"releases/release-notes/0.77.0/#finished-mt-32-integration","title":"Finished MT-32 integration","text":"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.
"},{"location":"releases/release-notes/0.77.0/#ibm-ps1-audio-device-support","title":"IBM PS/1 Audio device support","text":"See the wiki notes for how to use it.
Thanks to JMK for authoring PS/1 Audio emulation in 2008.
"},{"location":"releases/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.
"},{"location":"releases/release-notes/0.77.0/#macos-hotkey-changes","title":"macOS hotkey changes","text":"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":"releases/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":"releases/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.
"},{"location":"releases/release-notes/0.77.0/#relative-window-size-support","title":"Relative window size support","text":"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).
"},{"location":"releases/release-notes/0.77.0/#window-resizing-enabled-by-default","title":"Window resizing enabled by default","text":"Window resizing using corner-drag is now auto-enabled on all platforms when conditions permit.
"},{"location":"releases/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)
"},{"location":"releases/release-notes/0.77.0/#contributions","title":"Contributions","text":"The 0.77 release includes 920 commits plus 35 commits originating from the DOSBox project.
"},{"location":"releases/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:
- Antti Peltola (macOS testing and feedback)
- Brandon Munger (collaborator)
- Burrito78 (macOS testing and feedback)
- GranMinigun (testing and triage)
- kcgen (maintainer)
- Kirk Klobe (maintainer)
- Dennis L\u00fchring (collaborator)
- nemo93 (Wiki maintainer)
- Patryk Obara (maintainer)
- Ruben Genoese (testing and triage)
- Wengier (collaborator)
"},{"location":"releases/release-notes/0.77.0/#direct-contributors","title":"Direct contributors","text":"The following authors, co-authors, wiki editors, translators, testers, and bug reporters directly contributed to the 0.77 release:
- Allofich
- Antti Peltola
- Brandon Munger
- Burrito78
- Dennis L\u00fchring
- Didu
- Draky50110
- Dugan Chen
- eli-schwart
- Emmanuel Gil Peyrot
- Feignint
- Gilles
- GranMinigun
- hail-to-the-ryzen
- IlyaIndigo
- IPeluchito
- jmarsh
- Joshua Kr\u00e4mer
- Kappa971
- kcgen
- Ken H\u00e4ndel
- Kirk Klobe
- mdmallard
- nemo93
- Otto Urpelainen
- Patryk Obara
- Peluchito
- Ruben Genoese
- rhys073
- Sarah Whitman
- Toby Jennings
- warpdesign
- Wengier
"},{"location":"releases/release-notes/0.77.0/#dosbox-contributors","title":"DOSBox contributors","text":"The following DOSBox authors\u2019 SVN commits (r4393 through r4459) were merged during the 0.77 timeframe:
- jmarsh
- Peter Veenstra
- ripsaw8080
- Sjoerd van der Berg
"},{"location":"releases/release-notes/0.77.0/#indirect-contributors","title":"Indirect contributors","text":"The following patch or external project authors\u2019 sources were merged during the 0.77 timeframe:
- Antti S. Lankila (reSIDfp maintainer)
- Dag Lem (original reSID author)
- David Reid (dr_libs audio codecs author)
- Dean Beeler (original MT-32 patch author)
- Jason Kim (PS/1 patch author)
- Jonathan Campbell (DOSBox-X maintainer)
- nukeykt (Nuked OPL emulator author)
- sergm (Munt and MT-32 patch maintainer)
- Vasyl Tsvirkunov (SS1-2001 patch author)
- Wengier (DOSBox-X maintainer)
- ykhwong (DOSBox Daum maintainer)
"},{"location":"releases/release-notes/0.77.0/#thank-you","title":"Thank you","text":"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":"releases/release-notes/0.77.1/","title":"0.77.1 release notes","text":"Release date: 2021-08-28
"},{"location":"releases/release-notes/0.77.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.77.1/#bugfixes","title":"Bugfixes","text":"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).
- Synchronize Italian translation files (Kappa971).
- Synchronize German translation files (Burrito78).
- Generate macOS Universal Binary supporting x86_64 and arm64 (Kirk Klobe)
"},{"location":"releases/release-notes/0.77.1/#translations-pack-included","title":"Translations pack included","text":"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\n
Or via primary or local config file:
[dosbox]\nlanguage = de\n# de, es, fr, it, pl, ru\n
Tip
Use dosbox -editconf to open your config file.
For future reference, the above is also discussed in the README.
"},{"location":"releases/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":"releases/release-notes/0.78.0/","title":"0.78.0 release notes","text":"Release date: 2021-12-25
"},{"location":"releases/release-notes/0.78.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.78.0/#significant-changes","title":"Significant changes","text":" -
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)
"},{"location":"releases/release-notes/0.78.0/#bugfixes","title":"Bugfixes","text":" -
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)
"},{"location":"releases/release-notes/0.78.0/#translation-updates","title":"Translation updates","text":" - Italian (Kappa971)
- German (Burrito78)
- Russian (GranMinigun)
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.
"},{"location":"releases/release-notes/0.78.0/#repository-authors","title":"Repository authors","text":"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 7 During the 0.78 timeframe, DOSBox SVN commits r4466 through r4471 were merged to the project and authorship is reflected above.
"},{"location":"releases/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":"releases/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":"releases/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":"releases/release-notes/0.78.1/","title":"0.78.1 release notes","text":"Release date: 2022-01-07
"},{"location":"releases/release-notes/0.78.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.78.1/#fixes-and-regressions","title":"Fixes and regressions","text":"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)
"},{"location":"releases/release-notes/0.78.1/#functionality-refinements","title":"Functionality refinements","text":" -
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)
"},{"location":"releases/release-notes/0.78.1/#documentation-related-improvements","title":"Documentation-related improvements","text":" -
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)
"},{"location":"releases/release-notes/0.78.1/#development-and-packaging-fixes","title":"Development and packaging fixes","text":" -
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)
"},{"location":"releases/release-notes/0.78.1/#known-issues","title":"Known issues","text":" -
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
- to the Windows Console API.
-
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\n
Tip
Run dosbox -editconf to open your config file.
Thanks to Genju for reporting this regression and isolating the solution.
"},{"location":"releases/release-notes/0.78.1/#thank-you","title":"Thank you","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"releases/release-notes/0.79.0/","title":"0.79.0 release notes","text":"Release date: 2022-09-19
"},{"location":"releases/release-notes/0.79.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.79.0/#what-you-can-expect","title":"What you can expect","text":" -
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":"releases/release-notes/0.79.0/#audio-improvements","title":"Audio improvements","text":""},{"location":"releases/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\n
"},{"location":"releases/release-notes/0.79.0/#sound-card-output-filter-emulation","title":"Sound card output filter emulation","text":"Most 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":"releases/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\n
Some 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.
"},{"location":"releases/release-notes/0.79.0/#small-speaker-systems","title":"Small-speaker systems","text":"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_filter
"},{"location":"releases/release-notes/0.79.0/#custom-filters","title":"Custom filters","text":"Advanced 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]\n
where 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\n
To 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\n
In 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_filter
"},{"location":"releases/release-notes/0.79.0/#crossfeed","title":"Crossfeed","text":"Listening 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.
"},{"location":"releases/release-notes/0.79.0/#reverb-and-chorus","title":"Reverb and chorus","text":""},{"location":"releases/release-notes/0.79.0/#reverb","title":"Reverb","text":"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.
"},{"location":"releases/release-notes/0.79.0/#chorus","title":"Chorus","text":"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 the video 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 the audio 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":"releases/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.
"},{"location":"releases/release-notes/0.79.0/#general-mixer-improvements","title":"General mixer improvements","text":" -
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.
"},{"location":"releases/release-notes/0.79.0/#one-opl-mode-to-rule-them-all","title":"\u201cOne OPL mode to rule them all\u201d \ud83d\udc8d","text":"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":"releases/release-notes/0.79.0/#fluidsynth-configuration-changes","title":"FluidSynth configuration changes","text":""},{"location":"releases/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":"releases/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.
"},{"location":"releases/release-notes/0.79.0/#ripas-pc-speaker-patch","title":"ripa\u2019s PC speaker patch","text":"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\n[speaker]\npcspeaker = discrete\n
Your browser does not support the video 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":"releases/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.
"},{"location":"releases/release-notes/0.79.0/#audio-mute-and-pause","title":"Audio mute and pause","text":"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\n
Or you can pause emulation entirely when in the background with:
[sdl]\npause_when_inactive = true\n
"},{"location":"releases/release-notes/0.79.0/#graphical-improvements","title":"Graphical improvements","text":""},{"location":"releases/release-notes/0.79.0/#shader-reload-shortcut","title":"Shader reload shortcut","text":"As 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":"releases/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
"},{"location":"releases/release-notes/0.79.0/#scaled-image-quality-improvements","title":"Scaled image quality improvements","text":"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":"releases/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":"releases/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).
"},{"location":"releases/release-notes/0.79.0/#frame-presentation-modes","title":"Frame presentation modes","text":"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\n[dosbox]\ndos_rate = default | host | custom-rate\n
"},{"location":"releases/release-notes/0.79.0/#dos-shell-improvements","title":"DOS shell improvements","text":""},{"location":"releases/release-notes/0.79.0/#piping-from-the-dos-prompt-or-batch-files","title":"Piping from the DOS prompt or batch files","text":"DOSBox 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).
"},{"location":"releases/release-notes/0.79.0/#file-attribute-support-and-attrib-command","title":"File attribute support and ATTRIB command","text":"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.
"},{"location":"releases/release-notes/0.79.0/#default-choices-for-the-choice-command","title":"Default choices for the CHOICE command","text":"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.
"},{"location":"releases/release-notes/0.79.0/#mount-improvements","title":"Mount improvements","text":""},{"location":"releases/release-notes/0.79.0/#physical-cd-rom-mount-support","title":"Physical CD-ROM mount support","text":"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.
"},{"location":"releases/release-notes/0.79.0/#read-only-disk-image-mount-support","title":"Read-only disk image mount support","text":"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.
"},{"location":"releases/release-notes/0.79.0/#z-drive-customisation-and-directory-support","title":"Z-drive customisation and directory support","text":"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.
"},{"location":"releases/release-notes/0.79.0/#imgmount-wildcard-support","title":"IMGMOUNT wildcard support","text":"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.
"},{"location":"releases/release-notes/0.79.0/#automount-of-resource-drives","title":"Automount of resource drives","text":"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\n
A 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.
"},{"location":"releases/release-notes/0.79.0/#localisation-improvements","title":"Localisation improvements","text":""},{"location":"releases/release-notes/0.79.0/#code-pages-and-keyboard-layouts","title":"Code pages and keyboard layouts","text":"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:
- List of available code pages
- List of available keyboard layouts
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
"},{"location":"releases/release-notes/0.79.0/#country-support-for-different-date-time-and-decimal-formats","title":"Country support for different date, time, and decimal formats","text":"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":"releases/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.
"},{"location":"releases/release-notes/0.79.0/#input-improvements","title":"Input improvements","text":""},{"location":"releases/release-notes/0.79.0/#mouse-wheel-emulation","title":"Mouse-wheel emulation","text":"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.
"},{"location":"releases/release-notes/0.79.0/#serial-mice-emulation","title":"Serial mice emulation","text":"Numerous serial (COM port) mice are now emulated:
- original Microsoft mouse with 2 buttons
- Logitech mouse, with 3 buttons
- wheel mouse with 3 buttons
- Mouse Systems mouse (old mouse type, not compatible with the ones listed above), with 3 buttons
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":"releases/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":"releases/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\n
Once 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\n
Note 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 the video element. The new joystick calibration feature in action
"},{"location":"releases/release-notes/0.79.0/#general-improvements","title":"General improvements","text":""},{"location":"releases/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.
"},{"location":"releases/release-notes/0.79.0/#windows-installer-for-windows-users","title":"Windows installer for Windows users","text":"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":"releases/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\n
Although 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":"releases/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:
mcb_fault_strategy Behaviour How it affects the buggy game 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":"releases/release-notes/0.79.0/#developer-related-improvements","title":"Developer-related improvements","text":""},{"location":"releases/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":"releases/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":"releases/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
"},{"location":"releases/release-notes/0.79.0/#continuous-integration-msys2-workflow-improvements","title":"Continuous integration MSYS2 workflow improvements","text":"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":"releases/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":"releases/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":"releases/release-notes/0.79.0/#translation-status","title":"Translation status","text":" - German: up-to-date
- Italian: up-to-date
- Polish: up-to-date
- Russian: config sections up-to-date
- French: not updated
- Spanish: not updated
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 style Escribiendo ^[[34;1mdir^[[0m all\ufffd mostrar\ufffd su contenido. Digita [color=blue]dir[reset] per visualizzarne il contenuto."},{"location":"releases/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.
"},{"location":"releases/release-notes/0.79.0/#special-thanks","title":"Special thanks","text":" -
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
"},{"location":"releases/release-notes/0.79.0/#contributors","title":"Contributors","text":""},{"location":"releases/release-notes/0.79.0/#maintainers","title":"Maintainers","text":" - kcgen
- John Novak
- FeralChild64
- shermp
- Wengier
"},{"location":"releases/release-notes/0.79.0/#authors","title":"Authors","text":" - kcgen
- John Novak
- FeralChild64
- Wengier
- shermp
- Kirk Klobe
- GranMinigun
- Patryk Obara
- ripsaw8080 (DOSBox maintainer)
- NicknineTheEagle
- David Reid (dr_lib author, 3rd party dependency)
- Leandro Nini (libresidfp author, 3rd party dependency)
- Jonathan Campbell (DOSBox-X maintainer)
- Dean Beeler
- ripa (DOSBox patch author)
- Keenan Weaver
- Dennis L\u00fchring
- IPeluchito
- Otto Liljalaakso
- Peter Ferrie
- arrowgent
- gulrak
- hunterk
"},{"location":"releases/release-notes/0.79.0/#translators","title":"Translators","text":" - Burrito78 (German)
- FeralChild64 (Polish)
- GranMinigun (Russian)
- Kappa971 (Italian)
"},{"location":"releases/release-notes/0.79.0/#sponsors","title":"Sponsors","text":" - Antti Peltola: 3,000 USD during the 0.79 development cycle
- Wengier
"},{"location":"releases/release-notes/0.79.0/#backers","title":"Backers","text":" 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":"releases/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":"releases/release-notes/0.79.1/","title":"0.79.1 release notes","text":"Release date: 2022-09-30
"},{"location":"releases/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":"releases/release-notes/0.79.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.79.1/#fixes-and-regressions","title":"Fixes and regressions","text":" -
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)
Your browser does not support the video element. 303 by Acme \u2014 30fps encoding, 120k cycles, and SB16 using the modern filter
"},{"location":"releases/release-notes/0.79.1/#functionality-refinements","title":"Functionality refinements","text":" -
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)
"},{"location":"releases/release-notes/0.79.1/#translation-improvements","title":"Translation improvements","text":" - Added Dutch translation (Robert de Rooy)
- Fixed outdated content in German translation (Burrito78)
-
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)
"},{"location":"releases/release-notes/0.79.1/#wiki-updates-since-0790","title":"Wiki updates since 0.79.0","text":" -
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)
"},{"location":"releases/release-notes/0.79.1/#packaging-fixes","title":"Packaging fixes","text":" -
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\n
"},{"location":"releases/release-notes/0.79.1/#thank-you","title":"Thank you","text":"Thanks 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":"releases/release-notes/0.80.0/","title":"0.80.0 release notes","text":"Release date: 2022-12-21
"},{"location":"releases/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":"releases/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":"releases/release-notes/0.80.0/#downloads","title":"Downloads","text":""},{"location":"releases/release-notes/0.80.0/#upgrade-your-configuration-file","title":"Upgrade your configuration file","text":" - Launch the new release.
- At the
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.
"},{"location":"releases/release-notes/0.80.0/#new-features","title":"New features","text":""},{"location":"releases/release-notes/0.80.0/#reelmagic-support","title":"ReelMagic support","text":"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.
Your browser does not support the 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":"releases/release-notes/0.80.0/#mouse-improvements","title":"Mouse improvements","text":""},{"location":"releases/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
"},{"location":"releases/release-notes/0.80.0/#dual-mouse-gaming","title":"Dual mouse gaming","text":"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 the video element. The Settlers II (1996) \u2014 showcasing dual-mouse gaming in action
"},{"location":"releases/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":"releases/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":"releases/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":"releases/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
"},{"location":"releases/release-notes/0.80.0/#how-to-use-it","title":"How to use it","text":"Follow the steps indicated in the DMG package, as shown:
Simply copy the included Start DOSBox Staging.command to a folder that contains a local dosbox.conf and then open it (Start DOSBox Staging.command) in the 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":"releases/release-notes/0.80.0/#general-improvements","title":"General improvements","text":""},{"location":"releases/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.
Your browser does not support the video element. more.com \u2014 Better and Improved\u2122
"},{"location":"releases/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 the video element. Reconfiguring audio on-the-fly \u2014 changing sound cards in a PC has never been easier!
"},{"location":"releases/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":"releases/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
Full PR list of additions and improvements - Add
--working-dir command line option (#2122) - Add a subset of OpenGL shaders from Tyrells\u2019 repo (#2137)
- Add direct support for Windows 3.1 seamless mouse driver by javispedro (#1996)
- Add libraries to support TrueType font rendering (#2075)
- Add more cleanup on audio device tear-down (#2099)
- Add mouse related hints to title bar (#2062)
- Add release drafter support files (#2036)
- Add screenshots for rendered output #2073) (#2078)
- Allow to cancel interactive mouse mapping with a keyboard (#2067)
- Bump actions/cache from 2 to 3.0.11 (#2025)
- Bump actions/download-artifact from 2 to 3 (#2028)
- Bump actions/upload-artifact from 2 to 3 (#2026)
- Bump fountainhead/action-wait-for-check from 1.0.0 to 1.1.0 (#2027)
- Bump microsoft/setup-msbuild from 1.1 to 1.2 (#2123)
- Bump microsoft/setup-msbuild from 1.2 to 1.3 (#2129)
- Check file-descriptor dependency for Enet, slirp, and ManyMouse (#2108)
- Cleanup a handful of build issues for clang 10.x and 11.x (#2096)
- Cleanup issues in ReelMagic flagged by Coverity (#2084)
- Cleanup overcomplicated data conversions in Unicode support (#2104)
- Cleanup string IDs of DOS programs (#2064)
- Compiler warning fix in ManyMouse library (#2076)
- Contribute a script to convert from YouTube chapters to CD-DA (#2037)
- Customise the looks of the macOS DMG distribution disk image (#2127)
- Debloat the binary: use more heap storage and retire the software scalar (#2101)
- Drop architecture spec from setup-msbuild GitHub action (#2124)
- Enable DPI scaling on Windows (#2105)
- Fix a couple CWE issues in ManyMouse (#2040)
- Fix sentence starting with lower case in MOUNT command help (#2068)
- Generate linker map file by default (#2103)
- Implement MORE.COM command (#2020)
- Import Jon Dennis\u2019s ReelMagic emulation package #1112) (#2077)
- Improve detection of atomics, testing of speexDSP, and cleanup README (#1992)
- Improve interactive mouse mapping (#2065)
- Improve management of audio devices (#2095)
- Look for libXInput dependency (#2085)
- Minor mouse enhancements (#2060)
- Mouse mapper and configuration mechanism (#2000)
- Refactor ReelMagic player with per-stream handle registration (#2086)
- Refactor the ReelMagic audio FIFO class (#2090)
- Simplifies file search in virtual drive (#2130)
- Split contributed CD-DA scripts into fetch vs. cue functions (#2045)
- Sync reSIDfp with upstream (#2092)
- Update CI against latest deprecations and OS versions (#2031)
- Update Tracy to v0.9 (#2069)
- Update the build system wraps and automate CI action maintenance (#2024)
- Update wraps and PVS Studio (#2097)
- Use MORE engine for help output (#2079)
- Use a
sdd::unique_ptr to manage the video memory (#2116) - Use shared pointers to manage the virtual files (#2117)
"},{"location":"releases/release-notes/0.80.0/#bug-and-regression-fixes","title":"Bug and regression fixes","text":" -
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.
Full PR list of bug and regression fixes - Adapt
update-sources.sh script to UTF-8 locale (#2011) - Add modem call warm-up period (#2125)
- Always use VFR presentation mode for text modes (#2139)
- Avoid shifting negative DAC data in Sound Blaster (CWE-758) (#2115)
- Capture the OpenGL screenshot using RGBA pixel format (#2143)
- Change
config -wc to write UTF-8 file (#1991) - Drop architecture spec from setup-msbuild GitHub action (#2124)
- Fix FluidSynth reverb and chorus settings not applying (#2133)
- Fix a memory leak in the keyboard layout class (#1985)
- Fix assertion in mouse code for surface screen output (#2110)
- Fix bitwise shift of negative in DOS date pack call (#2034)
- Fix character D6 mapping in code page 3021 (Bulgarian MIK encoding) (#2094)
- Fix several English strings too long to fit on screen (#1998)
- Fix tab handling in MORE command (#2102)
- Improve
mixer.com CLI handling of volume and effect arguments (#2021) - Initialize the window\u2019s canvas size during its setup phase (#2038)
- Limit
bit_views to 8-bit registers to avoid byte-order assumption (#1999) - MORE text output engine fixes (#2083)
- Parse language options before writing the conf file (#2001)
- Remove errorneous screen parameters check in mouse code (#2119)
- Restore 0.79.1 mouse acceleration model in DOS driver (#2087)
- Restore WheelHasMoved bit in DOS mouse driver to correct value (#2091)
- Use non-throwing form of
std::filesystem calls (#1995)
"},{"location":"releases/release-notes/0.80.0/#translation-improvements","title":"Translation improvements","text":""},{"location":"releases/release-notes/0.80.0/#translations","title":"Translations","text":" - German: up-to-date
- Italian: up-to-date
- Polish: up-to-date
- Russian: up-to-date
- French: not updated
- Spanish: not updated
"},{"location":"releases/release-notes/0.80.0/#related-improvements","title":"Related improvements","text":" -
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.
Full PR list of documentation and translation changes - Adapt
update-sources.sh script to UTF-8 locale (#2011) - Add Dutch tranlation of MOUSECTL (#2042)
- Add Dutch translation of MORE (#2048)
- Add handling for ABNT2 slash/question mark key (by rsribeiro) (#2082)
- Add release drafter support files (#2036)
- Clarify
tandy and ibm5153 cga_colors config descriptions (#2074) - Cleanup string IDs of DOS programs (#2064)
- Convert esc codes to ansi in src (#2008)
- Delete obsolete translated msgs (#2058)
- Fix character D6 mapping in code page 3021 (Bulgarian MIK encoding) (#2094)
- Fix code page 30020 to UTF-8 mapping (#1988)
- Fix code page 30020 to UTF-8 mapping (#1988)
- Fix mistakes in switching to ansi text codes (#2017)
- Fix some errors in the Italian (it-it) translation (#2029)
- Fixed some ANSI escape codes in the Italian translation (#2013)
- Fixup nl.txt to match nl.lng (#2010)
- Improve build instructions (#2126)
- Improve detection of atomics, testing of speexDSP, and cleanup README (#1992)
- Minor Dutch translation updates (#2007)
- Parse language options before writing the conf file (#2001)
- Support for UTF-8 locale (2nd generation patch) (#1884)
- Support for UTF-8 locale (2nd generation patch) (#1884)
- Switch messages in
MSG_Add from code page 437 to UTF-8 (#1984) - Switch messages in
MSG_Add from code page 437 to UTF-8 (#1984) - Translate new message (#2032)
- Update Dutch (nl) translation (#2100)
- Update Dutch (nl) translation (#2141)
- Update Italian (it-it) translation (#2005)
- Update Italian (it-it) translation (#2041)
- Update Italian (it-it) translation (#2055)
- Update Italian (it-it) translation (#2072)
- Update Italian (it-it) translation (#2088)
- Update Polish (pl) translation (#1982)
- Update Polish (pl) translation (#2070)
- Update Polish (pl) translation (#2098)
- Update Polish (pl) translation (#2118)
- Update Polish (pl) translation, change ANSI escape codes to tags (#2012)
- Update Russian (ru-RU) translation (#2120)
- Various Dutch translation updates (#2016)
"},{"location":"releases/release-notes/0.80.0/#documentation-updates","title":"Documentation updates","text":"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.
"},{"location":"releases/release-notes/0.80.0/#contributors","title":"Contributors","text":"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":"releases/release-notes/0.80.0/#080-commit-authors","title":"0.80 commit authors","text":" - Burrito78
- dreamer
- drfiemost
- FeralChild64
- GranMinigun
- javispedro
- Jkapp76
- johnnovak
- jrdennisoss
- Kappa971
- kcgen
- kklobe
- LowLevelMahn
- memononen
- nemo93
- NicknineTheEagle
- rderooy
- rsribeiro
- tyrells
"},{"location":"releases/release-notes/0.80.0/#080-sponsors","title":"0.80 sponsors","text":"Sponsors who donated more than 100 USD per month to the project:
- Antti Peltola (1000 USD during the period)
- Wengier Wu (380 USD during the period)
"},{"location":"releases/release-notes/0.80.0/#080-backers","title":"0.80 backers","text":"Backers who donated more than 5 USD per month to the project:
- Burrito78
- Hannu Hartikainen
- Hugo Locurcio
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":"releases/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":"releases/release-notes/0.80.1/","title":"0.80.1 release notes","text":"Release date: 2023-01-06
"},{"location":"releases/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":"releases/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":"releases/release-notes/0.80.1/#downloads","title":"Downloads","text":" - Linux (or Steam on Linux)
- Windows
- macOS
"},{"location":"releases/release-notes/0.80.1/#upgrade-your-configuration-file","title":"Upgrade your configuration file","text":" - Launch the new release.
- At the
Z:\\> prompt, run config -wc to write the new configuration file.
Note
- Existing settings will be retained, but extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.80.1/#bug-and-regression-fixes","title":"Bug and regression fixes","text":" -
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.
Full PR list of bug and regression fixes - Add Linux ARM CI jobs using containerized cross-compiler (#2193)
- Add missing Windows 11 features to MORE command (#2142)
- Bump Coverity to v2022.06 (#2162)
- Bump actions/cache from 3.2.0 to 3.2.1 (#2152)
- Bump actions/cache from 3.2.1 to 3.2.2 (#2165)
- Center mouse cursor before releasing it (#2173)
- Change mouse capture default to \u2018onclick\u2019 (#2172)
- Check CLI arguments for directories using non-invasive test (#2148)
- Cleanup some minor Coverity issues (#2179)
- Fix CGA mono and Hercules intro banners (#2190)
- Fix imprecise help string in MORE command (#2161)
- Fix logging of some pre-EGA modes (#2187)
- Fix remaining two CWEs involving unchecked return values (#2150)
- Fix slirp/ne2000 warnings (#2182)
- Improve logging of the current display mode (#2168)
- Improve seamless mouse configuration entry description, mention the touchscreen (#2163)
- Make the xinput2 library optional for ManyMouse (#2155)
- Use extended ASCII check in MORE command (#2195)
- Use presence of desktop environment in mouse capture states (#2181)
"},{"location":"releases/release-notes/0.80.1/#translation-improvements","title":"Translation improvements","text":"This maintenance release includes updates to the Dutch, Italian, and Polish translations.
Full PR list of translation improvements - Update Dutch (nl) translation of MORE (#2164)
- Update Italian (it-it) translation (#2166)
- Update Polish (pl) translation (#2159)
- Update Polish (pl) translation (#2186)
- Update Polish (pl) translation, for 0.80.x only (#2194)
"},{"location":"releases/release-notes/0.80.1/#contributors","title":"Contributors","text":"The following commit authors, sponsors, supporters, and backers invested their time or funds into this maintenance release. Thank you!
"},{"location":"releases/release-notes/0.80.1/#commit-authors","title":"Commit authors","text":"In alphabetic order:
- FeralChild64
- johnnovak
- Kappa971
- kcgen
- NicknineTheEagle
- rderooy
- shermp
- ThomasEricB
"},{"location":"releases/release-notes/0.80.1/#sponsors","title":"Sponsors","text":"Sponsors who donated 100+ USD per month to the project:
"},{"location":"releases/release-notes/0.80.1/#backers","title":"Backers","text":"Backers who donated 5+ USD per month to the project:
- Burrito78
- Hannu Hartikainen
- Hugo Locurcio
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":"releases/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":"releases/release-notes/0.81.0/","title":"0.81.0 release notes","text":"Release date: 2024-02-14
"},{"location":"releases/release-notes/0.81.0/#summary","title":"Summary","text":"Hey DOS enthusiasts! We are proud to present DOSBox Staging 0.81.0 to you, a rather substantial release containing a large number of exciting new features and improvements!
For the first time in history, DOSBox comes with built-in authentic CRT monitor emulation that just works out-of-the-box without any manual configuration required. The VGA code has been overhauled, shortcuts and simplifications have been removed, and now we\u2019re defaulting to accurate per-scanline emulation and double scanning in all VGA, SVGA, and VESA modes. Integer scaling options have been added, it\u2019s now possible to stretch the image to fullscreen, force any arbitrary aspect ratio, or even emulate the horizontal and vertical stretch controls of CRT monitors in real-time. Screenshots have been made aspect ratio correct by default, and image capturing has become multi-threaded, so it no longer causes audio hiccups and micro-pauses. Video capturing has been made about three times more performant. Oh, almost forgot: we\u2019ve also added 3dfx Voodoo 1 support for the fans of those late 90s 3D DOS games!
Well, that\u2019s just the video side of things. We\u2019ve added support for the ultra-rare IBM Music Feature Card, dealing with Roland MT-32 ROMs has become much easier, plus we\u2019ve made numerous MIDI-related improvements as well. Not to mention all the mouse and joystick enhancements and fixes, the addition of a few missing DOS commands, improved filesystem integration, fixing some long-standing annoying shortcomings of the FPU emulation in non-x86 builds, taking localisation support to the next level, and the list just goes on and on\u2026
Read on to learn more!
"},{"location":"releases/release-notes/0.81.0/#how-to-upgrade","title":"How to upgrade","text":"Start by downloading the latest version, then make sure to upgrade your primary configuration as described below.
"},{"location":"releases/release-notes/0.81.0/#downloads","title":"Downloads","text":""},{"location":"releases/release-notes/0.81.0/#upgrading-your-primary-configuration","title":"Upgrading your primary configuration","text":"Since config settings might be renamed, altered, or deprecated between releases, it\u2019s best to let DOSBox Staging write the new default primary config on the first launch, then reapply your old settings manually.
Start by backing up your existing primary config. This is where to find it on each platform:
Windows C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox-staging.conf macOS ~/Library/Preferences/DOSBox/dosbox-staging.conf Linux ~/.config/dosbox/dosbox-staging.conf You can also execute DOSBox Staging with the --printconf option to have the location of the primary config printed to your console.
After backing up the existing primary config, simply start the new version\u2014a new dosbox-staging.conf will be written containing the new defaults and updated setting descriptions.
Portable mode notes
In portable mode, dosbox-staging.conf resides in the same folder as your DOSBox Staging executable. The migration steps for portable mode users are as follows:
- Unpack the new version into a new folder (this is important).
- Create a new empty
dosbox-staging.conf file in the new folder to enable portable mode. - Launch the new version.
DOSBox Staging will write the new defaults to the empty dosbox-staging.conf file. After this, you carry over your settings from the old primary config manually.
"},{"location":"releases/release-notes/0.81.0/#after-upgrading","title":"After upgrading","text":"Look out for deprecation warnings in the logs (in yellow/orange colour) and update your configs accordingly.
"},{"location":"releases/release-notes/0.81.0/#new-getting-started-guide","title":"New Getting Started guide","text":"Due to popular demand, we\u2019ve added a new Getting Started guide to the front page. The guide will teach you how to set up your own DOSBox Staging environment from scratch through easy-to-follow instructions with lots of pretty pictures. It adopts a learn-by-doing approach to ensure you\u2019ll have fun while setting up famous classic DOS games.
Although it\u2019s primarily intended for beginners, we guarantee even our most experienced long-time users will learn a few tricks from it!
"},{"location":"releases/release-notes/0.81.0/#graphics","title":"Graphics","text":""},{"location":"releases/release-notes/0.81.0/#authentic-adaptive-crt-emulation","title":"Authentic adaptive CRT emulation","text":"We are happy to announce that we\u2019ve removed all CRT shaders previously bundled with our releases.
Every single one of them.
What the @^$*%#!!!?? Have these guys gone mad??!
The reason for removing them is that they got replaced with something far better: a set of no less than 24 CRT shaders tweaked to perfection to emulate the glorious CRT monitors of the past, including authentic recreations of Hercules, CGA, monochrome CGA, composite CGA, EGA, and VGA monitors.
24 new CRT shaders sound a lot\u2014how will someone not intimately familiar with CRT monitor technology and PC history know which is the best for a particular game? Well, the good news is you don\u2019t need to know\u2014DOSBox Staging will automatically pick the most appropriate shader based on the current DOS video mode and viewport resolution. High-DPI and displays from 720p to 4K resolutions are fully supported, and absolutely no manual configuration is required!
The following magic glshader options have been introduced:
-
crt-auto \u2014 This is the new default\u2014an adaptive CRT shader that prioritises developer intent and how people experienced the game at the time of release. This means VGA games will be double-scanned, like on a real VGA monitor, EGA games will appear single-scanned with \u201cfat scanlines\u201d, and so on, regardless of the machine setting.
-
crt-auto-machine \u2014 This one emulates a fixed CRT monitor based on your machine setting. So CGA and EGA modes on a VGA machine will always appear double-scanned with big chunky pixels, just like on a real VGA adapter and monitor.
-
crt-auto-arcade \u2014 This fantasy option does not exist in real life, but it can be a lot of fun! It emulates a 15 kHz arcade or home computer monitor with thick scanlines in low-resolution modes. Perfect for playing DOS VGA ports of Amiga and Atari ST games to experience them with MT-32 or SC-55 sound from a strange parallel universe! \ud83d\ude0e
Adaptive CRT shaders work in tandem with the new integer scaling feature to achieve the most optimal results. The default auto setting for integer_scaling auto-enables vertical integer scaling for the adaptive CRT shaders; this avoids unwanted interference patterns that can result from non-integer vertical scaling ratios.
Here are the shaders in action at 4K resolution (make sure to click on the zoomed-in images if the cursor turns into a magnifying glass to view them at 100% magnification):
Gods \u2014 320\u00d7200 VGA
Ultima Underworld: The Stygian Abyss \u2014320\u00d7200 VGA
Celtic Tales: Balor of the Evil Eye \u2014 640\u00d7480 VGA
Dark Seed \u2014 640\u00d7350 EGA
The Secret of Monkey Island \u2014 320\u00d7200 EGA
Space Quest III: The Pirates of Pestulon \u2014 320\u00d7200 EGA
Wizardry: Proving Grounds of the Mad Overlord \u2014 320\u00d7200 CGA
Smoker by Fairfax \u2014320\u00d7200 15kHz \u201carcade\u201d shader
Zak McKracken and the Alien Mindbenders \u2014320\u00d7200 CGA composite
Starblade \u2014 720\u00d7348 Hercules
If you don\u2019t like CRT shaders, no problem\u2014simply set glshader to sharp in your config to regain your sharp little rectangles back. Naturally, you can continue to use regular GLSL shaders like before. The deprecated CRT shaders are still available as a separate download, should you ever need them.
The adaptive shaders are largely based on one of Hyllian\u2019s excellent CRT shaders, so big thanks to him for laying a solid foundation for this feature.
Why were the old CRT shaders removed?
One problem with the previously bundled CRT shaders was that they lacked proper documentation, so it wasn\u2019t clear which shader was meant for what monitor resolution (some were tuned for 1080p, some for 4K, etc.) Moreover, most were designed to emulate arcade monitors or TV sets from the 80s and early 90s; these displays had very different characteristics than the much higher quality PC monitors. Because of all this, many people were rather unimpressed by them and gave up on CRT shaders altogether as a result.
"},{"location":"releases/release-notes/0.81.0/#accurate-vga-emulation","title":"Accurate VGA emulation","text":"Previously, DOSBox rendered the emulated VGA output without double scanning, and only in quarter-frame chunks. These optimisation steps were necessary 20 years ago, but now we\u2019re doing proper double scanning and accurate per-scanline rendering in all VGA, SVGA, and VESA video modes. It turns out this only causes a ~7% performance drop on modern hardware in benchmarks, which is not much for such a significant improvement.
Double scanning and per-scanline rendering were available via the special vgaonly machine type before, but that was incompatible with VESA modes and it truncated the 18-bit VGA DAC colour output to 16-bits only, causing banding in certain scenes. We no longer do that either\u2014VGA output is now always rendered at full 18-bit precision.
We use 9\u00d716 fonts on all emulated VGA adapters now which is how most people remember VGA text modes. You can still force 8\u00d716 fonts on VGA by enabling the new vga_8dot_font setting.
These improvements absorb the benefits of vgaonly into the base VGA emulation, making the vgaonly machine type unnecessary, so it has been deprecated (it\u2019s still recognised as an alias for svga_paradise for backward compatibility).
Additionally, all CGA, PCjr, and Tandy text modes are now properly single-scanned when using their respective machine types. A few CGA, PCjr, and Tandy graphics modes appeared with the incorrect aspect ratio before; these have all been fixed up.
The logging of video modes has become a lot more accurate; now we\u2019re consistently logging the video standard the mode first appeared in (e.g., CGA modes are always logged as CGA, regardless of the emulated display adapter in use), and the logged pixel aspect ratios are now always correct.
"},{"location":"releases/release-notes/0.81.0/#3dfx-voodoo-1-emulation","title":"3dfx Voodoo 1 emulation","text":"Aaron Giles\u2019 3dfx Voodoo emulation originally written for the MAME project has finally found its way into Staging. During its journey, it has picked up a few enhancements, namely a few changes by kekko for the DOSBox integration, plus some multi-threading improvements by Bernhard Schelling (also known as psyraven).
We\u2019ve added support for emulating a Voodoo 1 board with either a 2 MB Frame Buffer Interface (FBI) and one 2 MB Texture Mapping Unit (TMU), or a 4 MB FBI + dual 2x4 MB TMU configuration.
The default refresh rate for the Voodoo is 60 Hz, but it\u2019s possible to force any custom refresh rate via dos_rate.
Please refer to the new [voodoo] config section to learn more.
Low vs high-level emulation
Note this is purely software-based low-level emulation; we\u2019re emulating the 3dfx Voodoo 1 hardware accurately in software, which requires a beefy host CPU. We don\u2019t support high-level emulation where the Glide API calls are transformed and passed through to modern 3D APIs for the actual rendering (e.g., OpenGL, Vulkan, Direct3D, etc.)
"},{"location":"releases/release-notes/0.81.0/#new-integer-scaling-modes","title":"New integer scaling modes","text":"A new integer_scaling setting has been introduced to constrain the horizontal or vertical scaling factor to integer values when upscaling the image to fit it into the viewport. For example, you can enable vertical integer scaling now with the following config:
[render]\ninteger_scaling = vertical\n
The correct aspect ratio will always be maintained, so in this case, the horizontal scaling factor might become fractional. With the sharp shader this is not a problem as the \u201cinterpolation band\u201d can only be up to 1 pixel wide at the two sides of the pixels\u2014still plenty sharp, especially on 1440p or 4K. Then with the CRT shaders, non-integer horizontal scaling matters even less; it\u2019s practically a non-issue.
integer_scaling is set to auto by default which only enables vertical integer scaling for the adaptive CRT emulation, otherwise, it\u2019s disabled.
This replaces the so-called \u201cpixel-perfect mode\u201d (openglpp and texturepp output modes) which prioritised 100% sharp pixels at the expense of aspect ratio correctness. That feature had been the source of endless confusion even among experienced users as most of the time it could only approximate the correct aspect ratio, and even that varied semi-randomly based on the current viewport size and monitor resolution. Our reasons for removing it are documented in detail here.
"},{"location":"releases/release-notes/0.81.0/#aspect-ratio-correct-image-captures","title":"Aspect ratio correct image captures","text":"Previously, even if you had aspect ratio correction enabled, the captured screenshots always contained the raw, non-corrected image. This has been flipped around: the new default is capturing images in the same aspect ratio that you see on your screen.
Taking raw and rendered (post-shader) screenshots continues to be an option, of course. The following three image capture formats have been introduced:
-
upscaled \u2014 The image is captured in the same aspect ratio you see on the screen. Upscaled captures always use sharp pixels, regardless of the shader in use.
-
rendered \u2014 Capture the post-rendered, post-shader image\u2014an exact pixel-by-pixel replica of what you see on the screen.
-
raw \u2014 Capture the raw image; this always results in square pixels. So for 320\u00d7200 VGA or EGA content, you\u2019ll always get a 320\u00d7200 PNG file, no matter what.
You can configure the capture formats of the default screenshot action with the following setting:
[capture]\ndefault_image_capture_formats = upscaled raw\n
With this setting, two PNG files will be written in raw and upscaled formats whenever you press the Ctrl+F5 image capture hotkey (Cmd+F5 on macOS).
Keybindings for taking single screenshots in specific formats are also available.
Interpolation in upscaled mode
The image is integer or bilinear-sharp upscaled to around 1200 pixels of vertical resolution in the new upscaled capture mode. For example:
- 320x200 content is upscaled to 1600x1200 (5:6 integer scaling)
- 640x480 to 1920x1440 (3:3 integer scaling)
- 640x350 to 1400x1050 (3x vertical and 2.1875x horizontal scaling)
The resulting PNG files are only about 30% bigger than raw screenshots on average. This is a rather small price to pay for aspect ratio correctness.
Aspect ratio correctness, 2023 edition
Fact: most 320\u00d7200 and similar low-resolution DOS games absolutely need aspect ratio correction enabled to appear correctly. While some games benefit from forcing square pixels, these only account for about 1-2% of the total DOS gaming catalogue. That\u2019s the reason why DOSBox Staging performs aspect ratio correction out-of-the-box.
The sad reality of the situation today is that the vast majority of 320\u00d7200 DOS games are displayed in the wrong aspect ratio with square pixels on various websites and video-sharing services. Emulators that don\u2019t default to aspect ratio correct output and screen captures have undoubtedly contributed to this widespread problem. Aspect ratio correct screen captures by default is our attempt to play our part in remedying the situation, and hopefully reversing it with time.
Raw capture breaking changes
Previously, raw image captures width or height doubled certain DOS video modes. There wasn\u2019t much rhyme or reason to it. Now raw captures always contain the actual emulated DOS framebuffer-level image (e.g., 320\u00d7200 modes get captured as 320\u00d7200 PNG files, regardless of any other settings).
The only exceptions are the composite CGA, PCjr, and Tandy modes. These modes are a bit special as internally they\u2019re rendered width-doubled to have enough horizontal resolution for representing composite artifacts. Therefore, we write raw image captures of composite modes width-doubled to retain all rendered information (e.g., the 640\u00d7200 composite CGA mode will result in a 1280\u00d7200 raw image, which might be surprising at first, but it\u2019s intended and correct behaviour).
"},{"location":"releases/release-notes/0.81.0/#supercharged-image-and-video-capturing","title":"Supercharged image and video capturing","text":"The optimised zlib-ng library has been added to mitigate the video capturing performance hit incurred by our new more accurate VGA emulation approach compared to 0.80.1. In fact, zlib-ng not only makes up the difference but speeds video capturing up by another factor of three (!) versus 0.80.1! This makes a huge difference on older CPUs, but even on fast modern machines, you can now capture videos at higher resolutions without glitches.
Additionally, image capturing is now being performed in multiple background threads. This eliminates emulation micro-pauses and sound glitches even when rapidly spamming the screenshot hotkey. This was a problem even on fast machines with rendered post-shader captures at 4K resolution.
"},{"location":"releases/release-notes/0.81.0/#aspect-ratio-and-viewport-enhancements","title":"Aspect ratio and viewport enhancements","text":"Stretching the image to completely fill the screen has been an often requested feature (e.g., to play text adventures without black bars on the sides). Now we\u2019re giving you not only that but an entirely new mechanism to apply arbitrary aspect ratios, zoom into the DOS content, and even emulate the horizontal and vertical stretch controls of CRT monitors of yore!
The key element of the feature is the new aspect = stretch mode which stretches the image to the extents of the viewport. For example, to make a game completely fill the screen, use the following config:
[sdl]\nfullscreen = on\n\n[render]\naspect = stretch\nviewport = fit\ninteger_scaling = off\n
The second piece of the puzzle is the new relative mode added to the viewport setting (viewport_resolution has been renamed to viewport and moved to the [render] section). In relative mode, the viewport is a 4:3 aspect ratio rectangle fit into the window or screen as the starting point, which is then scaled by the specified horizontal and vertical stretch factors. The resulting viewport is allowed to extend beyond the edges of the window or the screen, so this can be used to \u201czoom\u201d into the image while forcing arbitrary aspect ratios.
For example, you can aspect ratio correct lazy Hercules conversions that just reused the EGA/VGA assets and make them fill the screen better by zooming in a little. The following example illustrates this in Prince of Persia in Hercules mode:
[render]\naspect = stretch\nviewport = relative 112% 173%\ninteger_scaling = off\n
You can use the Stretch Axis, Inc Stretch, and Dec Stretch hotkey actions to set the stretching in real-time (unbound by default). The current viewport setting is logged, so you can simply copy it to your config.
Prince of Persia without any custom stretching
Prince of Persia with aspect = stretch and viewport = relative 112% 173%
"},{"location":"releases/release-notes/0.81.0/#fix-black-vertical-bars-video-corruption-issue","title":"Fix \u201cblack vertical bars\u201d video corruption issue","text":"This is a fix for the \u201cblack vertical bars\u201d video corruption issue seen on a few late 90s games and demos that require Pentium CPUs. Due to some fairly intricate technical details to do with 80-bit x87 FPU emulation, the issue does not manifest in Intel builds, but it does in all non-Intel builds when using the non-dynamic cores.
A non-exhaustive list of affected programs:
Games
- Carmageddon (1997)
- Motor Mash (1997)
- Peter Sampras Tennis (1997)
Demos
- Sunflower by Pulse (1997)
- Multikolor by kolor (1997)
- toontown by kolor (1997)
Multikolor by kolor \u2014 Black vertical bars issue
Multikolor by kolor \u2014 After the fix
"},{"location":"releases/release-notes/0.81.0/#new-deinterlacing-shader-for-fmv-games","title":"New deinterlacing shader for FMV games","text":"Schlocky 90s FMV titles are the guilty pleasure of every true retro-gamer (we\u2019re no different, so zero judging!) Unfortunately, many of these games are plagued by a weird trick: the video footage is often displayed with alternating black \u201cinterlace lines\u201d. This just doesn\u2019t look very good on modern ultra-sharp flat screens, and upscaling such content with non-integer scaling ratios often causes very ugly interpolation artifacts.
To restore cosmic balance, we\u2019ve introduced a pair of \u201cdeinterlacing\u201d shaders, building upon the work of Ove Kaaven:
-
misc/fixvideo \u2014 This intelligently doubles scanlines that have a black line beneath them. Works well with non-integer scaling ratios.
-
misc/fixvideo-scanlines \u2014 Similar to the first one, but this retains a subtle scanline look to improve the \u201cperceptual resolution\u201d of the video footage. This one absolutely needs vertical integer scaling enabled!
Now you can enjoy your 90s FMV shlock in its full gory glory!
Angel Devoid: Face of the Enemy \u2014 Raw output
With the misc/fixvideo shader
With the misc/fixvideo-scanline shader
"},{"location":"releases/release-notes/0.81.0/#other-graphics-related-changes","title":"Other graphics-related changes","text":" -
OpenGL Pixel Buffer Object (PBO) support was dropped to enhance performance and efficiency. This will result in reduced energy use, reduced thermal load, and significantly improved performance on single-board computers, Intel HD Graphics, and AMD APUs.
-
The keymapper now supports high DPI screens.
-
We\u2019ve added support for disabling the screen via the clocking mode register. This fixes some visual glitches in Alien Carnage.
-
A new interpolation/catmull-rom shader has been added. This implements an upscaling method that looks better than the bilinear interpolation option you get with the none shader.
-
Various monochrome mode fixes & improvements affecting Hercules and monochrome CGA emulation have been made. Most notably, the manual \u201cbright mode\u201d hotkey to toggle between the two monochrome palette variants has been removed. Now the appropriate palette is auto-selected based on whether we\u2019re in a text or graphics mode.
-
A corner case delayed display regression was fixed in VFR presentation mode. The presentation mode auto-selection criteria have also been refined to achieve optimal results with a wider range of monitor, driver, and operating system combinations.
-
The legacy surface output mode has been removed. The new fallback option is the texture output mode that automatically selects the best available rendering backend via SDL (a purely CPU-based non-accelerated backend is available too). The preferred and recommended output mode is still OpenGL, as it always has been.
-
Fixed a regression where some colours had a very subtle greenish tint on emulated VGA adapters. In practice, this was only noticeable on dark neutral grey colours.
-
Reloading shaders at runtime via the hotkey action now works a lot more reliably.
-
Nearest-neighbour output modes aren\u2019t treated any differently anymore when determining the default window size.
-
sRGB GLSL pragmas now work correctly. Somewhat embarrassingly, the sharp shader was advertised to be gamma-correct more than a year ago, but sadly that was never the case\u2014until this fix.
-
Introduction of the use_npot_texture GLSL pragma to request non-power-of-two-texture.
-
Introduction of the force_single_scan and force_no_pixel_doubling GLSL pragmas to force no line doubling and no pixel doubling in VGA modes, respectively. This might come in handy for certain shaders that need to work on the \u201craw\u201d pixel data, such as upscalers.
-
We\u2019ve changed the VESA BIOS branding to DOSBox Staging (because we can )
Full PR list of graphics-related changes - (S)VGA/VESA square pixel mode fix/cleanup (#2583)
- Adaptive CRT shader compatibility fixes for really old GPUs (#3172)
- Adaptive shader fixes (#2866)
- Add
crt-auto-arcade-sharp adaptive CRT shader (#3083) - Add
misc/fixvideo.glsl OpenGL shader (#2442) - Add crt/aperture.mono shader variant (#2393)
- Add deinterlacing shader variants (#3200)
- Add new glshader/misc dir to the Meson build (#2443)
- Add support for disabling screen via the clocking mode register, fixes #2838 (#2842)
- Always log OpenGL shader and program info logs if they\u2019re non-empty (#3121)
- Aspect ratio and viewport improvements (#3124)
- Authentic adaptive CRT shaders (#2777)
- Auto-disable the integer scaling feature if the image is smaller than\u2026 (#2588)
- Capture modularisation/cleanup (#2451)
- Change VESA BIOS branding to \u2018DOSBox Staging\u2019 (#2712)
- Clean up OpenGL attribute init (#3111)
- De-SDL voodoo threading (#2568)
- Deprecate machine type
vgaonly (#2398) - Disable framebuffer acceleration for debugger (#2477)
- Don\u2019t auto-disable OpenGL for debugger-enabled builds on Linux (#2480)
- Don\u2019t restrict text video modes to the VFR presentation mode (#2286)
- Double-scanning support for VESA modes, accurate mode change logging,
vga_draw.cpp rework & many other improvements (#2654) - Drop OpenGL PBO support (#3099)
- Enable vsync by default (#2373)
- Fix \u201c-fullscreen\u201d argument on Wayland (#2688)
- Fix CGA composite regression (#2662)
- Fix Tandy support for Ninja (1986) (#2225)
- Fix VESA 256 / 8-bit in Windows 3.1 (#2569)
- Fix a couple aspect ratios (#2612)
- Fix a couple issues from the
vgaonly PR (#2424) - Fix a crash when using
glshader = crt-auto-machine (#3077) - Fix a window size regression on macOS (#2374)
- Fix altered shader pragmas not taking an effect when reloading the shader (#2736)
- Fix comment describing BGRX8888 PixelFormat (#2766)
- Fix compilation failures on *BSD and colour rendering on big-endian platforms (#3155)
- Fix const issue writing a png with png12 (#2740)
- Fix double-scanning & pixel-doubling handling in
openglnb output mode (#3092) - Fix fallback shader scaling for adaptive CRT shaders (#2840)
- Fix flicker in some games due to mouse driver breaking double buffering (#2867)
- Fix image capture indices always starting from 1 (#2656)
- Fix incorrect pixel aspect ratio calculation for all text modes (#2570)
- Fix infinite recursion problem at startup on Pop OS 22.04 and SDL 2.0.20 (#3209)
- Fix invalid default config value for voodoo_memsize (#2744)
- Fix mapper screen for high dpi (#2708)
- Fix raw image & video capture for 160x200 16-colour Tandy/PCjr modes (#3185)
- Fix raw video capture so it always writes non-double-scanned raw output (#3177)
- Fix regression in Build Engine games (3Dfx mode) (#2432)
- Fix regression in VGA draw\u2019s wrapped line case (#2441)
- Fix regression in palettized VGA line draw function (#2491)
- Fix regressions in some video modes\u2019 aspect and line-counts (#2445)
- Fix sRGB GLSL pragmas (#2665)
- Fix spelling mistakes in \u2018voodoo_*\u2019 config descriptions (#2859)
- Fix the aspect ratio of 40-column 00h and 01h BIOS text modes (#2852)
- Fix the calculation of vga.draw.lines_scaled when double scanning (#2806)
- Fix vertical bars due to FILD/FIST memcpy trick (#3151)
- Fixes and cleanup of PCI BIOS (#2731)
- Force OpenGL renderer backend for keymapper (#2768)
- Give Voodoo a gentle push to get it passing CI (#2710)
- Ignore extensions when finding highest capture index (#2946)
- Image capture enhancements mega-PR \u2014 Godzilla Edition\u00a9\u00ae\u2122 \ud83e\udd96 (#2503)
- Implement Voodoo usability fixes (#3103)
- Implement integer viewport scaling (#2456)
- Improve the \u201cmode 1\u201d deinterlace method (#3192)
- Include low width resolution in VGA scanning citeria (#2582)
- Introduce PixelFormat enum (#2735)
- Let the VESA 8-bit mode draw lines from the DAC palette (#2494)
- Limit consecutive duplicate frames in VFR presentation mode (#3004)
- Make triangle_worker members threadsafe (#2434)
- Minor voodoo performance tweaks (#2435)
- Monochrome mode fixes & improvements (#2769)
- Only capture the visible image in rendered image capture mode (#3194)
- Perform console cursor and text calls via interrupt (#3113)
- Port Voodoo support with multi-threaded software backend (#2410)
- Present VFR duplicate frames on a tempo (#2379)
- Refine when
presentation mode = auto uses throttled mode (#2818) - Reload shader fixes (#2730)
- Remove scan and pixel doubling config settings (#2728)
- Rename PixelFormat enum members BGR555 and BGR565 to RGB555 and RGB565 (#2823)
- Rendering related refactorings (#2739)
- Replace busy-wait atomic bool goto logic (#2545)
- Resize VGA within half the current frame-time (#2510) (#2528)
- Restore authentic text mode pixel aspect ratio calculation (#2625)
- Rework \u201cEGA mode with VGA palette\u201d CRT shader auto-switching (#3354)
- Retire surface output (#2780)
- Simplify and improve
presentation_mode handling (#2690) - Simplify double-scan criteria and let users
'force_vga_single_scan' w/ conf option (#2428) - Update Catmull-Rom shader (#2786)
- Use zlib-ng in local builds and CI releases (#3202)
- Video related refactorings (#2808)
- Window sizing improvements & aspect ratio related cleanup (#2749)
crt-auto should auto-switch to VGA shaders in EGA modes with 18-bit VGA palettes (#2819)sdlmain improvements (#3123)
"},{"location":"releases/release-notes/0.81.0/#sound","title":"Sound","text":""},{"location":"releases/release-notes/0.81.0/#ibm-music-feature-card-support","title":"IBM Music Feature Card support","text":"The IBM Music Feature Card is a rare and expensive sound card from the late 1980s. It is mainly supported by early Sierra SCI games and a few others, like Silpheed. Thanks to Loris Chiocca for authoring this originally! See the [imfc] section for further details.
We highly recommend checking out this excellent blog post to learn more about the interesting history of the card.
Game Audio example Quest for Glory: So You Want to Be a Hero Your browser does not support the audio element. The Colonel\u2019s Bequest \u2013 Intro 1 Your browser does not support the audio element. The Colonel\u2019s Bequest \u2013 Intro 2 Your browser does not support the audio element. The Colonel\u2019s Bequest \u2013 Intro 3 Your browser does not support the audio element."},{"location":"releases/release-notes/0.81.0/#roland-mt-32-rom-handling-improvements","title":"Roland MT-32 ROM handling improvements","text":"We have moved from the fiddly and error-prone filename-based Roland MT-32/CM-32L ROM lookup mechanism to checksum-based detection. It\u2019s no longer necessary to get the ROM filenames right; you can chuck all of them into your mt32-roms folder\u2014DOSBox Staging will do the rest! Valid ROMs are identified by their checksums (hashes) at runtime. Both interleaved (mt32pi style) and non-interleaved (MAME style) ROM files are supported.
As a result, the old \u201cversioned\u201d vs \u201cunversioned\u201d ROM differentiation doesn\u2019t make sense anymore. The mt32 and cm32l model types now behave differently: mt32 now selects the first available MT-32 ROM, and cm32l the first available CM-32L ROM (in priority order). Similarly, the mt32_old and mt32_new aliases are not tied to specific version numbers anymore but pick the best available ROMs.
The revised ROM selection method should be backward compatible with the most common use cases\u2014in fact, the new method should generally result in better matches, assuming the same ROM set.
Support for the rare 2.06 and 2.07 MT-32 ROMs and the CM-32LN 1.00 has also been added.
Lastly, we\u2019ve improved the output of the MIXER /LISTMIDI command to make the display of available ROMs and the active ROM much clearer.
Output of the improved MIXER /LISTMIDI command
"},{"location":"releases/release-notes/0.81.0/#fluidsynth-fixes","title":"FluidSynth fixes","text":"The Roland SC-55 and FluidSynth handle MIDI portamento messages (pitch glides between consecutive notes) very differently. As the rather unique Roland SC-55 portamento cannot be emulated with FluidSynth, music written for the SC-55 that uses it might sound weirdly out of tune on FluidSynth (e.g., the level 8 music of Descent).
All in all, it\u2019s best not to send MIDI portamento messages to FluidSynth at all to avoid the problem completely. The resulting sound is a lot closer to the Roland SC-55\u2019s output.
Additionally, a rather strange sound stage issue has also been fixed by upgrading to the latest FluidSynth library. The panning of some instruments was off-centre, slightly leaning to the left. The problem could be fairly subtle or quite apparent depending on the SoundFont in use, the musical score, and the instruments being played. You can hear it to varying degrees in the \u201cbuggy\u201d audio recording below recorded using the previous 0.80.1 DOSBox Staging version.
Descent \u2013 Level 8 (SC-55) \u00b9 Your browser does not support the audio element. Descent \u2013 Level 8 (FluidSynth buggy) \u00b2 Your browser does not support the audio element. Descent \u2013 Level 8 (FluidSynth fixed) \u00b3 Your browser does not support the audio element.
\u00b9 Roland Sound Canvas VA in SC-55 mode was used for the recording \u00b2 DOSBox Staging v0.80.1 (previous version) with the GeneralUser GS SoundFont \u00b3 Current DOSBox Staging version with the GeneralUser GS SoundFont
"},{"location":"releases/release-notes/0.81.0/#improved-mixer-command","title":"Improved MIXER command","text":"The MIXER command has been recreated from the ground up to make it a lot more robust and less confusing to use. The main highlights are as follows:
-
The MIXER command no longer accepts slightly incorrect input; command parsing is now strict and we\u2019re displaying error messages for invalid commands. These messages try to guide the users to correct their mistakes.
-
MIXER command handling is now \u201ctransactional\u201d\u2014if there is a single error in a list of multiple commands, no command is executed but an error for the first problem is raised. This leads to less confusing and more deterministic overall behaviour.
-
Mixer channels now retain their settings when a channel gets deleted and then re-created later (e.g., by setting sbtype none followed by sbtype sbpro1).
-
The CMS mixer channel is no longer renamed to GAMEBLASTER when sbtype is set to gb.
"},{"location":"releases/release-notes/0.81.0/#midi-muting-improvements","title":"MIDI muting improvements","text":"Previously, when muting the audio, all MIDI devices were sent Note Off messages, which was problematic with long-held notes in musical scores. You\u2019d get missing notes after unmuting, and the slower the tempo, the more annoying this problem would become.
Muting has been 100% fixed both for the internal Roland MT-32 and FluidSynth MIDI synthesisers and also for external MIDI devices. Technically, we keep feeding external devices with MIDI events in the muted state, but we set all channel volumes to zero when muting, and then restore the volumes when unmuting.
Also, we\u2019re now correctly muting the MIDI output when mute_when_inactive or pause_when_inactive is enabled.
"},{"location":"releases/release-notes/0.81.0/#sanitise-midi-output-roland-ra-50-compatibility","title":"Sanitise MIDI output & Roland RA-50 compatibility","text":"The MIDI drivers of many games don\u2019t fully conform to the MIDI standard, which makes editing the MIDI recordings of these games very error-prone and cumbersome in MIDI sequencers, often resulting in hanging or missing notes.
Now DOSBox Staging corrects the MIDI output of such games by default. This results in no audible difference; it only affects the representation of the MIDI data. Specifically, we\u2019re emitting Note Off messages for all active notes when an All Notes Off message is encountered (this is mandated by the MIDI specification, but many games ignore that). There are other Channel Mode Messages that result in an implicit All Notes Off message; these are handled correctly as well.
This incidentally also fixes the infamous hanging notes issue with the Roland RA-50 external MIDI module (the module does not implement the All Notes Off MIDI message).
A new raw_midi_output setting has been introduced to disable this \u201csanitisation\u201d of MIDI data. That might come in handy if you need to leave the raw MIDI stream unaltered (e.g., when working with music applications, or when debugging MIDI issues).
"},{"location":"releases/release-notes/0.81.0/#optionally-fade-out-hanging-notes-on-tandy-opl","title":"Optionally fade out hanging notes on Tandy & OPL","text":"Some games like Bard\u2019s Tale Construction Set and California Games II suffer from hanging note issues where the notes are not always properly terminated at the end of a musical piece. We\u2019ve introduced an option to fade out the OPL or Tandy sound output after the last IO port write to these audio devices to remedy the situation. See the documentation of the opl_fadeout and tandy_fadeout settings for further details.
"},{"location":"releases/release-notes/0.81.0/#cd-audio-support-on-linux-for-physical-cd-roms","title":"CD Audio support on Linux for physical CD-ROMs","text":"CD Audio is now supported on Linux too via ioctls when using physical CD-ROMs. The audio is routed through the DOSBox mixer, each drive having its dedicated mixer channel (CDAUDIO_0 for the first drive, CDAUDIO_1 for the second, and so on).
With this addition, we now support CD Audio on both Windows and Linux for physical media (but on Windows, the CD audio still goes through the OS-level mixer).
"},{"location":"releases/release-notes/0.81.0/#other-sound-related-changes","title":"Other sound-related changes","text":" -
It\u2019s no longer possible to create DMA conflicts by configuring multiple sound devices to use the same DMA channel. In case of a conflict, the last configured or enabled device takes precedence and the other device gets deactivated automatically. The three sound devices that use DMA are the Sound Blaster, the Tandy DAC (the Tandy PSG doesn\u2019t need it), and the Gravis Ultrasound.
-
The crossfeed config setting has been revised; now it works the same way as the chorus setting (it has light, normal, and strong presets; on defaults to normal).
-
Fixed a regression that made the sound effects sound crackly in Duke Nukem 3D when using 44 kHz sample rate on the Gravis Ultrasound.
-
Fixed a Gravis Ultrasound regression where 16-bit samples sounded noisy in some games (e.g., Star Control II and Star Trek: The Next Generation \u2013 A Final Unity).
-
Un-deprecate the per-SoundFont volume scaling as it is useful to reign in overly loud SoundFonts.
-
Ignore speaker-output enable/disable commands on the Sound Blaster 16 (this is how the hardware works). This increases compatibility with some badly coded games, e.g., the digital audio in Monkey Island 2: LeChuck\u2019s Revenge Ultimate Talkie Edition was muted before this fix.
-
CD-ROM seek delays are now emulated to fix the CD audio in a few games. For example, Chasm: The Rift stopped playing the music after about 20 minutes of gameplay without this fix.
-
Fixed a regression where the Sound Blaster 16\u2019s maximum sample rate was erroneously clamped to 45\u2009000 Hz (it can go up to 45\u2009454 Hz on real hardware). This caused the sound to be slightly out of tune in programs that use the maximum sample rate.
-
Fixed a regression that prevented Tandy Sound from being re-configurable at runtime.
Full PR list of sound-related changes - Accumulate GUS frames accross each voice instead of per-sample (#2696) (#2698)
- Add Loris Chiocca\u2019s IBM Music Feature Card (IMFC) patch (#2367)
- Add
iir to the set of MSYS2 packages (#2242) - Add a fade-to-sleep-after-last-port-write feature to the mixer (#3058)
- Always clamp \u2018frames_needed\u2019 to the allowed mix/max range in the mixer (#2843)
- Always clamp
frames_needed to the allowed mix/max range in the mixer (#3217) - Clamp the max Sound Blaster 16 sample rate to 45454 Hz, not 45000 Hz (#2676)
- Cleanup the GUS and SB DMA channels on close (#2585)
- Consistently cast and wrap the mixer\u2019s position (#2745)
- Do not send portamento messages (MIDI CC 5, 65 & 84) to FluidSynth (#2705)
- Don\u2019t rename the CMS mixer channel to GAMEBLASTER when
sbtype is gb (#2228) - Drop volatile members in IMFC and reSIDfp (#2380)
- Extract MIXER command into its own file (#2839)
- Fix MIDI capture (#2707)
- Fix Sound Blaster DMA ADPCM frame count assertion error (#2277)
- Fix a Coverity warning in SDL Sound (#3000)
- Fix a GUS regression when interpolating 16-bit samples (#2576)
- Fix a couple regressions in
main relating to MIDI refactoring (#2541) - Fix description of the
imfc_filter setting (#3205) - Fix duplicate SoundFont listing in mixer /listmidi (#3074)
- Fix spurious directory separators in
mixer /listmidi output (#2383) - Fix state handling of the BIOS\u2019s Tandy DAC callbacks (#3148)
- Fix the priority of the \u201cset decibel volume\u201d MIXER command (#3068)
- Ignore speaker-output enable/disable commands on the SB16 (#3105)
- Implement CD Audio using Linux ioctls (#2675)
- Improve MIDI buffer underrun logging (#2227)
- Let derived CDROM devices asynchronously lag their calls (#2622)
- Let only one device reserve a DMA channel at a time (#2593)
- Link mt32emu statically in the MSYS2 CI release (#2711)
- Load MT-32 ROMs from
romdir using hash matches (#2591) - Lookup MT-32 ROMs using std::filesystem paths (#2387)
- MIDI mute improvements (#2318)
- MIXER command improvements & general mixer enhancements + fixes (#2868)
- Minor string fixes in MIXER command (#3072)
- Mixer refactoring & cleanup (#2787)
- Only process MT-32 debug messages in debug builds (#3100)
- Re-add the SDL Sound assert (third time\u2019s a charm?) (#3006)
- Re-initialize the BIOS DAC callbacks on SB and Tandy changes (#3142)
- Refill the SB audio channel when DMA reaches terminal count (#233) (#2614)
- Rework the MT-32/CM-32L ROM lookup and
MIXER /LISTMIDI improvements (#3011) - Sanitise raw MIDI output by default & add
raw_midi_output config option (#2308) - Setup the BIOS Tandy DAC only after critical BIOS features are setup first (#3199)
- Sync Nuked-OPL3 with upstream (#3015)
- Sync YM1728B_emu with upstream (#3021)
- Sync fluidsynth, glib, gtest, libjpeg-turbo, and mt32emu wraps (#2991)
- Sync reSIDfp with upstream (#3067)
- Sync residfp with 2.4.2 (#2259)
- Try again to fix Coverity warning in SDL Sound (#3005)
- Tune the IBM Music Feature card\u2019s 0-dB level and default filter (#3048)
- Un-deprecate the per-SoundFont volume scaling (#2677)
"},{"location":"releases/release-notes/0.81.0/#input","title":"Input","text":""},{"location":"releases/release-notes/0.81.0/#virtual-joystick-fixes","title":"Virtual joystick fixes","text":"Virtual joysticks can now be created without a physical joystick being plugged in. This fixes a regression introduced early in DOSBox Staging development, which now allows mapping keyboard events to joystick events. The deactivation logic of the pressed key now detects when the key is not being pressed anymore\u2014this improves joystick support in 74 games.
"},{"location":"releases/release-notes/0.81.0/#support-for-mapping-mouse-buttons-to-keys","title":"Support for mapping mouse buttons to keys","text":"Some games like Settlers I (also known as Serf City: Life is Feudal) require the player to push both mouse buttons at the same time to perform certain actions. This is impossible to perform on some input devices such as the Apple MacBook trackpad or the ChesterMouse. This has now been fixed by allowing mouse buttons to be mapped to the keys of the keyboard as a workaround.
"},{"location":"releases/release-notes/0.81.0/#virtualbox-mouse-driver-support","title":"VirtualBox mouse driver support","text":"DOSBox Staging has had experimental support for the VMware mouse protocol for quite some time now, and in this version, we have added support for the VirtualBox mouse protocol. The primary motivation is to enable seamless mouse operation in Windows 3.x.
Just install Javis Pedro\u2019s Windows 3.x driver and enjoy the seamless Windows 3.x experience!
"},{"location":"releases/release-notes/0.81.0/#multi-monitor-aware-mouse-capture-support","title":"Multi-monitor-aware mouse capture support","text":"DOSBox Staging now has fully multi-monitor-aware mouse capture and seamless mouse behaviour. Essentially, if DOSBox is in fullscreen mode on multi-monitor systems, mouse capture and seamless mode work as if you were still in windowed mode, allowing you to move the mouse cursor freely between the monitors.
The feature is enabled by default but it\u2019s only active on systems with multiple displays. Of course, you can always disable it by setting mouse_multi_display_aware to off in your config.
"},{"location":"releases/release-notes/0.81.0/#other-mouse-improvements","title":"Other mouse improvements","text":" - The PS/2 mouse port is now emulated at the register level, and more PS/2 protocol commands are supported. This allows the emulation of fairly complex input devices like the Microsoft IntelliMouse Explorer with 5 buttons and a mouse wheel on Windows 95.
- It is now possible to disable the built-in emulated mouse driver and use your favourite real DOS driver.
- Fixed problems with the internal mouse driver and text modes with more than 80 columns.
- Fixed mouse support in MS Word 5.5 for DOS.
"},{"location":"releases/release-notes/0.81.0/#macos-function-key-support","title":"macOS function key support","text":"macOS users can now force the Touch Bar or media keys to operate as function keys in DOSBox Staging (this will not affect other apps or the OS). Please refer to our wiki article for the setup instructions.
"},{"location":"releases/release-notes/0.81.0/#brazilian-abnt2-keyboard-support","title":"Brazilian ABNT2 keyboard support","text":"The mapper, keyboard, and BIOS tables have been expanded to handle the OEM102 and ABNT1 keys found on Brazilian ABNT2 keyboards. The left and right Windows keys have been assigned to their correct scan codes too.
Full PR list of input-related changes - Add extra hotkey button row in the mapper (#3147)
- Add mouse button mapping community patch (#3078)
- Add multi-monitor awareness mode for mouse capture (#2377)
- Create and update joy binds even when physical joysticks aren\u2019t present (#2516)
- DOS mouse driver fixes (#2601)
- Fix compatibility problems with VBADOS (VBMOUSE.EXE) mouse driver (#2742)
- Fix deactivation of queued joystick axis movement (#2713)
- Fix joysticks breaking after a config -set (#2694)
- Fix memory access in VirtualBox device, enable VirtualBox mouse protocol (#3089)
- Fix mouse centering on high DPI displays with scaling enabled (#2611)
- Fix mouse movement limitation regression in some games (#2648)
- Fix mouse problem with windowed mode and viewport_resolution setting (#2333)
- Fix problem with some software (like MSD.EXE) displaying garbage mouse driver info (#2538)
- Fix register-level PS/2 mouse access when DOS mouse driver is disabled (#3120)
- Fix the scan code sequence for the
pause key (#2498) - Handle OEM102 and ABNT1 keyboard scancodes (#2209)
- Implement DOS mouse driver function 0x32 (#2508)
- Implement i8042 diagnostic dump (#2298)
- Improve
mouse_sensitivity behavior (#3138) - Improve i8042 emulation, fix KEYB.COM (#2293)
- Improve text mode detection in DOS mouse driver (#2658)
- Keyboard rework and PS/2 mouse register-level access support (#2287)
- Minor cleanups in mouse and keyboard emulation code (#2230)
- Only unmute / unpause when Window focus is gained (#2254)
- Pause fixes (#2323)
- Port keymapper to SDL renderer (#2763)
- Prefer evdev mouse API over xinput on Linux (#2529)
- Release mouse if
config -set mouse_capture=nomouse is executed (#3129) - Reset DOS mouse driver position granularity on every mode change (#2608)
- Reworked virtual machine mouse support (#2755)
- Workaround for keyboard problem in Ultima VIII: Pagan (#3109)
"},{"location":"releases/release-notes/0.81.0/#dos-integration","title":"DOS integration","text":""},{"location":"releases/release-notes/0.81.0/#new-for-command","title":"New FOR command","text":"The missing FOR command has been added, resulting in better software compatibility with batch files that contain loops. The behaviour mirrors the behaviour of the MS-DOS 6.22 FOR command.
"},{"location":"releases/release-notes/0.81.0/#various-dos-command-additions-and-improvements","title":"Various DOS command additions and improvements","text":" - The missing
MOVE, TREE, SETVER, and VOL commands have been added. - The
CLS command now does not reset the screen mode to 80\u00d725. - The verbosity of the
DELETE command has been improved. - The wildcard handling of the
IMGMOUNT command has been improved. - The
LS command now accepts multiple paths or patterns and ignores hidden or system files unless the /A switch is specified. - The
MEM command now supports XMS memory capacities over 64 MB and has a critical bug fixed where it consumed all upper memory blocks after invocation. - The
MORE command is now extended with features from modern Windows.
"},{"location":"releases/release-notes/0.81.0/#persistent-command-history","title":"Persistent command history","text":"The emulated DOS shell now retains a 500-line history of your previous commands. The history is remembered across multiple sessions, just like you would expect it from a Linux shell.
If you\u2019d like to disable the shell history, set the new shell_history_file setting to an empty value.
"},{"location":"releases/release-notes/0.81.0/#support-for-all-dos-file-directory-attributes","title":"Support for all DOS file & directory attributes","text":"All DOS file and directory attributes are now supported.
On Windows, the attributes are stored as standard filesystem attributes.
On macOS and Linux, they\u2019re stored as a mixture of standard attributes (for the read-only flag) and extended xattr attributes. The extended attributes follow the Samba 3 format which is compatible with WINE and DOSEmu2.
"},{"location":"releases/release-notes/0.81.0/#autoexec-improvements","title":"Autoexec improvements","text":"Several long-standing autoexec issues have been fixed:
- The
[autoexec] section in config files is now fully UTF-8 aware and its contents are now converted to the internally set code page on the fly. - The size limitations of the
[autoexec] section have been lifted. - The generated
Z:\\AUTOEXEC.BAT is now prettier due to the added extra comments. - The
CONFIG -wc command does not eat away empty lines from the [autoexec] section anymore.
"},{"location":"releases/release-notes/0.81.0/#optional-shell-config-shortcuts","title":"Optional shell config shortcuts","text":"We\u2019ve supported config shortcuts for a long time now (e.g., instead of CONFIG -set sbtype sb16 you can simply use the sbtype sb16 shortcut). The feature is enabled by default, but this can cause some confusion when a shortcut conflicts with a DOS executable having the same name.
Now config shortcuts can be disabled by setting shell_config_shortcuts to off.
Full PR list of DOS integration related changes - Cleanup AUTOEXEC.BAT generation (#2609)
- Add FOR Command (#3094)
- Add full file path printing for file related debugger commands (#2472)
- Add short prompts for MORE commands for 40 column screen modes (#2953)
- Auto enable shell variable expansion for DOS >=7 (#2378)
- Autoexec fixes (#3007)
- Disable writing command line history if entry is empty (#2635)
- Do not discard empty lines in
[autoexec] section (#2415) - Do not write SETVER table back to file if secure mode is engaged (#2623)
- Don\u2019t block r/w file opens on r/o FAT images (#2280)
- Don\u2019t save command history to current working directory (#2630)
- Enable large disk image support (#2301)
- Exclude COMMAND.COM\u2019s help arguments when part of sub-command (#2263) (#2264)
- FAT image mounting fixes (#2278)
- FCB argument regression fix (#2524)
- File attribute support improvements (#2961)
- Filesystem fixes (#2288)
- Fix MSCDEX regression in game \u201cFascination (1991)\u201d (#3163)
- Fix alignment of file size column in the DIR command\u2019s output (#2799)
- Fix batch file \u2018goto\u2019 for previous labels (#2384)
- Fix bug where DTA can be modified by DELETE command (#2653)
- Fix drive automounts (#3038)
- Fix file creation regression on case sensitive file systems (#2971)
- Fix for DOS error code being wrongly set on creating files (#2989)
- Fix lockup involving specific mount order (#2310)
- Fix mounting directory with space in its name, passed as an argument (#2626)
- Fix read checks in shell file reader (#3076)
- Fix unneeded empty lines in \u2018TREE | MORE\u2019 display (#2944)
- Fixes for shell_misc.cpp regressions (#2517)
- Ignore trailing colon in shell redirection (#2240) (#2446)
- Implement DOS file/directory attributes support (#2951)
- Implement MOVE shell command (#2660)
- Implement SETVER.EXE command (#2464)
- Implement TREE.COM command (#2366)
- Implement persistent command line history (#2615)
- Implemented VOL shell command (#2638)
- Improve the help and output of the
CONFIG command (#2672) - Improve the online help of the MORE command (#2947)
- Improve verbosity of DELETE command (#2274)
- Improve wildcard handling for
imgmount file arguments (#2270) - Make MOVE and SUBST external commands (#2691)
- Make shell configuration shortcuts optional/configurable (#2807)
- Omit blank lines from command history (#2673)
- Re-write CLS command to not change screen mode (#3024)
- Re-write DOS_Shell::CMD_RENAME (#3126)
- Rename command_history to shell_history, for consistency (#2640)
- Rework and improve
LS.COM command (#3034) - Skip processing of hidden host files (#2240)
- Tab completion fixes for / and . (#2555)
- Track and free allocations in MEM program (#2534)
"},{"location":"releases/release-notes/0.81.0/#general","title":"General","text":""},{"location":"releases/release-notes/0.81.0/#revised-cpu-cycles-handling","title":"Revised CPU cycles handling","text":"Some legacy CPU cycles optimisations aimed at improving multi-tasking performance on single-core computers have finally been removed. These features probably made sense 20 years ago, but they no longer serve any useful purpose in a world where minimum quad-cores are the norm:
-
Previously, the cycles = max 100% setting resulted in only 90% CPU core utilisation and the max 105% \u201cmagic value\u201d expanded this to about 95%. Now 100% means 100%, and the weird 105% special case has been removed. As a beneficial side effect, cycles = max 100% can now make the CPU emulation thread go into oversubscription at times (over 100% capacity), resulting in a faster and more aggressive boost clock ramp-up.
-
CPU emulation is no longer silently throttled to half the configured cycles setting (!) when the DOSBox Staging window is unfocused. Such behaviour can cause audio glitches when listening to music in the background, and severely degrade performance when running computation-intensive tasks in DOSBox (such as compiling programs or rendering 3D images) while doing something else on your computer.
-
The rate for cycle guessing has been increased from 4 to 10 times per second, allowing emulation to reach optimal speeds much quicker.
-
We\u2019ve also added compensation for delays caused by the system graphics driver, such as vsync, which were adversely affecting the cycle guessing performance.
-
The DOSBox Staging window\u2019s title bar now shows the current cycles setting more accurately; specifically, the limit option is now also shown, if configured.
"},{"location":"releases/release-notes/0.81.0/#pause-improvements","title":"Pause improvements","text":"The pause feature now operates on the same principle as the mute function: you press the pause hotkey to pause, then press it again to unpause. Alt+Pause remains the hotkey on Windows and Linux, and on macOS you can use the newly introduced Cmd+P hotkey.
Additionally, we\u2019ve restored the pause indicator in the window\u2019s title bar too.
Various edge-case scenarios with the pause_when_inactive setting have also been fixed.
Pause gotchas
All input is disabled in the paused state\u2014the only thing you can do is press the pause hotkey again to unpause the emulator.
Remapping the pause hotkey is not supported (technically, you can do it in the mapper, but that will break the pause feature).
"},{"location":"releases/release-notes/0.81.0/#config-improvements","title":"Config improvements","text":" -
Previously, the primary config was only written if it did not exist and no local config was present. This was rather confusing and inconsistent. The new behaviour is to always write the primary config with the default settings if the file is missing or if it\u2019s empty.
-
You can now enable portable mode by putting an empty dosbox-staging.conf file into your DOSBox Staging executable folder. DOSBox will write the default settings to this empty file on the first launch.
-
For config settings that toggle an option (booleans), you can now use on, enabled, yes, true or 1 for enabling the feature, and off, disabled, no, false or 0 for disabling it.
-
Now the config descriptions list the defaults for all settings in a consistent manner.
-
Deprecated settings are handled better by the CONFIG command now, e.g., when listing all settings in a section, the deprecated settings are filtered out.
-
The CONFIG command has been generally revised to make working with configs simpler and more intuitive.
"},{"location":"releases/release-notes/0.81.0/#revised-capture-naming-scheme","title":"Revised capture naming scheme","text":"The naming scheme of the captured files has been revised. Previously, the name of the running DOS executable was used as the basename to which a running number was appended. This rarely added any value because DOS programs tend to have short nonsensical names such as GAME.EXE, START.EXE, SCIV.EXE, etc. If anything, this only created confusion when capturing the output from multiple differently named programs during a single DOSBox session because all basenames effectively had their own independent counters. In such a scenario, the only way to view the captured images in a timeline order was to sort them by creation date which was cumbersome.
Technically, this change was necessary to keep the counter values in sync when taking screenshots in multiple formats with the default screenshot action, but it makes a lot of sense in general too.
Captured images are now named as follows (the 0001 part is a running counter):
- Raw capture:
image0001-raw.png - Upscaled capture:
image0001.png (no postfix) - Rendered capture:
image0001-rendered.png
The other capture types have the following naming scheme:
- Audio:
audio0001.wav - Video:
video0001.avi - MIDI:
midi0001.mid - Raw OPL:
rawopl0001.dro - OPL instruments:
oplinstr0001.rad - Serial log:
serial0001.serlog
Note that the last counter value in the capture folder per capture type is only looked up at startup or after changing the capture_dir setting.
"},{"location":"releases/release-notes/0.81.0/#command-line-user-experience-improvements","title":"Command-line user experience improvements","text":"We listened to our users and improved the command-line user experience. Every option has been looked at critically; text descriptions have been rewritten, and some old options have been removed that do not apply to the current state of the software. All behaviour is still backward compatible to ensure smooth operation with old batch files and shell scripts.
Most notably, some long options were prefixed with a single dash (e.g., -machine, -lang) and some with two dashes (e.g., --list-glshaders, --printconf). Now all options conform to GNU conventions, so all long options start with two dashes (e.g., --machines). The legacy single-dash variants are still silently recognised for backward compatibility.
"},{"location":"releases/release-notes/0.81.0/#normalise-windows-explorer-context-menus","title":"Normalise Windows Explorer context menus","text":"If you\u2019re using the installer version on Windows, now starting DOSBox Stating via the right-click context menu in Windows Explorer is more consistent. Regardless of whether you click on a folder or the empty space inside a folder, DOSBox Staging will start with the working directory set to that folder.
The previous ability to execute .EXE, .COM and .BAT files directly using the right-click menu has been removed as that feature was inconsistent, confusing, and had limited applicability.
The ability to execute a .conf file using the context menu has been retained.
"},{"location":"releases/release-notes/0.81.0/#log-window-support-on-macos","title":"Log window support on macOS","text":"Previously, macOS users couldn\u2019t view the logs when starting DOSBox Staging from the Finder. We\u2019ve fixed that by adding a new special shortcut to the DMG installer to start Staging with a log window open.
How to use it
Follow the steps indicated in the DMG package, as shown:
Simply copy the included Start DOSBox Staging (logging).command to a folder then open it in Finder. DOSBox Staging will act as if started from that folder, it will pick up the local config, and it will also open a terminal window that shows the logs. \u00a0
Note
You might be asked to give DOSBox Staging access to the containing folder on the first launch\u2014just click OK if that dialog comes up.
"},{"location":"releases/release-notes/0.81.0/#modernised-application-icons","title":"Modernised application icons","text":"The new icons are compliant with modern OS interface guidelines and improve legibility at small icon sizes. A custom icon with a rounded rectangle design has been added for macOS that conforms to the Apple Human Interface Guidelines.
Linux users downloading the release from the website should run the included install-icons.sh script to see the new icons.
"},{"location":"releases/release-notes/0.81.0/#maximum-memory-space-increased-to-3-gb","title":"Maximum memory space increased to 3 GB","text":"The maximum XMS memory size has been increased from 63 MB to 3 GB. Windows 3.1x now allows more than 64 MB of RAM to be allocated.
"},{"location":"releases/release-notes/0.81.0/#modem-improvements","title":"Modem improvements","text":"The modem speed and port baud rate now match by default. This simplifies things as there isn\u2019t a possibility for the modem and port speeds to mismatch with the defaults anymore. Modem speed is now reported in bps (bits per second) to differentiate it from port speed. This fixes v1.2 of Doom as that game mandates a modem speed of 9\u2009600 bps.
"},{"location":"releases/release-notes/0.81.0/#x87-fpu-emulation-improvements","title":"x87 FPU emulation improvements","text":" -
DOSBox Staging no longer quits when an x87 FPU stack overflow occurs. Real DOS allows the system to continue in such cases, so this mimics real hardware behaviour. This improves compatibility with some misbehaving programs such as the demo kkowboy by blasphemy.
-
Rounding floating point numbers very close to integers has been fixed on non-x86 platforms. This fixes some obscure issues like not being able to increase the view size above 99 in Quake on ARM CPUs.
-
Fix \u201cblack vertical bars\u201d video corruption issue due to FILD/FIST memcpy trick in some late 90s Pentium games and demos. This was caused by a trick these programs do to perform a fast memory copy of 64-bit integer values by misusing the FILD/FIST FPU instructions (also see here).
-
The Intel Floating Point Conformance Test for IEEE 754-1985 (MCPDIAG.exe) passes with zero failures on x86 hosts with core = normal too now in our official releases. 80-bit extended precision floating point numbers are truncated to 64-bit double precision on non-x86 hosts due to performance reasons; it\u2019s not recommended to use DOSBox Staging on such hosts for any engineering or financial calculations. The current state of x87 FPU emulation is as follows:
- 100% conformance in all Intel x86 (32-bit) and x64 (64-bit) Windows, macOS and Linux builds on all cores.
- Every other build, host, and core combination is non-conformant (but working at reduced 64-bit precision).
-
Builds that only support reduced 64-bit double precision floating-point emulation instead of full 80-bit extended precision now log a warning about this at startup.
"},{"location":"releases/release-notes/0.81.0/#debugger-improvements","title":"Debugger improvements","text":" -
Linux debugger-enabled builds now have OpenGL enabled (previously, this was disabled due to the OpenGL code paths not being compatible with the debugger on Linux).
-
A C_HEAVY_DEBUG compile-time feature has been added to allow breaking on memory reads in the integrated debugger. Similarly to most of the debugger features, this only works reliably when using core = normal with real mode programs.
"},{"location":"releases/release-notes/0.81.0/#improved-linux-man-page","title":"Improved Linux man page","text":"The Linux man page has been outdated for quite some time now. This has been rectified; the man page now contains an accurate description of the new and revised command-line interface of DOSBox Staging.
"},{"location":"releases/release-notes/0.81.0/#freebsd-openbsd-ppc-support","title":"FreeBSD, OpenBSD & PPC support","text":"DOSBox Staging can now be compiled on FreeBSD and OpenBSD. The PPC dynarec core has been broken for a while now; this has been fixed, and various endianness issues have been rectified so now you can run Staging on big-endian PPC processors without problems.
Full PR list of miscellaneous enhancements - Always write the primary config if it doesn\u2019t exist (#2966)
- Don\u2019t throttle emulation speed when window becomes unfocused (#3085)
- Enable loguru stack traces (#2652)
- Fix FROUND Issues (#3161)
- Fix rounding when very close to an integer (#3149)
- Import FPU scale fix for x86 normal core (#2297)
- Improve handling of deprecated settings and other setting related improvements (#3118)
- Increase maximum memory size to 384 MB (256 MB+128 MB) (#2289)
- Logging & config description improvements (#2668)
- Never hard-exit DOSBox when an x87 FPU stack overflow is detected (#2564)
- Normalise warnings messages (#3143)
- Regenerate primary config file if it is empty (#3139)
- Restore pause on macOS & pause indicator in the window\u2019s title bar (#3140)
- Restore sane
max N% cycles behaviour where 100% means 100% (#3141) - Skip compiler if error instead of aborting in compile_commits.sh (#3130)
- Skip hidden dot files when wildcard pattern is first (#2492)
- Turn down loguru verbosity when started with following arugments (#2722)
- Update Tracy to 0.10 (#3022)
- Update increaseticks sleep strategy (#2655)
- Updated modem CONNECT response behavior (#3023)
- Use C++11
std::nearbyint() for nearest FPU round (#2296) - Use dynamic SDL version checking for logging (#2689)
Full PR list of miscellaneous fixes - Adapt to setup function additions (#2563)
- Add missing mutex lock to RWQueue (#2773)
- Allow FROUND fix on x64 (#3216)
- Always write the default config if the primary config file is missing (#3117)
- Change drive macros to return boolean values (#3020)
- Close file descriptor in cdrom ioctl class (#2685)
- Copy only the available command line chars (#2542)
- Display \u2018max limit\u2019 cycles setting properly in the title bar (#3214)
- Do not assert if mapperfile parameter is empty (#2995)
- Don\u2019t emulate CDROM lag for stationary calls (#2624)
- Don\u2019t sign extend 16-bit immediates to 32-bit in ppc64le dynrec, fixes #2846 (#2850)
- Fix \u2018auto\u2019 presentation mode on macOS in fullscreen (#3219)
- Fix
pause_when_inactive mouse behavior for macOS and Linux (#2262) - Fix completion index assertion error (#2531)
- Fix incorrect version reporting in Virtualbox LOG_WARNING. (#3002)
- Fix macOS debugger crash (#2495)
- Fix mistake in a comment (#2299)
- Fix mouse pointer for MS Word 5.5, based on DOSBox-X implementation (#2504)
- Fix no function names in Loguru stack traces on Linux (#2682)
- Fix null pointer de-reference in dyncache on Windows (#2863)
- Fix ppc64le backend and 64K page size support (#2828)
- Gracefully quit stdin loops on program termination (#2392)
- Handle exiting when
pause_when_inactive = true (#3079) - Make conf path handling more robust (#2241)
- Prevent duplicate SDL Window creation when using OpenGL (#2822)
- Replace invalid vector.end dereference with raw pointer access (#2471)
- Set the icon on window regeneration (#3081)
- Store envelope channel_name as std::string (#2670)
- Track previously added userdata when deleting the SDL resize watch (#2802)
- Use int64_t consistently for tick durations (#2596)
- Zero initalize memory allocation in GrowWriteMask in dyn_cache (#2986)
Full PR list of documentation-related changes - Add Instructions to Build on Nix (#2326)
- Add game mode support for macOS Sonoma or newer (#3016)
- Add missing defaults to all config settings that still don\u2019t have them (#3207)
- Add v0.80.1 release notes (#2203)
- Fix a few bad links in README. (#2320)
- Fix or simplify some descriptions (#3062)
- Fix the formatting of some config descriptions (#2560)
- Harmonize some help strings (#2686)
- Improve some config setting descriptions (#2578)
- Minor configuration file cleanups (#2634)
- Modify deploy website workflow to deploy to the GitHub Pages org repo (#2202)
- Move Wiki link to the top navbar from the footer (#2206)
- Normalise config descriptions and add default values to most of them (#2221)
- README.md typo Vorbis (#2791)
- Remove opencaptures (#2970)
- Rename \u2018cdda\u2019 to \u2018cdaudio\u2019 in the MIXER help examples (#2725)
- Revise the README template & include link to the new Getting Started \u2026 (#2360)
- Snip truism note from MIXER long help text (#3066)
- String fixes in CONFIG command (#2723)
- Update DOCUMENTATION.md (#2827)
- Update docs with supported versions of Windows, macOS, and Linux (#2258) (#2276)
- Update the Linux
man page (#2837) - Update translation guide (#3213)
- Various config setting description improvements (#2729)
- [DRAFT] Our man page is currently unmaintained - do not install it (#2820)
Full PR list of project maintenance related changes - Add \u201cStart DOSBox Staging (logging)\u201d command to the macOS DMG image (#2352)
- Add a memory read breakpoint feature to the builtin debugger (#3191)
- Add a script to compile all commits on the current branch (#2642)
- Add higher res icons to meson install script (#3179)
- Add several warnings to the GCC build (#2661)
- Add support for FreeBSD and OpenBSD (#2338)
- Add warning log if message is missing (#2566)
- Add wrap for SDL2 to support static macos builds (#2239)
- Adjust ticksDone with render time (#3136)
- Another batch of PVS Studio fixes (#2776)
- Another batch of PVS Studio fixes (#2756)
- Boolean config param handling improvements & cleanup (#2354)
- Bound and pin dependency versions (#2217)
- Change sdl.opengl.shader_source from std::string_view to std::string (#2753)
- Check and log *nix
ioctl return-code errors (#2721) - Clean up VESA_GetSVGAInformation() & get rid of warnings (#2715)
- Cleanup a Coverity null-deference reloading the shader (#2633)
- Cleanup a couple unhandled switch cases when OpenGL isn\u2019t available (#3197)
- Cleanup a handful of PVS Studio warnings (#2627)
- Cleanup a handful of unchecked return-code issues flagged by Coverity (#3180)
- Cleanup a handul of new Coverity issues (#2639)
- Cleanup among PCI/Memory constants (#2733)
- Cleanup in cross.cpp (#2447)
- Cleanup new CI warnings due to host-side updates (#2836)
- Cleanup two ASAN initialization order issues (#2330)
- Compile debug builds with GCC and Clang library check flags (#2553)
- Convert SDLOSXCAGuard files to UTF-8 (#2982)
- core_dyn_x86: Initialise rettype to avoid compiler warning (#2365)
- De-unionise X86PageEntry (#2994)
- Debug/trace logging improvements (#2832)
- Differentiate CLI arguments from markup tags with escapes (#2349)
- Do not set icon at runtime (#3171)
- Drop Visual Studio 2019-specific accomodations in
.clang-format (#2489) - Encapsulate the Cache\u2019s write mask functions as members (#2990)
- Fix OpenGL symbol type mismatch warning at link time (#3098)
- Fix Visual Studio project & filter definitions for src/hardware (#2459)
- Fix
format-commit.sh, Stop reformatting #includes (#2388) - Fix a couple Coverity warnings involved unchecked return values (#2631)
- Fix a couple recent Coverity warnings (#2368)
- Fix compilation error on
misc_util.h (#2329) - Fix coverity sign extension warning (#3001)
- Fix flipped ANSI colour intensity flag bug and use canonical CGA colour tag names (#2979)
- Fix for spelling mistake on NixOS.txt (#2363)
- Fix minor data read access issues flagged by TSAN (#2328)
- Fix nullptr compiler warnings (#2709)
- Fix several static analysis warnings (#2750)
- Fix small typos on
build-nix.md (#2341) - Fixing missing header file for select() syscall when building on MacO\u2026 (#2968)
- Harmonize ManyMouse support message in the build system (#3050)
- Hopefully make MSYS2 build pass (#2692)
- Improve DOSBox Staging application icons (#3157)
- Improve XMS emulation, based on code from DOSBox-X (#2386)
- Improve compile commits script (#2760)
- Increase max memory size to 3072 MB, minor cleanup (#2334)
- Let Meson use a system call to detect the page size (#3174)
- Let
DriveManager own all filesystem and image mount objects (#2306) - Make BatchFile Testable (#2618)
- Make the DOS module depend on SDL2 net (#2358)
- Make the RWQueue more usable for complex types (#2522)
- Mark all core run functions with
noexcept (#2251) - Move
bit_view value assignment to a general function (#2290) - Move dynamic FPU synchronization inside preprocessor defines (#2252)
- Normalise Windows context menus created by the installer (#2355)
- Notify all when RWQueue stops (#2775)
- PVS Studio fixes (#3088)
- PVS Studio warning fixes (#3070)
- Packaging improvements for icons on Linux (#3193)
- Perform safe left-shift of signed values in dynrec operators (#2535)
- Refactor Prop_path to use std_fs::path (#2700)
- Refactor Property->Get_string to return a std::string (#3009)
- Refactor WriteOut functions in program.cpp (#2309)
- Refactor command line arguments (#2703)
- Refactor shell_batch.cpp (#2342)
- Refactor shell_misc.cpp (#2482)
- Remove fontstash library (#3013)
- Remove obsolete APIs from \u2018dos_system.h\u2019 (#2976)
- Restore files required by the Linux Flatpak build (#2213)
- Revert increaseticks sleep to 1ms (#2792)
- Revert use of pinned vcpkg versions (#2222)
- Show backtraces in debug builds using Loguru\u2019s assert (#2650)
- Suppress excessively verbose
sprintf warnings on macos + clang (#2307) - Sync GHC std::filesystem with v1.5.14 (#2613)
- Sync Meson wraps with upstream (#2427)
- Sync decoders with upstream versions (#2718)
- Sync enet with upstream version 2.3.6 (#3012)
- Sync flatpak metadata up to
0.81.0-alpha (#2216) - Sync whereami with upstream (#3017)
- Typo fixed in setup.cpp (#3063)
- Update Linux AppData description (#2732)
- Update Linux and macOS debug CI workflows (#2628)
- Update RPM spec file (#2659)
- Update macOS build instructions (#3044)
- Use safe_strcpy and safe_strcat (#3003)
- Use safer calls in dynrec and operators (#2350)
- Use std math functions in
compressor.cpp (#3203)
Full PR list of other changes - Add docker image and CI job for ppc64le architecture (#2834)
- Add package download URL to issue template (#2473)
- Add pull request template (#2845)
- Avoid checked-STL false positives in Coverity build (#2561)
- Bundle all license texts with binary packages (#2420)
- Contribute an SDL audio test tool (#2317)
- Disable FluidSynth\u2019s own unit tests under MSYS2 CI (#2357)
- Drop Ubuntu 18.04 from the CI workflows (#2292)
- Improve caching of subpackages (#2269)
- Let MacOS homebrew overwrite conflicting junk files in CI (#2716)
- Reinstate MSVC CI workflow (#2573)
- Revisit our approach to categorising items in the release notes (#3196)
- Support the right control key on MacOS. (#2314)
- Suppress ALSA API macros PVS Studio warnings (#2783)
- Update Coverity to version 2023.6.2 (#3175)
- Update Windows SSL certificate authority in MSYS2 workflow (#2245)
- Update packages/*.txt files to include ffmpeg and conan (#2805)
- Update templates (#2830)
- Use versioned action/upload key names in CI workflows (#3215)
"},{"location":"releases/release-notes/0.81.0/#localisation","title":"Localisation","text":""},{"location":"releases/release-notes/0.81.0/#support-for-modern-and-historic-locales","title":"Support for modern and historic locales","text":"It is now possible to select between modern and historic (DOS era) locale styles via the new locale_period setting. Historic settings (if available for the given country) try to mimic old DOS behaviour when displaying information such as dates, times, or numbers; modern ones follow practices more consistent with typical current-day host systems.
Also, a lot more locale definitions not present in the original MS-DOS have been added from OS/2 Warp 4.52.
"},{"location":"releases/release-notes/0.81.0/#translation-updates","title":"Translation updates","text":" - Updates to Polish, Dutch, and Italian translations.
- The command-line help text is now translatable and correctly outputs UTF-8 text on Windows.
- The translation workflow has been simplified.
- A batch file for converting translations made on Windows to Unix carriage return format has been added.
"},{"location":"releases/release-notes/0.81.0/#script-to-convert-gog-cp473-config-files-to-utf-8","title":"Script to convert GOG CP473 config files to UTF-8","text":"GOG ship their DOS games with dosbox.conf files that assume the CP437 DOS codepage (also known as OEM-US or DOS Latin US). Some of their games display fancy startup menus via commands in the [autoexec] section, and these often use extended ASCII table drawing characters. This, however, conflicts with our revised UTF8-aware config handling, which results in the table drawing characters not being displayed correctly.
The fix is to convert such config files from CP473 to UTF-8 encoding. One of our contributors created a script that can convert such config files, even recursively in all subdirectories to fix up all your GOG games. You can download it from here. Make sure to install the required dependencies as described in the readme.
Full PR list of localisation-related changes - Add batch file (Windows) to convert GOG cp437 config files to UTF-8 (#3031)
- Add countries and historic locales from OS/2 Warp 4.52 (#3182)
- Add legacy codepage to UTF-8 script (#3029)
- Add more definitions to Unicode engine (#3084)
- Add translation batch file for Windows (#2303)
- Country codes cleanup, fix incorrect country set in some cases (#3134)
- Country support improvements (#3164)
- Fix UTF8 to DOS conversion by mistake applied twice in autoexec code (#2645)
- Fix extended ASCII codes not being rendered in batch files (#3028)
- Fix few English strings, update Polish (pl) translation (#2295)
- Fix problem with loading Unicode data files in some situations (#2641)
- Fix some mistakes in code page character to Unicode mappings (#2490)
- Group together shell error strings (#2343)
- Handle host code pages when running
dosbox.exe --help on Windows (#3064) - Improve Arabic support in Unicode engine (#2458)
- Improve Unicode character fallback rules (#2594)
- Improve batch file to convert GOG cp437 config files to UTF-8 (#3042)
- Let the command line
--help text be translatable (#3052) - Make
--list-glshaders output translatable (#3178) - Minor Unicode definitions improvements (#3153)
- Minor country and help fixes (#3186)
- Rework AUTOEXEC.BAT support, make it UTF-8 aware (#2425)
- Simplify translation workflow (#2954)
- Two trivial fixes (#2423)
- Unicode (and [autoexec]) improvements (#2422)
- Unicode engine improvements (#2548)
- Unicode mapping for CYRILLIC LETTER I WITH GRAVE, RUBLE, BG (#2621)
- Update Dutch (nl) translation (#3187)
- Update Dutch (nl) translation (#3069)
- Update Dutch (nl) translation (#2974)
- Update Dutch (nl) translation (#2824)
- Update Dutch (nl) translation (#2680)
- Update Dutch (nl) translation (#2657)
- Update Dutch (nl) translation (#2372)
- Update Italian (it-IT) translation (#2385)
- Update Italian (it-IT) translation (#2327)
- Update Italian (it-IT) translation (improved some strings) (#2419)
- Update Italian (it-it) translation (#2302)
- Update Italian (it-it) translation (#3137)
- Update Italian (it-it) translation (#3065)
- Update Italian (it-it) translation (#2980)
- Update Italian (it-it) translation (#2815)
- Update Italian (it-it) translation (#2737)
- Update Italian (it-it) translation (#2702)
- Update Italian (it-it) translation (#2643)
- Update Italian (it-it) translation (#2584)
- Update Italian (it-it) translation (#2497)
- Update Italian (it-it) translation (#2476)
- Update Italian (it-it) translation (#2226)
- Update Polish (pl) translation (#3190)
- Update Polish (pl) translation (#3176)
- Update Polish (pl) translation (#3071)
- Update Polish (pl) translation (#3033)
- Update Polish (pl) translation (#2810)
- Update Polish (pl) translation (#2493)
- Update Polish (pl) translation (#2381)
- Update Polish (pl) translation (#2337)
- Update Polish (pl) translation (#2300)
- Update Polish (pl) translation, fix one more English string (#2724)
- Update Polish (pl) translation, trivial fix to one help string (#2644)
"},{"location":"releases/release-notes/0.81.0/#contributors","title":"Contributors","text":"The following commit authors, sponsors, supporters, and backers all invested their time or funds into the 0.81 release effort. Thank you!
Contributors are listed in alphabetic order.
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":"releases/release-notes/0.81.0/#081-commit-authors","title":"0.81 commit authors","text":"Complete list of commit authors who have contributed code, documentation, or translation changes:
- Burrito78
- classilla
- d10sfan
- dreamer
- farsil
- FeralChild64
- flakesl
- ftortoriello
- GranMinigun
- Grounded0
- h3xx
- johnnovak
- Kappa971
- kcgen
- keenanweaver
- khalid586
- kklobe
- LowLevelMahn
- MaddTheSane
- MeAreJeenius
- NicknineTheEagle
- Nopey
- rderooy
- runlevel5
- shermp
- signed-log
- sulix
- thaewrapt
- ThomasEricB
- Torinde
- weirddan455
"},{"location":"releases/release-notes/0.81.0/#081-sponsors","title":"0.81 sponsors","text":"Sponsors who have donated 100 USD or more per month:
"},{"location":"releases/release-notes/0.81.0/#081-supporters","title":"0.81 supporters","text":"Supporters who have donated 25 USD or more per month:
"},{"location":"releases/release-notes/0.81.0/#081-backers","title":"0.81 backers","text":"Backers who have donated 5 USD or more per month:
- BenBudr
- Burrito78
- flakesl
- Florent Wagner
- Hannu Hartikainen
- Hugo Lucorcio
- MagnusPerotinus
- Robin Mattheussen
- Thomas Eric
"},{"location":"releases/release-notes/0.81.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":"releases/release-notes/0.81.1/","title":"0.81.1 release notes","text":"Release date: 2024-05-12
"},{"location":"releases/release-notes/0.81.1/#summary","title":"Summary","text":"The main focus of this maintenance release is to fix a couple of regressions introduced in 0.81.0, most of them related to game compatibility, and address a few long-standing issues.
This release was made possible by everyone who tried 0.81.0, submitted bugs and pull requests, and tested the updates. Thank you!
"},{"location":"releases/release-notes/0.81.1/#regression-fixes","title":"Regression fixes","text":"The release fixes the following 0.81.0 regressions:
-
Fix Wing Commander 3 videos and cutscenes appearing height-doubled.
-
Introduce vga_render_per_scanline = off workaround to fix the crash-at-startup regression in Deus, Ishar 3, Robinson\u2019s Requiem, and Time Warriors.
-
Fix the Tandy version of Impossible Mission II crashing at startup.
-
Fix regression in Tyrian where pressing the arrow keys get registered twice in menus.
-
Fix starting In Extremis resulting in a black screen.
-
Fix wrong colours in Spell It Plus! (needs machine = svga_paradise).
-
Fix wrong colours and garbled graphics in Spong and Exobius.
-
Fix squashed video output in the text mode game Indenture.
-
Fix the DOSBox Staging window gaining focus on every emulated video mode change.
-
Fix crash when exiting DOSBox Staging while in fullscreen mode on macOS and Linux.
-
Fix not being able to disable OPL emulation with oplmode = none.
"},{"location":"releases/release-notes/0.81.1/#enhancements-and-fixes","title":"Enhancements and fixes","text":"We\u2019ve also backported a number of enhancements and fixes for long-standing issues:
-
Introduce vmem_delay = on to help with flickering graphics and speed issues in Hercules, CGA, EGA, and early VGA games. This has proven to improve compatibility with Future Wars, Operation Stealth, Quest for Glory II, Hostages, The Gold of the Aztecs, Crazy Brix, Corncob Deluxe, and Corncob 3-D so far.
-
Improve support for multiple joysticks/game controllers (the mapper could behave erratically if you had more than one controller connected).
-
Emulate a memory-expanded PCjr machine more faithfully. This improves game compatibility; for{ example, Space Quest (v1.0x and v2.2) and King\u2019s Quest (1986 PCjr DOS version) now work instead of hanging the emulator.
-
CD Audio is no longer muted in certain parts of Time Warriors and Alpha Storm.
-
The batch file installer of Alpha Storm no longer fails.
-
Forcing single scanning via crt-auto-arcade should now work with more programs.
-
Fix various VGA double scanning related edge cases in demoscene productions.
-
Detecting \u201crepurposed\u201d EGA video modes with 18-bit VGA DAC colours has been made more robust when using the crt-auto shader (should result in a double-scanned VGA shader being picked).
-
Spanish and Brazilian Portuguese translations have been added, and most of the other translations have been updated.
Read on to learn about the details!
"},{"location":"releases/release-notes/0.81.1/#how-to-upgrade","title":"How to upgrade","text":"Start by downloading the latest version, then make sure to upgrade your primary configuration as described below.
"},{"location":"releases/release-notes/0.81.1/#downloads","title":"Downloads","text":""},{"location":"releases/release-notes/0.81.1/#upgrading-your-primary-configuration","title":"Upgrading your primary configuration","text":"Since config settings might get renamed, altered, or deprecated between releases, it\u2019s best to let DOSBox Staging write the new default primary config on the first launch, then reapply your old settings manually.
Start by backing up your existing primary config. This is where to find it on each platform:
Windows C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox-staging.conf macOS ~/Library/Preferences/DOSBox/dosbox-staging.conf Linux ~/.config/dosbox/dosbox-staging.conf You can also execute DOSBox Staging with the --printconf option to have the location of the primary config printed to your console.
After backing up the existing primary config, simply start the new version\u2014a new dosbox-staging.conf will be written containing the new defaults and updated setting descriptions.
Portable mode notes
In portable mode, dosbox-staging.conf resides in the same folder as your DOSBox Staging executable. The migration steps for portable mode users are as follows:
- Unpack the new version into a new folder (this is important).
- Create a new empty
dosbox-staging.conf file in the new folder to enable portable mode. - Launch the new version.
DOSBox Staging will write the new defaults to the empty dosbox-staging.conf file. After this, you carry over your settings from the old primary config manually.
"},{"location":"releases/release-notes/0.81.1/#after-upgrading","title":"After upgrading","text":"Look for deprecation warnings in the logs (in yellow or orange colours) and update your configs accordingly.
"},{"location":"releases/release-notes/0.81.1/#graphics-related-changes","title":"Graphics-related changes","text":""},{"location":"releases/release-notes/0.81.1/#vga-double-scanning-fixes-improvements","title":"VGA double scanning fixes & improvements","text":" -
The SVGA/VESA double scanning criteria has been refined, which fixes a Wing Commander 3 regression where the videos and cutscenes appeared height-doubled.
-
Some 320\u00d7 } 200, 320 & times; 240 and similar tweaked double - scanned VGA modes were incorrectly identified as 320 & times; 400, 320 & times;480, etc., which was confusing in the logs and single scanning could not be forced on them (e.g., with glshader = crt-auto-arcade). Affected programs include Pinball Dreams, Show by Majic 12, and the Copper demo (see the issue ticket for the exact details).
-
Support \u201cunorthodox\u201d scanline repeats on VGA in forced single scanning mode. This improves compatibility with demoscene productions; for example, Show by Majic 12 sets up a custom 320\u00d740 mode and then uses scanline-quintupling to repeat every line 5 times in the zoom-rotator part in the intro.
-
Support for double-scanned text modes was removed by mistake, which we\u2019re now restoring. This resulted in the text mode game Indenture appearing squashed (half-height). The game sets up a custom 640\u00d7200 text mode using the 8\u00d78 pixel CGA font with double scanning enabled.
-
Detecting \u201crepurposed\u201d EGA video modes with 18-bit VGA DAC colours on emulated VGA adapters has been made more robust. In these scenarios, the crt-auto shader should more reliably choose a double-scanned VGA shader instead of a single-scanned EGA shader.
"},{"location":"releases/release-notes/0.81.1/#option-to-emulate-video-memory-access-delays","title":"Option to emulate video memory access delays","text":"We\u2019ve added the new vmem_delay setting to the [dosbox] section to more closely emulate the behaviour of old video cards. This approximates the CPU-throttling effect of accessing slow video memory via the ISA bus. The feature was adapted from DOSBox-X based on a tip by MX9000. Thanks man!
To enable the feature, just set vmem_delay to on in your config. This can help reduce or eliminate flicker in Hercules, CGA, EGA, and early VGA games and \u201ceven out\u201d emulation speed in speed-sensitive titles.
We recommend enabling this only when necessary on a per-game basis, as it slows down the emulation. You can also fine-tune the delay by specifying the access delay in nanoseconds (on sets 3000 ns).
vmem_delay = on fixes the flashing graphics and various speed issues in at least the following titles:
- Corncob 3-D
- Corncob Deluxe
- Crazy Brix (
vmem_delay = 2000 and cycles = 70000 makes the game run smoothly) - Future Wars (also needs
cycles = 1000) - Gold of the Aztecs, The
- Hostages (also needs
cycles = 1500) - Operation Stealth (when VGA or EGA is selected in the game\u2019s setup)
- Quest for Glory II (fixes the too-fast vertical scrolling in the intro)
"},{"location":"releases/release-notes/0.81.1/#option-for-legacy-vga-rendering","title":"Option for legacy VGA rendering","text":"In 0.81.0, we made accurate per-scanline VGA rendering the only rendering option available (previously, you could only enable this via machine = vgaonly). A minority of games, however, have regressed by this and would crash at startup.
As a workaround, until we improve the accuracy of the VGA emulation, we\u2019re introducing the vga_render_per_scanline setting in the [dosbox] section. The setting is enabled by default, but you can disable it to restore the legacy rendering behaviour on a per-game basis.
Disabling vga_render_per_scanline fixes the crash-at-startup regression in the following Silmarils titles:
- Deus
- Ishar 3
- Robinson\u2019s Requiem
- Time Warriors
Note that these games are also CPU speed sensitive and would crash with high cycles settings\u2014see the issue ticket for config recommendations.
"},{"location":"releases/release-notes/0.81.1/#option-for-legacy-palette-behaviour","title":"Option for legacy palette behaviour","text":"The svga_paradise machine type now uses the legacy non-vgaonly palette behaviour. This fixes the wrong colours in some rare titles (e.g., Spell It Plus!).
"},{"location":"releases/release-notes/0.81.1/#tandy-graphics-fixes","title":"Tandy graphics fixes","text":"Fixed a regression where the Tandy version of Impossible Mission II would crash when starting a new game. This fix should restore our general compatibility with non-standard Tandy graphics modes as well.
"},{"location":"releases/release-notes/0.81.1/#other-fixes","title":"Other fixes","text":" -
Fixed the DOSBox Staging window gaining focus on emulated video mode changes.
-
Fixed crash when exiting DOSBox Staging while in fullscreen mode on macOS and Linux.
-
Fixed wrong colours and garbled graphics in Spong and Exobius.
Full PR list of graphics-related changes - Add
vga_render_per_scanline option (#3507) - Do not resize if Tandy vertical rows register is zero (#3448)
- Fix crash when quitting while in fullscreen mode (#3545)
- Fix double-scanning behavior for SVGA/VESA games (#3428)
- Fix Impossible Mission II transition effect (#3454)
- Fix the width of VGA text modes being incorrectly set sometimes (#3611)
- Fix \u201cunorthodox\u201d scanline repeats on VGA (#3441)
- Improve VGA double scanning criteria (#3446)
- Log OpenGL vsync state (#3553)
- Only raise window when it is newly created (#3440)
- Port video memory I/O delay tweak from DOSBox-X (#3597)
- Restore double scanning support for VGA text modes (#3568)
- Revert to legacy non-
vgaonly palette behaviour on svga_paradise (#3589) - Simplify \u201cEGA mode with VGA palette\u201d detection & make it more robust (#3639)
"},{"location":"releases/release-notes/0.81.1/#sound-related-changes","title":"Sound-related changes","text":""},{"location":"releases/release-notes/0.81.1/#implement-seeking-in-mscdex","title":"Implement seeking in MSCDEX","text":"A few games use the seek function of the CD-ROM but this was not previously implemented in our emulated MSCDEX driver. This resulted in CD Audio playing only sometimes in a few games.
The new seek implementation fixes CD Audio music in at least these titles:
- Time Warriors \u2014 CD Audio music is now playing during the main menu and gameplay.
- Alpha Storm \u2014 CD Audio music is now playing in the opening movie.
"},{"location":"releases/release-notes/0.81.1/#fix-not-being-able-to-disable-opl-emulation","title":"Fix not being able to disable OPL emulation","text":"Fixed a regression where you could not disable OPL emulation with oplmode = none anymore (sbtype = none still worked, but that disabled the Sound Blaster as well).
"},{"location":"releases/release-notes/0.81.1/#other-fixes_1","title":"Other fixes","text":" -
Fixed crash when output filter cutoff frequencies are not below half the sample rate (e.g., by setting rate = 11025 and sbtype = sbpro1 which selects a 8 kHz low-pass filter by default).
-
Fixed FluidSynth and MT-32 crashing the emulator when the host sample rate is set to 8000 Hz.
Full PR list of sound-related changes - Fix not being able to set
oplmode = none regression (#3565) - Fix various crashes when the host sample rate is set to low values (#3629)
- Implement seeking in MSCDEX (#3516)
- Use SB* and OPL logging prefixes consistely in all scenarios (#3587)
"},{"location":"releases/release-notes/0.81.1/#input-related-changes","title":"Input-related changes","text":" -
Fixed a keyboard handling regression in Tyrian where pressing the arrow keys get registered twice, making the menus very hard to use.
-
Fixed a keyboard handling regression in In Extremis where starting the game only resulted in a black screen.
-
Fixed various problems in the mapper when using more than a single game controller (e.g., with two joysticks connected, mapping the controls of the first joystick could randomly target the mappings of the second one and vice versa).
-
Fixed obscure regression where the timed = on joystick setting messed up the available free memory reported by the FreeDOS MEM.EXE command.
Full PR list of input-related changes - Deactivate IRQ if byte is read from i8042 chip (#3647)
- Fix handling multiple game controllers (#3404)
- Fix the \u2018In Extremis\u2019 game intro getting stuck (#3549)
- Set BIOS_Destroy not changeable at runtime (#3420)
"},{"location":"releases/release-notes/0.81.1/#dos-integration-related-changes","title":"DOS integration related changes","text":""},{"location":"releases/release-notes/0.81.1/#improved-expanded-pcjr-emulation","title":"Improved expanded PCjr emulation","text":"Now we\u2019re emulating a memory-expanded PCjr machine more faithfully. This improves game compatibility; for example, Space Quest (v1.0x and v2.2) and King\u2019s Quest (1986 PCjr DOS version) now work fine\u2014these games resulted in the emulator hanging previously.
A new pcjr_memory_config setting has been introduced to the [dosbox] section, defaulting to expanded (the new improved behaviour). Setting this to standard restores the legacy memory model. You should only need this for a handful of titles, such as the DOS conversions of the Jumpman and Troll PC Booter games.
"},{"location":"releases/release-notes/0.81.1/#dos-shell-improvements","title":"DOS shell improvements","text":" -
Fixed a bug that caused the batch file installer of Alpha Storm to fail.
-
The help text of the IMGMOUNT command now mentions the very handy wildcard mounting option. E.g., you can use the IMGMOUNT A floppy*.img -t floppy command to mount multiple floppy images, then cycle between them with Ctrl+F4 at runtime (Cmd+F4 on macOS).
-
The LOADFIX command\u2019s help text is more complete now (some options were not documented previously).
-
When a batch file was being instantiated, the echo state from the parent was not being transferred correctly if the parent was another batch file.
Full PR list of DOS integration related changes - Check the validity of leading path when checking device name (#3525)
- Improve the IMGMOUNT command\u2019s help text (#3551)
- Inherit batch file echo state from parent (#3578)
- Improve the help text of the LOADFIX command (#3221) (#3427)
- Make PCjr application memory contiguous (#3460)
"},{"location":"releases/release-notes/0.81.1/#localisation-related-changes","title":"Localisation-related changes","text":" - Spanish and Brazilian Portuguese translations have been added.
- Updates to the Dutch, German, and Polish translations.
Full PR list of localisation-related changes - Fix incomplete integration of Brazilian translation (#3438)
- New Spanish translation (#3317)
- Portuguese (Brazilian) Translation (#3432)
- Update br.lng (#3439)
- Update br.lng (#3458)
- Update de.lng (#3530)
- Update de.lng (#3530)
- Update Dutch (nl) translation (#3459)
- Update English (en) translation for 0.81.1 (#3600)
- Update German (de) translation (#3630)
- Update Italian (it) translation (#3560)
- Update Italian (it) translation (#3603)
- Update Polish (pl) translation (#3463)
- Update Polish (pl) translation (#3532)
- Update Polish (pl) translation (#3633)
- Update Portuguese (br) translation (#3469)
"},{"location":"releases/release-notes/0.81.1/#miscellaneous-changes","title":"Miscellaneous changes","text":" -
Attempting to change unchangeable settings via the CONFIG command at runtime is no longer silently accepted (without doing anything) but an error is raised instead.
-
Unknown command-line switches starting with dashes are now ignored and a warning is logged\u2014DOSBox Staging will not try to execute them anymore. As a side effect, the current working directory was mounted as the C drive, which led to very non-intuitive behaviour.
-
The Windows installer now creates a Start Menu shortcut to launch DOSBox Staging without showing the console window (DOSBox Staging (no console window) menu item).
-
The Windows installer no longer starts DOSBox Staging automatically when the installation is completed.
-
Most config settings are now correctly reverted to their defaults when an invalid value is set, and their values are kept in sync with the active setting.
Full PR list of miscellaneous changes - Add \u201cno console\u201d start menu item to the Windows installer (#3510)
- Better build version handling at runtime (#3556)
- Config setting defaulting/syncing improvements & fixes (#3626)
- Do not treat illegal command line switches as commands (#3621)
- Drop Debian 10 (#3557)
- Fix IPX config help comment (#3403)
- Improve \u2018keyboardlayout\u2019 option description (#3409)
- LTO build fix (#3538)
- Throw error if user attempts to change an unchangeable setting (#3470)
"},{"location":"releases/release-notes/0.81.1/#0811-commit-authors","title":"0.81.1 commit authors","text":"Complete list of commit authors who have contributed code, documentation, or translation changes:
- altiereslima
- bluddy
- Burrito78
- farsil
- japsmits
- FeralChild64
- ftortoriello
- johnnovak
- kklobe
- weirddan455
"},{"location":"releases/release-notes/0.81.1/#thank-you","title":"Thank you","text":"We are grateful for all the community contributions and the original DOSBox project, on which DOSBox Staging is based.
"},{"location":"releases/release-notes/0.81.2/","title":"0.81.2 release notes","text":"Release date: 2024-07-21
"},{"location":"releases/release-notes/0.81.2/#summary","title":"Summary","text":"This patch release fixes a critical keyboard regression bug in the classic Bitmap Brothers game Gods. The regression was accidentally introduced in the 0.81.1 release (#3777).
The game is very difficult to play without this fix, as holding down the movement keys may result in delayed movement, jerky start/stop motion, or no movement at all after a bit of playing.
Gods \u2014 with glshader = crt-auto-arcade to emulate the original Amiga look
"},{"location":"releases/release-notes/0.81.2/#installation","title":"Installation","text":"This is a drop-in upgrade for users already on\u00a00.81.0\u00a0or\u00a00.81.1\u2014no configuration changes are necessary.
For those upgrading from an earlier DOSBox Staging version, please follow these upgrade instructions and read the release notes of 0.81.0 and 0.81.1.
First-time users and people migrating from other DOSBox variants should start by reading the Getting started guide.
"},{"location":"releases/release-notes/0.81.2/#0812-commit-authors","title":"0.81.2 commit authors","text":""},{"location":"releases/release-notes/0.81.2/#thank-you","title":"Thank you","text":"We are grateful for all the community contributions and the original DOSBox project, on which DOSBox Staging is based.
"},{"location":"releases/release-notes/0.82.0-rc/","title":"0.82.0-RC release notes","text":"Release date: 2024-08-20
Release candidate notes
Welcome to the release candidate (RC) of DOSBox Staging 0.82.0!
What is a \u201crelease candidate\u201d? You can think of it as a \u201csneak preview\u201d of our upcoming release before we complete our full round of internal testing. As such, it might contain occasional bugs or regressions, but it should be free of major problems.
Community feedback is crucial to discovering issues in any complex software. The release candidate is intended for experienced early adopters willing to help us stabilise DOSBox Staging for the final release. If you\u2019ve found any issue in the RC, please report it to us!
Regular users who prefer a straight-line progression from one release to the next should wait for the stable release, which should come up to two months after the release candidate.
"},{"location":"releases/release-notes/0.82.0-rc/#summary","title":"Summary","text":"Just six short months after our monstre 0.81.0 release, we\u2019re back with another big one that adds Pentium MMX emulation, ESS Enhanced FM Audio, numerous audio related enhancements, a large number of game compatibility fixes, improved Windows 3.1x compatibility, experimental Windows ARM64 support, and a lot more!
Read on to learn more!
"},{"location":"releases/release-notes/0.82.0-rc/#downloads","title":"Downloads","text":"Start by downloading the 0.82.0-RC release candidate:
For those upgrading from an earlier DOSBox Staging version, please follow the upgrade instructions below.
First-time users and people migrating from other DOSBox variants should start by reading the Getting started guide.
"},{"location":"releases/release-notes/0.82.0-rc/#how-to-upgrade","title":"How to upgrade","text":""},{"location":"releases/release-notes/0.82.0-rc/#upgrading-your-primary-configuration","title":"Upgrading your primary configuration","text":"Since config settings might be renamed, altered, or deprecated between releases, it\u2019s best to let DOSBox Staging write the new default primary config on the first launch, then reapply your old settings manually.
Start by backing up your existing primary config. This is where to find it on each platform:
Windows C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox-staging.conf macOS ~/Library/Preferences/DOSBox/dosbox-staging.conf Linux ~/.config/dosbox/dosbox-staging.conf You can also execute DOSBox Staging with the --printconf option to have the location of the primary config printed to your console.
After backing up the existing primary config, simply start the new version\u2014a new dosbox-staging.conf will be written containing the new defaults and updated setting descriptions.
Portable mode notes
In portable mode, dosbox-staging.conf resides in the same folder as your DOSBox Staging executable. The migration steps for portable mode users are as follows:
- Unpack the new version into a new folder (this is important).
- Create a new empty
dosbox-staging.conf file in the new folder to enable portable mode. - Launch the new version.
DOSBox Staging will write the new defaults to the empty dosbox-staging.conf file. After this, you carry over your settings from the old primary config manually.
"},{"location":"releases/release-notes/0.82.0-rc/#after-upgrading","title":"After upgrading","text":"Look for deprecation warnings in the logs (in yellow or orange colour) and update your configs accordingly.
"},{"location":"releases/release-notes/0.82.0-rc/#game-compatibility-fixes","title":"Game compatibility fixes","text":" -
Fix regression in Command & Conquer: Red Alert where the emulator crashed after playing the game for a while.
-
Fix regression in The Magic Candle 2: The Four and Forty where the second MIDI sequence did not play.
-
Fix regression in Soltys where the Gravis UltraSound was not starting up after the game auto-detected it.
-
Fix Dunkle Schatten 2 freezing after startup.
-
Fix distorted HUD issue in the 3dfx version of Archimedean Dynasty.
-
Fix the odd horizontal black lines appearing in the following Synthetic Dimensions games:
- Chronicles of the Sword
- Druid: Daemons of the Mind
- Perfect Assassin
-
Generically fix all Windows 3.1x games that complain about enabling file sharing, asking the user to run SHARE.EXE. This fixes at least the following games:
- Comix Zone
- Garfield Caught in the Act
- Microsoft Flight Simulator (v5.0, ATC Workshop)
- Monopoly
- Ultimate Yahtzee
-
Fix the intro tune in Bumpy\u2019s Arcade Fantasy using the wrong instruments on the MT-32.
-
Fix the AdLib intro jingle not playing in Silmarlis games (e.g., Crystals of Arborea, Ishar 1 & 2, Storm Master, Transantartica, etc.)
-
Fix flipped Sound Blaster Pro 2 output filter behaviour in Doom and all games that toggle the filter programmatically.
Note - Add carry, sign, zero, and parity flags to integer division instructions (#3785)
- Clean up some leaked file handles (#3673)
- Fix decrementing of MPU-401 track and conductor counters (#3766)
- Fix file open error in ISO Drive (#3804)
- Fix programmatic toggling of the Sound Blaster Pro 2 output filter (#3815)
- Fix regression in Voodoo 16-bit memory write (#3841)
- Fix the GUS reset register\u2019s startup behavior (#3755)
- Implement File Locking (#3687)
- Import missing S3 Trio64 XGA compare and fill routines from DOSBox-X (#3775)
- Initialise the OPL operators per the AdLib v1.51 driver (#3772)
- Integrate MMX emulation (#3426)
- Move System File Table memory location (#3680)
- Use inline memory routines for MMX (#3847)
- Use linear 128 KB video memory pages for VESA modes (#3767)
- Various MT-32 improvements & fix Bumpy\u2019s Arcade Fantasy intro tune (#3729)
"},{"location":"releases/release-notes/0.82.0-rc/#graphics","title":"Graphics","text":""},{"location":"releases/release-notes/0.82.0-rc/#remove-the-openglnb-output-mode","title":"Remove the \u2018openglnb\u2019 output mode","text":"The openglnb output mode for OpenGL with nearest-neighbour interpolation has been removed (nb stood for \u201cno bilinear\u201d, which is a roundabout way to say \u201cnearest-neighbour interpolation\u201d).
When using CRT shaders or any other shader, openglnb and opengl worked exactly the same way\u2014there was zero reason for preferring openglnb over opengl.
The only legitimate use-case for openglnb was to get nearest-neighbour interpolation with uneven pixels when not setting any shader explicitly. This was a relic from the past from pre-shader times when you had to select between two bad options when aspect-ratio correction was enabled: blurry output (with bilinear filtering) or sharp output at the expense of uneven pixels (with nearest-neighbour, or \u201cno bilinear\u201d interpolation). The much better current solution in DOSBox Staging if you want the \u201csharp pixel\u201d look is to use the sharp shader.
If you really want to, you can still use nearest-neighbour interpolation with the new nearest shader. But you\u2019ll get far better results with sharp, especially on 1080p displays.
The texturenb output mode remains available as a last resort fallback for weak hardware with no functional OpenGL drivers.
"},{"location":"releases/release-notes/0.82.0-rc/#new-xbr-upscaler-shaders","title":"New xBR upscaler shaders","text":"A few of Hyllian\u2019s xBR upscaling shaders have been added for those hell-bent on playing games with a fake high-resolution look:
scaler/xbr-lv2-3dscaler/xbr-lv2-noblendscaler/xbr-lv3
"},{"location":"releases/release-notes/0.82.0-rc/#voodoo-fixes","title":"Voodoo fixes","text":"16-bit memory writes have been fixed in our Voodoo emulation; this resolves the distorted HUD issue in the 3dfx version of Archimedean Dynasty.
"},{"location":"releases/release-notes/0.82.0-rc/#s3-trio64-improvements","title":"S3 Trio64 improvements","text":" -
Fixed the hardware cursor handling on the S3 Trio64 card; this fixes the display corruption on exit issue in the Teddybear\u2019s Revenge demo by Eclipse.
-
Implemented the missing S3 Trio64 XGA compare and fill routines. This lets you use version 1.70.04 of the S3 Trio64 drivers in Windows 3.1x without issues and resolves graphical glitches in Windows 3.1x games that use XGA features, such as the demo of Critical Mass. This change improves general compatibility with games that use WinG as well.
-
Now we use linear 128 KB video memory pages for all VESA modes. Some games exploit this low-level detail of some SVGA cards to access the video memory as a single contiguous 128 KB memory block instead of manually flipping between two 64 KB pages. This enhancement gets rid of the odd horizontal black lines in the following Synthetic Dimensions games and possibly in other games and demoscene productions too that use the same hack:
- Chronicles of the Sword
- Druid \u2014 Daemons of the Mind
- Perfect Assassin
Full PR list of graphics-related changes - Add
use_nearest_texture_filter shader pragma and nearest shader (#3852) - Check if hardware cursor is actually being enabled or disabled before setting VGA_LineDraw (#3725)
- Fix assert failure from incorrectly mapping result of SDL_GL_SwapInterval() (#3844)
- Fix regression in Voodoo 16-bit memory write (#3841)
- Import missing S3 Trio64 XGA compare and fill routines from DOSBox-X (#3775)
- Kill
openglnb with fire \ud83d\udd25\ud83d\udd25\ud83d\udd25\ud83d\udd25\ud83d\udd25 (#3672) - Minor
vga_draw.cpp refactor (#3734) - Presentation mode, host rate & vsync cleanup (#3824)
- Use linear 128 KB video memory pages for VESA modes (#3767)
"},{"location":"releases/release-notes/0.82.0-rc/#sound","title":"Sound","text":""},{"location":"releases/release-notes/0.82.0-rc/#multi-threaded-audio-processing","title":"Multi-threaded audio processing","text":"Some audio devices, such as the MT-32 and FluidSynth, were already running in their own threads. We\u2019ve taken this to the next level, and now the DOSBox mixer itself has got its own dedicated thread, too. This greatly reduces and often completely eliminates audio stuttering and glitches. The improvement is especially noticeable in games that use the Roland MT-32 or FluidSynth for MIDI music, the AdLib/OPL synth, the IBM Music Feature Card (IMFC), or Red Book CD Audio.
For example, now you should get zero glitches in the intro of Eric the Unready on the MT-32 when the game repeatedly switches between 320\u00d7200 and 640\u00d7480 VGA modes.
We plan to take this approach even further in the following releases, with the ultimate goal of achieving a 100% glitch-free, hardware-like audio experience.
"},{"location":"releases/release-notes/0.82.0-rc/#ess-enhanced-fm-audio-esfm-emulation","title":"ESS Enhanced FM Audio (ESFM) emulation","text":"DOS audio connoisseurs, we have a real treat for you! We\u2019ve added support for emulating ESS Enhanced FM Audio, or ESFM, the OPL3-compatible FM synth found on later ESS AudioDrive cards.
In \u201clegacy mode\u201d, ESFM is fully compatible with the Yamaha OPL3; on most materials, it yields almost identical output (with the occasional subtle difference). What sets it apart is its \u201cnative mode\u201d, in which it offers advanced synthesis features surpassing the capabilities of the OPL3 chips. It bridges the gap between synthetic-sounding OPL music and MIDI music that uses sampled real instruments\u2014it definitely makes those expensive external MIDI modules run for their money!
Unfortunately, since ESFM was released in 1995, only a handful of games support \u201cnative mode,\u201d but in the few that do, the results sound quite spectacular!
-
To run ESFM in \u201clegacy mode\u201d, use oplmode = esfm with any Sound Blaster model and configure the game for Sound Blaster and AdLib/OPL as usual.
-
To use \u201cnative mode\u201d, set sbtype = ess and configure the ESS Technology ES1688, ES1788, ES1888 Enhanced FM Audio MIDI music driver in the game\u2019s setup utility (most games that support ESFM natively use the Miles Sound System). For the digital audio driver, select the Sound Blaster Pro option (ESS AudioDrive cards are Sound Blaster Pro compatible).
Here\u2019s a non-exhaustive list of games that support ESFM Enhanced FM music. If you discover more, please let us know!
- 11th Hour, The
- Advanced Civilization
- Callahan\u2019s Crosstime Saloon
- Gene Machine, The
- Heaven\u2019s Dawn
- Heroes of Might and Magic II
- Magic Carpet 2
- Settlers II, The
- Shannara
- Theme Hospital
- WarCraft II
- Z
Game Audio example Heroes of Might and Magic II \u2014 Title (ESFM) Your browser does not support the audio element. Heroes of Might and Magic II \u2014 Title (OPL) Your browser does not support the audio element. Heroes of Might and Magic II \u2014 In-game (ESFM) Your browser does not support the audio element. Heroes of Might and Magic II \u2014 In-game (OPL) Your browser does not support the audio element. The Settlers 2 \u2014 Track 5 (ESFM) Your browser does not support the audio element. The Settlers 2 \u2014 Track 5 (OPL) Your browser does not support the audio element. The Settlers 2 \u2014 Track 14 (ESFM) Your browser does not support the audio element. The Settlers 2 \u2014 Track 14 (OPL) Your browser does not support the audio element. The Gene Machine (ESFM) Your browser does not support the audio element. The Gene Machine (OPL) Your browser does not support the audio element. Heaven\u2019s Dawn (ESFM) Your browser does not support the audio element. Heaven\u2019s Dawn (OPL) Your browser does not support the audio element. The more adventurous among you can also try to \u201cretrofit\u201d the ESFM.MID driver from Miles Sound System games that have it into earlier ones that don\u2019t.
Here\u2019s how Discworld sounds with the ESFM driver from Heaven\u2019s Dawn\u2014it\u2019s pretty great, sounds almost like sample-based music!
Discworld (ESFM) Your browser does not support the audio element. Discworld (OPL) Your browser does not support the audio element."},{"location":"releases/release-notes/0.82.0-rc/#adlibopl-dc-bias-remover","title":"AdLib/OPL DC bias remover","text":"Some games like Golden Eagle and Wizardry VI: Bane of the Cosmic Forge play digitised music and sound effects using the OPL (AdLib) channels by rapidly changing the volume in very crude steps, similar to how the Disney Sound System and Covox LPT DAC operate.
We\u2019ve introduced a new opl_remove_dc_bias config setting to the [sblaster] section, eliminating these annoying pops in affected games.
Recommended audio settings for Wizardry VI: Bane of the Cosmic Forge when configured for AdLib sound:
[sblaster]\nsbtype = none\noplmode = opl2\nopl_remove_dc_bias = true\nopl_filter = lpf 2 5500\n\n[speaker]\npcspeaker = off\n\n[autoexec]\nmixer opl 500\n
"},{"location":"releases/release-notes/0.82.0-rc/#default-to-the-impulse-pc-speaker-model","title":"Default to the \u2018impulse\u2019 PC speaker model","text":"The impulse PC speaker model has been made the default option as it emulates the iconic little speaker found in old PCs more faithfully and with fewer overall issues.
The catch is that a small percentage of games have problems with it, so you might need to revert to the legacy and less accurate discrete model on a per-game basis.
"},{"location":"releases/release-notes/0.82.0-rc/#decouple-cms-and-adlibopl-emulation","title":"Decouple CMS and AdLib/OPL emulation","text":"The CMS (Creative Sound System or Game Blaster) and OPL (AdLib) emulations have finally been decoupled. DOSBox always treated the emulation of the CMS as \u201cjust another OPL option\u201d, which was completely wrong as the AdLib and the CMS use different sound chips and have nothing to do with each other.
This resulted in various complications, such as oplmode = opl2 always enabling CMS emulation as well (probably to allow emulating early Sound Blaster cards that featured both the OPL2 and CMS chips).
The new model allows the user to control the OPL and CMS emulations separately:
oplmode only determines the type of OPL chip(s) to emulate. Valid values are none, opl2, dualopl2, opl3, and opl3gold.- The new
cms config setting in the [sblaster] section controls whether to emulate the CMS. Valid values are on and off.
Warning
As usual, oplmode = cms is still accepted with a deprecation warning, but you should update your configs to use the new model as we might remove support for the legacy settings in the future.
"},{"location":"releases/release-notes/0.82.0-rc/#sound-blaster-pro-2-output-filter-fix","title":"Sound Blaster Pro 2 output filter fix","text":"Previously, toggling the analog output filter programmatically on the Sound Blaster Pro 2 (sbtype = sbpro2) was flipped due to a coding error. You can hear the difference in games that toggle the filter, such as Doom, when configured for the SB Pro 2 and authentic output filter emulation is enabled with sb_filter = auto.
"},{"location":"releases/release-notes/0.82.0-rc/#adlibopl-improvements","title":"AdLib/OPL improvements","text":"The OPL (AdLib) chip is now initialised with the official AdLib v1.51 driver\u2019s startup values instead of the chip\u2019s native power-on state. Most games don\u2019t care about this because they fully overwrite the card with whatever state they need at startup, but this fixed the missing intro jingle in the following Silmarils games:
- Boston Bomb Club
- Bunny Bricks
- Crystals of Arborea
- Ishar 1
- Ishar 2
- Metal Mutant
- Storm Master
- Transantartica
"},{"location":"releases/release-notes/0.82.0-rc/#further-mixer-improvements","title":"Further mixer improvements","text":" -
Fix lower-pitched audio bug when the emulated audio device\u2019s sample rate exceeds the host sample rate. E.g., if a program uses the maximum native 45\u2009454 Hz Sound Blaster rate and the host rate is 44\u2009100 Hz.
-
Host sample rates can now be set continuously from 8000 Hz to 96 kHz. This makes DOSBox Staging fully placebo and audio snake oil compliant! Also, by setting custom sample rates, you can capture audio at an emulated device\u2019s native rate without resampling.
-
blocksize can now be set to non-power-of-two values, too.
-
The nosound option now works better because it renders the audio and progresses the audio frames rendered counters (e.g., FastTracker II now plays the module even in \u201cno sound\u201d mode; previously, it was completely stalled). Additionally, you can now capture the audio to a WAV file even in \u201cno sound\u201d mode.
"},{"location":"releases/release-notes/0.82.0-rc/#other-audio-improvements","title":"Other audio improvements","text":" -
The Gravis UltraSound and Sound Blaster can coexist now when you run ULTRINIT.EXE. This way, you can use the SB for digital sound effects and GUS for MIDI music via ULTRAMID.EXE or MEGAEM.EXE in supported games.
-
Turn off the \u201ccable delay\u201d emulation MIDI for the MT-32. This fixes the intro tune in Bumpy\u2019s Arcade Fantasy, and probably other game startup issues, too.
-
Use 16-bit integer rendering mode for the MT-32 which is more accurate to the real hardware and much faster. Also, use \u201cnice\u201d partials mode and render at libmt32\u2019s 48 kHz \u201canalog emulation\u201d rate for improved authenticity.
-
Map the Capture MIDI action to Ctrl+Alt+F6 by default (Cmd+Option+F6 on macOS).
-
Reading audio data from physical CD-ROMs is now done in a separate thread, which should eliminate latency and stuttering issues.
-
Windows CD-ROM audio is now routed through the DOSBox mixer, bringing it to feature parity with Linux.
-
Fix no CD Audio issue on Windows if using a USB CD drive (SATA drives worked fine).
-
The strength of the tiny reverb preset has been reduced by 25% as it sounded too strong; now it simulates the natural reverberation of a domestic room better.
Full PR list of sound-related changes - Add a simple DC bias remover for the OPL output (#3310)
- Add support for ESS mixer registers (#3702)
- Decouple CMS and OPL emulations (#3559)
- ESFM emulation (#3614)
- Fix CD audio support on physical USB drives on Windows (#3840)
- Fix ESS mixer volume handling (#3705)
- Fix Ring Buffer PrevIndex() wrapping behavior for non power of 2 size (#3813)
- Fix Sound Blaster programmatic low-pass filter toggling behaviour (#3712)
- Fix decrementing of MPU-401 track and conductor counters (#3766)
- Fix programmatic toggling of the Sound Blaster Pro 2 output filter (#3815)
- Fix the GUS reset register\u2019s startup behavior (#3755)
- Further mixer fixes and improvements mega PR #2 (#3756)
- Improve
sbtype and oplmode descriptions & clean up sblaster.cpp (#3566) - Improve tiny reverb preset for small-speaker emulation (#3867)
- Initialise the OPL operators per the AdLib v1.51 driver (#3772)
- Make the
impulse PC speaker model the default (#3851) - Map \u2018Capture MIDI action\u2019 to Ctrl+Alt+F6 (Cmd+Opt+F6) by default (#3714)
- Mirror the Adlib command port (388h) in the GUS (#3763)
- Move mixer to a seperate thread (#3848)
- Rework physical CDROM interface (#3591)
- Show the mixer who\u2019s boss \ud83d\ude0e (#3650)
- Sync Nuked-OPL3 with upstream (#3818)
- Various MT-32 improvements & fix Bumpy\u2019s Arcade Fantasy intro tune (#3729)
"},{"location":"releases/release-notes/0.82.0-rc/#input","title":"Input","text":" -
Fix hang on exiting DOSBox Staging after pressing the Pause key.
-
General keyboard handling accuracy improvements, allowing us to get rid of the Ultima VIII game-specific hack.
Full PR list of input-related changes - Fix hang on exit after pressing the pause key (#3671)
- Replace Ultima VIII keyboard hack with a proper solution (#3784)
"},{"location":"releases/release-notes/0.82.0-rc/#dos-integration","title":"DOS integration","text":""},{"location":"releases/release-notes/0.82.0-rc/#new-mode-command","title":"New MODE command","text":"A new MODE command has been added to set the display mode of the DOS prompt and the keyboard\u2019s typematic rate. The command is loosely based on the original MS-DOS MODE command, but it supports a lot more display modes.
Examples of setting a custom text mode:
mode 80x30\nmode 80x43\nmode 132x34\n
Setting the fastest key repeat with the shortest repeat delay (everybody\u2019s favourite):
mode rate=32 delay=1\n
Run mode /? to see the full list of options.
"},{"location":"releases/release-notes/0.82.0-rc/#file-sharing-support","title":"File sharing support","text":"Certain Windows 3.1x programs that rely on SHARE.EXE or VSHARE.386 would display an error on startup, complaining that SHARE.EXE has not been loaded. This mostly affects office programs (e.g., Microsoft Office, Lotus Office, Peachtree Complete Accounting, etc.), but also a few games.
The previous workaround was to rely on a small utility called FAKESHAR.COM which, as the name implies, fakes that SHARE.EXE is running. This worked mostly fine with games but could lead to data corruption when using application programs.
We\u2019ve added support for file sharing and locking, which means workarounds like FAKESHAR.COM are no longer necessary. All Windows 3.1x games that complain about SHARE.EXE not running should now work out-of-the-box. This fixes at least the following games:
- Comix Zone
- Garfield Caught in the Act
- Microsoft Flight Simulator (v5.0, ATC Workshop)
- Monopoly
- Ultimate Yahtzee
"},{"location":"releases/release-notes/0.82.0-rc/#improved-physical-cd-rom-mounting","title":"Improved physical CD-ROM mounting","text":"Physical CD-ROM devices are now auto-detected when using the MOUNT command\u2014no more need to use the additional clunky -usecd parameter (this has been removed).
For example:
- Windows:
mount d d:\\ -t cdrom - Linux:
mount d /mnt/cdrom -t cdrom
"},{"location":"releases/release-notes/0.82.0-rc/#other-dos-integration-improvements","title":"Other DOS integration improvements","text":" -
LOADFIX can now be used with batch files.
-
Fix improper handling of some special characters in shell history.
-
Improve redirection handling in the DOS shell. This helps with a few game installers (e.g., running the B-Wing Add-On installer for X-Wing corrupted the game files without this fix).
-
More accurate System File Table (SFT) emulation. This helps with some game compatibility issues, e.g. Dunkle Shatten 2 was freezing without this fix.
-
The DEBUG and XCOPY commands from FreeDOS have been updated to their latest versions.
Full PR list of DOS integration related changes - Add MODE command & various text mode improvements (#3741)
- Allow loadfix to execute batch files (#3657)
- Clean up some leaked file handles (#3673)
- Do not hard exit when running
SET /P (#3789) - Fix Windows 3.1 regression from SFT change (#3744)
- Fix broken shell_history_file config option (std::weak_ptr version) (#3664)
- Fix improper handling of some characters in shell history (#3791)
- Fix shell history creation regression (#3485)
- Fix shell redirection for appending to the end of a file (#3873)
- Implement File Locking (#3687)
- Improve redirection handling in the DOS shell (#3838)
- Keep file handle instead of entry in FileReader (#3528)
- MODE command fixes & improvements (#3853)
- Move System File Table memory location (#3680)
- Move environment functions to psp (+ other small changes) (#3093)
- Replace use of
stat in imgmount (#3465) - The great DOS_File/DOS_Drive Refactor (plus some timestamp improvements) (#3786)
- Update bundled FreeDOS binaries (#3876)
- Use native file I/O in local and overlay drive (#3765)
- Use wrapping behavior on localFile seek position (#3779)
"},{"location":"releases/release-notes/0.82.0-rc/#general","title":"General","text":""},{"location":"releases/release-notes/0.82.0-rc/#pentium-mmx-emulation","title":"Pentium MMX emulation","text":"Finally, we\u2019ve added Pentium MMX instruction set emulation to run late-90s demoscene productions (e.g., heaven seven by Exceed) and the odd game with MMX-specific enhancements (e.g., Extreme Assault and Z.A.R.). And yeah, now you can use the MMX-only real-time resonant filters in Impulse Tracker, too
You must enable MMX emulation explicitly by setting cputype = pentium_mmx in your config. All normal and dynamic cores are supported on all platforms.
"},{"location":"releases/release-notes/0.82.0-rc/#simplified-cpu-cycles-settings","title":"Simplified CPU cycles settings","text":"The cycles setting has been a source of a lot of confusion, so we\u2019ve replaced it with a much simpler way to configure the emulated CPU speed (believe it or not, there are over 20 valid cycles value permutations!)
The new streamlined CPU cycles settings are as follows:
cpu_cycles \u2014 Global or real mode only cycles setting.cpu_cycles_protected \u2014 Optional protected mode only cycles setting.cpu_throttle \u2014 Whether the CPU emulation should be dynamically throttled if your host CPU cannot keep up.
Please refer to the settings\u2019 descriptions to learn more (e.g., run config -h cpu_cycles from the DOS prompt).
Here are a few concrete examples:
Set fixed speed globally
This will roughly emulate the speed of the venerable i486DX2-66 in both real and protected mode. cpu_cycles_protected = auto means cpu_cycles controls the emulated CPU speed globally, both for real and protected mode.
[cpu]\ncpu_cycles = 25000\ncpu_cycles_protected = auto\n
Different real and protected mode speeds with throttling
20k cycles for real mode programs, and 400k for protected mode. Throttling is enabled, so if your host machine can\u2019t keep up, the actual number of emulated CPU cycles per millisecond will be dynamically lowered.
[cpu]\ncpu_cycles = 20000\ncpu_cycles_protected = 400000\ncpu_throttle = on\n
Max speed
This will make the CPU emulation run as fast as your computer can handle it. Pretty useful when compiling programs, rendering 3D images, or playing late \u201990s 3D games at 640\u00d7480 or higher resolutions (as long as they can run glitch-free on very fast CPUs).
[cpu]\ncpu_cycles = max\ncpu_cycles_protected = max\n
Backward compatibility with cycles
The legacy cycles setting is still available for backward compatibility with existing configs. When cycles is set, the new CPU settings are simply ignored. Do note, however, that we might remove support for cycles in the future; please start migrating your configs to the new settings now.
"},{"location":"releases/release-notes/0.82.0-rc/#revised-cpu-cycles-defaults","title":"Revised CPU cycles defaults","text":"Summary of changes
-
The default emulated CPU speed (cycles) setting for protected mode programs has been changed from max to 60\u2009000 cycles.
-
The real mode default of 3000 cycles is unchanged.
-
When \u201clegacy cycles mode\u201d is enabled by setting cycles explicitly, the old \u201cmax cycles\u201d protected mode default applies.
DOSBox traditionally defaulted to 3000 cycles for real mode programs, and \u201cmax cycles\u201d (as fast as your host CPU can go) for protected mode programs. 3000 cycles for real mode is a good middle-of-the-road setting that gets most games running (even if not optimally). The \u201cmax cycles\u201d setting, on the other hand, is quite problematic for a couple of reasons:
-
A significant number of games crash, misbehave, or manifest subtle bugs when the emulated CPU is \u201ctoo fast\u201d. In the early days of DOSBox, cycles = max was not a problem because the much slower host CPUs from 10-20 years ago acted as a \u201cnatural throttle\u201d on the effective emulation speed. However, many of those old speed-sensitive games that used to work with cycles = max are now broken on today\u2019s fast CPUs.
-
The max setting is not transferable across setups as it depends on the host CPU\u2019s speed. Games configured for cycles = max might work fine on your particular machine, but they could break on your friend\u2019s faster computer or yours a few years later when you get your next CPU upgrade. The max N% cycles setting (e.g., max 70%) is plagued by the same problem.
-
cycles = max often causes audio glitches and drop-outs in games. It\u2019s best to use the lowest fixed cycles value that runs the game at an acceptable speed (read more tips about that here).
-
Some DOS programs really freak out when the emulated CPU is being dynamically changed at runtime, which is what max tends to do.
All in all, max for protected mode is not a good default in 2024, so we\u2019ve changed it to fixed 60\u2009000 cycles, which is roughly equivalent to slow Pentium speeds. As protected mode games started appearing in the early to mid-90s, this should run the vast majority of games fairly optimally out-of-the-box.
"},{"location":"releases/release-notes/0.82.0-rc/#cputype-normalisation","title":"\u2018cputype\u2019 normalisation","text":"After introducing the pentium_mmx CPU type, we felt the need to clean up the cputype options a bit and make them more logical:
386_slow has been renamed to 386386 has been renamed to 386_fast486_slow has been renamed to 486pentium_slow has been renamed to pentium
Please refer to the description of the cputype setting for further info (e.g., execute config -h cputype from the DOS prompt).
The descriptions of all CPU settings have been extensively revised and now include helpful hints, so it\u2019s recommended that you familiarise yourself with them (run config -h cpu to see the complete list of CPU settings).
Warning
The old renamed cputype values are still accepted with a deprecation warning, but you should update your configs to use the new values, as we might remove support for the legacy settings in the future.
"},{"location":"releases/release-notes/0.82.0-rc/#improved-config-command","title":"Improved CONFIG command","text":"The CONFIG command\u2019s output is now paginated when you use it to display a config setting\u2019s description (e.g., config -h glshader of config -h cpu_cycles). Previously you had to pipe the output through the MORE command to paginate the output, which was a hassle (i.e., config -h glshader | more).
The formatting and colouring of the CONFIG command\u2019s output has also been improved.
"},{"location":"releases/release-notes/0.82.0-rc/#configurable-window-title-bar","title":"Configurable window title bar","text":"You can now fully customise the information displayed in the emulator window\u2019s title bar.
For example, this configuration
[sdl]\nwindow_titlebar = program=none version=detailed mouse=short\n
yields the following to be displayed in the title bar:
DOSBox Staging 0.82.0-alpha (9fdba) - 3000 cycles/ms\n
An animated audio/video capturing indicator and a pause indicator has also been added.
Please refer to the window_titlebar setting\u2019s description to learn about the available options (e.g., run config -h window_titlebar from the DOS prompt).
"},{"location":"releases/release-notes/0.82.0-rc/#read-only-directory-mounts","title":"Read-only directory mounts","text":"The MOUNT command now accepts the -ro flag to create read-only (write-protected) directory mounts (the IMGMOUNT command already had this option).
For auto-mounts, you can specify readonly = true in the [drive] section of the mount config file (see resources).
Additionally, the built-in Y drive has been made read-only by default (you can change this in resources/drives/y.conf, of course, if you want to).
"},{"location":"releases/release-notes/0.82.0-rc/#experimental-windows-arm64-builds","title":"Experimental Windows ARM64 builds","text":"We\u2019re ready for the ARM revolution!
Luckily, we already have a battle-tested dynamic ARM recompiler that we\u2019ve been using for the Apple Silicon macOS builds, so we started providing experimental Windows ARM64 packages for devices such as the Snapdragon X Elite.
The ARM64 packages can be downloaded from our development builds page (requires a GitHub account).
We don\u2019t provide any official support for the experimental Windows ARM64 builds yet.
"},{"location":"releases/release-notes/0.82.0-rc/#other-general-improvements","title":"Other general improvements","text":" -
The IPX server has been moved into its own dedicated thread. This should improve multi-player game performance, especially for the host running the IPX server.
-
The IBM Extended Density Format (XDF) was used by IBM for software distribution on 5.25\u201d and 3.5\u201d media. XDF image files were often provided by IBM on CD-ROMs, bulletin boards, and FTP sites.
-
A more realistic implementation of the Time Stamp Counter (TSC) found on Pentium and later CPUs, often used to determine the CPU clock. Now various benchmark software should display more realistic CPU speeds (e.g., HWINFO and SiSoft Sandra). Games don\u2019t seem to be affected by this improvement.
-
Software-initiated reset requests now restart the emulator instead of crashing it. The reset message has been improved and now includes a countdown counter.
Full PR list of miscellaneous enhancements - Add IBM XDF floppy support (#3442)
- Add carry, sign, zero, and parity flags to integer division instructions (#3785)
CONFIG command enhancements (#3667)- Config setting improvements and
CONFIG command fixes (#3754) - Fix MMX crash on moralhardcandy (#3814)
- Fix switch to dynamic core warning edge case (#3732)
- Fix warning when using a high cycles value on a non-dynamic core (#3716)
- Implement read-only mounting + make Y drive read-only by default (#3711)
- Improve reset handler (#3696)
- Improve the
core and cputype setting descriptions (#3708) - Improve title bar and make it configurable (#3249)
- Integrate MMX emulation (#3426)
- Introduce a better way to set the CPU cycles with new defaults (#3681)
- Make the Time Stamp Counter more realistic (#3471)
- Move IPX server to a background thread (#3414)
- Paginate the CONFIG command\u2019s output (#3758)
- Show memory read breakpoint with BPLIST (#3396)
Full PR list of miscellaneous fixes - Add DOS Files to shutdown step to avoid a crash when shutting down (#3801)
- Allow running the
INTRO built-in from subshells (#3665) - Avoid unnecessary new-lines (#3617)
CONFIG -h should only list visible setting values (#3753)- Fix \u2018output\u2019 and other \u2018sdl\u2019 settings not changeable in runtime (#3571)
- Fix IPX ping value display (#3418)
- Fix Reboot Handler crash (#3683)
- Fix file open error in ISO Drive (#3804)
- Make parameter addresses properly sized in ppc64le dynrec (fixes #3686) (#3718)
- Use CreateFileW on Windows to create file in local_drive_create_file() (#3746)
Full PR list of documentation-related changes - Add bisecting notes to build documentation (#3816)
- Add comment about PPC64 big-endian and running 32-bit BE code (#3827)
- Add warning about CMake support being experimental (#3790)
- Clarify build instructions for low memory targets (#3658)
- Create .clang-tidy (#3423)
- Remove -usecd and -listcd MOUNT parameters from INTRO and the README (#3625)
- Simple documentation fixes (#3782)
- Update Windows build guide (#3424)
Full PR list of project maintenance related changes - Add Debian package build scripts and workflow (#3809)
- Advance vcpkg baseline to upgrade to SDL 2.30.0 (#3606)
- Allow SDL wraps to be bypassed on macOS (#3483)
- Audio cleanups (#3615)
- Avoid the use of std::string_view::data() (#3542)
- Basic CMake support (#3361)
- Bump Coverity build from Clang 14 to Clang 15 (#3419)
- Bump PVS Studio CI from Clang 14 to Clang 15 (#3437)
- Bump vcpkg baseline and update to upstream libslirp v4.8.0 (#3761)
- Callback code generation rework (#3748)
- Centralize app_id handling (continuation) (#3854)
- Change ppc64 to use correct
POWERPC target (#3826) - Clean up macOS notarization script (#3408)
- Cleanup a few warnings in cdrom_image.cpp (#3472)
- Cleanup of using namespace (#3444)
- Cleanup some missed C++ header conversions (#3412)
- Create new cross compiler docker images and adjust workflows (#3678)
- Do not auto-run DOSBox Staging after installing it on Windows (#3583)
- DYN_LOG: Fix formatting type mismatch (#3869)
- Eliminate excessive repeat heap calls during normal runtime (#3812)
- Fix CDROM_Interface pointer ownership issue (#3634)
- Fix MSVC CI builds (#3474)
- Fix compilation warnings reported by g++ 14.1 (#3783)
- Fix issue with replace() (#3533)
- Fix macOS CI workflow (#3505)
- Fix sed creating backup files ending with \u201c-e\u201d in macOS bundle (#3406)
- Fix some PVS warnings (#3484)
- Fix variables optimizing away when debugging MSClang builds (#3397)
- Fix vcredist version for MSVC CI runner (#3480)
- Ignore meson.build in VS tests project (#3422)
- Introduce custom release notes drafter script & workflow (#3398)
- Make GCC 11 / Ubuntu 22.04 the minimum build target (#3674)
- Mass update copyright dates (#3584)
- Migrate to C++20 (#3286)
- Minor FPU cleanup (#3837)
- More PVS warning fixes (#3494)
- Pin CMake version for MSVC runner (#3598)
- Reinstate creating the Windows installer package in CI (#3849)
- Release drafter enhancements (#3546)
- Remove Debian 10 support (#3534)
- Remove GCC_LIKELY/GCC_UNLIKELY (#3293)
- Search for numbered clang-format binaries in format-commit.sh (#3747)
- Unicode API refactoring (#3797)
- Unify use of prop->Set_values (#3572)
- Update simde to 0.8.0 (#3522)
- Update string_utils to use C++20 constructs (#3540)
- Upgrade SIMDE to 0.8.2 (#3662)
- Upgrade Windows CI setup-msbuild GitHub action (#3477)
- Usage of integer types & disabling sign conversion warnings (#3631)
- Use C++ system headers (#3284)
- Use GitHub actions cache for vcpkg (#3503)
- Use GitHub runners for macOS builds (#3384)
Full PR list of other changes - Allow the PVS-Studio workflow run in forked PRs (#3493)
- Build Windows package for the ARM64 platform (#3823)
- Don\u2019t execute compile workflows on documentation and script changes (#3393)
- Fix division regression by resetting flag type (#3795)
- Fix fs_utils_tests for macOS and enable test runs on macOS CI (#3622)
- Fix msys2 compilation error with cdrom_win32.cpp (#3676)
- Introduce unittests for the Value class (#3369)
- Minor fix to x87 64-bit memcpy (#3866)
- Remove hard-coded version string from MSVC CI (#3736)
- Upgrade deprecated Node.js 16 GitHub actions to latest (#3457)
- website: Add NixOS install instructions (#3479)
"},{"location":"releases/release-notes/0.82.0-rc/#localisation","title":"Localisation","text":" - Update Dutch, Italian, Polish, Portugese, and Spanish translations.
- Use uncompressed CPI code page files instead of the compressed FreeDOS-specific CPX format. This improves code page switching performance, which was rather slow with low
cpu_cycles settings. - Ensure all platform-specific translatable strings are visible to the translators.
Full PR list of localisation-related changes - Avoid false positive warnings in translations (#3610)
- Further refinements to the Italian (it) translation (#3880)
- Improve italian (it) translation (#3877)
- Translations differ between platforms (#3579)
- Update Dutch (nl) translation (#3874)
- Update Italian (it) translation (#3871)
- Update Polish (pl) translation (#3870)
- Update Polish (pl) translation, minor help string fix (#3850)
- Update Polish (pl) translation, minor string fixes (#3684)
- Update Portuguese Translation (#3609)
- Update Spanish translation (#3624)
- Update italian (it) translation (#3751)
- Use uncompressed CPI files instead of compressed CPX ones (#3413)
"},{"location":"releases/release-notes/0.82.0-rc/#contributors","title":"Contributors","text":"The following commit authors, sponsors, supporters, and backers all invested their time or funds into the 0.82 release effort. Thank you!
Contributors are listed in alphabetic order.
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":"releases/release-notes/0.82.0-rc/#082-commit-authors","title":"0.82 commit authors","text":" - altiereslima
- Arcnor
- bluddy
- classilla
- dreamer
- farsil
- FeralChild64
- ftortoriello
- Grounded0
- interloper98
- japsmits
- johnnovak
- Kappa971
- kcgen
- keenanweaver
- kklobe
- LowLevelMahn
- MeAreJeenius
- rderooy
- Ringdingcoder
- shermp
- stackErr-NameNotResolved
- strikersix23
- Torinde
- weirddan455
"},{"location":"releases/release-notes/0.82.0-rc/#082-sponsors","title":"0.82 sponsors","text":""},{"location":"releases/release-notes/0.82.0-rc/#082-supporters","title":"0.82 supporters","text":""},{"location":"releases/release-notes/0.82.0-rc/#082-backers","title":"0.82 backers","text":" - BenBudr
- Burrito78
- Diduz
- Florent Wagner
- Hannu Hartikainen
- Hugo Lucorcio
- Robin Mattheussen
"},{"location":"releases/release-notes/0.82.0-rc/#thank-you","title":"Thank you","text":"We are grateful for all the community contributions and the original DOSBox project, on which DOSBox Staging is based.
"}]}
\ 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 a (mostly) drop-in replacement for older DOSBox versions\u2014your existing configurations will continue to work, and you will have access to many advanced features.
DOSBox Staging comes with sensible defaults, so you\u2019ll need to write a lot less configuration than with older DOSBox versions. Most games and applications 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 delve deeper. Please refer to the Feature highlights on our front page to learn more about these.
The key features for developers are summarised here.
"},{"location":"about/#goals","title":"Goals","text":" - Faithfully emulate the DOS operating environment running on IBM PC compatibles and the IBM PCjr, with the primary goal of running all PC Booter, DOS and Windows 3.x games released in the 1981\u20132000 period. Running applications and demoscene productions or more recent DOS software is a secondary objective.
- Improve the out-of-the-box experience.
- Provide a self-contained emulator that requires no extra legacy or \u201cmodern retro\u201d hardware to function.
- Focus on supporting up-to-date, current operating systems and modern hardware.
- Implement new features and quality-of-life improvements.
- Deliver a consistent cross-platform experience.
- Leverage upstream and community developments in DOSBox.
- Encourage new contributors by removing barriers to entry.
- Prioritise code quality to minimise technical debt and ease maintenance. This generally means following the Staging Coding Style Guide and best practices such as the C++ Core Guidelines.
"},{"location":"about/#non-goals","title":"Non-goals","text":" -
Support old, end-of-life operating systems (e.g., Windows 7 or older, OS/2, Mac OS X 10.5 or older) and limited CPU/memory hardware, which are constraints the original DOSBox continues to support.
-
Support legacy or \u201cmodern retro\u201d hardware. DOSBox Staging is a self-contained emulator; its aim is to emulate all PC hardware it supports in software. Legacy and retro hardware are not supported (e.g., ISA boards, CRT monitors, RetroWave OPL3 and similar devices, etc.).
-
Support the use of Windows 9x/Me in the emulator. Windows 9x/Me emulation is supported by projects such as QEMU, VirtualBox and the DOSBox-X and DOSBox Pure forks.
-
Pursue hardware accuracy above all else. If you\u2019re after a more faithful emulation of an entire PC, look into MartyPC, PCem, 86Box, PCBox, QEMU or VirtualBox (although DOSBox Staging often matches or surpasses the graphics and especially audio emulation fidelity of these other 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.
"},{"location":"about/#relationship-to-the-original-dosbox-project","title":"Relationship to the original DOSBox project","text":"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":"about/#data-privacy-policy","title":"Data privacy policy","text":"DOSBox Staging never collects any personal information about you or your computer, and it never connects to the Internet or any network without you asking it to do so in the first place (e.g., by running BBS software or playing multiplayer DOS games over Ethernet).
"},{"location":"about/#disclaimer","title":"Disclaimer","text":"Free for personal use, but no warranties!
Although we do our best to emulate the DOS environment and legacy IBM PC hardware as accurately as we can, we cannot guarantee DOSBox Staging has zero bugs or can run every single DOS software ever written 100% correctly.
Under no circumstances should DOSBox Staging be used for professional applications, especially where DOS software malfunctioning due to emulation bugs or inaccuracies could result in significant financial loss, data loss, or putting living beings at risk.
Neither the members of the DOSBox Staging team nor our contributors can be held responsible for such unfortunate accidents resulting from the misuse of our software. DOSBox Staging is intended for personal use only in low-stakes scenarios, such as playing DOS games, watching demoscene productions, or researching the history of IBM PC compatibles and the DOS software catalogue.
If you disregard this and get into trouble, you\u2019re on your own!
IEEE 754 80-bit extended precision floating point emulation
One particularly risky area is engineering software that requires accurate 80-bit extended precision x87 FPU emulation to function correctly. Support for 80-bit floats is not available on all platforms that DOSBox Staging runs on. The logs will warn you about this at startup:
FPU: Using reduced-precision floating-point\n
Do note, however, that the lack of such log messages does not imply or guarantee bug-free operation!
"},{"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.
"},{"location":"get-involved/code-of-conduct/#reporting-issues","title":"Reporting issues","text":"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/","title":"Index","text":"Dummy page for redirecting links to to top-level sections
"},{"location":"getting-started/advanced-graphics-options/","title":"Advanced graphics options","text":""},{"location":"getting-started/advanced-graphics-options/#aspect-ratios-square-pixels-black-borders","title":"Aspect ratios, square pixels & black borders","text":"Okay, let\u2019s tackle the pressing question every second person wants an answer for: why doesn\u2019t the image fill the screen completely? And why are there black borders around it? (Well, that\u2019s two questions, but never mind.)
Computer monitors were originally not widescreen but had a 4:3 display 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 CRT screen. When displaying such 4:3 aspect ratio content on a 16:9 modern flat panel, you\u2019ll get black bars on the sides of the image. This is called pillarboxing.
Pillarboxing in action: black bars fill the extra spacewhen the aspect ratio of the screen and the image do not match
Hang on a second, something is not right here! 320:200 can be simplified to 16:10, which is quite close to 16:9, which means 320\u00d7200 resolution content should fill a 16:9 screen almost completely with only very minor pillarboxing! Sure, that would be true if the pixels of the 320\u00d7200 VGA mode were perfect little squares, but they are not. How so?
As mentioned, 320\u00d7200 graphics completely fill the screen on a 4:3 aspect ratio CRT\u2014but that\u2019s only possible if the pixels are not perfect squares, but slightly tall rectangles. With square pixels, you\u2019d get some letterboxing below the image (the horizontal version of pillarboxing) as shown in the below image. If you do the maths, it turns out the pixels need to be exactly 20% taller than wide.
Left: 320\u00d7200 pixel image with square pixels on a 4:3 monitor\u2014there is some letterboxing below the image; Right: the same image with 20% taller pixels on the same monitor\u2014the image fills the screen completely
Here\u2019s how to derive it: 4:3 can be rewritten as 320:240 if you multiply both the numerator and denominator by 80. Then 240 divided by 200 is 1.2, so the pixel aspect ratio is 1:1.2, which can be rewritten as 5:6. (Pixel aspect ratio, or PAR in short, is the mathematical ratio that describes how the width of a pixel compares to its height.)
But hey, not everybody likes maths, especially not in the middle of a gaming session! Most of the time, you won\u2019t need to worry about aspect ratio correctness because DOSBox Staging handles that automatically for you. There is a small but significant number of games though where forcing square pixels yields better results as we\u2019ve seen in our Beneath the Steel Sky example.
When 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 any old computer magazine from the 1980s and the \u201990s, most screenshots are shown in the correct aspect ratio (but 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 video modes with non-square pixels, e.g., the 640\u00d7350 EGA mode with 1:1.3714 PAR, the 640\u00d7200 EGA mode (1:2.4 PAR), and the 720\u00d7348 Hercules graphics mode (1:1.5517 PAR).
"},{"location":"getting-started/advanced-graphics-options/#integer-scaling","title":"Integer scaling","text":"That explains the black bars on the sides, but what about the letterboxing we sometimes see above and below the image? Why doesn\u2019t the graphics fill the screen vertically and why does it change size, depending on the DOS video mode?
Again, we need a little history lesson to understand what\u2019s going on. CRT monitors did not have a fixed pixel grid like modern flat panels; they were a lot more flexible and could display any resolution within the physical limits of the monitor. They did not even have discrete \u201cpixels\u201d in the sense that modern flat panels do\u2014the image was literally projected onto the screen, similarly to how a movie projector works.
Modern flat screens, however, do have a fixed native resolution. The scanlines of the emulated CRT image need to \u201cline up\u201d with this fixed pixel grid vertically, otherwise we might get interference artifacts. These usually manifest as wavy vertical patterns and look rather unpleasant. When DOSBox Staging enlarges the emulated image to fill the screen, by default it constrains the vertical scaling factor to integer values. This ensures perfect alignment with the native pixel grid of the display. The horizontal direction is rarely a problem, so non-integer horizontal scaling factors are generally fine.
Assuming a 4K monitor with 3840\u00d72160 native resolution, the 320\u00d7200 VGA mode double-scanned to 640\u00d7400 will be enlarged by a factor of 5 vertically. The horizontal scaling factor will be 5 \u00d7 4/3 = 6.6667 to maintain the correct 4:3 aspect ratio of the upscaled image. This results in a final output of 2667\u00d72000 pixels. Those 160 unused pixels in the vertical direction account for the slight letterboxing above and below the image.
Now, the higher your monitor resolution, the more you can get away with using non-integer vertical scaling ratios. It\u2019s just that enabling vertical integer scaling by default is the only surefire way to completely avoid ugly interference artifacts on everybody\u2019s monitors out-of-the-box. If you play games in fullscreen on a 4K screen, you can safely disable integer scaling without any adverse effects up to the 640\u00d7480 VGA resolution. Just put the following into your config:
[render]\ninteger_scaling = off\n
If you don\u2019t have a 4K monitor or you like to play your games in windowed mode, you\u2019ll need to experiment a bit\u2014some monitor resolution, window size, and DOS video mode combinations look fine without integer scaling, some will result in interference patterns.
"},{"location":"getting-started/advanced-graphics-options/#sharp-pixels","title":"Sharp pixels","text":"\u201cOkay, enough blabbering about all those near-extinct, mythical cathode-ray tube contraptions, grandpa. Can\u2019t you just give us sharp pixels and be done with it?\u201d
Sure thing, kiddo. Just put this into your config:
[render]\nglshader = sharp\n
By default, integer scaling is disabled when the sharp shader is selected, so if you want to re-enable it, you\u2019ll need to add another line:
[render]\nglshader = sharp\ninteger_scaling = vertical\n
This will yield 100% sharp pixels vertically, no matter what. Horizontally, there might be a 1-pixel-wide interpolation band at the sides of some pixels, depending on the DOS video mode and the upscale factor. This is the best possible compromise between maintaining the correct aspect ratio, even horizontal pixel widths, and good overall sharpness.
The resulting image has quite acceptable horizontal sharpness at 1080p, and from 1440p upwards, you\u2019ll be hard-pressed to notice the occasional 1-pixel interpolation band\u2026 unless you\u2019re literally pressing your nose against the monitor to give those pixels a deep inspection (well, how about not doing that then? )
"},{"location":"getting-started/advanced-graphics-options/#custom-viewport-resolution","title":"Custom viewport resolution","text":"That\u2019s very nice and all, but now the graphics look as if it was constructed from brightly coloured little bricks at fullscreen on a 24\u201d or larger modern display!
Well, 14\u201d VGA monitors were still the most affordable and thus most popular option until the mid-1990s, close to the end of the DOS era. Before that, CGA and EGA monitors were typically 12\u201d or 14\u201d, and monochrome Hercules monitors only 10\u201d or 12\u201d. And these are just the \u201cnominal\u201d diagonal screen sizes\u2014the actual visible area was about 1.5 to 2 inches smaller!
To emulate the physical image size you\u2019d get on a typical 14\u201d VGA monitor, you\u2019d need to restrict the output to about 960\u00d7720 on a modern 24\u201d widescreen display with a 16:9 aspect ratio (assuming the same normal viewing distance). You want the resulting image to measure about 12 inches (30 cm) diagonally for the most authentic results. But alas, that would be a tad too small for most people. 960\u00d7720 would result in a non-integer vertical scale factor, anyway, which is to be avoided. It\u2019s best to bump it up to 1067\u00d7800 then:
[render]\nviewport = 1067x800\n
The viewport size is specified in logical units (more on that below). You can also specify the viewport size restriction as a percentage of the size of your desktop:
[render]\nviewport = 89%\n
The video output will be sized to fit within the bounds of this rectangle while keeping the correct aspect ratio. If integer scaling is also enabled, the resulting image might become smaller than the specified viewport size.
Why 89% in this example? Because that\u2019s a magic number that will result in optimal image sizes for DOS resolutions between 320\u00d7200 and 640\u00d7480 on most common modern displays. With integer scaling enabled, 320\u00d7200 content will have the physical image size you\u2019d get on a 15\u201d CRT, and 640x480 what you\u2019d get on a big 19\u201d beast. These are reasonable upper maximums that can be considered \u201cbig screen mode\u201d for DOS-era standards, yielding the best overall compromise between \u201cmodern sensibilities\u201d and the authentic original experience. You go higher than this, the graphics will start looking overly blocky from a normal viewing distance.
No, DOS games did not look like Roman mosaics\u2026
Running DOS games in fullscreen on a modern 24\u201d widescreen display is equivalent to playing them on a 21\u201d CRT monitor! Those huge beasts were used by (and most importantly, priced for) professionals, so extremely few gamers and enthusiasts saw low-resolution art blown up to look like Roman mosaics back in the day. Even yours truly performed all the tricks in the book to shrink 320\u00d7200 DOS games as much as possible on his 19\u201d CRT in the early 2000s\u2026
Logical units vs pixels
Most operating systems operate in high DPI mode using a 200% scaling factor on 4K displays and use \u201cunscaled\u201d logical units for specifying window dimensions. The viewport setting adopts the same approach; the viewport size must be always specified in logical units.
For example, on a 4K display, a viewport resolution specified as 1280x960 logical units will translate to 2560\u00d71920 physical pixels (assuming a typical 200% scaling factor). Then on 1080p with a 100% scaling factor, it will simply translate to 1280\u00d7960 pixels.
The magic of 89% explained
This is hardcore mode\u2014only the brave and the mathematically inclined shall prevail! \ud83e\udd13 \ud83e\udde0 \ud83d\udcda
-
Assuming a 1920\u00d71080 desktop resolution, viewport = 89% will restrict the maximum viewport size to 1709\u00d7961 logical units.
-
The viewport size is a potential. With integer scaling disabled and aspect ratio correction enabled, for a 4:3 aspect ratio DOS image you\u2019d get a 1281\u00d7961 image in logical units (because 1281 / 961 \u2248 4/3).
-
This would result in 1281\u00d7961 pixels on 1080p monitors, then on 4K monitors with 200% DPI scaling, the resulting image would be 2562\u00d71922 pixels.
-
With integer scaling enabled and assuming a 320\u00d7200 VGA resolution double-scanned to 640\u00d7400, dividing 961 by 400 gives us 2.4025, so a 2x vertical integer scaling factor will be used. The resulting image will be 1067\u00d7800 on 1080p and 2133\u00d71600 on 4K. The image should measure about 14.4\u201d diagonally (about 35 cm) on your monitor, which is a little bit above the viewable size of a typical 15\u201d CRT.
-
For the 640\u00d7480 VGA mode, 961 / 480 \u2248 2.0021, so a 2x vertical integer scaling factor will be used again. The resulting image will be 1280\u00d7960 on 1080p and 2560\u00d71920 on 4K. The resulting image should measure about 17.3\u201d diagonally (about 42 cm) on your monitor, which is almost spot on the viewable size of a typical 19\u201d CRT.
Q.E.D.
"},{"location":"getting-started/advanced-graphics-options/#custom-aspect-ratios","title":"Custom aspect ratios","text":"Psssst\u2026 Don\u2019t tell anyone, but DOSBox Staging features a hidden \u201cscrew the developer\u2019s intent\u201d switch as well (also known as \u201cLOL what aspect ratio?\u201d mode). To unleash its formidable powers, put this casually into your config when no one\u2019s looking:
[render]\naspect = stretch\n
DOSBox Staging will now happily trample over any authentic aspect ratios and stretch the image to the full extents of the viewport. Keep resizing the window and see what happens. Whoopee! Now you can play Prince of Persia completely stretched to a widescreen monitor like a barbarian!
Jokes aside, this mode might come in handy when playing text adventures in fullscreen; it\u2019s hard to argue the correct aspect ratio matters much for those games. The same reasoning can also be applied to more abstract graphical games (although opinions on that are somewhat divisive\u2026)
You can also specify custom aspect ratios in the form of horizontal and vertical \u201cstretch factors\u201d. This emulates the horizontal and vertical stretch controls of CRT monitors. For example, we can correct the squashed look of the Hercules graphics in Prince of Persia with the following magic incantations:
[render]\naspect = stretch\nviewport = relative 112% 173%\n
Prince of Persia in Hercules mode with custom stretch factors to make the image fill our 4:3 \u201cemulated CRT screen\u201d
"},{"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 about launching our growing collection of games more easily. Having to navigate to the game\u2019s folder whenever we want to launch it gets old really fast. Here\u2019s how we can skip this step:
Windows -
Create a batch file called Start DOSBox Staging.bat with the following content:
C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox.exe\n
That\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.
-
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).
macOS 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.
Linux The easiest way is to create a shell script with the following content (of course, modify the path passed in with the --working-dir option so it points to your game directory):
#!/bin/bash\ndosbox --working-dir \"~/Documents/DOS Games/Prince of Persia\"\n
Then 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 then the usual drives/c subfolder within it. Download the ISO CD-ROM image from the Beneath a Steel Sky item at the Internet Archive 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 or Extras subfolder too for the scanned manuals and other extra files). 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\n
Warning
If you\u2019ve decided to keep 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\n
Tip
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 /? or help imgmount if you need a little reminder on how to use the command (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:\\>_\n
MSCDEX 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!
Always mount CD-ROM images with imgmount
While you could mount CD-ROM images outside of DOSBox with other programs too (e.g., Daemon Tools, ImgDrive, WinCDEmu, or the built-in Windows 10/11 ISO mounting feature), these alternative approaches often lead to compatibility problems. That\u2019s because these tools don\u2019t emulate the MSCDEX MS-DOS driver that DOS games expect.
For a trouble-free life, always just use the built-in imgmount command. There\u2019s nothing to be gained from using these 3rd party mounting tools for DOS games.
"},{"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\n
Okay, 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). 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\u2019ll need to select the installation path:
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 that by pressing Enter.
The installer will take us now to the setup screen where we can select the language of the in-game text (the voice-acting is English-only), and the sound 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 either. Reading the manual or some trial and error might help too.
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\n\nTo run the game type:\n\nC:\nCD \\SKY\nSKY\n
Alrighty, 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\n
"},{"location":"getting-started/beneath-a-steel-sky/#changing-the-current-directory","title":"Changing the current directory","text":"So 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\n
The 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:\\>_\n
How do you go straight to the root directory? By executing cd \\ (the \\ backslash character means \u201croot directory\u201d).
C:\\SKY>cd \\\nC:\\>_\n
You 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>_\n
Play around a bit with the drive and directory switching commands, then when you\u2019ve 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)!
"},{"location":"getting-started/beneath-a-steel-sky/#adjusting-volume-levels","title":"Adjusting volume levels","text":"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 at 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 why their channels appear in the mixer, and the CDAUDIO channel is added automatically whenever we mount a CD-ROM image (as it might 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\n
By 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\u2019re setting the OPL channel\u2019s volume to 50%, and the SB channel\u2019s to 500%:
mixer opl 50 sb 500\n
You can run mixer /? or help 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\n
"},{"location":"getting-started/beneath-a-steel-sky/#changing-the-emulated-sound-blaster-model","title":"Changing the emulated Sound Blaster model","text":"DOSBox 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 have 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\n
We 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:
[autoexec]\nimgmount D \"cd/cdrom1.iso\" -t iso\nc:\ncd sky\n#mixer opl 50 sb 500 /noshow\nsky\n
It 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.
"},{"location":"getting-started/beneath-a-steel-sky/#disabling-the-sound-blaster-mixer","title":"Disabling the Sound Blaster mixer","text":"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 card\u2019s internal 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\n
Well, that\u2019s another way of fixing the issue; the volume levels are now perfect!
When the game knows best
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, but no hard feelings), you must have heard 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\n
Remember 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% cycles/ms\n
SKY 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\n
Restart 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. These extenders also print out some fairly characteristic messages as they start up when launching the game, so they\u2019re easy to recognise.
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.
"},{"location":"getting-started/beneath-a-steel-sky/#finding-the-correct-speed-for-a-game","title":"Finding the correct speed for a game","text":"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\u2009000 Always 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 much\u2014you 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 card. They were the Cadillacs of DOS gaming audio for a while, they were priced accordingly, and they still sound excellent 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:
Windows C:\\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:
"},{"location":"getting-started/beneath-a-steel-sky/#selecting-the-mt-32-version","title":"Selecting the MT-32 version","text":"As you might have guessed already, you can tell DOSBox Staging to emulate an MT-32 model of a specific revision; you can read all 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. Some studios, such as LucasArts, tended to favour the CM-32L, so their games sound a little bit better on this module. mt32_old Most older games, most notably the entire early Sierra adventure catalogue, absolutely need a 1st generation MT-32; they will refuse to work correctly on any other model or at least sound incorrect. 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\n[mt32]\nmodel = cm32l\n
How 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.
"},{"location":"getting-started/beneath-a-steel-sky/#configuring-the-game-for-mt-32","title":"Configuring the game for MT-32","text":"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 or the ls command, 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 combined installer-and-setup utility into C:\\SKY as one would rightly expect. To reconfigure the game, you\u2019ll need to run INSTALL.EXE from the CD, so from the D drive (I\u2019ve told you\u2014setting up the game itself is often 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\u2014the computer says no, buddy.
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 enhance 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\n
"},{"location":"getting-started/beneath-a-steel-sky/#aspect-ratio-correction","title":"Aspect ratio correction","text":"We\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 (just trust me on that for a moment).
So where\u2019s this magical 20% vertical stretch factor coming from? DOSBox Staging enables aspect ratio correction by default to make 320\u00d7200 graphics appear exactly as it 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. One of the tell-tale signs is that the artwork in the intro was scanned using square pixels, and 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, or PAR). All this is explained in a lot more detail in the advanced graphics options chapter at the end.
Left: Screenshot from the intro with aspect ratio correction disabled (square pixels) Right: The original image from the comic book included with the game That\u2019s quite easy to do, and we\u2019re also setting the viewport resolution to 4x integer scaling, effectively, because the game would appear too blocky when fit to fullscreen:
[render]\naspect = off\nviewport = 1280x800\n
Beneath a Steel Sky with aspect ratio correction disabled
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 primarily developed for DOS. This is the DOSBox Staging default, and it ensures the overwhelming majority of DOS games appear correctly out of the box.
-
For games primarily developed for the Amiga or Atari ST by a North American studio for the NTSC standard. (Note that even if the work was performed by a European studio, but it was commissioned by North Americans, that usually means the game was primarily intended for the NTSC-only North American market, so you need aspect ratio correction.)
aspect = off
- For most games primarily developed by European studios for the Amiga or Atari ST.
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 1980s and \u201990s featuring 2D graphics, the art was created once for the \u201cleading platform\u201d 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\u2019ve 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). We\u2019ll get to the detailed mathematical derivation of the 1:1.2 PAR in the last chapter.
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 economically motivated compromise 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/#arcade-monitor-emulation","title":"Arcade monitor emulation","text":"Now that we brought up the Amiga, it\u2019s worthwhile mentioning a special feature of the CRT emulation which is not quite authentic, but still a lot of fun!
Home computer and arcade monitors (also known as 15 kHz monitors), such as the Commodore monitors typically used with Amiga computers, were quite different from VGA CRTs. They displayed low-resolution content with thick scanlines, similary to EGA monitors, and they were a lot less sharp. While this wasn\u2019t great for displaying text and spreadsheets, it made low-resolution pixel art appear in a more favourable light.
We can enable this special fantasy mode with the following setting:
[render]\nglshader = crt-auto-arcade\n
Now you can play the game with Amiga-like graphics and MT-32 or OPL sound from a strange parallel universe! \ud83d\ude0e
Beneath a Steel Sky from a parellel universe running on an Amiga in 256 colour mode
"},{"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\n[sdl]\nfullscreen = on\n\n[render]\naspect = off\nviewport = 1280x800\n\n# uncomment for arcade monitor emulation\n#glshader = crt-auto-arcade\n\n[sblaster]\nsbmixer = off\n\n[midi]\nmididevice = mt32\n\n[mt32]\nmodel = cm32l\n\n[mixer]\nreverb = large\nchorus = strong\n\n[autoexec]\nimgmount d \"cd/cdrom1.iso\" -t iso\nc:\ncd sky\nsky\nexit\n
With 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 and chorus, so DOSBox Staging is intelligent enough not to apply these effects twice on its output.
"},{"location":"getting-started/enhancing-prince-of-persia/","title":"Enhancing Prince of Persia","text":""},{"location":"getting-started/enhancing-prince-of-persia/#fullscreen-mode","title":"Fullscreen mode","text":"You 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 make DOSBox start in fullscreen right away?
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\n[autoexec]\nc:\nprince\nexit\n
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.
Note we\u2019ve also added the exit command to the end of the [autoexec] section; with this in place, DOSBox Staging will quit after we exit from the game by pressing Ctrl+Q. Not strictly necessary, but a nice touch.
Making configuration changes
Every time you modify dosbox.conf, you need to restart DOSBox Staging for the changes to take effect. We will not mention this every single time from now on.
You can do this by closing the DOSBox Staging application and then starting it again. But there is a better way: simply press Ctrl+Alt+Home! This is a homage to the Ctrl+Alt+Del \u201cthree-finger salute\u201d way of soft-rebooting IBM PCs.
If you\u2019re on macOS, you\u2019ll need to press Cmd+Option+Home instead, and if Apple has decided for you that your MacBook doesn\u2019t need a Home key, Cmd+Option+Fn+Left should do the trick.
"},{"location":"getting-started/enhancing-prince-of-persia/#graphics-options","title":"Graphics options","text":"DOSBox emulates an SVGA (Super VGA) display adapter by default; this 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 adapters among several 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 (we\u2019ll discuss how to do that too in later chapters).
"},{"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. This video mode allows up to 256 colours to be displayed simultaneously on the screen from a total palette of 16 million colours.
This is how the start of the game looks with the authentic CRT emulation feature which is enabled by default. As mentioned previously, make sure to view all screenshots at 100% magnification to avoid weird artifacts caused by the browser rescaling the image.
Prince of Persia in VGA mode with the default settings
But wait a minute, this doesn\u2019t look like anything I\u2019m used to from console emulators. Where are those visible thick scanlines?
VGA display adapters have a peculiarity in that they display not one but two scanlines per pixel in low-resolution video modes having less than about 350 lines of vertical resolution. This means the 320\u00d7200 VGA mode is really 640\u00d7400, just pixel and line-doubled. In fact, the vast majority of VGA monitors from the 1980s and \u201990s are incapable of displaying \u201ctrue\u201d 200-line graphics, so it\u2019s physically impossible to get the \u201cthick scanline\u201d arcade and home computer monitor look on a real VGA CRT.
Double-scanned VGA emulation looks stellar on a 4K monitor and even on 1440p, but on 1080p, there is simply not enough vertical resolution to accurately represent all those 400 tightly-packed scanlines. Therefore, the best thing the CRT emulation can do on 1080p and lower is to fake that double-scanned look so it looks approximately similar to the real thing.
Aspect ratio correction
Computer monitors were originally not widescreen but had a 4:3 display aspect ratio, just like old television sets. DOS games were normally designed to completely fill a 4:3 CRT screen. DOSBox Staging displays the emulated image in the correct aspect ratio by default, which means you\u2019ll see pillarboxing (vertical black bars) at the two sides in fullscreen on modern widescreen displays. This is normal.
However, there is also letterboxing (horizontal black bars) above and below the image. We\u2019ll explain why that\u2019s necessary in the last advanced graphics options chapter. Feel free to take a detour if you wish to gain an understanding of these details now.
Alternatively, if you\u2019re on a 4K (UHD, 3840x2160) or better screen, you can put this into your [render] section to get rid of pillarboxing altogether:
[render]\ninteger_scaling = off\n
"},{"location":"getting-started/enhancing-prince-of-persia/#ega","title":"EGA","text":"The next graphics adapter the game supports is the EGA adapter released in 1984. The EGA standard was quite popular until the early 1990s because VGA cards were initially prohibitively expensive for most hobbyists. The majority of 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\n
This is how the game looks with the fixed 16-colour EGA palette. Unlike VGA, EGA monitors can display true 320\u00d7200 resolution with the well-known thick scanline look.
Prince of Persia in EGA mode\u2014EGA monitors can display 200-line modes without line doubling, so we\u2019ll get the \u201cfat scanline\u201d look
"},{"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, only 4 colours can be displayed simultaneously on the screen chosen from a small number of fixed palettes. Frankly, all combinations look pretty horrifying\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 goggles!
[dosbox]\nmachine = cga\n
Ready? Behold the formidable 4-colour CGA graphics\u2014and what 4 colours those are! Similarly to EGA, CGA is capable of displaying true 200-line modes.
Prince of Persia in CGA mode. Yeah, it\u2019s not pretty\u2026
Tip
To compare how the game looks on different graphics adapters, click on one of the screenshots to enlarge it, then use the Left and Right arrow keys to switch between the images.
"},{"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\n
Here\u2019s how it looks. Oldschool! The 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 (but we\u2019ll examine some advanced techniques on how to fix that).
Prince of Persia in Hercules mode using the default amber palette
Monochrome monitors come in different colours and DOSBox Staging can emulate all these variations via the monochrome_palette setting. The available options are amber (the default), green, white, and paperwhite.
[render]\nmonochrome_palette = green\n
You can also cycle between these while the game is running with the F11 key.
Hercules mode using the green palette
Hercules mode using the white 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 not to play a DOS game with the best graphics. The list of possible reasons includes a) nostalgic feelings towards a particular display adapter; b) research purposes; c) you like your games to look like the user interface of an industrial CNC machine; d) a strong 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/#sharp-pixels","title":"Sharp pixels","text":"If you really prefer sharp pixels over authentic CRT emulation, you only need to add a single line to the [render] config section:
[render]\nglshader = sharp\n
That\u2019s it! Switching to the sharp shader will also make the image fill the screen vertically, so no more letterboxing. The reason for this (and a lot more) will be explained in the advanced graphics options chapter.
Keep in mind, though, that the rest of the guide assumes you\u2019re using the CRT emulation.
"},{"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\n
Now 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 too with the standard drivers.
"},{"location":"getting-started/enhancing-prince-of-persia/#joystick-support","title":"Joystick support","text":"Okay, so if we want to play the game with the keyboard, we need to press Ctrl+K to enter keyboard mode every single time we start the game. As mentioned, that\u2019s because by default DOSBox Staging either lets you use your gamepad as the joystick, or it emulates a PC joystick even if you don\u2019t have a physical game controller plugged in. Either way, the game will always \u201csee\u201d a joystick at startup and will therefore auto-switch to joystick mode.
From this follows that if we disable the joystick in the config, the game will have no other choice than to default to keyboard mode:
[joystick]\njoysticktype = disabled\n
But if you want to play the game with your gamepad instead, you can do that too! DOSBox Staging auto-maps most common game controllers, so you can control the game with the left analog stick and the X button out-of-the-box with most gamepads.
You\u2019ll need to hit diagonals often to jump and crouch. If your left stick can only move in a circle, the following setting might make this easier:
[joystick]\ncircularinput = on\n
You can also adjust the deadzone of your stick if you experience controller drift. It\u2019s 10% by default, so let\u2019s increase it to 15% instead:
[joystick]\ndeadzone = 15\n
The PC is not a console
Note that Prince of Persia requires a lot of precise control, so playing it with the analog stick makes the game quite a bit harder and somewhat frustrating. This is a common theme with many DOS games; most of them were really optimised for keyboard controls, or require you to use the keyboard anyway to perform some essential actions.
While playing DOS games from the couch with a controller in your hand might be cool, for the best results, just stick with the keyboard controls. Apart from some space and flight simulators, joystick support was often an afterthought in DOS games.
Issues with multiple controllers
You might get some weird behaviour or even crashes if you have multiple game controllers plugged in. If that\u2019s the case, please disconnect all game controllers except the one you want to use and restart DOSBox Staging. We\u2019re aiming to improve multi-controller support in the future.
"},{"location":"getting-started/enhancing-prince-of-persia/#pausing-the-game","title":"Pausing the game","text":"Prince of Persia can be paused by pressing the Esc key during the game. That\u2019s nice, but not all games have such built-in pause functionality.
Luckily, DOSBox has a pause feature that you can activate in any game with the Alt+Pause shortcut (Cmd+P on macOS), then unpause by pressing the same shortcut again.
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]\npause_when_inactive = yes\n
Restart the game and switch to a different window\u2014DOSBox will pause itself. Switch back to DOSBox\u2014the game will resume. Nifty, isn\u2019t it?
Pause gotchas
All input is disabled in the manually paused state\u2014the only thing you can do is press the pause shortcut again to unpause the emulator. In windowed mode, the paused state is indicated in the DOSBox Staging window\u2019s title bar.
"},{"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:
[sdl]\nfullscreen = on\npause_when_inactive = yes\n\n[mixer]\nreverb = large\nchorus = normal\n\n[autoexec]\nc:\nprince\nexit\n
"},{"location":"getting-started/enhancing-prince-of-persia/#configuration-comments","title":"Configuration comments","text":"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\npause_when_inactive = yes\n\n[joystick]\n# if you prefer the keyboard; remove it if you want to play with your gamepad\njoysticktype = disabled\n\n# optional gamepad adjustments\n#circularinput = on\n#deadzone = 15\n\n[render]\n# for 4K+ monitors only\n#integer_scaling = off\n\n[mixer]\nreverb = large\nchorus = normal\n\n[autoexec]\nc:\nprince\nexit\n
Note we haven\u2019t commented out the [render] section itself. That\u2019s fine; empty sections are allowed and do no harm.
"},{"location":"getting-started/enhancing-prince-of-persia/#inspecting-the-logs","title":"Inspecting the logs","text":"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 Staging can inform you if something goes wrong. It does that via the logs, which are just a continuous stream of timestamped messages in a separate window.
The behaviour of the log window is different on each platform:
Windows The 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.
macOS 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).
Note
Remember, for the first time you\u2019ll need to right-click or Ctrl-click on this icon, select the topmost Open menu item, then press the Open button in the appearing dialog. After the first start, you can simply double-click on it.
Linux 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 is 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:
- Set
machine to mcp - Include a bogus config setting in the
[sdl] section: no_such_config_param = 42 - Set
fullscreen to blah - Put the letter
x in front of the shader\u2019s name
This is how the freshly ruined parts of our config should look like:
[sdl]\nfullscreen = blah\nno_such_config_param = 42\n\n[dosbox]\nmachine = mcp\n\n[render]\nglshader = xsharp\n
As 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 Staging has reverted 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. Although it\u2019s primarily intended for newcomers unfamiliar with DOSBox and DOS emulation, it\u2019s a recommended read for people already comfortable with other DOSBox variants but not DOSBox Staging. And even if you\u2019re a long-time Staging user, we\u2019re quite certain you will learn a few new useful things and techniques from it.
The guide has been 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. For example. Windows users probably know what the \u201cC drive\u201d is, and most Linux people are comfortable using the command line, but these things need to be explained to the Mac folks.
We wish you a pleasant journey and we hope DOSBox 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":"You must use the latest stable version of DOSBox Staging for this guide. If you already have other versions of DOSBox on your computer, installing DOSBox Staging won\u2019t interfere with them at all. Experienced users can 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.
Windows Download the latest installer from our Windows releases 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.
macOS Download the latest universal binary from our macOS releases page, then simply drag the DOSBox Staging icon into your Applications folder. Both Intel and Apple silicon are supported.
Don\u2019t delete the .dmg installer disk image just yet\u2014we\u2019ll need it later.
Linux Please check out our Linux releases 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.
Windows We recommend Windows users 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.
macOS TextMate 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 status bar).
Linux We\u2019re pretty sure Linux users don\u2019t need any help and have their favourite text editors at hand already. And, of course, everybody knows vim is the best!
"},{"location":"getting-started/introduction/#a-note-for-existing-dosbox-staging-users","title":"A note for existing DOSBox Staging users","text":"If you already have DOSBox Staging installed on your computer, or if you have used it in the past but have uninstalled it, most likely you have a primary configuration file named dosbox-staging.conf somewhere on your drive (this is sometimes also referred to as the default or global configuration).
The guide assumes the default settings of the latest stable release, so it\u2019s highly recommended to remove any existing primary configuration files first (but make sure to back them up). If the primary config file does not exist in an platform-specific location, DOSBox Staging will create it on the first launch. If it exists, it will be used, but the defaults of some settings might have changed between releases, or you might have tweaked some settings yourself. These differences may render the instructions in the guide invalid as the default settings are assumed.
This is where the primary config is located per platform:
Windows C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox-staging.conf macOS ~/Library/Preferences/DOSBox/dosbox-staging.conf Linux ~/.config/dosbox/dosbox-staging.conf You can also execute DOSBox Staging with the --printconf option to have the location of the primary config printed to your console.
To back up your existing primary config, you can simply change the extension of dosbox-staging.conf from .conf to .bak. DOSBox Staging will write a brand new primary config containing the current defaults the next time you start it.
"},{"location":"getting-started/introduction/#portable-mode-notes","title":"Portable mode notes","text":"If you\u2019ve been using DOSBox Staging in portable mode, dosbox-staging.conf is located in the same folder as your DOSBox Staging executable. In that case, it\u2019s recommended to back up your existing primary config, and then create a new empty dosbox-staging.conf file in the executable folder. DOSBox Staging will write the new defaults to the empty dosbox-staging.conf file on the first launch.
"},{"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 Staging 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 primary configuration file; look around on our wiki; familiarise yourself with our feature highlights; read the release notes on our releases 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 community 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 hardware An 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 Days This 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 Pleasures Written 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.
PhilsComputerLab Phil\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 list If 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.
VOGONS An 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/#primary-configuration","title":"Primary 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 primary 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 and a short description for each.
For example, this is the start of the description of the viewport setting:
Set the viewport size (maximum drawable area). The video output is always\ncontained within the viewport while taking the configured aspect ratio into\naccount (see 'aspect'). Possible values:\n fit: Fit the viewport into the available window/screen (default).\n There might be padding (black areas) around the image with\n 'integer_scaling' enabled.\n WxH: Set a fixed viewport size in WxH format in logical units\n (e.g., 960x720). The specified size must not be larger than\n the desktop. If it's larger than the window size, it's\n scaled to fit within the window.\n ...\n
Here are the locations of dosbox-staging.conf on each platform:
Windows 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.
"},{"location":"getting-started/passport-to-adventure/#online-help","title":"Online help","text":"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 <setting_name>.
However, if the description is longer than what can fit into a single screen, this is not too fruitful as the config command will effectively only display the last page. In such cases, we can \u201cpipe\u201d the output of the config command through the more command that will paginate the preceding command\u2019s output. For example, this is how to display the description of the viewport setting which is rather long:
config -h viewport | more\n
The | 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.
This is how the output of the command looks like:
When piping the output through more, you can press Space to go to the next page, Enter to advance to the next line, or Q to quit the viewer, as the bottom line indicates. The viewer will also automatically quit once we\u2019ve reached the end of the output.
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 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 we started DOSBox Staging from that folder. In such a scenario, DOSBox loads the primary configuration first, then applies the local dosbox.conf configuration found in the folder it was started from (the game\u2019s folder). Because of this loading order, you can override any primary config setting in your local config.
This layered configuration approach is very useful; you can apply broad, general settings in your primary configuration that will apply to all games, then fine-tune these defaults on a per-game basis via local dosbox.conf configs in the individual game folders. Because of this, the primary configuration is sometimes also referred to as the default or global configuration.
As DOSBox Staging comes with sensible defaults, you can keep these local configs 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 very 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 primary configuration while you\u2019re still a beginner. Even more experienced DOSBox users are generally better off changing the primary configuration very sparingly as those settings will affect all games.
A few things that you might want to consider setting globally in the primary config include enabling fullscreen mode, turning on auto-pausing, integer scaling and shader defaults, and certain MIDI and audio-related settings (e.g., sample rate, buffer sizes, volume levels, etc.) 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.
"},{"location":"getting-started/passport-to-adventure/#examining-text-files","title":"Examining text files","text":"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 we\u2019ll only see the end of the file that way because it\u2019s longer than a single page. Good thing we\u2019ve just learned about the more command, so let\u2019s put it to good use by executing the following:
type README.TXT | more\n
Now we can read the whole file, starting from the beginning. 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.
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!
"},{"location":"getting-started/passport-to-adventure/#mouse-capture","title":"Mouse capture","text":"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\n
"},{"location":"getting-started/passport-to-adventure/#playing-the-game","title":"Playing the game","text":"This is a really user-friendly program; you can press F1 on 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 dialogues, 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 or even lossless 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 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\n
Note
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.
-
FM refers to the type of sound synthesis the OPL chip is doing, which is Frequency Modulation synthesis (or FM synthesis, in short).
-
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 result.
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 by doing so.
-
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.
All in all, the terms OPL, AdLib, and FM are used interchangeably in practice, and usually they refer to the exact same thing.
"},{"location":"getting-started/passport-to-adventure/#pc-speaker-sound","title":"PC speaker sound","text":"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 while 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\n
Okey-dokey, let\u2019s try the \u201cinternal speaker\u201d option by starting the game with the i command-line argument:
C:\\>SAMPLER.EXE i\n
Well, 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 coerce it to 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 subjecting 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\n
"},{"location":"getting-started/passport-to-adventure/#tandy-sound","title":"Tandy sound","text":"Another option is the \u201cTandy(tm) sounds\u201d you can select with the ts command-line argument. Let\u2019s try it!
C:\\>SAMPLER.EXE ts\n
Aaaaand, now there\u2019s no sound at all. Why is that?
Tandy Corporation was an IBM PC clone manufacturer in the 1980s; they produced the Tandy line of home computers that were mostly compatible with 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 enhanced Tandy & PCjr graphics and sound page on our wiki should help you find these pre-1990 Tandy specials.
DOSBox can emulate a Tandy machine\u2014we only need to instruct it to do so in our config:
[dosbox]\nmachine = tandy\n
Emulating the Tandy will cause the standard DOS font to be a bit different; this is normal, so 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 sound 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\n
"},{"location":"getting-started/passport-to-adventure/#game-blaster-cms-sound","title":"Game Blaster / CMS sound","text":"The 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\n
The 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\n
Naturally, you can combine crossfeed with chorus and reverb. You can also set crossfeed to light, normal, or strong according to your preference, or specify a custom crossfeed amount as a percentage from 0% (no crossfeed) to 100% (collapse the stereo image to mono):
crossfeed = 50\n
Try 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 offered backward compatibility with EGA graphics, although this was not full compatibility but a kind of emulation: 320\u00d7200 EGA graphics were simply line and pixel-doubled to 640\u00d7400.
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. Because of this, the authentic CRT emulation feature displays EGA graphics with the \u201ctrue EGA look\u201d out of the box with the glshader = crt-auto setting.
However, if you grew up with a VGA-equipped PC, then you only ever saw EGA games double-scanned. To appease such people, you can instruct DOSBox Staging to emulate a double-scanning VGA card in all screen modes with the crt-auto-machine setting:
[render]\nglshader = crt-auto-machine\n
Technically, this setting instructs DOSBox Staging to always emulate a CRT monitor appropriate for the configured machine type which is VGA by default.
The below screenshots illustrate the difference between the \u201ctrue EGA\u201d and \u201cEGA as displayed on VGA\u201d look:
Indiana Jones and the Last Crusade \u2014EGA as displayed on VGA monitors
Indiana Jones and the Last Crusade \u2014\u201cTrue EGA\u201d emulation
The Secret of Monkey Island \u2014EGA as displayed on VGA monitors
The Secret of Monkey Island \u2014\u201cTrue EGA\u201d emulation
Loom \u2014 EGA as displayed on 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/#authentic-image-size","title":"Authentic image size","text":"DOS games appear overly blocky at fullscreen on 24\u201d or larger modern monitors. This is not how people experienced these games back in the day. Typical monitor sizes were 14-15\u201d throughout the 320\u00d7200 VGA era, and 17-19\u201d for the brief 640\u00d7480 SVGA period at the end of the DOS days.
We can make the image a bit smaller with the following setting:
[render]\nviewport = 89%\n
This will result in an image size that is the best compromise between \u201cmodern sensibilities\u201d and the authentic original experience. It\u2019s still on the large end of the spectrum, but not overly so. If you go higher than this, the graphics will start looking overly blocky from a normal viewing distance.
The rationale behind the \u201cmagic 89% value\u201d is explained in detail in the last advanced graphics options chapter.
"},{"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\n
Let\u2019s see what happens if we double the emulated CPU speed!
[cpu]\ncycles = 6000\n
Now we\u2019re greeted by an error when trying to start the game:
run-time error R6003\n- integer divide by 0\n\nC:\\>\n
We 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\n[dosbox]\n# uncomment for Tandy sound\n#machine = tandy\n\n[mouse]\nmouse_capture = onstart\n\n[render]\nviewport = 89%\n# uncomment for double-scanned VGA CRT emulation\n#glshader = crt-auto-machine\n\n[sblaster]\n# uncomment for Game Blaster audio\n#sbtype = gb\n\n[mixer]\n# change 'reverb' to 'tiny' for the PC speaker\nreverb = medium\nchorus = normal\ncrossfeed = on\n\n[autoexec]\nc:\n# use for PC speaker sound\n#sampler i\n\n# use for Tandy sound\n#sampler ts\n\nsampler\nexit\n
"},{"location":"getting-started/setting-up-prince-of-persia/","title":"Setting up Prince of Persia","text":""},{"location":"getting-started/setting-up-prince-of-persia/#first-steps","title":"First steps","text":"We 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.\n
I\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; 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. Looking at pop1demo.exe the solution is quite obvious: we\u2019ll need to run this executable file in DOSBox!
"},{"location":"getting-started/setting-up-prince-of-persia/#the-c-drive","title":"The C drive","text":"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 whether you use uppercase or lowercase C on Windows and macOS but it does in Linux). 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/setting-up-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:
Windows 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, and then select Open with DOSBox Staging in the context menu.
macOS - Mount the DOSBox Staging installer
.dmg image file. - Copy the Start DOSBox Staging icon from the appearing window into the
Prince of Persia folder. - Right-click or Ctrl-click the icon, then select the topmost Open menu item.
- A dialog with the following text will appear: macOS cannot verify the developer of \u201cStart DOSBox Staging\u201d. Are you sure you want to open it?
- Press the Open button.
- A dialog will open, asking for permission to allow DOSBox Staging access to your Documents folder. Click on the OK button.
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.
Linux 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>\n
Alternatively, 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).
"},{"location":"getting-started/setting-up-prince-of-persia/#installing-the-game","title":"Installing the game","text":"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:\\>_\n
The 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:\\>_\n
Type 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:\\>_\n
Well, 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.
DOS filenames
DOS filenames are always uppercase and are limited to 8 characters, plus an optional 3-character file extension. It does not matter whether you type in lowercase or uppercase letters because DOS will always convert them to uppercase before dealing with your input. Tab completion always uses uppercase because\u2026 I guess it just looks nice?
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:\\>_\n
The 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. Best of all, the command history is preserved across DOSBox Staging restarts.
Okay, so here\u2019s what 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:\\>_\n
Tip
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 (nothing to do with body weight) 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.
"},{"location":"getting-started/setting-up-prince-of-persia/#starting-the-game","title":"Starting the game","text":"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.
Running DOS programs
To run executable files (files with the .EXE, .COM or .BAT file extension) it\u2019s enough to type in the filename only, without the extension. So you could have started the game with the prince command as well.
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!
This particular game supports both the keyboard and the joystick. DOSBox Staging emulates a joystick by default, even if you don\u2019t have a physical game controller plugged in. The game is clever enough to auto-detect that and switches to joystick mode at the start. Okay, so let\u2019s switch to keyboard mode instead by pressing Ctrl+K!
You can control the prince with the cursor keys. Hold down the Shift key to walk carefully. 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 available keyboard shortcuts.
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, 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 \u201990s; 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/setting-up-prince-of-persia/#authentic-crt-monitor-emulation","title":"Authentic CRT monitor emulation","text":"DOSBox Staging includes a cathode-ray tube (CRT) monitor emulation feature which is enabled by default. It strives to achieve authentic, period-correct results; the look of PC CRT monitors from the 1980s and 1990s has been painstakingly recreated via shaders as accurately as current technology allows. These monitors exhibit certain characteristic peculiarities when displaying low-resolution graphics; you can think of them as \u201cbuilt-in filters\u201d that can never be disabled. Artists of the era had to embrace and work with these peculiarities, and people playing DOS games on their CRTs saw the art through the same \u201cfilters\u201d as the artists.
For this reason, many people who grew up with CRTs think that once these filters are \u201cdigitally removed\u201d by drawing the pixels as sharp little rectangles on modern flat screens, the art looks bland, sterile, and loses its \u201canalog magic\u201d. That\u2019s the main reason behind enabling the CRT emulation by default, to give people a chance to see the art of DOS games in their full glory as the developers intended.
The remarkable thing about the feature is that it\u2019s \u201czero config\u201d\u2014it automatically adapts to the changing circumstances to always produce the correct CRT look based on the emulated graphics adapter, the current DOS video mode, the window size, and the native resolution of your monitor. You don\u2019t need to think about it or tinker with it, It Just Works\u2122
We\u2019ll showcase the authentic CRT emulation throughout the guide, but if you prefer sharp pixels, we\u2019ll explain how to achieve that in the next chapter.
Proper viewing of screenshots
Screenshots of CRT shaders in action need to be viewed at 100% magnification; otherwise, you might see strange wavy interference patterns 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 at 100% magnification.
"},{"location":"getting-started/setting-up-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 that?
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\n
The 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 with the .conf extension only 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 say \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.
"},{"location":"getting-started/star-wars-dark-forces/","title":"Star Wars: Dark Forces","text":"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/star-wars-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.\n
We 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/star-wars-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\n
The first -w 0.5 argument of the autotype command specifies an initial half-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.
"},{"location":"getting-started/star-wars-dark-forces/#display-refresh-rate","title":"Display refresh rate","text":"Dark Forces uses the 320\u00d7200 256-colour VGA screen mode, just like the majority of DOS games from the 1990s. 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 a fixed 60 Hz rate. 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 the graphics standards emulated by DOSBox Staging:
Graphics standard 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 Hz Creating 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 still has a lot of practical utility.
"},{"location":"getting-started/star-wars-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 tries to automatically detect the conditions where enabling vertical syncing is beneficial 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, so there\u2019s nothing we can do about them at the emulator level).
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, even with DOSBox-level 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. Many pre-rendered cutscenes and FMV games tear really badly on real hardware too on CRTs\u2014that\u2019s the \u201cauthentic DOS experience\u201d for you!
Manually configuring vsync is a complex advanced topic for power users only, so it\u2019s beyond the scope of this beginner\u2019s guide. If you\u2019re feeling brave, look into the presentation_mode, vsync, vsync_skip, host_rate, and dos_rate settings for further details, but it\u2019s unlikely you\u2019ll be able to improve the automatically chosen settings unless you really know what you\u2019re doing (and it\u2019s really easy to make the situation a lot worse by misconfiguring things).
"},{"location":"getting-started/star-wars-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 1990s 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\n
As 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 just powerful enough to handle 70 FPS but not more powerful. 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\n
Start 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 CPU speeds.
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\n
Running 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 achieving a smooth and stable 70 FPS rate.
You have only two options in that 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 chunk 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 switchers 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. This might seem counterintuitive as we\u2019re running decades-old software here, but emulation can be very demanding on your computer.
"},{"location":"getting-started/star-wars-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:
Windows 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\n[fluidsynth]\nsoundfont = \"GeneralUser GS v1.471.sf2\"\n
The 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. It\u2019s best to do this in your primary config, then you never need to think about it again.
Further comparison recordings can be found on our wiki.
Roland SC-55 v1.21 (hardware) Your browser does not support the audio 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 its output level. The best way to do so is by including an additional percentage volume value after the SoundFont\u2019s name in the config, e.g.:
[fluidsynth]\nsoundfont = Arachno.sf2 40\n
This will scale back the volume to 40%. A few SoundFonts are extremely loud\u2014you need to turn the 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 often sounds utterly wrong on a General MIDI device, 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 programmable synthesisers and most MT-32 supporting games take advantage of that to create custom sounds. In contrast, General MIDI modules are generally weaker in the synthesis front but feature more realistic-sounding real-world instruments. The soundtrack of Dark Forces showcases this very well\u2014you can\u2019t get such realistic orchestral music out of an MT-32.
Whenever you configure a game for MIDI sound, you should consult the List of MT-32-compatible computer games first. This contains the hard-earned knowledge of many decades of research and tells you which MIDI module to use for a particular game. The original game manuals very rarely give you this info, and even if they do, the information is often wrong. So you absolutely need this list.
Quite confusingly, there\u2019s a large list of games that claim MT-32 compatibility but only sound correct on a General MIDI module. Make sure to check the List of games that falsely claim MT-32 compatibility as well before configuring any game for MT-32 sound.
A brief history of MIDI in DOS gaming
The iconic Roland MT-32 released in 1987 was the first sound module that made realistic-sounding music in DOS games a possibility. In 1991, Roland released its successor, the iconic Roland Sound Canvas SC-55.
The SC-55 shaped DOS gaming history in significant ways: it was the world\u2019s first device to support the General MIDI standard. MIDI only defines a communication mechanism between MIDI-capable devices (e.g., a sound module and your computer). But it remains silent on how the different instruments should sound. General MIDI (GM) remedied this with its 128 standard instrument definitions. For example, on any GM-compliant module, instrument #1 is always the Acoustic Grand Piano and instrument #36 is the Fretless Bass.
This made interoperation between GM-compliant devices possible. You could use any General MIDI sound module with any GM-compliant game, and you would get music. The music would sound mostly correct, but this depends on the musical composition and the particular sound module. Most composers and gamers had the SC-55, establishing it as a de facto standard. This means music could sound unbalanced and weird on other GM sound modules if they deviated too much from the \u201cgold standard\u201d SC-55 sound.
Additionally, the SC-55 also supports the General Standard (Roland GS, or only GS in short), which is Roland\u2019s vendor-specific General MIDI extension. Many games make good use of these extra features and sound wrong in their absence. This means that alternative MIDI modules need to support both the GM and the GS standards to sound correct with DOS games.
The Yamaha DB50XG and MU-series (e.g., MU50, MU80, MU100, etc.) are such MIDI modules. They can be viewed as more modern-sounding and higher-quality takes on the original SC-55. They offer excellent SC-55 compatibility but with a more polished and punchy sonic character. In fact, many prefer them to the SC-55 in certain DOS games. If you are curious about how these Yamaha modules stack up against the SC-55, this article might be of interest.
"},{"location":"getting-started/star-wars-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 distortions.
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\n
Overall, 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\n
"},{"location":"getting-started/star-wars-dark-forces/#reverse-stereo","title":"Reverse stereo","text":"The 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. This will only reverse the digital sound output of the Sound Blaster.
(Remember, you can use mixer /? or help mixer to view the mixer command\u2019s help.)
"},{"location":"getting-started/star-wars-dark-forces/#minimising-audio-glitches","title":"Minimising audio glitches","text":"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 it mainly 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 but blocksize must be one of the following values: 256, 512, 1024, 2048, 4096, or 8192.
[mixer]\nblocksize = 2048\nprebuffer = 50\n
"},{"location":"getting-started/star-wars-dark-forces/#final-configuration","title":"Final configuration","text":"Here\u2019s the full config of Dark Forces set up for General MIDI sound:
[sdl]\nfullscreen = on\n\n[cpu]\n# to emulate a Pentium 90\ncycles = 50000\n\n[mixer]\ncompressor = off\n\n[midi]\nmididevice = fluidsynth\n\n[fluidsynth]\n# not needed if you set this in the primary config\nsoundfont = \"GeneralUser GS v1.471.sf2\"\n\n[autoexec]\nc:\nmixer master 50\nautotype -w 0.5 1\ndemo\nexit\n
"},{"location":"releases/","title":"Index","text":"Dummy page for redirecting links to to top-level sections
"},{"location":"releases/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 Windows, macOS, or Linux download pages.
Build artifacts are hosted on GitHub; you need to be logged in to GitHub to download them.
Download link Build version Date \u00b9 Windows builds include x86_64 installer and portable ZIP packages, and the experimental ARM64 portable ZIP package.
\u00b2 macOS builds include Intel, Apple silicon, and universal binary package.
\u00b3 We provide a statically linked x86_64 Linux package (only depends on C/C++, ALSA, and OpenGL system libraries).
"},{"location":"releases/development-builds/#installation-notes","title":"Installation notes","text":""},{"location":"releases/development-builds/#windows","title":"Windows","text":"Windows executables in snapshot packages are not signed, therefore Windows 10 or later might prevent the program from starting.
See this guide to learn how to deal with this.
"},{"location":"releases/development-builds/#macos","title":"macOS","text":"macOS development builds are not notarized (but the public releases are); Apple Gatekeeper will try to prevent the program from running.
See this guide to learn how to deal with this.
"},{"location":"releases/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":"releases/development-builds/#fedora","title":"Fedora","text":"sudo dnf install SDL2 SDL2_net opusfile\n
"},{"location":"releases/development-builds/#debian-ubuntu","title":"Debian, Ubuntu","text":"sudo apt install libsdl2-2.0-0 libsdl2-net-2.0-0 libopusfile0\n
"},{"location":"releases/development-builds/#arch-manjaro","title":"Arch, Manjaro","text":"sudo pacman -S sdl2 sdl2_net opusfile\n
"},{"location":"releases/development-builds/#upgrading-your-primary-configuration","title":"Upgrading your primary configuration","text":"Testing new features might require a manual reset of the configuration file.
Since config settings might get renamed, altered, or deprecated between builds, it\u2019s best to let DOSBox Staging write the new default primary config on the first launch, then reapply your old settings manually.
Start by backing up your existing primary config. This is where to find it on each platform:
Windows C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox-staging.conf macOS ~/Library/Preferences/DOSBox/dosbox-staging.conf Linux ~/.config/dosbox/dosbox-staging.conf You can also execute DOSBox Staging with the --printconf option to have the location of the primary config printed to your console.
After backing up the existing primary config, simply start the new version\u2014a new dosbox-staging.conf will be written containing the new defaults and updated setting descriptions.
Portable mode notes
In portable mode, dosbox-staging.conf resides in the same folder as your DOSBox Staging executable. The migration steps for portable mode users are as follows:
- Unpack the new version into a new folder (this is important).
- Create a new empty
dosbox-staging.conf file in the new folder to enable portable mode. - Launch the new version.
DOSBox Staging will write the new defaults to the empty dosbox-staging.conf file. After this, you carry over your settings from the old primary config manually.
"},{"location":"releases/development-builds/#after-upgrading","title":"After upgrading","text":"Look for deprecation warnings in the logs (in yellow or orange colours) and update your configs accordingly.
"},{"location":"releases/linux/","title":"Linux releases","text":""},{"location":"releases/linux/#current-stable-version","title":"Current stable version","text":"Download DOSBox Staging 0.82.0 (x86_64) sha256: TODOTODO
Our pre-compiled builds run on most desktop Linux distributions (x86_64 only for now). They only depend on the C/C++, ALSA, and OpenGL system libraries.
Please run the install-icons.sh script included with the release to install the application icons.
Check out the 0.82.0 release notes to learn about the changes and improvements introduced in this release.
If you\u2019re new to DOSBox Staging, we highly recommend following the Getting started guide.
"},{"location":"releases/linux/#hardware-requirements","title":"Hardware requirements","text":"From the x86 family of processors, a processor with SSSE3 (Supplemental Streaming SIMD Extensions 3) is required.
"},{"location":"releases/linux/#external-repository-packages","title":"External repository packages","text":"DOSBox 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":"releases/linux/#containerised-packages","title":"Containerised packages","text":""},{"location":"releases/linux/#fedora-repository-package","title":"Fedora repository package","text":"sudo dnf install dosbox-staging\n
"},{"location":"releases/linux/#gentoo-repository-package","title":"Gentoo repository package","text":"emerge games-emulation/dosbox-staging\n
"},{"location":"releases/linux/#ubuntu-and-mint-repository-package","title":"Ubuntu and Mint repository package","text":"Available via Personal Package Archive:
sudo add-apt-repository ppa:feignint/dosbox-staging\nsudo apt-get update\nsudo apt install dosbox-staging\n
"},{"location":"releases/linux/#arch-and-manjaro-repository-package","title":"Arch and Manjaro repository package","text":"Available via Arch User Repository.
"},{"location":"releases/linux/#nixos-repository-package","title":"NixOS repository package","text":"Available via NixOS or Home Manager. Add the following to your configuration.nix file:
For NixOS:
environment.systemPackages = with pkgs; [\n dosbox-staging\n];\n
For Home Manager:
home.packages = with pkgs; [\n dosbox-staging\n];\n
Then rebuild your system with: nixos-rebuild switch
"},{"location":"releases/linux/#other-repository-packages","title":"Other repository packages","text":""},{"location":"releases/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\n
"},{"location":"releases/linux/#retropie-package","title":"RetroPie package","text":"You can easily configure your DOS games on Retropie to use DOSBox Staging via RetroPie-Setup (select Optional Packages \u2192 DOSBox Staging).
"},{"location":"releases/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":"releases/linux/#older-releases","title":"Older releases","text":" -
Download DOSBox Staging 0.81.2 (x86_64) sha256: c47f1767ae1371666f40e3a4e13272da5c5a98c9c6f355b4fb82bac0d3911a68
-
DOSBox Staging 0.81.1 (tar.xz) sha256: 5aee92774569cf1e39ade3fccff03994464d17b396b0ae98360af61e9d37cba7
-
DOSBox Staging 0.81.0 (tar.xz) sha256: 034b08a941a7fd0279a81b10af620999c569f7e81b786e7f4b59a0b94e46d399
-
DOSBox Staging 0.80.1 (tar.xz) sha256: 12582a6496b1a276cd239e6b3d21ddfcd51fd8f9e40a1ebbc0a3800e0636190a
-
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
"},{"location":"releases/linux/#building-from-source","title":"Building from source","text":"Of course, you can always build DOSBox Staging straight from the source.
Send us patches if you improve something!
"},{"location":"releases/macos/","title":"macOS releases","text":""},{"location":"releases/macos/#current-stable-version","title":"Current stable version","text":"Download DOSBox Staging 0.82.0 Universal Binary (dmg) sha256: TODOTODO
DOSBos Staging requires macOS 10.15 (Catalina) or later, and supports both Intel and Apple silicon Macs.
Check out the 0.82.0 release notes to learn about the changes and improvements introduced by this release.
If you\u2019re new to DOSBox Staging, we highly recommend following the Getting started guide.
"},{"location":"releases/macos/#hardware-requirements","title":"Hardware requirements","text":"The latest release is compatible with macOS 10.15 (Catalina) or newer and supports both 64-bit Intel and Apple silicon Macs.
"},{"location":"releases/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\n
"},{"location":"releases/macos/#macports","title":"MacPorts","text":"The 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\n
If 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":"releases/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":"releases/macos/#apple-gatekeeper","title":"Apple Gatekeeper","text":"For releases before 0.81.0 and the development snapshot builds, you\u2019ll need to do the following when launching DOSBox Staging for the first time.
You\u2019ll need to repeat these steps after upgrading to a more recent development build.
"},{"location":"releases/macos/#macos-sequoia-15","title":"macOS Sequoia 15","text":" - Open the DOSBox Staging app, then click Done in the appearing dialog.
- Follow these instructions to allow launching DOSBox Staging in the Privacy & Security tab in System Settings.
"},{"location":"releases/macos/#macos-sonoma-14-or-earlier","title":"macOS Sonoma 14 or earlier","text":" - Ctrl click (or right-click) on the DOSBox Staging app, then click Open.
- Click OK to close the appearing dialog.
- Open the app a second time\u2014now Gatekeeper will show an Open button. Press this to launch DOSBox Staging.
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 were not in a position to make such payments prior to version 0.81.0, and therefore asked users to bypass Apple\u2019s Gatekeeper manually.
Read the first section of this Apple Support article for further info.
"},{"location":"releases/macos/#older-releases","title":"Older releases","text":" -
Download DOSBox Staging 0.81.2 Universal Binary (dmg) (macOS 10.15 or newer) sha256: 718968485a0418ead3434285e3a6ab4853914d29d38e14289711af1b2152368e
-
DOSBox Staging 0.81.1 Universal Binary (dmg) (macOS 10.15 or newer) sha256: 0f89f42d93c39fe96634934e19ef5a9f0a6978d6568e853e95c3f2154b9dbe9c
-
DOSBox Staging 0.81.0 Universal Binary (dmg) (macOS 10.15 or newer) sha256: 5d3cec60552b2a34caa70702b35bdf9ce591cf0b03143802351725a7c729d9fe
-
DOSBox Staging 0.80.1 Universal Binary (dmg) (macOS 10.15 or newer) sha256: 46a256645255e8345981ea357f1416b8ce4bc60a2aba9a86b5122d5075aa7fa9
-
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
"},{"location":"releases/macos/#building-from-source","title":"Building from source","text":"Of course, you can always build DOSBox Staging straight from the source.
Send us patches if you improve something!
"},{"location":"releases/windows/","title":"Windows releases","text":""},{"location":"releases/windows/#current-stable-version","title":"Current stable version","text":" - Download DOSBox Staging 0.82.0 (x86_64, Installer) sha256: TODOTODO
- Download DOSBox Staging 0.82.0 (x86_64, Portable ZIP) sha256: TODOTODO
DOSBox Staging requires 64-bit Windows 8, 10, or 11.
Check out the 0.82.0 release notes to learn about the changes and improvements introduced in this release.
If you\u2019re new to DOSBox Staging, we highly recommend following the Getting started guide.
Important
If Windows Security prevents you from running DOSBox Staging via Windows Defender SmartScreen (the built-in Windows antivirus), please follow these instructions.
"},{"location":"releases/windows/#hardware-requirements","title":"Hardware requirements","text":"An x86 processor with SSSE3 (Supplemental Streaming SIMD Extensions 3) is required.
"},{"location":"releases/windows/#legacy-windows-support","title":"Legacy Windows support","text":"If you\u2019re still on a legacy Windows version, you can use the following older releases. Note these earlier version come with zero official support; the core team won\u2019t be able to help you if you run into issues. Our recommendation will always be to upgrade your Windows and use the latest stable version.
"},{"location":"releases/windows/#windows-810-32-bit","title":"Windows 8/10 32-bit","text":"The official distribution packages only support 32-bit Windows 8 or 10 up to version 0.80.1:
-
For 32-bit Windows 8 or 10, use the 0.80.1 portable ZIP package.
-
For 64-bit Windows 8 or 10, use the current stable version.
"},{"location":"releases/windows/#windows-7","title":"Windows 7","text":"The official distribution packages only support Windows 7 up to version 0.80.1:
-
For 64-bit Windows 7, use the 0.80.1 installer and select the MSVC build, or the 0.81.1 portable ZIP package.
-
For 32-bit Windows 7, use the 0.80.1 portable ZIP package.
"},{"location":"releases/windows/#windows-vista","title":"Windows Vista","text":"The official distribution packages only support Windows Vista up to version 0.78.1.
"},{"location":"releases/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":"releases/windows/#experimental-windows-arm64-builds","title":"Experimental Windows ARM64 builds","text":"We started providing experimental Windows ARM64 packages for devices such as the Snapdragon X Elite. Note we don\u2019t provide any official support for these builds yet.
The ARM64 packages can be downloaded from our development builds page.
"},{"location":"releases/windows/#windows-defender","title":"Windows Defender","text":"Windows Defender (the built-in Windows antivirus starting from Windows 8) might prevent you from running DOSBox Staging when you start it for the first time.
This is a false positive; DOSBox Staging has no malicious code whatsoever, just antivirus software tend to be mistakenly flag emulators as \u201cmalware\u201d.
If this happens, please follow the below steps to grant Windows permission to run DOSBox Staging. You may need to repeat these steps after upgrading to a newer version.
"},{"location":"releases/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.
Consider also performing Method 3 to make DOSBox Staging start up faster.
"},{"location":"releases/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.
Consider also performing Method 3 to make DOSBox Staging start up faster.
"},{"location":"releases/windows/#method-3","title":"Method 3","text":"Add an exclusion to Windows Security to whitelist the DOSBox Staging executable or the folder in which it resides. We recommend doing so even if you\u2019ve already performed either of the previous methods, as it can eliminate the 3\u20135 second startup delay caused by the real-time antivirus scan.
See the steps on how to do this here and here.
"},{"location":"releases/windows/#explanation","title":"Explanation","text":"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":"releases/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":"releases/windows/#older-releases","title":"Older releases","text":" -
Download DOSBox Staging 0.81.2 (x86_64, Installer) (Windows 8 or newer) sha256: 7c23512666f694420e5e2612742de5fb64b32d336e54359b65fd21e7107ef51c
-
Download DOSBox Staging 0.81.2 (x86_64, Portable ZIP) (Windows 8 or newer) sha256: d7ec6054ae58d287c3ad5fbf4c3df732ea3fd75ae828c8f4481fcf7c6203d168
-
DOSBox Staging 0.81.1 (Installer) (Windows 8 or newer) sha256: 4bb5e63bfef41d4a6ee8f7af3b8c5ee6756987c4247197db0b16d888c6ac0705
-
DOSBox Staging 0.81.1 (Portable ZIP) (Windows 8 or newer) sha256: cb45e4e56b85cac7b8b1eb63a1bbd93430a226215a5c04f2700076c279d10e12
-
DOSBox Staging 0.81.0 (Installer) (Windows 8 or newer) sha256: 7de2cbdd8b320017dcf904c3df58b15088047954b053757c870279cbbb301393
-
DOSBox Staging 0.81.0 (Portable ZIP) (Windows 8 or newer) sha256: ce772a963716d63610e6cb0e817b16f1b5a3cbfd3d5ad802726ddd583f32b79d
-
DOSBox Staging 0.80.1 64-bit (Installer) (Windows 8 or newer) sha256: 94b961f397f3b70a13daf3b573857b5262515e75d490bfc19f019479fe1694f8
-
DOSBox Staging 0.80.1 64-bit (Portable ZIP) (Windows 8 or newer) sha256: e7ab98013b55f6fd6db1f529574b8f2905d374225f532ce0905666281cbe32af
-
DOSBox Staging 0.80.1 32-bit (Portable ZIP) (Windows 8 or newer) sha256: 63a8c5b084231364961f7c8b6415e44622c5ab9822e49839c2aca1bddd3a9459
-
DOSBox Staging 0.80.0 64-bit (Installer) (Windows 7 or newer) sha256: 84445c869e58f6b4591484f6178c7b5b3c8f284bf9460e9afc4502ba842ab039
-
DOSBox Staging 0.80.0 64-bit (Portable 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 (Portable ZIP) (Windows 7 or newer) sha256: 8c7045dfea6dc20bb985cff516d2faee51d2ecaf054db60632857b6941d3d648
-
DOSBox Staging 0.78.1 64-bit (Portable ZIP) (Windows Vista or newer) sha256: 3c2f408125351154a37e93de8a4bd05d0c722bbf53e1f583909e4ca6c3eb9204
-
DOSBox Staging with built-in debugger 0.78.1 64-bit (Portable ZIP) (Windows Vista or newer) sha256: b99f3c354f831ed2b0ed04d215170f696b6fc18285b0c7192c0abab62c41bbc8
-
DOSBox Staging 0.78.0 64-bit (Portable ZIP) (Windows Vista or newer) sha256: f13cba664259fdb0db5e32826e13dcded4270557963f6e823a4731129f23a8a3
-
DOSBox Staging 0.78.0 32-bit (Portable ZIP) (Windows Vista or newer) sha256: 0ca9201cdf3f3a1576b97b0de0e87280b75c633976f0b179ba33a68d44f5ba56
-
DOSBox Staging 0.77.1 64-bit (Portable ZIP) (Windows Vista or newer) sha256: 11ba992ece6d3e4ef2046fcdb6d842da364b69720a921d61fdcc793eb52e7051
-
DOSBox Staging 0.77.1 32-bit (Portable ZIP) (Windows Vista or newer) sha256: a34883101486ce2af071a29c6390f2038889fc519e042101284f2a6999d9f0ef
-
DOSBox Staging 0.77.0 64-bit (Portable ZIP) (Windows Vista or newer) sha256: cacdac418642fd8c7faf1e5955110c35d0c207392ae20835707fd2a1e1114b82
-
DOSBox Staging 0.77.0 32-bit (Portable ZIP) (Windows Vista or newer) sha256: f718d07bab69e3e1be0b28207039cea2746c7e45b8ba7a19b625011f477e609a
-
DOSBox Staging 0.76.0 32-bit (Portable ZIP) (Windows Vista or newer) sha256: 646d2f3fa8189e411589fedcb8148a295361693a6ce95d08e06f4a70e5a36b16
-
DOSBox Staging 0.75.2 64-bit (Portable ZIP) (Windows Vista or newer) sha256: 09f0ca911813a64b8814880eb6e49ad4dcdac9a5bb9263c4887ad82b71fad292
-
DOSBox Staging 0.75.2 32-bit (Portable ZIP) (Windows Vista or newer) sha256: 51dc171ff52ea395c6a22f09ebb98a93974a95c701ca81008368c22a66deced2
-
DOSBox Staging 0.75.1 64-bit (Portable ZIP) (Windows Vista or newer) sha256: 80c60c4377ff2882649f113b3cb3bcd407c17acaac344c49fa1fc4229813f012
-
DOSBox Staging 0.75.1 32-bit (Portable ZIP) (Windows Vista or newer) sha256: 843c742a348f575862e152e02cf174be0ea1c52bdb6e4bffd65f34af88b566b7
-
DOSBox Staging 0.75.0 32-bit (Portable ZIP) (Windows Vista or newer, supports CPUs without SSE4.2) sha256: 69046adcef2ef9920fbba8d40fc9e51f3dd144ba4549787e1816cf1c2ae87d71
-
DOSBox Staging 0.75.0-rc1 32-bit (Portable ZIP) (Windows Vista or newer, supports CPUs without SSE4.2) sha256: 738d2ae2101384f2eeaf1895de64cf1b4c76eaf7873de7e15b7f52145dfed7e7
"},{"location":"releases/windows/#building-from-source","title":"Building from source","text":"Of course, you can always build DOSBox Staging straight from the source.
Send us patches if you improve something!
"},{"location":"releases/release-notes/0.75.0-rc1/","title":"0.75.0-RC1 release notes","text":"Release date: 2020-04-22
"},{"location":"releases/release-notes/0.75.0-rc1/#installation-instructions","title":"Installation instructions","text":" - Linux (or Steam on Linux)
- Windows
- macOS
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":"releases/release-notes/0.75.0/","title":"0.75.0 release notes","text":"Release date: 2020-05-06
"},{"location":"releases/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":"releases/release-notes/0.75.0/#installation-instructions","title":"Installation instructions","text":" - Linux (or Steam on Linux)
- Windows
- macOS
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":"releases/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":"releases/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:
- Dropped 3,211 lines of SDL 1.2 code in place of 1,664 lines, for just under a 50% reduction in code-size.
- Eliminated several OS-specific branches and all SDL1-specific kludges.
- Eased support for modern graphic APIs, and opened the field for new features and improvements.
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\n
macOS users can try Metal:
[sdl]\noutput = texture\ntexture_renderer = metal\n
And everyone can use OpenGL as texture backend:
[sdl]\noutput = texture\ntexture_renderer = opengl\n
Or just use texture_renderer = auto to let SDL pick the backend appropriate for your operating system.
"},{"location":"releases/release-notes/0.75.0/#support-flac-opus-and-mp3-cd-da-tracks","title":"Support FLAC, Opus, and MP3 CD-DA tracks","text":"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\n
For 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\n
FLAC 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\n
When 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\n
If 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\n
"},{"location":"releases/release-notes/0.75.0/#pixel-perfect-scaling-mode","title":"Pixel-perfect scaling mode","text":"Pixel-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\n[render]\nscaler = none\nglshader = none\n
Pixel-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":"releases/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\n
On 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.
"},{"location":"releases/release-notes/0.75.0/#autotype-command","title":"AUTOTYPE command","text":"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\n
Some games that benefit from AUTOTYPE on startup are listed on the wiki page.
"},{"location":"releases/release-notes/0.75.0/#changed-rendering-defaults","title":"Changed rendering defaults","text":"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":"releases/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 game
The 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\n
This 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":"releases/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).
"},{"location":"releases/release-notes/0.75.0/#reload-key-bindings-at-runtime","title":"Reload key bindings at runtime","text":"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.
"},{"location":"releases/release-notes/0.75.0/#reloading-key-bindings","title":"Reloading key bindings","text":"You can now change key bindings at runtime by loading them from a file:
Z:\\> config -set \"sdl mapperfile=<path-to-file>\"\n
"},{"location":"releases/release-notes/0.75.0/#other-new-options-svn","title":"Other new options (SVN)","text":"DOSBox added a number of features to the CONFIG command. To list them all, run:
Z:\\> config /?\n
"},{"location":"releases/release-notes/0.75.0/#configuration-file-locations","title":"Configuration file locations","text":""},{"location":"releases/release-notes/0.75.0/#linux","title":"Linux","text":"DOSBox 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/\n
Users can customize the parent (.config/) location by setting the XDG_CONFIG_HOME environment variable, according to the XDG Specification.
"},{"location":"releases/release-notes/0.75.0/#macos","title":"macOS","text":"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/\n
"},{"location":"releases/release-notes/0.75.0/#windows","title":"Windows","text":"No changes; the configuration files are created in:
C:\\Users\\<username>\\AppData\\Local\\DOSBox\\\n
"},{"location":"releases/release-notes/0.75.0/#modem-phonebook","title":"Modem phonebook","text":"You 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\n
Now 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":"releases/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":"releases/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":"releases/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.
"},{"location":"releases/release-notes/0.75.0/#cga-composite-mode-svn","title":"CGA Composite mode (SVN)","text":"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":"releases/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\n
It\u2019s also possible to provide your shader implementations by placing .glsl files in the configuration directory:
Linux ~/.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\n
Note
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":"releases/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\n
Note 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":"releases/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\n
File TEST.TXT is written to the directory backup, and not to real.
"},{"location":"releases/release-notes/0.75.0/#overview-of-changes","title":"Overview of changes","text":""},{"location":"releases/release-notes/0.75.0/#removed-features","title":"Removed features","text":" - DOSBox Staging does not run on Operating System/2 (OS/2) or derivatives.
- DOSBox Staging does not run on Windows XP or earlier Windows versions.
- Removed support for old DirectDraw (
ddraw) output. Use output = texture, texture_renderer = directx11 instead. - Removed support for old
overlay output. Use any other output. - Removed support for relative window size (
windowresolution = X%). - Removed support for 64-bit Zip Motion Blocks Video (ZMBV) codec (old 32-bit codec still works).
- Removed support for CD-DA playback from physical disks. It is still possible to install games distributed on CDs by mounting them as directories (#260)
- Removed CD-DA playback support for tracks using the Audio Interchange File Format AIFF audio codec.
"},{"location":"releases/release-notes/0.75.0/#development-changes","title":"Development changes","text":" -
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.
- Active SVN branch paths were imported as Git branches (named
svn/<name>). - SVN tag paths were imported as Git lightweight tags (named
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:
- builds cleanly on all supported platforms and compilers,
- adds no new compiler warnings, and
- adds no new static or dynamic analysis issues.
-
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.
"},{"location":"releases/release-notes/0.75.0/#known-issues","title":"Known issues","text":" - Inconsistent minimum window size with
windowresolution = resizable when leaving fullscreen. - Windows, macOS: Window content is not refreshed when resizing.
- Windows, macOS: Emulation stops when moving or resizing window.
- Linux: Wayland crashes (Wayland support is \u201cexperimental\u201d at the moment).
- Linux: Splash screen is sometimes transparent or corrupted on KDE.
Submit new issues or learn more about existing ones using our bug-tracker.
"},{"location":"releases/release-notes/0.75.0/#contributors","title":"Contributors","text":"During the DOSBox Staging 0.75 development period:
- 11 DOSBox Staging contributors submitted 208 pull requests comprised of 780 commits written by 18 authors.
- 69 DOSBox Staging issues were reported and addressed.
- 54 DOSBox Staging wiki updates were made.
- Three DOSBox (SVN) maintainers committed 76 changes written by 5 authors. These changes have been incorporated into DOSBox Staging.
"},{"location":"releases/release-notes/0.75.0/#maintainers","title":"Maintainers","text":" - Patryk Obara
- kcgen
- Anton Shepelev (ant-222)
"},{"location":"releases/release-notes/0.75.0/#direct-contributors","title":"Direct contributors","text":" - Anton Shepelev (ant-222)
- Joshua Fern
- kcgen
- Marco Maccaferri
- NicknineTheEagle
- Nopey Nope
- numberZero
- Patrick McMorris
- Patryk Obara
- Troy Campbell
- Wouter Wijsman
"},{"location":"releases/release-notes/0.75.0/#testers-and-wiki-contributors","title":"Testers and wiki contributors","text":" - GranMinigun
- kas1e
- nemo93
- rderooy
"},{"location":"releases/release-notes/0.75.0/#indirect-contributors","title":"Indirect contributors","text":"Library or patch authors, upstream SVN developers, etc.
- Alexey Khokholov (nukeykt)
- Arthur Ouellet
- David Reid
- jmarsh
- NY00123
- Peter Veenstra
- ripsaw8080
- Ryan C. Gordon
- Sean Barrett
- Sjoerd van der Berg
- VileRancour
- Yann Collet
"},{"location":"releases/release-notes/0.75.0/#changelog","title":"Changelog","text":"You can read detailed changelog via Git, e.g. using the following command:
git shortlog ^v0.75.0-pre v0.75.0 --no-merges\n
"},{"location":"releases/release-notes/0.75.0/#merged-in-community-patches-and-libraries","title":"Merged-in community patches and libraries","text":"The 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
- Add built-in xxHash (v0.7.3) (Yann Collet)
- Add built-in Vorbis codec: (v1.17) (Sean Barrett)
- Add built-in SDL_sound r599 (LGPL) (Ryan C. Gordon)
- Add built-in C++ object serializer (Arthur Cuellet)
- Add built-in FLAC codec: dr_flac v0.12.11 (David Reid)
- Add built-in MP3 codec: dr_mp3 v0.6.4 (David Reid)
- Add built-in WAV codec: dr_wav v0.12.1 (David Reid)
Patryk Obara
- Replace SDL 1.2 with SDL 2.0 (based on work of NY00123)
- Add Nuked OPL3 emulator v1.8 (Alexey Khokholov)
Peter Veenstra
Changes merged-in to SVN
- Add OpenGL shader support (ny00123 and refined by jmarsh)
-
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)
- Fix some issues with commit 4282 (Patryk Obara and 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
- Add cga_mono machine (VileRancour)
"},{"location":"releases/release-notes/0.75.0/#thank-you","title":"Thank you","text":"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
"},{"location":"releases/release-notes/0.75.1/","title":"0.75.1 release notes","text":"Release date: 2020-08-19
"},{"location":"releases/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":"releases/release-notes/0.75.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
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":"releases/release-notes/0.75.1/#new-features-in-detail","title":"New features in detail","text":""},{"location":"releases/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":"releases/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":"releases/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)\n
Users previously had to debug the dosbox binary to discover the base address; an easy but tedious process.
"},{"location":"releases/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)
"},{"location":"releases/release-notes/0.75.1/#contributors","title":"Contributors","text":""},{"location":"releases/release-notes/0.75.1/#maintainers","title":"Maintainers","text":""},{"location":"releases/release-notes/0.75.1/#direct-contributors","title":"Direct contributors","text":" - Expack3
- kcgen
- nemo93
- Patryk Obara
- WengierWu
"},{"location":"releases/release-notes/0.75.1/#indirect-contributors","title":"Indirect contributors","text":""},{"location":"releases/release-notes/0.75.1/#changelog","title":"Changelog","text":"You can read detailed changelog via Git, e.g. using the following command:
git shortlog ^v0.75.0 v0.75.1\n
"},{"location":"releases/release-notes/0.75.1/#thank-you","title":"Thank you","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"releases/release-notes/0.75.2/","title":"0.75.2 release notes","text":"Release date: 2020-10-26
"},{"location":"releases/release-notes/0.75.2/#summary","title":"Summary","text":"This is a maintenance release from the 0.75.x stable branch.
"},{"location":"releases/release-notes/0.75.2/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.75.2/#new-features-in-detail","title":"New features in detail","text":""},{"location":"releases/release-notes/0.75.2/#select-monochrome-palette-colour","title":"Select monochrome palette colour","text":"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\n
See: #607
"},{"location":"releases/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\n
The 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":"releases/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)
"},{"location":"releases/release-notes/0.75.2/#notes-for-packagers","title":"Notes for packagers","text":"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\"\n
-
Our 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":"releases/release-notes/0.75.2/#contributors","title":"Contributors","text":""},{"location":"releases/release-notes/0.75.2/#maintainers","title":"Maintainers","text":" - Patryk Obara
- kcgen
- nemo93
"},{"location":"releases/release-notes/0.75.2/#contributors_1","title":"Contributors","text":" - Bernard Cafarelli
- David Heidelberg
- Feignint
- MasterO2
- NicknineTheEagle
- WengierWu
"},{"location":"releases/release-notes/0.75.2/#thank-you","title":"Thank you","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"releases/release-notes/0.76.0/","title":"0.76.0 release notes","text":"Release date: 2020-12-03
"},{"location":"releases/release-notes/0.76.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.76.0/#summary","title":"Summary","text":"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":"releases/release-notes/0.76.0/#new-features-in-detail","title":"New features in detail","text":""},{"location":"releases/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 the audio 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":"releases/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)
"},{"location":"releases/release-notes/0.76.0/#built-in-midi-support-via-fluidsynth","title":"Built-in MIDI support via FluidSynth","text":"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\n[fluidsynth]\nsoundfont = my-favourite-soundfont.sf2\n
DOSBox 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).
"},{"location":"releases/release-notes/0.76.0/#fine-grained-midi-level-controls","title":"Fine-grained MIDI level controls","text":"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\n
This 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\n
"},{"location":"releases/release-notes/0.76.0/#what-soundfont-should-i-use","title":"What soundfont should I use?","text":"This 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":"releases/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":"releases/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":"releases/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.
"},{"location":"releases/release-notes/0.76.0/#ls-command","title":"LS command","text":"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:
- Fits as many directory entries as possible on the screen
- Differentiates directories, executables, and plain files using color
- Prints files in lowercase and directories in uppercase, Norton Commander style
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
"},{"location":"releases/release-notes/0.76.0/#rapid-dc-offset-correction-for-the-emulated-pc-speaker","title":"Rapid DC offset correction for the emulated PC speaker","text":"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":"releases/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:
- Initial audio by all emulated devices is fed through a 15-ms envelope specifically timed to prevent unnatural electronic pops and clicks, yet fast enough to ensure that sharp-attack natural sounds (such as a cymbal crash) are not affected.
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
- Some games test their interface to the Sound Blaster 16 using one or more small \u201cjunk\u201d DMA transfers. Unfortunately on actual hardware, these result in startup clicks and pops, which can be jarring when using a headset. We now suppress these initial junk transfers.
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":"releases/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":"releases/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":"releases/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\n
For 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":"releases/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":"releases/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":"releases/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:
- Alt+Enter \u2013 Switch between fullscreen and window mode
- Alt+Pause \u2013 Pause/Unpause emulator
- Ctrl+F1 \u2013 Start the keymapper
- Ctrl+F4 \u2013 Change between mounted floppy/CD images
- Ctrl+F5 \u2013 Save a screenshot
- Ctrl+F6 \u2013 Start/Stop recording sound output to a wave file
- Ctrl+F7 \u2013 Start/Stop recording video output to a zmbv file
- Ctrl+F9 \u2013 Shutdown emulator
- Ctrl+F10 \u2013 Capture/Release the mouse
- Ctrl+F11 \u2013 Slow down emulation
- Ctrl+F12 \u2013 Speed up emulation
- Ctrl+Alt+Home \u2013 Restart emulator
- Hold Alt+F12 \u2013 Fast forward
Keymapper received tiny usability improvements as well: it displays the keyboard shortcut (binding) for the selected action.
"},{"location":"releases/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":"releases/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":"releases/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":"releases/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":"releases/release-notes/0.76.0/#bugfixes","title":"Bugfixes","text":"Some notable bugfixes:
- Prevent SDL2 crash on exit when using Wayland. (#336)
- Fix sound effects in Prince of Persia on Tandy. (#457)
- Prevent crash on SDL2 re-creating OpenGL window. (#510)
- Fix
dir /p in non-standard text modes. (#528) - Prevent injection of spurious newlines in autoexec and bat files. (#536)
- Fix
capture_mouse middlegame setting. (#563) - Fix a CD-DA roll-over bug when calculating PCM frames. (#569)
- Fix boot failure from an image mounted as C:. (#589)
- Fix memory leak in the modem phone book. (#622)
- Fix
cls command. (#639) - Increase default DOS file limit for emulation of program Subiekt 4. (#656)
-
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)
"},{"location":"releases/release-notes/0.76.0/#known-issues","title":"Known issues","text":" -
(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.
"},{"location":"releases/release-notes/0.76.0/#removed-features","title":"Removed features","text":" -
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).
"},{"location":"releases/release-notes/0.76.0/#notes-for-developers","title":"Notes for developers","text":" -
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":"releases/release-notes/0.76.0/#changes-merged-from-upstream-projects","title":"Changes merged from upstream projects","text":" - Merge DOSBox SVN changes up to revision 4392
- Sync dr_mp3 v0.6.11 from upstream
- Sync dr_flac v0.12.13 from upstream
- Sync dr_wav v0.12.4 from upstream
- Sync xxhash 0.8.0 from upstream
- Sync stb header v2.36 from upstream
- Sync stb_vorbis v1.19 from upstream
"},{"location":"releases/release-notes/0.76.0/#contributors","title":"Contributors","text":"During DOSBox Staging 0.76 development period we merged 1035 commits, including 55 commits originating from the DOSBox project.
"},{"location":"releases/release-notes/0.76.0/#maintainers","title":"Maintainers","text":" - Patryk Obara
- kcgen
- nemo93
"},{"location":"releases/release-notes/0.76.0/#direct-contributors","title":"Direct contributors","text":" - Affonso Amendola
- Bernard Cafarelli
- cfoesch
- ClassicHasClass
- David Heidelberg
- drfiemost
- Edward Betts
- Erlotinib
- Expack3
- Feignint
- Jonathan Campbell
- MasterO2
- NicknineTheEagle
- Nikos Chantziaras
- Robert de Rooy
- Troy Campbell
- Tyrell Sassen
- Vladimir Serbinenko
- Wengier
"},{"location":"releases/release-notes/0.76.0/#dosbox-contributors","title":"DOSBox contributors","text":"SVN r4336:r4392
- Harekiet
- jmarsh
- Jonathan Campbell
- NewRisingSun
- Qbix
- ripsaw8080
"},{"location":"releases/release-notes/0.76.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":"releases/release-notes/0.77.0/","title":"0.77.0 release notes","text":"Release date: 2021-07-21
"},{"location":"releases/release-notes/0.77.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.77.0/#significant-changes","title":"Significant changes","text":""},{"location":"releases/release-notes/0.77.0/#migrated-to-the-meson-build-system","title":"Migrated to the Meson build system","text":"Migrated Staging from autotools to the Meson build system. Those building from source, please see BUILD.md in the repository. See: #854
"},{"location":"releases/release-notes/0.77.0/#macos-and-selinux-security-policy-compliance","title":"macOS and SELinux security policy compliance","text":"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":"releases/release-notes/0.77.0/#variable-expansion-in-the-interactive-dos-shell","title":"Variable expansion in the interactive DOS shell","text":"See: #1059
"},{"location":"releases/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.
"},{"location":"releases/release-notes/0.77.0/#finished-mt-32-integration","title":"Finished MT-32 integration","text":"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.
"},{"location":"releases/release-notes/0.77.0/#ibm-ps1-audio-device-support","title":"IBM PS/1 Audio device support","text":"See the wiki notes for how to use it.
Thanks to JMK for authoring PS/1 Audio emulation in 2008.
"},{"location":"releases/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.
"},{"location":"releases/release-notes/0.77.0/#macos-hotkey-changes","title":"macOS hotkey changes","text":"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":"releases/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":"releases/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.
"},{"location":"releases/release-notes/0.77.0/#relative-window-size-support","title":"Relative window size support","text":"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).
"},{"location":"releases/release-notes/0.77.0/#window-resizing-enabled-by-default","title":"Window resizing enabled by default","text":"Window resizing using corner-drag is now auto-enabled on all platforms when conditions permit.
"},{"location":"releases/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)
"},{"location":"releases/release-notes/0.77.0/#contributions","title":"Contributions","text":"The 0.77 release includes 920 commits plus 35 commits originating from the DOSBox project.
"},{"location":"releases/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:
- Antti Peltola (macOS testing and feedback)
- Brandon Munger (collaborator)
- Burrito78 (macOS testing and feedback)
- GranMinigun (testing and triage)
- kcgen (maintainer)
- Kirk Klobe (maintainer)
- Dennis L\u00fchring (collaborator)
- nemo93 (Wiki maintainer)
- Patryk Obara (maintainer)
- Ruben Genoese (testing and triage)
- Wengier (collaborator)
"},{"location":"releases/release-notes/0.77.0/#direct-contributors","title":"Direct contributors","text":"The following authors, co-authors, wiki editors, translators, testers, and bug reporters directly contributed to the 0.77 release:
- Allofich
- Antti Peltola
- Brandon Munger
- Burrito78
- Dennis L\u00fchring
- Didu
- Draky50110
- Dugan Chen
- eli-schwart
- Emmanuel Gil Peyrot
- Feignint
- Gilles
- GranMinigun
- hail-to-the-ryzen
- IlyaIndigo
- IPeluchito
- jmarsh
- Joshua Kr\u00e4mer
- Kappa971
- kcgen
- Ken H\u00e4ndel
- Kirk Klobe
- mdmallard
- nemo93
- Otto Urpelainen
- Patryk Obara
- Peluchito
- Ruben Genoese
- rhys073
- Sarah Whitman
- Toby Jennings
- warpdesign
- Wengier
"},{"location":"releases/release-notes/0.77.0/#dosbox-contributors","title":"DOSBox contributors","text":"The following DOSBox authors\u2019 SVN commits (r4393 through r4459) were merged during the 0.77 timeframe:
- jmarsh
- Peter Veenstra
- ripsaw8080
- Sjoerd van der Berg
"},{"location":"releases/release-notes/0.77.0/#indirect-contributors","title":"Indirect contributors","text":"The following patch or external project authors\u2019 sources were merged during the 0.77 timeframe:
- Antti S. Lankila (reSIDfp maintainer)
- Dag Lem (original reSID author)
- David Reid (dr_libs audio codecs author)
- Dean Beeler (original MT-32 patch author)
- Jason Kim (PS/1 patch author)
- Jonathan Campbell (DOSBox-X maintainer)
- nukeykt (Nuked OPL emulator author)
- sergm (Munt and MT-32 patch maintainer)
- Vasyl Tsvirkunov (SS1-2001 patch author)
- Wengier (DOSBox-X maintainer)
- ykhwong (DOSBox Daum maintainer)
"},{"location":"releases/release-notes/0.77.0/#thank-you","title":"Thank you","text":"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":"releases/release-notes/0.77.1/","title":"0.77.1 release notes","text":"Release date: 2021-08-28
"},{"location":"releases/release-notes/0.77.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.77.1/#bugfixes","title":"Bugfixes","text":"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).
- Synchronize Italian translation files (Kappa971).
- Synchronize German translation files (Burrito78).
- Generate macOS Universal Binary supporting x86_64 and arm64 (Kirk Klobe)
"},{"location":"releases/release-notes/0.77.1/#translations-pack-included","title":"Translations pack included","text":"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\n
Or via primary or local config file:
[dosbox]\nlanguage = de\n# de, es, fr, it, pl, ru\n
Tip
Use dosbox -editconf to open your config file.
For future reference, the above is also discussed in the README.
"},{"location":"releases/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":"releases/release-notes/0.78.0/","title":"0.78.0 release notes","text":"Release date: 2021-12-25
"},{"location":"releases/release-notes/0.78.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.78.0/#significant-changes","title":"Significant changes","text":" -
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)
"},{"location":"releases/release-notes/0.78.0/#bugfixes","title":"Bugfixes","text":" -
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)
"},{"location":"releases/release-notes/0.78.0/#translation-updates","title":"Translation updates","text":" - Italian (Kappa971)
- German (Burrito78)
- Russian (GranMinigun)
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.
"},{"location":"releases/release-notes/0.78.0/#repository-authors","title":"Repository authors","text":"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 7 During the 0.78 timeframe, DOSBox SVN commits r4466 through r4471 were merged to the project and authorship is reflected above.
"},{"location":"releases/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":"releases/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":"releases/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":"releases/release-notes/0.78.1/","title":"0.78.1 release notes","text":"Release date: 2022-01-07
"},{"location":"releases/release-notes/0.78.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.78.1/#fixes-and-regressions","title":"Fixes and regressions","text":"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)
"},{"location":"releases/release-notes/0.78.1/#functionality-refinements","title":"Functionality refinements","text":" -
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)
"},{"location":"releases/release-notes/0.78.1/#documentation-related-improvements","title":"Documentation-related improvements","text":" -
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)
"},{"location":"releases/release-notes/0.78.1/#development-and-packaging-fixes","title":"Development and packaging fixes","text":" -
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)
"},{"location":"releases/release-notes/0.78.1/#known-issues","title":"Known issues","text":" -
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
- to the Windows Console API.
-
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\n
Tip
Run dosbox -editconf to open your config file.
Thanks to Genju for reporting this regression and isolating the solution.
"},{"location":"releases/release-notes/0.78.1/#thank-you","title":"Thank you","text":"We are extremely grateful for all contributions, including the invaluable improvements merged in from the DOSBox project.
"},{"location":"releases/release-notes/0.79.0/","title":"0.79.0 release notes","text":"Release date: 2022-09-19
"},{"location":"releases/release-notes/0.79.0/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.79.0/#what-you-can-expect","title":"What you can expect","text":" -
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":"releases/release-notes/0.79.0/#audio-improvements","title":"Audio improvements","text":""},{"location":"releases/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\n
"},{"location":"releases/release-notes/0.79.0/#sound-card-output-filter-emulation","title":"Sound card output filter emulation","text":"Most 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":"releases/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\n
Some 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.
"},{"location":"releases/release-notes/0.79.0/#small-speaker-systems","title":"Small-speaker systems","text":"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_filter
"},{"location":"releases/release-notes/0.79.0/#custom-filters","title":"Custom filters","text":"Advanced 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]\n
where 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\n
To 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\n
In 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_filter
"},{"location":"releases/release-notes/0.79.0/#crossfeed","title":"Crossfeed","text":"Listening 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.
"},{"location":"releases/release-notes/0.79.0/#reverb-and-chorus","title":"Reverb and chorus","text":""},{"location":"releases/release-notes/0.79.0/#reverb","title":"Reverb","text":"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.
"},{"location":"releases/release-notes/0.79.0/#chorus","title":"Chorus","text":"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 the video 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 the audio 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":"releases/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.
"},{"location":"releases/release-notes/0.79.0/#general-mixer-improvements","title":"General mixer improvements","text":" -
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.
"},{"location":"releases/release-notes/0.79.0/#one-opl-mode-to-rule-them-all","title":"\u201cOne OPL mode to rule them all\u201d \ud83d\udc8d","text":"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":"releases/release-notes/0.79.0/#fluidsynth-configuration-changes","title":"FluidSynth configuration changes","text":""},{"location":"releases/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":"releases/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.
"},{"location":"releases/release-notes/0.79.0/#ripas-pc-speaker-patch","title":"ripa\u2019s PC speaker patch","text":"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\n[speaker]\npcspeaker = discrete\n
Your browser does not support the video 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":"releases/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.
"},{"location":"releases/release-notes/0.79.0/#audio-mute-and-pause","title":"Audio mute and pause","text":"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\n
Or you can pause emulation entirely when in the background with:
[sdl]\npause_when_inactive = true\n
"},{"location":"releases/release-notes/0.79.0/#graphical-improvements","title":"Graphical improvements","text":""},{"location":"releases/release-notes/0.79.0/#shader-reload-shortcut","title":"Shader reload shortcut","text":"As 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":"releases/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
"},{"location":"releases/release-notes/0.79.0/#scaled-image-quality-improvements","title":"Scaled image quality improvements","text":"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":"releases/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":"releases/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).
"},{"location":"releases/release-notes/0.79.0/#frame-presentation-modes","title":"Frame presentation modes","text":"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\n[dosbox]\ndos_rate = default | host | custom-rate\n
"},{"location":"releases/release-notes/0.79.0/#dos-shell-improvements","title":"DOS shell improvements","text":""},{"location":"releases/release-notes/0.79.0/#piping-from-the-dos-prompt-or-batch-files","title":"Piping from the DOS prompt or batch files","text":"DOSBox 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).
"},{"location":"releases/release-notes/0.79.0/#file-attribute-support-and-attrib-command","title":"File attribute support and ATTRIB command","text":"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.
"},{"location":"releases/release-notes/0.79.0/#default-choices-for-the-choice-command","title":"Default choices for the CHOICE command","text":"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.
"},{"location":"releases/release-notes/0.79.0/#mount-improvements","title":"Mount improvements","text":""},{"location":"releases/release-notes/0.79.0/#physical-cd-rom-mount-support","title":"Physical CD-ROM mount support","text":"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.
"},{"location":"releases/release-notes/0.79.0/#read-only-disk-image-mount-support","title":"Read-only disk image mount support","text":"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.
"},{"location":"releases/release-notes/0.79.0/#z-drive-customisation-and-directory-support","title":"Z-drive customisation and directory support","text":"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.
"},{"location":"releases/release-notes/0.79.0/#imgmount-wildcard-support","title":"IMGMOUNT wildcard support","text":"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.
"},{"location":"releases/release-notes/0.79.0/#automount-of-resource-drives","title":"Automount of resource drives","text":"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\n
A 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.
"},{"location":"releases/release-notes/0.79.0/#localisation-improvements","title":"Localisation improvements","text":""},{"location":"releases/release-notes/0.79.0/#code-pages-and-keyboard-layouts","title":"Code pages and keyboard layouts","text":"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:
- List of available code pages
- List of available keyboard layouts
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
"},{"location":"releases/release-notes/0.79.0/#country-support-for-different-date-time-and-decimal-formats","title":"Country support for different date, time, and decimal formats","text":"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":"releases/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.
"},{"location":"releases/release-notes/0.79.0/#input-improvements","title":"Input improvements","text":""},{"location":"releases/release-notes/0.79.0/#mouse-wheel-emulation","title":"Mouse-wheel emulation","text":"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.
"},{"location":"releases/release-notes/0.79.0/#serial-mice-emulation","title":"Serial mice emulation","text":"Numerous serial (COM port) mice are now emulated:
- original Microsoft mouse with 2 buttons
- Logitech mouse, with 3 buttons
- wheel mouse with 3 buttons
- Mouse Systems mouse (old mouse type, not compatible with the ones listed above), with 3 buttons
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":"releases/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":"releases/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\n
Once 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\n
Note 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 the video element. The new joystick calibration feature in action
"},{"location":"releases/release-notes/0.79.0/#general-improvements","title":"General improvements","text":""},{"location":"releases/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.
"},{"location":"releases/release-notes/0.79.0/#windows-installer-for-windows-users","title":"Windows installer for Windows users","text":"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":"releases/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\n
Although 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":"releases/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:
mcb_fault_strategy Behaviour How it affects the buggy game 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":"releases/release-notes/0.79.0/#developer-related-improvements","title":"Developer-related improvements","text":""},{"location":"releases/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":"releases/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":"releases/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
"},{"location":"releases/release-notes/0.79.0/#continuous-integration-msys2-workflow-improvements","title":"Continuous integration MSYS2 workflow improvements","text":"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":"releases/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":"releases/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":"releases/release-notes/0.79.0/#translation-status","title":"Translation status","text":" - German: up-to-date
- Italian: up-to-date
- Polish: up-to-date
- Russian: config sections up-to-date
- French: not updated
- Spanish: not updated
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 style Escribiendo ^[[34;1mdir^[[0m all\ufffd mostrar\ufffd su contenido. Digita [color=blue]dir[reset] per visualizzarne il contenuto."},{"location":"releases/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.
"},{"location":"releases/release-notes/0.79.0/#special-thanks","title":"Special thanks","text":" -
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
"},{"location":"releases/release-notes/0.79.0/#contributors","title":"Contributors","text":""},{"location":"releases/release-notes/0.79.0/#maintainers","title":"Maintainers","text":" - kcgen
- John Novak
- FeralChild64
- shermp
- Wengier
"},{"location":"releases/release-notes/0.79.0/#authors","title":"Authors","text":" - kcgen
- John Novak
- FeralChild64
- Wengier
- shermp
- Kirk Klobe
- GranMinigun
- Patryk Obara
- ripsaw8080 (DOSBox maintainer)
- NicknineTheEagle
- David Reid (dr_lib author, 3rd party dependency)
- Leandro Nini (libresidfp author, 3rd party dependency)
- Jonathan Campbell (DOSBox-X maintainer)
- Dean Beeler
- ripa (DOSBox patch author)
- Keenan Weaver
- Dennis L\u00fchring
- IPeluchito
- Otto Liljalaakso
- Peter Ferrie
- arrowgent
- gulrak
- hunterk
"},{"location":"releases/release-notes/0.79.0/#translators","title":"Translators","text":" - Burrito78 (German)
- FeralChild64 (Polish)
- GranMinigun (Russian)
- Kappa971 (Italian)
"},{"location":"releases/release-notes/0.79.0/#sponsors","title":"Sponsors","text":" - Antti Peltola: 3,000 USD during the 0.79 development cycle
- Wengier
"},{"location":"releases/release-notes/0.79.0/#backers","title":"Backers","text":" 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":"releases/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":"releases/release-notes/0.79.1/","title":"0.79.1 release notes","text":"Release date: 2022-09-30
"},{"location":"releases/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":"releases/release-notes/0.79.1/#how-to-upgrade","title":"How to upgrade","text":"Download and launch the latest version:
- Linux (or Steam on Linux)
- Windows
- macOS
At theZ:\\> prompt, run config -wc to write the new configuration file. Any existing settings will be retained, however, extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.79.1/#fixes-and-regressions","title":"Fixes and regressions","text":" -
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)
Your browser does not support the video element. 303 by Acme \u2014 30fps encoding, 120k cycles, and SB16 using the modern filter
"},{"location":"releases/release-notes/0.79.1/#functionality-refinements","title":"Functionality refinements","text":" -
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)
"},{"location":"releases/release-notes/0.79.1/#translation-improvements","title":"Translation improvements","text":" - Added Dutch translation (Robert de Rooy)
- Fixed outdated content in German translation (Burrito78)
-
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)
"},{"location":"releases/release-notes/0.79.1/#wiki-updates-since-0790","title":"Wiki updates since 0.79.0","text":" -
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)
"},{"location":"releases/release-notes/0.79.1/#packaging-fixes","title":"Packaging fixes","text":" -
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\n
"},{"location":"releases/release-notes/0.79.1/#thank-you","title":"Thank you","text":"Thanks 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":"releases/release-notes/0.80.0/","title":"0.80.0 release notes","text":"Release date: 2022-12-21
"},{"location":"releases/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":"releases/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":"releases/release-notes/0.80.0/#downloads","title":"Downloads","text":""},{"location":"releases/release-notes/0.80.0/#upgrade-your-configuration-file","title":"Upgrade your configuration file","text":" - Launch the new release.
- At the
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.
"},{"location":"releases/release-notes/0.80.0/#new-features","title":"New features","text":""},{"location":"releases/release-notes/0.80.0/#reelmagic-support","title":"ReelMagic support","text":"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.
Your browser does not support the 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":"releases/release-notes/0.80.0/#mouse-improvements","title":"Mouse improvements","text":""},{"location":"releases/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
"},{"location":"releases/release-notes/0.80.0/#dual-mouse-gaming","title":"Dual mouse gaming","text":"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 the video element. The Settlers II (1996) \u2014 showcasing dual-mouse gaming in action
"},{"location":"releases/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":"releases/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":"releases/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":"releases/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
"},{"location":"releases/release-notes/0.80.0/#how-to-use-it","title":"How to use it","text":"Follow the steps indicated in the DMG package, as shown:
Simply copy the included Start DOSBox Staging.command to a folder that contains a local dosbox.conf and then open it (Start DOSBox Staging.command) in the 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":"releases/release-notes/0.80.0/#general-improvements","title":"General improvements","text":""},{"location":"releases/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.
Your browser does not support the video element. more.com \u2014 Better and Improved\u2122
"},{"location":"releases/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 the video element. Reconfiguring audio on-the-fly \u2014 changing sound cards in a PC has never been easier!
"},{"location":"releases/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":"releases/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
Full PR list of additions and improvements - Add
--working-dir command line option (#2122) - Add a subset of OpenGL shaders from Tyrells\u2019 repo (#2137)
- Add direct support for Windows 3.1 seamless mouse driver by javispedro (#1996)
- Add libraries to support TrueType font rendering (#2075)
- Add more cleanup on audio device tear-down (#2099)
- Add mouse related hints to title bar (#2062)
- Add release drafter support files (#2036)
- Add screenshots for rendered output #2073) (#2078)
- Allow to cancel interactive mouse mapping with a keyboard (#2067)
- Bump actions/cache from 2 to 3.0.11 (#2025)
- Bump actions/download-artifact from 2 to 3 (#2028)
- Bump actions/upload-artifact from 2 to 3 (#2026)
- Bump fountainhead/action-wait-for-check from 1.0.0 to 1.1.0 (#2027)
- Bump microsoft/setup-msbuild from 1.1 to 1.2 (#2123)
- Bump microsoft/setup-msbuild from 1.2 to 1.3 (#2129)
- Check file-descriptor dependency for Enet, slirp, and ManyMouse (#2108)
- Cleanup a handful of build issues for clang 10.x and 11.x (#2096)
- Cleanup issues in ReelMagic flagged by Coverity (#2084)
- Cleanup overcomplicated data conversions in Unicode support (#2104)
- Cleanup string IDs of DOS programs (#2064)
- Compiler warning fix in ManyMouse library (#2076)
- Contribute a script to convert from YouTube chapters to CD-DA (#2037)
- Customise the looks of the macOS DMG distribution disk image (#2127)
- Debloat the binary: use more heap storage and retire the software scalar (#2101)
- Drop architecture spec from setup-msbuild GitHub action (#2124)
- Enable DPI scaling on Windows (#2105)
- Fix a couple CWE issues in ManyMouse (#2040)
- Fix sentence starting with lower case in MOUNT command help (#2068)
- Generate linker map file by default (#2103)
- Implement MORE.COM command (#2020)
- Import Jon Dennis\u2019s ReelMagic emulation package #1112) (#2077)
- Improve detection of atomics, testing of speexDSP, and cleanup README (#1992)
- Improve interactive mouse mapping (#2065)
- Improve management of audio devices (#2095)
- Look for libXInput dependency (#2085)
- Minor mouse enhancements (#2060)
- Mouse mapper and configuration mechanism (#2000)
- Refactor ReelMagic player with per-stream handle registration (#2086)
- Refactor the ReelMagic audio FIFO class (#2090)
- Simplifies file search in virtual drive (#2130)
- Split contributed CD-DA scripts into fetch vs. cue functions (#2045)
- Sync reSIDfp with upstream (#2092)
- Update CI against latest deprecations and OS versions (#2031)
- Update Tracy to v0.9 (#2069)
- Update the build system wraps and automate CI action maintenance (#2024)
- Update wraps and PVS Studio (#2097)
- Use MORE engine for help output (#2079)
- Use a
sdd::unique_ptr to manage the video memory (#2116) - Use shared pointers to manage the virtual files (#2117)
"},{"location":"releases/release-notes/0.80.0/#bug-and-regression-fixes","title":"Bug and regression fixes","text":" -
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.
Full PR list of bug and regression fixes - Adapt
update-sources.sh script to UTF-8 locale (#2011) - Add modem call warm-up period (#2125)
- Always use VFR presentation mode for text modes (#2139)
- Avoid shifting negative DAC data in Sound Blaster (CWE-758) (#2115)
- Capture the OpenGL screenshot using RGBA pixel format (#2143)
- Change
config -wc to write UTF-8 file (#1991) - Drop architecture spec from setup-msbuild GitHub action (#2124)
- Fix FluidSynth reverb and chorus settings not applying (#2133)
- Fix a memory leak in the keyboard layout class (#1985)
- Fix assertion in mouse code for surface screen output (#2110)
- Fix bitwise shift of negative in DOS date pack call (#2034)
- Fix character D6 mapping in code page 3021 (Bulgarian MIK encoding) (#2094)
- Fix several English strings too long to fit on screen (#1998)
- Fix tab handling in MORE command (#2102)
- Improve
mixer.com CLI handling of volume and effect arguments (#2021) - Initialize the window\u2019s canvas size during its setup phase (#2038)
- Limit
bit_views to 8-bit registers to avoid byte-order assumption (#1999) - MORE text output engine fixes (#2083)
- Parse language options before writing the conf file (#2001)
- Remove errorneous screen parameters check in mouse code (#2119)
- Restore 0.79.1 mouse acceleration model in DOS driver (#2087)
- Restore WheelHasMoved bit in DOS mouse driver to correct value (#2091)
- Use non-throwing form of
std::filesystem calls (#1995)
"},{"location":"releases/release-notes/0.80.0/#translation-improvements","title":"Translation improvements","text":""},{"location":"releases/release-notes/0.80.0/#translations","title":"Translations","text":" - German: up-to-date
- Italian: up-to-date
- Polish: up-to-date
- Russian: up-to-date
- French: not updated
- Spanish: not updated
"},{"location":"releases/release-notes/0.80.0/#related-improvements","title":"Related improvements","text":" -
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.
Full PR list of documentation and translation changes - Adapt
update-sources.sh script to UTF-8 locale (#2011) - Add Dutch tranlation of MOUSECTL (#2042)
- Add Dutch translation of MORE (#2048)
- Add handling for ABNT2 slash/question mark key (by rsribeiro) (#2082)
- Add release drafter support files (#2036)
- Clarify
tandy and ibm5153 cga_colors config descriptions (#2074) - Cleanup string IDs of DOS programs (#2064)
- Convert esc codes to ansi in src (#2008)
- Delete obsolete translated msgs (#2058)
- Fix character D6 mapping in code page 3021 (Bulgarian MIK encoding) (#2094)
- Fix code page 30020 to UTF-8 mapping (#1988)
- Fix code page 30020 to UTF-8 mapping (#1988)
- Fix mistakes in switching to ansi text codes (#2017)
- Fix some errors in the Italian (it-it) translation (#2029)
- Fixed some ANSI escape codes in the Italian translation (#2013)
- Fixup nl.txt to match nl.lng (#2010)
- Improve build instructions (#2126)
- Improve detection of atomics, testing of speexDSP, and cleanup README (#1992)
- Minor Dutch translation updates (#2007)
- Parse language options before writing the conf file (#2001)
- Support for UTF-8 locale (2nd generation patch) (#1884)
- Support for UTF-8 locale (2nd generation patch) (#1884)
- Switch messages in
MSG_Add from code page 437 to UTF-8 (#1984) - Switch messages in
MSG_Add from code page 437 to UTF-8 (#1984) - Translate new message (#2032)
- Update Dutch (nl) translation (#2100)
- Update Dutch (nl) translation (#2141)
- Update Italian (it-it) translation (#2005)
- Update Italian (it-it) translation (#2041)
- Update Italian (it-it) translation (#2055)
- Update Italian (it-it) translation (#2072)
- Update Italian (it-it) translation (#2088)
- Update Polish (pl) translation (#1982)
- Update Polish (pl) translation (#2070)
- Update Polish (pl) translation (#2098)
- Update Polish (pl) translation (#2118)
- Update Polish (pl) translation, change ANSI escape codes to tags (#2012)
- Update Russian (ru-RU) translation (#2120)
- Various Dutch translation updates (#2016)
"},{"location":"releases/release-notes/0.80.0/#documentation-updates","title":"Documentation updates","text":"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.
"},{"location":"releases/release-notes/0.80.0/#contributors","title":"Contributors","text":"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":"releases/release-notes/0.80.0/#080-commit-authors","title":"0.80 commit authors","text":" - Burrito78
- dreamer
- drfiemost
- FeralChild64
- GranMinigun
- javispedro
- Jkapp76
- johnnovak
- jrdennisoss
- Kappa971
- kcgen
- kklobe
- LowLevelMahn
- memononen
- nemo93
- NicknineTheEagle
- rderooy
- rsribeiro
- tyrells
"},{"location":"releases/release-notes/0.80.0/#080-sponsors","title":"0.80 sponsors","text":"Sponsors who donated more than 100 USD per month to the project:
- Antti Peltola (1000 USD during the period)
- Wengier Wu (380 USD during the period)
"},{"location":"releases/release-notes/0.80.0/#080-backers","title":"0.80 backers","text":"Backers who donated more than 5 USD per month to the project:
- Burrito78
- Hannu Hartikainen
- Hugo Locurcio
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":"releases/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":"releases/release-notes/0.80.1/","title":"0.80.1 release notes","text":"Release date: 2023-01-06
"},{"location":"releases/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":"releases/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":"releases/release-notes/0.80.1/#downloads","title":"Downloads","text":" - Linux (or Steam on Linux)
- Windows
- macOS
"},{"location":"releases/release-notes/0.80.1/#upgrade-your-configuration-file","title":"Upgrade your configuration file","text":" - Launch the new release.
- At the
Z:\\> prompt, run config -wc to write the new configuration file.
Note
- Existing settings will be retained, but extraneous comments will be dropped.
"},{"location":"releases/release-notes/0.80.1/#bug-and-regression-fixes","title":"Bug and regression fixes","text":" -
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.
Full PR list of bug and regression fixes - Add Linux ARM CI jobs using containerized cross-compiler (#2193)
- Add missing Windows 11 features to MORE command (#2142)
- Bump Coverity to v2022.06 (#2162)
- Bump actions/cache from 3.2.0 to 3.2.1 (#2152)
- Bump actions/cache from 3.2.1 to 3.2.2 (#2165)
- Center mouse cursor before releasing it (#2173)
- Change mouse capture default to \u2018onclick\u2019 (#2172)
- Check CLI arguments for directories using non-invasive test (#2148)
- Cleanup some minor Coverity issues (#2179)
- Fix CGA mono and Hercules intro banners (#2190)
- Fix imprecise help string in MORE command (#2161)
- Fix logging of some pre-EGA modes (#2187)
- Fix remaining two CWEs involving unchecked return values (#2150)
- Fix slirp/ne2000 warnings (#2182)
- Improve logging of the current display mode (#2168)
- Improve seamless mouse configuration entry description, mention the touchscreen (#2163)
- Make the xinput2 library optional for ManyMouse (#2155)
- Use extended ASCII check in MORE command (#2195)
- Use presence of desktop environment in mouse capture states (#2181)
"},{"location":"releases/release-notes/0.80.1/#translation-improvements","title":"Translation improvements","text":"This maintenance release includes updates to the Dutch, Italian, and Polish translations.
Full PR list of translation improvements - Update Dutch (nl) translation of MORE (#2164)
- Update Italian (it-it) translation (#2166)
- Update Polish (pl) translation (#2159)
- Update Polish (pl) translation (#2186)
- Update Polish (pl) translation, for 0.80.x only (#2194)
"},{"location":"releases/release-notes/0.80.1/#contributors","title":"Contributors","text":"The following commit authors, sponsors, supporters, and backers invested their time or funds into this maintenance release. Thank you!
"},{"location":"releases/release-notes/0.80.1/#commit-authors","title":"Commit authors","text":"In alphabetic order:
- FeralChild64
- johnnovak
- Kappa971
- kcgen
- NicknineTheEagle
- rderooy
- shermp
- ThomasEricB
"},{"location":"releases/release-notes/0.80.1/#sponsors","title":"Sponsors","text":"Sponsors who donated 100+ USD per month to the project:
"},{"location":"releases/release-notes/0.80.1/#backers","title":"Backers","text":"Backers who donated 5+ USD per month to the project:
- Burrito78
- Hannu Hartikainen
- Hugo Locurcio
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":"releases/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":"releases/release-notes/0.81.0/","title":"0.81.0 release notes","text":"Release date: 2024-02-14
"},{"location":"releases/release-notes/0.81.0/#summary","title":"Summary","text":"Hey DOS enthusiasts! We are proud to present DOSBox Staging 0.81.0 to you, a rather substantial release containing a large number of exciting new features and improvements!
For the first time in history, DOSBox comes with built-in authentic CRT monitor emulation that just works out-of-the-box without any manual configuration required. The VGA code has been overhauled, shortcuts and simplifications have been removed, and now we\u2019re defaulting to accurate per-scanline emulation and double scanning in all VGA, SVGA, and VESA modes. Integer scaling options have been added, it\u2019s now possible to stretch the image to fullscreen, force any arbitrary aspect ratio, or even emulate the horizontal and vertical stretch controls of CRT monitors in real-time. Screenshots have been made aspect ratio correct by default, and image capturing has become multi-threaded, so it no longer causes audio hiccups and micro-pauses. Video capturing has been made about three times more performant. Oh, almost forgot: we\u2019ve also added 3dfx Voodoo 1 support for the fans of those late 90s 3D DOS games!
Well, that\u2019s just the video side of things. We\u2019ve added support for the ultra-rare IBM Music Feature Card, dealing with Roland MT-32 ROMs has become much easier, plus we\u2019ve made numerous MIDI-related improvements as well. Not to mention all the mouse and joystick enhancements and fixes, the addition of a few missing DOS commands, improved filesystem integration, fixing some long-standing annoying shortcomings of the FPU emulation in non-x86 builds, taking localisation support to the next level, and the list just goes on and on\u2026
Read on to learn more!
"},{"location":"releases/release-notes/0.81.0/#how-to-upgrade","title":"How to upgrade","text":"Start by downloading the latest version, then make sure to upgrade your primary configuration as described below.
"},{"location":"releases/release-notes/0.81.0/#downloads","title":"Downloads","text":""},{"location":"releases/release-notes/0.81.0/#upgrading-your-primary-configuration","title":"Upgrading your primary configuration","text":"Since config settings might be renamed, altered, or deprecated between releases, it\u2019s best to let DOSBox Staging write the new default primary config on the first launch, then reapply your old settings manually.
Start by backing up your existing primary config. This is where to find it on each platform:
Windows C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox-staging.conf macOS ~/Library/Preferences/DOSBox/dosbox-staging.conf Linux ~/.config/dosbox/dosbox-staging.conf You can also execute DOSBox Staging with the --printconf option to have the location of the primary config printed to your console.
After backing up the existing primary config, simply start the new version\u2014a new dosbox-staging.conf will be written containing the new defaults and updated setting descriptions.
Portable mode notes
In portable mode, dosbox-staging.conf resides in the same folder as your DOSBox Staging executable. The migration steps for portable mode users are as follows:
- Unpack the new version into a new folder (this is important).
- Create a new empty
dosbox-staging.conf file in the new folder to enable portable mode. - Launch the new version.
DOSBox Staging will write the new defaults to the empty dosbox-staging.conf file. After this, you carry over your settings from the old primary config manually.
"},{"location":"releases/release-notes/0.81.0/#after-upgrading","title":"After upgrading","text":"Look out for deprecation warnings in the logs (in yellow/orange colour) and update your configs accordingly.
"},{"location":"releases/release-notes/0.81.0/#new-getting-started-guide","title":"New Getting Started guide","text":"Due to popular demand, we\u2019ve added a new Getting Started guide to the front page. The guide will teach you how to set up your own DOSBox Staging environment from scratch through easy-to-follow instructions with lots of pretty pictures. It adopts a learn-by-doing approach to ensure you\u2019ll have fun while setting up famous classic DOS games.
Although it\u2019s primarily intended for beginners, we guarantee even our most experienced long-time users will learn a few tricks from it!
"},{"location":"releases/release-notes/0.81.0/#graphics","title":"Graphics","text":""},{"location":"releases/release-notes/0.81.0/#authentic-adaptive-crt-emulation","title":"Authentic adaptive CRT emulation","text":"We are happy to announce that we\u2019ve removed all CRT shaders previously bundled with our releases.
Every single one of them.
What the @^$*%#!!!?? Have these guys gone mad??!
The reason for removing them is that they got replaced with something far better: a set of no less than 24 CRT shaders tweaked to perfection to emulate the glorious CRT monitors of the past, including authentic recreations of Hercules, CGA, monochrome CGA, composite CGA, EGA, and VGA monitors.
24 new CRT shaders sound a lot\u2014how will someone not intimately familiar with CRT monitor technology and PC history know which is the best for a particular game? Well, the good news is you don\u2019t need to know\u2014DOSBox Staging will automatically pick the most appropriate shader based on the current DOS video mode and viewport resolution. High-DPI and displays from 720p to 4K resolutions are fully supported, and absolutely no manual configuration is required!
The following magic glshader options have been introduced:
-
crt-auto \u2014 This is the new default\u2014an adaptive CRT shader that prioritises developer intent and how people experienced the game at the time of release. This means VGA games will be double-scanned, like on a real VGA monitor, EGA games will appear single-scanned with \u201cfat scanlines\u201d, and so on, regardless of the machine setting.
-
crt-auto-machine \u2014 This one emulates a fixed CRT monitor based on your machine setting. So CGA and EGA modes on a VGA machine will always appear double-scanned with big chunky pixels, just like on a real VGA adapter and monitor.
-
crt-auto-arcade \u2014 This fantasy option does not exist in real life, but it can be a lot of fun! It emulates a 15 kHz arcade or home computer monitor with thick scanlines in low-resolution modes. Perfect for playing DOS VGA ports of Amiga and Atari ST games to experience them with MT-32 or SC-55 sound from a strange parallel universe! \ud83d\ude0e
Adaptive CRT shaders work in tandem with the new integer scaling feature to achieve the most optimal results. The default auto setting for integer_scaling auto-enables vertical integer scaling for the adaptive CRT shaders; this avoids unwanted interference patterns that can result from non-integer vertical scaling ratios.
Here are the shaders in action at 4K resolution (make sure to click on the zoomed-in images if the cursor turns into a magnifying glass to view them at 100% magnification):
Gods \u2014 320\u00d7200 VGA
Ultima Underworld: The Stygian Abyss \u2014320\u00d7200 VGA
Celtic Tales: Balor of the Evil Eye \u2014 640\u00d7480 VGA
Dark Seed \u2014 640\u00d7350 EGA
The Secret of Monkey Island \u2014 320\u00d7200 EGA
Space Quest III: The Pirates of Pestulon \u2014 320\u00d7200 EGA
Wizardry: Proving Grounds of the Mad Overlord \u2014 320\u00d7200 CGA
Smoker by Fairfax \u2014320\u00d7200 15kHz \u201carcade\u201d shader
Zak McKracken and the Alien Mindbenders \u2014320\u00d7200 CGA composite
Starblade \u2014 720\u00d7348 Hercules
If you don\u2019t like CRT shaders, no problem\u2014simply set glshader to sharp in your config to regain your sharp little rectangles back. Naturally, you can continue to use regular GLSL shaders like before. The deprecated CRT shaders are still available as a separate download, should you ever need them.
The adaptive shaders are largely based on one of Hyllian\u2019s excellent CRT shaders, so big thanks to him for laying a solid foundation for this feature.
Why were the old CRT shaders removed?
One problem with the previously bundled CRT shaders was that they lacked proper documentation, so it wasn\u2019t clear which shader was meant for what monitor resolution (some were tuned for 1080p, some for 4K, etc.) Moreover, most were designed to emulate arcade monitors or TV sets from the 80s and early 90s; these displays had very different characteristics than the much higher quality PC monitors. Because of all this, many people were rather unimpressed by them and gave up on CRT shaders altogether as a result.
"},{"location":"releases/release-notes/0.81.0/#accurate-vga-emulation","title":"Accurate VGA emulation","text":"Previously, DOSBox rendered the emulated VGA output without double scanning, and only in quarter-frame chunks. These optimisation steps were necessary 20 years ago, but now we\u2019re doing proper double scanning and accurate per-scanline rendering in all VGA, SVGA, and VESA video modes. It turns out this only causes a ~7% performance drop on modern hardware in benchmarks, which is not much for such a significant improvement.
Double scanning and per-scanline rendering were available via the special vgaonly machine type before, but that was incompatible with VESA modes and it truncated the 18-bit VGA DAC colour output to 16-bits only, causing banding in certain scenes. We no longer do that either\u2014VGA output is now always rendered at full 18-bit precision.
We use 9\u00d716 fonts on all emulated VGA adapters now which is how most people remember VGA text modes. You can still force 8\u00d716 fonts on VGA by enabling the new vga_8dot_font setting.
These improvements absorb the benefits of vgaonly into the base VGA emulation, making the vgaonly machine type unnecessary, so it has been deprecated (it\u2019s still recognised as an alias for svga_paradise for backward compatibility).
Additionally, all CGA, PCjr, and Tandy text modes are now properly single-scanned when using their respective machine types. A few CGA, PCjr, and Tandy graphics modes appeared with the incorrect aspect ratio before; these have all been fixed up.
The logging of video modes has become a lot more accurate; now we\u2019re consistently logging the video standard the mode first appeared in (e.g., CGA modes are always logged as CGA, regardless of the emulated display adapter in use), and the logged pixel aspect ratios are now always correct.
"},{"location":"releases/release-notes/0.81.0/#3dfx-voodoo-1-emulation","title":"3dfx Voodoo 1 emulation","text":"Aaron Giles\u2019 3dfx Voodoo emulation originally written for the MAME project has finally found its way into Staging. During its journey, it has picked up a few enhancements, namely a few changes by kekko for the DOSBox integration, plus some multi-threading improvements by Bernhard Schelling (also known as psyraven).
We\u2019ve added support for emulating a Voodoo 1 board with either a 2 MB Frame Buffer Interface (FBI) and one 2 MB Texture Mapping Unit (TMU), or a 4 MB FBI + dual 2x4 MB TMU configuration.
The default refresh rate for the Voodoo is 60 Hz, but it\u2019s possible to force any custom refresh rate via dos_rate.
Please refer to the new [voodoo] config section to learn more.
Low vs high-level emulation
Note this is purely software-based low-level emulation; we\u2019re emulating the 3dfx Voodoo 1 hardware accurately in software, which requires a beefy host CPU. We don\u2019t support high-level emulation where the Glide API calls are transformed and passed through to modern 3D APIs for the actual rendering (e.g., OpenGL, Vulkan, Direct3D, etc.)
"},{"location":"releases/release-notes/0.81.0/#new-integer-scaling-modes","title":"New integer scaling modes","text":"A new integer_scaling setting has been introduced to constrain the horizontal or vertical scaling factor to integer values when upscaling the image to fit it into the viewport. For example, you can enable vertical integer scaling now with the following config:
[render]\ninteger_scaling = vertical\n
The correct aspect ratio will always be maintained, so in this case, the horizontal scaling factor might become fractional. With the sharp shader this is not a problem as the \u201cinterpolation band\u201d can only be up to 1 pixel wide at the two sides of the pixels\u2014still plenty sharp, especially on 1440p or 4K. Then with the CRT shaders, non-integer horizontal scaling matters even less; it\u2019s practically a non-issue.
integer_scaling is set to auto by default which only enables vertical integer scaling for the adaptive CRT emulation, otherwise, it\u2019s disabled.
This replaces the so-called \u201cpixel-perfect mode\u201d (openglpp and texturepp output modes) which prioritised 100% sharp pixels at the expense of aspect ratio correctness. That feature had been the source of endless confusion even among experienced users as most of the time it could only approximate the correct aspect ratio, and even that varied semi-randomly based on the current viewport size and monitor resolution. Our reasons for removing it are documented in detail here.
"},{"location":"releases/release-notes/0.81.0/#aspect-ratio-correct-image-captures","title":"Aspect ratio correct image captures","text":"Previously, even if you had aspect ratio correction enabled, the captured screenshots always contained the raw, non-corrected image. This has been flipped around: the new default is capturing images in the same aspect ratio that you see on your screen.
Taking raw and rendered (post-shader) screenshots continues to be an option, of course. The following three image capture formats have been introduced:
-
upscaled \u2014 The image is captured in the same aspect ratio you see on the screen. Upscaled captures always use sharp pixels, regardless of the shader in use.
-
rendered \u2014 Capture the post-rendered, post-shader image\u2014an exact pixel-by-pixel replica of what you see on the screen.
-
raw \u2014 Capture the raw image; this always results in square pixels. So for 320\u00d7200 VGA or EGA content, you\u2019ll always get a 320\u00d7200 PNG file, no matter what.
You can configure the capture formats of the default screenshot action with the following setting:
[capture]\ndefault_image_capture_formats = upscaled raw\n
With this setting, two PNG files will be written in raw and upscaled formats whenever you press the Ctrl+F5 image capture hotkey (Cmd+F5 on macOS).
Keybindings for taking single screenshots in specific formats are also available.
Interpolation in upscaled mode
The image is integer or bilinear-sharp upscaled to around 1200 pixels of vertical resolution in the new upscaled capture mode. For example:
- 320x200 content is upscaled to 1600x1200 (5:6 integer scaling)
- 640x480 to 1920x1440 (3:3 integer scaling)
- 640x350 to 1400x1050 (3x vertical and 2.1875x horizontal scaling)
The resulting PNG files are only about 30% bigger than raw screenshots on average. This is a rather small price to pay for aspect ratio correctness.
Aspect ratio correctness, 2023 edition
Fact: most 320\u00d7200 and similar low-resolution DOS games absolutely need aspect ratio correction enabled to appear correctly. While some games benefit from forcing square pixels, these only account for about 1-2% of the total DOS gaming catalogue. That\u2019s the reason why DOSBox Staging performs aspect ratio correction out-of-the-box.
The sad reality of the situation today is that the vast majority of 320\u00d7200 DOS games are displayed in the wrong aspect ratio with square pixels on various websites and video-sharing services. Emulators that don\u2019t default to aspect ratio correct output and screen captures have undoubtedly contributed to this widespread problem. Aspect ratio correct screen captures by default is our attempt to play our part in remedying the situation, and hopefully reversing it with time.
Raw capture breaking changes
Previously, raw image captures width or height doubled certain DOS video modes. There wasn\u2019t much rhyme or reason to it. Now raw captures always contain the actual emulated DOS framebuffer-level image (e.g., 320\u00d7200 modes get captured as 320\u00d7200 PNG files, regardless of any other settings).
The only exceptions are the composite CGA, PCjr, and Tandy modes. These modes are a bit special as internally they\u2019re rendered width-doubled to have enough horizontal resolution for representing composite artifacts. Therefore, we write raw image captures of composite modes width-doubled to retain all rendered information (e.g., the 640\u00d7200 composite CGA mode will result in a 1280\u00d7200 raw image, which might be surprising at first, but it\u2019s intended and correct behaviour).
"},{"location":"releases/release-notes/0.81.0/#supercharged-image-and-video-capturing","title":"Supercharged image and video capturing","text":"The optimised zlib-ng library has been added to mitigate the video capturing performance hit incurred by our new more accurate VGA emulation approach compared to 0.80.1. In fact, zlib-ng not only makes up the difference but speeds video capturing up by another factor of three (!) versus 0.80.1! This makes a huge difference on older CPUs, but even on fast modern machines, you can now capture videos at higher resolutions without glitches.
Additionally, image capturing is now being performed in multiple background threads. This eliminates emulation micro-pauses and sound glitches even when rapidly spamming the screenshot hotkey. This was a problem even on fast machines with rendered post-shader captures at 4K resolution.
"},{"location":"releases/release-notes/0.81.0/#aspect-ratio-and-viewport-enhancements","title":"Aspect ratio and viewport enhancements","text":"Stretching the image to completely fill the screen has been an often requested feature (e.g., to play text adventures without black bars on the sides). Now we\u2019re giving you not only that but an entirely new mechanism to apply arbitrary aspect ratios, zoom into the DOS content, and even emulate the horizontal and vertical stretch controls of CRT monitors of yore!
The key element of the feature is the new aspect = stretch mode which stretches the image to the extents of the viewport. For example, to make a game completely fill the screen, use the following config:
[sdl]\nfullscreen = on\n\n[render]\naspect = stretch\nviewport = fit\ninteger_scaling = off\n
The second piece of the puzzle is the new relative mode added to the viewport setting (viewport_resolution has been renamed to viewport and moved to the [render] section). In relative mode, the viewport is a 4:3 aspect ratio rectangle fit into the window or screen as the starting point, which is then scaled by the specified horizontal and vertical stretch factors. The resulting viewport is allowed to extend beyond the edges of the window or the screen, so this can be used to \u201czoom\u201d into the image while forcing arbitrary aspect ratios.
For example, you can aspect ratio correct lazy Hercules conversions that just reused the EGA/VGA assets and make them fill the screen better by zooming in a little. The following example illustrates this in Prince of Persia in Hercules mode:
[render]\naspect = stretch\nviewport = relative 112% 173%\ninteger_scaling = off\n
You can use the Stretch Axis, Inc Stretch, and Dec Stretch hotkey actions to set the stretching in real-time (unbound by default). The current viewport setting is logged, so you can simply copy it to your config.
Prince of Persia without any custom stretching
Prince of Persia with aspect = stretch and viewport = relative 112% 173%
"},{"location":"releases/release-notes/0.81.0/#fix-black-vertical-bars-video-corruption-issue","title":"Fix \u201cblack vertical bars\u201d video corruption issue","text":"This is a fix for the \u201cblack vertical bars\u201d video corruption issue seen on a few late 90s games and demos that require Pentium CPUs. Due to some fairly intricate technical details to do with 80-bit x87 FPU emulation, the issue does not manifest in Intel builds, but it does in all non-Intel builds when using the non-dynamic cores.
A non-exhaustive list of affected programs:
Games
- Carmageddon (1997)
- Motor Mash (1997)
- Peter Sampras Tennis (1997)
Demos
- Sunflower by Pulse (1997)
- Multikolor by kolor (1997)
- toontown by kolor (1997)
Multikolor by kolor \u2014 Black vertical bars issue
Multikolor by kolor \u2014 After the fix
"},{"location":"releases/release-notes/0.81.0/#new-deinterlacing-shader-for-fmv-games","title":"New deinterlacing shader for FMV games","text":"Schlocky 90s FMV titles are the guilty pleasure of every true retro-gamer (we\u2019re no different, so zero judging!) Unfortunately, many of these games are plagued by a weird trick: the video footage is often displayed with alternating black \u201cinterlace lines\u201d. This just doesn\u2019t look very good on modern ultra-sharp flat screens, and upscaling such content with non-integer scaling ratios often causes very ugly interpolation artifacts.
To restore cosmic balance, we\u2019ve introduced a pair of \u201cdeinterlacing\u201d shaders, building upon the work of Ove Kaaven:
-
misc/fixvideo \u2014 This intelligently doubles scanlines that have a black line beneath them. Works well with non-integer scaling ratios.
-
misc/fixvideo-scanlines \u2014 Similar to the first one, but this retains a subtle scanline look to improve the \u201cperceptual resolution\u201d of the video footage. This one absolutely needs vertical integer scaling enabled!
Now you can enjoy your 90s FMV shlock in its full gory glory!
Angel Devoid: Face of the Enemy \u2014 Raw output
With the misc/fixvideo shader
With the misc/fixvideo-scanline shader
"},{"location":"releases/release-notes/0.81.0/#other-graphics-related-changes","title":"Other graphics-related changes","text":" -
OpenGL Pixel Buffer Object (PBO) support was dropped to enhance performance and efficiency. This will result in reduced energy use, reduced thermal load, and significantly improved performance on single-board computers, Intel HD Graphics, and AMD APUs.
-
The keymapper now supports high DPI screens.
-
We\u2019ve added support for disabling the screen via the clocking mode register. This fixes some visual glitches in Alien Carnage.
-
A new interpolation/catmull-rom shader has been added. This implements an upscaling method that looks better than the bilinear interpolation option you get with the none shader.
-
Various monochrome mode fixes & improvements affecting Hercules and monochrome CGA emulation have been made. Most notably, the manual \u201cbright mode\u201d hotkey to toggle between the two monochrome palette variants has been removed. Now the appropriate palette is auto-selected based on whether we\u2019re in a text or graphics mode.
-
A corner case delayed display regression was fixed in VFR presentation mode. The presentation mode auto-selection criteria have also been refined to achieve optimal results with a wider range of monitor, driver, and operating system combinations.
-
The legacy surface output mode has been removed. The new fallback option is the texture output mode that automatically selects the best available rendering backend via SDL (a purely CPU-based non-accelerated backend is available too). The preferred and recommended output mode is still OpenGL, as it always has been.
-
Fixed a regression where some colours had a very subtle greenish tint on emulated VGA adapters. In practice, this was only noticeable on dark neutral grey colours.
-
Reloading shaders at runtime via the hotkey action now works a lot more reliably.
-
Nearest-neighbour output modes aren\u2019t treated any differently anymore when determining the default window size.
-
sRGB GLSL pragmas now work correctly. Somewhat embarrassingly, the sharp shader was advertised to be gamma-correct more than a year ago, but sadly that was never the case\u2014until this fix.
-
Introduction of the use_npot_texture GLSL pragma to request non-power-of-two-texture.
-
Introduction of the force_single_scan and force_no_pixel_doubling GLSL pragmas to force no line doubling and no pixel doubling in VGA modes, respectively. This might come in handy for certain shaders that need to work on the \u201craw\u201d pixel data, such as upscalers.
-
We\u2019ve changed the VESA BIOS branding to DOSBox Staging (because we can )
Full PR list of graphics-related changes - (S)VGA/VESA square pixel mode fix/cleanup (#2583)
- Adaptive CRT shader compatibility fixes for really old GPUs (#3172)
- Adaptive shader fixes (#2866)
- Add
crt-auto-arcade-sharp adaptive CRT shader (#3083) - Add
misc/fixvideo.glsl OpenGL shader (#2442) - Add crt/aperture.mono shader variant (#2393)
- Add deinterlacing shader variants (#3200)
- Add new glshader/misc dir to the Meson build (#2443)
- Add support for disabling screen via the clocking mode register, fixes #2838 (#2842)
- Always log OpenGL shader and program info logs if they\u2019re non-empty (#3121)
- Aspect ratio and viewport improvements (#3124)
- Authentic adaptive CRT shaders (#2777)
- Auto-disable the integer scaling feature if the image is smaller than\u2026 (#2588)
- Capture modularisation/cleanup (#2451)
- Change VESA BIOS branding to \u2018DOSBox Staging\u2019 (#2712)
- Clean up OpenGL attribute init (#3111)
- De-SDL voodoo threading (#2568)
- Deprecate machine type
vgaonly (#2398) - Disable framebuffer acceleration for debugger (#2477)
- Don\u2019t auto-disable OpenGL for debugger-enabled builds on Linux (#2480)
- Don\u2019t restrict text video modes to the VFR presentation mode (#2286)
- Double-scanning support for VESA modes, accurate mode change logging,
vga_draw.cpp rework & many other improvements (#2654) - Drop OpenGL PBO support (#3099)
- Enable vsync by default (#2373)
- Fix \u201c-fullscreen\u201d argument on Wayland (#2688)
- Fix CGA composite regression (#2662)
- Fix Tandy support for Ninja (1986) (#2225)
- Fix VESA 256 / 8-bit in Windows 3.1 (#2569)
- Fix a couple aspect ratios (#2612)
- Fix a couple issues from the
vgaonly PR (#2424) - Fix a crash when using
glshader = crt-auto-machine (#3077) - Fix a window size regression on macOS (#2374)
- Fix altered shader pragmas not taking an effect when reloading the shader (#2736)
- Fix comment describing BGRX8888 PixelFormat (#2766)
- Fix compilation failures on *BSD and colour rendering on big-endian platforms (#3155)
- Fix const issue writing a png with png12 (#2740)
- Fix double-scanning & pixel-doubling handling in
openglnb output mode (#3092) - Fix fallback shader scaling for adaptive CRT shaders (#2840)
- Fix flicker in some games due to mouse driver breaking double buffering (#2867)
- Fix image capture indices always starting from 1 (#2656)
- Fix incorrect pixel aspect ratio calculation for all text modes (#2570)
- Fix infinite recursion problem at startup on Pop OS 22.04 and SDL 2.0.20 (#3209)
- Fix invalid default config value for voodoo_memsize (#2744)
- Fix mapper screen for high dpi (#2708)
- Fix raw image & video capture for 160x200 16-colour Tandy/PCjr modes (#3185)
- Fix raw video capture so it always writes non-double-scanned raw output (#3177)
- Fix regression in Build Engine games (3Dfx mode) (#2432)
- Fix regression in VGA draw\u2019s wrapped line case (#2441)
- Fix regression in palettized VGA line draw function (#2491)
- Fix regressions in some video modes\u2019 aspect and line-counts (#2445)
- Fix sRGB GLSL pragmas (#2665)
- Fix spelling mistakes in \u2018voodoo_*\u2019 config descriptions (#2859)
- Fix the aspect ratio of 40-column 00h and 01h BIOS text modes (#2852)
- Fix the calculation of vga.draw.lines_scaled when double scanning (#2806)
- Fix vertical bars due to FILD/FIST memcpy trick (#3151)
- Fixes and cleanup of PCI BIOS (#2731)
- Force OpenGL renderer backend for keymapper (#2768)
- Give Voodoo a gentle push to get it passing CI (#2710)
- Ignore extensions when finding highest capture index (#2946)
- Image capture enhancements mega-PR \u2014 Godzilla Edition\u00a9\u00ae\u2122 \ud83e\udd96 (#2503)
- Implement Voodoo usability fixes (#3103)
- Implement integer viewport scaling (#2456)
- Improve the \u201cmode 1\u201d deinterlace method (#3192)
- Include low width resolution in VGA scanning citeria (#2582)
- Introduce PixelFormat enum (#2735)
- Let the VESA 8-bit mode draw lines from the DAC palette (#2494)
- Limit consecutive duplicate frames in VFR presentation mode (#3004)
- Make triangle_worker members threadsafe (#2434)
- Minor voodoo performance tweaks (#2435)
- Monochrome mode fixes & improvements (#2769)
- Only capture the visible image in rendered image capture mode (#3194)
- Perform console cursor and text calls via interrupt (#3113)
- Port Voodoo support with multi-threaded software backend (#2410)
- Present VFR duplicate frames on a tempo (#2379)
- Refine when
presentation mode = auto uses throttled mode (#2818) - Reload shader fixes (#2730)
- Remove scan and pixel doubling config settings (#2728)
- Rename PixelFormat enum members BGR555 and BGR565 to RGB555 and RGB565 (#2823)
- Rendering related refactorings (#2739)
- Replace busy-wait atomic bool goto logic (#2545)
- Resize VGA within half the current frame-time (#2510) (#2528)
- Restore authentic text mode pixel aspect ratio calculation (#2625)
- Rework \u201cEGA mode with VGA palette\u201d CRT shader auto-switching (#3354)
- Retire surface output (#2780)
- Simplify and improve
presentation_mode handling (#2690) - Simplify double-scan criteria and let users
'force_vga_single_scan' w/ conf option (#2428) - Update Catmull-Rom shader (#2786)
- Use zlib-ng in local builds and CI releases (#3202)
- Video related refactorings (#2808)
- Window sizing improvements & aspect ratio related cleanup (#2749)
crt-auto should auto-switch to VGA shaders in EGA modes with 18-bit VGA palettes (#2819)sdlmain improvements (#3123)
"},{"location":"releases/release-notes/0.81.0/#sound","title":"Sound","text":""},{"location":"releases/release-notes/0.81.0/#ibm-music-feature-card-support","title":"IBM Music Feature Card support","text":"The IBM Music Feature Card is a rare and expensive sound card from the late 1980s. It is mainly supported by early Sierra SCI games and a few others, like Silpheed. Thanks to Loris Chiocca for authoring this originally! See the [imfc] section for further details.
We highly recommend checking out this excellent blog post to learn more about the interesting history of the card.
Game Audio example Quest for Glory: So You Want to Be a Hero Your browser does not support the audio element. The Colonel\u2019s Bequest \u2013 Intro 1 Your browser does not support the audio element. The Colonel\u2019s Bequest \u2013 Intro 2 Your browser does not support the audio element. The Colonel\u2019s Bequest \u2013 Intro 3 Your browser does not support the audio element."},{"location":"releases/release-notes/0.81.0/#roland-mt-32-rom-handling-improvements","title":"Roland MT-32 ROM handling improvements","text":"We have moved from the fiddly and error-prone filename-based Roland MT-32/CM-32L ROM lookup mechanism to checksum-based detection. It\u2019s no longer necessary to get the ROM filenames right; you can chuck all of them into your mt32-roms folder\u2014DOSBox Staging will do the rest! Valid ROMs are identified by their checksums (hashes) at runtime. Both interleaved (mt32pi style) and non-interleaved (MAME style) ROM files are supported.
As a result, the old \u201cversioned\u201d vs \u201cunversioned\u201d ROM differentiation doesn\u2019t make sense anymore. The mt32 and cm32l model types now behave differently: mt32 now selects the first available MT-32 ROM, and cm32l the first available CM-32L ROM (in priority order). Similarly, the mt32_old and mt32_new aliases are not tied to specific version numbers anymore but pick the best available ROMs.
The revised ROM selection method should be backward compatible with the most common use cases\u2014in fact, the new method should generally result in better matches, assuming the same ROM set.
Support for the rare 2.06 and 2.07 MT-32 ROMs and the CM-32LN 1.00 has also been added.
Lastly, we\u2019ve improved the output of the MIXER /LISTMIDI command to make the display of available ROMs and the active ROM much clearer.
Output of the improved MIXER /LISTMIDI command
"},{"location":"releases/release-notes/0.81.0/#fluidsynth-fixes","title":"FluidSynth fixes","text":"The Roland SC-55 and FluidSynth handle MIDI portamento messages (pitch glides between consecutive notes) very differently. As the rather unique Roland SC-55 portamento cannot be emulated with FluidSynth, music written for the SC-55 that uses it might sound weirdly out of tune on FluidSynth (e.g., the level 8 music of Descent).
All in all, it\u2019s best not to send MIDI portamento messages to FluidSynth at all to avoid the problem completely. The resulting sound is a lot closer to the Roland SC-55\u2019s output.
Additionally, a rather strange sound stage issue has also been fixed by upgrading to the latest FluidSynth library. The panning of some instruments was off-centre, slightly leaning to the left. The problem could be fairly subtle or quite apparent depending on the SoundFont in use, the musical score, and the instruments being played. You can hear it to varying degrees in the \u201cbuggy\u201d audio recording below recorded using the previous 0.80.1 DOSBox Staging version.
Descent \u2013 Level 8 (SC-55) \u00b9 Your browser does not support the audio element. Descent \u2013 Level 8 (FluidSynth buggy) \u00b2 Your browser does not support the audio element. Descent \u2013 Level 8 (FluidSynth fixed) \u00b3 Your browser does not support the audio element.
\u00b9 Roland Sound Canvas VA in SC-55 mode was used for the recording \u00b2 DOSBox Staging v0.80.1 (previous version) with the GeneralUser GS SoundFont \u00b3 Current DOSBox Staging version with the GeneralUser GS SoundFont
"},{"location":"releases/release-notes/0.81.0/#improved-mixer-command","title":"Improved MIXER command","text":"The MIXER command has been recreated from the ground up to make it a lot more robust and less confusing to use. The main highlights are as follows:
-
The MIXER command no longer accepts slightly incorrect input; command parsing is now strict and we\u2019re displaying error messages for invalid commands. These messages try to guide the users to correct their mistakes.
-
MIXER command handling is now \u201ctransactional\u201d\u2014if there is a single error in a list of multiple commands, no command is executed but an error for the first problem is raised. This leads to less confusing and more deterministic overall behaviour.
-
Mixer channels now retain their settings when a channel gets deleted and then re-created later (e.g., by setting sbtype none followed by sbtype sbpro1).
-
The CMS mixer channel is no longer renamed to GAMEBLASTER when sbtype is set to gb.
"},{"location":"releases/release-notes/0.81.0/#midi-muting-improvements","title":"MIDI muting improvements","text":"Previously, when muting the audio, all MIDI devices were sent Note Off messages, which was problematic with long-held notes in musical scores. You\u2019d get missing notes after unmuting, and the slower the tempo, the more annoying this problem would become.
Muting has been 100% fixed both for the internal Roland MT-32 and FluidSynth MIDI synthesisers and also for external MIDI devices. Technically, we keep feeding external devices with MIDI events in the muted state, but we set all channel volumes to zero when muting, and then restore the volumes when unmuting.
Also, we\u2019re now correctly muting the MIDI output when mute_when_inactive or pause_when_inactive is enabled.
"},{"location":"releases/release-notes/0.81.0/#sanitise-midi-output-roland-ra-50-compatibility","title":"Sanitise MIDI output & Roland RA-50 compatibility","text":"The MIDI drivers of many games don\u2019t fully conform to the MIDI standard, which makes editing the MIDI recordings of these games very error-prone and cumbersome in MIDI sequencers, often resulting in hanging or missing notes.
Now DOSBox Staging corrects the MIDI output of such games by default. This results in no audible difference; it only affects the representation of the MIDI data. Specifically, we\u2019re emitting Note Off messages for all active notes when an All Notes Off message is encountered (this is mandated by the MIDI specification, but many games ignore that). There are other Channel Mode Messages that result in an implicit All Notes Off message; these are handled correctly as well.
This incidentally also fixes the infamous hanging notes issue with the Roland RA-50 external MIDI module (the module does not implement the All Notes Off MIDI message).
A new raw_midi_output setting has been introduced to disable this \u201csanitisation\u201d of MIDI data. That might come in handy if you need to leave the raw MIDI stream unaltered (e.g., when working with music applications, or when debugging MIDI issues).
"},{"location":"releases/release-notes/0.81.0/#optionally-fade-out-hanging-notes-on-tandy-opl","title":"Optionally fade out hanging notes on Tandy & OPL","text":"Some games like Bard\u2019s Tale Construction Set and California Games II suffer from hanging note issues where the notes are not always properly terminated at the end of a musical piece. We\u2019ve introduced an option to fade out the OPL or Tandy sound output after the last IO port write to these audio devices to remedy the situation. See the documentation of the opl_fadeout and tandy_fadeout settings for further details.
"},{"location":"releases/release-notes/0.81.0/#cd-audio-support-on-linux-for-physical-cd-roms","title":"CD Audio support on Linux for physical CD-ROMs","text":"CD Audio is now supported on Linux too via ioctls when using physical CD-ROMs. The audio is routed through the DOSBox mixer, each drive having its dedicated mixer channel (CDAUDIO_0 for the first drive, CDAUDIO_1 for the second, and so on).
With this addition, we now support CD Audio on both Windows and Linux for physical media (but on Windows, the CD audio still goes through the OS-level mixer).
"},{"location":"releases/release-notes/0.81.0/#other-sound-related-changes","title":"Other sound-related changes","text":" -
It\u2019s no longer possible to create DMA conflicts by configuring multiple sound devices to use the same DMA channel. In case of a conflict, the last configured or enabled device takes precedence and the other device gets deactivated automatically. The three sound devices that use DMA are the Sound Blaster, the Tandy DAC (the Tandy PSG doesn\u2019t need it), and the Gravis Ultrasound.
-
The crossfeed config setting has been revised; now it works the same way as the chorus setting (it has light, normal, and strong presets; on defaults to normal).
-
Fixed a regression that made the sound effects sound crackly in Duke Nukem 3D when using 44 kHz sample rate on the Gravis Ultrasound.
-
Fixed a Gravis Ultrasound regression where 16-bit samples sounded noisy in some games (e.g., Star Control II and Star Trek: The Next Generation \u2013 A Final Unity).
-
Un-deprecate the per-SoundFont volume scaling as it is useful to reign in overly loud SoundFonts.
-
Ignore speaker-output enable/disable commands on the Sound Blaster 16 (this is how the hardware works). This increases compatibility with some badly coded games, e.g., the digital audio in Monkey Island 2: LeChuck\u2019s Revenge Ultimate Talkie Edition was muted before this fix.
-
CD-ROM seek delays are now emulated to fix the CD audio in a few games. For example, Chasm: The Rift stopped playing the music after about 20 minutes of gameplay without this fix.
-
Fixed a regression where the Sound Blaster 16\u2019s maximum sample rate was erroneously clamped to 45\u2009000 Hz (it can go up to 45\u2009454 Hz on real hardware). This caused the sound to be slightly out of tune in programs that use the maximum sample rate.
-
Fixed a regression that prevented Tandy Sound from being re-configurable at runtime.
Full PR list of sound-related changes - Accumulate GUS frames accross each voice instead of per-sample (#2696) (#2698)
- Add Loris Chiocca\u2019s IBM Music Feature Card (IMFC) patch (#2367)
- Add
iir to the set of MSYS2 packages (#2242) - Add a fade-to-sleep-after-last-port-write feature to the mixer (#3058)
- Always clamp \u2018frames_needed\u2019 to the allowed mix/max range in the mixer (#2843)
- Always clamp
frames_needed to the allowed mix/max range in the mixer (#3217) - Clamp the max Sound Blaster 16 sample rate to 45454 Hz, not 45000 Hz (#2676)
- Cleanup the GUS and SB DMA channels on close (#2585)
- Consistently cast and wrap the mixer\u2019s position (#2745)
- Do not send portamento messages (MIDI CC 5, 65 & 84) to FluidSynth (#2705)
- Don\u2019t rename the CMS mixer channel to GAMEBLASTER when
sbtype is gb (#2228) - Drop volatile members in IMFC and reSIDfp (#2380)
- Extract MIXER command into its own file (#2839)
- Fix MIDI capture (#2707)
- Fix Sound Blaster DMA ADPCM frame count assertion error (#2277)
- Fix a Coverity warning in SDL Sound (#3000)
- Fix a GUS regression when interpolating 16-bit samples (#2576)
- Fix a couple regressions in
main relating to MIDI refactoring (#2541) - Fix description of the
imfc_filter setting (#3205) - Fix duplicate SoundFont listing in mixer /listmidi (#3074)
- Fix spurious directory separators in
mixer /listmidi output (#2383) - Fix state handling of the BIOS\u2019s Tandy DAC callbacks (#3148)
- Fix the priority of the \u201cset decibel volume\u201d MIXER command (#3068)
- Ignore speaker-output enable/disable commands on the SB16 (#3105)
- Implement CD Audio using Linux ioctls (#2675)
- Improve MIDI buffer underrun logging (#2227)
- Let derived CDROM devices asynchronously lag their calls (#2622)
- Let only one device reserve a DMA channel at a time (#2593)
- Link mt32emu statically in the MSYS2 CI release (#2711)
- Load MT-32 ROMs from
romdir using hash matches (#2591) - Lookup MT-32 ROMs using std::filesystem paths (#2387)
- MIDI mute improvements (#2318)
- MIXER command improvements & general mixer enhancements + fixes (#2868)
- Minor string fixes in MIXER command (#3072)
- Mixer refactoring & cleanup (#2787)
- Only process MT-32 debug messages in debug builds (#3100)
- Re-add the SDL Sound assert (third time\u2019s a charm?) (#3006)
- Re-initialize the BIOS DAC callbacks on SB and Tandy changes (#3142)
- Refill the SB audio channel when DMA reaches terminal count (#233) (#2614)
- Rework the MT-32/CM-32L ROM lookup and
MIXER /LISTMIDI improvements (#3011) - Sanitise raw MIDI output by default & add
raw_midi_output config option (#2308) - Setup the BIOS Tandy DAC only after critical BIOS features are setup first (#3199)
- Sync Nuked-OPL3 with upstream (#3015)
- Sync YM1728B_emu with upstream (#3021)
- Sync fluidsynth, glib, gtest, libjpeg-turbo, and mt32emu wraps (#2991)
- Sync reSIDfp with upstream (#3067)
- Sync residfp with 2.4.2 (#2259)
- Try again to fix Coverity warning in SDL Sound (#3005)
- Tune the IBM Music Feature card\u2019s 0-dB level and default filter (#3048)
- Un-deprecate the per-SoundFont volume scaling (#2677)
"},{"location":"releases/release-notes/0.81.0/#input","title":"Input","text":""},{"location":"releases/release-notes/0.81.0/#virtual-joystick-fixes","title":"Virtual joystick fixes","text":"Virtual joysticks can now be created without a physical joystick being plugged in. This fixes a regression introduced early in DOSBox Staging development, which now allows mapping keyboard events to joystick events. The deactivation logic of the pressed key now detects when the key is not being pressed anymore\u2014this improves joystick support in 74 games.
"},{"location":"releases/release-notes/0.81.0/#support-for-mapping-mouse-buttons-to-keys","title":"Support for mapping mouse buttons to keys","text":"Some games like Settlers I (also known as Serf City: Life is Feudal) require the player to push both mouse buttons at the same time to perform certain actions. This is impossible to perform on some input devices such as the Apple MacBook trackpad or the ChesterMouse. This has now been fixed by allowing mouse buttons to be mapped to the keys of the keyboard as a workaround.
"},{"location":"releases/release-notes/0.81.0/#virtualbox-mouse-driver-support","title":"VirtualBox mouse driver support","text":"DOSBox Staging has had experimental support for the VMware mouse protocol for quite some time now, and in this version, we have added support for the VirtualBox mouse protocol. The primary motivation is to enable seamless mouse operation in Windows 3.x.
Just install Javis Pedro\u2019s Windows 3.x driver and enjoy the seamless Windows 3.x experience!
"},{"location":"releases/release-notes/0.81.0/#multi-monitor-aware-mouse-capture-support","title":"Multi-monitor-aware mouse capture support","text":"DOSBox Staging now has fully multi-monitor-aware mouse capture and seamless mouse behaviour. Essentially, if DOSBox is in fullscreen mode on multi-monitor systems, mouse capture and seamless mode work as if you were still in windowed mode, allowing you to move the mouse cursor freely between the monitors.
The feature is enabled by default but it\u2019s only active on systems with multiple displays. Of course, you can always disable it by setting mouse_multi_display_aware to off in your config.
"},{"location":"releases/release-notes/0.81.0/#other-mouse-improvements","title":"Other mouse improvements","text":" - The PS/2 mouse port is now emulated at the register level, and more PS/2 protocol commands are supported. This allows the emulation of fairly complex input devices like the Microsoft IntelliMouse Explorer with 5 buttons and a mouse wheel on Windows 95.
- It is now possible to disable the built-in emulated mouse driver and use your favourite real DOS driver.
- Fixed problems with the internal mouse driver and text modes with more than 80 columns.
- Fixed mouse support in MS Word 5.5 for DOS.
"},{"location":"releases/release-notes/0.81.0/#macos-function-key-support","title":"macOS function key support","text":"macOS users can now force the Touch Bar or media keys to operate as function keys in DOSBox Staging (this will not affect other apps or the OS). Please refer to our wiki article for the setup instructions.
"},{"location":"releases/release-notes/0.81.0/#brazilian-abnt2-keyboard-support","title":"Brazilian ABNT2 keyboard support","text":"The mapper, keyboard, and BIOS tables have been expanded to handle the OEM102 and ABNT1 keys found on Brazilian ABNT2 keyboards. The left and right Windows keys have been assigned to their correct scan codes too.
Full PR list of input-related changes - Add extra hotkey button row in the mapper (#3147)
- Add mouse button mapping community patch (#3078)
- Add multi-monitor awareness mode for mouse capture (#2377)
- Create and update joy binds even when physical joysticks aren\u2019t present (#2516)
- DOS mouse driver fixes (#2601)
- Fix compatibility problems with VBADOS (VBMOUSE.EXE) mouse driver (#2742)
- Fix deactivation of queued joystick axis movement (#2713)
- Fix joysticks breaking after a config -set (#2694)
- Fix memory access in VirtualBox device, enable VirtualBox mouse protocol (#3089)
- Fix mouse centering on high DPI displays with scaling enabled (#2611)
- Fix mouse movement limitation regression in some games (#2648)
- Fix mouse problem with windowed mode and viewport_resolution setting (#2333)
- Fix problem with some software (like MSD.EXE) displaying garbage mouse driver info (#2538)
- Fix register-level PS/2 mouse access when DOS mouse driver is disabled (#3120)
- Fix the scan code sequence for the
pause key (#2498) - Handle OEM102 and ABNT1 keyboard scancodes (#2209)
- Implement DOS mouse driver function 0x32 (#2508)
- Implement i8042 diagnostic dump (#2298)
- Improve
mouse_sensitivity behavior (#3138) - Improve i8042 emulation, fix KEYB.COM (#2293)
- Improve text mode detection in DOS mouse driver (#2658)
- Keyboard rework and PS/2 mouse register-level access support (#2287)
- Minor cleanups in mouse and keyboard emulation code (#2230)
- Only unmute / unpause when Window focus is gained (#2254)
- Pause fixes (#2323)
- Port keymapper to SDL renderer (#2763)
- Prefer evdev mouse API over xinput on Linux (#2529)
- Release mouse if
config -set mouse_capture=nomouse is executed (#3129) - Reset DOS mouse driver position granularity on every mode change (#2608)
- Reworked virtual machine mouse support (#2755)
- Workaround for keyboard problem in Ultima VIII: Pagan (#3109)
"},{"location":"releases/release-notes/0.81.0/#dos-integration","title":"DOS integration","text":""},{"location":"releases/release-notes/0.81.0/#new-for-command","title":"New FOR command","text":"The missing FOR command has been added, resulting in better software compatibility with batch files that contain loops. The behaviour mirrors the behaviour of the MS-DOS 6.22 FOR command.
"},{"location":"releases/release-notes/0.81.0/#various-dos-command-additions-and-improvements","title":"Various DOS command additions and improvements","text":" - The missing
MOVE, TREE, SETVER, and VOL commands have been added. - The
CLS command now does not reset the screen mode to 80\u00d725. - The verbosity of the
DELETE command has been improved. - The wildcard handling of the
IMGMOUNT command has been improved. - The
LS command now accepts multiple paths or patterns and ignores hidden or system files unless the /A switch is specified. - The
MEM command now supports XMS memory capacities over 64 MB and has a critical bug fixed where it consumed all upper memory blocks after invocation. - The
MORE command is now extended with features from modern Windows.
"},{"location":"releases/release-notes/0.81.0/#persistent-command-history","title":"Persistent command history","text":"The emulated DOS shell now retains a 500-line history of your previous commands. The history is remembered across multiple sessions, just like you would expect it from a Linux shell.
If you\u2019d like to disable the shell history, set the new shell_history_file setting to an empty value.
"},{"location":"releases/release-notes/0.81.0/#support-for-all-dos-file-directory-attributes","title":"Support for all DOS file & directory attributes","text":"All DOS file and directory attributes are now supported.
On Windows, the attributes are stored as standard filesystem attributes.
On macOS and Linux, they\u2019re stored as a mixture of standard attributes (for the read-only flag) and extended xattr attributes. The extended attributes follow the Samba 3 format which is compatible with WINE and DOSEmu2.
"},{"location":"releases/release-notes/0.81.0/#autoexec-improvements","title":"Autoexec improvements","text":"Several long-standing autoexec issues have been fixed:
- The
[autoexec] section in config files is now fully UTF-8 aware and its contents are now converted to the internally set code page on the fly. - The size limitations of the
[autoexec] section have been lifted. - The generated
Z:\\AUTOEXEC.BAT is now prettier due to the added extra comments. - The
CONFIG -wc command does not eat away empty lines from the [autoexec] section anymore.
"},{"location":"releases/release-notes/0.81.0/#optional-shell-config-shortcuts","title":"Optional shell config shortcuts","text":"We\u2019ve supported config shortcuts for a long time now (e.g., instead of CONFIG -set sbtype sb16 you can simply use the sbtype sb16 shortcut). The feature is enabled by default, but this can cause some confusion when a shortcut conflicts with a DOS executable having the same name.
Now config shortcuts can be disabled by setting shell_config_shortcuts to off.
Full PR list of DOS integration related changes - Cleanup AUTOEXEC.BAT generation (#2609)
- Add FOR Command (#3094)
- Add full file path printing for file related debugger commands (#2472)
- Add short prompts for MORE commands for 40 column screen modes (#2953)
- Auto enable shell variable expansion for DOS >=7 (#2378)
- Autoexec fixes (#3007)
- Disable writing command line history if entry is empty (#2635)
- Do not discard empty lines in
[autoexec] section (#2415) - Do not write SETVER table back to file if secure mode is engaged (#2623)
- Don\u2019t block r/w file opens on r/o FAT images (#2280)
- Don\u2019t save command history to current working directory (#2630)
- Enable large disk image support (#2301)
- Exclude COMMAND.COM\u2019s help arguments when part of sub-command (#2263) (#2264)
- FAT image mounting fixes (#2278)
- FCB argument regression fix (#2524)
- File attribute support improvements (#2961)
- Filesystem fixes (#2288)
- Fix MSCDEX regression in game \u201cFascination (1991)\u201d (#3163)
- Fix alignment of file size column in the DIR command\u2019s output (#2799)
- Fix batch file \u2018goto\u2019 for previous labels (#2384)
- Fix bug where DTA can be modified by DELETE command (#2653)
- Fix drive automounts (#3038)
- Fix file creation regression on case sensitive file systems (#2971)
- Fix for DOS error code being wrongly set on creating files (#2989)
- Fix lockup involving specific mount order (#2310)
- Fix mounting directory with space in its name, passed as an argument (#2626)
- Fix read checks in shell file reader (#3076)
- Fix unneeded empty lines in \u2018TREE | MORE\u2019 display (#2944)
- Fixes for shell_misc.cpp regressions (#2517)
- Ignore trailing colon in shell redirection (#2240) (#2446)
- Implement DOS file/directory attributes support (#2951)
- Implement MOVE shell command (#2660)
- Implement SETVER.EXE command (#2464)
- Implement TREE.COM command (#2366)
- Implement persistent command line history (#2615)
- Implemented VOL shell command (#2638)
- Improve the help and output of the
CONFIG command (#2672) - Improve the online help of the MORE command (#2947)
- Improve verbosity of DELETE command (#2274)
- Improve wildcard handling for
imgmount file arguments (#2270) - Make MOVE and SUBST external commands (#2691)
- Make shell configuration shortcuts optional/configurable (#2807)
- Omit blank lines from command history (#2673)
- Re-write CLS command to not change screen mode (#3024)
- Re-write DOS_Shell::CMD_RENAME (#3126)
- Rename command_history to shell_history, for consistency (#2640)
- Rework and improve
LS.COM command (#3034) - Skip processing of hidden host files (#2240)
- Tab completion fixes for / and . (#2555)
- Track and free allocations in MEM program (#2534)
"},{"location":"releases/release-notes/0.81.0/#general","title":"General","text":""},{"location":"releases/release-notes/0.81.0/#revised-cpu-cycles-handling","title":"Revised CPU cycles handling","text":"Some legacy CPU cycles optimisations aimed at improving multi-tasking performance on single-core computers have finally been removed. These features probably made sense 20 years ago, but they no longer serve any useful purpose in a world where minimum quad-cores are the norm:
-
Previously, the cycles = max 100% setting resulted in only 90% CPU core utilisation and the max 105% \u201cmagic value\u201d expanded this to about 95%. Now 100% means 100%, and the weird 105% special case has been removed. As a beneficial side effect, cycles = max 100% can now make the CPU emulation thread go into oversubscription at times (over 100% capacity), resulting in a faster and more aggressive boost clock ramp-up.
-
CPU emulation is no longer silently throttled to half the configured cycles setting (!) when the DOSBox Staging window is unfocused. Such behaviour can cause audio glitches when listening to music in the background, and severely degrade performance when running computation-intensive tasks in DOSBox (such as compiling programs or rendering 3D images) while doing something else on your computer.
-
The rate for cycle guessing has been increased from 4 to 10 times per second, allowing emulation to reach optimal speeds much quicker.
-
We\u2019ve also added compensation for delays caused by the system graphics driver, such as vsync, which were adversely affecting the cycle guessing performance.
-
The DOSBox Staging window\u2019s title bar now shows the current cycles setting more accurately; specifically, the limit option is now also shown, if configured.
"},{"location":"releases/release-notes/0.81.0/#pause-improvements","title":"Pause improvements","text":"The pause feature now operates on the same principle as the mute function: you press the pause hotkey to pause, then press it again to unpause. Alt+Pause remains the hotkey on Windows and Linux, and on macOS you can use the newly introduced Cmd+P hotkey.
Additionally, we\u2019ve restored the pause indicator in the window\u2019s title bar too.
Various edge-case scenarios with the pause_when_inactive setting have also been fixed.
Pause gotchas
All input is disabled in the paused state\u2014the only thing you can do is press the pause hotkey again to unpause the emulator.
Remapping the pause hotkey is not supported (technically, you can do it in the mapper, but that will break the pause feature).
"},{"location":"releases/release-notes/0.81.0/#config-improvements","title":"Config improvements","text":" -
Previously, the primary config was only written if it did not exist and no local config was present. This was rather confusing and inconsistent. The new behaviour is to always write the primary config with the default settings if the file is missing or if it\u2019s empty.
-
You can now enable portable mode by putting an empty dosbox-staging.conf file into your DOSBox Staging executable folder. DOSBox will write the default settings to this empty file on the first launch.
-
For config settings that toggle an option (booleans), you can now use on, enabled, yes, true or 1 for enabling the feature, and off, disabled, no, false or 0 for disabling it.
-
Now the config descriptions list the defaults for all settings in a consistent manner.
-
Deprecated settings are handled better by the CONFIG command now, e.g., when listing all settings in a section, the deprecated settings are filtered out.
-
The CONFIG command has been generally revised to make working with configs simpler and more intuitive.
"},{"location":"releases/release-notes/0.81.0/#revised-capture-naming-scheme","title":"Revised capture naming scheme","text":"The naming scheme of the captured files has been revised. Previously, the name of the running DOS executable was used as the basename to which a running number was appended. This rarely added any value because DOS programs tend to have short nonsensical names such as GAME.EXE, START.EXE, SCIV.EXE, etc. If anything, this only created confusion when capturing the output from multiple differently named programs during a single DOSBox session because all basenames effectively had their own independent counters. In such a scenario, the only way to view the captured images in a timeline order was to sort them by creation date which was cumbersome.
Technically, this change was necessary to keep the counter values in sync when taking screenshots in multiple formats with the default screenshot action, but it makes a lot of sense in general too.
Captured images are now named as follows (the 0001 part is a running counter):
- Raw capture:
image0001-raw.png - Upscaled capture:
image0001.png (no postfix) - Rendered capture:
image0001-rendered.png
The other capture types have the following naming scheme:
- Audio:
audio0001.wav - Video:
video0001.avi - MIDI:
midi0001.mid - Raw OPL:
rawopl0001.dro - OPL instruments:
oplinstr0001.rad - Serial log:
serial0001.serlog
Note that the last counter value in the capture folder per capture type is only looked up at startup or after changing the capture_dir setting.
"},{"location":"releases/release-notes/0.81.0/#command-line-user-experience-improvements","title":"Command-line user experience improvements","text":"We listened to our users and improved the command-line user experience. Every option has been looked at critically; text descriptions have been rewritten, and some old options have been removed that do not apply to the current state of the software. All behaviour is still backward compatible to ensure smooth operation with old batch files and shell scripts.
Most notably, some long options were prefixed with a single dash (e.g., -machine, -lang) and some with two dashes (e.g., --list-glshaders, --printconf). Now all options conform to GNU conventions, so all long options start with two dashes (e.g., --machines). The legacy single-dash variants are still silently recognised for backward compatibility.
"},{"location":"releases/release-notes/0.81.0/#normalise-windows-explorer-context-menus","title":"Normalise Windows Explorer context menus","text":"If you\u2019re using the installer version on Windows, now starting DOSBox Stating via the right-click context menu in Windows Explorer is more consistent. Regardless of whether you click on a folder or the empty space inside a folder, DOSBox Staging will start with the working directory set to that folder.
The previous ability to execute .EXE, .COM and .BAT files directly using the right-click menu has been removed as that feature was inconsistent, confusing, and had limited applicability.
The ability to execute a .conf file using the context menu has been retained.
"},{"location":"releases/release-notes/0.81.0/#log-window-support-on-macos","title":"Log window support on macOS","text":"Previously, macOS users couldn\u2019t view the logs when starting DOSBox Staging from the Finder. We\u2019ve fixed that by adding a new special shortcut to the DMG installer to start Staging with a log window open.
How to use it
Follow the steps indicated in the DMG package, as shown:
Simply copy the included Start DOSBox Staging (logging).command to a folder then open it in Finder. DOSBox Staging will act as if started from that folder, it will pick up the local config, and it will also open a terminal window that shows the logs. \u00a0
Note
You might be asked to give DOSBox Staging access to the containing folder on the first launch\u2014just click OK if that dialog comes up.
"},{"location":"releases/release-notes/0.81.0/#modernised-application-icons","title":"Modernised application icons","text":"The new icons are compliant with modern OS interface guidelines and improve legibility at small icon sizes. A custom icon with a rounded rectangle design has been added for macOS that conforms to the Apple Human Interface Guidelines.
Linux users downloading the release from the website should run the included install-icons.sh script to see the new icons.
"},{"location":"releases/release-notes/0.81.0/#maximum-memory-space-increased-to-3-gb","title":"Maximum memory space increased to 3 GB","text":"The maximum XMS memory size has been increased from 63 MB to 3 GB. Windows 3.1x now allows more than 64 MB of RAM to be allocated.
"},{"location":"releases/release-notes/0.81.0/#modem-improvements","title":"Modem improvements","text":"The modem speed and port baud rate now match by default. This simplifies things as there isn\u2019t a possibility for the modem and port speeds to mismatch with the defaults anymore. Modem speed is now reported in bps (bits per second) to differentiate it from port speed. This fixes v1.2 of Doom as that game mandates a modem speed of 9\u2009600 bps.
"},{"location":"releases/release-notes/0.81.0/#x87-fpu-emulation-improvements","title":"x87 FPU emulation improvements","text":" -
DOSBox Staging no longer quits when an x87 FPU stack overflow occurs. Real DOS allows the system to continue in such cases, so this mimics real hardware behaviour. This improves compatibility with some misbehaving programs such as the demo kkowboy by blasphemy.
-
Rounding floating point numbers very close to integers has been fixed on non-x86 platforms. This fixes some obscure issues like not being able to increase the view size above 99 in Quake on ARM CPUs.
-
Fix \u201cblack vertical bars\u201d video corruption issue due to FILD/FIST memcpy trick in some late 90s Pentium games and demos. This was caused by a trick these programs do to perform a fast memory copy of 64-bit integer values by misusing the FILD/FIST FPU instructions (also see here).
-
The Intel Floating Point Conformance Test for IEEE 754-1985 (MCPDIAG.exe) passes with zero failures on x86 hosts with core = normal too now in our official releases. 80-bit extended precision floating point numbers are truncated to 64-bit double precision on non-x86 hosts due to performance reasons; it\u2019s not recommended to use DOSBox Staging on such hosts for any engineering or financial calculations. The current state of x87 FPU emulation is as follows:
- 100% conformance in all Intel x86 (32-bit) and x64 (64-bit) Windows, macOS and Linux builds on all cores.
- Every other build, host, and core combination is non-conformant (but working at reduced 64-bit precision).
-
Builds that only support reduced 64-bit double precision floating-point emulation instead of full 80-bit extended precision now log a warning about this at startup.
"},{"location":"releases/release-notes/0.81.0/#debugger-improvements","title":"Debugger improvements","text":" -
Linux debugger-enabled builds now have OpenGL enabled (previously, this was disabled due to the OpenGL code paths not being compatible with the debugger on Linux).
-
A C_HEAVY_DEBUG compile-time feature has been added to allow breaking on memory reads in the integrated debugger. Similarly to most of the debugger features, this only works reliably when using core = normal with real mode programs.
"},{"location":"releases/release-notes/0.81.0/#improved-linux-man-page","title":"Improved Linux man page","text":"The Linux man page has been outdated for quite some time now. This has been rectified; the man page now contains an accurate description of the new and revised command-line interface of DOSBox Staging.
"},{"location":"releases/release-notes/0.81.0/#freebsd-openbsd-ppc-support","title":"FreeBSD, OpenBSD & PPC support","text":"DOSBox Staging can now be compiled on FreeBSD and OpenBSD. The PPC dynarec core has been broken for a while now; this has been fixed, and various endianness issues have been rectified so now you can run Staging on big-endian PPC processors without problems.
Full PR list of miscellaneous enhancements - Always write the primary config if it doesn\u2019t exist (#2966)
- Don\u2019t throttle emulation speed when window becomes unfocused (#3085)
- Enable loguru stack traces (#2652)
- Fix FROUND Issues (#3161)
- Fix rounding when very close to an integer (#3149)
- Import FPU scale fix for x86 normal core (#2297)
- Improve handling of deprecated settings and other setting related improvements (#3118)
- Increase maximum memory size to 384 MB (256 MB+128 MB) (#2289)
- Logging & config description improvements (#2668)
- Never hard-exit DOSBox when an x87 FPU stack overflow is detected (#2564)
- Normalise warnings messages (#3143)
- Regenerate primary config file if it is empty (#3139)
- Restore pause on macOS & pause indicator in the window\u2019s title bar (#3140)
- Restore sane
max N% cycles behaviour where 100% means 100% (#3141) - Skip compiler if error instead of aborting in compile_commits.sh (#3130)
- Skip hidden dot files when wildcard pattern is first (#2492)
- Turn down loguru verbosity when started with following arugments (#2722)
- Update Tracy to 0.10 (#3022)
- Update increaseticks sleep strategy (#2655)
- Updated modem CONNECT response behavior (#3023)
- Use C++11
std::nearbyint() for nearest FPU round (#2296) - Use dynamic SDL version checking for logging (#2689)
Full PR list of miscellaneous fixes - Adapt to setup function additions (#2563)
- Add missing mutex lock to RWQueue (#2773)
- Allow FROUND fix on x64 (#3216)
- Always write the default config if the primary config file is missing (#3117)
- Change drive macros to return boolean values (#3020)
- Close file descriptor in cdrom ioctl class (#2685)
- Copy only the available command line chars (#2542)
- Display \u2018max limit\u2019 cycles setting properly in the title bar (#3214)
- Do not assert if mapperfile parameter is empty (#2995)
- Don\u2019t emulate CDROM lag for stationary calls (#2624)
- Don\u2019t sign extend 16-bit immediates to 32-bit in ppc64le dynrec, fixes #2846 (#2850)
- Fix \u2018auto\u2019 presentation mode on macOS in fullscreen (#3219)
- Fix
pause_when_inactive mouse behavior for macOS and Linux (#2262) - Fix completion index assertion error (#2531)
- Fix incorrect version reporting in Virtualbox LOG_WARNING. (#3002)
- Fix macOS debugger crash (#2495)
- Fix mistake in a comment (#2299)
- Fix mouse pointer for MS Word 5.5, based on DOSBox-X implementation (#2504)
- Fix no function names in Loguru stack traces on Linux (#2682)
- Fix null pointer de-reference in dyncache on Windows (#2863)
- Fix ppc64le backend and 64K page size support (#2828)
- Gracefully quit stdin loops on program termination (#2392)
- Handle exiting when
pause_when_inactive = true (#3079) - Make conf path handling more robust (#2241)
- Prevent duplicate SDL Window creation when using OpenGL (#2822)
- Replace invalid vector.end dereference with raw pointer access (#2471)
- Set the icon on window regeneration (#3081)
- Store envelope channel_name as std::string (#2670)
- Track previously added userdata when deleting the SDL resize watch (#2802)
- Use int64_t consistently for tick durations (#2596)
- Zero initalize memory allocation in GrowWriteMask in dyn_cache (#2986)
Full PR list of documentation-related changes - Add Instructions to Build on Nix (#2326)
- Add game mode support for macOS Sonoma or newer (#3016)
- Add missing defaults to all config settings that still don\u2019t have them (#3207)
- Add v0.80.1 release notes (#2203)
- Fix a few bad links in README. (#2320)
- Fix or simplify some descriptions (#3062)
- Fix the formatting of some config descriptions (#2560)
- Harmonize some help strings (#2686)
- Improve some config setting descriptions (#2578)
- Minor configuration file cleanups (#2634)
- Modify deploy website workflow to deploy to the GitHub Pages org repo (#2202)
- Move Wiki link to the top navbar from the footer (#2206)
- Normalise config descriptions and add default values to most of them (#2221)
- README.md typo Vorbis (#2791)
- Remove opencaptures (#2970)
- Rename \u2018cdda\u2019 to \u2018cdaudio\u2019 in the MIXER help examples (#2725)
- Revise the README template & include link to the new Getting Started \u2026 (#2360)
- Snip truism note from MIXER long help text (#3066)
- String fixes in CONFIG command (#2723)
- Update DOCUMENTATION.md (#2827)
- Update docs with supported versions of Windows, macOS, and Linux (#2258) (#2276)
- Update the Linux
man page (#2837) - Update translation guide (#3213)
- Various config setting description improvements (#2729)
- [DRAFT] Our man page is currently unmaintained - do not install it (#2820)
Full PR list of project maintenance related changes - Add \u201cStart DOSBox Staging (logging)\u201d command to the macOS DMG image (#2352)
- Add a memory read breakpoint feature to the builtin debugger (#3191)
- Add a script to compile all commits on the current branch (#2642)
- Add higher res icons to meson install script (#3179)
- Add several warnings to the GCC build (#2661)
- Add support for FreeBSD and OpenBSD (#2338)
- Add warning log if message is missing (#2566)
- Add wrap for SDL2 to support static macos builds (#2239)
- Adjust ticksDone with render time (#3136)
- Another batch of PVS Studio fixes (#2776)
- Another batch of PVS Studio fixes (#2756)
- Boolean config param handling improvements & cleanup (#2354)
- Bound and pin dependency versions (#2217)
- Change sdl.opengl.shader_source from std::string_view to std::string (#2753)
- Check and log *nix
ioctl return-code errors (#2721) - Clean up VESA_GetSVGAInformation() & get rid of warnings (#2715)
- Cleanup a Coverity null-deference reloading the shader (#2633)
- Cleanup a couple unhandled switch cases when OpenGL isn\u2019t available (#3197)
- Cleanup a handful of PVS Studio warnings (#2627)
- Cleanup a handful of unchecked return-code issues flagged by Coverity (#3180)
- Cleanup a handul of new Coverity issues (#2639)
- Cleanup among PCI/Memory constants (#2733)
- Cleanup in cross.cpp (#2447)
- Cleanup new CI warnings due to host-side updates (#2836)
- Cleanup two ASAN initialization order issues (#2330)
- Compile debug builds with GCC and Clang library check flags (#2553)
- Convert SDLOSXCAGuard files to UTF-8 (#2982)
- core_dyn_x86: Initialise rettype to avoid compiler warning (#2365)
- De-unionise X86PageEntry (#2994)
- Debug/trace logging improvements (#2832)
- Differentiate CLI arguments from markup tags with escapes (#2349)
- Do not set icon at runtime (#3171)
- Drop Visual Studio 2019-specific accomodations in
.clang-format (#2489) - Encapsulate the Cache\u2019s write mask functions as members (#2990)
- Fix OpenGL symbol type mismatch warning at link time (#3098)
- Fix Visual Studio project & filter definitions for src/hardware (#2459)
- Fix
format-commit.sh, Stop reformatting #includes (#2388) - Fix a couple Coverity warnings involved unchecked return values (#2631)
- Fix a couple recent Coverity warnings (#2368)
- Fix compilation error on
misc_util.h (#2329) - Fix coverity sign extension warning (#3001)
- Fix flipped ANSI colour intensity flag bug and use canonical CGA colour tag names (#2979)
- Fix for spelling mistake on NixOS.txt (#2363)
- Fix minor data read access issues flagged by TSAN (#2328)
- Fix nullptr compiler warnings (#2709)
- Fix several static analysis warnings (#2750)
- Fix small typos on
build-nix.md (#2341) - Fixing missing header file for select() syscall when building on MacO\u2026 (#2968)
- Harmonize ManyMouse support message in the build system (#3050)
- Hopefully make MSYS2 build pass (#2692)
- Improve DOSBox Staging application icons (#3157)
- Improve XMS emulation, based on code from DOSBox-X (#2386)
- Improve compile commits script (#2760)
- Increase max memory size to 3072 MB, minor cleanup (#2334)
- Let Meson use a system call to detect the page size (#3174)
- Let
DriveManager own all filesystem and image mount objects (#2306) - Make BatchFile Testable (#2618)
- Make the DOS module depend on SDL2 net (#2358)
- Make the RWQueue more usable for complex types (#2522)
- Mark all core run functions with
noexcept (#2251) - Move
bit_view value assignment to a general function (#2290) - Move dynamic FPU synchronization inside preprocessor defines (#2252)
- Normalise Windows context menus created by the installer (#2355)
- Notify all when RWQueue stops (#2775)
- PVS Studio fixes (#3088)
- PVS Studio warning fixes (#3070)
- Packaging improvements for icons on Linux (#3193)
- Perform safe left-shift of signed values in dynrec operators (#2535)
- Refactor Prop_path to use std_fs::path (#2700)
- Refactor Property->Get_string to return a std::string (#3009)
- Refactor WriteOut functions in program.cpp (#2309)
- Refactor command line arguments (#2703)
- Refactor shell_batch.cpp (#2342)
- Refactor shell_misc.cpp (#2482)
- Remove fontstash library (#3013)
- Remove obsolete APIs from \u2018dos_system.h\u2019 (#2976)
- Restore files required by the Linux Flatpak build (#2213)
- Revert increaseticks sleep to 1ms (#2792)
- Revert use of pinned vcpkg versions (#2222)
- Show backtraces in debug builds using Loguru\u2019s assert (#2650)
- Suppress excessively verbose
sprintf warnings on macos + clang (#2307) - Sync GHC std::filesystem with v1.5.14 (#2613)
- Sync Meson wraps with upstream (#2427)
- Sync decoders with upstream versions (#2718)
- Sync enet with upstream version 2.3.6 (#3012)
- Sync flatpak metadata up to
0.81.0-alpha (#2216) - Sync whereami with upstream (#3017)
- Typo fixed in setup.cpp (#3063)
- Update Linux AppData description (#2732)
- Update Linux and macOS debug CI workflows (#2628)
- Update RPM spec file (#2659)
- Update macOS build instructions (#3044)
- Use safe_strcpy and safe_strcat (#3003)
- Use safer calls in dynrec and operators (#2350)
- Use std math functions in
compressor.cpp (#3203)
Full PR list of other changes - Add docker image and CI job for ppc64le architecture (#2834)
- Add package download URL to issue template (#2473)
- Add pull request template (#2845)
- Avoid checked-STL false positives in Coverity build (#2561)
- Bundle all license texts with binary packages (#2420)
- Contribute an SDL audio test tool (#2317)
- Disable FluidSynth\u2019s own unit tests under MSYS2 CI (#2357)
- Drop Ubuntu 18.04 from the CI workflows (#2292)
- Improve caching of subpackages (#2269)
- Let MacOS homebrew overwrite conflicting junk files in CI (#2716)
- Reinstate MSVC CI workflow (#2573)
- Revisit our approach to categorising items in the release notes (#3196)
- Support the right control key on MacOS. (#2314)
- Suppress ALSA API macros PVS Studio warnings (#2783)
- Update Coverity to version 2023.6.2 (#3175)
- Update Windows SSL certificate authority in MSYS2 workflow (#2245)
- Update packages/*.txt files to include ffmpeg and conan (#2805)
- Update templates (#2830)
- Use versioned action/upload key names in CI workflows (#3215)
"},{"location":"releases/release-notes/0.81.0/#localisation","title":"Localisation","text":""},{"location":"releases/release-notes/0.81.0/#support-for-modern-and-historic-locales","title":"Support for modern and historic locales","text":"It is now possible to select between modern and historic (DOS era) locale styles via the new locale_period setting. Historic settings (if available for the given country) try to mimic old DOS behaviour when displaying information such as dates, times, or numbers; modern ones follow practices more consistent with typical current-day host systems.
Also, a lot more locale definitions not present in the original MS-DOS have been added from OS/2 Warp 4.52.
"},{"location":"releases/release-notes/0.81.0/#translation-updates","title":"Translation updates","text":" - Updates to Polish, Dutch, and Italian translations.
- The command-line help text is now translatable and correctly outputs UTF-8 text on Windows.
- The translation workflow has been simplified.
- A batch file for converting translations made on Windows to Unix carriage return format has been added.
"},{"location":"releases/release-notes/0.81.0/#script-to-convert-gog-cp473-config-files-to-utf-8","title":"Script to convert GOG CP473 config files to UTF-8","text":"GOG ship their DOS games with dosbox.conf files that assume the CP437 DOS codepage (also known as OEM-US or DOS Latin US). Some of their games display fancy startup menus via commands in the [autoexec] section, and these often use extended ASCII table drawing characters. This, however, conflicts with our revised UTF8-aware config handling, which results in the table drawing characters not being displayed correctly.
The fix is to convert such config files from CP473 to UTF-8 encoding. One of our contributors created a script that can convert such config files, even recursively in all subdirectories to fix up all your GOG games. You can download it from here. Make sure to install the required dependencies as described in the readme.
Full PR list of localisation-related changes - Add batch file (Windows) to convert GOG cp437 config files to UTF-8 (#3031)
- Add countries and historic locales from OS/2 Warp 4.52 (#3182)
- Add legacy codepage to UTF-8 script (#3029)
- Add more definitions to Unicode engine (#3084)
- Add translation batch file for Windows (#2303)
- Country codes cleanup, fix incorrect country set in some cases (#3134)
- Country support improvements (#3164)
- Fix UTF8 to DOS conversion by mistake applied twice in autoexec code (#2645)
- Fix extended ASCII codes not being rendered in batch files (#3028)
- Fix few English strings, update Polish (pl) translation (#2295)
- Fix problem with loading Unicode data files in some situations (#2641)
- Fix some mistakes in code page character to Unicode mappings (#2490)
- Group together shell error strings (#2343)
- Handle host code pages when running
dosbox.exe --help on Windows (#3064) - Improve Arabic support in Unicode engine (#2458)
- Improve Unicode character fallback rules (#2594)
- Improve batch file to convert GOG cp437 config files to UTF-8 (#3042)
- Let the command line
--help text be translatable (#3052) - Make
--list-glshaders output translatable (#3178) - Minor Unicode definitions improvements (#3153)
- Minor country and help fixes (#3186)
- Rework AUTOEXEC.BAT support, make it UTF-8 aware (#2425)
- Simplify translation workflow (#2954)
- Two trivial fixes (#2423)
- Unicode (and [autoexec]) improvements (#2422)
- Unicode engine improvements (#2548)
- Unicode mapping for CYRILLIC LETTER I WITH GRAVE, RUBLE, BG (#2621)
- Update Dutch (nl) translation (#3187)
- Update Dutch (nl) translation (#3069)
- Update Dutch (nl) translation (#2974)
- Update Dutch (nl) translation (#2824)
- Update Dutch (nl) translation (#2680)
- Update Dutch (nl) translation (#2657)
- Update Dutch (nl) translation (#2372)
- Update Italian (it-IT) translation (#2385)
- Update Italian (it-IT) translation (#2327)
- Update Italian (it-IT) translation (improved some strings) (#2419)
- Update Italian (it-it) translation (#2302)
- Update Italian (it-it) translation (#3137)
- Update Italian (it-it) translation (#3065)
- Update Italian (it-it) translation (#2980)
- Update Italian (it-it) translation (#2815)
- Update Italian (it-it) translation (#2737)
- Update Italian (it-it) translation (#2702)
- Update Italian (it-it) translation (#2643)
- Update Italian (it-it) translation (#2584)
- Update Italian (it-it) translation (#2497)
- Update Italian (it-it) translation (#2476)
- Update Italian (it-it) translation (#2226)
- Update Polish (pl) translation (#3190)
- Update Polish (pl) translation (#3176)
- Update Polish (pl) translation (#3071)
- Update Polish (pl) translation (#3033)
- Update Polish (pl) translation (#2810)
- Update Polish (pl) translation (#2493)
- Update Polish (pl) translation (#2381)
- Update Polish (pl) translation (#2337)
- Update Polish (pl) translation (#2300)
- Update Polish (pl) translation, fix one more English string (#2724)
- Update Polish (pl) translation, trivial fix to one help string (#2644)
"},{"location":"releases/release-notes/0.81.0/#contributors","title":"Contributors","text":"The following commit authors, sponsors, supporters, and backers all invested their time or funds into the 0.81 release effort. Thank you!
Contributors are listed in alphabetic order.
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":"releases/release-notes/0.81.0/#081-commit-authors","title":"0.81 commit authors","text":"Complete list of commit authors who have contributed code, documentation, or translation changes:
- Burrito78
- classilla
- d10sfan
- dreamer
- farsil
- FeralChild64
- flakesl
- ftortoriello
- GranMinigun
- Grounded0
- h3xx
- johnnovak
- Kappa971
- kcgen
- keenanweaver
- khalid586
- kklobe
- LowLevelMahn
- MaddTheSane
- MeAreJeenius
- NicknineTheEagle
- Nopey
- rderooy
- runlevel5
- shermp
- signed-log
- sulix
- thaewrapt
- ThomasEricB
- Torinde
- weirddan455
"},{"location":"releases/release-notes/0.81.0/#081-sponsors","title":"0.81 sponsors","text":"Sponsors who have donated 100 USD or more per month:
"},{"location":"releases/release-notes/0.81.0/#081-supporters","title":"0.81 supporters","text":"Supporters who have donated 25 USD or more per month:
"},{"location":"releases/release-notes/0.81.0/#081-backers","title":"0.81 backers","text":"Backers who have donated 5 USD or more per month:
- BenBudr
- Burrito78
- flakesl
- Florent Wagner
- Hannu Hartikainen
- Hugo Lucorcio
- MagnusPerotinus
- Robin Mattheussen
- Thomas Eric
"},{"location":"releases/release-notes/0.81.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":"releases/release-notes/0.81.1/","title":"0.81.1 release notes","text":"Release date: 2024-05-12
"},{"location":"releases/release-notes/0.81.1/#summary","title":"Summary","text":"The main focus of this maintenance release is to fix a couple of regressions introduced in 0.81.0, most of them related to game compatibility, and address a few long-standing issues.
This release was made possible by everyone who tried 0.81.0, submitted bugs and pull requests, and tested the updates. Thank you!
"},{"location":"releases/release-notes/0.81.1/#regression-fixes","title":"Regression fixes","text":"The release fixes the following 0.81.0 regressions:
-
Fix Wing Commander 3 videos and cutscenes appearing height-doubled.
-
Introduce vga_render_per_scanline = off workaround to fix the crash-at-startup regression in Deus, Ishar 3, Robinson\u2019s Requiem, and Time Warriors.
-
Fix the Tandy version of Impossible Mission II crashing at startup.
-
Fix regression in Tyrian where pressing the arrow keys get registered twice in menus.
-
Fix starting In Extremis resulting in a black screen.
-
Fix wrong colours in Spell It Plus! (needs machine = svga_paradise).
-
Fix wrong colours and garbled graphics in Spong and Exobius.
-
Fix squashed video output in the text mode game Indenture.
-
Fix the DOSBox Staging window gaining focus on every emulated video mode change.
-
Fix crash when exiting DOSBox Staging while in fullscreen mode on macOS and Linux.
-
Fix not being able to disable OPL emulation with oplmode = none.
"},{"location":"releases/release-notes/0.81.1/#enhancements-and-fixes","title":"Enhancements and fixes","text":"We\u2019ve also backported a number of enhancements and fixes for long-standing issues:
-
Introduce vmem_delay = on to help with flickering graphics and speed issues in Hercules, CGA, EGA, and early VGA games. This has proven to improve compatibility with Future Wars, Operation Stealth, Quest for Glory II, Hostages, The Gold of the Aztecs, Crazy Brix, Corncob Deluxe, and Corncob 3-D so far.
-
Improve support for multiple joysticks/game controllers (the mapper could behave erratically if you had more than one controller connected).
-
Emulate a memory-expanded PCjr machine more faithfully. This improves game compatibility; for{ example, Space Quest (v1.0x and v2.2) and King\u2019s Quest (1986 PCjr DOS version) now work instead of hanging the emulator.
-
CD Audio is no longer muted in certain parts of Time Warriors and Alpha Storm.
-
The batch file installer of Alpha Storm no longer fails.
-
Forcing single scanning via crt-auto-arcade should now work with more programs.
-
Fix various VGA double scanning related edge cases in demoscene productions.
-
Detecting \u201crepurposed\u201d EGA video modes with 18-bit VGA DAC colours has been made more robust when using the crt-auto shader (should result in a double-scanned VGA shader being picked).
-
Spanish and Brazilian Portuguese translations have been added, and most of the other translations have been updated.
Read on to learn about the details!
"},{"location":"releases/release-notes/0.81.1/#how-to-upgrade","title":"How to upgrade","text":"Start by downloading the latest version, then make sure to upgrade your primary configuration as described below.
"},{"location":"releases/release-notes/0.81.1/#downloads","title":"Downloads","text":""},{"location":"releases/release-notes/0.81.1/#upgrading-your-primary-configuration","title":"Upgrading your primary configuration","text":"Since config settings might get renamed, altered, or deprecated between releases, it\u2019s best to let DOSBox Staging write the new default primary config on the first launch, then reapply your old settings manually.
Start by backing up your existing primary config. This is where to find it on each platform:
Windows C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox-staging.conf macOS ~/Library/Preferences/DOSBox/dosbox-staging.conf Linux ~/.config/dosbox/dosbox-staging.conf You can also execute DOSBox Staging with the --printconf option to have the location of the primary config printed to your console.
After backing up the existing primary config, simply start the new version\u2014a new dosbox-staging.conf will be written containing the new defaults and updated setting descriptions.
Portable mode notes
In portable mode, dosbox-staging.conf resides in the same folder as your DOSBox Staging executable. The migration steps for portable mode users are as follows:
- Unpack the new version into a new folder (this is important).
- Create a new empty
dosbox-staging.conf file in the new folder to enable portable mode. - Launch the new version.
DOSBox Staging will write the new defaults to the empty dosbox-staging.conf file. After this, you carry over your settings from the old primary config manually.
"},{"location":"releases/release-notes/0.81.1/#after-upgrading","title":"After upgrading","text":"Look for deprecation warnings in the logs (in yellow or orange colours) and update your configs accordingly.
"},{"location":"releases/release-notes/0.81.1/#graphics-related-changes","title":"Graphics-related changes","text":""},{"location":"releases/release-notes/0.81.1/#vga-double-scanning-fixes-improvements","title":"VGA double scanning fixes & improvements","text":" -
The SVGA/VESA double scanning criteria has been refined, which fixes a Wing Commander 3 regression where the videos and cutscenes appeared height-doubled.
-
Some 320\u00d7 } 200, 320 & times; 240 and similar tweaked double - scanned VGA modes were incorrectly identified as 320 & times; 400, 320 & times;480, etc., which was confusing in the logs and single scanning could not be forced on them (e.g., with glshader = crt-auto-arcade). Affected programs include Pinball Dreams, Show by Majic 12, and the Copper demo (see the issue ticket for the exact details).
-
Support \u201cunorthodox\u201d scanline repeats on VGA in forced single scanning mode. This improves compatibility with demoscene productions; for example, Show by Majic 12 sets up a custom 320\u00d740 mode and then uses scanline-quintupling to repeat every line 5 times in the zoom-rotator part in the intro.
-
Support for double-scanned text modes was removed by mistake, which we\u2019re now restoring. This resulted in the text mode game Indenture appearing squashed (half-height). The game sets up a custom 640\u00d7200 text mode using the 8\u00d78 pixel CGA font with double scanning enabled.
-
Detecting \u201crepurposed\u201d EGA video modes with 18-bit VGA DAC colours on emulated VGA adapters has been made more robust. In these scenarios, the crt-auto shader should more reliably choose a double-scanned VGA shader instead of a single-scanned EGA shader.
"},{"location":"releases/release-notes/0.81.1/#option-to-emulate-video-memory-access-delays","title":"Option to emulate video memory access delays","text":"We\u2019ve added the new vmem_delay setting to the [dosbox] section to more closely emulate the behaviour of old video cards. This approximates the CPU-throttling effect of accessing slow video memory via the ISA bus. The feature was adapted from DOSBox-X based on a tip by MX9000. Thanks man!
To enable the feature, just set vmem_delay to on in your config. This can help reduce or eliminate flicker in Hercules, CGA, EGA, and early VGA games and \u201ceven out\u201d emulation speed in speed-sensitive titles.
We recommend enabling this only when necessary on a per-game basis, as it slows down the emulation. You can also fine-tune the delay by specifying the access delay in nanoseconds (on sets 3000 ns).
vmem_delay = on fixes the flashing graphics and various speed issues in at least the following titles:
- Corncob 3-D
- Corncob Deluxe
- Crazy Brix (
vmem_delay = 2000 and cycles = 70000 makes the game run smoothly) - Future Wars (also needs
cycles = 1000) - Gold of the Aztecs, The
- Hostages (also needs
cycles = 1500) - Operation Stealth (when VGA or EGA is selected in the game\u2019s setup)
- Quest for Glory II (fixes the too-fast vertical scrolling in the intro)
"},{"location":"releases/release-notes/0.81.1/#option-for-legacy-vga-rendering","title":"Option for legacy VGA rendering","text":"In 0.81.0, we made accurate per-scanline VGA rendering the only rendering option available (previously, you could only enable this via machine = vgaonly). A minority of games, however, have regressed by this and would crash at startup.
As a workaround, until we improve the accuracy of the VGA emulation, we\u2019re introducing the vga_render_per_scanline setting in the [dosbox] section. The setting is enabled by default, but you can disable it to restore the legacy rendering behaviour on a per-game basis.
Disabling vga_render_per_scanline fixes the crash-at-startup regression in the following Silmarils titles:
- Deus
- Ishar 3
- Robinson\u2019s Requiem
- Time Warriors
Note that these games are also CPU speed sensitive and would crash with high cycles settings\u2014see the issue ticket for config recommendations.
"},{"location":"releases/release-notes/0.81.1/#option-for-legacy-palette-behaviour","title":"Option for legacy palette behaviour","text":"The svga_paradise machine type now uses the legacy non-vgaonly palette behaviour. This fixes the wrong colours in some rare titles (e.g., Spell It Plus!).
"},{"location":"releases/release-notes/0.81.1/#tandy-graphics-fixes","title":"Tandy graphics fixes","text":"Fixed a regression where the Tandy version of Impossible Mission II would crash when starting a new game. This fix should restore our general compatibility with non-standard Tandy graphics modes as well.
"},{"location":"releases/release-notes/0.81.1/#other-fixes","title":"Other fixes","text":" -
Fixed the DOSBox Staging window gaining focus on emulated video mode changes.
-
Fixed crash when exiting DOSBox Staging while in fullscreen mode on macOS and Linux.
-
Fixed wrong colours and garbled graphics in Spong and Exobius.
Full PR list of graphics-related changes - Add
vga_render_per_scanline option (#3507) - Do not resize if Tandy vertical rows register is zero (#3448)
- Fix crash when quitting while in fullscreen mode (#3545)
- Fix double-scanning behavior for SVGA/VESA games (#3428)
- Fix Impossible Mission II transition effect (#3454)
- Fix the width of VGA text modes being incorrectly set sometimes (#3611)
- Fix \u201cunorthodox\u201d scanline repeats on VGA (#3441)
- Improve VGA double scanning criteria (#3446)
- Log OpenGL vsync state (#3553)
- Only raise window when it is newly created (#3440)
- Port video memory I/O delay tweak from DOSBox-X (#3597)
- Restore double scanning support for VGA text modes (#3568)
- Revert to legacy non-
vgaonly palette behaviour on svga_paradise (#3589) - Simplify \u201cEGA mode with VGA palette\u201d detection & make it more robust (#3639)
"},{"location":"releases/release-notes/0.81.1/#sound-related-changes","title":"Sound-related changes","text":""},{"location":"releases/release-notes/0.81.1/#implement-seeking-in-mscdex","title":"Implement seeking in MSCDEX","text":"A few games use the seek function of the CD-ROM but this was not previously implemented in our emulated MSCDEX driver. This resulted in CD Audio playing only sometimes in a few games.
The new seek implementation fixes CD Audio music in at least these titles:
- Time Warriors \u2014 CD Audio music is now playing during the main menu and gameplay.
- Alpha Storm \u2014 CD Audio music is now playing in the opening movie.
"},{"location":"releases/release-notes/0.81.1/#fix-not-being-able-to-disable-opl-emulation","title":"Fix not being able to disable OPL emulation","text":"Fixed a regression where you could not disable OPL emulation with oplmode = none anymore (sbtype = none still worked, but that disabled the Sound Blaster as well).
"},{"location":"releases/release-notes/0.81.1/#other-fixes_1","title":"Other fixes","text":" -
Fixed crash when output filter cutoff frequencies are not below half the sample rate (e.g., by setting rate = 11025 and sbtype = sbpro1 which selects a 8 kHz low-pass filter by default).
-
Fixed FluidSynth and MT-32 crashing the emulator when the host sample rate is set to 8000 Hz.
Full PR list of sound-related changes - Fix not being able to set
oplmode = none regression (#3565) - Fix various crashes when the host sample rate is set to low values (#3629)
- Implement seeking in MSCDEX (#3516)
- Use SB* and OPL logging prefixes consistely in all scenarios (#3587)
"},{"location":"releases/release-notes/0.81.1/#input-related-changes","title":"Input-related changes","text":" -
Fixed a keyboard handling regression in Tyrian where pressing the arrow keys get registered twice, making the menus very hard to use.
-
Fixed a keyboard handling regression in In Extremis where starting the game only resulted in a black screen.
-
Fixed various problems in the mapper when using more than a single game controller (e.g., with two joysticks connected, mapping the controls of the first joystick could randomly target the mappings of the second one and vice versa).
-
Fixed obscure regression where the timed = on joystick setting messed up the available free memory reported by the FreeDOS MEM.EXE command.
Full PR list of input-related changes - Deactivate IRQ if byte is read from i8042 chip (#3647)
- Fix handling multiple game controllers (#3404)
- Fix the \u2018In Extremis\u2019 game intro getting stuck (#3549)
- Set BIOS_Destroy not changeable at runtime (#3420)
"},{"location":"releases/release-notes/0.81.1/#dos-integration-related-changes","title":"DOS integration related changes","text":""},{"location":"releases/release-notes/0.81.1/#improved-expanded-pcjr-emulation","title":"Improved expanded PCjr emulation","text":"Now we\u2019re emulating a memory-expanded PCjr machine more faithfully. This improves game compatibility; for example, Space Quest (v1.0x and v2.2) and King\u2019s Quest (1986 PCjr DOS version) now work fine\u2014these games resulted in the emulator hanging previously.
A new pcjr_memory_config setting has been introduced to the [dosbox] section, defaulting to expanded (the new improved behaviour). Setting this to standard restores the legacy memory model. You should only need this for a handful of titles, such as the DOS conversions of the Jumpman and Troll PC Booter games.
"},{"location":"releases/release-notes/0.81.1/#dos-shell-improvements","title":"DOS shell improvements","text":" -
Fixed a bug that caused the batch file installer of Alpha Storm to fail.
-
The help text of the IMGMOUNT command now mentions the very handy wildcard mounting option. E.g., you can use the IMGMOUNT A floppy*.img -t floppy command to mount multiple floppy images, then cycle between them with Ctrl+F4 at runtime (Cmd+F4 on macOS).
-
The LOADFIX command\u2019s help text is more complete now (some options were not documented previously).
-
When a batch file was being instantiated, the echo state from the parent was not being transferred correctly if the parent was another batch file.
Full PR list of DOS integration related changes - Check the validity of leading path when checking device name (#3525)
- Improve the IMGMOUNT command\u2019s help text (#3551)
- Inherit batch file echo state from parent (#3578)
- Improve the help text of the LOADFIX command (#3221) (#3427)
- Make PCjr application memory contiguous (#3460)
"},{"location":"releases/release-notes/0.81.1/#localisation-related-changes","title":"Localisation-related changes","text":" - Spanish and Brazilian Portuguese translations have been added.
- Updates to the Dutch, German, and Polish translations.
Full PR list of localisation-related changes - Fix incomplete integration of Brazilian translation (#3438)
- New Spanish translation (#3317)
- Portuguese (Brazilian) Translation (#3432)
- Update br.lng (#3439)
- Update br.lng (#3458)
- Update de.lng (#3530)
- Update de.lng (#3530)
- Update Dutch (nl) translation (#3459)
- Update English (en) translation for 0.81.1 (#3600)
- Update German (de) translation (#3630)
- Update Italian (it) translation (#3560)
- Update Italian (it) translation (#3603)
- Update Polish (pl) translation (#3463)
- Update Polish (pl) translation (#3532)
- Update Polish (pl) translation (#3633)
- Update Portuguese (br) translation (#3469)
"},{"location":"releases/release-notes/0.81.1/#miscellaneous-changes","title":"Miscellaneous changes","text":" -
Attempting to change unchangeable settings via the CONFIG command at runtime is no longer silently accepted (without doing anything) but an error is raised instead.
-
Unknown command-line switches starting with dashes are now ignored and a warning is logged\u2014DOSBox Staging will not try to execute them anymore. As a side effect, the current working directory was mounted as the C drive, which led to very non-intuitive behaviour.
-
The Windows installer now creates a Start Menu shortcut to launch DOSBox Staging without showing the console window (DOSBox Staging (no console window) menu item).
-
The Windows installer no longer starts DOSBox Staging automatically when the installation is completed.
-
Most config settings are now correctly reverted to their defaults when an invalid value is set, and their values are kept in sync with the active setting.
Full PR list of miscellaneous changes - Add \u201cno console\u201d start menu item to the Windows installer (#3510)
- Better build version handling at runtime (#3556)
- Config setting defaulting/syncing improvements & fixes (#3626)
- Do not treat illegal command line switches as commands (#3621)
- Drop Debian 10 (#3557)
- Fix IPX config help comment (#3403)
- Improve \u2018keyboardlayout\u2019 option description (#3409)
- LTO build fix (#3538)
- Throw error if user attempts to change an unchangeable setting (#3470)
"},{"location":"releases/release-notes/0.81.1/#0811-commit-authors","title":"0.81.1 commit authors","text":"Complete list of commit authors who have contributed code, documentation, or translation changes:
- altiereslima
- bluddy
- Burrito78
- farsil
- japsmits
- FeralChild64
- ftortoriello
- johnnovak
- kklobe
- weirddan455
"},{"location":"releases/release-notes/0.81.1/#thank-you","title":"Thank you","text":"We are grateful for all the community contributions and the original DOSBox project, on which DOSBox Staging is based.
"},{"location":"releases/release-notes/0.81.2/","title":"0.81.2 release notes","text":"Release date: 2024-07-21
"},{"location":"releases/release-notes/0.81.2/#summary","title":"Summary","text":"This patch release fixes a critical keyboard regression bug in the classic Bitmap Brothers game Gods. The regression was accidentally introduced in the 0.81.1 release (#3777).
The game is very difficult to play without this fix, as holding down the movement keys may result in delayed movement, jerky start/stop motion, or no movement at all after a bit of playing.
Gods \u2014 with glshader = crt-auto-arcade to emulate the original Amiga look
"},{"location":"releases/release-notes/0.81.2/#installation","title":"Installation","text":"This is a drop-in upgrade for users already on\u00a00.81.0\u00a0or\u00a00.81.1\u2014no configuration changes are necessary.
For those upgrading from an earlier DOSBox Staging version, please follow these upgrade instructions and read the release notes of 0.81.0 and 0.81.1.
First-time users and people migrating from other DOSBox variants should start by reading the Getting started guide.
"},{"location":"releases/release-notes/0.81.2/#0812-commit-authors","title":"0.81.2 commit authors","text":""},{"location":"releases/release-notes/0.81.2/#thank-you","title":"Thank you","text":"We are grateful for all the community contributions and the original DOSBox project, on which DOSBox Staging is based.
"},{"location":"releases/release-notes/0.82.0/","title":"0.82.0 release notes","text":"Release date: 2024-10-20
"},{"location":"releases/release-notes/0.82.0/#summary","title":"Summary","text":"Just six short months after our monstre 0.81.0 release, we\u2019re back with another big one that adds
- Pentium MMX emulation,
- ESS Enhanced FM Audio,
- numerous audio related enhancements,
- a large number of game compatibility fixes,
- improved Windows 3.1x compatibility,
- supercharged 3dfx Voodoo emulation performance,
- experimental Windows ARM64 support,
and a lot more!
Read on to get the full story!
"},{"location":"releases/release-notes/0.82.0/#downloads","title":"Downloads","text":"Start by downloading the latest version, then make sure to upgrade your primary configuration as described below.
For those upgrading from an earlier DOSBox Staging version, please follow the upgrade instructions below.
First-time users and people migrating from other DOSBox variants should start by reading the Getting started guide.
"},{"location":"releases/release-notes/0.82.0/#how-to-upgrade","title":"How to upgrade","text":""},{"location":"releases/release-notes/0.82.0/#upgrading-your-primary-configuration","title":"Upgrading your primary configuration","text":"Since config settings might be renamed, altered, or deprecated between releases, it\u2019s best to let DOSBox Staging write the new default primary config on the first launch, then reapply your old settings manually.
Start by backing up your existing primary config. This is where to find it on each platform:
Windows C:\\Users\\%USERNAME%\\AppData\\Local\\DOSBox\\dosbox-staging.conf macOS ~/Library/Preferences/DOSBox/dosbox-staging.conf Linux ~/.config/dosbox/dosbox-staging.conf You can also execute DOSBox Staging with the --printconf option to have the location of the primary config printed to your console.
After backing up the existing primary config, simply start the new version\u2014a new dosbox-staging.conf will be written containing the new defaults and updated setting descriptions.
Portable mode notes
In portable mode, dosbox-staging.conf resides in the same folder as your DOSBox Staging executable. The migration steps for portable mode users are as follows:
- Unpack the new version into a new folder (this is important).
- Create a new empty
dosbox-staging.conf file in the new folder to enable portable mode. - Launch the new version.
DOSBox Staging will write the new defaults to the empty dosbox-staging.conf file. After this, you carry over your settings from the old primary config manually.
"},{"location":"releases/release-notes/0.82.0/#after-upgrading","title":"After upgrading","text":"Look for deprecation warnings in the logs (in yellow or orange colour) and update your configs accordingly.
"},{"location":"releases/release-notes/0.82.0/#game-compatibility-fixes","title":"Game compatibility fixes","text":" -
Fix regression in Command & Conquer: Red Alert where the emulator crashed after playing the game for a while.
-
Fix regression in The Magic Candle 2: The Four and Forty where the second MIDI sequence did not play.
-
Fix regression in Soltys where the Gravis UltraSound was not starting up after the game auto-detected it.
-
Fix Dunkle Schatten 2 freezing after startup.
-
Fix distorted HUD issue in the 3dfx Voodoo version of Archimedean Dynasty.
-
Fix the odd horizontal black lines appearing in the following Synthetic Dimensions games:
- Chronicles of the Sword
- Druid: Daemons of the Mind
- Perfect Assassin
-
1942: The Pacific Air War can now be played with sound when using the JEMM memory manager (see game notes).
-
Generically fix all Windows 3.1x games that complain about enabling file sharing, asking the user to run SHARE.EXE. This fixes at least the following games:
- Comix Zone
- Garfield Caught in the Act
- Microsoft Flight Simulator (v5.0, ATC Workshop)
- Monopoly
- Ultimate Yahtzee
-
Fix the intro tune in Bumpy\u2019s Arcade Fantasy using the wrong instruments on the MT-32.
-
Fix the AdLib intro jingle not playing in Silmarlis games (e.g., Crystals of Arborea, Ishar 1 & 2, Storm Master, Transantartica, etc.)
-
Fix flipped Sound Blaster Pro 2 output filter behaviour in Doom and all games that toggle the filter programmatically.
Note - Add carry, sign, zero, and parity flags to integer division instructions (#3785)
- Clean up some leaked file handles (#3673)
- Fix decrementing of MPU-401 track and conductor counters (#3766)
- Fix file open error in ISO Drive (#3804)
- Fix programmatic toggling of the Sound Blaster Pro 2 output filter (#3815)
- Fix regression in Voodoo 16-bit memory write (#3841)
- Fix the GUS reset register\u2019s startup behavior (#3755)
- Implement File Locking (#3687)
- Initialise the OPL operators per the AdLib v1.51 driver (#3772)
- Integrate MMX emulation (#3426)
- Move System File Table memory location (#3680)
- Prevent JEMM memory manager from detecting the VMware interface (#3925)
- Use inline memory routines for MMX (#3847)
- Use linear 128 KB video memory pages for VESA modes (#3767)
- Various MT-32 improvements & fix Bumpy\u2019s Arcade Fantasy intro tune (#3729)
"},{"location":"releases/release-notes/0.82.0/#graphics","title":"Graphics","text":""},{"location":"releases/release-notes/0.82.0/#remove-the-openglnb-output-mode","title":"Remove the \u2018openglnb\u2019 output mode","text":"The openglnb output mode for OpenGL with nearest-neighbour interpolation has been removed (nb stood for \u201cno bilinear\u201d, which is a roundabout way to say \u201cnearest-neighbour interpolation\u201d).
When using CRT shaders or any other shader, openglnb and opengl worked exactly the same way\u2014there was zero reason for preferring openglnb over opengl.
The only legitimate use-case for openglnb was to get nearest-neighbour interpolation with uneven pixels when not setting any shader explicitly. This was a relic from the past from pre-shader times when you had to select between two bad options when aspect-ratio correction was enabled: blurry output (with bilinear filtering) or sharp output at the expense of uneven pixels (with nearest-neighbour, or \u201cno bilinear\u201d interpolation). The much better current solution in DOSBox Staging if you want the \u201csharp pixel\u201d look is to use the sharp shader.
If you really want to, you can still use nearest-neighbour interpolation with the new nearest shader. But you\u2019ll get far better results with sharp, especially on 1080p displays.
The texturenb output mode remains available as a last resort fallback for weak hardware with no functional OpenGL drivers.
"},{"location":"releases/release-notes/0.82.0/#new-xbr-upscaler-shaders","title":"New xBR upscaler shaders","text":"A few of Hyllian\u2019s xBR upscaling shaders have been added for those hell-bent on playing games with a fake high-resolution look:
scaler/xbr-lv2-3dscaler/xbr-lv2-noblendscaler/xbr-lv3
"},{"location":"releases/release-notes/0.82.0/#3dfx-voodoo-improvements","title":"3dfx Voodoo improvements","text":" -
16-bit memory writes have been fixed in our Voodoo emulation; this resolves the distorted HUD issue in the 3dfx Voodoo version of Archimedean Dynasty.
-
The voodoo_multithreading confing setting (which previously toggled three extra worker threads), has been replaced with voodoo_threads which uses up to eight threads based on the number of available physical CPU cores. This is enabled by default (auto setting), but you can override it by setting the number of threads manually from 1 to 16.
-
The multithreading performance of the Voodoo emulation has been generally improved\u2014at the cost of higher overall CPU usage. Set voodoo_threads to 3 or less to conserve battery power on a laptop.
"},{"location":"releases/release-notes/0.82.0/#other-graphics-improvements","title":"Other graphics improvements","text":" -
Fixed the hardware cursor handling on the S3 Trio64 card; this fixes the display corruption on exit issue in the Teddybear\u2019s Revenge demo by Eclipse.
-
Now we use linear 128 KB video memory pages for all VESA modes. Some games exploit this low-level detail of some SVGA cards to access the video memory as a single contiguous 128 KB memory block instead of manually flipping between two 64 KB pages. This enhancement gets rid of the odd horizontal black lines in the following Synthetic Dimensions games and possibly in other games and demoscene productions too that use the same hack:
- Chronicles of the Sword
- Druid \u2014 Daemons of the Mind
- Perfect Assassin
-
Fixed a regression where video captures resulted in slightly larger file sizes than previously.
Full PR list of graphics-related changes - Add
use_nearest_texture_filter shader pragma and nearest shader (#3852) - Add xBR upscaler shaders (#3855)
- Address additional feedback on Voodoo thread count PR #3935 (#3939)
- Check if hardware cursor is actually being enabled or disabled before setting VGA_LineDraw (#3725)
- Comment out voodoo logging for local blending API call (#3907)
- Fix Windows 98 S3 driver regression (#3946)
- Fix ZMBV CompareBlock function returning a negative value for 24/32bpp types (#3908)
- Fix
INT10_ReloadFont() regression on VGA (#3943) - Fix assert failure from incorrectly mapping result of SDL_GL_SwapInterval() (#3844)
- Fix regression in Voodoo 16-bit memory write (#3841)
- Import missing S3 Trio64 XGA compare and fill routines from DOSBox-X (#3775)
- Kill
openglnb with fire \ud83d\udd25\ud83d\udd25\ud83d\udd25\ud83d\udd25\ud83d\udd25 (#3672) - Minor
vga_draw.cpp refactor (#3734) - Presentation mode, host rate & vsync cleanup (#3824)
- Use atomic operations and busy wait for Voodoo threads (#3952)
- Use linear 128 KB video memory pages for VESA modes (#3767)
"},{"location":"releases/release-notes/0.82.0/#sound","title":"Sound","text":""},{"location":"releases/release-notes/0.82.0/#multi-threaded-audio-processing","title":"Multi-threaded audio processing","text":"Some audio devices, such as the MT-32 and FluidSynth, were already running in their own threads. We\u2019ve taken this to the next level, and now the DOSBox mixer itself has got its own dedicated thread, too. This greatly reduces and often completely eliminates audio stuttering and glitches. The improvement is especially noticeable in games that use the Roland MT-32 or FluidSynth for MIDI music, the AdLib/OPL synth, the IBM Music Feature Card (IMFC), or Red Book CD Audio.
For example, now you should get zero glitches in the intro of Eric the Unready on the MT-32 when the game repeatedly switches between 320\u00d7200 and 640\u00d7480 VGA modes.
We plan to take this approach even further in the following releases, with the ultimate goal of achieving a 100% glitch-free, hardware-like audio experience.
"},{"location":"releases/release-notes/0.82.0/#ess-enhanced-fm-audio-esfm-emulation","title":"ESS Enhanced FM Audio (ESFM) emulation","text":"DOS audio connoisseurs, we have a real treat for you! We\u2019ve added support for emulating ESS Enhanced FM Audio, or ESFM, the OPL3-compatible FM synth found on later ESS AudioDrive cards.
In \u201clegacy mode\u201d, ESFM is fully compatible with the Yamaha OPL3; on most materials, it yields almost identical output (with the occasional subtle difference). What sets it apart is its \u201cnative mode\u201d, in which it offers advanced synthesis features surpassing the capabilities of the OPL3 chips. It bridges the gap between synthetic-sounding OPL music and MIDI music that uses sampled real instruments\u2014it definitely makes those expensive external MIDI modules run for their money!
Unfortunately, since ESFM was released in 1995, only a handful of games support \u201cnative mode,\u201d but in the few that do, the results sound quite spectacular!
-
To run ESFM in \u201clegacy mode\u201d, use oplmode = esfm with any Sound Blaster model and configure the game for Sound Blaster and AdLib/OPL as usual.
-
To use \u201cnative mode\u201d, set sbtype = ess and configure the ESS Technology ES1688, ES1788, ES1888 Enhanced FM Audio MIDI music driver in the game\u2019s setup utility (most games that support ESFM natively use the Miles Sound System). For the digital audio driver, select the Sound Blaster Pro option (ESS AudioDrive cards are Sound Blaster Pro compatible).
Here\u2019s a non-exhaustive list of games that support ESFM Enhanced FM music. If you discover more, please let us know!
- 11th Hour, The
- Advanced Civilization
- Callahan\u2019s Crosstime Saloon
- Gene Machine, The
- Heaven\u2019s Dawn
- Heroes of Might and Magic II
- Magic Carpet 2
- Settlers II, The
- Shannara
- Theme Hospital
- WarCraft II
- Z
Game Audio example Heroes of Might and Magic II \u2014 Title (ESFM) Your browser does not support the audio element. Heroes of Might and Magic II \u2014 Title (OPL) Your browser does not support the audio element. Heroes of Might and Magic II \u2014 In-game (ESFM) Your browser does not support the audio element. Heroes of Might and Magic II \u2014 In-game (OPL) Your browser does not support the audio element. The Settlers 2 \u2014 Track 5 (ESFM) Your browser does not support the audio element. The Settlers 2 \u2014 Track 5 (OPL) Your browser does not support the audio element. The Settlers 2 \u2014 Track 14 (ESFM) Your browser does not support the audio element. The Settlers 2 \u2014 Track 14 (OPL) Your browser does not support the audio element. The Gene Machine (ESFM) Your browser does not support the audio element. The Gene Machine (OPL) Your browser does not support the audio element. Heaven\u2019s Dawn (ESFM) Your browser does not support the audio element. Heaven\u2019s Dawn (OPL) Your browser does not support the audio element. The more adventurous among you can also try to \u201cretrofit\u201d the ESFM.MID driver from Miles Sound System games that have it into earlier ones that don\u2019t.
Here\u2019s how Discworld sounds with the ESFM driver from Heaven\u2019s Dawn\u2014it\u2019s pretty great, sounds almost like sample-based music!
Discworld (ESFM) Your browser does not support the audio element. Discworld (OPL) Your browser does not support the audio element."},{"location":"releases/release-notes/0.82.0/#adlibopl-dc-bias-remover","title":"AdLib/OPL DC bias remover","text":"Some games like Golden Eagle and Wizardry VI: Bane of the Cosmic Forge play digitised music and sound effects using the OPL (AdLib) channels by rapidly changing the volume in very crude steps, similar to how the Disney Sound System and Covox LPT DAC operate.
We\u2019ve introduced a new opl_remove_dc_bias config setting to the [sblaster] section, eliminating these annoying pops in affected games.
Recommended audio settings for Wizardry VI: Bane of the Cosmic Forge when configured for AdLib sound:
[sblaster]\nsbtype = none\noplmode = opl2\nopl_remove_dc_bias = true\nopl_filter = lpf 2 5500\n\n[speaker]\npcspeaker = off\n\n[autoexec]\nmixer opl 500\n
"},{"location":"releases/release-notes/0.82.0/#default-to-the-impulse-pc-speaker-model","title":"Default to the \u2018impulse\u2019 PC speaker model","text":"The impulse PC speaker model has been made the default option as it emulates the iconic little speaker found in old PCs more faithfully and with fewer overall issues.
The catch is that a small percentage of games have problems with it, so you might need to revert to the legacy and less accurate discrete model on a per-game basis.
"},{"location":"releases/release-notes/0.82.0/#decouple-cms-and-adlibopl-emulation","title":"Decouple CMS and AdLib/OPL emulation","text":"The CMS (Creative Sound System or Game Blaster) and OPL (AdLib) emulations have finally been decoupled. DOSBox always treated the emulation of the CMS as \u201cjust another OPL option\u201d, which was completely wrong as the AdLib and the CMS use different sound chips and have nothing to do with each other.
This resulted in various complications, such as oplmode = opl2 always enabling CMS emulation as well (probably to allow emulating early Sound Blaster cards that featured both the OPL2 and CMS chips).
The new model allows the user to control the OPL and CMS emulations separately:
oplmode only determines the type of OPL chip(s) to emulate. Valid values are none, opl2, dualopl2, opl3, and opl3gold.- The new
cms config setting in the [sblaster] section controls whether to emulate the CMS. Valid values are on and off.
Warning
As usual, oplmode = cms is still accepted with a deprecation warning, but you should update your configs to use the new model as we might remove support for the legacy settings in the future.
"},{"location":"releases/release-notes/0.82.0/#sound-blaster-pro-2-output-filter-fix","title":"Sound Blaster Pro 2 output filter fix","text":"Previously, toggling the analog output filter programmatically on the Sound Blaster Pro 2 (sbtype = sbpro2) was flipped due to a coding error. You can hear the difference in games that toggle the filter, such as Doom, when configured for the SB Pro 2 and authentic output filter emulation is enabled with sb_filter = auto.
"},{"location":"releases/release-notes/0.82.0/#adlibopl-improvements","title":"AdLib/OPL improvements","text":"The OPL (AdLib) chip is now initialised with the official AdLib v1.51 driver\u2019s startup values instead of the chip\u2019s native power-on state. Most games don\u2019t care about this because they fully overwrite the card with whatever state they need at startup, but this fixed the missing intro jingle in the following Silmarils games:
- Boston Bomb Club
- Bunny Bricks
- Crystals of Arborea
- Ishar 1
- Ishar 2
- Metal Mutant
- Storm Master
- Transantartica
"},{"location":"releases/release-notes/0.82.0/#further-mixer-improvements","title":"Further mixer improvements","text":" -
Fix lower-pitched audio bug when the emulated audio device\u2019s sample rate exceeds the host sample rate. E.g., if a program uses the maximum native 45\u2009454 Hz Sound Blaster rate and the host rate is 44\u2009100 Hz.
-
Host sample rates can now be set continuously from 8000 Hz to 96 kHz. This makes DOSBox Staging fully placebo and audio snake oil compliant! Also, by setting custom sample rates, you can capture audio at an emulated device\u2019s native rate without resampling.
-
blocksize can now be set to non-power-of-two values, too.
-
The nosound option now works better because it renders the audio and progresses the audio frames rendered counters (e.g., FastTracker II now plays the module even in \u201cno sound\u201d mode; previously, it was completely stalled). Additionally, you can now capture the audio to a WAV file even in \u201cno sound\u201d mode.
"},{"location":"releases/release-notes/0.82.0/#other-audio-improvements","title":"Other audio improvements","text":" -
The Gravis UltraSound and Sound Blaster can coexist now when you run ULTRINIT.EXE. This way, you can use the SB for digital sound effects and GUS for MIDI music via ULTRAMID.EXE or MEGAEM.EXE in supported games.
-
The Gravis Ultrasound\u2019s configuration options have been revised to reflect the actual options available on real hardware:
gusbase \u2014 Base addresses now range from 210 through 260gusirq \u2014 IRQs 2 and 15 have been addedgusdma \u2014 DMA 0 has been dropped (this setting is only useful on real hardware to park/disable the GUS)
-
Fix crash in Fasttracker II when GUS is configured to use IRQ 7.
-
Turn off the \u201ccable delay\u201d emulation MIDI for the MT-32. This fixes the intro tune in Bumpy\u2019s Arcade Fantasy, and probably other game startup issues, too.
-
Use 16-bit integer rendering mode for the MT-32 which is more accurate to the real hardware and much faster. Also, use \u201cnice\u201d partials mode and render at libmt32\u2019s 48 kHz \u201canalog emulation\u201d rate for improved authenticity.
-
Map the Capture MIDI action to Ctrl+Alt+F6 by default (Cmd+Option+F6 on macOS).
-
Reading audio data from physical CD-ROMs is now done in a separate thread, which should eliminate latency and stuttering issues.
-
Windows CD-ROM audio is now routed through the DOSBox mixer, bringing it to feature parity with Linux.
-
Fix no CD Audio issue on Windows if using a USB CD drive (SATA drives worked fine).
-
The strength of the tiny reverb preset has been reduced by 25% as it sounded too strong; now it simulates the natural reverberation of a domestic room better.
-
When using the PipeWire sound daemon on Linux, tools like pw-top, pavucontrol, or the KDE volume applet now show \u201cDOSBox Staging\u201d as the application\u2019s name instead of the generic \u201cSDL Application\u201d.
Full PR list of sound-related changes - Add a simple DC bias remover for the OPL output (#3310)
- Add support for ESS mixer registers (#3702)
- Decouple CMS and OPL emulations (#3559)
- ESFM emulation (#3614)
- Fix CD audio support on physical USB drives on Windows (#3840)
- Fix ESS mixer volume handling (#3705)
- Fix Ring Buffer PrevIndex() wrapping behavior for non power of 2 size (#3813)
- Fix Sound Blaster programmatic low-pass filter toggling behaviour (#3712)
- Fix SoundBlaster DMA stuttering in The Rocketeer (#3915)
- Fix data race on mixer volume change (#3923)
- Fix decrementing of MPU-401 track and conductor counters (#3766)
- Fix programmatic toggling of the Sound Blaster Pro 2 output filter (#3815)
- Fix the GUS reset register\u2019s startup behavior (#3755)
- Fix thread sanitizer warnings in threaded GUS code (#3919)
- Further mixer fixes and improvements mega PR #2 (#3756)
- Improve
sbtype and oplmode descriptions & clean up sblaster.cpp (#3566) - Improve tiny reverb preset for small-speaker emulation (#3867)
- Initialise the OPL operators per the AdLib v1.51 driver (#3772)
- Let GUS use its documented IRQ, DMA, and base addresses (#3960)
- Make the
impulse PC speaker model the default (#3851) - Map \u2018Capture MIDI action\u2019 to Ctrl+Alt+F6 (Cmd+Opt+F6) by default (#3714)
- Mirror the Adlib command port (388h) in the GUS (#3763)
- Move mixer to a seperate thread (#3848)
- Rework physical CDROM interface (#3591)
- Show the mixer who\u2019s boss \ud83d\ude0e (#3650)
- Sync Nuked-OPL3 with upstream (#3818)
- Various MT-32 improvements & fix Bumpy\u2019s Arcade Fantasy intro tune (#3729)
"},{"location":"releases/release-notes/0.82.0/#input","title":"Input","text":" -
Fix hang on exiting DOSBox Staging after pressing the Pause key.
-
General keyboard handling accuracy improvements, allowing us to get rid of the Ultima VIII game-specific hack.
Full PR list of input-related changes - Fix hang on exit after pressing the pause key (#3671)
- Fix mouse support in Descent II with a Voodoo patch (#3896)
- Remove special case for joystick axis 2 and 5 and add detection for gamepad trigger buttons (#3885)
- Replace Ultima VIII keyboard hack with a proper solution (#3784)
- Revert \u201cFix mouse support in Descent II with a Voodoo patch\u201d (#3903)
"},{"location":"releases/release-notes/0.82.0/#dos-integration","title":"DOS integration","text":""},{"location":"releases/release-notes/0.82.0/#new-mode-command","title":"New MODE command","text":"A new MODE command has been added to set the display mode of the DOS prompt and the keyboard\u2019s typematic rate. The command is loosely based on the original MS-DOS MODE command, but it supports a lot more display modes.
Examples of setting a custom text mode:
mode 80x30\nmode 80x43\nmode 132x34\n
Setting the fastest key repeat with the shortest repeat delay (everybody\u2019s favourite):
mode rate=32 delay=1\n
Run mode /? to see the full list of options.
"},{"location":"releases/release-notes/0.82.0/#file-sharing-support","title":"File sharing support","text":"Certain Windows 3.1x programs that rely on SHARE.EXE or VSHARE.386 would display an error on startup, complaining that SHARE.EXE has not been loaded. This mostly affects office programs (e.g., Microsoft Office, Lotus Office, Peachtree Complete Accounting, etc.), but also a few games.
The previous workaround was to rely on a small utility called FAKESHAR.COM which, as the name implies, fakes that SHARE.EXE is running. This worked mostly fine with games but could lead to data corruption when using application programs.
We\u2019ve added support for file sharing and locking, which means workarounds like FAKESHAR.COM are no longer necessary. All Windows 3.1x games that complain about SHARE.EXE not running should now work out-of-the-box. This fixes at least the following games:
- Comix Zone
- Garfield Caught in the Act
- Microsoft Flight Simulator (v5.0, ATC Workshop)
- Monopoly
- Ultimate Yahtzee
"},{"location":"releases/release-notes/0.82.0/#improved-physical-cd-rom-mounting","title":"Improved physical CD-ROM mounting","text":"Physical CD-ROM devices are now auto-detected when using the MOUNT command\u2014no more need to use the additional clunky -usecd parameter (this has been removed).
For example:
- Windows:
mount d d:\\ -t cdrom - Linux:
mount d /mnt/cdrom -t cdrom
"},{"location":"releases/release-notes/0.82.0/#other-dos-integration-improvements","title":"Other DOS integration improvements","text":" -
LOADFIX can now be used with batch files.
-
Fix improper handling of some special characters in shell history.
-
Improve redirection handling in the DOS shell. This helps with a few game installers (e.g., running the B-Wing Add-On installer for X-Wing corrupted the game files without this fix).
-
More accurate System File Table (SFT) emulation. This helps with some game compatibility issues, e.g. Dunkle Shatten 2 was freezing without this fix.
-
The DEBUG and XCOPY commands from FreeDOS have been updated to their latest versions.
-
The command shell now handles double quotes without preceding spaces similarly to real MS-DOS. For example, ECHO\" will now print an empty line and batch files that use squashed syntax, like IF\"%1\"==\"1\" GOTO adlib, will now also work.
-
The JEMM memory manager now works even with DOSBox Staging\u2019s VMware mouse emulated enabled (previuosly, JEMM could only be started with vmware_mouse = off). This is useful for games like 1942: The Pacific Air War which does not work correctly with Staging\u2019s emulated EMS memory.
Full PR list of DOS integration related changes - Add MODE command & various text mode improvements (#3741)
- Allow loadfix to execute batch files (#3657)
- Clean up some leaked file handles (#3673)
- Do not hard exit when running
SET /P (#3789) - Fix Reboot Handler crash (#3683)
- Fix Windows 3.1 regression from SFT change (#3744)
- Fix
IMGMOUNT command error message (#3863) - Fix broken shell_history_file config option (std::weak_ptr version) (#3664)
- Fix improper handling of some characters in shell history (#3791)
- Fix shell history creation regression (#3485)
- Fix shell redirection for appending to the end of a file (#3873)
- Handle double-quotes in the shell similar to real MS-DOS (#3924)
- Implement File Locking (#3687)
- Improve redirection handling in the DOS shell (#3838)
- Improve reset handler (#3696)
- Keep file handle instead of entry in FileReader (#3528)
- MODE command fixes & improvements (#3853)
- Move System File Table memory location (#3680)
- Move environment functions to psp (+ other small changes) (#3093)
- Replace use of
stat in imgmount (#3465) - The great DOS_File/DOS_Drive Refactor (plus some timestamp improvements) (#3786)
- Update bundled FreeDOS binaries (#3876)
- Use native file I/O in local and overlay drive (#3765)
- Use wrapping behavior on localFile seek position (#3779)
"},{"location":"releases/release-notes/0.82.0/#general","title":"General","text":""},{"location":"releases/release-notes/0.82.0/#pentium-mmx-emulation","title":"Pentium MMX emulation","text":"Finally, we\u2019ve added Pentium MMX instruction set emulation to run late-90s demoscene productions (e.g., heaven seven by Exceed) and the odd game with MMX-specific enhancements (e.g., Extreme Assault and Z.A.R.). And yeah, now you can use the MMX-only real-time resonant filters in Impulse Tracker, too
You must enable MMX emulation explicitly by setting cputype = pentium_mmx in your config. All normal and dynamic cores are supported on all platforms.
"},{"location":"releases/release-notes/0.82.0/#simplified-cpu-cycles-settings","title":"Simplified CPU cycles settings","text":"The cycles setting has been a source of a lot of confusion, so we\u2019ve replaced it with a much simpler way to configure the emulated CPU speed (believe it or not, there are over 20 valid cycles value permutations!)
The new streamlined CPU cycles settings are as follows:
cpu_cycles \u2014 Global or real mode only cycles setting.cpu_cycles_protected \u2014 Optional protected mode only cycles setting.cpu_throttle \u2014 Whether the CPU emulation should be dynamically throttled if your host CPU cannot keep up.
Please refer to the settings\u2019 descriptions to learn more (e.g., run config -h cpu_cycles from the DOS prompt).
Here are a few concrete examples:
Set fixed speed globally
This will roughly emulate the speed of the venerable i486DX2-66 in both real and protected mode. cpu_cycles_protected = auto means cpu_cycles controls the emulated CPU speed globally, both for real and protected mode.
[cpu]\ncpu_cycles = 25000\ncpu_cycles_protected = auto\n
Different real and protected mode speeds with throttling
20k cycles for real mode programs, and 400k for protected mode. Throttling is enabled, so if your host machine can\u2019t keep up, the actual number of emulated CPU cycles per millisecond will be dynamically lowered.
[cpu]\ncpu_cycles = 20000\ncpu_cycles_protected = 400000\ncpu_throttle = on\n
Max speed
This will make the CPU emulation run as fast as your computer can handle it. Pretty useful when compiling programs, rendering 3D images, or playing late \u201990s 3D games at 640\u00d7480 or higher resolutions (as long as they can run glitch-free on very fast CPUs).
[cpu]\ncpu_cycles = max\ncpu_cycles_protected = max\n
Backward compatibility with cycles
The legacy cycles setting is still available for backward compatibility with existing configs. When cycles is set, the new CPU settings are simply ignored. Do note, however, that we might remove support for cycles in the future; please start migrating your configs to the new settings now.
"},{"location":"releases/release-notes/0.82.0/#revised-cpu-cycles-defaults","title":"Revised CPU cycles defaults","text":"Summary of changes
-
The default emulated CPU speed (cycles) setting for protected mode programs has been changed from max to 60\u2009000 cycles.
-
The real mode default of 3000 cycles is unchanged.
-
When \u201clegacy cycles mode\u201d is enabled by setting cycles explicitly, the old \u201cmax cycles\u201d protected mode default applies.
DOSBox traditionally defaulted to 3000 cycles for real mode programs, and \u201cmax cycles\u201d (as fast as your host CPU can go) for protected mode programs. 3000 cycles for real mode is a good middle-of-the-road setting that gets most games running (even if not optimally). The \u201cmax cycles\u201d setting, on the other hand, is quite problematic for a couple of reasons:
-
A significant number of games crash, misbehave, or manifest subtle bugs when the emulated CPU is \u201ctoo fast\u201d. In the early days of DOSBox, cycles = max was not a problem because the much slower host CPUs from 10-20 years ago acted as a \u201cnatural throttle\u201d on the effective emulation speed. However, many of those old speed-sensitive games that used to work with cycles = max are now broken on today\u2019s fast CPUs.
-
The max setting is not transferable across setups as it depends on the host CPU\u2019s speed. Games configured for cycles = max might work fine on your particular machine, but they could break on your friend\u2019s faster computer or yours a few years later when you get your next CPU upgrade. The max N% cycles setting (e.g., max 70%) is plagued by the same problem.
-
cycles = max often causes audio glitches and drop-outs in games. It\u2019s best to use the lowest fixed cycles value that runs the game at an acceptable speed (read more tips about that here).
-
Some DOS programs really freak out when the emulated CPU is being dynamically changed at runtime, which is what max tends to do.
All in all, max for protected mode is not a good default in 2024, so we\u2019ve changed it to fixed 60\u2009000 cycles, which is roughly equivalent to slow Pentium speeds. As protected mode games started appearing in the early to mid-90s, this should run the vast majority of games fairly optimally out-of-the-box.
"},{"location":"releases/release-notes/0.82.0/#cputype-normalisation","title":"\u2018cputype\u2019 normalisation","text":"After introducing the pentium_mmx CPU type, we felt the need to clean up the cputype options a bit and make them more logical:
386_slow has been renamed to 386386 has been renamed to 386_fast486_slow has been renamed to 486pentium_slow has been renamed to pentium
Please refer to the description of the cputype setting for further info (e.g., execute config -h cputype from the DOS prompt).
The descriptions of all CPU settings have been extensively revised and now include helpful hints, so it\u2019s recommended that you familiarise yourself with them (run config -h cpu to see the complete list of CPU settings).
Warning
The old renamed cputype values are still accepted with a deprecation warning, but you should update your configs to use the new values, as we might remove support for the legacy settings in the future.
"},{"location":"releases/release-notes/0.82.0/#improved-config-command","title":"Improved CONFIG command","text":"The CONFIG command\u2019s output is now paginated when you use it to display a config setting\u2019s description (e.g., config -h glshader of config -h cpu_cycles). Previously you had to pipe the output through the MORE command to paginate the output, which was a hassle (i.e., config -h glshader | more).
The formatting and colouring of the CONFIG command\u2019s output has also been improved.
"},{"location":"releases/release-notes/0.82.0/#configurable-window-title-bar","title":"Configurable window title bar","text":"You can now fully customise the information displayed in the emulator window\u2019s title bar.
For example, this configuration
[sdl]\nwindow_titlebar = program=none version=detailed mouse=short\n
yields the following to be displayed in the title bar:
DOSBox Staging 0.82.0-alpha (9fdba) - 3000 cycles/ms\n
An animated audio/video capturing indicator and a pause indicator has also been added.
Please refer to the window_titlebar setting\u2019s description to learn about the available options (e.g., run config -h window_titlebar from the DOS prompt).
"},{"location":"releases/release-notes/0.82.0/#read-only-directory-mounts","title":"Read-only directory mounts","text":"The MOUNT command now accepts the -ro flag to create read-only (write-protected) directory mounts (the IMGMOUNT command already had this option).
For auto-mounts, you can specify readonly = true in the [drive] section of the mount config file (see resources).
Additionally, the built-in Y drive has been made read-only by default (you can change this in resources/drives/y.conf, of course, if you want to).
"},{"location":"releases/release-notes/0.82.0/#experimental-windows-arm64-builds","title":"Experimental Windows ARM64 builds","text":"We\u2019re ready for the ARM revolution!
Luckily, we already have a battle-tested dynamic ARM recompiler that we\u2019ve been using for the Apple Silicon macOS builds, so we started providing experimental Windows ARM64 packages for devices such as the Snapdragon X Elite.
The ARM64 packages can be downloaded from our development builds page (requires a GitHub account).
We don\u2019t provide any official support for the experimental Windows ARM64 builds yet.
"},{"location":"releases/release-notes/0.82.0/#other-general-improvements","title":"Other general improvements","text":" -
The IPX server has been moved into its own dedicated thread. This should improve multi-player game performance, especially for the host running the IPX server.
-
The IBM Extended Density Format (XDF) was used by IBM for software distribution on 5.25\u201d and 3.5\u201d media. XDF image files were often provided by IBM on CD-ROMs, bulletin boards, and FTP sites.
-
A more realistic implementation of the Time Stamp Counter (TSC) found on Pentium and later CPUs, often used to determine the CPU clock. Now various benchmark software should display more realistic CPU speeds (e.g., HWINFO and SiSoft Sandra). Games don\u2019t seem to be affected by this improvement.
-
Software-initiated reset requests now restart the emulator instead of crashing it. The reset message has been improved and now includes a countdown counter.
Full PR list of miscellaneous enhancements - Add IBM XDF floppy support (#3442)
- Add carry, sign, zero, and parity flags to integer division instructions (#3785)
CONFIG command enhancements (#3667)- Config setting improvements and
CONFIG command fixes (#3754) - Implement read-only mounting + make Y drive read-only by default (#3711)
- Improve the
core and cputype setting descriptions (#3708) - Improve title bar and make it configurable (#3249)
- Integrate MMX emulation (#3426)
- Introduce a better way to set the CPU cycles with new defaults (#3681)
- Make the Time Stamp Counter more realistic (#3471)
- Move IPX server to a background thread (#3414)
- Paginate the CONFIG command\u2019s output (#3758)
- Prevent JEMM memory manager from detecting the VMware interface (#3925)
- Provide application name to SDL (#3926)
- Show memory read breakpoint with BPLIST (#3396)
Full PR list of miscellaneous fixes - Add DOS Files to shutdown step to avoid a crash when shutting down (#3801)
- Allow running the
INTRO built-in from subshells (#3665) - Avoid unnecessary new-lines (#3617)
CONFIG -h should only list visible setting values (#3753)- Fix division regression by resetting flag type (#3795)
- Fix \u2018output\u2019 and other \u2018sdl\u2019 settings not changeable in runtime (#3571)
- Fix IPX ping value display (#3418)
- Fix MMX crash on moralhardcandy (#3814)
- Fix Windows 3.1 regression from SFT change (#3744)
- Fix byte calculation overflow using pages per MB (#3942)
- Fix file open error in ISO Drive (#3804)
- Fix switch to dynamic core warning edge case (#3732)
- Fix warning when using a high cycles value on a non-dynamic core (#3716)
- Follow-up fix for Debian package on
main push (#3930) - Make parameter addresses properly sized in ppc64le dynrec (fixes #3686) (#3718)
- Use CreateFileW on Windows to create file in local_drive_create_file() (#3746)
Full PR list of documentation-related changes - Add bisecting notes to build documentation (#3816)
- Add comment about PPC64 big-endian and running 32-bit BE code (#3827)
- Add warning about CMake support being experimental (#3790)
- Clarify build instructions for low memory targets (#3658)
- Create .clang-tidy (#3423)
- Improve the GUS config setting descriptions (#3862)
- Remove -usecd and -listcd MOUNT parameters from INTRO and the README (#3625)
- Simple documentation fixes (#3782)
- Update Windows build guide (#3424)
- website: Add NixOS install instructions (#3479)
Full PR list of project maintenance related changes - Add Debian package build scripts and workflow (#3809)
- Advance vcpkg baseline to upgrade to SDL 2.30.0 (#3606)
- Allow SDL wraps to be bypassed on macOS (#3483)
- Audio cleanups (#3615)
- Avoid the use of std::string_view::data() (#3542)
- Basic CMake support (#3361)
- Bump Coverity build from Clang 14 to Clang 15 (#3419)
- Bump PVS Studio CI from Clang 14 to Clang 15 (#3437)
- Bump vcpkg baseline and update to upstream libslirp v4.8.0 (#3761)
- Callback code generation rework (#3748)
- Centralize app_id handling (continuation) (#3854)
- Change ppc64 to use correct
POWERPC target (#3826) - Clean up macOS notarization script (#3408)
- Cleanup a few warnings in cdrom_image.cpp (#3472)
- Cleanup of using namespace (#3444)
- Cleanup some missed C++ header conversions (#3412)
- Create new cross compiler docker images and adjust workflows (#3678)
- DYN_LOG: Fix formatting type mismatch (#3869)
- Do not auto-run DOSBox Staging after installing it on Windows (#3583)
- Eliminate excessive repeat heap calls during normal runtime (#3812)
- Enable SDL atomic subsystem in Meson wrap (#3934)
- Fix \u2018launchable\u2019 in the Flathub metainfo.xml file (#3933)
- Fix CDROM_Interface pointer ownership issue (#3634)
- Fix MSVC CI builds (#3474)
- Fix compilation warnings reported by g++ 14.1 (#3783)
- Fix data race in the mapper when using
autotype (#3928) - Fix issue with replace() (#3533)
- Fix macOS CI workflow (#3505)
- Fix sed creating backup files ending with \u201c-e\u201d in macOS bundle (#3406)
- Fix some PVS warnings (#3484)
- Fix variables optimizing away when debugging MSClang builds (#3397)
- Fix vcredist version for MSVC CI runner (#3480)
- Handle SDL2 like the other dependencies (#3864)
- Ignore meson.build in VS tests project (#3422)
- Introduce custom release notes drafter script & workflow (#3398)
- Make GCC 11 / Ubuntu 22.04 the minimum build target (#3674)
- Mass update copyright dates (#3584)
- Migrate to C++20 (#3286)
- Minor FPU cleanup (#3837)
- More PVS warning fixes (#3494)
- Move environment functions to psp (+ other small changes) (#3093)
- Pin CMake version for MSVC runner (#3598)
- Reinstate creating the Windows installer package in CI (#3849)
- Release drafter enhancements (#3546)
- Remove Debian 10 support (#3534)
- Remove GCC_LIKELY/GCC_UNLIKELY (#3293)
- Search for numbered clang-format binaries in format-commit.sh (#3747)
- Unicode API refactoring (#3797)
- Unify use of prop->Set_values (#3572)
- Update SDL wrap to 2.30.6 (#3856)
- Update simde to 0.8.0 (#3522)
- Update string_utils to use C++20 constructs (#3540)
- Upgrade SIMDE to 0.8.2 (#3662)
- Upgrade Windows CI setup-msbuild GitHub action (#3477)
- Usage of integer types & disabling sign conversion warnings (#3631)
- Use C++ system headers (#3284)
- Use GitHub actions cache for vcpkg (#3503)
- Use GitHub runners for macOS builds (#3384)
- Use inline memory routines for MMX (#3847)
- Use std::atomic for CaptureState enum (#3931)
Full PR list of other changes - Allow the PVS-Studio workflow run in forked PRs (#3493)
- Build Windows package for the ARM64 platform (#3823)
- Don\u2019t execute compile workflows on documentation and script changes (#3393)
- Fix CI to create Debian package on
main push (#3929) - Fix fs_utils_tests for macOS and enable test runs on macOS CI (#3622)
- Fix msys2 compilation error with cdrom_win32.cpp (#3676)
- Include DEBUG.COM license in the packages (#3897)
- Introduce unittests for the Value class (#3369)
- Minor fix to x87 64-bit memcpy (#3866)
- Remove hard-coded version string from MSVC CI (#3736)
- Upgrade deprecated Node.js 16 GitHub actions to latest (#3457)
"},{"location":"releases/release-notes/0.82.0/#localisation","title":"Localisation","text":" - Update Dutch, Italian, Polish, Portugese, and Spanish translations.
- Use uncompressed CPI code page files instead of the compressed FreeDOS-specific CPX format. This improves code page switching performance, which was rather slow with low
cpu_cycles settings. - Ensure all platform-specific translatable strings are visible to the translators.
Full PR list of localisation-related changes - Avoid false positive warnings in translations (#3610)
- Ensure logs are UTF-8 on Windows, improve deprecated config warning log (#3893)
- Further refinements to the Italian (it) translation (#3880)
- Improve italian (it) translation (#3877)
- Make the titlebar cycles display translatable again (#3890)
- Translations differ between platforms (#3579)
- Update Dutch (nl) translation (#3874)
- Update German (de) translation (#3888)
- Update Italian (it) translation (#3871)
- Update Polish (pl) translation (#3870)
- Update Polish (pl) translation (#3944)
- Update Polish (pl) translation, minor help string fix (#3850)
- Update Polish (pl) translation, minor string fixes (#3684)
- Update Portuguese Translation (#3609)
- Update Spanish translation (#3624)
- Update italian (it) translation (#3751)
- Use uncompressed CPI files instead of compressed CPX ones (#3413)
"},{"location":"releases/release-notes/0.82.0/#contributors","title":"Contributors","text":"The following commit authors, sponsors, supporters, and backers all invested their time or funds into the 0.82 release effort. Thank you!
Contributors are listed in alphabetic order.
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":"releases/release-notes/0.82.0/#082-commit-authors","title":"0.82 commit authors","text":" - altiereslima
- Arcnor
- bluddy
- Burrito78
- classilla
- dreamer
- farsil
- FeralChild64
- ftortoriello
- Grounded0
- interloper98
- japsmits
- johnnovak
- Kappa971
- kcgen
- keenanweaver
- kklobe
- LowLevelMahn
- MeAreJeenius
- rderooy
- Ringdingcoder
- shermp
- stackErr-NameNotResolved
- strikersix23
- Torinde
- weirddan455
"},{"location":"releases/release-notes/0.82.0/#082-sponsors","title":"0.82 sponsors","text":""},{"location":"releases/release-notes/0.82.0/#082-supporters","title":"0.82 supporters","text":""},{"location":"releases/release-notes/0.82.0/#082-backers","title":"0.82 backers","text":" - BenBudr
- Burrito78
- Diduz
- Florent Wagner
- Hannu Hartikainen
- Hugo Lucorcio
- Robin Mattheussen
"},{"location":"releases/release-notes/0.82.0/#thank-you","title":"Thank you","text":"We are grateful for all the community contributions and the original DOSBox project, on which DOSBox Staging is based.
"}]}
\ No newline at end of file
diff --git a/preview/dev/sitemap.xml b/preview/dev/sitemap.xml
index 431d9e8..c7c0ba4 100644
--- a/preview/dev/sitemap.xml
+++ b/preview/dev/sitemap.xml
@@ -2,142 +2,142 @@
https://www.dosbox-staging.org/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/about/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/get-involved/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/get-involved/code-of-conduct/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/getting-started/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/getting-started/advanced-graphics-options/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/getting-started/beneath-a-steel-sky/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/getting-started/enhancing-prince-of-persia/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/getting-started/introduction/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/getting-started/next-steps/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/getting-started/passport-to-adventure/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/getting-started/setting-up-prince-of-persia/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/getting-started/star-wars-dark-forces/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/development-builds/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/linux/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/macos/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/windows/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.75.0-rc1/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.75.0/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.75.1/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.75.2/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.76.0/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.77.0/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.77.1/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.78.0/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.78.1/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.79.0/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.79.1/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.80.0/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.80.1/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.81.0/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.81.1/
- 2024-09-25
+ 2024-09-28
https://www.dosbox-staging.org/releases/release-notes/0.81.2/
- 2024-09-25
+ 2024-09-28
- https://www.dosbox-staging.org/releases/release-notes/0.82.0-rc/
- 2024-09-25
+ https://www.dosbox-staging.org/releases/release-notes/0.82.0/
+ 2024-09-28
\ No newline at end of file
diff --git a/preview/dev/sitemap.xml.gz b/preview/dev/sitemap.xml.gz
index 77f6719..9c479b2 100644
Binary files a/preview/dev/sitemap.xml.gz and b/preview/dev/sitemap.xml.gz differ
- Also, by setting custom sample rates, you can capture audio at an emulated
- device’s native rate without resampling.
-