diff --git a/docs/Navigation.md b/docs/Navigation.md index 89107725..45de29c9 100644 --- a/docs/Navigation.md +++ b/docs/Navigation.md @@ -50,6 +50,7 @@ search: - [Uploads](using/uploads.md) - In-Browser Play - [EmulatorJS](using/in-browser-play/emulatorjs.md) + - [`js-dos`](using/in-browser-play/js-dos.md) - [MS-DOS](using/in-browser-play/ms-dos.md) - [Ruffle](using/in-browser-play/ruffle.md) - [Emulator Streaming](using/emulator-streaming.md) diff --git a/docs/about/credits.md b/docs/about/credits.md index 27d76fbd..6fe9fec6 100644 --- a/docs/about/credits.md +++ b/docs/about/credits.md @@ -35,6 +35,8 @@ This stack stands on an enormous amount of open-source work. In rough order of " ### In-browser emulation - [EmulatorJS](https://emulatorjs.org/) +- [`js-dos`](https://js-dos.com/) +- [DOSBox-X](https://dosbox-x.com/) - [Ruffle](https://ruffle.rs/) - [dosbox-pure](https://github.com/schellingb/dosbox-pure) diff --git a/docs/about/license.md b/docs/about/license.md index e8c082f2..5ad6b65b 100644 --- a/docs/about/license.md +++ b/docs/about/license.md @@ -34,7 +34,7 @@ Companion repos use more permissive licenses AGPLv3 or MIT because they're small ## Third-party components -Several third-party components ship with their own licenses: [EmulatorJS](https://emulatorjs.org/), [Ruffle](https://ruffle.rs/), Vue, FastAPI, and a long list of smaller dependencies. Their licenses apply to their respective code, and none of them override AGPLv3 on the RomM code itself. View the full list via `uv tree` in the backend and `npm ls` in the frontend. Redistribution respects each upstream's terms. +Several third-party components ship with their own licenses: [EmulatorJS](https://emulatorjs.org/), [`js-dos`](https://js-dos.com/), [Ruffle](https://ruffle.rs/), Vue, FastAPI, and a long list of smaller dependencies. Their licenses apply to their respective code, and none of them override AGPLv3 on the RomM code itself. View the full list via `uv tree` in the backend and `npm ls` in the frontend. Redistribution respects each upstream's terms. ## FAQ diff --git a/docs/install/image-variants.md b/docs/install/image-variants.md index 40fccec4..c5ded6c8 100644 --- a/docs/install/image-variants.md +++ b/docs/install/image-variants.md @@ -5,12 +5,12 @@ description: Choose between the slim and full container images # Image Variants -RomM publishes two production image variants. They're interchangeable at the config level, so pick based on whether you want baked-in EmulatorJS cores or fetch them from the CDN at runtime. +RomM publishes two production image variants. They're interchangeable at the config level, so pick based on whether you want the browser emulator runtimes baked into the image or fetched from a CDN at runtime. -| Variant | Tag | Approx size | When to pick | -| ------------------ | --------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------- | -| **Full** (default) | `rommapp/romm:latest` `rommapp/romm:5.0.0` | ~400MB | You want in-browser play (most users pick this). | -| **Slim** | `rommapp/romm:slim` `rommapp/romm:5.0.0-slim` | ~100MB | Headless use (API + native-app clients only) or when you're running emulators elsewhere. | +| Variant | Tag | Approx size | When to pick | +| ------------------ | --------------------------------------------- | ----------- | ------------------------------------------------------------------------------------ | +| **Full** (default) | `rommapp/romm:latest` `rommapp/romm:5.0.0` | ~400MB | You want in-browser play with every runtime baked in (most users pick this). | +| **Slim** | `rommapp/romm:slim` `rommapp/romm:5.0.0-slim` | ~100MB | Headless use, or you're fine fetching EmulatorJS and `js-dos` from a CDN at runtime. | Both variants are published on Docker Hub (`docker.io/rommapp/romm`) and GitHub Container Registry (`ghcr.io/rommapp/romm`). The GHCR images track the same tags and are a good choice if you run into Docker Hub's rate limits. diff --git a/docs/platforms/index.md b/docs/platforms/index.md index c012ceac..0dc38982 100644 --- a/docs/platforms/index.md +++ b/docs/platforms/index.md @@ -10,6 +10,6 @@ description: Everything about the supported platforms ## Related sections -- **[In-Browser Play](../using/in-browser-play/emulatorjs.md)**: the end-user side of EmulatorJS + Ruffle +- **[In-Browser Play](../using/in-browser-play/emulatorjs.md)**: the end-user side of EmulatorJS, `js-dos`, and Ruffle - **[Metadata Providers](../getting-started/metadata-providers.md)** - **[Folder Structure](../getting-started/folder-structure.md)** diff --git a/docs/resources/snippets/env-vars.md b/docs/resources/snippets/env-vars.md index df12b541..3f77e5d2 100644 --- a/docs/resources/snippets/env-vars.md +++ b/docs/resources/snippets/env-vars.md @@ -127,10 +127,11 @@ ### Emulation -| Variable | Default | Required | Description | -| --------------------- | ------- | :------: | ---------------------------------------------- | -| `DISABLE_EMULATOR_JS` | `false` | | Disable in-browser play via EmulatorJS | -| `DISABLE_RUFFLE_RS` | `false` | | Disable in-browser Flash playback via RuffleRS | +| Variable | Default | Required | Description | +| --------------------- | ------- | :------: | ----------------------------------------------------------- | +| `DISABLE_EMULATOR_JS` | `false` | | Disable in-browser play via EmulatorJS | +| `DISABLE_RUFFLE_RS` | `false` | | Disable in-browser Flash playback via RuffleRS | +| `DISABLE_JSDOS` | `false` | | Disable in-browser Windows 3.x and 9x playback via `js-dos` | ### Integrations diff --git a/docs/using/in-browser-play/js-dos.md b/docs/using/in-browser-play/js-dos.md new file mode 100644 index 00000000..26809f8d --- /dev/null +++ b/docs/using/in-browser-play/js-dos.md @@ -0,0 +1,61 @@ +--- +title: js-dos +description: Play Windows 3.x and 9x games in the browser via DOSBox-X +--- + +# `js-dos` + +[`js-dos`](https://js-dos.com/) runs DOSBox-X in the browser for Windows 3.x (`win3x`) and Windows 9x (`win9x`) titles. MS-DOS games continue to use the [EmulatorJS `dosbox-pure` core](ms-dos.md). + + +!!! info "Bundled in the full image, fetched from a CDN in slim" + The full container image ships the `js-dos` runtime locally. The slim image has no local copy, so the player falls back to jsDelivr at runtime and needs outbound internet access from the browser (see [Image Variants](../../install/image-variants.md)). + + +!!! warning "`js-dos` requires HTTPS" + DOSBox-X uses the `SharedArrayBuffer` API, which browsers only expose in secure, cross-origin-isolated contexts, so RomM must be served over `https://` for these games to run. Use a [reverse proxy with TLS](../../install/reverse-proxy.md) if you're still on plain HTTP. + +Operators can turn the player off with `DISABLE_JSDOS=true` (see [Environment Variables](../../reference/environment-variables.md)). + +## Bundling a game + +RomM passes the selected file directly to `js-dos`, so upload a ready-to-run [`js-dos` bundle](https://js-dos.com/jsdos-bundle.html), not a regular zip of loose game files. The bundle is a zip archive carrying a `.jsdos/dosbox.conf`, and RomM only offers the player for files with a `.jsdos` extension, so rename the archive before uploading: + +```text +game.jsdos + .jsdos/ + dosbox.conf + WINDOWS/ + ...game files +``` + + +!!! important "The file extension must be `.jsdos`" + A bundle left as `game.zip` scans in fine but never gets a Play button, because RomM gates the `js-dos` player on the file extension. + +The configuration controls how the bundle boots. For example, a Windows 3.x bundle with Windows installed in the bundle root can use: + +```ini +[dosbox] +machine=svga_s3 +memsize=32 + +[autoexec] +@echo off +mount c . +c: +WIN GAMEDIR\GAME +``` + +- `mount c .` mounts the bundle root as `C:`. `js-dos` does not add this mount automatically. +- `WIN GAMEDIR\GAME` boots Windows straight into the game instead of Program Manager. + +Windows 9x and disk-image layouts need different DOSBox-X configuration. Use the [`js-dos` bundle cookbook](https://js-dos.com/jsdos-bundle.html) or [`js-dos` Game Studio](https://v8.js-dos.com/studio/), its browser-based bundle builder. Upload the result under the `win3x` or `win9x` platform. RomM uses `js-dos` only for those platforms and leaves `dos` with EmulatorJS. + +## Saves + +`js-dos` stores filesystem changes in the browser, isolated by RomM user and game. They are not uploaded or synced with RomM. Quitting the player writes a final save, so wait for it to finish rather than closing the tab mid-game. + + +!!! warning "Saving depends on the application" + Some applications save only when you exit back to Windows. Exit the application before quitting the player. diff --git a/docs/using/in-browser-play/ms-dos.md b/docs/using/in-browser-play/ms-dos.md index 12ed9224..e49782f5 100644 --- a/docs/using/in-browser-play/ms-dos.md +++ b/docs/using/in-browser-play/ms-dos.md @@ -9,6 +9,10 @@ description: Run DOS games in the browser via dosbox-pure DOS games run via the `dosbox-pure` core (part of [EmulatorJS](emulatorjs.md)). Create a DOS platform (folder named `dos`) and drop your games in. Operator tuning lives in [Configuration File → `emulatorjs`](../../reference/configuration-file.md#emulatorjs) (notably `disable_batch_bootup` for DOS-specific issues). + +!!! info "Windows 3.x and 9x games use `js-dos`" + RomM keeps DOS games on `dosbox-pure` and routes Windows 3.x and 9x titles through the [`js-dos` player](js-dos.md). Put those titles under the `win3x` and `win9x` platform folders instead of `dos`. + !!! tip "Upload games as `.zip`" `dosbox-pure` knows how to unzip and auto-mount zipped DOS games, which is much easier than packaging a raw folder. diff --git a/docs/using/index.md b/docs/using/index.md index 729c4616..82eb45c8 100644 --- a/docs/using/index.md +++ b/docs/using/index.md @@ -9,6 +9,7 @@ description: Browse, play, collect, patch, and share from the UI - **[EmulatorJS](in-browser-play/emulatorjs.md)** - **[MS-DOS](in-browser-play/ms-dos.md)** +- **[`js-dos`](in-browser-play/js-dos.md)** - **[Ruffle](in-browser-play/ruffle.md)** - **[Emulator Streaming](emulator-streaming.md)** - **[Downloads](downloads.md)**