Nostalgist.js

https://nostalgist.js.org/
Admin
Nostalgist.js is a JavaScript library that allows you to run emulators of retro consoles like NES,...
Tokens:14,334
Snippets:140
Trust Score:8.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Start Emulator

Source: https://nostalgist.js.org/apis/start

Starts the emulator. This method should always be used in conjunction with `Nostalgist.prepare`.

```APIDOC
## POST /start

### Description
Starts the emulator. This method should always be used in conjunction with `Nostalgist.prepare`.

### Method
POST

### Endpoint
/start

### Parameters

### Request Body
This method does not require a request body.

### Request Example
```javascript
// This may take a long time 🥱
const nostalgist = await Nostalgist.prepare({
  core: 'fceumm',
  rom: 'flappybird.nes',
})


const startButton = document.querySelector('.start-button')
startButton.addEventListener('click', async () => {
  // The emulator will be launched in no time 🚀
  await nostalgist.start()
})
```

### Response
#### Success Response (200)
This method does not return a specific value upon success, but initiates the emulator.

#### Response Example
(No specific response body for success)
```

--------------------------------

### Prepare and Start Nostalgist Emulator

Source: https://nostalgist.js.org/apis/start

Use Nostalgist.prepare to load game assets and then call nostalgist.start() to launch the emulator. Ensure Nostalgist.prepare is always called before starting the emulator.

```javascript
const nostalgist = await Nostalgist.prepare({
  core: 'fceumm',
  rom: 'flappybird.nes',
})


const startButton = document.querySelector('.start-button')
startButton.addEventListener('click', async () => {
  // The emulator will be launched in no time 🚀
  await nostalgist.start()
})
```

--------------------------------

### Configure player controls with retroarchConfig

Source: https://nostalgist.js.org/apis/press-down

Example of setting up key bindings for additional players during the launch process.

```javascript
await Nostalgist.launch({
  retroarchConfig: {
    input_player2_down: 'num3',
    input_player2_left: 'num2',
    input_player2_right: 'num4',
    // see https://github.com/libretro/RetroArch/blob/575859e5d76d921cb490f55afcd0bbca90d4a742/retroarch.cfg#L468-L483
    input_player2_up: 'num1',
  },


  /* ...other options */
})
```

--------------------------------

### Install Nostalgist.js with npm

Source: https://nostalgist.js.org/guides/getting-started

Install Nostalgist.js into your modern frontend project using npm or other package managers. Then import and use the Nostalgist class.

```bash
npm i nostalgist 
```

```bash
yarn add nostalgist 
```

```bash
pnpm i nostalgist 
```

```bash
bun i nostalgist 
```

```javascript
import { Nostalgist } from 'nostalgist'


await Nostalgist.nes('flappybird')
```

--------------------------------

### Prepare emulator files and launch on demand

Source: https://nostalgist.js.org/apis/prepare

Use prepare to load emulator files asynchronously. Call start later to launch the emulator, which may require user interaction in some browsers.

```javascript
// This may take a long time 🥱
const nostalgist = await Nostalgist.prepare({
  core: 'fceumm',
  rom: 'flappybird.nes',
})


const startButton = document.querySelector('.start-button')
startButton.addEventListener('click', async () => {
  // The emulator will be launched in no time 🚀
  await nostalgist.start()
})
```

--------------------------------

### Manually launch the emulator

Source: https://nostalgist.js.org/apis/launch-emulator

Use this method when runEmulatorManually is set to true to start the emulator instance.

```javascript
// the emulator will not be launched
const nostalgist = await Nostalgist.nes({ rom: 'flappybird.nes', runEmulatorManually: true })


// the emulator is going to be launched
await nostalgist.launchEmulator()
```

--------------------------------

### Launch Game with Button Click Listener

Source: https://nostalgist.js.org/

An example of launching an NES emulator when a button is clicked. This involves importing Nostalgist and setting up an event listener.

```javascript
import './style.css'
import { Nostalgist } from 'nostalgist'
async function launchGame() {
// launch Flappy Bird with an NES emulator!
await Nostalgist.nes('flappybird.nes')
}
const button = document.querySelector('#launch-button')
button.addEventListener('click', launchGame)
```

--------------------------------

### Simulate button presses with Nostalgist.js

Source: https://nostalgist.js.org/apis/press

Examples of using the press method with different button, player, and timing configurations.

```javascript
const nostalgist = await Nostalgist.nes('flappybird.nes')


await nostalgist.press('select')
await nostalgist.press('start')
await nostalgist.press('a')
await nostalgist.press('left')
await nostalgist.press('l')
await nostalgist.press({ button: 'a', player: 2 }) // press the button "a" on player 2's controller
await nostalgist.press({ button: 'a', time: 200 }) // press the button "a" for 200 milliseconds
await nostalgist.press({ button: 'a', player: 2, time: 200 }) // press the button "a" on player 2's controller for 200 milliseconds
```

--------------------------------

### Launch Games in Browser DevTools

Source: https://nostalgist.js.org/guides/getting-started

Use the global Nostalgist object in your browser's DevTools to launch various retro games. No additional setup is required.

```javascript
await Nostalgist.nes('flappybird.nes')


// Launch a Sega Genesis game
await Nostalgist.megadrive('30yearsofnintendont.bin')


// Launch a GBA game
await Nostalgist.gba('eliminator.gba')


// Or choose a ROM file from your disk
await Nostalgist.nes(showOpenFilePicker)
```

--------------------------------

### Save and Load Game SRAM with Nostalgist.js

