To contribute to the
emulators package do the following:
git clone https://github.com/js-dos/emulators
Install emscripten sdk, and confgure environment to use it.
Now you can build everything with
Native part of emulators is plain cmake project, you can open it in your favorite editor. Project have the following targets:
sokol- js-dos v7 native version: dosbox + UI based on sokol. This version is exactly the same as the web version. You should use this target to contribute in js-dos v7.
direct- target is used to build the web-direct version of js-dos v7. You can compile it only with emscripten.
worker- target is used to build the web-worker version of js-dos v7. You can compile it only with emscripten.
dosbox- original version of dosbox (UI based on SDL). You can use it to compare behaviour between original dosbox and js-dos v7.
libzip- shared codes that contain implementation of zip.
jsdos- shared codes that contain implementation of dosbox.
The idea of new js-dos v7 is that all targets (native and web) have exactly same way to communicate between client (native UI, browser UI) and dosbox.
For simplicity, you can think that the server is a dosbox.
In the future servers can be implemented with different emulators. Now we support
only dosbox implementation (look at
Client should run this function when it's ready to start dosbox. This
function will start the emulator. Client should prepare file system for dosbox it
So you need to extract js-dos bundle in some directory and start sokol binary in this directory, and it will act exactly in the same way as direct/worker dosbox.
#server_add_key(keycode, pressed, timeMs)
This function adds keycode to the queue. They will be processed when dosbox poll keyboard events.
Terminates execution of dosbox and free resources.
Direct, worker, and sokol implementations share the same code for server part. But they are completely different, because they implement UI and sound system for different platforms. In original dosbox this was made by SDL, it was hard-coupled with dosbox. js-dos clearly detaches the emulator from its ui. You can easily add new UI/sound system to dosbox.
For example, let's look on sokol UI implementation. You can use it to debug and develop new features for js-dos. Worker is a primary web implementation for js-dos v7. sokol implementation tries to work in similar way: we start dosbox emulator in main thread and client in new thread.
When the server starts it will send the frame size of the dosbox window by invoking
client_frame_set_size. You should allocate rgba buffer to store frame content. This function will be called each time when dosbox window size is changed.
#client_frame_update_lines(lines, count, rgba)
This method will be called each time if contents of dosbox window are changed. dosbox implementation will send only changed lines. You need to update your frame buffer correctly.
Dirty region format (lines argument):
- line number [0, height)
- count of changed lines
- offset in passed buffer (rgba argument)
client_frame_update_lines is enough to render
Called when the dosbox needs to initialize the sound system.
This method is called each time when new sound samples should be pushed to audio device. With sokol implementation is very simple:
This method will be called each time when dosbox prints something to its console.
#Communicate to server
Each time when key is pressed we should send event to dosbox:
When user closes sokol window we need to stop server:
That is. Check complete source of sokol implementation.
gulp command is finished successfully then you can run emulators tests.
To do this, run a static web server to host the
dist directory. For example, with
and open test page in browser:
all tests should pass.
#Running native js-dos v7
As said above, you need to compile a
sokol target with your favorite C++ toolkit. It will generate
executable. Next, you need to download some js-dos bundle for example
js-dos bundle is a plain zip archive, you need to extract it in some folder. After that you
sokol executable from that folder (cwd must be the root of the extracted bundle).
You can use docker image to develop emulators core. The image has already configured everything to build emulators core and start emulators tests.
http://localhost:8080 in browser, all tests should pass
Run inside the project directory:
Use your code editor to edit the content of src and test.
In the docker VM you can run
gulp to build everything into
dist OR use
./node_modules/.bin/tsc --watch if you need only compile time checks.
#Contributing on github
To contribute your code please create PR on github, and check if all tests passed.