Coding for the Playstation 1 - PSX Development in 2013 - by Orion_

It has been a very long time since I wanted to write a tutorial on how to code for the Playstation 1, and I always got lazy. But lucky you, here it is !
This tutorial takes into account that we are in the year 2013, we have modern PC, with modern OS such as Windows 7, 64bits etc...
Still, it is possible to code for our old Psx without digging for an old dos or win98 PC !

The Psx was my first video game console, I always loved it, but at the time I started coding for it, there were only old websites and not very much active community for it.
People seemed much more interested by other retro console, and I felt like the Psx was a bit too "commercial" for ever being considered a retro platform.
That's why I didn't really tried to do much things on it. :(
But recently, there have been a cool community showing up on Psxdev.net and I felt the Psx was back to life !

So I decided to make this tutorial and release my PsxLib based on the top of the official Psy-Q SDK.
I won't cover here open source sdk, there are some nice and easy to use library out there (blade libs for example), but you can't really unleash the full power of the Psx with them. (for example cd/pc loading and movie player)
I will also assume that you have basic knowledge of homebrew, console hacking, curiosity, and of course, average C programming knowledge !

- Hardware and Software needed

- Hardware Setup

- Software Setup

- Psy-Q SDK Setup

- Graphic System of the Playstation, VRAM & TIM image

- Converting Sound, VAG format

- CDRom and Data loading philosophy of my library.

- Creating a valid Psx CD Image.

- Info on my Personal Playstation Development Library.


Hardware and Software needed

If you want to code for the Psx, you will need to find the PSY-Q official SDK.
I won't show you how to get it, just search on the internet, it's easy to find :)

Then you can download my personal Playstation Development Library for the PSY-Q SDK: psxlib.zip
This library provide an easy to use way of coding for the Playstation.

You can also download this pack of tools that will be used in this tutorial: psxdevpack.zip
Unpack this file somewhere (for example: "c:\psx") and keep it ! I will point you to this pack every time you will need a tool during this tutorial !

Then, to test your productions, you can use an emulator or a real Playstation !

A really nice and very accurate emulator is no$psx, you can find it here: http://nocash.emubase.de/psx.htm

Although, I don't recommend my tutorial to be used with emulators, because of my "datamanager" which use external files, you will need to create an ISO CD each time you want to test on the emulator.
If using an emulator, you should include your data files directly into your PSX EXE so it's easier to test on emulator then.

If you want to test your productions on the real hardware, you will need a Playstation 1 :)
You can have a psone, but you will need a modchip or a boot cd, and you will need to burn a cd for each test you want to make !

There is another solution, easier for fast development, you can upload data from your PC to the Psx memory !
For this, you will need an old model Playstation with a parallel port like this one:



You also need a PC with a parallel port !
If your PC don't have a parallel port, you can buy a PCI Express card like this one, or this one if you have a notebook.



Finaly, you need a not so common "action replay" called, the "Xplorer FX".
No other action replay will work, even if you think that your action replay have a parallel port, it doesn't !
Only the Xplorer FX have a port that can be plug directly into your PC parallel port !



There is another modern solution called, the Psx Blaster, it use USB port, but I don't have it and I don't know if it is out yet, check it here


Hardware Setup

Once you have your PC ready, plugged with a parallel cable to your Xplorer FX, also plugged into your Psx, you will need to flash the Xplorer FX with a development bios called "caetla".
With older PC and tools, you could do it from the PC, but now you can't, so you will need to burn a CD and boot it from your Psx to flash the action replay.

I made a ready to use cd image for this, you will find it in the "psxdevpack.zip", in the folder "tools\cdflash".
You can use the free tool "ImgBurn" to burn this image into a blank CD-R. http://www.imgburn.com/

Select "Write image file to disc", select the "CAETLAFLASH.CUE" file, and set writing speed to "1x" ! (even if your cd burner won't burn under 8x)



Burn the CD, boot it on your Playstation using a modchip or a boot cd, press R2 to see if it can detect your action replay.
Press "start", select the image file "caetla037" then press "X".
Wait for the flash to end, then reboot your Psx with the action replay on, and voila ! you should see the new caetla menu :)

Ok, we are ready with our hardware setup for Psx deving !

