To contribute to the
emulators package do the following:
git clone https://github.com/caiiiycuk/js-dos
git checkout -b dev origin/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. CMake project have following targets:
sokol- js-dos v7 native version: dosbox + UI based on sokol. This version is exactly same as web version. You should use this target to contribute in js-dos v7.
direct- target that used to build web-direct version of js-dos v7. You can compile it only with emscripten.
worker- target that used to build 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 code that contain implementation of zip.
jsdos- shared code 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 server is a dosbox.
But in theory server 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 emulator. Client should prepare filesystem 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 same way as direct/worker dosbox.
This function add keycode to queue. They will be processed when dosbox poll keyboard events.
Terminates execution of dosbox and free resouces.
Direct, worker, and sokol implementations share 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 detach emulator from it's ui. You can easily add new UI/sound system to dosbox.
For example let's look on sokol UI implementaion. You can use it to debug and develop new features for js-dos. Worker is a primary web implemenation for js-dos v7. sokol implementaion tries to work in simmilar way: we start dosbox emulator in main thread and client in new thread.
When server starts it will send frame size of 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 content of dosbox window are changed. dosbox implemenation 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 dosbox need to initialize 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 it's 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 finished successfully then you can run emulators tests.
To do this run static web server to host
dist directory. For example, with
and open test page in browser:
all tests should pass.
Running native js-dos v7
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 root of extracted bundle).
You can use docker image to develop emulators core. Image have already configured eveyrthing to build emulators core and start emulators tests.
http://localhost:8080 in browser, all test should pass
Run inside the project dir:
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.