Tree [r17] / src /

File Date Author Commit
src 2012-08-04 kevodwyer [r13] July 2012
src2 2013-06-15 kevodwyer [r14] June 2013
src3 2014-09-11 kevodwyer [r16] Sept 2014
CHANGES.txt 2014-09-11 kevodwyer [r17] Sept 2014
LicenceGPL2.txt 2011-08-29 kevodwyer [r2]
README.txt 2014-09-11 kevodwyer [r17] Sept 2014 2014-09-11 kevodwyer [r17] Sept 2014

Read Me

JavaScript PC Emulator : JsDOSBox
by Kevin O'Dwyer kevodwyer _at_

JavaScript port of jDosbox which is itself a port of DOSBox.  
Built with the assistance of Google Web Toolkit (GWT).

A significant number of changes were required, including but not limited to:
- input event handling
- keyboard key code translation
- output rendering (canvas, webGL)
- threading (lack of)
- date/time/tick handling
- translate dynarec class compile to building Js functions 
- sound mixing and generation. I have tried three different approaches, would benefit from some more work
- unchecked exceptions to checked exceptions (GWT/JS limitation)
- primitive arrays to TypedArrays
- support for Zip file backed virtual file system
and numerous workarounds for various things that don't translate to JavaScript
As with anything that requires R&D, more code was developed and thrown away than actually made it into this codebase.

Project homepage:

This program is released under the GPLv2 open source license.

The following open source projects were used in the making of this project:
jDosbox	(GPL)
gwt-g3d (Apache v2)
gwt-nes-port (file upload) (GPL v3)  
MIDPath (Zip file handling) (GPL)
 - including code from GNU Classpath and phoneME
The Crystal Icon set (config icons) (LGPL) - Java floating point library for MID devices by Roar Lauritzsen (GPL)


The first thing to note is that this is a port of DOSBox, so some knowledge is transferable.  
This port is however in beta so not everything DOSBox (or more specifically jDosbox) supports is 
currently available or working.

JsDOSBox has a config using:
- 486 machine type with a FPU
- 8 Mb ram (configurable)
- s3 video card
- sound card emulation

- Only screen modes that use a colour palette are supported 
- Page faults are not handled correctly
- No network card emulation
- No CD-ROM emulation
- No joystick emulation
- Sound is mono
- No Midi
- No shell


Extract the file from the base source directory.  
This contains all the static JavaScript files to run JsDOSBox.  
The JsDOSBoxTest.html file includes everything to launch and configure the program. 
Take particular note of the input fields at the end of the file that capture the configuration parameters.  
The files are to be copied into the appropriate directory of your favourite web server.  
REMEMBER:  Due to browser caching, make sure to flush your browser cache as you configure the program.

Configuration parameters:
Very little verification is done on the parameters so be careful.
* If you are reading this section after previously reading it before you will note that some have changed and some have been added/removed.  Defaults have also changed.

    <input id="override" type="hidden" value="false">
If true, a visitor can override the config parameters by appending items to the url query string   
    <input id="frameskip" type="hidden" value="1"> 
values -1 to 6. -1 means auto. -1,0 likely to cause emulator to run slowly. 1,2,3 seem reasonable.  A high number is likely to cause the sound to break up.
    <input id="cycles" type="hidden" value="auto"> 
Indicates cycle strategy. Default is auto.  Values auto, max, limit and ignore.
    <input id="cyclelimit" type="hidden" value="0"> 
The number of instructions the emulator will try to execute up to per millisecond.  Default value is 0 indicating no limit. Other possible values are from 100 to 90000
    <input id="core" type="hidden" value="dynamic"> 
either dynamic or normal.  Default is dynamic
    <input id="mouse" type="hidden" value="false"> 
Mouse emulation.  Default value is false.  This is experimental.
    <input id="maxFPS" type="hidden" value="12"> 
Reduces the number of frames per second to no more then the value set. Default value is 12. Values -1 to 100.
    <input id="autorun" type="hidden" value=" -t zip !c:!cd doom!doom.exe"> 

The Autorun parameter captures what gets executed by the emulator.  The '!' character is used as a newline delimiter.  
The first instruction details the name of the file to use and subsequent instructions indicate what to execute.  
The file should be copied into the same directory as the html file.  
The final execution instruction must contain .exe or .com

Currently RAW and zip disk images are supported.  Make sure to append -t zip when using zip files. NOTE: zip files are mounted as read-only.  Attempts by the emulator to write to the zip file will fail!

sound emulation is hardcoded to mono.
PC Speaker emulation suffers from constant ticks.  
The SoundBlaster configuration is set to Interrupt 7, DMA 1 and port 220. No midi
Configuration parameters
<input id="nosound" type="hidden" value="false"> 
enable sound.  Default is nosound=false
<input id="sbtype" type="hidden" value="sb1">
options are sb1, sb2, sbpro1, sbpro2, sb16, gb, none. Default is sb1
<input id="oplmode" type="hidden" value="none">
options are auto, none. Default is auto
<input id="gravis" type="hidden" value="false">
enable gravis emulation.  Default is gravis=false

<input id="mixerrate" type="hidden" value="11025">
it is not recommended using a Mixing Freq > 22050 Hz.  A value of 8000 is the current default. Shared by all audio devices.  
Possible values 8000, 11025, 16000, 22050, 32000, 44100
<input id="jsbuffer" type="hidden" value="2048"> 
the size of the sample sent to Web Audio decoder. Actually it is x2 the real size as mono is the current default
<input id="modfactor" type="hidden" value="55">
optional fudge parameter.  This determines how often sound output is generated. The emulator tries to guess
the right interval based on the jsbuffer size and mixerrate.  The lower the value the greater the rate of output generation.
For a 8000khz mixer and a jsbuffer size of 2048, a reasonable modfactor is 55.

Internal sound parameters.  Additional dials to tweak.  The same meaning as the equivalent jdosbox params. 
    <input id="blocksize" type="hidden" value="2048"> 
    <input id="prebuffer" type="hidden" value="40"> 

<input id="backgroundcolor" type="hidden" value=“FFFFFF”>
the color of the page expressed as a hex value. Default is 496E98.
<input id="scalefactor" type="hidden" value=“0”>
scale the canvas. Values -1,1,2,3.  Not all screen resolutions will be scaled.
-1 is default and always draw directly to the canvas.
2,3 always draws to backing canvas which is then drawn to the scaled screen canvas.
1 indicates a mix of the above. Drawing to the screen directly for non-scaled resolutions and to a backing canvas for scaled resolutions.
<input id="suppresszipfilewriteerrormsg" type="hidden" value=“false” />
as zip file are mounted as read only and an error message is displayed if an attempt to write is made.  This suppresses the error alert box if set to true.  Default is false.


Built using Google Web Toolkit.  You will need GWT and the GWT eclipse plugin.  
Use at least GWT version 2.5
Everything needed to build is under the src directory.  
You will also need the gwt-g3d jar file from