# incredibleidea/emulatorjs architecture

> Architecture diagram of the GitHub repository incredibleidea/emulatorjs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/incredibleidea/emulatorjs
- Repository: https://github.com/incredibleidea/emulatorjs

## Overview

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: [`data/src/emulator.js`](https://github.com/incredibleidea/emulatorjs/blob/main/data/src/emulator.js) (Emulator), [`data/loader.js`](https://github.com/incredibleidea/emulatorjs/blob/main/data/loader.js) (Loader), [`data/src/compression.js`](https://github.com/incredibleidea/emulatorjs/blob/main/data/src/compression.js) (Compression), [`build.js`](https://github.com/incredibleidea/emulatorjs/blob/main/build.js) (Build script)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Browser runtime"]
  node_index["Entry page<br/>html entry<br/>[index.html]"]
  node_loader["Loader<br/>bootstrap<br/>[loader.js]"]
  node_emulator["Emulator<br/>orchestrator<br/>[emulator.js]"]
  node_game_manager["Game manager<br/>game flow<br/>[GameManager.js]"]
  node_compression["Compression<br/>archive loading<br/>[compression.js]"]
  node_gamepad["Gamepad input<br/>input mapping<br/>[gamepad.js]"]
  node_touch_input["Touch input<br/>virtual joystick<br/>[nipplejs.js]"]
  node_shaders["Shaders<br/>video effects<br/>[shaders.js]"]
  node_storage[("Storage<br/>persistence<br/>[storage.js]")]
  node_style["Stylesheet<br/>ui styling<br/>[emulator.css]"]
end

subgraph group_assets["Runtime assets"]
  node_cores["Cores package<br/>external cores<br/>[README.md]"]
  node_core_pkg["Core package<br/>npm package<br/>[package.json]"]
  node_extract7z["7z extractor<br/>archive helper<br/>[extract7z.js]"]
  node_extractzip["Zip extractor<br/>archive helper<br/>[extractzip.js]"]
  node_unrar["UnRAR engine<br/>wasm extractor<br/>[libunrar.js]"]
  node_unrar_wasm["WASM binary<br/>webassembly<br/>[libunrar.wasm]"]
  node_locales["Localizations<br/>translations<br/>[en.json]"]
  node_version["Version file<br/>release metadata<br/>[version.json]"]
end

subgraph group_tooling["Build and release"]
  node_build["Build script<br/>packaging<br/>[build.js]"]
  node_minify["Minifier<br/>bundle transform<br/>[minify.js]"]
  node_update["Updater<br/>release automation<br/>[update.js]"]
  node_github["CI workflows<br/>automation<br/>[stable.yml]"]
  node_docs["Docs<br/>documentation<br/>[README.md]"]
end

node_index -->|"loads"| node_loader
node_loader -->|"bootstraps"| node_emulator
node_loader -->|"applies"| node_style
node_emulator -->|"coordinates"| node_game_manager
node_emulator -->|"unpacks"| node_compression
node_emulator -->|"maps input"| node_gamepad
node_emulator -->|"supports"| node_touch_input
node_emulator -->|"renders with"| node_shaders
node_emulator -->|"persists"| node_storage
node_game_manager -->|"selects core"| node_cores
node_cores -->|"packages"| node_core_pkg
node_compression -->|"uses"| node_extract7z
node_compression -->|"uses"| node_extractzip
node_compression -->|"uses"| node_unrar
node_unrar -->|"loads"| node_unrar_wasm
node_loader -->|"loads"| node_locales
node_loader -->|"reads"| node_version
node_build -->|"invokes"| node_minify
node_build -->|"supports"| node_update
node_github -->|"automates"| node_build
node_github -.->|"publishes"| node_docs
node_docs -.->|"explains"| node_loader

click node_index "https://github.com/incredibleidea/emulatorjs/blob/main/index.html"
click node_loader "https://github.com/incredibleidea/emulatorjs/blob/main/data/loader.js"
click node_emulator "https://github.com/incredibleidea/emulatorjs/blob/main/data/src/emulator.js"
click node_game_manager "https://github.com/incredibleidea/emulatorjs/blob/main/data/src/GameManager.js"
click node_compression "https://github.com/incredibleidea/emulatorjs/blob/main/data/src/compression.js"
click node_gamepad "https://github.com/incredibleidea/emulatorjs/blob/main/data/src/gamepad.js"
click node_touch_input "https://github.com/incredibleidea/emulatorjs/blob/main/data/src/nipplejs.js"
click node_shaders "https://github.com/incredibleidea/emulatorjs/blob/main/data/src/shaders.js"
click node_storage "https://github.com/incredibleidea/emulatorjs/blob/main/data/src/storage.js"
click node_style "https://github.com/incredibleidea/emulatorjs/blob/main/data/emulator.css"
click node_cores "https://github.com/incredibleidea/emulatorjs/blob/main/data/cores/README.md"
click node_core_pkg "https://github.com/incredibleidea/emulatorjs/blob/main/data/cores/package.json"
click node_extract7z "https://github.com/incredibleidea/emulatorjs/blob/main/data/compression/extract7z.js"
click node_extractzip "https://github.com/incredibleidea/emulatorjs/blob/main/data/compression/extractzip.js"
click node_unrar "https://github.com/incredibleidea/emulatorjs/blob/main/data/compression/libunrar.js"
click node_unrar_wasm "https://github.com/incredibleidea/emulatorjs/blob/main/data/compression/libunrar.wasm"
click node_locales "https://github.com/incredibleidea/emulatorjs/blob/main/data/localization/en.json"
click node_version "https://github.com/incredibleidea/emulatorjs/blob/main/data/version.json"
click node_build "https://github.com/incredibleidea/emulatorjs/blob/main/build.js"
click node_minify "https://github.com/incredibleidea/emulatorjs/blob/main/minify/minify.js"
click node_update "https://github.com/incredibleidea/emulatorjs/blob/main/update.js"
click node_github "https://github.com/incredibleidea/emulatorjs/blob/main/.github/workflows/stable.yml"
click node_docs "https://github.com/incredibleidea/emulatorjs/blob/main/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_index,node_loader,node_emulator,node_game_manager,node_compression,node_gamepad,node_touch_input,node_shaders,node_storage,node_style toneBlue
class node_cores,node_core_pkg,node_extract7z,node_extractzip,node_unrar,node_unrar_wasm,node_locales,node_version toneAmber
class node_build,node_minify,node_update,node_github,node_docs toneMint
```

## Components

### Browser runtime

Assets shipped to the browser to bootstrap and run emulation.

- [Entry page](https://github.com/incredibleidea/emulatorjs/blob/main/index.html): html entry · Public page that loads the browser runtime. · `index.html`
- [Loader](https://github.com/incredibleidea/emulatorjs/blob/main/data/loader.js): bootstrap · Initial runtime bootstrap and configuration wiring. · `data/loader.js`
- [Emulator](https://github.com/incredibleidea/emulatorjs/blob/main/data/src/emulator.js): orchestrator · Central emulation lifecycle and startup coordination. · `data/src/emulator.js`
- [Game manager](https://github.com/incredibleidea/emulatorjs/blob/main/data/src/GameManager.js): game flow · Selects games and coordinates ROM loading and unloading. · `data/src/GameManager.js`
- [Compression](https://github.com/incredibleidea/emulatorjs/blob/main/data/src/compression.js): archive loading · Browser-side archive extraction and ROM unpacking logic. · `data/src/compression.js`
- [Gamepad input](https://github.com/incredibleidea/emulatorjs/blob/main/data/src/gamepad.js): input mapping · Controller input handling and mapping. · `data/src/gamepad.js`
- [Touch input](https://github.com/incredibleidea/emulatorjs/blob/main/data/src/nipplejs.js): virtual joystick · Mobile touch control layer. · `data/src/nipplejs.js`
- [Shaders](https://github.com/incredibleidea/emulatorjs/blob/main/data/src/shaders.js): video effects · Rendering and visual adjustment support. · `data/src/shaders.js`
- [Storage](https://github.com/incredibleidea/emulatorjs/blob/main/data/src/storage.js): persistence · Browser persistence for saves, settings, and session data. · `data/src/storage.js`
- [Stylesheet](https://github.com/incredibleidea/emulatorjs/blob/main/data/emulator.css): ui styling · Presentation styles for the emulator UI. · `data/emulator.css`

### Runtime assets

Supporting data files consumed by the browser runtime.

- [Cores package](https://github.com/incredibleidea/emulatorjs/blob/main/data/cores/README.md): external cores · Separate packaged emulator cores distributed with the runtime. · `data/cores/README.md`
- [Core package](https://github.com/incredibleidea/emulatorjs/blob/main/data/cores/package.json): npm package · Packaging boundary for external emulator cores. · `data/cores/package.json`
- [7z extractor](https://github.com/incredibleidea/emulatorjs/blob/main/data/compression/extract7z.js): archive helper · 7z archive extraction helper. · `data/compression/extract7z.js`
- [Zip extractor](https://github.com/incredibleidea/emulatorjs/blob/main/data/compression/extractzip.js): archive helper · ZIP archive extraction helper. · `data/compression/extractzip.js`
- [UnRAR engine](https://github.com/incredibleidea/emulatorjs/blob/main/data/compression/libunrar.js): wasm extractor · RAR extraction implementation and WASM runtime. · `data/compression/libunrar.js`
- [WASM binary](https://github.com/incredibleidea/emulatorjs/blob/main/data/compression/libunrar.wasm): webassembly · Binary WASM payload used by the RAR extractor. · `data/compression/libunrar.wasm`
- [Localizations](https://github.com/incredibleidea/emulatorjs/blob/main/data/localization/en.json): translations · Translated UI string bundles. · `data/localization/en.json`
- [Version file](https://github.com/incredibleidea/emulatorjs/blob/main/data/version.json): release metadata · Runtime version metadata used for distribution. · `data/version.json`

### Build and release

Packaging, minification, and automation used to publish the distributable bundle.

- [Build script](https://github.com/incredibleidea/emulatorjs/blob/main/build.js): packaging · Repository build and bundling entrypoint. · `build.js`
- [Minifier](https://github.com/incredibleidea/emulatorjs/blob/main/minify/minify.js): bundle transform · Minification step for distributable assets. · `minify/minify.js`
- [Updater](https://github.com/incredibleidea/emulatorjs/blob/main/update.js): release automation · Project update and release helper script. · `update.js`
- [CI workflows](https://github.com/incredibleidea/emulatorjs/blob/main/.github/workflows/stable.yml): automation · GitHub Actions used for stable, latest, npm, and newline checks. · `.github/workflows/stable.yml`
- [Docs](https://github.com/incredibleidea/emulatorjs/blob/main/README.md): documentation · Repository documentation and contributor-facing guidance. · `README.md`

## Connections

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