Development environment setup¶
Goal: from a fresh clone, be able to edit PS1 scenes in Godot, build the psxsplash runtime, and iterate in PCSX-Redux with a one-click loop.
Target time to boot: ~15 minutes for a new machine.
Supported platforms: Windows, Linux, macOS. The launcher
(scripts/run.py) is Python-based and works on all three; the
.cmd / .sh shims wrap it for muscle memory. See
docs/internal/rfc/linux-support.md for the
underlying design.
Prerequisites¶
| Tool | Purpose | Windows | Linux | macOS |
|---|---|---|---|---|
| Godot .NET / Mono build (pinned: 4.7.0-dev.5) | Editor + plugin | godotengine.org/download | same — pick the Linux .NET tarball | same — pick the macOS .NET universal |
| .NET 8 SDK | C# compilation | dotnet.microsoft.com/download | apt install dotnet-sdk-8.0 (or .deb / .rpm) |
brew install --cask dotnet-sdk |
| Python 3.10+ | Launcher (scripts/run.py) |
python.org | system python3 or apt install python3 |
system python3 or brew install python |
| MIPS toolchain | Cross-compile psxsplash | PCSX-Redux mips.ps1 (mipsel-none-elf-gcc) |
apt install gcc-mipsel-linux-gnu binutils-mipsel-linux-gnu |
brew tap pcsx-redux/mips && brew install mips |
GNU make |
Build psxsplash | MSYS2 or Git Bash | apt install build-essential |
comes with Xcode CLT |
| PCSX-Redux | Run PS1 code | dev-win-x64 zip | AppImage / .deb | .dmg |
mkpsxiso (Phase 3+) |
Real-hardware ISO | GitHub releases | same | same — or brew install mkpsxiso if a tap exists |
| JetBrains Rider | IDE + C# debug | JetBrains Toolbox | JetBrains Toolbox | JetBrains Toolbox |
scripts/run.py auto-detects either MIPS prefix (mipsel-none-elf-
on Windows/macOS, mipsel-linux-gnu- on Debian/Ubuntu) and passes
the matching PREFIX=... to make, so contributors don't need to
patch the Makefile.
One-time setup¶
1. Install Godot .NET + .NET SDK¶
- Download the Godot .NET build (currently pinned: 4.7.0-dev.5).
- Extract anywhere — set
GODOT_EXEto the executable's full path: - Windows:
setx GODOT_EXE "D:\Programs\Godot...\Godot_v4.7-dev5_mono_win64.exe" - Linux:
export GODOT_EXE=~/.local/bin/godotin~/.bashrc(or wherever you put it). - macOS:
export GODOT_EXE=/Applications/Godot.app/Contents/MacOS/Godotin~/.zshrc. - Install the .NET 8 SDK if you don't already have it. Verify with
dotnet --version→ should print8.x.x. - Inspect what the launcher resolves — prints the current values
and flags anything missing:
On Windows you can also run the
.cmdshim (scripts\bootstrap-env.cmd); on Linux / macOS the.shshim (./scripts/bootstrap-env.sh). Both route through the same Python entry point.
Why GODOT_NUPKGS matters. The 4.7-dev.5 SDK is not on nuget.org; it ships inside the Godot install at
GodotSharp\Tools\nupkgs\.godot-ps1\NuGet.Configreferences%GODOT_NUPKGS%so Rider and CLIdotnet buildfind it. Without it, you'll seeerror NU1102: Unable to find package Godot.NET.Sdk with version (>= 4.7.0-dev.5). Godot itself injects the path internally, so opening in the editor works even without the env var — but any build outside the editor won't.
2. Install the MIPS toolchain (for building psxsplash)¶
Pick the path for your OS:
Windows. From any PowerShell prompt (not admin — user-scope install only):
Installs silently to %APPDATA%\mips\. After install, open a new
terminal, then mips install 15.2.0 (or whatever mips ls-remote
recommends — psxsplash's Makefile has no version pin). Verify with
mipsel-none-elf-gcc --version.
If you'd rather install elsewhere, download mips.ps1 first then run
powershell -ExecutionPolicy Unrestricted -File mips.ps1 self-install
D:\Programs\mips. The path must have no spaces (installer constraint).
If make isn't on PATH, install MSYS2 and
add C:\msys64\usr\bin, or use Git Bash which ships with make.
Linux (Debian / Ubuntu). The distro toolchain works as-is:
Verify with mipsel-linux-gnu-gcc --version. Other distros: install the
equivalent (mipsel-linux-gnu-gcc-*, binutils-mipsel-linux-gnu-*).
scripts/run.py auto-detects either the none-elf or linux-gnu prefix
and passes PREFIX=mipsel-linux-gnu to make so no Makefile edit is
needed.
macOS. The PCSX-Redux project maintains a Homebrew tap with the
same mipsel-none-elf-gcc binary the Windows installer ships:
make ships with Xcode CLT (xcode-select --install).
3. Install PCSX-Redux¶
- Windows. Download
pcsx-redux-HEAD-win-x64.zipfrom the distrib.app page. Extract anywhere; setPCSX_REDUX_EXEto the full.exepath. - Linux. Grab the AppImage or
.debfrom GitHub releases. Either chmod+x the AppImage andexport PCSX_REDUX_EXE=/path/to/pcsx-redux.AppImage, ordpkg -ithe.deband letrun.pyfindpcsx-reduxon PATH. - macOS. Install the
.dmgfrom GitHub releases; the binary lives at/Applications/PCSX-Redux.app/Contents/MacOS/pcsx-redux. That's the pathrun.pychecks by default — no env var needed if you used the standard install location.
First run on any OS: set OpenBIOS in Configuration → Emulation.
OpenBIOS is bundled; use it to avoid retail-BIOS copyright issues.
4. Install Rider + Godot plugin¶
- In Rider: Settings → Plugins → Marketplace, search for Godot Support (by JetBrains), install, restart.
- Open
godot-ps1\PS1Godot.slnin Rider. The plugin auto-detects theproject.godotsibling and offers a Godot Editor run configuration. - The generated run configuration launches Godot's editor. To get F5-launch-and-debug working:
- Add a second configuration of type .NET Executable pointed at
%GODOT_EXE%with argument--path $ProjectFileDir$ --remote-debug tcp://127.0.0.1:23685. - Or simpler: use the Godot plugin's own "Play" button once the
PS1GodotPluginis enabled in Godot.
5. Configure the external editor for Lua scripts¶
Godot's built-in editor opens .lua files as plain text — no
highlighting or completion. Point Godot at Rider (or VS Code, or your
preferred editor) so double-clicking a Lua script pops it open with
full language support, and run the API-stub generator so the external
editor picks up PS1Godot-specific completions.
See reference/lua-editor-setup.md for the
step-by-step — takes about 5 minutes.
Per-clone bootstrap¶
From the workspace root, any of the equivalent invocations:
# Cross-platform canonical form:
python scripts/run.py launch-editor
# Or the platform-native shim:
scripts\launch-editor.cmd # Windows
./scripts/launch-editor.sh # Linux / macOS
First launch takes 30–60s while Godot imports assets and builds C#.
Expected output in Godot's Output dock: [PS1Godot] Plugin enabled.
Then open demo/demo.tscn — you should see a jittering cube on a flat floor
with nearest-neighbor rendering. That's the PS1 shader working.
Phase 0 verification¶
When all of the below succeed, you're ready for Phase 1 preview work and
Phase 2 exporter work. Substitute the platform-appropriate shim
(launch-editor.cmd on Windows, ./launch-editor.sh on Linux/macOS)
or always use the canonical python scripts/run.py <action> form.
-
python scripts/run.py launch-editoropens Godot. Plugin is listed as enabled in Project → Project Settings → Plugins. -
demo/demo.tscnloads and renders with visible vertex snapping. -
python scripts/run.py build-psxsplashproducesgodot-ps1/build/psxsplash.{ps-exe,elf}. -
python scripts/run.py launch-emulatorboots the empty psxsplash runtime in PCSX-Redux. (Will show "no splashpack found" or similar until Phase 2.) - Rider can open
PS1Godot.sln, build, and set a breakpoint inPS1GodotPlugin.csthat hits when the plugin enables.
Environment variables (summary)¶
| Var | What | Default if unset (per OS) |
|---|---|---|
GODOT_EXE |
Full path to the .NET Godot executable | Windows: D:\Programs\Godot_v4.7-dev5_mono_win64\Godot_v4.7-dev5_mono_win64.exe · Linux: ~/.local/bin/godot · macOS: /Applications/Godot.app/Contents/MacOS/Godot (each falls back to which godot if absent) |
GODOT_NUPKGS |
Full path to <Godot>/GodotSharp/Tools/nupkgs (required for Rider/CLI restore of dev builds) |
— must be set |
PCSX_REDUX_EXE |
Full path to PCSX-Redux executable | Windows: C:\tools\pcsx-redux\pcsx-redux.exe · Linux: ~/.local/bin/pcsx-redux · macOS: /Applications/PCSX-Redux.app/Contents/MacOS/pcsx-redux (each falls back to which pcsx-redux) |
Set them user-scoped so all tooling picks them up:
:: Windows (persistent, user-scope; reopen terminals after):
setx GODOT_EXE "C:\tools\Godot\Godot_v4.7-dev5_mono_win64.exe"
setx GODOT_NUPKGS "C:\tools\Godot\GodotSharp\Tools\nupkgs"
setx PCSX_REDUX_EXE "C:\tools\pcsx-redux\pcsx-redux.exe"
# Linux / macOS — append to ~/.bashrc or ~/.zshrc, then `source` it:
export GODOT_EXE="$HOME/.local/bin/godot"
export GODOT_NUPKGS="$HOME/.local/share/godot/GodotSharp/Tools/nupkgs"
export PCSX_REDUX_EXE="$HOME/.local/bin/pcsx-redux"
python scripts/run.py bootstrap-env prints the resolved values so you
can sanity-check.
Troubleshooting¶
"C# build failed" on Godot launch.
Godot needs the .NET SDK on PATH. Run dotnet --version; if it errors, install
the SDK and restart.
NU1102: Unable to find package Godot.NET.Sdk with version (>= 4.7.0-dev.5).
Your GODOT_NUPKGS env var is unset or points at the wrong directory. It
must point at the nupkgs folder inside your Godot install — the one that
contains Godot.NET.Sdk.4.7.0-dev.5.nupkg. setx GODOT_NUPKGS "..." then
restart Rider/terminals.
"The type PS1Scene could not be resolved."
Godot hasn't built the C# assembly yet. In the editor menu:
Project → Tools → C# → Create C# solution (if prompted), then
Build → Build Solution (hammer icon, top-right). Reopen the scene.
PCSX-Redux errors on -pcdrvbase.
Make sure the directory exists. scripts\launch-emulator.cmd creates it
implicitly via build-psxsplash.cmd, but if you call PCSX-Redux directly,
create godot-ps1\build\ first.
Rider doesn't debug into Godot.
Verify the Godot plugin is installed. Rider's detection is solution-based, so
always open PS1Godot.sln, not individual .cs files.