Topic: Guide to mapping PlayStation (PSX) 2D games with PSVrammed

[mechaskrom]

A few people have asked me how I did my Suikoden maps so I thought I would write a short guide for the method I use to rip graphics from PSX 2D games. It mainly depends on a program I wrote when mapping Suikoden 2. This program was also used for my Suikoden 1 update and Legend of Mana maps. In this guide I'll use LoM (Legend of Mana) and the BizHawk (PSX octoshock core) emulator in the examples.

The program is called PSVrammed (available on my github page) and it can extract and edit VRAM (video memory) in emulator savestates. It relies on the fact that PSX games don't often change VRAM. Edits in VRAM will usually remain until you trigger a loading screen. I started experimenting with VRAM hacking when mapping Suikoden 2 and it worked so well that I created PSVrammed. With it you can isolate different "layers" in an area and map them one by one. It's also useful for removing things (like sprites) you don't want in screenshots.

The PSX GPU (graphics processor) has 1MB VRAM which fits 1024*512 of 16-bit pixels. The major parts stored in VRAM are framebuffers, textures and palettes (also known as CLUTs, color lookup tables). Palettes are 16-bit and so are framebuffers usually too. Textures are usually 4- or 8-bit which means their pixels are indices to a palette with 16 or 256 colors (16-bit).

16-bit pixels have 3*5=15 bits for red, green and blue, and one alpha bit. The alpha bit is used for masking and blending (semi-transparency) effects. 5 bits give each color channel a decimal range of 0-31. A zero black color (RGB=0,0,0) is normally not drawn by the GPU and used for fully transparent pixels.

I recommend checking online for more info about the PSX's GPU and VRAM. It's good to have some basic knowledge about them when using PSVrammed and mapping PSX games.

Here's an example of VRAM from LoM (Legend of Mana):

LoM uses a very typical VRAM layout. PSX games don't have to use this layout, but it's very common. In the example I've also marked in yellow where LoM stores palettes and textures for backgrounds (BG). LoM uses a mix of both 4- and 8-bit for its backgrounds, but sprites are usually only 4-bit.

[mechaskrom]

Let's continue with an example of how you would map the entrance of Luon Highway in LoM with PSVrammed. I wrote a BizHawk lua-script for LoM that will screenshot-stitch an area and if we run it we will get this:

The result will have an ugly "seam" in the back mountains because that layer scrolls at a different speed than the camera (main layer). We need to isolate the different layers (back+main) and rip them one by one instead.

