PS1Godot — quickstart¶
What this is: a Godot plugin that lets you author PlayStation 1 games in the Godot editor and run them on actual PS1 hardware (or PCSX-Redux). Scenes, meshes, textures, Lua scripting, audio, UI, and MIDI-driven background music all pack into a "splashpack" binary that the psxsplash runtime loads and plays.
It's a Godot-native rethink of SplashEdit (which is a Unity plugin for the same runtime). Same binary format, different editor, better authoring UX.
Status: Phase 2 complete. You can author a full PS1 scene (meshes with
CLUT textures, colliders, nav, interactive objects, UI canvases, cutscenes,
skinned meshes, dialog-driven Lua scripts, and sequenced BGM) in Godot, hit
one button, and see it running in PCSX-Redux. See ROADMAP.md
for what's shipped vs. pending.
Try it in ~15 minutes¶
Works on Windows, Linux, and macOS. The launcher (scripts/run.py)
is Python-based; the .cmd and .sh shims in the same directory wrap
it so muscle memory keeps working on whichever shell you prefer.
1. Install the four tools¶
- Godot 4.7.x .NET build (the C#
/ Mono variant, not the default). You'll point
GODOT_EXEat it in step 3. - .NET 8 SDK. Verify with
dotnet --version. - MIPS cross-compiler for the PS1:
- Windows / macOS: PCSX-Redux's mips helper installs the
mipsel-none-elf-gcctoolchain. From PowerShell (Windows) or a Homebrew shell (macOS): Then in a new terminal:mips install 15.2.0. - Linux (Debian / Ubuntu): the apt-distributed toolchain works out of the box (run.py auto-detects either prefix):
- PCSX-Redux
for emulation. Windows users grab the dev-win-x64 zip; Linux uses
the AppImage /
.deb; macOS uses the.dmg.
2. Get the code¶
Two paths depending on what you want to do:
Path A — "I just want to use the plugin in my own Godot project": grab the latest zips from the Releases page:
- Download
PS1Godot-plugin-<version>.zip, extract into your Godot project'saddons/folder, and enable PS1Godot in Project → Project Settings → Plugins. - Download
psxsplash-runtime-<version>.zipand droppsxsplash.ps-exeinto your project'sbuild/folder so the Run-on-PSX button has a runtime to launch.
You can skip straight to step 5 with this path. The MIPS toolchain is only needed if you want to modify the PS1-side runtime yourself.
Path B — "I want to clone the full repo with the demo, tests, and tools":
--recursive matters — psxsplash has git submodules (nugget,
psyqo-lua). Missing them silently breaks the runtime build.
3. Wire up environment variables¶
From the repo root, check what the launcher currently sees:
That prints the resolved GODOT_EXE, PCSX_REDUX_EXE, MIPS toolchain,
and dotnet paths. Anything labeled (not found) needs an export:
- Windows:
setx GODOT_EXE "C:\path\to\Godot.exe"(then reopen terminals). - Linux / macOS:
export GODOT_EXE=/path/to/godotin~/.bashrc/~/.zshrc.
4. Build the PS1 runtime¶
# All three platforms:
python scripts/run.py build-psxsplash
# Or the platform-native shim if you prefer typing the bare name:
scripts\build-psxsplash.cmd # Windows
./scripts/build-psxsplash.sh # Linux / macOS
Cross-compiles the C++ runtime with the MIPS toolchain and drops the
binary at godot-ps1/build/psxsplash.ps-exe. Takes 30–60s on first run.
5. Open Godot, export the demo, see it running¶
python scripts/run.py launch-editor
# or: scripts\launch-editor.cmd (Windows) / ./scripts/launch-editor.sh
First open takes ~60s (C# assembly build + asset import). When the
Output dock shows [PS1Godot] Plugin enabled.:
- Open
demo/demo.tscnin the FileSystem dock. - Find the PS1Godot panel (dockable — bottom-right by default).
- Click the big red ▶ Run on PSX button.
The plugin exports a splashpack, launches PCSX-Redux, and loads it. You should see an intro cutscene with narration, land next to a spinning green cube, and hear sequenced music playing. Press Triangle next to either cube to interact, walk through the portal-culled room in the distance, or the teleport trigger to hop to a second scene.
What's in the demo¶
| Feature | How it's wired |
|---|---|
| PS1 shader (vertex jitter, 2× color modulate, affine warp, fog) | addons/ps1godot/shaders/ps1.gdshader on every mesh |
| Custom nodes | PS1Scene, PS1MeshInstance, PS1SkinnedMesh, PS1Player, PS1Room, PS1PortalLink, PS1AudioClip, PS1MusicSequence, PS1TriggerBox, PS1UICanvas, PS1Animation, PS1Cutscene, … |
| Lua scripting | Drop .lua on any node; PS1Lua is a first-class Godot script language |
| Rooms + portals | Two rooms + a portal link between them; runtime culls everything you can't see through the portal |
| Cutscenes | Multi-track timelines: camera position + rotation tracks, object animation, synced voice clips |
| Sequenced music | Drop a .mid + short sample WAVs; bind each MIDI channel to a sample; Music.Play("song") from Lua |
| Dialog | UI canvases with Triangle-to-interact; audio-aware auto-hide (box stays up until the voice clip actually finishes); auto-ducks music while on screen |
| Multi-scene | Scene.Load(N) swaps between scenes packed together — demo has a "checkered realm" reachable via a teleport trigger |
The intro cutscene + the music are both MVP features that landed in the
sequenced-music session. The details of that format are documented in
authoring/audio/sequenced-music.md.
Authoring your own scene¶
→ first-scene.md — build a scene from
scratch in ~40 minutes: floor with PS1 textures, third-person
player, an interactive cube that triggers a Lua-driven dialog line.
Ends with a working splashpack booting in PCSX-Redux.
And the pipeline architecture / file-layout conventions live in
CLAUDE.md — worth a skim before modifying anything
substantial.
Troubleshooting¶
"PCSX-Redux boots to a black screen and doesn't load the game." Your
runtime binary at godot-ps1\build\psxsplash.ps-exe is probably stale
against the current splashpack format. Re-run scripts\build-psxsplash.cmd.
"C# build failed" when launching Godot. Install the .NET 8 SDK and
verify dotnet --version prints 8.x.x. Restart terminals afterwards.
NU1102: Unable to find package Godot.NET.Sdk. GODOT_NUPKGS isn't
set or points at the wrong folder. It must be
<GodotInstall>\GodotSharp\Tools\nupkgs. Fix with setx and reopen
terminals. Full detail in installation.md.
Music plays but WAVs sound muffled / wrong. Godot 4.4+ defaults WAV
imports to lossy QOA compression; the splashpack needs raw PCM. The
project overrides this in project.godot ([importer_defaults] wav =
{ "compress/mode": 0 }) so new WAV drops come in uncompressed — but
existing .wav.import files from before the override need to be
re-imported (delete the cached .sample blob in .godot/imported/ and
reopen the project).
More troubleshooting in installation.md. If something's busted and
isn't listed, file an issue or ping me.
Full setup detail¶
Everything above is the short path. If you're setting up a dev machine
or hitting something weird, installation.md is the complete
walkthrough with environment-variable tables and Phase 0 verification
checklist.
🤖 Parts of this codebase and documentation are AI-assisted (Claude Code). The music sequencer pipeline in particular was built in a single session — see the recent commit log for the audit trail.