engine-psx/README.org

#+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: <center>
[[file:./screenshots/titlescreen-100424.gif]]
#+html: </center>

/Game title screen running on PCSX-Redux, dated [2024-10-04]./

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

*Also get a build on 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.

* Running on real hardware

#+html: <center>
[[file:./screenshots/engine-psx-081924-realhardware.gif]]
#+html: </center>

/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):

#+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-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.