|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +This is a Windows 10/11 EmulationStation auto-installer that sets up a complete retro gaming environment. The main script (`prepare.ps1`) automates the download and configuration of EmulationStation Desktop Edition (ES-DE), RetroArch cores, multiple emulators, and public domain ROMs. |
| 8 | + |
| 9 | +**Recent Updates (2025):** |
| 10 | +- Updated to ES-DE 3.3.0 (modern EmulationStation) |
| 11 | +- Replaced Yuzu with Suyu (Nintendo shut down Yuzu in 2024) |
| 12 | +- Added DuckStation for superior PlayStation 1 emulation |
| 13 | +- Updated RetroArch to 1.21.0 and PCSX2 to 2.5.68 |
| 14 | +- Improved error handling and download validation |
| 15 | +- Added progress indicators and better logging |
| 16 | + |
| 17 | +## Core Commands |
| 18 | + |
| 19 | +### Main Installation |
| 20 | +- `.\prepare.ps1` - Main installation script (requires PowerShell admin session) |
| 21 | +- `Set-ExecutionPolicy Bypass -Scope Process -Force; .\prepare.ps1` - Run with execution policy bypass |
| 22 | + |
| 23 | +### Development/Testing Commands |
| 24 | +- No specific build or test commands - this is a PowerShell deployment script |
| 25 | +- Script can be re-run safely to recover from interrupted installations |
| 26 | +- Use `Get-ExecutionPolicy` to check current PowerShell execution policy |
| 27 | + |
| 28 | +### Utility Scripts |
| 29 | +- `.\misc\scripts\scraper.ps1` - ROM metadata scraping tool (requires ScreenScraper account) |
| 30 | +- `.\misc\scripts\onedrive.ps1` - Configure OneDrive storage for ROMs and saves |
| 31 | + |
| 32 | +## Architecture |
| 33 | + |
| 34 | +### Core Components |
| 35 | +1. **prepare.ps1** - Main orchestration script that: |
| 36 | + - Installs Chocolatey and Scoop package managers |
| 37 | + - Downloads and configures EmulationStation |
| 38 | + - Sets up RetroArch with multiple libretro cores |
| 39 | + - Installs standalone emulators (Citra, PPSSPP, Yuzu, RPCS3, Dolphin, Cemu, Vita3K) |
| 40 | + - Configures ROM directories and downloads public domain games |
| 41 | + - Generates EmulationStation system configuration |
| 42 | + |
| 43 | +2. **download_list.json** - Centralized configuration for all downloads: |
| 44 | + - `downloads`: Direct URL downloads (emulators, cores, ROMs) |
| 45 | + - `releases`: GitHub release downloads (scrapers, themes) |
| 46 | + - `other_downloads`: Additional homebrew content |
| 47 | + - `extra_nes_games`: Extended NES homebrew collection |
| 48 | + |
| 49 | +### Installation Structure |
| 50 | +- Main installation: `%UserProfile%\.emulationstation\` |
| 51 | +- ROMs: `%UserProfile%\.emulationstation\roms\` |
| 52 | +- RetroArch: `%UserProfile%\.emulationstation\systems\retroarch\` |
| 53 | +- Emulators: Various paths (`%UserProfile%\scoop\apps\`, `C:\Program Files\`, etc.) |
| 54 | + |
| 55 | +### Emulator Configuration |
| 56 | +The script configures 20+ gaming systems including: |
| 57 | +- Retro consoles (NES, SNES, Genesis, N64, etc.) via RetroArch cores |
| 58 | +- Modern systems (3DS via Citra, Switch via Suyu, PS3 via RPCS3) |
| 59 | +- PlayStation systems (PS1 via DuckStation, PS2 via PCSX2 2.5.68) |
| 60 | +- Handheld systems (PSP via PPSSPP, Vita via Vita3K, Game Boy family) |
| 61 | +- Nintendo consoles (GameCube/Wii via Dolphin, Wii U via Cemu) |
| 62 | +- Computer platforms (Amiga, C64, MSX) |
| 63 | + |
| 64 | +### Key Functions in prepare.ps1 |
| 65 | +- `DownloadFiles()` - Downloads from JSON configuration with progress tracking |
| 66 | +- `GithubReleaseFiles()` - Fetches latest GitHub releases |
| 67 | +- `Test-DownloadedFiles()` - Validates successful downloads |
| 68 | +- `Expand-Archive()` - Custom 7-Zip extraction wrapper |
| 69 | +- System setup blocks for each emulator/console |
| 70 | +- Improved error handling and TLS 1.2 support |
| 71 | + |
| 72 | +## File Locations |
| 73 | +- Installation script: `prepare.ps1` |
| 74 | +- Download configuration: `download_list.json` |
| 75 | +- Registry tweaks: `misc/registry_tweaks/` |
| 76 | +- Utility scripts: `misc/scripts/` |
| 77 | +- Documentation: `README.md`, `misc/translations/` |
| 78 | + |
| 79 | +## Development Notes |
| 80 | +- Script requires Windows PowerShell 5+ and admin privileges |
| 81 | +- Downloads are cached in `requirements/` folder to enable resumable installs |
| 82 | +- All configurations use absolute paths with PowerShell variable expansion |
| 83 | +- ES-DE config is generated dynamically with proper paths |
| 84 | +- Enhanced error handling, download validation, and progress tracking |
| 85 | +- TLS 1.2 support for secure downloads |
| 86 | +- Fallback emulators provided where modern alternatives exist |
| 87 | + |
| 88 | +## Important Changes from Original |
| 89 | +- **Yuzu Replacement**: Nintendo shut down Yuzu in March 2024. Script now uses Suyu as Switch emulator |
| 90 | +- **Modern EmulationStation**: Updated to ES-DE 3.3.0 for better compatibility and features |
| 91 | +- **Better PS1 Emulation**: DuckStation provides superior accuracy compared to ePSXe |
| 92 | +- **Latest Versions**: All emulators and cores updated to current stable releases |
| 93 | +- **Improved Reliability**: Better error handling and download validation |
0 commit comments