# Retro Player (v1.1.1)
### *The High-Performance, Zero-Overhead Web Emulation Station*

> Your favorite retro classics, beautifully organized and ready to play anywhere. Retro Player turns any browser into a dedicated retro console. Experience tactile navigation, authentic save management, customizable player profiles, and curated game libraries tailored for both living-room couch play and on-the-go handheld sessions.

## Live Demo & Source
- [Live Web Demo](https://godarayudhvir.github.io/retro-player/): Play classic retro games directly in your browser with zero installation.
- [GitHub Repository](https://github.com/godarayudhvir/retro-player): Source code, issues, Docker images, and community discussions.
- [Full Technical LLM Context](https://godarayudhvir.github.io/retro-player/llms-full.txt): Unabridged technical specification, architecture, emulator cores, and save state binary formats.

## Core Features & Highlights
- **12 Emulated Consoles & Handhelds**: Game Boy Advance (GBA), Game Boy Color (GBC), Game Boy (GB), Sega Game Gear, Nintendo DS (NDS), Super Nintendo (SNES), NES, Nintendo 64 (N64), Sega Genesis, Atari 2600, PlayStation 1 (PS1), and Arcade (MAME).
- **Zero-Overhead Edge-WASM Architecture**: Pure client-side WebAssembly execution; host server CPU/RAM usage is ~0%.
- **Nintendo DS Touch Experience**: Authentic dual-screen firmware theme with top-screen dynamic box art & spec sheets, and bottom touchscreen game selection grid with integrated inline Save Data Studio, Strategy Guides Deck, Edit & Scrape Studio, and dark/light mode toggles.
- **Strategy Guides & Walkthroughs Hub**: Direct, curated access to written walkthroughs (GameFAQs, StrategyWiki) and video playthroughs (YouTube) with a companion mobile QR code scan modal for couch/TV play.
- **100% Client-Side Battery Saves & Profiles**: In-game battery RAM (.sav / .srm / .mcr), quick save states, playtime analytics, Multiavatar player passports, and IndexedDB local caching.
- **Centralized Filesystem DB & 1-Click Backup**: Single JSON document database (`data/retroplayer_db.json`) syncing profiles, saves, and settings to host disk, with 1-click JSON backup export and restore studio.
- **Folder Ingestion & Companion Asset Pairing**: Drag-and-drop or browse entire multi-system ROM folders with zero-copy in-memory sessions or permanent host disk ingestion, automatic console classification, background scraping, and local box art / sidecar binding.
- **Universal Gamepad & Keyboard Navigation**: 100% controller spatial navigation across desktop & mobile feeds, telemetry widget with gamepad battery status and charging indicators.
- **Universal Organic Achievements & Pokémon Save Inspector**: Master registry of 24 universal organic achievements across 6 categories (300G Gamerscore), in-game unlock buffering, session exit toast flushing with Web Audio chiptune fanfare, and a zero-overhead binary Pokémon Save Inspector across Gen 1–5 (.sav/.dsv) unlocking 8/16 Gym Badges, League Champions, HM utilities, and story event milestones.
- **Rich Presence & Multi-Platform Game Activity**: Real-time game status broadcasting to Discord Desktop Rich Presence (RPC via local IPC socket with interactive web launcher & GitHub buttons), OS MediaSession API (macOS Control Center, Windows 11, iOS Lock Screen, Android notifications), and `/api/presence` webhook / OBS streamer overlay widget (`/widgets/now-playing.html`).
- **Haptic Touch & Tactile Feedback Engine**: Hardware-accelerated tactile impulses (`navigator.vibrate`) for mobile touch navigation, carousel selection, on-screen virtual gamepads, and achievement fanfare with built-in battery-saver awareness.
- **Universal Multi-Resolution & Device Adaptive**: 100% responsive across compact phones (`375x667`), modern smartphones (`390x844` / `430x932`), tablets (`810x1080`), handheld consoles (`1280x800` Steam Deck), 1080p / 1440p (2K) desktop monitors, and 4K Big Picture TVs (`3840x2160`).
- **Genuine Real-Time Performance & Diagnostics HUD**: Low-overhead canvas presentation draw-call hooking, lifecycle state tracking (zero false 60 FPS), per-system native frame targets (NTSC/PAL/N64/GBA), Web Audio hardware buffer latency inspection, real gamepad polling frequency benchmarks, and authentic native core vs HiDPI presentation resolution telemetry.
- **Progressive Web App (PWA) & Offline Mode**: Installable standalone app across macOS, Windows, Linux, Steam Deck, iOS, and Android.

## Documentation & Guides
- [Docker Deployment Guide](https://github.com/godarayudhvir/retro-player/blob/main/guides/docker.md): Full Docker Compose setup, container configurations, and troubleshooting.
- [macOS & OrbStack Guide](https://github.com/godarayudhvir/retro-player/blob/main/guides/orbstack.md): Ultra-fast macOS Docker alternative, native filesystem speeds, and backend ROM & save management.
- [Cloud & Self-Hosting Guide](https://github.com/godarayudhvir/retro-player/blob/main/guides/hosting.md): Deployment instructions for Railway, Render, Fly.io, Coolify, Portainer, and NAS (Unraid/TrueNAS).
- [Remote Access Guide](https://github.com/godarayudhvir/retro-player/blob/main/guides/remote-access.md): Anywhere play via Tailscale Mesh VPN and Cloudflare Tunnels.
- [Controls, Keybindings & Accessibility](https://github.com/godarayudhvir/retro-player/blob/main/guides/controls.md): Complete controller button mappings, spatial navigation, tri-modal accessibility heuristics, and in-game controls.
- [Save States & Battery Architecture](https://github.com/godarayudhvir/retro-player/blob/main/guides/save-states.md): Snapshot quick saves vs in-game cartridge battery saves (.sav) across all platforms.
- [Universal Achievements & Milestones Guide](https://github.com/godarayudhvir/retro-player/blob/main/guides/achievements.md): Master registry of 24 universal achievements (300G Gamerscore), points matrix, status checklist, and persistence model.
- [Rich Presence, OS Media Controls & Feeds Guide](https://github.com/godarayudhvir/retro-player/blob/main/guides/presence.md): Real-time gaming presence across Discord Desktop (RPC), OS MediaSession (macOS/iOS/Android/Windows), hardware media keys, and OBS stream overlays.
- [Pokémon Save Inspector & Regional Milestones Hub](https://github.com/godarayudhvir/retro-player/blob/main/guides/pokemon/README.md): Binary SRAM/Flash save inspection specifications across Gen 1 (Kanto), Gen 2 (Johto 16 Badges), Gen 3 (Hoenn & FRLG), Gen 4 (Sinnoh & HGSS), and Gen 5 (Unova).
- [Hardware Compatibility Matrix](https://github.com/godarayudhvir/retro-player/blob/main/guides/compatibility.md): Smart TV (LG webOS, Samsung Tizen), Steam Deck, mobile, tablet, and browser matrix.
- [ROM Management & Sidecar Metadata](https://github.com/godarayudhvir/retro-player/blob/main/guides/roms.md): Directory organization, folder mounting, and local companion sidecars (.nfo, .json, cover.webp) guide.
- [Background Music (BGM) Architecture](https://github.com/godarayudhvir/retro-player/blob/main/guides/bgm.md): Virtual audio hierarchy, dual-layer directory scanning, codec formats, and smart in-game pause.