Player API

js-dos player provides a single entry point a Dos function, it takes two arguments:

element where to create a player window
options object to configure player

Dos(element: HTMLDivElement, options: DosOptions) => DosProps;

It returns DosProps to a control created player

Options

option	description	type	default
url	url to js-dos bundle	URL
dosboxConf	if you omit url this will be used to configure DOSBox example	str
jsdosConf	additionally to dosboxConf you can provide jsdos configuration (jsdos.json)	Object	{}
initFs	additional files to init FS, read more	`Array< { path: string, contents: Uint8Array } >`
background	background image of player window	URL
pathPrefix	a way to set different path for emulators deployment	str
theme	the color theme of player	light, dark, cupcake, bumblebee, emerald, corporate, synthwave, retro, cyberpunk, valentine, halloween, garden, forest, aqua, lofi, pastel, fantasy, wireframe, black, luxury, dracula, cmyk, autumn, business, acid, lemonade, night, coffee, winter	light
lang	language	en, ru	auto
backend	default backend	dosbox, dosboxX	dosbox
backendLocked	possibility to change backend from UI	bool	false
backendHardware	reserved	-
workerThread	use Worker	bool	true
mouseCapture	lock the mouse in player window	bool	false
server	ipx server	netherlands, newyork, singapore	netherlands
room	ipx room	str
fullScreen	auto enter fullscreen mode	bool	false
onEvent	listener of js-dos events	function
autoStart	automatically starts emulation	boolean	false
kiosk	switch kiosk mode, in kiosk mode player ui is hidden	boolean	false
imageRendering	image rendering mode	pixelated, smooth	pixelated
renderBackend	the way to render dos screen	webgl, canvas	webgl
renderAspect	change the aspect of output window	AsIs, 1/1, 5/4, 4/3, 16/10, 16/9, Fit	AsIs
noNetworking	hide networking button	bool	true
noCloud	disable cloud feature	bool	false
key	set the key to access cloud services	string
scaleControls	set scale of controls	number	0.2
mouseSensitivity	set mouse sensitivity	number	1.0
noCursor	show/hide system cursor	bool	false
volume	set sound volume	number [0..1]	1.0
softKeyboardLayout	initial virtual keyboard layout, read more	srting[]	qwerty
softKeyboardSymbols	initial virtual keyboard symbols	map[]	en, ru

DosProps

DosProps is a properties that you can use to control player after creation, use it like this:

cost props = Dos(elem, options);
props.setFullScreen(true); // switch to fullscreen mode

property	description	arguments
setTheme	switch player theme	theme name
setLang	change language	en, ru
setBackend	change backend	dosbox, dosboxX
setBackendLocked	change is backend locked or not	bool
setWorkerThread	select execution mode	bool
setMouseCapture	set is mouse captured or not	bool
setServer	change ipx server	str
setRoom	change ipx room	str
setFrame	open named sidebar panel	network
setBackground	change background image	URL
setFullScreen	change fullscreen mode	bool
setAutoStart	change auto start	bool
setKiosk	change kisok mode	bool
setImageRendering	change image rendering	pixelated, smooth
setRenderBackend	change render backend (available only before emulation start)	webgl
setRenderAspect	change render aspect	AsIs, 1/1, 5/4, 4/3, 16/10, 16/9, Fit
setNoNetworking	show/hide networking button	bool
setNoCloud	disable/enable cloud feature	bool
setKey	set key to access cloud services	string / null
setScaleControls	set scale of controls	number
setMouseSensitivity	set mouse sensitivity	number
setPaused	pause/resume emulation	bool
setNoCursor	show/hide system cursor	bool
setVolume	set sound volume	number [0..1]
setSoftKeyboardLayout	set virtual keyboard layout	string[]
setSoftKeyboardSymbols	set virtual keyboard symbols	map[]
save	trigger to save changes in FS, return `Promise<boolean>`	-
stop	kill the emulation (use to stop player)	-

Events

You can listen to js-dos event by providing listener in Dos function:

Dos(elem, {
    onEvent: (event , ci?: [[[CommandInterface|command-interface.html]]]) => {
       console.log("js-dos event", event); 
    }
});