Software Setup

You will need a little tool called "catflap" to communicate from your PC to your Psx.
Unfortunately, this tool doesn't work on modern OS ..
But wait ! After a lots of internet research, I found the source code of this tool and modified it to use modern compiler and parallel port library so it now works on Windows 7 64bits !

You can find this tool on my website: http://onorisoft.free.fr in the retro / Psx part, but it is also included in this pack "psxdevpack.zip" in the "tools\catflap" folder.

To install this for the first time, just go in the "tools\catflap\inpout32" folder and launch "InstallDriver.exe".
It will install the parallel port communication driver "inpout32.dll".
Then go back and launch a dos "cmd" box in the "catflap" folder and start playing with the catflap exe.
For example, type "catflap run file.exe" to send and start the "file.exe" Psx program on your Psx !
Start the "vram.bat" file to dump the Psx screen into a bmp file !

Psy-Q SDK Setup

Now we will setup the Psy-Q official SDK.
Then I will show you how to use my Psx library, it is much easier to use than understanding the official SDK.

Create a "Psx" or "Psxdev" (or whatever you like) folder somewhere, and unpack the Psy-Q SDK in it.
For example "C:\psx\psyq", you should get these files.



Go into the "bin" folder and copy here some useful tool you will need at anytime (so it will be accessible from your path)
Check my "psxdevpack" and copy "cpe2x.exe" available in the "tools\cpe2x" folder.
Also, copy the "catflap.exe" + "inpout32.dll" available in the "tools\catflap" folder.



Edit the "psyq.ini" file to change the path where Psy-Q is located.



My path is "E:\programmation\psx\psyq" but if you unpacked psy-q in "C:\psx\psyq", then the first line of your "psyq.ini" file should be:
library_path=C:\psx\psyq\lib
And so on for the other lines

Once done with psyq, let's go into the "examples\rpgtest" folder of my development library (psxlib.zip)
Edit the "compil.bat" file into notepad (or right click, edit)
Modify the 2 first line according to where Psy-Q is located, for example:
set PATH=C:\PSX\PSYQ\BIN
set PSYQ_PATH=C:\PSX\PSYQ\BIN


Save and close the file, double click on it and the compilation should now be done and create a "MAIN.PSX" file, which is the exe file you will send to the Psx.
Do the same path modification for the "send.bat" file, and double click on it, it should send the program to your Psx and you will see an RPG like map with a dialog box.




Graphic System of the Playstation, VRAM & TIM image

In my library you have some examples on how to load and display sprites and images.
But even if my library simplify this process, you need understand how the Playstation graphic system works, in order to prepare your image.
Images files for the Playstation are in the TIM format.
You can create a TIM file using a plugin that will load in Photoshop or in PaintShopPro.
You will also be able to edit this TIM file using the TIM Tool utility.
You can search for these tools on the internet "TIM Tool" and "tim_plugin.zip" or download them here for example.
If you have PaintShopPro you can put the .8b* plugin files inside the "C:\Program Files\Paint Shop Pro\Plugins" folder.

Now you can load a picture, paletted or not, and save it as a .tim file.
This will popup a dialog box:



Tick the box "Black as transparent" if you want the black pixels 0:0:0 to be transparent.
Select the "Except black as translucent" if you want to use transparency on your sprite.

Also you can edit here the position of the image within the VRAM of the Playstation.
But what does that mean ??

The Playstation have a chip called the GPU, and the GPU process all the graphics on screen.
This GPU will process graphics only from the Video RAM (or VRAM)
The VRAM on the Playstation is a space of 1024x512 16bits pixels. (=1Mbyte)
This space contains:
-The current screen showing on the TV. (the green space in the screenshot below)
-The screen currently being drawn for the next frame. (the yellow space in the screenshot below)
-The rest of the free space used to store textures, images, sprites and palettes. (the blue space in the screenshot below)



The VRAM is split into Texture Pages of 256x256 pixels max !
And a sprite cannot overlap 2 Texture Page !
That's why you can't have a Sprite of the size of the screen ! (ie: 320x240)
You need to have 2 sprites, one of 256x240 and one of 64x240