Source: https://nostalgist.js.org/apis/save-sram

Use saveSRAM to get the current game's SRAM, and then pass it to the Nostalgist constructor to load it in a subsequent session. Requires initializing Nostalgist with a ROM.

```javascript
const nostalgist = await Nostalgist.nes('zelda.nes')


// save the SRAM
const sram = await nostalgist.saveSRAM()


// launch with the SRAM
await nostalgist.nes({
  rom: 'zelda.nes',
  sram,
})
```

--------------------------------

### Configure Player 2 Input Bindings

Source: https://nostalgist.js.org/apis/press-up

When controlling players other than player 1, ensure key bindings for the desired player are set in retroarchConfig during launch. This example shows how to bind player 2's directional inputs.

```javascript
await Nostalgist.launch({
  retroarchConfig: {
    input_player2_down: 'num3',
    input_player2_left: 'num2',
    input_player2_right: 'num4',
    // see https://github.com/libretro/RetroArch/blob/575859e5d76d921cb490f55afcd0bbca90d4a742/retroarch.cfg#L468-L483
    input_player2_up: 'num1',
  },

  /* ...other options */
})
```

--------------------------------

### Get Emulator Status

Source: https://nostalgist.js.org/apis/get-status

Retrieves the current status of the emulator instance. The status indicates the emulator's lifecycle stage.

```APIDOC
## GET /emulator/status

### Description
Get the current status of the emulator instance.

### Method
GET

### Endpoint
/emulator/status

### Returns
#### Success Response (200)
- **status** (string) - A string representing the current status of the emulator instance. Can be one of: 'initial', 'running', 'paused', 'terminated'.

### Response Example
```json
{
  "status": "running"
}
```
```

--------------------------------

### Get Emscripten Module and Take Screenshot

Source: https://nostalgist.js.org/apis/get-emscripten-module

Obtain the Emscripten Module object from a running Nostalgist emulator to execute low-level commands. Ensure the emulator is initialized before calling this function.

```javascript
const nostalgist = await Nostalgist.nes('flappybird.nes')


const Module = nostalgist.getEmscriptenModule()
Module._cmd_take_screenshot()
```

--------------------------------

### Get Emscripten File System Object

Source: https://nostalgist.js.org/apis/get-emscripten-fs

Retrieves the Emscripten File System object for the currently running emulator, allowing access to its virtual file system. Refer to the Emscripten File System API for more details.

```APIDOC
## GET /emscripten/fs

### Description
Get the Emscripten FS object of the currently running emulator to access its virtual file system. See Emscripten File System API for more information.

### Method
GET

### Endpoint
/emscripten/fs

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **FS** (object) - The Emscripten File System object.

#### Response Example
```javascript
// Assuming 'nostalgist' is an instance of Nostalgist
const FS = nostalgist.getEmscriptenFS();
const files = FS.readdir('/home/web_user/retroarch/userdata');
console.log(files);
```
```

--------------------------------

### Get Emscripten Object from Nostalgist Emulator

Source: https://nostalgist.js.org/apis/get-emscripten

Retrieve the Emscripten object after initializing a Nostalgist emulator. This object exposes AL, Browser, exit, JSEvents, and Module for advanced control.

```javascript
const nostalgist = await Nostalgist.nes('flappybird.nes')


const { AL, Browser, exit, JSEvents, Module } = nostalgist.getEmscripten()
```

--------------------------------

### Launch an emulator with basic configuration

Source: https://nostalgist.js.org/apis/launch

Initializes an emulator instance using a specified core and ROM file.

```javascript
const nostalgist = await Nostalgist.launch({
  core: 'fceumm',
  rom: 'flappybird.nes',
})
```

--------------------------------

### Nostalgist.launch Configuration Parameters

Source: https://nostalgist.js.org/apis/launch

Configuration options for initializing the emulator environment.

```APIDOC
## Nostalgist.launch Configuration

### Parameters
- **shader** (string) - Optional - The name of a shader. Defaults to loading from libretro/glsl-shaders via jsDelivr.
- **style** (Object) - Optional - CSS style for the canvas element. Use camelCase for property names and string values.
- **size** ('auto' | { width: number, height: number }) - Optional - The size of the canvas element. Defaults to 'auto'.
- **signal** (Object) - Optional - An AbortSignal object used for cancelling a launch.
- **cache** (boolean | { bios: boolean, core: boolean, rom: boolean, shader: boolean }) - Optional - Whether to cache loaded files. Defaults to false.
- **retroarchConfig** (Object) - Optional - Custom configuration content for retroarch.cfg.
- **retroarchCoreConfig** (Object) - Optional - Custom configuration content for the core option file.
- **runEmulatorManually** (boolean) - Optional - Whether to run the emulator manually. Defaults to false.

### Request Example
{
  "core": "fceumm",
  "rom": "flappybird.nes",
  "cache": true,
  "style": {
    "backgroundColor": "black"
  }
}
```

--------------------------------

### Nostalgist.launch

Source: https://nostalgist.js.org/apis/launch

Initializes the emulator with the provided configuration options.

