psxrecomp/docs/GETTING_STARTED.md

Your first PSXRecomp port

This is one Windows x64 path from your own disc image to a generated game project. It uses a terminal and an editor. No AI assistant or account is required. Start with the stock game and OpenBIOS; add mods after you have a repeatable working baseline.

If you want to play an existing port, choose it from the game list and follow that game's download and disc-selection instructions instead.

1. Install the tools

Install Git for Windows and Python 3, available on PATH. Download the Windows x64 cmake-clang-v1 toolchain ZIP from the toolchain releases and extract it to D:\RecompDev\Toolchain. Use the folder containing bin. This supplies the compiler, CMake and Ninja for this guide.

Open PowerShell and prepare the session:

New-Item -ItemType Directory -Force D:\RecompDev\Temp | Out-Null
$env:TEMP = 'D:\RecompDev\Temp'
$env:TMP = $env:TEMP
$env:PSXRECOMP_TOOLCHAIN_DIR = 'D:\RecompDev\Toolchain'
$env:Path = "D:\RecompDev\Toolchain\bin;$env:Path"
git --version
python --version
cmake --version
ninja --version

Replace D: with your development drive. Each version check should succeed before you continue. Keep build output, caches and the extracted toolchain on that drive.

2. Prepare a disc and clone the framework

Use your own supported CUE/BIN dump. Extract archives first and keep the .cue with all of its referenced tracks. Leave the disc outside the source repository. This example uses D:\Discs\My Game\game.cue.

Set-Location D:\RecompDev
git clone --recurse-submodules https://github.com/RetroPortingToolKit/psxrecomp.git
Set-Location psxrecomp

Check the existing projects before starting another port of the same game. Their per-disc configurations and validation may give you a better starting point for a contribution.

3. Generate one local game project

Run the setup command with these fixed first-project choices:

powershell -File tools\new_project_layout\setup_project.ps1 `
  -Disc 'D:\Discs\My Game\game.cue' -Dir D:\RecompDev `
  -Name MyFirstPSXPort -GithubRepo my-first-psx-port -Players 1 -Yes `
  -EnableRecompUi -NoNetplay -NoFetchBoxart -NoGithub -Generate -EnableBuild

The output folder is D:\RecompDev\my-first-psx-port. The script probes the disc, records its identity, creates the framework/UI submodules, generates the game and open-source OpenBIOS code, then configures and builds. The GitHub slug above controls the local folder; -NoGithub keeps the project local. You do not need to supply a retail BIOS for this path.

Wait for generation and compilation to succeed. Read errors at the step where they occur; a created folder alone is not a completed build. Open the executable at the path printed by setup, select the same disc if asked, and try a cold boot with the default presentation.

4. Make one short route reliable

Your first goal is boot → title menu → first gameplay scene. Compare input, graphics, sound and transitions with the original game in a trusted emulator. Record what works and the smallest sequence that reproduces a failure.

The new project owns game.toml, symbol/analysis inputs and game-specific integration. The framework owns the shared hardware runtime. Keep original disc data outside Git, and fix analysis/configuration or runtime behavior instead of hand-editing generated functions to force a result.

Games can stream executable overlays from disc. Reaching a title screen does not establish that later overlays or a full campaign work. Read the execution model and overlay guide when the next failing scene needs more code coverage.

5. Add enhancements after the baseline

Keep one disc revision and the original game behavior working before adding widescreen, multiplayer, translations or alternate content. Each feature needs its own tested contract. Additional discs and content variants need explicit identities and integration; selecting a different image does not make it supported.

Use the project reference for regeneration and packaging, and manual mod authoring for the mod system. Include the required license notices when distributing a build. The full build reference covers other host platforms and advanced toolchain choices.