0.82.0
Summary¶
Just six short months after our monstre 0.81.0 release, we’re 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!
Downloads¶
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.
How to upgrade¶
Upgrading your primary configuration¶
Since config settings might be renamed, altered, or deprecated between releases, it’s 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—a 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.
After upgrading¶
Look for deprecation warnings in the logs (in yellow or orange colour) and update your configs accordingly.
Game compatibility fixes¶
- 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’s 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
Graphics¶
Remove the ‘openglnb’ output mode¶
The openglnb
output mode for OpenGL with nearest-neighbour interpolation has been removed (nb stood for “no bilinear”, which is a roundabout way to say “nearest-neighbour interpolation”).
When using CRT shaders or any other shader, openglnb
and opengl
worked exactly the same way—there 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 “no bilinear” interpolation). The much better current solution in DOSBox Staging if you want the “sharp pixel” 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’ll 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.
New xBR upscaler shaders¶
A few of Hyllian’s xBR upscaling shaders have been added for those hell-bent on playing games with a fake high-resolution look:
scaler/xbr-lv2-3d
scaler/xbr-lv2-noblend
scaler/xbr-lv3
Voodoo fixes¶
16-bit memory writes have been fixed in our Voodoo emulation; this resolves the distorted HUD issue in the 3dfx version of Archimedean Dynasty.
S3 Trio64 improvements¶
- Fixed the hardware cursor handling on the S3 Trio64 card; this fixes the display corruption on exit issue in the Teddybear’s 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 — Daemons of the Mind
- Perfect Assassin
Full PR list of graphics-related changes
Sound¶
Multi-threaded audio processing¶
Some audio devices, such as the MT-32 and FluidSynth, were already running in their own threads. We’ve 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×200 and 640×480 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.
ESS Enhanced FM Audio (ESFM) emulation¶
DOS audio connoisseurs, we have a real treat for you! We’ve added support for emulating ESS Enhanced FM Audio, or ESFM, the OPL3-compatible FM synth found on later ESS AudioDrive cards.
In “legacy mode”, 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 “native mode”, 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—it definitely makes those expensive external MIDI modules run for their money!
Unfortunately, since ESFM was released in 1995, only a handful of games support “native mode,” but in the few that do, the results sound quite spectacular!
- To run ESFM in “legacy mode”, use
oplmode = esfm
with any Sound Blaster model and configure the game for Sound Blaster and AdLib/OPL as usual. - To use “native mode”, set
sbtype = ess
and configure the ESS Technology ES1688, ES1788, ES1888 Enhanced FM Audio MIDI music driver in the game’s 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’s 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’s Crosstime Saloon
- Gene Machine, The
- Heaven’s Dawn
- Heroes of Might and Magic II
- Magic Carpet 2
- Settlers II, The
- Shannara
- Theme Hospital
- WarCraft II
- Z
GameAudio example
Heroes of Might and Magic II — Title (ESFM)
Heroes of Might and Magic II — Title (OPL)
Heroes of Might and Magic II — In-game (ESFM)
Heroes of Might and Magic II — In-game (OPL)
The Settlers 2 — Track 5 (ESFM)
The Settlers 2 — Track 5 (OPL)
The Settlers 2 — Track 14 (ESFM)
The Settlers 2 — Track 14 (OPL)
The Gene Machine (ESFM)
The Gene Machine (OPL)
Heaven’s Dawn (ESFM)
Heaven’s Dawn (OPL)
The more adventurous among you can also try to “retrofit” the ESFM.MID
driver from Miles Sound System games that have it into earlier ones that don’t.
Here’s how Discworld sounds with the ESFM driver from Heaven’s Dawn—it’s pretty great, sounds almost like sample-based music!
Discworld (ESFM)
Discworld (OPL)
AdLib/OPL DC bias remover¶
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’ve 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]
sbtype = none
oplmode = opl2
opl_remove_dc_bias = true
opl_filter = lpf 2 5500
[speaker]
pcspeaker = off
[autoexec]
mixer opl 500
Default to the ‘impulse’ PC speaker model¶
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.
Decouple CMS and AdLib/OPL emulation¶
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 “just another OPL option”, 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.
Sound Blaster Pro 2 output filter fix¶
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
.
AdLib/OPL improvements¶
The OPL (AdLib) chip is now initialised with the official AdLib v1.51 driver’s startup values instead of the chip’s native power-on state. Most games don’t 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
Further mixer improvements¶
- Fix lower-pitched audio bug when the emulated audio device’s sample rate exceeds the host sample rate. E.g., if a program uses the maximum native 45 454 Hz Sound Blaster rate and the host rate is 44 100 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’s 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 “no sound” mode; previously, it was completely stalled). Additionally, you can now capture the audio to a WAV file even in “no sound” mode.
Other audio improvements¶
- 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 “cable delay” emulation MIDI for the MT-32. This fixes the intro tune in Bumpy’s 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 “nice” partials mode and render at libmt32’s 48 kHz “analog emulation” 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
- 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
DOS integration¶
New MODE command¶
A new MODE
command has been added to set the display mode of the DOS prompt and the keyboard’s 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
mode 80x43
mode 132x34
Setting the fastest key repeat with the shortest repeat delay (everybody’s favourite):
mode rate=32 delay=1
Run mode /?
to see the full list of options.
File sharing support¶
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’ve added support for file sharing and locking, which means workarounds likeFAKESHAR.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
Improved physical CD-ROM mounting¶
Physical CD-ROM devices are now auto-detected when using the MOUNT
command—no 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
Other DOS integration improvements¶
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
General¶
Pentium MMX emulation¶
Finally, we’ve 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.
Simplified CPU cycles settings¶
The cycles
setting has been a source of a lot of confusion, so we’ve 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
— Global or real mode only cycles setting.cpu_cycles_protected
— Optional protected mode only cycles setting.cpu_throttle
— Whether the CPU emulation should be dynamically throttled if your host CPU cannot keep up.
Please refer to the settings’ 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]
cpu_cycles = 25000
cpu_cycles_protected = auto
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’t keep up, the actual number of emulated CPU cycles per millisecond will be dynamically lowered.
[cpu]
cpu_cycles = 20000
cpu_cycles_protected = 400000
cpu_throttle = on
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 ’90s 3D games at 640×480 or higher resolutions (as long as they can run glitch-free on very fast CPUs).
[cpu]
cpu_cycles = max
cpu_cycles_protected = max
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.
Revised CPU cycles defaults¶
Summary of changes
- The default emulated CPU speed (cycles) setting for protected mode programs has been changed from max to 60 000 cycles.
- The real mode default of 3000 cycles is unchanged.
- When “legacy cycles mode” is enabled by setting
cycles
explicitly, the old “max cycles” protected mode default applies.
DOSBox traditionally defaulted to 3000 cycles for real mode programs, and “max cycles” (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 “max cycles” 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 “too fast”. 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 “natural throttle” 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’s fast CPUs. - The
max
setting is not transferable across setups as it depends on the host CPU’s speed. Games configured for cycles = max
might work fine on your particular machine, but they could break on your friend’s 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’s 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’ve changed it to fixed 60 000 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.
‘cputype’ normalisation¶
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 386
386
has been renamed to 386_fast
486_slow
has been renamed to 486
pentium_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’s 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.
Improved CONFIG command¶
The CONFIG
command’s output is now paginated when you use it to display a config setting’s 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’s output has also been improved.
Configurable window title bar¶
You can now fully customise the information displayed in the emulator window’s title bar.
For example, this configuration
[sdl]
window_titlebar = program=none version=detailed mouse=short
yields the following to be displayed in the title bar:
DOSBox Staging 0.82.0-alpha (9fdba) - 3000 cycles/ms
An animated audio/video capturing indicator and a pause indicator has also been added.
Please refer to the window_titlebar
setting’s description to learn about the available options (e.g., run config -h window_titlebar
from the DOS prompt).
Read-only directory mounts¶
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).
Experimental Windows ARM64 builds¶
We’re ready for the ARM revolution!
Luckily, we already have a battle-tested dynamic ARM recompiler that we’ve 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’t provide any official support for the experimental Windows ARM64 builds yet.
Other general improvements¶
- 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” and 3.5” 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’t 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 enhancementsFull PR list of miscellaneous fixesFull PR list of documentation-related changesFull PR list of project maintenance related changesFull PR list of other changes
Localisation¶
- 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
Contributors¶
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 orOpen Collective. Your contribution helps us purchase the necessary hardware and licenses to keep our project going.
0.82 commit authors¶
- 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
0.82 supporters¶
0.82 backers¶
- BenBudr
- Burrito78
- Diduz
- Florent Wagner
- Hannu Hartikainen
- Hugo Lucorcio
- Robin Mattheussen
Thank you¶
We are grateful for all the community contributions and the original DOSBox project, on which DOSBox Staging is based.