```APIDOC
## Nostalgist.launch

### Description
Launches the emulator and game based on the provided configuration object.

### Parameters
#### Request Body
- **options** (Object) - Required - Configuration object for the emulator launch.
  - **element** (string | HTMLCanvasElement) - Optional - The canvas element to render the emulator. Defaults to an empty string (auto-created).
  - **core** (string | Object) - Required - The emulator core. Can be a string (e.g., 'snes9x') or an object containing { name, js, wasm }.
  - **rom** (resolvable file | Array) - Required - The game ROM file(s) to load.
  - **bios** (resolvable file | Array) - Optional - BIOS files to be written to the system directory.
  - **state** (resolvable file) - Optional - Initial state to load after launch.
  - **sram** (resolvable file) - Optional - Initial SRAM to load after launch.
  - **sramType** (string) - Optional - Save file battery type ('srm' or 'sav'). Defaults to 'srm'.

### Request Example
```javascript
await Nostalgist.launch({
  core: {
    js: 'https://example.com/cores/snes9x.js',
    name: 'snes9x',
    wasm: 'https://example.com/cores/snes9x.wasm',
  },
  rom: 'https://example.com/roms/super-metroid.sfc',
})
```
```

--------------------------------

### Launch with default ROM resolution

Source: https://nostalgist.js.org/apis/launch

Load a ROM from the default retrobrews repository by providing the filename.

```javascript
await Nostalgist.launch({
  core: 'fceumm',
  rom: 'flappybird.nes',
})
```

--------------------------------

### Load custom shaders via beforeLaunch

Source: https://nostalgist.js.org/apis/launch

Use the beforeLaunch hook to manually write shader files to the Emscripten file system when standard loading patterns do not apply.

```javascript
await Nostalgist.launch({
  core: 'fceumm',
  rom: 'flappybird.nes',


  async beforeLaunch(nostalgist) {
    const FS = nostalgist.getEmscriptenFS()


    const glslp = await fetch('https://cdn.jsdelivr.net/gh/libretro/glsl-shaders/crt/crt-easymode.glslp')
    const glsl = await fetch('https://cdn.jsdelivr.net/gh/libretro/glsl-shaders/crt/shaders/crt-easymode.glsl')


    // Put all shader files into shaders/shaders_glsl directory
    FS.writeFile('/home/web_user/retroarch/bundle/shaders/shaders_glsl/crt-easymode.glslp', await glslp.text())
    FS.writeFile(
      '/home/web_user/retroarch/bundle/shaders/shaders_glsl/shaders/crt-easymode.glsl',
      await glsl.text(),
    )


    // Enable the shader in the global shader config file config/global.glslp
    FS.writeFile(
      '/home/web_user/retroarch/userdata/config/global.glslp',
      '#reference /home/web_user/retroarch/bundle/shaders/shaders_glsl/crt-easymode.glslp',
    )
  },
})
```

--------------------------------

### Instance Methods

Source: https://nostalgist.js.org/apis

Instance methods allow for fine-grained control over a running emulator instance.

```APIDOC
## Instance Methods

### Description
Instance methods provide control over a specific, running emulator instance, including state management, playback control, and interaction.

### Methods
- `saveState`: Saves the current state of the emulator.
- `loadState`: Loads a previously saved state into the emulator.
- `saveSRAM`: Saves the Save RAM data.
- `start`: Starts or resumes emulator playback.
- `restart`: Restarts the current emulator session.
- `pause`: Pauses emulator playback.
- `resume`: Resumes paused emulator playback.
- `exit`: Exits the current emulator session.
- `resize`: Resizes the emulator canvas.
- `press`: Simulates a button press on the controller.
- `screenshot`: Takes a screenshot of the current emulator screen.
- `getStatus`: Retrieves the current status of the emulator.
- `getCanvas` (advanced): Gets the emulator's canvas element.
- `getEmscripten` (advanced): Gets the Emscripten module.
- `getEmscriptenAL` (advanced): Gets the Emscripten audio library.
- `getEmscriptenFS` (advanced): Gets the Emscripten file system.
- `getEmscriptenModule` (advanced): Gets the Emscripten module instance.
- `launchEmulator` (advanced): Launches an emulator instance programmatically.
- `pressDown` (advanced): Simulates pressing the down button.
- `pressUp` (advanced): Simulates pressing the up button.
- `sendCommand` (advanced): Sends a custom command to the emulator.
```

--------------------------------

### Launch GBA ROM with Nostalgist.gba

Source: https://nostalgist.js.org/apis/gba

Demonstrates the basic usage of the gba method and its equivalence to the standard launch method.

```javascript
await Nostalgist.gba('anotherworld.gba')


// is equal to
await Nostalgist.launch({ core: 'mgba', rom: 'anotherworld.gba' })
```

--------------------------------

### Nostalgist.launch

Source: https://nostalgist.js.org/apis/launch

Launches an emulator instance and returns a Promise that resolves to the emulator instance.

```APIDOC
## Nostalgist.launch

### Description
Launches an emulator and returns a Promise of the emulator instance. It is recommended to use `Nostalgist.prepare` and `<instance>.start` if loading files through a network.

### Parameters
#### Request Body
- **core** (string) - Required - The core identifier to use (e.g., 'fceumm', 'fbneo').
- **rom** (string|array) - Required - The ROM file path or array of paths.
- **element** (HTMLElement) - Optional - The DOM element to render the emulator canvas.
- **bios** (array) - Optional - Array of BIOS file paths.
- **retroarchConfig** (object) - Optional - Custom configuration settings for RetroArch.
- **resolveCoreJs** (function) - Optional - Custom resolver for core JavaScript files.
- **resolveCoreWasm** (function) - Optional - Custom resolver for core WebAssembly files.
- **resolveRom** (function) - Optional - Custom resolver for ROM file paths.
- **resolveBios** (function) - Optional - Custom resolver for BIOS file paths.

### Request Example
{
  "core": "fceumm",
  "rom": "flappybird.nes"
}

### Response
#### Success Response (200)
- **instance** (object) - The initialized emulator instance.
```