Each TIM file have information on where it will be loaded inside the VRAM space.
Using the TIM Photoshop Plugin you can edit the coordinates by hand, but this is a bit painful.
That's why a tool called TIM Tool was made, and it will allow you to edit the place where your TIM files are loaded easily.

Launch TIM Tool and click on the "Add Tim" button, then select your TIM file.



Now click on the TIM file in the down-left list, and move the image inside the VRAM space in order to place it just after the (green) screen area.
If this TIM image is 4 or 8bits (paletted) you must place the CLUT inside the VRAM too.
The CLUT is the palette, so for example it will take 256x1 pixels inside the VRAM for a 8bits image.

To auto place the CLUTs inside the VRAM, place your cursor where you want to place the CLUTs.
Hold the "shift" key on your keyboard then click and drag the zone where the CLUT will be. Now select in the menu "CLUT -> Auto sort 8bits CLUT"



Now go in the menu "TIM Options" and click "Save modified TIM's".
Your TIM file is ready to be loaded !

Converting Sound, VAG format

On the Playstation, the Sound format is called VAG, it's a compressed sound format, and you only have 512Kbytes of space for compressed sound.
To convert a WAV to VAG, you can use a tool called VAGedit. It's pretty straightforward to use.




CDRom and Data loading philosophy of my library.

First you have to know that the Psx only have 2Mbytes of program memory, 1Mbytes of VRAM for graphics, and 512Kbytes for sound (compressed)
So, the typical "homebrew" way is to include all the data inside the Psx exe program and send this to the Psx, the problem is, your program need to be smaller than 2mbytes, else it won't fit into memory.
This can be ok for small homebrew game, but when doing bigger game, it is a problem because you might have much more datas (we have 650mbytes of CD space available !!)

So, I choose to not include my data, and to load them externally, using the CD as a storage device.
But how do you proceed when debugging on PC ? You won't burn a CD every time !
No, you just have a nice feature in caetla bios that will allow you to load any data from the PC to the PSX remotely while your program is running !
And when making a cd release, you just have to do the same but from the CD !

So I made a "datamanager" library that takes care of that for you.
You use the same loading functions, and depending on if you compil for a debugging test from PC or a CD release, you just change a compilation flag and loading will works the same way !
How nice is that ?

So, generally I put my datas in the "data" folder, and when starting the program from the PC, you will see some lines appearing in the dos box:



This is remote data loading from PC through the parallel port cable and xplorer fx.

Now, how to make a cd release ?

Easy ! Just edit the "compil.bat" file, and uncomment the line "CDROM_RELEASE" by removing the 2 first ":"



Double click on the "compil.bat" to recreate the MAIN.PSX exe file in cd release version.

Select the MAIN.PSX file and the "data" folder, and copy them.
Go into the "makecd" folder of my "psxdevpack" and paste the file/folder into the "ISOROOT" folder.
This will be the "root" of our Psx cd !

You will notice a file called "SYSTEM.CNF", this is the first file the Psx will load, and search inside what exe program to boot from.
You can edit this file in notepad to change the Psx exe file, by default I wrote "BOOT=cdrom:\MAIN.PSX;1" so, as our exe file is named "MAIN.PSX" it's already ok, leave it like that.
(tip: double click on the edit.bat file to edit the system.cnf file in notepad)

Creating a valid Psx CD Image.

Now, we are going to create our cd image, this is my way to do it, there are plenty of other tool to do that, maybe better, maybe easier, etc...
But this is my way, using some old tool, and I have proven it works on a real Psx hardware !

So, use the tool I provided called "PSXISOMaker.exe" and select the "ISOROOT" folder in the first text field.
Choose your iso file name, select the country of your Psx hardware and click on "generate Psxiso"



This will create a .bin and .cue file.
If you move the .bin/.cue file, don't forget to edit the .cue file in notepad to remove the fixed folder path, just leave the file.bin name only.

Now, with this you can try the .bin file into a Psx emulator and it should work !



You can also burn this cd image on a blank cd-r and boot it on a real Psx hardware using a modchip or a boot cd.

Info on my Personal Playstation Development Library.

You can see the sample programs for using my library in the "Examples" folder.
Also you can check out the header files (.h) in the "MyPsxLib" folder to learn more about additionnal functions not used in the samples.