Turn your uConsole into a
retro gaming handheld.

sudo apt update && sudo apt upgrade -y

# Install RetroArch + common cores
sudo apt install -y retroarch \
  libretro-snes9x \
  libretro-mgba \
  libretro-nestopia \
  libretro-gambatte \
  libretro-genesis-plus-gx \
  libretro-pcsx-rearmed \
  libretro-desmume \
  libretro-fbneo

# Launch RetroArch
retroarch

# Then navigate:
# Main Menu → Online Updater → Core Downloader
# Install these cores:
#   - Mupen64Plus-Next (N64)
#   - PPSSPP (PSP)
#   - FCEUmm (NES — alternative to Nestopia)
#   - Flycast (Dreamcast)

# List installed cores (apt-installed)
ls /usr/lib/libretro/

# You should see files like:
# snes9x_libretro.so
# mgba_libretro.so
# pcsx_rearmed_libretro.so
# genesis_plus_gx_libretro.so

# Cores from the downloader go here:
ls ~/.config/retroarch/cores/

# ─── Video Driver ───
# Use GL for best compatibility on the uConsole
video_driver = "gl"

# ─── Resolution ───
# Match the uConsole's native landscape resolution
video_fullscreen_x = "1280"
video_fullscreen_y = "720"
video_fullscreen = "true"

# ─── Aspect Ratio ───
# Keep original aspect ratio — no stretching
aspect_ratio_index = "22"
# 22 = "Core Provided" — each system uses its native ratio
# NES/SNES = 4:3, GBA = 3:2, etc.

# ─── VSync ───
# Enable for tear-free, disable if you need more performance
video_vsync = "true"

# ─── Smooth Scaling ───
# Bilinear filtering — false for pixel-perfect, true for smoothed
video_smooth = "false"

# ─── Integer Scaling ───
# Keeps pixels crisp by only scaling to integer multiples
video_scale_integer = "true"

# In RetroArch:
# Quick Menu → Shaders → Load Shader Preset
# Navigate to:
#   shaders_glsl/crt/crt-pi.glslp  (for CRT effect)
#   shaders_glsl/handheld/lcd3x.glslp  (for LCD grid)

# To auto-load for a specific core:
# Quick Menu → Shaders → Save → Save Core Preset

# ─── uConsole Keyboard Bindings ───
input_player1_up = "w"
input_player1_left = "a"
input_player1_down = "s"
input_player1_right = "d"
input_player1_b = "j"
input_player1_a = "k"
input_player1_y = "u"
input_player1_x = "i"
input_player1_l = "q"
input_player1_r = "e"
input_player1_select = "tab"
input_player1_start = "return"

# ─── RetroArch Hotkeys ───
input_menu_toggle = "f1"
input_save_state = "f2"
input_load_state = "f4"
input_state_slot_increase = "f7"
input_state_slot_decrease = "f6"
input_toggle_fast_forward = "space"
input_rewind = "r"
input_exit_emulator = "escape"

# Start the Bluetooth service
sudo systemctl enable bluetooth
sudo systemctl start bluetooth

# Open the pairing tool
bluetoothctl

# Inside bluetoothctl:
power on
agent on
scan on
# Put your controller in pairing mode, then:
pair XX:XX:XX:XX:XX:XX
trust XX:XX:XX:XX:XX:XX
connect XX:XX:XX:XX:XX:XX
exit

# Set default core for .nes files:
# Settings → Directory → Core Info
# Then: Quick Menu → Set Core Association → FCEUmm

# Recommended core options (Quick Menu → Core Options):
#   Region: Auto
#   Turbo Enable: On (for speedrunning)
#   Palette: Composite Direct (authentic colors)

# Recommended core options:
#   SuperFX Overclock: 100% (increase to 200% if
#     Star Fox / Yoshi's Island run slow)
#   Hires Blending: Merge (for transparency effects)
#   Lightgun Mode: Touchscreen (for Super Scope games)

# Recommended core options:
#   Solar Sensor Level: 0 (increase for Boktai games)
#   Allow Opposing Directions: Off
#   Use BIOS if Available: On (put gba_bios.bin in system/)
#   Color Correction: Game Boy Advance
#   Interframe Blending: Smart (fixes GBA transparency tricks)

# Recommended core options:
#   Use BIOS: On (much better compatibility)
#   NEON Enhanced Resolution: 1x (keep at 1x on CM4)
#   Frameskip Type: Auto
#   Frameskip Threshold: 95%
#   Threaded Rendering: On
#   Speed Hack: On (helps with demanding games)
#   Analog Mode: DualShock (for analog stick support)
#
# CM5 users: try 2x resolution for sharper 3D

