Sonic The Hedgehog XA

Open source Sonic fangame built for the PlayStation 1 (formerly engine-psx).

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 PCSX-Redux, dated [2024-10-04].

VIEW GAME ON ITCH.IO: https://luksamuk.itch.io/sonic-the-hedgehog-xa

GET BUILDS AND BETAS ON THE RELEASES SECTION!!!!

Also visit my website:: https://luksamuk.codes/

About

This is a Sonic The Hedgehog fangame built for the PlayStation 1. The focus here is on experimentation: I’m studying the PlayStation hardware and capabilities while building a 2D sonic game in pure C.

This game is opensource and can be built by anyone. Also, since it uses Psn00bSDK, the source code can be freely distributed.

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);
• Tiled, for anything relating to levels and object positioning. You may also want to install custom exporters that are in tools/tiled_exporter/ and also enable Tiled’s Python scripting format.
• 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

There is a specific target for Sonic XA that generates the current project in Debug mode (without optimizations) and with debug symbols:

make build-debug

Run pcsx-redux. Go to File > Open Disk Image, select SONICXA.cue on the build directory, but don’t start the emulation yet; GDB will start it for us. This will serve as our application’s filesystem.

It may be necessary to enable the GDB Server on pcsx-redux as well. Go to Configuration > Emulation. Mark the option “Enable GDB Server”, and make sure that the GDB Server Port is 3333.

Keep pcsx-redux open on that state.

Now check if you have gdb-multiarch installed (or if you’re on Arch Linux, the package extra/gdb already has multiarch support), then run:

gdb-multiarch

# On Arch Linux:
gdb

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

For more information on debugging with GDB on PCSX-Redux, see this link.

Have fun.

A note on loading .gdbinit

Sometimes it is necessary to “trust” the .gdbinit included on this project so it runs under GDB.

If you experience problems, 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

Running on real hardware

Green Hill Zone boss running on a PlayStation SCPH-5501 and a Philips CRT TV, dated [2025-07-23].

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 "SONICXA.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
	SAGE 2025 Demo (Release Candidate 2) [2025-08-01]. Recorded from a real PlayStation (SCPH-5501) using a capture device.
	Development build [2025-07-23]. Showcasing Green Hill Zone’s boss and Knuckles. Running on a physical PlayStation (SCPH-5501).
	Version 0.1 [2025-04-24]. First tag featuring Sonic, Tails, Knuckles, and a bunch of other stuff.
	Beta engine [2024-12-25]. Christmas build. Showcasing Amazing Ocean running on AutoDemo.
	Beta engine [2024-12-22]. Amazing Ocean Zone. Much more mature with many objects and water implemented.
	Beta engine [2024-11-04]. Like below. Showcasing Surely Wood Zone, springs, background, etc.
	Beta engine [2024-11-04]. Many changes, notably a HUD, improved collision, spikes and damage.
	Beta engine [2024-10-04]. Same as below, showcasing Green Hill Zone.
	Beta engine [2024-10-04]. Includes object rendering, and monitors and rings can be interacted.
	Beta engine [2024-09-22]. Same as below, but showcasing an initial Green Hill Zone.
	Beta engine [2024-09-22]. Modifications of test level, collision layout and much more.
	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.