DOS

Warning

WebЯcade is not designed for installing games onto hard disks from CD or similar sources, as this will result in large save files being created (either locally or to the cloud). Instead, installations should be performed outside of WebЯcade using something like DOSBox Pure in RetroArch. Once the installation is complete, the resulting files can be packaged for use within WebЯcade.

Overview

The DOS application is an emulator that runs programs or games that were designed for DOS-based systems.

Controls

The keyboard/mouse controls, gamepad mappings, and touch controls are listed in the tables below.

Keyboard and Mouse

The following table contains the standard keyboard mappings. The DOS application supports full keyboard and mouse functionality. Each game will have its own specific keyboard and mouse bindings.

Name	Keys	Comments
Pause Screen	+	Displays the webЯcade pause screen.
Pause Screen	+	Displays the webЯcade pause screen.

Gamepad

The following table contains the common gamepad mappings. The DOS application currently supports only a single connected gamepad, which can operate in two modes: standard gamepad mode, functioning like a joystick, and mouse emulation mode, where the gamepad emulates a mouse.

Controller Mode: Gamepad

In gamepad mode, the connected gamepad functions like a joystick, providing standard input controls for the game.

See the Gamepad Controls Tab in the View Controls section of the Pause screen to view how the gamepad is mapped to the current game.

Name	Gamepad	Comments
Show Virtual Keyboard	and	Hold down the Left Trigger and click (press down) on the Right Thumbstick.
Switch to Mouse Mode	and	Hold down the Left Trigger and click (press down) on the Right Thumbstick for several seconds until the message, "Switched to mouse mode" appears.

Controller Mode: Mouse Emulation

In mouse emulation mode, the connected gamepad emulates the mouse, allowing for mouse-like input.

Name	Gamepad	Comments
Mouse
Left Mouse
Right Mouse
Show Virtual Keyboard	and	Hold down the Left Trigger and click (press down) on the Right Thumbstick.
Switch to Gamepad Mode	and	Hold down the Left Trigger and click (press down) on the Right Thumbstick for several seconds until the message, "Switched to gamepad mode" message appears.

Standard webЯcade mappings to display the pause screen are listed below (regardless of controller mode).

Name	Gamepad	Comments
Show WebЯcade Pause Screen	and	Not available for Xbox and not recommended for iOS (see alternate 3 or 4) Hold down the Left Trigger and press the Menu (Start) Button.
Show WebЯcade Pause Screen (Alternate)	and	Not available for Xbox and not recommended for iOS (see alternate 3 or 4) Hold down the Left Trigger and press the View (Back) Button.
Show WebЯcade Pause Screen (Alternate 2)	and	Not available for Xbox and not recommended for iOS (see alternate 3 or 4) Hold down the X Button and press the View (Back) Button.
Show WebЯcade Pause Screen (Alternate 3)	and	Hold down the Left Trigger and click (press down) on the Left Thumbstick.

Touch Controls

Touch input can be used to simulate mouse input in the game.

Dragging your finger behaves similarly to using a touchpad, where the mouse cursor moves relative to the movement of your finger.

Gesture	Description
Short single finger tap	Left mouse button click
Short second finger tap while holding one finger	Right mouse button click
Single finger drag	Move pointer indirectly with finger
Two finger drag	Move pointer while left mouse button is held down (drag and drop). The pointer motion is affected by the first finger. The drag is ended when the last finger is removed.
Three finger drag	Move pointer while right mouse button is held down (drag and drop). The pointer motion is affected by the first finger. The drag is ended when the last finger is removed.

Packaging Games

DOS games must be packaged as an archive (.zip) file for use with webЯcade. This archive file can also be (optionally) converted to a webЯcade package archive manifest (.json) layout to reduce browser memory use and increase compatibility with memory limited devices (iOS and Xbox).

Important

The webЯcade editor's repackage archive tool can be used to automatically generate package archive manifests.

Important

For DOS game archive (.zip) sizes that are over 100 megabytes in size, it is highly recommended that the webЯcade package archive manifest (.json) layout be utilized. This will greatly reduce the amount of memory necessary for the browser to load the game, and increase compatibility with devices with higher memory use limitations (iOS and Xbox).

Adding Games (Feed Editor)

Due to the variability of packaging DOS games, adding DOS-based games in the Feed Editor must be done manually (versus using auto-detection).

See the Adding Disc and Archive-based Items section for details on adding DOS-based games in the Feed Editor.

Important

Both the Safari (iOS and macOS) and Xbox Series X|S Edge browsers limit the amount of memory that can be consumed by a particular web application (such as webЯcade).

On macOS, it is recommended that the Chrome Browser be utilized to increase the size of DOS games that can be loaded.

To increase the likelihood of loading larger DOS games on iOS and Xbox you can optionally choose to launch the game using a standalone-based link (versus launching the game within the webЯcade player or editor). See the Standalone section of this documentation for further information (On Xbox, you would most likely want to bookmark the direct link. On iOS, you would most likely want to add the game to the home screen).

On-screen Controls

The DOS application includes a set of on-screen controls which are detailed below.

Button		Description
Virtual Keyboard		Displays the Virtual Keyboard.
Pause (Show Pause Screen)		Displays the webЯcade pause screen.

Virtual Keyboard

The DOS application includes a virtual keyboard that can be utilized on devices that don't have a physical keyboard readily available (mobile, Xbox, etc.).

Display of the virtual keyboard can be toggled via the "Virtual Keyboard" button within the On-screen controls.

Special Keys

The virtual keyboard includes the following "special" keys.

