$ show arianrhodsandlot/nostalgist
Nostalgist.js is a TypeScript library that provides a simplified API for running retro console emulators in web browsers using RetroArch compiled via Emscripten. It handles the complex setup of Emscripten modules, virtual file systems, and RetroArch configuration, allowing developers to launch games with minimal code. The library supports a wide range of consoles (NES, SNES, Game Boy, etc.) with sensible defaults for loading cores and ROMs from CDNs, while also allowing custom resolvers. It includes features like save/load states, SRAM management, screenshot capture, and programmatic input control. The codebase is well-structured with strong TypeScript types, comprehensive tests (integration and e2e), and a clean class hierarchy. Notable highlights include a flexible file resolution system that handles various input formats (URLs, Blobs, ArrayBuffers, etc.) and a clever patching mechanism for importing Emscripten modules as ES modules.
The LLM identified 3 files worth highlighting for reuse:
A robust utility class that normalizes diverse input types (URL strings, Request, Response, Blob, File, ArrayBuffer, Uint8Array, FileSystemFileHandle, and objects with fileName/fileContent) into a unified ResolvableFile object with lazy loading capabilities. It provides methods to retrieve the file as Blob, ArrayBuffer, text, or Uint8Array, and handles name inference from URLs or provided metadata. This component is self-contained and could be extracted as a standalone file loading/management utility for any JavaScript project.
Contains the `importCoreJsAsESM` function that patches the core JavaScript file of RetroArch (either global or ESM script) to export a `getEmscripten` function that exposes the Emscripten module, AL, Browser, JSEvents, and exit function. This enables dynamic import of the core as an ES module, overcoming the typical Emscripten module loading pattern. The function is isolated and demonstrates a clever workaround for integrating Emscripten-compiled code into modern JavaScript module systems.
Manages the Emscripten virtual file system for the emulator, providing methods to create directories, read/write files, wait for file completion (with exponential backoff), and write INI configuration files. It sets up the necessary directory structure for RetroArch (content, system, config, shader, etc.) and handles file operations with proper abort signal support. This class is well-isolated and could be reused for other Emscripten-based projects needing a virtual file system abstraction.