GitHub - muditjuneja/koin: The high-performance, preservation-focused emulation engine powering Koin Deck. Built for those who remember blowing into cartridges, but demand the convenience of the cloud.

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

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