--------------------------------

### Launch an emulator with advanced configuration

Source: https://nostalgist.js.org/apis/launch

Configures an emulator with custom DOM elements, remote file resolution, and specific RetroArch settings.

```javascript
const nostalgist = await Nostalgist.launch({
  element: document.querySelector('.emulator-canvas'),


  // Will load https://example.com/core/fbneo_libretro.js and https://example.com/core/fbneo_libretro.wasm as the launching core
  // Because of the custom `resolveCoreJs` and `resolveCoreWasm` options
  core: 'fbneo',


  // Will load https://example.com/roms/mslug.zip as the ROM
  // Because of the custom `resolveRom` option
  rom: ['mslug.zip'],


  // Will load https://example.com/system/neogeo.zip as the BIOS
  // Because of the custom `resolveBios` option
  bios: ['neogeo.zip'],


  // Custom configuration for RetroArch
  retroarchConfig: {
    rewind_enable: true,
    savestate_thumbnail_enable: true,
  },


  // Specify where to load the core files
  resolveCoreJs(core) {
    return `https://example.com/core/${core}_libretro.js`
  },
  resolveCoreWasm(core) {
    return `https://example.com/core/${core}_libretro.wasm`
  },


  // Specify where to load the ROM files
  resolveRom(file) {
    return `https://example.com/roms/${file}`
  },


  // Specify where to load the BIOS files
  resolveBios(bios) {
    return `https://example.com/system/${bios}`
  },
})
```

--------------------------------

### Basic SNES Emulation Launch

Source: https://nostalgist.js.org/apis/snes

Use this shortcut for launching SNES games with default `snes9x` core. It is equivalent to calling `Nostalgist.launch` with the `core` option set to `snes9x`.

```javascript
await Nostalgist.snes('jetpilotrising.sfc')
```

```javascript
await Nostalgist.launch({ core: 'snes9x', rom: 'jetpilotrising.sfc' })
```

--------------------------------

### Send a command to RetroArch

Source: https://nostalgist.js.org/apis/send-command

Initializes a game instance and sends a fast-forward command to the RetroArch core.

```javascript

const nostalgist = await Nostalgist.nes('flappybird.nes')


nostalgist.sendCommand('FAST_FORWARD')

```

--------------------------------

### Launch a Game Boy ROM

Source: https://nostalgist.js.org/apis/gb

Demonstrates the basic usage of the gb method and its equivalence to the standard launch method.

```javascript
await Nostalgist.gb('blastah.gb')


// is equal to
await Nostalgist.launch({ core: 'mgba', rom: 'blastah.gb' })
```

--------------------------------

### Basic Nostalgist.gbc Usage

Source: https://nostalgist.js.org/apis/gbc

Demonstrates the basic usage of the Nostalgist.gbc method for launching a GBC ROM. This is equivalent to calling Nostalgist.launch with specific options.

```javascript
await Nostalgist.gbc('combatsoccer.gbc')


// is equal to
await Nostalgist.launch({ core: 'mgba', rom: 'combatsoccer.gbc' })
```

--------------------------------

### Launch NES Emulator Quickly

Source: https://nostalgist.js.org/

Use this snippet in the browser's DevTools to quickly launch an NES emulator with a specified ROM. No imports are needed for this basic usage.

```javascript
await Nostalgist.nes('flappybird.nes')
```

--------------------------------

### Launch with custom core URLs

Source: https://nostalgist.js.org/apis/launch

Use an object to specify custom URLs for the emulator core's JS and WASM files.

```javascript
await Nostalgist.launch({
  core: {
    js: 'https://example.com/cores/snes9x.js',
    name: 'snes9x',
    wasm: 'https://example.com/cores/snes9x.wasm',
  },
  rom: 'https://example.com/roms/super-metroid.sfc',
})
```

--------------------------------

### screenshot()

Source: https://nostalgist.js.org/apis/screenshot

Captures the current game display and returns it as a Blob.

```APIDOC
## screenshot()

### Description
Takes a screenshot of the current game display and returns it as a Blob.

### Returns
A `Promise` of a PNG image as a `Blob` object.

### Request Example
```javascript
const nostalgist = await Nostalgist.nes('flappybird.nes')
const screenshot = await nostalgist.screenshot()
```
```

--------------------------------

### Customize RetroArch Configuration

Source: https://nostalgist.js.org/

Launches an emulator with custom RetroArch and core configurations. Import Nostalgist and provide configuration objects to the launch options.

```javascript
import { Nostalgist } from 'nostalgist'


const nostalgist = await Nostalgist.launch({
  core: 'fceumm',
  rom: 'flappybird.nes',
  retroarchConfig: {
    rewind_enable: true,
  },
  retroarchCoreConfig: {
    fceumm_turbo_enable: 'Both',
  },
})
```

--------------------------------

### launchEmulator

Source: https://nostalgist.js.org/apis/launch-emulator

Manually triggers the launch of the emulator instance when the runEmulatorManually configuration option is set to true.

```APIDOC
## launchEmulator

### Description
Launches the emulator instance. This is used when the `runEmulatorManually` option is set to `true` during initialization, preventing the emulator from starting automatically.

### Usage
```javascript
// Initialize with manual launch enabled
const nostalgist = await Nostalgist.nes({ rom: 'flappybird.nes', runEmulatorManually: true });

// Manually trigger the launch
await nostalgist.launchEmulator();
```
```

--------------------------------

### Launch NES game with Nostalgist.nes

Source: https://nostalgist.js.org/apis/nes

Demonstrates the shorthand syntax for launching an NES ROM compared to the full launch configuration.

```javascript
await Nostalgist.nes('flappybird.nes')


