js-dos

js-dos is a DOSBox-based emulator that runs classic DOS executables in the browser via WebAssembly. Wavedash has first-class support for js-dos: upload a .jsdos bundle, point wavedash.toml at it, and the platform wraps it in the js-dos runtime automatically. No SDK code is required inside your DOS game.

Create a .jsdos bundle

A .jsdos file is a standard ZIP archive (renamed to .jsdos) that contains your DOS executable plus a .jsdos/dosbox.conf describing how to run it. The minimum layout is:

game.jsdos (zip)
├── GAME.EXE               ; or .COM / .BAT — your game
├── dosbox.conf            ; short root-level override (usually just [cpu] cycles)
└── .jsdos/
    └── dosbox.conf        ; full DOSBox config with [autoexec] that runs your game

The .jsdos/dosbox.conf needs an [autoexec] section that launches your game. A minimal working config:

[sdl]
autolock=false

[cpu]
cycles=fixed 3000

[autoexec]
GAME.EXE

Zip it up:

cd game-files && zip -r ../game.jsdos . && cd ..

The js-dos Studio has a visual tool for creating bundles from existing DOS games if you'd rather not hand-write the config.

Upload your bundle

Put game.jsdos in your upload directory, then in wavedash.toml:

game_id = "YOUR_GAME_ID_HERE"
upload_dir = "./build"

[jsdos]
version = "v8"
executable = "game.jsdos"

Run wavedash dev to test locally. When ready to ship, upload your build and publish it from the Developer Portal.

SDK integration

None required inside the DOS game. The platform loads js-dos from a CDN, configures the emulator (kiosk mode, auto-start, aspect-preserving render), and fires Wavedash.loadComplete() once the emulator is ready.

Custom loader script

If you want to configure js-dos options yourself — render aspect, input mappings, event handlers, cloud-save wiring — add a loader_url:

[jsdos]
version = "v8"
executable = "game.jsdos"
loader_url = "loader.js"

Place loader.js in your upload directory. Set window.dosOptions to any valid js-dos options object (or a Promise resolving to one); js-dos will merge it with the platform's defaults:

// build/loader.js
window.dosOptions = {
    renderAspect: "4/3",
    onEvent: function (event, ci) {
        if (event === "ci-ready") {
            Wavedash.loadComplete();
            // Game is running; you can stash `ci` and submit scores via the SDK later.
        }
    },
};

If you override onEvent, you're responsible for calling Wavedash.loadComplete() yourself — the default loader hands that off to you.

See the js-dos v8 options for the full surface.