#+title: 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 [[https://github.com/Lameguy64/PSn00bSDK/tree/master][PSn00bSDK]]. #+html:
[[file:./screenshots/titlescreen-100424.gif]] #+html:
/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 [[https://github.com/Gabinou/tilemap_scripts_aseprite][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 [[https://github.com/Lameguy64/PSn00bSDK/blob/master/doc/installation.md][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: #+begin_src bash make elf make iso #+end_src 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: #+begin_example add-auto-load-safe-path /path/to/engine-psx/.gdbinit #+end_example 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: #+begin_src bash gdb-multiarch #+end_src 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. ** A note on gdb-multiarch and Arch Linux For some reason, =gdb-multiarch= right now cannot be installed from AUR. So you'll probably have to generate the package from a PKGBUILD by cloning the repo and building it: #+begin_src bash git clone --depth=1 https://aur.archlinux.org/gdb-multiarch.git/ cd gdb-multiarch makepkg -si #+end_src Notice that you MIGHT Have to tweak download links and the =pkgver= variable as well! If you install the =gdb= package, take a look at the version of the package =gdb-common= which is also installed with it. (If you have other problems you can just pass =--skippgpcheck= to =makepkg=, but be wary of what you're doing) * Running on real hardware #+html:
[[file:./screenshots/sonicxa-realhardware-xmas-24.gif]] #+html:
/Amazing Ocean Zone autodemo running on a PlayStation SCPH-5501, dated [2024-12-25]./ 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): #+begin_src bash cd build/ cdrdao write --speed 1 --driver generic-mmc-raw --swap -n --eject "engine.cue" #+end_src If you're on Windows or you need more information on other methods, check out [[https://alex-free.github.io/psx-cdr/][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 [[https://github.com/thingsiplay/tochd][tochd]]: #+begin_src bash tochd -d . -- ./build/engine.cue #+end_src * Gallery | Screenshot | Description | |-------------------------------------------------------+---------------------------------------------------------------------------------------------------------| | [[file:./screenshots/sonicxa-v0.1.gif]] | Version 0.1 [2025-04-24]. First tag featuring Sonic, Tails, Knuckles, and a bunch of other stuff. | | [[file:./screenshots/sonicxa-realhardware-xmas-24.gif]] | Beta engine [2024-12-25]. Christmas build. Showcasing Amazing Ocean running on AutoDemo. | | [[file:./screenshots/sonicxa-122224-aoz.gif]] | Beta engine [2024-12-22]. Amazing Ocean Zone. Much more mature with many objects and water implemented. | | [[file:./screenshots/sonicxa-110424-swz.gif]] | Beta engine [2024-11-04]. Like below. Showcasing Surely Wood Zone, springs, background, etc. | | [[file:./screenshots/sonicxa-110424-ghz.gif]] | Beta engine [2024-11-04]. Many changes, notably a HUD, improved collision, spikes and damage. | | [[file:./screenshots/sonicxa-100424-gh.gif]] | Beta engine [2024-10-04]. Same as below, showcasing Green Hill Zone. | | [[file:./screenshots/sonicxa-100424.gif]] | Beta engine [2024-10-04]. Includes object rendering, and monitors and rings can be interacted. | | [[file:./screenshots/sonicxa-092224-gh.gif]] | Beta engine [2024-09-22]. Same as below, but showcasing an initial Green Hill Zone. | | [[file:./screenshots/sonicxa-092224.gif]] | Beta engine [2024-09-22]. Modifications of test level, collision layout and much more. | | [[file:./screenshots/engine-psx-081924-realhardware.gif]] | Alpha engine [2024-08-19]. Same as below, on a physical SCPH-5501. | | [[file:./screenshots/engine-psx-081924.gif]] | Alpha engine [2024-08-19]. New tilesets, animation with variable speed, extended camera. | | [[file:./screenshots/engine-psx-081624-realhardware.gif]] | Alpha engine [2024-08-16]. Same as below, on a physical SCPH-5501. | | [[file:./screenshots/engine-psx-081624.gif]] | Alpha engine [2024-08-16]. First working implementation of slope collision. | | [[file:./screenshots/engine-psx-080524-realhardware.gif]] | Alpha engine [2024-08-05]. Same as screenshot below, but on a physical PlayStation (SCPH-5501). | | [[file:./screenshots/engine-psx-080524.gif]] | Alpha engine [2024-08-05]. First implementation of collision, camera and level data. | | [[file:./screenshots/engine-psx-072224.gif]] | Alpha engine [2024-07-22]. Running on DuckStation. | | [[file:./screenshots/engine-psx-realhardware-072124.gif]] | Alpha engine [2024-07-21]. Running on a physical PlayStation (SCPH-5501). | * License Licensed under the Mozilla Public License 2.0.