// is equal to
await Nostalgist.launch({ core: 'fceumm', rom: 'flappybird.nes' })
```

--------------------------------

### Nostalgist.launch Configuration

Source: https://nostalgist.js.org/apis/launch

Configuration options for the Nostalgist.launch method to control emulator behavior, file resolution, and lifecycle events.

```APIDOC
## Nostalgist.launch

### Description
Initializes a new emulator instance with the provided configuration options.

### Parameters
#### Request Body
- **runEmulatorManually** (boolean) - Optional - If true, the emulator will not start automatically; call <instance>.launchEmulator() to start.
- **emscriptenModule** (Object) - Optional - Override the Module object for Emscripten.
- **respondToGlobalEvents** (boolean) - Optional - Default: true. Whether user input events bind to the global root or the canvas.
- **resolveCoreJs** (Function) - Optional - Custom function to resolve the RetroArch core JS file.
- **resolveCoreWasm** (Function) - Optional - Custom function to resolve the RetroArch core WASM file.
- **resolveRom** (Function) - Optional - Custom function to resolve the ROM file.
- **resolveBios** (Function) - Optional - Custom function to resolve the BIOS file.
- **resolveShader** (Function) - Optional - Custom function to resolve shader files (glslp/glsl).
- **beforeLaunch** (Function) - Optional - Hook executed before the emulator launches. Receives the Nostalgist instance.
- **onLaunch** (Function) - Optional - Hook executed after the emulator launches. Receives the Nostalgist instance.

### Response
#### Success Response (200)
- **Promise** (Object) - Returns a Promise that resolves to the emulator instance.
```

--------------------------------

### Static Methods

Source: https://nostalgist.js.org/apis

Static methods provide global control over the emulator instance.

```APIDOC
## Static Methods

### Description
Static methods offer global control and configuration for the Nostalgist.js emulator.

### Methods
- `launch`: Initializes and launches an emulator for a specific system.
- `configure`: Configures global settings for the emulator.
- `prepare`: Prepares the emulator environment.
- `nes`: Launches the NES emulator.
- `snes`: Launches the SNES emulator.
- `megadrive`: Launches the Sega Genesis (Mega Drive) emulator.
- `gb`: Launches the Game Boy emulator.
- `gbc`: Launches the Game Boy Color emulator.
- `gba`: Launches the Game Boy Advance emulator.
- `resetToDefault` (advanced): Resets the emulator to its default configuration.
```

--------------------------------

### Save and Load Game State

Source: https://nostalgist.js.org/apis/save-state

Demonstrates initializing a game, saving the current state, and reloading it later.

```javascript
const nostalgist = await Nostalgist.nes('flappybird.nes')


// Save the state
const { state } = await nostalgist.saveState()


// Load the state
await nostalgist.loadState(state)
```

--------------------------------

### Load NES ROM with Nostalgist.js

Source: https://nostalgist.js.org/guides/under-the-hood

Load a NES ROM from a specified URL using the Nostalgist.nes method. Ensure your server is configured with appropriate CORS headers.

```javascript
await Nostalgist.nes('https://your-server.com/roms/super-mario-bros.nes')
```

--------------------------------

### Enable file caching

Source: https://nostalgist.js.org/apis/launch

Enable caching to speed up subsequent launches with the same parameters.

```javascript
// This may take some time as files are loaded through network...
const nostalgist1 = await Nostalgist.launch({ cache: true, core: 'fceumm', rom: 'flappybird.nes' })


nostalgist1.exit()


// Will be launched instantly!
const nostalgist2 = await Nostalgist.launch({ cache: true, core: 'fceumm', rom: 'flappybird' })
```

--------------------------------

### Nostalgist.gb Method

Source: https://nostalgist.js.org/apis/gb

The `gb` method is a shortcut for `Nostalgist.launch` with default options for Game Boy emulation, using `mgba` as the default core.

```APIDOC
## POST /websites/nostalgist_js

### Description
Launches a Game Boy emulation using the `Nostalgist.gb` shortcut method.

### Method
POST

### Endpoint
`/websites/nostalgist_js`

### Parameters
#### Request Body
- **options** (string | Object) - Required - The ROM file or an options object for emulation. If a string, it's treated as `{ rom: options }`. If an object, it's passed directly to `Nostalgist.launch`.

### Request Example
```json
{
  "options": "blastah.gb"
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates successful launch of the emulator.

#### Response Example
```json
{
  "message": "Emulator launched successfully"
}
```
```

--------------------------------

### Launch RetroArch Emulator with Nostalgist.js

Source: https://nostalgist.js.org/

Launches a retro game using a specified RetroArch core and ROM. Ensure the 'nostalgist' library is imported before use.

```javascript
import { Nostalgist } from 'nostalgist'


await Nostalgist.launch({
  core: 'fceumm',
  rom: 'flappybird.nes',
})
```

--------------------------------

### Basic Megadrive Emulation Launch

Source: https://nostalgist.js.org/apis/megadrive

Use this shortcut for launching Sega Genesis/Megadrive games with default options. It automatically selects 'genesis_plus_gx' as the core.

```javascript
await Nostalgist.megadrive('30yearsofnintendont.bin')


// is equal to
await Nostalgist.launch({ core: 'genesis_plus_gx', rom: '30yearsofnintendont.bin' })
```

--------------------------------

### Define Resolvable Files via URL, URL Object, or Request

