engine-psx/README.org

#+title: engine-psx

Open source platformer engine built for the PSX.

Uses [[https://github.com/Lameguy64/PSn00bSDK/tree/master][PSn00bSDK]].

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

/Engine short video running on DuckStation, dated 07/22/2024./

* 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:

- 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);
- =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.

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]].

** Running on real hardware

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

/Engine short video running on a PlayStation SCPH-5501, dated 07/21/2024./

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 "sonicengine.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]].

** Running on your browser

If you're using a  browser emulator such as [[https://emulatorjs.org/][EmulatorJS]] and 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/sonicengine.cue
#+end_src

* License

Licensed under the Mozilla Public License 2.0.