2.3.4
- the minimum required JDK version has been raised to 21
- the embedded JDK has been updated to 23.0.1+13
- upgraded the JInput library to 2.0.10
- refactoring, fixes in Z80 CPU emulation
DosBox Staging
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.confmacOS
~/Library/Preferences/DOSBox/dosbox-staging.confLinux
~/.config/dosbox/dosbox-staging.confYou can also execute DOSBox Staging with the
--printconfoption 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.confwill be written containing the new defaults and updated setting descriptions.Portable mode notes
In portable mode,
dosbox-staging.confresides 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.conffile in the new folder to enable portable mode.- Launch the new version.
DOSBox Staging will write the new defaults to the empty
dosbox-staging.conffile. 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
openglnboutput 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,
openglnbandopenglworked exactly the same way—there was zero reason for preferringopenglnboveropengl.The only legitimate use-case for
openglnbwas 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 thesharpshader.If you really want to, you can still use nearest-neighbour interpolation with the new
nearestshader. But you’ll get far better results withsharp, especially on 1080p displays.The
texturenboutput 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-3dscaler/xbr-lv2-noblendscaler/xbr-lv3Voodoo 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 = esfmwith any Sound Blaster model and configure the game for Sound Blaster and AdLib/OPL as usual.- To use “native mode”, set
sbtype = essand 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.MIDdriver 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_biasconfig 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 500Default to the ‘impulse’ PC speaker model¶
The
impulsePC 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
discretemodel 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 = opl2always 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:
oplmodeonly determines the type of OPL chip(s) to emulate. Valid values arenone,opl2,dualopl2,opl3, andopl3gold.- The new
cmsconfig setting in the[sblaster]section controls whether to emulate the CMS. Valid values areonandoff.Warning
As usual,
oplmode = cmsis 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 withsb_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!
blocksizecan now be set to non-power-of-two values, too.- The
nosoundoption 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 viaULTRAMID.EXEorMEGAEM.EXEin 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
tinyreverb 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
Input¶
- 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
MODEcommand 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-DOSMODEcommand, but it supports a lot more display modes.Examples of setting a custom text mode:
mode 80x30 mode 80x43 mode 132x34Setting the fastest key repeat with the shortest repeat delay (everybody’s favourite):
mode rate=32 delay=1Run
mode /?to see the full list of options.File sharing support¶
Certain Windows 3.1x programs that rely on
SHARE.EXEorVSHARE.386would display an error on startup, complaining thatSHARE.EXEhas 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.COMwhich, as the name implies, fakes thatSHARE.EXEis 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 like
FAKESHAR.COMare no longer necessary. All Windows 3.1x games that complain aboutSHARE.EXEnot 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
MOUNTcommand—no more need to use the additional clunky-usecdparameter (this has been removed).For example:
- Windows:
mount d d:\ -t cdrom- Linux:
mount d /mnt/cdrom -t cdromOther DOS integration improvements¶
LOADFIXcan 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
DEBUGandXCOPYcommands 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_mmxin your config. All normal and dynamic cores are supported on all platforms.Simplified CPU cycles settings¶
The
cyclessetting 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 validcyclesvalue 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_cyclesfrom 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 = automeanscpu_cyclescontrols the emulated CPU speed globally, both for real and protected mode.
[cpu] cpu_cycles = 25000 cpu_cycles_protected = autoDifferent 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 = onMax 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 = maxBackward compatibility with
cyclesThe legacy
cyclessetting is still available for backward compatibility with existing configs. Whencyclesis set, the new CPU settings are simply ignored. Do note, however, that we might remove support forcyclesin 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
cyclesexplicitly, 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 = maxwas 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 withcycles = maxare now broken on today’s fast CPUs.- The
maxsetting is not transferable across setups as it depends on the host CPU’s speed. Games configured forcycles = maxmight 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. Themax N%cycles setting (e.g.,max 70%) is plagued by the same problem.cycles = maxoften 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
maxtends to do.All in all,
maxfor 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_mmxCPU type, we felt the need to clean up thecputypeoptions a bit and make them more logical:
386_slowhas been renamed to386386has been renamed to386_fast486_slowhas been renamed to486pentium_slowhas been renamed topentiumPlease refer to the description of the
cputypesetting for further info (e.g., executeconfig -h cputypefrom 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 cputo see the complete list of CPU settings).Warning
The old renamed
cputypevalues 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
CONFIGcommand’s output is now paginated when you use it to display a config setting’s description (e.g.,config -h glshaderofconfig -h cpu_cycles). Previously you had to pipe the output through theMOREcommand to paginate the output, which was a hassle (i.e.,config -h glshader | more).The formatting and colouring of the
CONFIGcommand’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=shortyields the following to be displayed in the title bar:
DOSBox Staging 0.82.0-alpha (9fdba) - 3000 cycles/msAn animated audio/video capturing indicator and a pause indicator has also been added.
Please refer to the
window_titlebarsetting’s description to learn about the available options (e.g., runconfig -h window_titlebarfrom the DOS prompt).Read-only directory mounts¶
The
MOUNTcommand now accepts the-roflag to create read-only (write-protected) directory mounts (theIMGMOUNTcommand already had this option).For auto-mounts, you can specify
readonly = truein the[drive]section of the mount config file (see resources).Additionally, the built-in
Ydrive has been made read-only by default (you can change this inresources/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_cyclessettings.- 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 sponsors¶
- Antti Peltola
0.82 supporters¶
- Wengier Wu
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.
![Icône de Virtual ][](/sites/default/files/styles/hauteur_80px/public/2024-02/virtualii.png?itok=C-4mxvXR)