Source: https://nostalgist.js.org/apis/resolvable-file

Use these formats to load files via fetch, where the filename is inferred from the URL path.

```javascript
// URL strings
'http://www.example.com/roms/contra.nes'
'https://www.example.com/roms/contra.nes'
'blob:https://example.com/550e8400-e29b-41d4-a716-446655440000'
'data:application/octet-stream;base64,abcdefghijkl....'


// a URL object
new URL('/roms/contra.nes', 'http://www.example.com')


// a Request Object
new Request('http://www.example.com/roms/contra.nes')
```

--------------------------------

### Configure RetroArch core options

Source: https://nostalgist.js.org/apis/launch

Specify core-specific configuration settings using the retroarchCoreConfig parameter.

```javascript
const nostalgist = await Nostalgist.launch({
  core: 'fceumm',
  retroarchCoreConfig: {
    fceumm_turbo_enable: 'Both',
  },
  rom: 'flappybird.nes',
})
```

--------------------------------

### exit()

Source: https://nostalgist.js.org/apis/exit

Terminates the running game and emulator instance.

```APIDOC
## exit()

### Description
Exit the current running game and the emulator. Optionally remove the canvas element used by the emulator.

### Parameters
#### Request Body
- **options** (object) - Optional - Configuration object for the exit process.
  - **removeCanvas** (boolean) - Optional - If true, the canvas element will be removed. Defaults to true.
```

--------------------------------

### Save and Load Game State with Nostalgist.js

Source: https://nostalgist.js.org/

Saves the current state of an emulated game and then loads it back. This requires initializing Nostalgist with a ROM first.

```javascript
import { Nostalgist } from 'nostalgist'


const nostalgist = await Nostalgist.nes('flappybird.nes')
const { state } = await nostalgist.saveState()
await nostalgist.loadState(state)
```

--------------------------------

### pressUp Method

Source: https://nostalgist.js.org/apis/press-up

Releases a button programmatically. Analog joysticks are not supported.

```APIDOC
## POST /websites/nostalgist_js/pressUp

### Description
Releases a button programmatically. Analog joysticks are not supported at this time.

### Method
POST

### Endpoint
/websites/nostalgist_js/pressUp

### Parameters
#### Request Body
- **options** (string | object) - Required - Specifies the button to release and optionally the player.
  - **button** (string) - Required - The button to press. Can be: `up`, `down`, `left`, `right`, `select`, `start`, `a`, `b`, `x`, `y`, `l`, `l2`, `l3`, `r`, `r2`, `r3`. Note: 'a', 'b', 'x', 'y' use the SNES layout.
  - **player** (number) - Optional - Defaults to 1. The player to control. Requires corresponding key binding in `retroarchConfig` if not player 1.

### Request Example
```json
{
  "options": "select"
}
```
```json
{
  "options": {
    "button": "a",
    "player": 2
  }
}
```

### Response
#### Success Response (200)
- **message** (string) - Indicates the button press was simulated.

#### Response Example
```json
{
  "message": "Button 'select' released for player 1."
}
```
```

--------------------------------

### Pause a running game instance

Source: https://nostalgist.js.org/apis/pause

Initialize a game instance and invoke the pause method to halt gameplay.

```javascript
const nostalgist = await Nostalgist.nes('flappybird.nes')


nostalgist.pause()
```

--------------------------------

### Configure RetroArch key bindings for multi-player

Source: https://nostalgist.js.org/apis/press

Required configuration when controlling players other than the default player 1.

```javascript
await Nostalgist.launch({
  // see https://github.com/libretro/RetroArch/blob/575859e5d76d921cb490f55afcd0bbca90d4a742/retroarch.cfg#L468-L483
  retroarchConfig: {
    input_player2_down: 'num3',
    input_player2_left: 'num2',
    input_player2_right: 'num4',
    input_player2_up: 'num1',
  },


  /* ...other options */
})
```

--------------------------------

### Customizing Core Resolution

Source: https://nostalgist.js.org/apis/launch

Use resolveCoreJs and resolveCoreWasm to provide custom logic for resolving RetroArch core files.

```javascript
const nostalgist = await Nostalgist.launch({
  core: 'fceumm',
  rom: 'flappybird.nes',


  resolveCoreJs(core, options) {
    // will print 'fceumm'
    console.log(core)


    // will print the whole options object: { core: 'fceumm', rom: 'flappybird.nes', ... }
    console.log(options)


    return `https://example.com/${core}.js`
  },
})
```

```javascript
const nostalgist = await Nostalgist.launch({
  core: 'fceumm',
  rom: 'flappybird.nes',


  resolveCoreWasm(core, options) {
    // will print 'fceumm'
    console.log(core)


    // will print the whole options object: { core: 'fceumm', rom: 'flappybird.nes', ... }
    console.log(options)


    return `https://example.com/${core}.wasm`
  },
})
```

--------------------------------

### Save and Load Emulator State with Nostalgist.js

Source: https://nostalgist.js.org/apis/load-state

Use this snippet to save the current state of an emulator and then load it back. Ensure the emulator is initialized before saving or loading.

```javascript
const nostalgist = await Nostalgist.nes('flappybird.nes')


// save the state
const { state } = await nostalgist.saveState()


// load the state
await nostalgist.loadState(state)
```

--------------------------------

### Configure Default Nostalgist.js Options

Source: https://nostalgist.js.org/apis/configure

Use `Nostalgist.configure` to set default options that apply to all following emulator launches. Call `Nostalgist.resetToDefault` to revert all configurations to their default values.

```javascript
Nostalgist.configure({
  style: {
    position: 'static',
  },
})


