Setting up jDOSBox for your website
*** NOTE *** this tutorial is superceded by the fact that Java in the browser is DEAD! To that end I'm using the JavaScript based em-dosbox implementation from archive.org until I spin my own build.
The jDOSBox project is a pretty remarkable thing -- porting the entire DOSBox codebase to run on the Java Virtual Machine is quite an accomplishment letting many websites put DOS games up free to play online... but there's just one problem...
The... sparse... ok, let's be honest, nonexistant documentation makes it be detective-work, intuition and outright wild guesses trying to get it up and running... so, here's a simple guide to get you up and running. Thanks go to "kiyotewolf" for prompting me to write this up over on the Vintage Computer Forums.
Step One -- make a floppy image or virtual disk
In order to run any game you need a disk image for the emulator to use. jDOSBox supports the same IMA format (which is just a raw dump) of a floppy, as well as hard disk images. For simplicity sake we'll just be using virtual floppies here. If you want to know more about making disk images and how they are used in DOSBox, check the IMGMOUNT documentation from the official DOSBox website.
The easiest way to create an IMA file in this day and age is to use a program like WinImage. File > New > select the disk size you need. You can then drag and drop all your required files into it. See image to the right. While the largest floppy size isn't that big by modern standards, being able to support up to 2.88 meg disk images covers most games that are fast enough to be run in jDOSBox. In the image to the right you can see the default size is 1.44megs. I suggest choosing as small a disk size as your game will fit into, in this case I'm choosing 160k since I'll use my game "Paku Paku" as an example. The original 5150 shipped with 160k floppy drives -- single sided 40 track 8 sectors per track... so that's in keeping with that game's design goal. The real reason to use the smallest disk image you can though is to keep the download size under control. At almost 3 megabytes jDOSBox is a bit saggy around the midsection as live downloads go, so anything we can do to keep sizes down is good.
I am not aware of any equivalent utilities for Linux or OSX -- If you know of any please use the Contact Form so I can update this page. My Google-fu is really failing me on this one!
Since DosBox comes with it's own DOS emulator we do not need to put DOS on the floppy. All you need to do now is drag and drop the files into your floppy image, and save. In the image to the right you can see I just dropped the files for Paku Paku in there. When saving you want to make sure you choose an IMA file, and not the default IMZ. DOSBox does not appear to have support for compressed floppy formats.
So for this example, I saved the file as PAKU_1_6_160K.IMA. Once saved you have an image file that can be used by both DOSBox and jDOSBox. Now we get to convince jDOSBox of that.
Step Two -- making a .JAR file... NOT!
Jar files seem intimidating and the online information and tutorials on making one are not for the casual user... which total nonsense because they are NOTHING MORE THAN A RELABELED ZIP FILE!
Yes, you heard me right, the big bad intimidating .JAR that every site on the planet tells you special tools are needed to build, is just a .ZIP file with a different extension on it. If the JAR contains executable JAVA code, sure some specific files and directory structures need to be in place -- but if all you're doing is making a data archive to pass to a program, you don't need anything fancy. Make a .ZIP, pass it to the program, and you're in business! I tell you when I found that out I wanted to bitch slap the writer of every single tutorial page I found on Google... and I found it out when I saw it mentioned it was "Based on ZIP" -- so I said "well what happens if I feed it one?"
... and the ONLY thing needed to make a .ZIP into a .JAR for executable code is to put in a META-INF directory with a MANIFEST.MF file in it... said file basically just listing the Main-Class to execute... which uses periods for the directory structure... So simple and everything I've seen turns it into a massive chore!
The directory structure needed in the ZIP file for jDOSBox is important. You need a subdirectory in the ZIP file called /jdos... into your /jdos directory you will place a DOSBOX.CONF containing any customizations you want loaded at startup, as well as your .IMA file. (again, see example to the right)
DOSBOX.CONF
[dosbox]
machine=cga
[mixer]
rate=8000
blocksize=256
prebuffer=1The DOSBOX.CONF I use makes a few tweaks to the audio I highly recommend using, because there's a major timing issue in jDOSBox where it seems to have ridiculous amounts of lag on the audio. Latency issues are almost always caused by the number of audio buffers and buffer sizes, and shrinking the number used usually fixes that problem right up - though it uses more CPU so slow systems MAY choke on it. Dropping the sample rate to 8khz clears up the latter issue... The version for Paku Paku actually adds a couple more lines to set up CMS sound, but apart from that is the same as the one to the right.
From there just turn that directory into a .ZIP file using whatever utility you like best. WinRar, 7-ZIP, WinZip -- they all work pretty much the same... the explorer extensions to right click and make archive being the easiest approach, just be sure it's a .ZIP and not some other format. Also, 7-ZIP's overly aggressive compressor is hit-or-miss on whether it works in jDOSBox or not... so if it doesn't work and you're using 7-Zip, "Well there's your problem.". Fir this example we'll call it simply "jdos.zip".
Step Three -- putting it on a website
First you'll need the file jdosbox_applet.jar from the latest jDOSBox release. All the other .jar files in there are for running it locally, and will not work embedded in a website. (This information is accurate as of the 0.74.25 release, and may change in future ones!) -- put that in the same directory as your jdos.zip... and that's where we'll build our HTML.
The markup for embedding a JAVA applet has seen a lot of changes over the years due to the fact that browser makers have never seen eye-to-eye on doing any of this stuff. Even with the newer standards there's so much room for interpretation and worse, so much legacy code and outdated advice floating around, it's hard to know if you're doing it right. The PROPER tag in a MODERN page to put JAVA in is the same as for video and audio (no matter what the HTML 5 nimrods tell you) -- and that's OBJECT. The following OBJECT tag construct works around IE handling it different, and is valid XHTML 1.0 Strict -- the most recent standard anyone has ANY business building websites for deployment with. (as of 2011.. and honestly probably until sometime around 2016 at the rate things become real world deployable!)
<!-- [if IE]>
<object
classid="clsid:8AD9C840-044E-11D1-B3E9-00805F499D93"
width="640" height="400"
>
<![endif]-->
<!-- [if !IE]>-->
<object
type="application/x-java-applet"
width="640" height="400"
>
<!--<![endif]-->
<param name="code" value="jdos.gui.MainApplet" />
<param name="archive" value="jdosbox_applet.jar,jdos.zip" />
<param name="param1" value="-conf jar://dosbox.conf" />
<param name="param2" value="imgmount e jar://paku_1_6_160k.IMA -t floppy" />
<param name="param3" value="e:" />
<param name="param4" value="paku /cms" />
<p>
This game requires Java to function.
Please either enable it in your browser,
switch to a Java capable browser,
or download the appropriate version off of
<a href="http://www.java.com">Oracle's Java Website</a>
</p>
</object>
The first part of this with the oddball exclamation points is an IE conditional comment, a way to send IE different code than everybody else... so the first OBJECT tag is only sent to IE, the second one is sent to FF, Opera, Saffy, Chrome and anyone else who needs TYPE and doesn't need classid. The PARAM elements are the same for every browser -- if you want this as valid HTML 4.01, just remove the trailing slashes before the closing bracket on each param. Finally the paragraph tag is shown if Java is not present. Simple enough, but let's dig into those PARAM tags and see what's making this tick.
<param name="code" value="jdos.gui.MainApplet" />
This tells JAVA what application in the archives should be run. There's no reason for you to play with this value.
<param name="archive" value="jdosbox_applet.jar,jdos.zip" />
The "archive" parameter tells JAVA what archive files to load -- in this case the application .JAR and our data .ZIP -- you can add full paths to each as this uses URI's separated by comma's to build the list. For example the live copy on this site uses:
value="/jdosbox/jdosbox_applet.jar,/jdosbox/paku_1_6.zip"In that spot, since the files are in the jdosbox subdirectory on the server. In theory you could even point to other servers, though that can run into "trust" issues in many browsers for being "cross-site scripting"...
Numbered Parameters
jDOSBox appears to be able to take a large number of numbered parameters -- "param1","param2","param3", etc. Only Param 1 appears to have a fixed purpose, all the rest appear to operate on the DOSBOX command line. So what are we doing here?
<param name="param1" value="-conf jar://dosbox.conf" />
The first numbered "param" seems to function the same as appending to the the executable from the command line. In this case we're simply telling it that in the root directory of our mounted archives there's a dosbox.conf file to be used.
<param name="param2" value="imgmount e jar://paku_1_6_160k.IMA -t floppy" />
The IMGMOUNT command in DOSBox simply tells it to mount a image file as a drive. In this case I'm telling it to mount drive E as our IMA file. Much like the previous command the jar:// part tells it our file is located in our archive. While this looks like a URI, you can't point it at a web location. The -t flag means type, and of course this is a floppy. Again, see the IMGMOUNT Documentation for more on how that works.
I used E because sometimes I mount these alongside some of my local directories in the real jDOSBox -- E pushes it past those. For the most part it's a relatively safe value to use.
<param name="param3" value="e:" />
DOSBox starts up with drive Z: mounted, so we just change our directory location to E:
<param name="param4" value="paku /cms" />
... and finally we have our DOS command to start the game.
... and you're done. Not that hard.
That's it -- all that's involved in setting up jDOSBox on a website. Not really that hard to do once you understand what all the little PARAM elements are and how to set up your .IMA and .ZIP files, and which .JAR file you need.
Hope this helps those of you who were having issues setting it up.
-- Jason