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:
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).
The src can be composed like this:
To receive input you should focus the iframe:
Complete example:
info
- Drag with the mouse to play without a keyboard!
- 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 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:
Complete example:
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:
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:
Complete example:
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.