order	event	description	args
0	emu-ready	when emulators are fully loaded and ready to run the program
1	bnd-play	when play button is clicked
2	ci-ready	when backend is started and CommandInterface is available	CommandInterface

Stop/Restart player

To stop player and free all used resources, please call props.stop(), after this player is totally disposed.
To restart player dispose current player and start new one.

Typescript

js-dos provide Typescript types declaration. Just put it somewhere in your codebase, and declare Dos function:

import {DosFn} from "types";

declare const Dos: DosFn;

// ...

Dos(element, options)

export type DosEvent = "emu-ready" | "ci-ready" | "bnd-play" | "open-key"; export type ImageRendering = "pixelated" | "smooth"; export type RenderBackend = "webgl" | "canvas"; export type RenderAspect = "AsIs" | "1/1" | "5/4" | "4/3" | "16/10" | "16/9" | "Fit"; export type InitBundleEntry = Uint8Array; export interface InitFileEntry { path: string; contents: Uint8Array; } export type InitFsEntry = InitBundleEntry | InitFileEntry; export type InitFs = InitFsEntry | InitFsEntry[]; export interface DosOptions { url: string, dosboxConf: string, jsdosConf: any, initFs: InitFs, background: string, pathPrefix: string, theme: "light" | "dark" | "cupcake" | "bumblebee" | "emerald" | "corporate" | "synthwave" | "retro" | "cyberpunk" | "valentine" | "halloween" | "garden" | "forest" | "aqua" | "lofi" | "pastel" | "fantasy" | "wireframe" | "black" | "luxury" | "dracula" | "cmyk" | "autumn" | "business" | "acid" | "lemonade" | "night" | "coffee" | "winter", lang: "ru" | "en", backend: "dosbox" | "dosboxX", backendLocked: boolean, backendHardware: ((backend: "dosbox" | "dosboxX") => Promise<string | null>), workerThread: boolean, mouseCapture: boolean, onEvent: (event: DosEvent, ci?: any /* CommandInterface */) => void, server: "netherlands" | "newyork" | "singapore", room: string, fullScreen: boolean, sockdriveBackend: { name: string, host: string, }, autoStart: boolean, kiosk: boolean, imageRendering: ImageRendering, renderBackend: RenderBackend, renderAspect: RenderAspect, noNetworking: boolean, noCloud: boolean, scaleControls: number, mouseSensitivity: number, noCursor: boolean, softKeyboardLayout: string[] | string[][][], softKeyboardSymbols: {[key: string]: string}[], volume: number, key: string, } export interface DosProps { setTheme(theme: DosOptions["theme"]): void; setLang(lang: DosOptions["lang"]): void; setBackend(backend: DosOptions["backend"]): void; setBackendLocked(locked: boolean): void; setWorkerThread(capture: DosOptions["workerThread"]): void; setMouseCapture(capture: DosOptions["mouseCapture"]): void; setServer(server: DosOptions["server"]): void; setRoom(room: DosOptions["room"]): void; setFrame(frame: "network"): void; setBackground(background: string | null): void; setFullScreen(fullScreen: boolean): void; setAutoStart(autoStart: boolean): void; setKiosk(kiosk: boolean): void; setImageRendering(rendering: ImageRendering): void; setRenderBackend(backend: RenderBackend): void; setRenderAspect(aspect: RenderAspect): void; setNoNetworking(noNetworking: boolean): void; setNoCloud(noCloud: boolean): void; setPaused(pause: boolean): void; setScaleControls(scaleControls: number): void; setMouseSensitivity(mouseSensitivity: number): void; setNoCursor(noCursor: boolean): void; setSoftKeyboardLayout(layout: string[] | string[][][]): void; setSoftKeyboardSymbols(symbols: {[key: string]: string}[]): void; setVolume(volume: number): void; setKey(key: string | null): void; save(): Promise<boolean>; stop(): Promise<void>; } export type DosFn = (element: HTMLDivElement, options: Partial<DosOptions>) => DosProps; // declare const Dos: DosFn;

Last modified: 13 октября 2024