An Emscripten port of DOSBox
See the codeDOSBox is an open source DOS emulator designed for running games. Emscripten compiles code to JavaScript and WebAssembly. This is a version of DOSBox which can be compiled with Emscripten to run in a web browser. It allows running old DOS games and other DOS programs in a web browser.
DOSBox is distributed under the GNU General Public License. See the COPYING file for more information.
Em-DOSBox runs most games successfully in web browsers. Although DOSBox has not been fully re-structured for running as an Emscripten main loop, most functionality is available thanks to Emscripten Asyncify. A few programs can still run into problems due to paging exceptions.
--enable-funarray
configure option controls this and defaults to yes.file:// URLs.
Use a web server such as python -m http.server instead.This code retains the ability to build a normal version of DOSBox, for running as an ordinary computer application. These instructions are focused on how to build using Emscripten, for running in a web browser.
Use the latest stable version of Emscripten. For more information see the the Emscripten installation instructions. Em-DOSBox depends on bug fixes and new features found in recent versions of Emscripten. Some Linux distributions have packages with old versions, which should not be used.
First, create ./configure by running ./autogen.sh. Then
configure with emconfigure ./configure and build with make.
DOSBox will be contained in src/dosbox.js, and if WebAssembly is enabled
(the default), src/dosbox.wasm. Also, src/dosbox.html will be created,
which is a simple web page that provides an interface to DOSBox. You can
customize it or use DOSBox in your own web page. If you built with Asyncify
enabled (the default), you can open src/dosbox.html via a web server, and
run DOSBox. Without Asyncify DOSBox won't work like that, and you need to add
files to run. See below for information on "Running DOS Programs".
This branch supports SDL 2 and uses it by default. Emscripten will
automatically fetch SDL 2 from Emscripten Ports and build it. Use of make -j
to speed up compilation by running multiple Emscripten processes in parallel
may break this.
Once SDL 2 has been built by Emscripten, you can use make -j.
To use a different pre-built copy of Emscripten SDL 2, specify a path as in
emconfigure ./configure --with-sdl2=/path/to/SDL-emscripten.
To use SDL 1, give a --with-sdl2=no or --without-sdl2 argument to
./configure. There will be more problems, like some keys not working and the
mapper not displaying. Emscripten's SDL 2 is better.
Emscripten Asyncify is used by default. This enables more DOSBox features to work, and only causes a very small performance penalty.
If building with Emscripten versions between 1.29.4 and 1.39.17, you could
try using Emterpreter Sync instead of Asyncify. This is depreciated, worse
than Asyncify and not recommended. Such builds create a memory initialization
file src/dosbox.html.mem needs to be in the same folder as dosbox.js. The
memory initialization file is large. Serve it in compressed format to save
bandwidth.
When compiled using Asyncify, you can interactively load files. In DOSBox,
first use mount c: / and c: commands to provide a space for new files.
Then use the wget command to retrieve files from the same web server.
You can use relative URLs, simply providing file names to load files from
the same directory as the HTML page.
If not using Asyncify, or generally, for convenience, you can create web pages which run particular games. Such a page needs to load files into the Emscripten file system and give command line arguments to DOSBox. The simplest method is by using the included packager tools.
The normal packager tool is src/packager.py, which runs the Emscripten
packager. It requires dosbox.html, which is created when building Em-DOSBox.
If you do not have Emscripten installed, you need to use src/repackager.py
instead. Any packager or repackager HTML output file can be used as a template
for the repackager. Name it template.html and put it in the same directory
as repackager.py.
The following instructions assume use of the normal packager. If using
repackager, replace packager.py with repackager.py. You need
Python 3 to run either packager.
If you have a single DOS executable such as Gwbasic.exe, place
it in the same src directory as packager.py and package it using:
./packager.py gwbasic Gwbasic.exe
This creates gwbasic.html and gwbasic.data. Placing those in the same
directory as dosbox.js and viewing gwbasic.html will run the program in a
web browser:
Most browsers prevent access to the required
data files while using file:// URLs. To get around this you can use Python's
built in HTTP server and point the browser to
http://localhost:8000.
python -m http.server 8000
If you need to package a collection of DOS files. Place all the files in a
single directory and package that directory with the executable specified. For
example, if Major Stryker's files are in the subdirectory src/major_stryker
and it's launched using STRYKER.EXE you would package it using:
./packager.py stryker major_stryker STRYKER.EXE
Again, place the created stryker.html and stryker.data files in the same
directory as dosbox.js and view stryker.html to run the game in browser.
You can also include a DOSBox
configuration file that will be
acknowledged by the emulator to modify any speed, audio or graphic settings.
Simply include a dosbox.conf text file in the package directory before you
run ./packager.py.
To attempt to run Major Stryker in CGA graphics mode, you would create the
configuration file src/major_stryker/dosbox.conf and include this body of
text:
[dosbox]
machine=cga
Then package it using:
./packager.py stryker-cga major_stryker STRYKER.EXE
Most of the credit belongs to the DOSBox crew. They created DOSBox and made it compatible with a wide variety of DOS games. Ismail Khatib got DOSBox to compile with Emscripten, but didn't get it to work. Boris Gjenero started with that and got it to work. Then, Boris re-implemented Ismail's changes a cleaner way, fixed issues and improved performance to make many games usable in web browsers. Meanwhile, Alon Zakai quickly fixed Emscripten bugs which were encountered and added helpful Emscripten features.
3,705 followers · starred Jan 2014
473 followers · starred Dec 2015
109 followers · starred Jan 2020
79 followers · starred May 2018
An Emscripten port of DOSBox
See the codeDOSBox is an open source DOS emulator designed for running games. Emscripten compiles code to JavaScript and WebAssembly. This is a version of DOSBox which can be compiled with Emscripten to run in a web browser. It allows running old DOS games and other DOS programs in a web browser.
DOSBox is distributed under the GNU General Public License. See the COPYING file for more information.
Em-DOSBox runs most games successfully in web browsers. Although DOSBox has not been fully re-structured for running as an Emscripten main loop, most functionality is available thanks to Emscripten Asyncify. A few programs can still run into problems due to paging exceptions.
--enable-funarray
configure option controls this and defaults to yes.file:// URLs.
Use a web server such as python -m http.server instead.This code retains the ability to build a normal version of DOSBox, for running as an ordinary computer application. These instructions are focused on how to build using Emscripten, for running in a web browser.
Use the latest stable version of Emscripten. For more information see the the Emscripten installation instructions. Em-DOSBox depends on bug fixes and new features found in recent versions of Emscripten. Some Linux distributions have packages with old versions, which should not be used.
First, create ./configure by running ./autogen.sh. Then
configure with emconfigure ./configure and build with make.
DOSBox will be contained in src/dosbox.js, and if WebAssembly is enabled
(the default), src/dosbox.wasm. Also, src/dosbox.html will be created,
which is a simple web page that provides an interface to DOSBox. You can
customize it or use DOSBox in your own web page. If you built with Asyncify
enabled (the default), you can open src/dosbox.html via a web server, and
run DOSBox. Without Asyncify DOSBox won't work like that, and you need to add
files to run. See below for information on "Running DOS Programs".
This branch supports SDL 2 and uses it by default. Emscripten will
automatically fetch SDL 2 from Emscripten Ports and build it. Use of make -j
to speed up compilation by running multiple Emscripten processes in parallel
may break this.
Once SDL 2 has been built by Emscripten, you can use make -j.
To use a different pre-built copy of Emscripten SDL 2, specify a path as in
emconfigure ./configure --with-sdl2=/path/to/SDL-emscripten.
To use SDL 1, give a --with-sdl2=no or --without-sdl2 argument to
./configure. There will be more problems, like some keys not working and the
mapper not displaying. Emscripten's SDL 2 is better.
Emscripten Asyncify is used by default. This enables more DOSBox features to work, and only causes a very small performance penalty.
If building with Emscripten versions between 1.29.4 and 1.39.17, you could
try using Emterpreter Sync instead of Asyncify. This is depreciated, worse
than Asyncify and not recommended. Such builds create a memory initialization
file src/dosbox.html.mem needs to be in the same folder as dosbox.js. The
memory initialization file is large. Serve it in compressed format to save
bandwidth.
When compiled using Asyncify, you can interactively load files. In DOSBox,
first use mount c: / and c: commands to provide a space for new files.
Then use the wget command to retrieve files from the same web server.
You can use relative URLs, simply providing file names to load files from
the same directory as the HTML page.
If not using Asyncify, or generally, for convenience, you can create web pages which run particular games. Such a page needs to load files into the Emscripten file system and give command line arguments to DOSBox. The simplest method is by using the included packager tools.
The normal packager tool is src/packager.py, which runs the Emscripten
packager. It requires dosbox.html, which is created when building Em-DOSBox.
If you do not have Emscripten installed, you need to use src/repackager.py
instead. Any packager or repackager HTML output file can be used as a template
for the repackager. Name it template.html and put it in the same directory
as repackager.py.
The following instructions assume use of the normal packager. If using
repackager, replace packager.py with repackager.py. You need
Python 3 to run either packager.
If you have a single DOS executable such as Gwbasic.exe, place
it in the same src directory as packager.py and package it using:
./packager.py gwbasic Gwbasic.exe
This creates gwbasic.html and gwbasic.data. Placing those in the same
directory as dosbox.js and viewing gwbasic.html will run the program in a
web browser:
Most browsers prevent access to the required
data files while using file:// URLs. To get around this you can use Python's
built in HTTP server and point the browser to
http://localhost:8000.
python -m http.server 8000
If you need to package a collection of DOS files. Place all the files in a
single directory and package that directory with the executable specified. For
example, if Major Stryker's files are in the subdirectory src/major_stryker
and it's launched using STRYKER.EXE you would package it using:
./packager.py stryker major_stryker STRYKER.EXE
Again, place the created stryker.html and stryker.data files in the same
directory as dosbox.js and view stryker.html to run the game in browser.
You can also include a DOSBox
configuration file that will be
acknowledged by the emulator to modify any speed, audio or graphic settings.
Simply include a dosbox.conf text file in the package directory before you
run ./packager.py.
To attempt to run Major Stryker in CGA graphics mode, you would create the
configuration file src/major_stryker/dosbox.conf and include this body of
text:
[dosbox]
machine=cga
Then package it using:
./packager.py stryker-cga major_stryker STRYKER.EXE
Most of the credit belongs to the DOSBox crew. They created DOSBox and made it compatible with a wide variety of DOS games. Ismail Khatib got DOSBox to compile with Emscripten, but didn't get it to work. Boris Gjenero started with that and got it to work. Then, Boris re-implemented Ismail's changes a cleaner way, fixed issues and improved performance to make many games usable in web browsers. Meanwhile, Alon Zakai quickly fixed Emscripten bugs which were encountered and added helpful Emscripten features.
3,705 followers · starred Jan 2014
473 followers · starred Dec 2015
109 followers · starred Jan 2020
79 followers · starred May 2018