Native Player

Native Player

Maintained docs in the repository are authoritative; this page is a summary. Last reviewed 2026-09-16.

The native player is a standalone, cross-platform SDL3 desktop application (build/nakagawa_player.exe) designed to replace browser-based frontend friction (interface/) with a native executable.

Architecture

The player UI and setup staging live in src/player/ and src/core/, compiling alongside the runtime with no Node.js or MSVC dependencies.

Component	Files	Role
ISO Reader	src/player/iso_reader.c, iso_reader.h	Clean-room C ISO9660 PVD reader and PARAM.SFO parser identifying disc ID and title against catalog.
XB Extraction	src/player/nk_xb.c, nk_xb.h	Clean-room XB FST parser and native LZS/Huffman/tag-0 decoder; operates without external dependencies.
Setup Staging	src/player/setup_staging.c, setup_staging.h	Worker-facing staging boundary executing ISO directory walks and XB archive extraction.
State Machine	src/player/player_state.c, player_state.h	Finite-state machine managing library entries, inspection, staging metrics, settings, and recovery.
UI Renderer	src/player/ui_renderer.c, ui_renderer.h	SDL3 immediate/retained renderer using Dark Court styling, responsive card layouts, and auto-scaled typography.
Application Core	src/player/main.c	Interactive event loop with native file dialog (SDL_ShowOpenFileDialog), gamepad/keyboard navigation, and drag-and-drop ISO support.

Current capabilities and limits

The implementation status is documented in docs/NATIVE_PLAYER_ARCHITECTURE.md and docs/NATIVE_PLAYER_IMPLEMENTATION_PROGRESS.md:

• Connected in current build:
  • Native file picker, drag-and-drop ISO selection, and PVD/PARAM.SFO inspection.
  • Bounded ISO/XB staging pipeline for the setup wizard, extracting assets and recording layout/audio/visual censuses.
  • Atomic promotion of staged directories and persistent title library registration.
  • Gamepad navigation via SDL3 (D-pad and shoulder buttons for library selection, face buttons for activate/back).
  • Settings dialog for resolution, FPS presets, display toggles, and motion reduction.
  • Discovery of pre-decrypted support PRXs from standard PPSSPP dump directories.
• Unbuilt targets (honest boundaries):
  • Clean-room KIRK cryptographic engine for on-the-fly module decryption remains unbuilt.
  • Automated full retail game preparation and on-demand runtime recompilation from raw ISO remain unbuilt.
  • In-game pause overlay (F1 / Gamepad Guide) remains an unbuilt target.
  • Non-wizard library preparation requests display an honest unavailable state (VIEW_PREPARING).
  • Authentic LLE typography requires user-supplied PSP firmware fonts (jpn0.pgf from flash0:/font/); the UI discloses this requirement rather than faking success.

Build and run

Build the native player with GNU Make from MSYS2 UCRT64:

mingw32-make player
.\build\nakagawa_player.exe

Headless test flags include --demo (in-memory fixtures only, never writes to disk) and --iso=<path> --stage-only for automated staging verification.