# Recommended core options:
#   GFX Plugin: GLideN64
#   RSP Plugin: HLE (faster than LLE)
#   Resolution: 320x240 (native — don't upscale on CM4)
#   Framebuffer Emulation: On
#   Texture Filter: None (saves CPU)
#   Threaded Renderer: On
#   VI Output Mode: Non-filtered (fastest)
#   CPU Core: Dynamic Recompiler
#
# CM5: try 640x480 for a much sharper image

# Per-game tips for tricky titles:
# GoldenEye — frameskip 1, disable expansion pak
# Perfect Dark — needs CM5 for playable speeds
# Conker — native resolution, frameskip 1

# Recommended core options:
#   Internal Resolution: 1x PSP (480x272) on CM4, 2x on CM5
#   Frame Skipping: 1 (for 3D games on CM4)
#   Auto Frameskip: On
#   Backend: OpenGL
#   Texture Scaling: Off on CM4, 2x on CM5
#   Hardware Transform: On
#   Software Skinning: On
#   Vertex Cache: On
#   I/O Threading: On

# Games that run great on CM4:
# - Persona 3 Portable, Final Fantasy Tactics
# - Patapon, LocoRoco, Lumines
# - Monster Hunter (with frameskip 1)

# Set performance governor (all cores)
echo performance | sudo tee /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

# Verify
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
# Should output: performance

# Make persistent — add to /etc/rc.local before "exit 0":
echo performance > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor
echo performance > /sys/devices/system/cpu/cpu1/cpufreq/scaling_governor
echo performance > /sys/devices/system/cpu/cpu2/cpufreq/scaling_governor
echo performance > /sys/devices/system/cpu/cpu3/cpufreq/scaling_governor

# ─── Threading ───
video_threaded = "true"

# ─── Audio ───
audio_latency = "64"
audio_driver = "alsa"

# ─── Rewind (disable to save CPU) ───
rewind_enable = "false"

# ─── Run-Ahead (reduces input lag — only for 8/16-bit) ───
# run_ahead_enabled = "true"
# run_ahead_frames = "1"

# Close unnecessary services
sudo systemctl stop cups avahi-daemon ModemManager

# Kill compositors
killall picom compton 2>/dev/null

# Increase GPU memory (CM4 — add to /boot/config.txt)
gpu_mem=256

# Disable Bluetooth if not using BT controller
sudo systemctl stop bluetooth
sudo rfkill block bluetooth

mkdir -p ~/roms/{nes,snes,gba,gbc,genesis,psx,n64,psp,ds,arcade}

# Set RetroArch to scan:
# Settings → Directory → File Browser → ~/roms

# Structure:
# ~/roms/
# ├── nes/          ← .nes, .zip
# ├── snes/         ← .sfc, .smc, .zip
# ├── gba/          ← .gba, .zip
# ├── gbc/          ← .gbc, .gb, .zip
# ├── genesis/      ← .md, .gen, .zip
# ├── psx/          ← .bin/.cue, .chd, .pbp
# ├── n64/          ← .n64, .z64, .v64
# ├── psp/          ← .iso, .cso
# ├── ds/           ← .nds
# └── arcade/       ← .zip (FBNeo romset names)

mkdir -p ~/.config/retroarch/system

# Verify path in RetroArch:
# Settings → Directory → System/BIOS

sudo apt install -y mame-tools
chdman createcd -i game.cue -o game.chd

# From Debian repos (quick)
sudo apt install -y ppsspp

# Or build from source (latest, recommended)
sudo apt install -y build-essential cmake git \
  libsdl2-dev libvulkan-dev libgl-dev
git clone --recurse-submodules https://github.com/hrydgard/ppsspp.git
cd ppsspp && mkdir build && cd build
cmake -DUSING_EGL=ON -DUSING_GLES2=ON ..
make -j$(nproc)

# Run:
./PPSSPPSDL /path/to/game.iso

# Graphics:
#   Backend: OpenGL
#   Resolution: 1x PSP (CM4) / 2x (CM5)
#   Frame Skipping: Auto, Max 1
#   Hardware Transform: On
#   Vertex Cache: On
#   Lazy Texture Caching: On

# System:
#   I/O Threading: On
#   Fast Memory: On
#   Multithreaded: On

# Download ARM64 AppImage
wget https://github.com/stenzek/duckstation/releases/latest/download/DuckStation-aarch64.AppImage
chmod +x DuckStation-aarch64.AppImage
./DuckStation-aarch64.AppImage

# First run setup:
# 1. Set BIOS path: Settings → BIOS → ~/.config/retroarch/system
# 2. Add game directory: Settings → Game List → Add
# 3. Configure controller mapping

# Graphics:
#   Renderer: OpenGL
#   Internal Resolution: 1x (CM4) / 2x (CM5)
#   PGXP Geometry Correction: On (fixes 3D wobble)
#   True Color: On (removes PS1 color banding)
#   Texture Filtering: Nearest (authentic look)

# Advanced:
#   Enable Recompiler: On
#   Recompiler Fast Memory: On