Skip to content

A JavaScript library used for running emulators of retro consoles inside browsers.

License

Notifications You must be signed in to change notification settings

arianrhodsandlot/nostalgist

Repository files navigation

Nostalgist.js

nostalgist.js.org badge GitHub badge NPM badge

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 and prefer playing games you own in browsers, rather than building something with code, you may want to try another open-source project RetroAssembly.

A Quick Glance

console demo

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',
      rom: 'flappybird.nes',
      retroarchConfig: {
        rewind_enable: true,
      },
      retroarchCoreConfig: {
        fceumm_turbo_enable: 'Both',
      },
    })

    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

Credits

  • These are the fundamental dependencies of Nostalgist.js.

  • 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.

Showcases

  • RetroAssembly

    A web app with which you can build a custom retro gaming library inside your browser. Game states can be synced with cloud storage services like OneDrive/Google Drive/Dropbox

    It's built on top of Nostalgist.js.

Alternatives

  • EmulatorJS

    Another JavaScript library for emulation inside browsers.

    It's more powerful and more sophisticated. It has 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