// The canvas element will have position: static
await Nostalgist.nes('flappybird.nes')


// The canvas element will have position: static too
await Nostalgist.nes('flappybird.nes')


// Reset all configurations to default
Nostalgist.resetToDefault()
```

--------------------------------

### Manually Launching the Emulator

Source: https://nostalgist.js.org/apis/launch

Use runEmulatorManually to prevent automatic startup, requiring a subsequent call to launchEmulator.

```javascript
// will not launch the emulator
const nostalgist = await Nostalgist.launch({
  core: 'fceumm',
  rom: 'flappybird.nes',
  runEmulatorManually: true,
})


// the emulator will be launched
await nostalgist.launchEmulator()
```

--------------------------------

### loadState API

Source: https://nostalgist.js.org/apis/load-state

This section details how to load a saved state for the current emulator and game using the Nostalgist JS library.

```APIDOC
## POST /loadState

### Description
Load a state for the current running emulator and game.

### Method
POST

### Endpoint
/loadState

### Parameters
#### Request Body
- **state** (resolvable file) - Required - The state file to be loaded.

### Request Example
```json
{
  "state": "path/to/your/state/file"
}
```

### Response
#### Success Response (200)
This endpoint does not return specific data upon successful loading, but the emulator state will be updated.

#### Response Example
```json
{
  "message": "State loaded successfully"
}
```
```

--------------------------------

### Restart a NES Game

Source: https://nostalgist.js.org/apis/restart

Instantiate a Nostalgist NES emulator and then call the restart method to reset the game state.

```javascript
const nostalgist = await Nostalgist.nes('flappybird.nes')

nostalgist.restart()
```

--------------------------------

### Capture and display a game screenshot

Source: https://nostalgist.js.org/apis/screenshot

Captures the current game frame as a Blob and appends it to the document body as an image element.

```javascript
const nostalgist = await Nostalgist.nes('flappybird.nes')


const screenshot = await nostalgist.screenshot()
const url = URL.createObjectURL(screenshot)


const img = document.createElement('img')
img.src = url
document.body.append(img)
```

--------------------------------

### Resume a paused game instance

Source: https://nostalgist.js.org/apis/resume

Use this pattern to pause a running game and resume it after a delay.

```javascript
const nostalgist = await Nostalgist.nes('flappybird.nes')


nostalgist.pause()
await new Promise((resolve) => setTimeout(resolve, 1000))
nostalgist.resume()
```

--------------------------------

### ROM repository mapping logic

Source: https://nostalgist.js.org/apis/launch

Internal mapping used to determine the repository based on the ROM file extension.

```javascript
const romRepo = {
  '.bin': 'retrobrews/md-games',
  '.gb': 'retrobrews/gbc-games',
  '.gba': 'retrobrews/gba-games',
  '.gbc': 'retrobrews/gbc-games',
  '.md': 'retrobrews/md-games',
  '.nes': 'retrobrews/nes-games',
  '.sfc': 'retrobrews/snes-games',
  '.sms': 'retrobrews/sms-games',
}[extension]
```

--------------------------------

### Include Nostalgist.js via CDN

Source: https://nostalgist.js.org/guides/getting-started

Add a script tag with a CDN link to your HTML to use Nostalgist.js. The global Nostalgist variable will be available for use.

```html
<script src='https://unpkg.com/nostalgist'></script>
```

```html
<script src='https://cdn.jsdelivr.net/npm/nostalgist'></script>
```

```javascript
await Nostalgist.nes('flappybird')
```

--------------------------------

### Access Emscripten File System

Source: https://nostalgist.js.org/

Access low-level Emscripten APIs, such as the file system, after launching an emulator. This requires importing Nostalgist and obtaining the Emscripten FS object.

```javascript
import { Nostalgist } from 'nostalgist'


const rom = 'https://example.com/zelda.sfc'
const nostalgist = await Nostalgist.snes(rom)
const FS = nostalgist.getEmscriptenFS()
FS.readdir('/')
```

--------------------------------

### Configure SNES button layout

Source: https://nostalgist.js.org/apis/press-down

Visual representation of the SNES button mapping used by the library.

```text
 x  
y a  
 b
```

--------------------------------

### Cancel launch with AbortSignal

Source: https://nostalgist.js.org/apis/launch

Use an AbortController to programmatically cancel an emulator launch.

```javascript
const abortController = new AbortController()


// Cancel the launch after 500ms
setTimeout(() => abortController.abort(), 500)


const nostalgist = await Nostalgist.launch({
  core: 'fceumm',
  rom: 'flappybird.nes',
  signal: abortController.signal,
})
```

--------------------------------

### Define Resolvable File as String Content

Source: https://nostalgist.js.org/apis/resolvable-file

Directly provide the file content as a string, commonly used for emulator core JavaScript files.

```javascript
// copied from https://cdn.jsdelivr.net/gh/arianrhodsandlot/retroarch-emscripten-build@v1.16.0/retroarch/snes9x_libretro.js
'var Module=typeof Module!=="undefined"?Module:{};var moduleOverrides={};var key;...'
```

--------------------------------

### Simulate button presses with pressDown

Source: https://nostalgist.js.org/apis/press-down

Demonstrates triggering various controller buttons for player 1 and specific buttons for player 2.

```javascript
const nostalgist = await Nostalgist.nes('flappybird.nes')


