Overview

warning

js-dos v7 is still under development and some features are not ready; for example you can't use a mouse yet. Please use js-dos 6.22 for production projects.

The new version of js-dos is more modular, you can use parts of it. It consists of:

  • js-dos bundle - universal package format that js-dos understands
  • emulators - npm package, that provide emulator backends which can run in different environments
  • emulators-ui - npm package, a set of ui and sound components to render emulator output in browser
  • js-dos - npm package that combines everything to run a DOS program in browser

js-dos bundle

Previous version (6.22) has a very simple API to run a DOS program in the browser. BUT, before starting it you need to perform some setup:

  • download game archive (usually zip)
  • extract it
  • configure dos file system
  • configure dosbox options (cycles, renderer type, etc.)
  • configure controllers (mouse, keyboard type, etc.)

Often gameplay quality depends on good configuration.

Starting from js-dos v7, the API expects a js-dos bundle that already contains all configuration needed to start the DOS program. js-dos bundle is just a ZIP archive that contains the game itself and a js-dos configuration file (same as dosbox.conf file). For example, digger.jsdos contains:

.jsdos/dosbox.conf - dosbox configuration file (required)
.jsdos/jsods.json - additional configuration (optional)
DIGGER.COM - game file
note

File .jsdos/dosbox.conf is required. js-dos would not start if this file does not exist.

You can generate a js-dos bundle programmatically. But, we recommend you use our bundle generator Moreover you can search our database to see if someone already uploaded a js-dos bundle for a program.

Read the guide about creating js-dos bundle.

Run jsdos file

Once you have a jsdos bundle you can easily run it in the browser. There are several options:

1. Using player hosted on dos.zone

Fastest way to embed a program on your page. You just need the url of a jsdos bundle (you can get it from our game database).

<iframe
id="jsdos"
src="https://dos.zone/en/player/https%3A%2F%2Fdoszone-uploads.s3.dualstack.eu-central-1.amazonaws.com%2Foriginal%2F2X%2F5%2F5c63f84bae9688046b9a7c0a9f1f1c8904616052.jsdos"
/>

The src can be composed like this:

const src = "https://dos.zone/en/player/" + encodeURIComponent(bundleUrl);

To receive input you should focus the iframe:

document.getElementById("jsdos").focus();

Complete example:

examples/iframe.html
Run
{}
info
  1. Drag with the mouse to play without a keyboard!
  2. Open top menu to type records name on mobile.
warning

Iframe integration didn't support a fullscreen button yet, if you need it look forward.

2. Using js-dos api

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

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

Dos receives HTMLDivElement and uses it to create the player UI. To run jsdos bundle just use its method run specifying the url of jsdos bundle.

To use js-dos you need to add js-dos.js script, and js-dos.css style. Also you need to specify path prefix of js-dos installation:

<script src="/v7/build/releases/latest/js-dos/js-dos.js"></script>
<link href="/v7/build/releases/latest/js-dos/js-dos.css" rel="stylesheet">
// ...
<script>
emulators.pathPrefix = "/v7/build/releases/latest/js-dos/";
Dos(<element>).run(<bundleUrl>);

Complete example:

examples/dos.html
Run
{}
info

By default, js-dos will load wasm modules relatively from current path, you should specify variable pathPrefix if you want to load them from different place:

emulators.pathPrefix = "/v7/build/releases/latest/js-dos/";

3. Using emulators-ui

From v7 js-dos npm package is only a wrapper script that combines emulators and emulators-ui packages. It didn't contains code itself. It's useful if you don't want to make customizations in UI or custom integration. js-dos package is single file solution to run DOS programs.

If you want to make customizations or something special then you need to use emulators and emulators-ui package in combination. They provide absolutely same functions as js-dos package and lot more (see threejs integration).

To change code above to use emulators-ui just change scripts imports to:

<script src="/v7/build/releases/latest/emulators/emulators.js"></script>
<script src="/v7/build/releases/latest/emulators-ui/emulators-ui.js"></script>
<link rel="stylesheet" href="/v7/build/releases/latest/emulators-ui/emulators-ui.css">

Complete example:

examples/ui-dos.html
Run
{}

4. Using emulators

In case you don't want to use the browser API of js-dos project, you can use just the emulators package. Read the guide to how we use emulators to estimate js-dos performance.