Key		Description
Switch to Letters Mode		Pressing this key will switch to the Letters Mode of the keyboard.
Switch to Numbers Mode		Pressing this key will switch to the Numbers Mode of the keyboard.
Switch to Symbols Mode		Pressing this key will switch to the Symbols Mode of the keyboard.
Change Keyboard Position		Toggles between the various keyboard positions (center, bottom, etc.). This key is available via the Numbers Mode of the keyboard.

Letters Mode

This mode primarily contains letters.

Numbers Mode

This mode primarily contains numbers, the ESCAPE key, and the ability to toggle holding down the SHIFT and CONTROL keys.

Symbols Mode

This mode primarily contains symbols and FUNCTION keys.

Pause Screen

The DOS application's pause screen provides access to DOS Application Settings.

DOS Settings

The DOS application includes a custom settings dialog.

To access these settings, display the "Pause" screen and select the "DOS Settings" option (See screenshot above).

DOS Settings Tab

The DOS Application's "settings" tab is detailed below.

Field	Description
Controller Mode (Session)	Allows for selecting between Gamepad and Mouse emulation controller modes.
Force Start Menu (On Load)	Enabling this option forces the DOSBox Pure Start Menu to always appear when launching a game, regardless of the auto-start settings or executables found for the game.

Display Settings Tab

The DOS application's "Display Settings" tab is detailed below.

Field Description

Screen size

The screen size to use when playing a game.

Options include:

Native : The application's native resolution
16:9 : Widescreen resolution
Fill : Fill the entire contents of the screen

On-screen controls Toggle whether the on-screen controls should always be displayed, or only displayed once touch input has been detected.

Show system pointer

Whether to always show the browser's mouse pointer in addition to the game-specific pointer.

While this essentially displays two pointers (on top of each other), it prevents not being able to find the mouse pointer when a game is not actively displaying one (during cut scenes, various modes, etc.).

Virtual Keyboard Settings

The DOS application's "Virtual Keyboard Settings" tab is detailed below.

Field

Description

Transparency

Toggles the degree of transparency the virtual keyboard should have.

A higher degree of transparency allows more of the game to be visible through the keyboard (which may make the keyboard itself less visible).

View Controls

The View Controls settings provide information about how controls are mapped for the current game. To access these settings, display the "Pause" screen and select the "View Controls" option.

Gamepad Controls Tab

The Gamepad Controls tab shows how the gamepad is mapped to the current game (See screenshot above).

The DOSBox Pure Start Menu will appear when a game is launched without an autoStartPath set in the feed, no executable has been previously set to auto-start via this menu, or multiple executables are found.

This menu allows for selecting which executable to launch and provides the option to set that executable to auto-start for future sessions on the current device. Additionally, it allows for adjusting the mappings of keyboard and mouse input to the controller (gamepad).

It is important to note that this menu will not appear if an executable has been specified to auto-start (either in the feed or previously via the menu), or if only a single executable is found for the game.

However, you can force this menu to always display by enabling the "Force Start Menu" option in the DOS Settings portion of the webЯcade pause screen. If this option is enabled, the menu will always appear on any game that is launched, regardless of the auto-start settings, or executables found for the game.

Saving Changes to Media

This application supports persisting changes to a game's media (hard disks, etc.) into the browser's local storage or optionally to cloud-based storage.

Feed

This section details how DOS application instances can be added to feeds.

Type

The type name for the DOS application is retro-dosbox-pure.

Note

The alias dos also currently maps to this application. In the future, the dos alias may be mapped to another DOS application (different engine implementation) if it is determined to be a more appropriate default.

Properties

The table below contains the properties that are specific to the DOS application. These properties are specified in the props object of a feed item.

Property	Type	Required	Details
uid	String	Yes	A unique identifier for the particular game (must be unique across all DOS games). This identifier is primarily used to associate persistent state with the game.
archive	URL	Yes	URL to a DOS game archive (`.zip`) or webЯcade package archive manifest (`.json`) file.
autoStartPath	String	No	A path to the binary to launch when the game starts. Partial file names and paths are supported. For example, specifying `run.bat` would launch the first file it finds that matches, such as `first_run.bat`, `go_run.bat`, etc. Using `autoStartPath` is equivalent to setting an "Auto Run" in the DOSBox Pure Start Menu when the game is first launched on a device. However, unlike the Start Menu option, this setting is part of the feed itself, ensuring the specified binary automatically launches on any device that uses the feed.
controllerMode	Numeric	No	Specifies the mode for the gamepad when the game is first launched (defaults to 0). `0` : Gamepad mode `1` : Mouse Emulation mode
mouseSpeed	Numeric	No	A numeric value ranging from `-5` to `5`, with `0` as the default. This controls the mouse speed for the current game. Positive values increase the mouse speed, while negative values slow it down.
zoomLevel	Numeric	No	A numeric value indicating how much the display image should be zoomed in (0-40).

Example

The following is an example of a complete feed that consists of a single DOS application instance (type value of dos). The archive property value is a URL that points to a Dropbox location that contains a webЯcade package archive manifest file for the game, "Tyrian 2000".

{
  "title": "DOS Feed",
  "categories": [
    {
      "title": "DOS Games",
      "items": [
        {
          "title": "Tyrian 2000",
          "type": "dos",
          "props": {
            "uid": "e3e4781c-9ac2-45ef-8a7d-1a9648799e09",
            "archive": "https://www.dropbox.com/scl/fi/yas4deya9t2y83y2t2fjr/tyrian2000.zip?rlkey=7gz61f8peuyrzdfqgc8u3d8tf&dl=0"
          }
        }
      ]
    }
  ]
}

This example can be tested by adding a feed with the following URL within the webЯcade player:

http://tinyurl.com/sample-dos-feed

References

DOS Application GitHub Repository