Make a savestate in BizHawk (e.g. Shift+F10) and open it with PSVrammed. Now we need to locate the palette (or palettes) that the back layer uses. Change to 8-bit palette editor mode (Ctrl+F2) and move the palette marker between the different palettes until you find a likely candidate (look for the mountains to appear in the BG textures area). Press enter to open the edit palette dialog and set the full palette to magenta. Save the changes (Ctrl+S) and reopen the savestate in BizHawk (F10). If we changed the right palette (it's an 8-bit palette located at X,Y=0,473) the back layer will now be magenta. In case we changed the wrong palette, just undo the edit (Ctrl+Z) and try again with another palette.


BizHawk result:


With a solid colored back layer we can now rip the main layer without problems. After that's done we just need to rip the back layer too. We could change all palettes except the back layer's to transparent black (RGB=0,0,0), but a faster way is to use the edit invert function in PSVrammed. Change the size (Ctrl/Shift+PageUp/PageDown) and position (arrow keys) of the texture marker so it encompasses the palettes and then press the I-key. This will write 0 (default edit value in 4- or 8-bit mode) and then undo the full palette magenta edit. All palettes will now be transparent black except the restored back layer palette that we edited in the first step.


BizHawk result:


Finally use your favorite image editor (I like paint.net) to change the magenta to fully transparent and compose the main and back layers. The back layer repeats horizontally every 192 pixels so it can be copy pasted (tiled) in 192 pixel wide chunks until the whole main layer is covered.

The next section of Luon Highway uses the same textures and palettes as the first. It's common in games that sections do this. This means that the edits to isolate the main and back layer will be the same as in the first section. PSVrammed can save a sequence of edits and perform it on other savestates to save work and time. Save the edit sequence after isolating the main layer and then again after the back layer. Edit sequences can be bound to the number-keys (0-9). If everything is setup correctly, you will only have to press a few keys to rip similar sections.

[mechaskrom]

Next we will do a bit more complicated example which uses color blended layers.

PSX has four blend modes/operations. The calculation done per color channel (RGB) for each mode is as follows:

Code: [Select]

1:   N = B>>1 + F>>1   (average, 0.5B + 0.5F)
2:   N = B + F         (add)
3:   N = B - F         (subtract)
4:   N = B + F>>2      (add 1/4, B + 0.25F)

'B'  = value already in the framebuffer
'F'  = value being written to the framebuffer
'N'  = resulting value in the framebuffer (clamped to 0-31, 5-bit)
'>>' = bit shift right operator

Here's how they look like. From left to right: normal, mode 1-4.


Legend of Mana mostly uses mode 2 and 3 which will make the drawn graphics have a bright (good for lights) or dark (good for shadows) transparency effect. The PSX blend modes are different from actual alpha blending that you're probably used to seeing in games and one of many factors which give PSX games that special "PSX look". Incidentally, I believe the SNES has something similar to mode 2 and 3 blending and I actually like the look of this kind of blending.

It can be difficult to see the priorities of blended layers so a tip is to set the layers' palettes to different solid colors to make it easier to tell layers apart.


I strongly suggest ripping blended graphics with the alpha bit cleared because otherwise it's very easy to get wrong results if you don't know exactly what you are doing.

Let's map a section from Norn Peaks (the one after the wind village) in LoM which uses a scrolling fog effect in the foreground. The fog is actually two layers which each use a 4-bit palette. The fog palettes are located at X,Y=80,472 and 96,472 in VRAM.

Remove the fog by setting both palettes to transparent black. After the main layer is stitched without any fog we can continue with ripping the two fog layers. Use the edit invert function to remove all palettes except the two for the fog we just cleared.

Before ripping the fog we want to clear all alpha bits in the two palettes to disable color blending. Move the palette marker to each fog palette and press the P-key. With the alpha bits cleared we can go ahead and rip the two fog layers. Just clear one of the fog's palette to transparent black and rip the remaining fog layer. Undo the clear fog edit and repeat for the other fog layer.

Both fog layers repeat horizontally every 256 pixels so they can be copy pasted in 256 pixel wide chunks until the whole main layer is covered.

To blend ripped layers I made a plugin for paint.net. It's called PS1Blend and can be found on my github. To use it you specify the blend mode in layers' name (**1, **2, **3 or **4), add and select an empty layer to write the result to and then run the plugin.

Both fog layers use blend mode 2 so the paint.net project for this example would look like this (name and order of layers):
layer 4 blend result
layer 3 fog2 **2
layer 2 fog1 **2
layer 1 main

This concludes my short introductory guide. Mapping areas can get really complicated (I hated Mekiv Caverns, Madora Beach and Home in LoM), but I hope this guide is enough to get you started. Feel free to post any questions, comments, corrections, etc.

The images and paint.net-projects used in this guide and more can be found here:
https://www.mediafire.com/file/v9zoj0tqnip9aim/PSVrammed_guide_assets_20250513.zip/file

GitHub links:
https://github.com/mechaskrom/PSVrammed
https://github.com/mechaskrom/PaintNet-PS1Blend

[VGCartography]

Thanks very much for sharing this! I've played around with VRAM tools for games before and it always gets tricky, I've stuck to emulator screenshots for the most part and trying to use codes to hide layers etc. I will definitely give this a try and check out your Lua scripts. The idea of trying to find the palette was always the part I dreaded, as it felt imprecise, but this seems like a fairly nice workflow.

Maybe I should write a PSX 3D mapping guide inspired by yours...

[mechaskrom]

Thanks very much for sharing this! I've played around with VRAM tools for games before and it always gets tricky, I've stuck to emulator screenshots for the most part and trying to use codes to hide layers etc. I will definitely give this a try and check out your Lua scripts. The idea of trying to find the palette was always the part I dreaded, as it felt imprecise, but this seems like a fairly nice workflow.

Maybe I should write a PSX 3D mapping guide inspired by yours...

The lua script I made for LoM is not included because it's an embarrassing mess of code. I'm not a lua-programmer and it was made for one game use with no consideration for readability/reusability. Let me know if you really want it despite that.

It's not that interesting either since it's pretty much the same as all my other screenshot lua scripts. What it does basically in pseudo code:
-save origin state
-while cameraY < areaHeight
 -while cameraX < areaWidth
  -load origin state
  -set new camera position and write it to game (using codes)
  -run emulator a few frames so game is updated with the new camera position
  -take screenshot
 -endWhile
-endWhile

The origin state load before every screenshot is to keep animated/moving things in the same state in every screenshot. I think this could fail though if the game inserts lag frames at some, but not all, camera positions. Probably rare that it causes any stitching errors though and should be fairly obvious if it does. It's definitely better to use codes to freeze things, but I wasn't able to find any in LoM.


Finding the right palette can be a challenge sometimes, but unless the game was programmed by a bunch of monkeys they are usually ordered in a logical/structured way. Finding the correct palette will become easy after you've worked on a game for a while and gotten more familiar with how it uses VRAM. At least that's my experience having mapped a few PSX games.

Overall I've found this mapping method to be powerful and easy to use. In some ways it's actually better than the "normal" enable/disable whole BG/OBJ layers in emulators, because you can control every drawn object separately as long as they use textures/palettes in VRAM.


A PSX 3D mapping guide would be interesting so please consider writing one. I'm sure many others would also be interested in such a guide. I always like to hear about other mappers' process for mapping games. Perhaps I'll try mapping a 3D game someday, but as an old 2D gamer, one extra dimension scares me.