engine-psx / Sonic The Hedgehog XA

Open source platformer engine built for the PlayStation 1.

This engine is focused on building the fangame Sonic The Hedgehog XA, and therefore is not dissociated with said project.

Heavily inspired by Sonic The Hedgehog. Uses PSn00bSDK.

Game title screen running on DuckStation, dated [2024-09-12].

About

This is a platformer game engine build for the PlayStation 1, heavily inspired by Sonic The Hedgehog. The focus here is on experimentation, attempting to build a sane 2D engine in pure C while taking advantage of what the PlayStation has to offer in terms of hardware.

This engine is opensource and can be built by anyone. Also, since it uses Psn00bSDK, it also contains no copyrighted material. Plus, any tools used in this project are modern, opensource or cheap to acquire.

Some assets use different formats than common formats. This is because I needed a better way to process these files, or the PlayStation recognizes different formats.

All code is tested under emulators PCSX-Redux and DuckStation, and are also tested on real hardware (a PlayStation model SCPH-5501).

Recommended tools

Here are some tools I’ve been using. Please notice that this project’s development has been targeted for Linux environments.

GIMP with G’Mic plugin (to reduce image colormaps to 256 colors with no dithering);
Aseprite (for handling sprite sheets and tilemaps), plus some useful script files (tweak export_tileset.lua so it only exports with a row_len of 32, since all tiles are 8x8);
mkpsxiso, to build the ISO files;
gcc-mipsel compiler toolchain;
timedit, to import images and convert them to .TIM format;
wav2vag, to convert .WAV sound effects to .VAG audio;
psxavenc, to convert music to a preliminary .XA format;
xainterleave, to interleave .XA files into a single, ready-for-production .XA file;
cdrdao, if you intend on burning your ISO on a CD-R;
CMake and GNU Make, for build scripts;
GNU Make and Python 3.12 for running extra build scripts.

Some of these tools are already available when you properly install PSn00bSDK. Just follow this guide.

Debugging

First of all, generate a disk image (that will be used as filesystem) and the executable ELF file. This can be consolidated individually with the following commands:

make elf
make iso

Note that, if you’re not generating new assets, you won’t need to rebuild the disk image (here named as the iso target, even though it generates BIN+CUE). Just rebuild your ELF file and reload it.

Now open your Linux environment’s ~/.gdbinit file and mark the project’s own .gdbinit as safe:

add-auto-load-safe-path /path/to/engine-psx/.gdbinit

Then, open PCSX-Redux. Go to Configuration > Emulation. Mark the option “Enable GDB Server”, and make sure that the GDB Server Port is 3333.

Still on PCSX-Redux, go to File > Open Disk Image and open engine.cue, but don’t start running the emulation yet; the program won’t be run from the disk.

Now go to the project’s root directory and run:

gdb-multiarch

This will fire up a GDB debug session that interacts with PCSX-Redux. It will even load the ELF file with proper debug symbols.

Have fun.

Running on real hardware

Engine short video running on a PlayStation SCPH-5501, dated [2024-08-19].

In theory, to burn the disc, you would need a Sony license file which comes bundled with the Psy-Q SDK (which I AM NOT using). I WILL NOT provide these files for obvious legal reasons. But if you manage to obtain them, tweak iso.xml to add such a license file. I cannot guarantee that the ISO will work on real hardware if this file is omitted.

You most likely will need a PlayStation console that allows you to run homebrew software – I did not do anything on my model, but again, I bought it from someone else, and I didn’t open it up to check if it was still intact from day one.

You will also need a CD drive capable of burning CD images to physical disks, and you will also need good quality CD-R disks. Do not ignore this. If you’re a fellow brazillian, I recommend Multilaser.

Remember also that this method was tested in an SCPH-5501 model.

Use a command such as this to burn your image into the disk by using cdrdao (do not use other software, unless you know what you’re doing):

cd build/
cdrdao write --speed 1 --driver generic-mmc-raw --swap -n --eject "engine.cue"

If you’re on Windows or you need more information on other methods, check out this awesome guide.

Generating a single file

If you need your .ISO + .CUE to be a single file, you might want to use something to convert it to .CHD format. You can do this by using a tool called tochd:

tochd -d . -- ./build/engine.cue

Gallery

Screenshot	Description
	Alpha engine [2024-08-19]. Same as below, on a physical SCPH-5501.
	Alpha engine [2024-08-19]. New tilesets, animation with variable speed, extended camera.
	Alpha engine [2024-08-16]. Same as below, on a physical SCPH-5501.
	Alpha engine [2024-08-16]. First working implementation of slope collision.
	Alpha engine [2024-08-05]. Same as screenshot below, but on a physical PlayStation (SCPH-5501).
	Alpha engine [2024-08-05]. First implementation of collision, camera and level data.
	Alpha engine [2024-07-22]. Running on DuckStation.
	Alpha engine [2024-07-21]. Running on a physical PlayStation (SCPH-5501).

License

Licensed under the Mozilla Public License 2.0.

luksamuk/engine-psx