nostalgist.pressDown('select')
nostalgist.pressDown('start')
nostalgist.pressDown('a')
nostalgist.pressDown('left')
nostalgist.pressDown('l')
nostalgist.pressDown({ button: 'a', player: 2 }) // press the button "a" on player 2's controller
```

--------------------------------

### Reset Nostalgist.js Configuration to Default

Source: https://nostalgist.js.org/apis/reset-to-default

Use `resetToDefault()` to revert all Nostalgist.js configurations to their initial default settings. This is useful after applying custom configurations with `configure`.

```javascript
Nostalgist.configure({
  style: {
    position: 'static',
  },
})


// The canvas element will have position: static
await Nostalgist.nes('flappybird.nes')


// Reset all configurations to default
Nostalgist.resetToDefault()


// The canvas element will use the default position: fixed
await Nostalgist.nes('flappybird.nes')
```

--------------------------------

### Retrieve Emulator Status

Source: https://nostalgist.js.org/apis/get-status

Demonstrates checking the emulator status at different stages of its lifecycle using the getStatus method.

```javascript
const nostalgist = await Nostalgist.prepare('flappybird.nes')
console.log(nostalgist.getStatus()) // 'initial'


await nostalgist.launch()
console.log(nostalgist.getStatus()) // 'running'


await nostalgist.pause()
console.log(nostalgist.getStatus()) // 'paused'


nostalgist.exit()
console.log(nostalgist.getStatus()) // 'terminated'
```

--------------------------------

### Define Resolvable File via Functions and Promises

Source: https://nostalgist.js.org/apis/resolvable-file

Provide a function or promise that resolves to one of the supported file formats. These are unwrapped recursively.

```javascript
// a function returning a URL string
function () {
  return 'http://www.example.com/roms/contra.nes'
}


// a promise wrapping a Blob object
(async function() {
  const response = await fetch('http://www.example.com/roms/contra.nes')
  return await response.blob()
})()
```

--------------------------------

### Press Button API

Source: https://nostalgist.js.org/apis/press

Simulates pressing and releasing a button on a game controller. This is a shortcut for `pressDown` and `pressUp`.

```APIDOC
## POST /websites/nostalgist_js/press

### Description
Press a button and then release it programmatically. This is a shortcut for a combination of `pressDown` and `pressUp`.
Analog joysticks are not supported at this time.

### Method
POST

### Endpoint
/websites/nostalgist_js/press

### Parameters
#### Request Body
- **options** (string | object) - Required - Specifies the button to press and optional parameters.
  - **button** (string) - Required - The button to press. Can be: `up`, `down`, `left`, `right`, `select`, `start`, `a`, `b`, `x`, `y`, `l`, `l2`, `l3`, `r`, `r2`, `r3`. The ‘a’, ‘b’, ‘x’, ‘y’ buttons use the SNES layout.
  - **player** (number) - Optional - Defaults to `1`. The player to control. Ensure key bindings are set for players other than 1.
  - **time** (number) - Optional - Defaults to `100`. How long to press the button in milliseconds.

### Request Example
```json
{
  "example": "await nostalgist.press('a')\nawait nostalgist.press({ button: 'a', player: 2 })\nawait nostalgist.press({ button: 'a', time: 200 })\nawait nostalgist.press({ button: 'a', player: 2, time: 200 })"
}
```

### Response
#### Success Response (200)
This endpoint does not return a specific response body upon success, indicating the operation was completed.

#### Response Example
```json
{
  "example": ""
}
```
```

--------------------------------

### Press Gamepad Buttons Programmatically

Source: https://nostalgist.js.org/apis/press-up

Use this function to simulate button presses on a game controller. It supports standard buttons and can target player 2.

```javascript
const nostalgist = await Nostalgist.nes('flappybird.nes')


nostalgist.pressUp('select')
nostalgist.pressUp('start')
nostalgist.pressUp('a')
nostalgist.pressUp('left')
nostalgist.pressUp('l')
nostalgist.pressUp({ button: 'a', player: 2 }) // press the button "a" on player 2's controller
```

--------------------------------

### Use ESM Version of Nostalgist.js via CDN

Source: https://nostalgist.js.org/guides/getting-started

Utilize the ESM version of Nostalgist.js by including a script tag with a CDN link for ESM modules. Import Nostalgist directly.

```html
<script type='module'>import {Nostalgist} from 'https://esm.run/nostalgist'</script>
```

```html
<script type='module'>import {Nostalgist} from 'https://cdn.skypack.dev/nostalgist'</script>
```

--------------------------------

### Access Emscripten File System

Source: https://nostalgist.js.org/apis/get-emscripten-fs

Retrieve the FS object after initializing an emulator to perform file system operations like reading directories.

```javascript
const nostalgist = await Nostalgist.nes('flappybird.nes')


const FS = nostalgist.getEmscriptenFS()
const files = FS.readdir('/home/web_user/retroarch/userdata')
```

--------------------------------

### Nostalgist.megadrive

Source: https://nostalgist.js.org/apis/megadrive

Launches a Sega Genesis / Megadrive ROM with default emulation settings.

```APIDOC
## Nostalgist.megadrive(options)

### Description
A shortcut method for the Nostalgist.launch method, specifically configured for Sega Genesis / Megadrive emulation using the genesis_plus_gx core.

### Parameters
#### Arguments
- **options** (string | File | Object) - Required - If a string, File, or { fileName: string; fileContent: Blob }, it is treated as the ROM file. If an object, it accepts the same options as Nostalgist.launch.

### Request Example
await Nostalgist.megadrive('30yearsofnintendont.bin');
```
Tokens:
Raw