@ta-torres/gbc-react

@ta-torres/gbc-react is a React-based emulator component built on @ta-torres/gbc-core. It provides a complete Game Boy / Game Boy Color emulation interface with rendering, keyboard, touch and gamepad controls, audio, save data, save states, and configurable emulation settings.

This package does not include games or ROM files. Users must select their own .gb, .gbc, or .zip game backup.

Install

## Install gbc-cor first
npm install @ta-torres/gbc-core
npm install @ta-torres/gbc-react

import { GbcPlayer } from "@ta-torres/gbc-react";
import "@ta-torres/gbc-react/styles.css";

export function App() {
  return <GbcPlayer />;
}

If using Astro, render the containing React component with a client:* directive.

The package exports the GbcPlayer component and GbcPlayerProps type. It does not expose an imperative shell ref; use onLoad to access the underlying GBCEmulator instance when application code needs the core API.

Features

• ROM loading: Select .gb, .gbc, or .zip files from the built-in file picker. The player loads the ROM, restores matching saved data, and starts emulation automatically.
• Controls: Use the on-screen touch controls, a standard mapped gamepad, or the keyboard bindings in the table below. Controls are disabled until a ROM is loaded.
• Playback: Pause/resume, reset, mute/unmute, enter fullscreen, and change emulation speed from the settings panel. Available speeds are 0.5x, 1x, 1.5x, 2x, 3x, and 4x.
• Display: Select a DMG or CGB color palette appropriate to the loaded ROM. The framebuffer is rendered at the native 160 × 144 resolution with pixel smoothing disabled.
• Touch layout: Hide the touch controls or move the D-pad and A/B controls in small increments. Preferences are retained in browser storage.

Keyboard and gamepad controls

| Input | Game Boy button | | ---------- | --------------- | | Arrow keys | D-pad | | Z | B | | X | A | | Shift | Select | | Enter | Start | | P | Pause/resume |

Standard-mapped gamepads use their standard A/B, Select, Start, and D-pad/axis buttons. The player polls connected gamepads while a ROM is loaded.

Saves and save states

Battery-backed SRAM data is saved automatically to localStorage when the component detects writes to SRAM and when the page is hidden or the component is unmounted. SRAM uses the shared gbc-save:* keys, RTC uses gbc-rtc:*, and preferences use the shared gbc-save:preferences key.

The settings panel provides five per-ROM save-state slots. Save states are validated against the loaded ROM before they are restored. Use Export saves to download player preferences and battery data as JSON, and Import saves to restore shared gbc-save:* records; reload a ROM after importing for the data to be applied.

Props

| Prop | Type | Description | | ------------------- | -------------------------- | ------------------------------------------------------------------------------ | | suspendWhenHidden | boolean | Pause frame execution while the document is hidden. Defaults to true. | | onLoad | (emulator, file) => void | Called after a ROM loads and starts, with the core emulator and selected file. | | onError | (error) => void | Called when ROM loading, storage, audio, or fullscreen operations fail. | | instanceId | string | Stable DOM ID for the player and its accessibility labels. | | className | string | Additional class name applied to the root. | | ariaLabel | string | Accessible label for the application. |

Build

To build the packages from the source repository:

git clone https://github.com/ta-torres/GBC-TS.git
cd GBC-TS
npm install
npm run build:packages
# Pack both the emulation core and UI after making changes to the source code
npm run pack

To build only this package, run npm run build from packages/gbc-react.

Repository

Source code is available in the GBC-TS repository.