koin.js

Browser Retro Game Emulation for React

24 systems. Cloud saves. Multi-language. Zero backend required.

The drop-in React component for browser-based retro game emulation. Built on Nostalgist.js, adding production-ready features like cloud saves, touch controls, gameplay recording, and RetroAchievements.

Features

🎮 Core Emulation

• 25 Consoles — NES to PlayStation, Game Boy to Saturn
• Automatic Core Selection — Best emulator core per system
• BIOS Management — Multi-file BIOS support with UI selection
• Performance Optimized — SharedArrayBuffer for maximum speed

☁️ Save System

• Slot-Based Saves — Multiple save states with screenshots
• Auto-Save — Periodic background saves (configurable interval)
• Emergency Saves — Automatic save on tab hide/close
• Cloud-Ready API — Bring your own backend with async handlers

🎨 Display & Effects

• 10 CRT Shaders — Lottes, Geom, Easymode, Hyllian, zFast, and more
• Runtime Shader Switching — Change filters without restart
• System Theming — Per-console accent colors
• Screenshot Capture — PNG snapshots with hotkey support

🕹️ Controls

• Keyboard Remapping — Per-console custom key bindings
• Gamepad Support — Auto-detect Xbox, PlayStation, Nintendo controllers
• Touch Controls — GPU-accelerated virtual D-pad and buttons for mobile
• Control Persistence — Saves user preferences across sessions

⏪ Special Features

• Rewind — Time-travel gameplay (auto-enabled for 8/16-bit)
• Speed Control — 0.25x to 4x with hotkey toggle
• Fast-Forward — Turbo mode for grinding

📹 Recording & Overlays

• Gameplay Recording — VP9/VP8 WebM capture at 30fps
• Performance Overlay — FPS, frame time, memory stats
• Input Display — Virtual controller overlay for streaming
• Toast Notifications — Non-intrusive save/load feedback

🏆 RetroAchievements

• Official RA Integration — Track unlocks across sessions
• Hardcore Mode — Disable saves/cheats for leaderboard eligibility
• Achievement Browser — Filter by locked/unlocked status
• Progress Tracking — Points remaining per game

🌍 Internationalization

• 3 Built-in Languages — English, Spanish, French
• Type-Safe Translations — Full TypeScript support
• Partial Overrides — Customize specific strings
• Custom Languages — Implement your own translation set

🎯 Developer Experience

• TypeScript First — Complete type definitions
• Zero Config — Works out of the box
• Customizable UI — Accent colors, shaders, controls
• Web Component — Use without React

Installation

npm install koin.js
# or
yarn add koin.js
# or
pnpm add koin.js

Quick Start

import { GamePlayer } from 'koin.js';
import 'koin.js/styles.css';

export default function App() {
  return (
    <GamePlayer
      romId="game-123"
      romUrl="/roms/mario.nes"
      system="NES"
      title="Super Mario Bros."
    />
  );
}

Cloud Integration

import { GamePlayer } from 'koin.js';

<GamePlayer
  romId="game-123"
  romUrl="/roms/game.nes"
  system="NES"
  title="My Game"
  
  // Cloud save handlers
  onSaveState={async (slot, blob, screenshot) => {
    await fetch(`/api/saves/${slot}`, {
      method: 'POST',
      body: blob,
    });
  }}
  onLoadState={async (slot) => {
    const res = await fetch(`/api/saves/${slot}`);
    return res.ok ? await res.blob() : null;
  }}
  onAutoSave={async (blob, screenshot) => {
    await fetch('/api/autosave', { method: 'POST', body: blob });
  }}
  
  // Customization
  systemColor="#FF3333"
  shader="crt/crt-lottes"
  initialLanguage="es"
/>

Internationalization

<GamePlayer
  initialLanguage="es"  // Spanish UI
/>

// Or provide custom translations
import { en } from 'koin.js';

<GamePlayer
  translations={{
    controls: {
      ...en.controls,
      play: 'START GAME',
    }
  }}
/>

Web Component

<script src="https://unpkg.com/koin.js/dist/web-component.global.js"></script>

<retro-game-player
  rom-url="./game.nes"
  system="nes"
  title="My Game"
  rom-id="game-1"
></retro-game-player>

Supported Systems

System	Key	Core	Source
NES / Famicom	NES	fceumm	Nostalgist
Super Nintendo	SNES	snes9x	Nostalgist
Nintendo 64	N64	mupen64plus_next	BinBashBanana
Game Boy / Color	GB, GBC	gambatte	Nostalgist
Game Boy Advance	GBA	mgba	Nostalgist
Nintendo DS	NDS	melonds	BinBashBanana
PlayStation	PS1	pcsx_rearmed	Nostalgist
Sega Genesis / Mega Drive	GENESIS	genesis_plus_gx	Nostalgist
Sega Master System	MASTER_SYSTEM	gearsystem	Nostalgist
Game Gear	GAME_GEAR	gearsystem	Nostalgist
Sega Saturn	SATURN	yabause	BinBashBanana
Neo Geo	NEOGEO	fbalpha2012_neogeo	Nostalgist
Arcade (FBNeo)	ARCADE	fbneo	Nostalgist
Atari 2600	ATARI_2600	stella2014	BinBashBanana
Atari 5200	ATARI_5200	a5200	BinBashBanana
Atari 7800	ATARI_7800	prosystem	BinBashBanana
Atari Lynx	LYNX	handy	Nostalgist
PC Engine / TurboGrafx-16	PC_ENGINE	mednafen_pce_fast	Nostalgist
WonderSwan / Color	WONDERSWAN, WONDERSWAN_COLOR	mednafen_wswan	Nostalgist
Virtual Boy	VIRTUAL_BOY	mednafen_vb	Nostalgist
Neo Geo Pocket / Color	NEOGEO_POCKET, NEOGEO_POCKET_COLOR	mednafen_ngp	Nostalgist
Commodore 64	C64	vice_x64	Nostalgist

Note: Systems marked BinBashBanana use cores from BinBashBanana/webretro via jsDelivr. Dreamcast and PSP are currently unavailable due to lack of compatible WASM cores.

Full system details →

Requirements

COOP/COEP Headers Required for SharedArrayBuffer:

// next.config.js
async headers() {
  return [{
    source: '/:path*',
    headers: [
      { key: 'Cross-Origin-Opener-Policy', value: 'same-origin' },
      { key: 'Cross-Origin-Embedder-Policy', value: 'require-corp' },
    ],
  }];
}

Documentation

• Quick Start — Get up and running
• Usage Guide — Cloud saves, BIOS, RA integration
• API Reference — Complete props documentation
• Advanced Guide — Shaders, recording, controls, i18n
• Systems List — Per-console configuration

License

MIT © Mudit Juneja