How incredibleidea/emulatorjs works
1. What this repository is
EmulatorJS is a browser-based emulation framework, not a single emulator. Its main job is to load the right emulation core, feed it ROM/data/input, and present video/audio/UI in the browser.
2. Primary runtime boundary
The runtime that ships to users lives under data/. The public entrypoint is index.html, which pulls in the loader and the client-side runtime assets from data/. The repo is structured as a distributable web package rather than a server app.
3. Bootstrapping and orchestration
data/loader.js is the key bootstrap layer. It is responsible for initializing the emulator experience, wiring configuration, and loading the rest of the runtime. From there, data/src/emulator.js appears to be the central orchestration module for emulation startup and lifecycle.
4. Core emulation subsystem
The actual system emulators are not committed as source here in the current repo state. They live in data/cores/ as a separate package and are also distributed through releases/CDN. This is the main architectural boundary: the framework code is in-repo, while the platform-specific emulator cores are external artifacts.
5. Game loading and lifecycle
data/src/GameManager.js is the likely domain layer for selecting a game, managing ROM metadata, and coordinating loading/unloading. This sits between the UI/configuration layer and the emulator core, so it is an important abstraction boundary for diagrams.
6. ROM and archive handling
data/src/compression.js plus data/compression/ implement ROM extraction from compressed archives. Supporting files like extract7z.js, extractzip.js, libunrar.js, and libunrar.wasm indicate that the browser can unpack archive formats before handing game files to the core.
7. Input subsystem
data/src/gamepad.js handles controller input mapping, and data/src/nipplejs.js suggests a touch/mobile virtual joystick layer. This input path feeds emulator controls, so it is a separate input boundary from the emulation core itself.
8. Rendering and presentation
data/src/shaders.js and data/emulator.css indicate a presentation layer for video output and UI styling. The browser renders emulator frames through the client runtime, with shader support likely used to adjust visuals and scaling behavior.
9. State and persistence
data/src/storage.js is the persistence boundary for browser storage. In an emulator context, this typically covers saves, settings, and session state, keeping user data local to the browser environment.
10. Localization
data/localization/*.json contains translated UI strings, with English as the base and multiple other languages supported. This is a UI-layer concern, not part of the emulation core, and is likely consumed by the loader/runtime during startup.
11. Versioning and distribution model
data/version.json plus the README’s stable/latest/nightly model show that the project is versioned as a deployable frontend bundle. The runtime can be served from the project itself, releases, or the CDN at cdn.emulatorjs.org, with loader.js and data/ paths varying by version.
12. Build and release pipeline
build.js, minify/minify.js, and update.js support packaging and publishing. The GitHub workflows in .github/workflows/ automate release-related tasks such as stable/latest builds and newline or npm checks. This is a distribution-focused repo, so build tooling is a significant architectural component.
13. Documentation and demo surfaces
README.md, docs/, and the demo-related assets represent the consumer-facing entry points for integrators. The project is intended to be embedded into other sites/apps, so the documentation is part of the product boundary, not just internal notes.
Main entry points: emulator.js Emulator · loader.js Loader · compression.js Compression · build.js Build script
Components 23
Browser runtime
Assets shipped to the browser to bootstrap and run emulation.
- Entry page · Public page that loads the browser runtime.
index.html - Loader · Initial runtime bootstrap and configuration wiring.
data/loader.js - Emulator · Central emulation lifecycle and startup coordination.
data/src/emulator.js - Game manager · Selects games and coordinates ROM loading and unloading.
data/src/GameManager.js - Compression · Browser-side archive extraction and ROM unpacking logic.
data/src/compression.js - Gamepad input · Controller input handling and mapping.
data/src/gamepad.js - Touch input · Mobile touch control layer.
data/src/nipplejs.js - Shaders · Rendering and visual adjustment support.
data/src/shaders.js - Storage · Browser persistence for saves, settings, and session data.
data/src/storage.js - Stylesheet · Presentation styles for the emulator UI.
data/emulator.css
Runtime assets
Supporting data files consumed by the browser runtime.
- Cores package · Separate packaged emulator cores distributed with the runtime.
data/cores/README.md - Core package · Packaging boundary for external emulator cores.
data/cores/package.json - 7z extractor · 7z archive extraction helper.
data/compression/extract7z.js - Zip extractor · ZIP archive extraction helper.
data/compression/extractzip.js - UnRAR engine · RAR extraction implementation and WASM runtime.
data/compression/libunrar.js - WASM binary · Binary WASM payload used by the RAR extractor.
data/compression/libunrar.wasm - Localizations · Translated UI string bundles.
data/localization/en.json - Version file · Runtime version metadata used for distribution.
data/version.json
Build and release
Packaging, minification, and automation used to publish the distributable bundle.
- Build script · Repository build and bundling entrypoint.
build.js - Minifier · Minification step for distributable assets.
minify/minify.js - Updater · Project update and release helper script.
update.js - CI workflows · GitHub Actions used for stable, latest, npm, and newline checks.
.github/workflows/stable.yml - Docs · Repository documentation and contributor-facing guidance.
README.md
Connections 22
- Entry page → Loader: loads · The entry page starts the runtime through the loader.
- Loader → Emulator: bootstraps · Loader initializes the main emulator orchestration layer.
- Loader → Stylesheet: applies · Loader/runtime uses the emulator stylesheet for presentation.
- Emulator → Game manager: coordinates · Emulator startup and lifecycle are driven through game management.
- Emulator → Compression: unpacks · Emulator prepares ROM/data through archive extraction.
- Emulator → Gamepad input: maps input · Emulator consumes controller mappings for gameplay input.
- Emulator → Touch input: supports · Touch input supplements controller input on mobile devices.
- Emulator → Shaders: renders with · Video output can be post-processed by shader support.
- Emulator → Storage: persists · Runtime state and saves are stored in browser persistence.
- Game manager → Cores package: selects core · Game management chooses an appropriate emulator core.
- Cores package → Core package: packages · The cores boundary is distributed as a separate package.
- Compression → 7z extractor: uses · Archive handling includes 7z extraction support.
- Compression → Zip extractor: uses · Archive handling includes ZIP extraction support.
- Compression → UnRAR engine: uses · Archive handling includes RAR extraction support.
- UnRAR engine → WASM binary: loads · The RAR extractor depends on the WASM binary payload.
- Loader → Localizations: loads · Loader/runtime consumes translated UI strings.
- Loader → Version file: reads · Runtime version metadata informs distribution and loading.
- Build script → Minifier: invokes · Build packaging passes through minification.
- Build script → Updater: supports · Build/release flow includes update automation.
- CI workflows → Build script: automates · GitHub Actions drive release and validation workflows.
- CI workflows → Docs: publishes · Repository automation and docs support the release process.
- Docs → Loader: explains · Documentation describes how integrators use the loader and bundle.