API Documentation

API Documentation

Overview

DosKit provides a programmatic API for controlling the DOS emulator and accessing its features. This document describes the available APIs and how to use them.

Command Interface

The primary API for controlling the emulator is the Command Interface (CI), provided by js-dos.

Getting the Command Interface

import { DosPlayer } from './components/DosPlayer';
import type { CommandInterface } from './types/js-dos';

function MyApp() {
  const [ci, setCi] = useState<CommandInterface | null>(null);

  const handleReady = (commandInterface: CommandInterface) => {
    setCi(commandInterface);
    console.log('Emulator ready!');
  };

  return <DosPlayer onReady={handleReady} />;
}

Core Methods

Emulation Control

ci.pause()

Pause the emulator.

ci.pause();

ci.resume()

Resume the emulator.

ci.resume();

ci.exit()

Stop the emulator and clean up resources.

ci.exit();

Audio Control

ci.mute()

Mute audio output.

ci.mute();

ci.unmute()

Unmute audio output.

ci.unmute();

Input Simulation

ci.simulateKeyPress(keyCode: number)

Simulate a key press.

// Press Enter (keyCode 13)
ci.simulateKeyPress(13);

// Press Escape (keyCode 27)
ci.simulateKeyPress(27);

Common Key Codes:

• Enter: 13
• Escape: 27
• Space: 32
• Arrow Up: 38
• Arrow Down: 40
• Arrow Left: 37
• Arrow Right: 39

Screenshot

ci.screenshot(): Promise<ImageData>

Capture a screenshot of the current screen.

const imageData = await ci.screenshot();
const canvas = document.createElement('canvas');
canvas.width = imageData.width;
canvas.height = imageData.height;
const ctx = canvas.getContext('2d');
ctx.putImageData(imageData, 0, 0);

// Convert to blob and download
canvas.toBlob((blob) => {
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = 'screenshot.png';
  a.click();
});

File System Access

ci.fsReadFile(path: string): Promise<Uint8Array>

Read a file from the virtual file system.

const data = await ci.fsReadFile('/C/AUTOEXEC.BAT');
const text = new TextDecoder().decode(data);
console.log(text);

ci.fsWriteFile(path: string, data: Uint8Array): Promise<void>

Write a file to the virtual file system.

const text = 'echo Hello World';
const data = new TextEncoder().encode(text);
await ci.fsWriteFile('/C/HELLO.BAT', data);

Save State

ci.save(): Promise<Uint8Array>

Save the current emulator state.

const state = await ci.save();
// Store in IndexedDB or localStorage
localStorage.setItem('saveState', JSON.stringify(Array.from(state)));

ci.load(state: Uint8Array): Promise<void>

Load a previously saved state.

const stateArray = JSON.parse(localStorage.getItem('saveState'));
const state = new Uint8Array(stateArray);
await ci.load(state);

DosPlayer Component Props

Props

interface DosPlayerProps {
  onReady?: (ci: CommandInterface) => void;
  onError?: (error: Error) => void;
  onExit?: () => void;
  dosboxConf?: string;
  jsdosOptions?: Partial<JsDosOptions>;
  files?: Record<string, ArrayBuffer>;
}

Example Usage

<DosPlayer
  onReady={(ci) => console.log('Ready!', ci)}
  onError={(error) => console.error('Error:', error)}
  onExit={() => console.log('Exited')}
  dosboxConf={customDosboxConf}
  jsdosOptions={{ renderBackend: 'webgl' }}
  files={{ 'game.exe': gameData }}
/>

js-dos Options

Configure js-dos behavior:

interface JsDosOptions {
  backend: 'dosbox' | 'dosbox-x';
  workerThread: boolean;
  offscreenCanvas: boolean;
  renderBackend: 'webgl' | 'canvas';
  imageRendering: 'smooth' | 'pixelated';
  volume: number; // 0.0 to 1.0
}

Default Options

const defaultOptions: JsDosOptions = {
  backend: 'dosbox',
  workerThread: true,
  offscreenCanvas: true,
  renderBackend: 'webgl',
  imageRendering: 'pixelated',
  volume: 0.7,
};

Events

Emulator Events

The Command Interface emits events you can listen to:

ci.events.onMessage((message) => {
  console.log('Message:', message);
});

ci.events.onExit(() => {
  console.log('Emulator exited');
});

ci.events.onError((error) => {
  console.error('Error:', error);
});

TypeScript Types

All types are available in src/types/js-dos.d.ts:

import type {
  CommandInterface,
  JsDosOptions,
  DosApp,
  DosboxConfig,
} from './types/js-dos';

Related Documentation

• Usage - General usage guide
• Configuration - Configure DosKit
• Architecture - Technical architecture

---

Made with ❤️ by Cameron Rye