Nostalgist.js

<h1 align="center">Nostalgist.js</h1> <p align="center"> <img src="docs/src/assets/logo.png" width="150" height="150"> </p> <p align="center"> <a href="https://nostalgist.js.org/" title="nostalgist.js.org"> <img width="181" height="28" src="https://img.shields.io/badge/nostalgist.js.org-F7DF1E?style=for-the-badge&logo=JavaScript&logoColor=black" alt="nostalgist.js.org badge" /> </a> <a href="https://github.com/arianrhodsandlot/nostalgist" title="Nostalgist.js on GitHub"> <img width="95" height="28" src="https://img.shields.io/badge/GitHub-181717.svg?style=for-the-badge&logo=GitHub&logoColor=white" alt="GitHub badge" /> </a> <a href="https://www.npmjs.com/package/nostalgist" title="Nostalgist.js on NPM"> <img width="73" height="28" src="https://img.shields.io/badge/npm-CB3837.svg?style=for-the-badge&logo=npm&logoColor=white" alt="NPM badge" /> </a> </p> <table align="center"> <tr> <td valign="middle"> <img align="middle" src="https://github.githubassets.com/assets/mona-e50f14d05e4b.png" alt="mona" width="28" height="28" /> </td> <td valign="middle"> <a href="https://github.com/sponsors/arianrhodsandlot">Become a sponsor</a> </td> </tr> </table>

Nostalgist.js is a JavaScript library that allows you to run emulators of retro consoles, like NES and Sega Genesis, within web browsers.

[!tip] Nostalgist.js is for developers. If you are a player rather than a developer planning to build something, you may want to try another open-source project RetroAssembly.

A Quick Glance

<p align="center"> <img src="docs/src/assets/console-demo.gif" alt="console demo" /> </p>

Website

Checkout nostalgist.js.org for more online examples and documentation.

Features

• Launch a retro game with RetroArch emulator in a browser

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

  Related API: launch

• Save the state of the game, then load it later

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

  Related APIs: saveState, loadState

• Customize any RetroArch config before launching

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

  Related API: launch#retroarchConfig

• Access low level APIs of Emscripten

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

  Related APIs: getEmscriptenModule, getEmscriptenFS

Motivation

Nostalgist.js is built on top of RetroArch Emscripten builds. We love RetroArch to run in browsers because that's portable and convenient. Although there is already an official instance, RetroArch web player, and some third-party ones like webretro, it's still not that easy to launch RetroArch in a browser programmatically.

The purpose of Nostalgist.js is to simplify the process of launching an emulator to play a game, via RetroArch, in browsers. Given a ROM and a core, the game should be launched without any additional configuration.

APIs

Please refer to nostalgist.js.org/apis.

Related

Showcases

[!note] Feel free to add yours by sending a pull request.

Project	Description
RetroAssembly	The personal retro game collection cabinet in your browser.
vme	Virtual Machine / Emulator - multi emulator web app
ultimate-homebrew-extensions	Runs an emulator to test ROMs inside of VS Code
NextCloud Nostalgist	Run emulators of retro consoles directly in NextCloud via Nostalgist.js.
Nostalbit	A retro web emulator with Next.js, Tailwind, TypeScript
AstroEmu	Famicom and Super Famicom on the web
Koin.js	The high-performance, preservation-focused netflix style emulation engine powered by Nostalgist.
Foxol	Foxol is a modern emulator platform with multiplayer, cloud saves, cheats, and deep customization across every device.

Credits

• These are the fundamental dependencies of Nostalgist.js.

  • RetroArch and its friends(the emulators/cores)
  • Emscripten

• We are using ROMs here for the purpose of demonstration.

  • retrobrews and the authors of the homebrew games.

• By default, our ROMs and cores are all loaded from this free CDN service.

  • jsDelivr

Alternatives

• EmulatorJS

  Another JavaScript library for emulation inside browsers.

  It's more powerful and more sophisticated. It includes many custom cores and has a friendly user interface. It can be used inside mobile browsers with touch support.

  It's not that friendly towards modern frontend development.

Caveat

[!caution]

• Nostalgist.js DOES NOT provide any pirated content, like copyrighted ROM files or BIOS files.
• And it DOES NOT encourage that.

License

MIT