How to run DOS game in browser

5 min readJun 17, 2022

js-dos v7 — best API to run DOS game in browser

In 2022, no one can be surprised by DOS in the browser. Thanks to dosbox, retro games are available on many platforms. With the development of the emscripten compiler DOS comes to browser. js-dos is one of the most notable projects for porting dosbox to the browser. I started working on it in 2014. The project has gone through a long evolution, 3 different versions were released with different architecture and API (v2/v3–2015/2017, 6.22–2018/2020, v7–2021+).

With new powerful technologies, the performance of the emulator has steadily grown, the very first versions were in pure JavaScript, then there was asm.js and finally WebAssembly. The latest version of js-dos already has enough performance to comfortably play games like Duke, Doom, C&C, Red Alert, WarCraft and many more.

Pros

In my opinion js-dos is the best API for running DOS games in a browser. Unlike other implementations:

stores progress between sessions (browser restarts)
works inside worker, which means it does not block the browser UI
works in node.js
have a headless mode, i.e. without screen output (ideal solution for VR)
supports IPX network protocol
aimed at mobile devices
has a huge library of ready-made games

Many have appreciated this solution, the list of integrations has already exceeded 50 web-sites.

I hope a good review will help increase this number. Article aims to explain how to run a DOS game using js-dos. And there are actually many ways.

js-dos bundle

js-dos operates with the concept of ‘bundle’. The bundle is a zip archive that contains everything you need to run the game. The js-dos community maintain a repository of DOS games and makes more than 1900+ DOS bundles publicly available. Many of them have support for mobile devices.

The easiest way is to prepare a game bundle for js-dos — use the “Game Studio”. This is an editor that not only generates a bundle, but also allows you to design mobile controls in a visual mode.

Running in Browser

Consider ways to run a DOS game, starting with the simplest one:

iframe integration

js-dos is not only an API, but also an ecosystem, it includes a player for embedding with iframe. To add a game to the web-site through an iframe, just use this code:

<iframe 
    frameborder="0" 
    src="https://dos.zone/player/?bundleUrl=<url>&anonymous=1"
    allowfullscreen />

Replace <url> with a link to your bundle. The link must be url encoded.

Where can I get a bundle? It’s very easy, just open the DOS Zone community site and use the button (</>) to generate the code to embed on the site:

IMPORTANT! To receive input you should focus the iframe (by click or using js):

iframe.focus()

Integration using JavaScript API

To run bundle you just need a one line of code:

Dos(document.getElementById("jsdos")).run("some.jsdos");

The Dos function creates an abstraction of the js-dos player. The first argument is a — div element that acts as a container for the player interface. To run a specific bundle, use the run method, which should be passed a url to the bundle.

The DOS constructor is defined in the js-dos.js script, the player styles in js-dos.css, and the emulator in WebAssembly files. js-dos.js and js-dos.css must be added to the web page code prior to using js-dos. To avoid errors, it is best to use the create-dosbox utility to generate a template project.

To use this utility, you need to install node.js/npm. And then execute:

npx create-dosbox my-app 
cd my-app 
npm install 
npm start

If successful, the selected DOS game will be available at localhost:8080.

npx create-dosbox my-app will create a directory my-app, the structure of this directory is:

my-app 
├── package.json 
└── _site
    ├── js-dos 
    ├── bundle.jsdos 
    └── index.html

js-dos — contains last release version of js-dos that you can download from Releases page
bundle.jsdos — is a bundle with game to start read more
index.html — is a web page template

Thus, it is enough to replace bundle.jsdos with another bundle to change the game being launched.

Headless mode

Headless mode allows you to run emulation in the “background” without displaying it on the screen. In this mode, dosbox output is available as an RGB buffer. This option can be used to create VR integrations, or for example, you can embed a DOS game inside another game.

The use of this mode is described in more detail in the documentation.

Node.js

js-dos has no required browser dependencies. You can run DOS games in node.js programs. For example, this feature was used to launch DOOM on LISK.

Lisk — is a platform for creating decentralized applications based on blockchain technology and using the LSK token.

DOOM at LISK even won the People’s Choice Award in the Design Competition, as well as a $1,000 prize.

A simpler example of using js-dos in node.js is described in the documentation.

Multiplayer games

Some dos games offers multiplayer gaming based on ipx, modem, or direct connection. Using browser isn’t possible to directly connect two clients. BUT using js-dos you can emulate a direct connection. This is an absolutely unique js-dos feature among DOS browser emulators. Using it, you can create a portal for online games like DOOM, Duke Nukem 3D, Warcraft and others. This feature is completely free.

To activate IPX support in js-dos you need to set withNetworkingApi to true:

Dos(<element>, { 
    withNetowkringApi: true, 
}).run(<bundleUrl>);

This is enough to integrate multiplayer games into web page.

However, in order to connect two js-dos clients using ipx, the user must set up an IPX server and provide the server token to other players.

We have prepared a tutorial video for players to make it easier for them to connect: