`bash
retroemu ~/roms/mario.nes
retroemu ~/roms/zelda.zip # extracts ROM from ZIP automatically
emu --frame-skip 3 ~/roms/zelda.sfc
emu --save-dir ~/.emu/saves ~/roms/pokemon.gbc
emu --contrast 1.5 ~/roms/space_invaders.a26 # boost contrast for dark games
`

Rendering

The emulator uses chafa-wasm to convert pixel data to truecolor ANSI sequences.

Default mode (half-blocks): Uses vertical half-block characters (▀▄) which provide 2 vertical pixels per character cell. This matches the blocky pixel art aesthetic of retro games and renders quickly.

ASCII mode (--ascii): Uses a wider variety of Unicode block and border characters for more detail. May look better for some games but can introduce visual artifacts.

Contrast boost (--contrast): Some games (especially Atari) have low contrast that doesn't translate well to terminal rendering. Use --contrast 1.5 or higher to boost visibility.

Controls

$3

Any gamepad recognized by gamepad-node works automatically. Buttons are mapped positionally — the south face button is always B, east is A, etc. — regardless of the controller's printed labels.

| Gamepad Button | Libretro |
|---------------|----------|
| South face (A/Cross) | B |
| East face (B/Circle) | A |
| West face (X/Square) | Y |
| North face (Y/Triangle) | X |
| L1 / LB | L |
| R1 / RB | R |
| L2 / LT | L2 |
| R2 / RT | R2 |
| Select / Back | Select |
| Start / Options | Start |
| D-Pad | D-Pad |
| Left Stick | Analog Left |
| Right Stick | Analog Right |

$3

Keyboard input is available as a fallback for player 1:

| Key | Action |
|-----|--------|
| Arrow keys | D-Pad |
| Z | B |
| X | A |
| A | Y |
| S | X |
| Q | L |
| W | R |
| Enter | Start |
| Shift | Select |

$3

| Key | Action |
|-----|--------|
| F1 | Reset |
| F5 | Save state (slot 0) |
| F7 | Load state (slot 0) |
| ESC | Quit |
| Ctrl+C | Force quit |

Save System

SRAM (battery-backed saves) is automatically saved when you quit and loaded when you start a ROM. Save files are stored as {rom-name}.srm in the save directory.

Save states capture the full emulation state (CPU registers, memory, video state, etc.) and are stored as {rom-name}.state0. Use F5 to save and F7 to load.

Default save directory: saves/ next to the ROM file, configurable with --save-dir.

Architecture

`
retroemu/
bin/cli.js CLI entry point
index.js Library exports
src/
core/
LibretroHost.js Main engine: WASM loading, callback registration, frame loop
CoreLoader.js Dynamic import of Emscripten WASM modules
SystemDetector.js ROM extension -> system/core mapping
SaveManager.js SRAM and save state persistence
video/
VideoOutput.js Pixel format conversion, aspect ratio, contrast
videoWorker.js Worker thread for chafa-wasm rendering
audio/
AudioBridge.js Direct SDL2 audio output
input/
InputManager.js Gamepad polling + keyboard fallback
InputMap.js W3C <-> libretro button mapping tables
constants/
libretro.js Libretro C API constants
cores/ Pre-built .wasm + .js glue files
scripts/
build-core.sh Emscripten build for any libretro core
build-all-cores.sh Batch build
cores/*.sh Per-core build configs
`

$3

LibretroHost (src/core/LibretroHost.js) is the central orchestrator. It:

1. Loads a WASM core via CoreLoader
2. Registers 6 JavaScript callbacks as WASM function pointers using Emscripten's addFunction():
- retro_environment — handles 20+ environment commands from the core (pixel format negotiation, directory queries, variable configuration, capability reporting)
- retro_video_refresh — receives framebuffer data each frame
- retro_audio_sample_batch — receives batched stereo audio samples
- retro_audio_sample — receives individual stereo samples (legacy fallback)
- retro_input_poll — triggers gamepad state refresh
- retro_input_state — returns button/axis state for a given port, device, and button ID
3. Allocates the ROM and retro_game_info struct in WASM memory
4. Reads retro_system_av_info to get screen dimensions, FPS, and audio sample rate
5. Runs the frame loop at the correct FPS using setTimeout/setImmediate hybrid timing

VideoOutput (src/video/VideoOutput.js) converts pixel data from the WASM heap into terminal art:

- Supports three pixel formats: RGB565, XRGB8888, 0RGB1555
- Uses pre-computed lookup tables (32-entry and 64-entry Uint8Arrays) for 16-bit to 8-bit color conversion — no division in the hot loop
- Default half-block mode (▀▄) doubles vertical resolution and matches pixel art aesthetic
- Optional detailed mode (--ascii) uses block/border Unicode symbols for more variety
- Contrast boost option for low-contrast games (Atari, etc.)
- Renders every Nth frame (configurable, default 2) to avoid overwhelming terminal I/O
- Runs chafa conversion in a worker thread to keep the main loop responsive

AudioBridge (src/audio/AudioBridge.js) sends audio directly to SDL2:

- Opens an SDL2 audio device in S16 stereo format (matches libretro exactly)
- Zero-copy path: passes WASM memory buffer directly to SDL2's queue
- No sample format conversion needed — libretro and SDL2 both use int16

InputManager (src/input/InputManager.js) multiplexes gamepad and keyboard input:

- Calls navigator.getGamepads() (provided by gamepad-node) each frame
- Maps W3C standard button indices to libretro joypad IDs via InputMap
- Supports input bitmasks for modern cores (mGBA, etc.) that query all buttons at once
- Supports analog sticks (W3C float axes converted to libretro int16 range)
- Falls back to keyboard for player 1 using stdin raw mode with frame-based key hold timing

$3

scripts/build-core.sh compiles any libretro core to WASM:

1. Clones the core repo (git clone --depth 1)
2. Builds with emmake make -f Makefile.libretro platform=emscripten
3. Links the output with emcc using flags:
- -O3 — full optimization
- -s MODULARIZE=1 -s EXPORT_ES6=1 — ES module factory
- -s ENVIRONMENT=node — Node.js target
- -s ALLOW_MEMORY_GROWTH=1 — dynamic memory (32MB initial, 256MB max)
- -s ALLOW_TABLE_GROWTH=1 — required for addFunction() callback registration
- -s FILESYSTEM=0 — no Emscripten FS (host handles I/O)
4. Exports 23 libretro API functions + Emscripten runtime helpers (addFunction, HEAPU8, setValue, etc.)

Programmatic API

`javascript
import { LibretroHost, VideoOutput, AudioBridge, InputManager, SaveManager } from 'retroemu';

const video = new VideoOutput();
await video.init();

const audio = new AudioBridge();
const input = new InputManager();
const saves = new SaveManager('./saves');

const host = new LibretroHost({
videoOutput: video,
audioBridge: audio,
inputManager: input,
saveManager: saves,
});

await host.loadAndStart('./game.nes');

// Later:
await host.saveState(0);
await host.loadState(0);
host.reset();
await host.shutdown();
``

Dependencies

| Package | Purpose |
|---------|---------|
| gamepad-node | W3C Gamepad API for Node.js via SDL2 — 2100+ controllers with standard mapping |
| @kmamal/sdl | Native SDL2 bindings for Node.js — audio output and gamepad input |
| chafa-wasm | Image-to-ANSI conversion — auto-detects Sixel, Kitty, or Unicode block art |

Acknowledgments

This project is built on top of the amazing work by the libretro team and the RetroArch community. All emulator cores are libretro cores compiled to WebAssembly:

- libretro provides a standardized API that allows emulator cores to be written once and run on many frontends
- RetroArch is the reference frontend implementation and home to most libretro core development
- Individual core authors and maintainers who have created and continue to improve these emulators

Without the libretro ecosystem and the open-source emulation community, this project would not be possible.

License

MIT