miércoles, 28 de diciembre de 2016

Games aside #1: Super Game Boy development (step by step)

Throughout this post we will learn to implement some of the features offered by the Super Game Boy, specifically those used by the recently published Super Game Boy compatible Rocket Man demo. Demo exposed as a local production in the international independent video game contest AzPlay held last November in Bilbao.

Before starting I would like to clarify a number of points:
  1. the program that we will elaborate is programmed in assembler and makes use of RGBDS for the creation of the ROM;
  2. this publication does not cover the bases of the development for Game Boy in assembler, but nor does it require an advanced knowledge on the subject. It can work as an additional lesson to the numerous tutorials that exist on the web in this respect (personal recommendation, https://avivace.ovh/apps/gbdev/salvage/tutorial_de_ensamblador%20%5bLa%20decadence%5d.html);
  3. according to the second point, we will work in the implementation of additional functions related to the Super Game Boy for an existing base program.
This post will cover the use of the following exclusive features of the Super Game Boy:
  • custom frame display;
  • custom game palettes.
Giving as a result the following Game Boy ROM.

Super Game Boy visualization of the ROM

First we should talk about what the Super Game Boy is. According to the Game Boy Programming Manual (page 124),  it is a device that allows you to enjoy Game Boy software on a television screen. This software (contained in the Game Boy cartridge) can be connected to the Super Game Boy, which operates on a Super Nintendo.

As the text emphasizes, Super Game Boy operates on a Super Nintendo. This cartridge is a replica of the Game Boy hardware capable of communicating with the SNES, it helps us inform the home console of the operations we want to perform and send the necessary data to it, but it is ultimately its hardware and not ours (the Super Game Boy one) the responsible for processing and applying the unique features offered by this technology. That is, the graphics of the frame for example, obey the limitations of the SNES and not the Game Boy ones.


That said, we move on to the preparation of the computer where we are going to develop. This is a list of the elements that we should have ready in our PC with Windows:
  1. code editor for program editing (personal recommendation, Visual Studio Code and the Z80 Assembly extension);
  2. RGBDS correctly configured as environment variable;
  3. Game Boy Tile Designer and Game Boy Map Builder for graphics and map editing respectively;
  4. Although the program of this publication is tested in a real Super Game Boy, it is recommended to have the necessary technology to execute the resulting ROM in the final hardware. Failing this, emulators like  BGB or bsnes can serve to test the developments that are made with this device in mind, but do not guarantee a perfect emulation.
Well, it's time to get down to business. As this post is about development for Super Game Boy and not about development for Game Boy we will start from a base project whose ROM offers the following result.

A static title screen

This is the main source file for this template project.

During development it will be important to have some documentation handy. In my opinion, these would be the texts that condense all you need to know when it comes to programming for Super Game Boy:
Each time I give information about the Super Game Boy I will try to complement it with the source of this information, indicating in which part of these two documents it is.

Making the graphics

We will begin by freely designing the Super Game Boy frame that we want to apply. Of course, taking into account the following limitations:
  1. The resolution of the frame must match the resolution of the SNES, ie, 256 pixels wide by 224 pixels high;
  2. we must leave a blank space of 160 by 144 pixels in the central part, which is where the screen of the Game Boy will be displayed;
  3. the SNES has 8 palettes of 16 RGB 15 bit colors (SGB Functions> Available SNES Palettes). The first four (0-3) are used to color the Game Boy's own graphics and the last four (4-7) for the frame. In the section Frame palettes I explain in more detail this limitation;
  4. we can not use more than 256 tiles of 8 by 8 pixels at the time of designing the frame (the tiles of the SNES are 8x8 and we have a byte to map them. The good thing is that these tiles can be flipped horizontally and vertically.

Frame palettes

As we have commented we have at our disposal 4 palettes of 16 colors for the frame. Although not exactly, according to the official documentation we have the 4-6 (Game Boy Programming Manual> page 162), ie 3 palettes. Anyway we can also use the 7. But some emulators will not recognize this last palette correctly.

15 bit RGB color, what does this mean? We have 5 bits to indicate the level of red, 5 for green and 5 for blue. That is, an accuracy of 0-31 to define the intensity of each of the colors. If we have an RGB color of 24 bit (the predominant format) that we want to use on any of our palettes we would have to round up the value from 0 to 255 that we have for color to the equivalent between 0 and 31.

We have said 16 colors, must be qualified: color 0 is shared (SGB Functions> Color 0 Restriction)! This means that if the color 0 of the last palette we assign is red, the color 0 of the other graphics will change to red. And we have 16 colors just in case we want to spend the memory needed to store 4bpp graphics (4 bits per pixel) in the Game Boy. If 2bpp is enough then we have four colors per palette with the color 0 shared, but the graphics will occupy half in memory.

There are many games that accept the limitation of four colors per palette in the frame showing the color 0 to save memory. As for example it happens with the frame of Pokémon Blue.

Comparing the two red squares we see that the frame shows the color 0 shared with the rest of the palettes. Using four colors per tile (2bpp)

Our frame

This is our frame.

256 by 224 pixels frame

These our tiles.

176 tiles (including tile null one) of the 256 available

And these our palettes.

Palettes 4-6 used to represent the colors of each of the tiles

Three palettes of 16 colors (4bpp), the color 0 (first column) is not used so we don't have to share it with the palettes that we are going to use in the graphics of the Game Boy. Because of the characteristics of the development, this is the color distribution that has remained on the three palettes. Only one might as well have been used, since they have many colors in common.

And now, it's time to turn these specifications into data that we can add to our program.

Tiles file

The graphic data of the tiles will be created with Game Boy Tile Designer. In our frame some of the palettes use more than 4 colors so our graphics should be 4bpp.

If the graphics are 2bpp we simply draw the tiles with the editor taking into account that the colors we choose for the values 0, 1, 2, and 3 will correspond to the colors 0, 1, 2 and 3 of the palette that we have specified for that tile.

Left: Game Boy Tile Designer tile; center: palette specified for the tile; Right: tile display in Super Game Boy

The SNES 4bpp graphics can also be created in a simple way using the same program: drawing two consecutive Game Boy tiles for each tile of Super NES. The first for bit planes 1 and 2, and the second one for numbers 3 and 4.

We can combine two Game Boy pixels (2 bits) to create a SNES pixel (4 bits)

Although we use 4bpp graphics we should also have a .gbr file that dedicates a single Game Boy tile per SNES tile. And we will use it when elaborating the map of the frame with Game Boy Map Builder, in this way we will reference the number of the tile as it would do the SNES and not the Game Boy.

The result of the elaboration of these tilesets with Game Boy Tile Designer is the following: the tileset that will store the graphics to use in the frame (FILE DOWNLOAD) and the tileset whose only function will be to contain an index of the tiles to be mapped later (FILE DOWNLOAD). Within the project, we will place these two files in res/tiles/.

And with the following configuration, we export the 4bpp tileset to obtain the necessary data file for the project. We delete the section declaration and automatically generated tags and place the resulting file in dev/data/tiles/ as sgb_tileset.z80 (FILE DOWNLOAD).

We generate a .z80 file compatible with RGBDS

Map file

Now, with Game Boy Map Builder, we will build the frame. We must associate it with the .gbr file of the tileset with the correct indexes, the one that uses a single tile of Game Boy per tile of Super NES. Remembering the fact that the dimensions of the frame are 256 by 224 pixels, which means 32 by 28 tiles. So once we open the program we go to "File> Map properties ..." and we take care of adapting dimensions and tileset.

The tileset we use here only serves as a visual reference when it comes to mapping the tiles

As I mentioned earlier, the SNES tiles can be flipped either horizontally (X Flip) or vertically (Y Flip). Additionally each of the tiles will be associated with one of the palettes we have specified. That's why we need to define additional attributes for each tile we place on our map. We can do this in "File> Location properties ...".

We do not define the vertical flip (Y Flip) because it is not used in our frame

As we will see the flip is defined as a single bit (1 flipped, 0 not flipped) and the palette with 2 (range of 0 to 3 that corresponds respectively with the palettes from 4 to 7), these will be the 2 less significant bits of the 3 that are later assigned to the palette. The third bit, the most significant bit, will always return the value of 1. This gives us a real range of values from 4 to 7 when exporting.

Now we map the tiles of the frame, and define their location properties through the fields available in the bottom row of the editor.

We recall that we must leave a space of null tiles in the position of the Game Boy screen

As a result, we have a .gbm file with the map design that will conform the frame (FILE DOWNLOAD), we place it in res/maps/. As a point, I would like to clarify that the first thing to do when opening the map in Game Boy Map Builder is to reference the tileset of the indexes through "File> Map properties ...".

Now we are going to generate the data file relative to the map through "File> Export to ...". Let's make sure that we comply with the map format specification (SGB Functions> SGB Command 14h - PCT_TRN). In the export options we will include the location properties we defined above. This would be the official specification regarding our export configuration.

Official frame tiles format specification

In the case of the Y Flip property, we ignore it occupying its place with a 0

Once exported, we delete the section declaration and the resulting data tags and place it in dev/data/maps/ (FILE DOWNLOAD). 

We already have all the graphic files ready, only the data from the palettes is missing. To do this we will now create the file sgb.z80, which we will place it dev/data/. Here we are going to write the definitions of the packets that we will send to the SNES and in this case also the macro of the RGB of 15 bits that will be used for the colors of our palettes.

The three parameters of the macro correspond respectively to the value of red, green and blue that we want to give to each color. Well, now we have to specify palettes based on this macro.

We must place the palettes next to the map data (SGB Functions> SGB Command 14h - PCT_TRN), so we will create a file in dev/data/maps called sgborder.z80 (FILE DOWNLOAD), there we will adapt our palettes to the specification.
The map must be 32x32 tiles but the last 4 rows are not part of the screen and are unnecessary

We remember the specification of our palettes

The first color of each palette (color 0) is specified but not used

Game palettes

Finally we are going to add to sgb.z80 the declaration of the palette that we will use for the graphics of the game itself. Recall that while the 4-7 palettes are used for the frame, the 0-3 palettes are used for the graphics of the game. The Game Boy's monochrome graphics have a 4 color limitation so we can only use 4 colors in this palette.

We will only use one of the four palettes assignable to the Game Boy game

The color 0 that we define should be the one we want to share with the rest of the palettes

As we have already specified all the necessary graphic files, it is time to add them to the memory bank that we have declared in main.asm.


Logic programming

Auxiliary definitions

There are two ways of sending information to the Super NES (Game Boy Programming Manual> page 127), through registers P14 and P15 and through the Game Boy's own VRAM (VRAM transfer). Both involve the use of commands. So let's start by defining in the sgb.z80 file the macros of the commands we are going to use (we have a definition of what each command does in Game Boy Programming Manual> page 132 and SGB Functions> SGB Command Summary):
  1. MLT_REQ, makes a multiplayer request, it will be used to detect if the software is running on a Super Game Boy;
  2. CHR_TRN, we will use it to copy the tiles from the frame to the SNES RAM (with a VRAM transfer)
  3. PCT_TRN, we will use it to copy the frame map to the SNES RAM (with a VRAM transfer);
  4. PAL_SET, will assign the palette that we have defined for the graphics of the game;
  5. PAL_TRN, will copy the palette that we have defined for the game graphics to the SNES RAM (with a VRAM transfer);
  6. MASK_EN, will freeze the screen during communication processes with the Super Game Boy, and unfreeze it upon completion;
  7. Finally we will define eight data packets that we will send to initialize the communication as recommended in the official documentation (Game Boy Programming Manual> page 178).

And with this we finally complete the auxiliary file sgb.z80 (FILE DOWNLOAD).

As a prerequisite to logic programming, we must write a 0x03 in the 0x0146 address of our ROM to indicate that we support the functionality of Super Game Boy (Game Boy Programming Manual> page 178). We already have parameterized this address in gbhw.inc, so we modified the second parameter of the header in main.asm.

Communication implementation

Let's explain with a practical example how we have defined the macros of the packets in sgb.z80. Let's take our macro from MLT_REQ and compare it to the memory specification of the command (SGB Functions> SGB Command 11h - MLT_REQ).

As we see the Super Game Boy allows a multiplayer mode of up to 4 players with the SNES Super 5 multi-player adapter

We see how byte 1 defines the number of players requested in the Super Game Boy multiplayer mode. We parameterized this byte in our macro and specified with two labels the two variants that we will use in our program.

All commands are made up of 16 bytes (128 bits), which is the size of the data packet that we can send. So we only send one packet per command. The number of packets per transfer can be specified through the three least significant bits of byte 0 of the first packet (as we see in the specification, byte 0: Command * 8, which happens to occupy the 5 most significant bits + Length, which occupies the remaining 3 bits), so we can send from 1 to 7 packets per transfer. We will represent the possibility of sending more than one packet per command in the code, but in the resulting program we do not use this functionality.

Now we will describe the process of sending each packet as explained on page 128 of the Game Boy Programming Manual. Sending made through bits 4 and 5 of the Game Boy's P1 register (0xFF00), these bits correspond respectively to the output ports P14 and P15:
  1. we start the communication by putting to 0 P14 and P15;
  2. we send the 128 bits of the packet by putting to 0 P14 and to 1 P15 if we want to send a 0 and to 1 P14 and 0 P15 if we want to send a 1;
  3. we send a 0 in bit 129 to close the communication (P14 to 0 and P15 to 1).
The following list of rules must be taken into account:
  1. the values we write in P14 and P15 must be kept for 5μs, and between writtings we must set P14 and P15 to 1 for at least 15μs. Considering that a Game Boy clock cycle already lasts more than 23μs, we ignore the times, but note that we must write a 1 on both ports for each bit sent;
  2. between sending one packet and the next we should wait for a minimum of 60 msec (about 4 frames of Game Boy). The "sgbpackettransfer_wait" routine will take care of this wait.
With all of this in mind, this is our routine of sending packets, which we add to main.asm.

The first functionality that will use this packet sending routine is the one that recognizes whether or not we are in a Super Game Boy. We will do it the following way (which is the recommended way in SGB Functions> Detecting SGB hardware):
  1. we will read the identifier of the register P1, which in addition to serving to send information through the ports is the register that returns the information of the joypad of the Game Boy. By default, its reading returns the identifier of the joypad;
  2. we request the two player mode of Super Game Boy by sending the command packet MLT_REQ with two players as the parameter;
  3. we re-read the identifier of the register P1. If it is the same identifier, it means that the two player mode has not been selected and that therefore we are not in a SGB.
We place the following code in main.asm.

The following routine will be called "init_sgb_default", and does the sending of the initialization packets recommended by the Game Boy Programming Manual (page 178). We also add it to main.asm.

The transfer commands CHR_TRN, PCT_TRN, and PAL_TRN use the VRAM transfer to copy their data to the SNES RAM. Here are the steps we must follow to perform this type of transfer (as explained in SGB Functions> SGB VRAM Transfers):
  1. if we do not want the data to be displayed on the screen of the Game Boy we must have previously configured a mask for the LCD of the Game Boy by  making use of the command MASK_EN;
  2. we disable interrupts and turn off the LCD, to avoid that the graphics we want to send are corrupted;
  3. we assign the default values to the background palette of the Game Boy, which translates to writing 0xE4 in the palette register that is at 0xFF47 (0 white, 1 light gray, 2 dark gray, 3 black);
  4. we copy the 4KB of data that we want to send to the visible background of the Game Boy LCD, the background address begins at 0x9800;
  5. we send the transfer command, either CHR_TRN, PCT_TRN or PAL_TRN. The data displayed in the visible background of the Game Boy will be sent to the SNES.
Before showing the code of the routine, a little more information about on MASK_EN. It is usually used at the beginning of the program to hide the actual display of the Game Boy LCD during data transfer.

(SGB Functions > SGB Command 17h - MASK_EN)

There are 4 possible values for command byte 1, we use the value 1 to freeze the screen image and 0 to unfreeze it when the process is finished. As we see in the tags we have defined in sgb.z80.

And once the digression is finished, this is the data transfer routine. We will place it in main.asm.

As we can see, we have an additional routine called "parsesgbbordertiles". This routine allows us to save memory in case the data we want to copy is 2bpp, since it will fill with zeroes the bit planes 3 and 4 (which we do not use). In our case, being 4bpp tiles, we do not make use of it.

And finally, using the routines we have developed so far, this would be the description of the main initialization routine of the Super Game Boy:
  1. we check if we are in a Super Game Boy, if we are not, we return and the routine ends;
  2. we freeze the LCD display of the Game Boy throughout the process;
  3. we send the initialization packets recommended by the documentation;
  4. we copy the 256 tiles we will use in the frame to the SNES RAM. In two batches of 128;
  5. we copy the frame information to the SNES RAM;
  6. we copy the information of the game palettes to the SNES RAM;
  7. we assign the palette previously copied as a palette to be used in the game;
  8. we clear the Game Boy VRAM and unfreeze the Game Boy LCD display to complete the process.
We add this code to main.asm (FILE DOWNLOAD).

If we now execute the assemble.bat file of the project we will have the ROM with the frame and the customized palettes as a result.

I terminate the explanation of this simple prototype. Naturally, many features of the Super Game Boy remain to be applied. But I hope this article serves as a starting point for people who have been encouraged to develop for the Game Boy but have not found any minimally guided development resources for Super Game Boy.

Any note or critic of any kind will be welcome, and any part of the post is subject to change if necessary.

So I can only give encouragement. Now you have to implement that Super Game Boy frame that you have always wanted to design.

Games aside #1: Desarrollo para Super Game Boy (paso a paso)

A lo largo de esta entrada vamos a aprender a implementar alguna de las funcionalidades que ofrece el Super Game Boy, concretamente las que aprovecha la recientemente publicada ROM mejorada para Super Game Boy de la demo de Rocket Man. Demo expuesta como producción local en el certamen internacional de videojuegos independientes AzPlay celebrado el pasado noviembre en Bilbao.

Antes de comenzar me gustaría aclarar una serie de puntos:
  1. el programa que se va a elaborar está programado en ensamblador y hace uso de RGBDS para la creación de la ROM;
  2. esta publicación no cubre las bases del desarrollo para Game Boy en ensamblador, pero tampoco requiere un conocimiento avanzado sobre el tema. Puede funcionar como lección adicional a los numerosos tutoriales que existen en la red al respecto (recomendación personal en castellano, http://wiki.ladecadence.net/doku.php?id=tutorial_de_ensamblador);
  3. de acuerdo al segundo punto, se parte de un programa base en el que se trabaja la implementación de funciones adicionales relacionadas con el Super Game Boy.
En esta entrada se va a cubrir el uso de las siguientes características exclusivas del Super Game Boy:
  • despliegue de un marco personalizado;
  • paletas personalizadas para los gráficos del juego.
Dando como resultado del aprendizaje la siguiente ROM de Game Boy.

Visualización de la ROM en una Super Game Boy

Primero deberíamos hablar sobre qué es el Super Game Boy. Se trata, según el Game Boy Programming Manual (pág 124), de un dispositivo que permite disfrutar del software de Game Boy en una pantalla de televisión. Este software (contenido en el cartucho de Game Boy) puede conectarse al Super Game Boy, el cual opera en una Super Nintendo.

Sobre esta definición cabe resaltar la última parte, el Super Game Boy opera en una Super Nintendo. Este cartucho es una réplica del hardware de la Game Boy capaz de comunicarse con la SNES, nos ayuda a informar a la sobremesa de las operaciones que queremos realizar y a enviarle los datos necesarios, pero es en última instancia su hardware y no el nuestro (el del Super Game Boy) el que se encarga de procesar y aplicar la funcionalidades exclusivas que nos ofrece esta tecnología. Es decir, los gráficos del marco por ejemplo, obedecen las limitaciones de la SNES y no de la Game Boy.


Dicho esto, pasamos a la preparación del equipo donde vayamos a desarrollar. Esta sería una lista de elementos que deberíamos tener listos en nuestro PC con Windows:
  1. editor de texto/código para la edición del programa (recomendación personal, Visual Studio Code y la extensión Z80 Assembly);
  2. RGBDS correctamente configurado como variable de entorno;
  3. Game Boy Tile Designer y Game Boy Map Builder para la edición de gráficos y mapas respectivamente;
  4. a pesar de que el programa de esta publicación está testeado en un Super Game Boy real, se recomienda disponer de la tecnología necesaria para ejecutar la ROM resultante en el hardware final. En su defecto, emuladores como BGB o bsnes pueden servir para probar los desarrollos que se hagan con este dispositivo en mente, pero no garantizan una emulación perfecta.
Pues bien, toca ponerse manos a la obra. Como esta publicación trata sobre el desarrollo para Super Game Boy y no sobre el desarrollo para Game Boy vamos a partir de un proyecto base cuya ROM ofrece el siguiente resultado.

Una pantalla de título estática

Este es el código del fichero principal de este proyecto plantilla.

Durante el desarrollo va a ser importante tener cerca cierta documentación a mano. En mi opinión, estos serían los textos que condensan todo lo que se necesita saber cuando se trata de programar para Super Game Boy:
Cada vez que dé información sobre el Super Game Boy procuraré complementarla con la fuente de dicha información, indicando en qué parte de estos dos documentos se encuentra.

Elaboración de gráficos

Empezaremos diseñando libremente el marco de Super Game Boy que queremos aplicar. Eso sí, teniendo en cuenta las siguientes limitaciones:
  1. la resolución del marco debe cuadrar con la resolución de la SNES, es decir, 256 píxeles de ancho por 224 píxeles de alto;
  2. debemos dejar un espacio en blanco de 160 por 144 píxeles en la parte central, que es donde se mostrará la pantalla de la Game Boy;
  3. la SNES dispone de 8 paletas de 16 colores RGB de 15 bit (SGB Functions > Available SNES Palettes). Las cuatro primeras (0-3) se usan para colorear los propios gráficos de la Game Boy y las cuatro últimas (4-7) para el marco. En el apartado Paletas del marco explico con más detalle esta limitación;
  4. no podemos usar más de 256 tiles de 8 por 8 píxeles a la hora de conformar el marco (los tiles de la SNES son de 8x8 y disponemos de un byte para direccionarlos. Lo bueno es que estos tiles pueden voltearse horizontal y verticalmente.

Paletas del marco

Como hemos comentado tenemos ha nuestra disposición 4 paletas de 16 colores para el marco. Aunque no exactamente, según la documentación oficial tenemos de la 4-6 (Game Boy Programming Manual > pág 162), es decir, 3 paletas. De todas formas también podemos hacer uso de la 7. Eso sí, algunos emuladores no reconocerán esta última paleta correctamente.

Color RGB de 15 bit, ¿qué implica esto? Pues que tenemos 5 bits para indicar el nivel de rojo, 5 para el verde y 5 para el azul. Es decir, una precisión de 0-31 para definir la intensidad de cada uno de los colores. Si tenemos un color RGB de 24 bit (el formato predominante) que queremos usar en alguna de las paletas tendriamos que redondear el valor de 0 a 255 que tenemos por color al equivalente entre 0 y 31.

Hemos dicho 16 colores, hay que matizarlo: ¡el color 0 es compartido (SGB Functions > Color 0 Restriction)! Esto significa que si el color 0 de la última paleta que asignemos es rojo, el color 0 del resto de gráficos pasará a ser el rojo. Y tenemos 16 colores sólo en el caso de que queramos gastar la memoria necesaria para almacenar gráficos 4bpp (4 bits por pixel) en la Game Boy. Si con 2bpp nos basta tenemos entonces cuatro colores por paleta con el color 0 compartido, pero los gráficos nos ocuparán la mitad de memoria.

Hay muchos juegos que aceptan la limitación de cuatro colores por paleta en el marco mostrando el color 0 para ahorrar memoria. Como por ejemplo ocurre con el marco del Pokémon Azul.

Comparando los dos cuadrados rojos vemos que el marco muestra el color 0 compartido con el resto de paletas. Usando además cuatro colores por tile (2bpp)

Nuestro marco

Este es nuestro marco.

Marco de 256 por 224 píxeles

Estos nuestros tiles.

176 tiles (incluyendo el tile nulo) de los 256 disponibles

Y estas nuestras paletas.

Paletas 4-6 usadas para representar los colores de cada uno de los tiles 

Tres paletas de 16 colores (4bpp), el color 0 (primera columna) no lo usamos para no tener que compartirlo con las paletas que se van a usar en los gráficos de Game Boy. Por las características del desarrollo, esta es la distribución de colores que ha quedado en las tres paletas. Bien podría haberse usado una sola, ya que guardan entre ellas bastantes colores en común.

Y ahora, es momento de convertir estas especificaciones en datos que añadir a nuestro programa.

Archivo de tiles

Los datos gráficos de los tiles los crearemos con Game Boy Tile Designer. En nuestro marco alguna de las paletas usa más de 4 colores así que nuestros gráficos deberán ser 4bpp.

En el caso de que los gráficos sean 2bpp sencillamente dibujamos los tiles con el editor teniendo en cuenta que los colores que eligamos para el valor 0, 1, 2, y 3 se corresponderán con los colores 0, 1, 2 y 3 de la paleta que tengamos pensada para ese tile.

Izquierda: tile en Game Boy Tile Designer; centro: paleta especificada para el tile; derecha: visualización del tile en el Super Game Boy

Los gráficos 4bpp de la SNES también podemos crearlos de manera sencilla usando el mismo programa: dibujando dos tiles consecutivos de Game Boy por cada tile de Super. El primero para los bit planes 1 y 2, y el segundo para los número 3 y 4.

Podemos combinar dos píxeles de Game Boy (2 bits) para crear un pixel de SNES (4 bits)

Aunque usemos gráficos 4bpp también debemos tener un archivo .gbr que dedique un sólo tile de Game Boy por tile de SNES. Y lo usaremos al elaborar el mapa del marco con Game Boy Map Builder, de esta forma referenciaremos el número de tile como lo haría la SNES y no la Game Boy.

El resultado de la elaboración de estos tileset en Game Boy Tile Designer es el siguiente: el tileset que almacenará los gráficos a usar en el marco (DESCARGAR EL ARCHIVO) y el tileset cuya única función será contener un índice de los tiles para mapearlos posteriormente (DESCARGAR EL ARCHIVO). Dentro del proyecto, ubicaremos estos dos archivos en res/tiles/.

Y con la siguiente configuración, exportamos el tileset de 4bpp para obtener el archivo de datos necesario para el proyecto. Borramos la declaración de sección y las etiquetas generadas automáticamente y ubicamos el archivo resultante en dev/data/tiles/ como sgb_tileset.z80 (DESCARGAR EL ARCHIVO).

Generamos un archivo .z80 compatible con RGBDS

Archivo de mapa

Ahora, con Game Boy Map Builder, construiremos el marco. Debemos asociarlo al archivo .gbr del tileset con los índices correctos, el que utiliza un sólo tile de Game Boy por tile de Super. Recordemos además que las dimensiones del marco son 256 por 224 píxeles, lo que significa 32  por 28 tiles. Así que una vez abramos el programa nos dirigimos a "File > Map properties..." y nos encargamos de cuadrar dimensiones y tileset.

 El tileset que aquí usemos sólo sirve como referencia visual a la hora de mapear los tiles

Como comentaba anteriormente, los tiles de la SNES se pueden voltear tanto horizontal (X Flip) como verticalmente (Y Flip). Adicionalmente cada uno de los tiles va a estar asociado a una de las paletas que hayamos especificado. Por eso necesitamos definir atributos adicionales para cada tile que coloquemos en nuestro mapa. Podemos hacer esto en "File > Location properties...".

No definimos el volteo vertical (Y Flip) porque no es usado en nuestro marco

Como veremos a continuación el volteo se define con un único bit (1 volteado, 0 no volteado) y la paleta con 2 (rango de 0 a 3 que se correponde respectivamente con las paletas de la 4 a la 7), estos serán los 2 bit más bajos de los 3 que se asignan posteriormente a la paleta. Al tercer bit, el más alto, le daremos siempre el valor de 1. Esto nos da un rango de valores de 4 a 7 real al exportar.

Ahora mapeamos los tiles del marco, y definimos sus location properties a través de los campos disponibles en la fila inferior del editor.

Recordemos que debemos dejar un espacio de tiles nulos en la ubicación de la pantalla de la Game Boy

Como resultado, tenemos un archivo .gbm con el diseño del mapa que conformará el marco (DESCARGAR EL ARCHIVO), lo situamos en res/maps/. Como apunte, aclarar que lo primero que debemos hacer al abrir el mapa en Game Boy Map Builder es referenciar el tileset de los índices a través de "File > Map properties...".

Ahora vamos a generar el archivo de datos relativo al mapa a través de "File > Export to...". Vamos a asegurarnos de que cumplimos con la especificación sobre el formato del mapa (SGB Functions > SGB Command 14h - PCT_TRN). En las opciones de la exportación incluiremos las location properties que hemos definido anteriormente. Esta sería la especificación oficial respecto a nuestra configuración de exportación.

Especificación oficial del formato de los tiles del mapa del marco

En el caso de la propiedad Y Flip, la ignoramos ocupando su lugar con un 0

Una vez exportado, borramos la declaración de sección y las etiquetas del archivo resultante y lo ubicamos en dev/data/maps/ (DESCARGAR EL ARCHIVO). 

Ya tenemos todos los archivos gráficos listos, sólo faltan los datos de las paletas. Para ello vamos a crear ahora el archivo sgb.z80, que ubicaremos en dev/data/. Aquí vamos a ubicar las definiciones de los paquetes que enviaremos a la SNES y en este caso también la macro del RGB de 15 bits del que se servirán los colores de nuestras paletas.

Los tres parámetros de la macro se corresponden respectivamente con el valor de rojo, de verde y de azul que queramos darle a cada color. Pues bien, ahora toca especificar las paletas en base a esta macro.

Debemos colocar las paletas a continuación de los datos del mapa (SGB Functions > SGB Command 14h - PCT_TRN), así que crearemos un archivo en dev/data/maps que se llame sgborder.z80 (DESCARGAR EL ARCHIVO), allí cuadraremos nuestras paletas con la especificación.
El mapa debe ser de 32x32 tiles pero las últimas 4 filas no entran en la pantalla y son innecesarias

Recordamos la especificación de nuestras paletas

El primer color de cada paleta (color 0) está especificado pero no llega a usarse

Paletas del juego

Por último vamos a añadir a sgb.z80 la declaración de la paleta que usaremos para los gráficos del propio juego. Recordemos que mientras las paletas de la 4-7 se usan para el marco, las de la 0-3 se usan para los gráficos del juego. Los gráficos monocromos de la Game Boy tienen una limitación de 4 colores así que sólo podremos usar 4 colores en esta paleta.

Sólo usaremos una de las cuatro paletas asignables al juego de Game Boy

El color 0 que definamos debería ser el que queramos compartir con el resto de paletas

Pues ya tenemos especificados todos los archivos gráficos necesarios, llegó el momento de añadirlos al banco de memoria que tenemos declarado en main.asm.


Programación de la lógica

Definiciones auxiliares

Existen dos formas de enviar información a la Super (Game Boy Programming Manual > pág 127), a través de los registros P14 y P15 y a través la propia VRAM de la Game Boy (transferencia de VRAM). Ambas implican el uso de comandos. Así que empezaremos definiendo en nuestro archivo sgb.z80 las macros de los comandos que vamos a utilizar (tenemos una definición de lo que hace cada comando en Game Boy Programming Manual > pág 132 y SGB Functions > SGB Command Summary):
  1. MLT_REQ, hace una petición del modo multijugador, se usará para detectar si el cartucho se está ejecutando en un Super Game Boy;
  2. CHR_TRN, lo usaremos para copiar los tiles del marco a la RAM de la SNES (con una transferencia de VRAM);
  3. PCT_TRN, lo usaremos para copiar el mapa del marco a la RAM de la SNES (con una transferencia de VRAM);
  4. PAL_SET, asignará la paleta que tenemos definida para los gráficos del juego;
  5. PAL_TRN, copiará la paleta que tenemos definida para los gráficos del juego a la RAM de la SNES (con una transferencia de VRAM);
  6. MASK_EN, congelará la pantalla durante los procesos de comunicación con el Super Game Boy, y la descongelará al terminar;
  7. Por último definiremos ocho paquetes de datos que enviaremos para inicializar la comunicación tal y como se recomienda en la documentación oficial (Game Boy Programming Manual > pág 178).

Y con esto completamos definitivamente el archivo auxiliar sgb.z80 (DESCARGAR EL ARCHIVO).

Como requisito previo a la programación de la lógica debemos escribir en la dirección 0x0146 de nuestra ROM un 0x03, para indicar que soportamos la funcionalidad de Super Game Boy (Game Boy Programming Manual > pág 178). Ya tenemos parametrizada esta dirección en gbhw.inc, así que modificamos el segundo parámetro de la cabecera en main.asm.

Implementación de la comunicación

Vamos a explicar con un ejemplo práctico cómo hemos definido las macros de los paquetes en sgb.z80. Cojamos nuestra macro de de MLT_REQ y comparémosla con la especificación de memoria del comando (SGB Functions > SGB Command 11h - MLT_REQ).

Como vemos el Super Game Boy permite un modo multijugador de hasta 4 jugadores con el Super 5 multi-player adapter de SNES

Vemos como el byte 1 define el número de jugadores solicitados en el modo multijugador del Super Game Boy. Nosotros parametrizamos dicho byte en nuestra macro y especificamos con dos etiquetas las dos variantes que vamos a usar en nuestro programa.

Todos los comandos están conformados por 16 bytes (128 bits), que es el tamaño del paquete de datos que podemos enviar. Por lo que sólo enviamos un paquete por comando. El número de paquetes por transferencia en cualquier caso puede especificarse a través de los últimos tres bits del byte 0 del primer paquete (como vemos en la especificación, byte 0: Command*8, que pasa a ocupar los 5 bits de mayor prioridad, + Length, que ocupa los 3 bits restantes), por lo que podemos enviar de 1 a 7 paquetes por transferencia. Nosotros representaremos la posibilidad de enviar más de un paquete por comando en el código del programa, aunque no se llegue a hacer uso de dicha funcionalidad.

Ahora describiremos el proceso de envío de cada paquete tal y como se explica en la pág 128 del Game Boy Programming Manual. Envío que realizaremos a través de los bits 4 y 5 del registro P1 (0xFF00) de la Game Boy, estos bit se corresponden respectivamente con los puertos de salida P14 y P15:
  1. empezamos la comunicación poniendo a 0 P14 y P15;
  2. enviamos los 128 bits del paquete poniendo a 0 a P14 y a 1 a P15 si quieremos enviar un 0 y a 1 a P14 y a 0 a P15 si queremos enviar un 1;
  3. enviamos un 0 en el bit 129 para cerrar la comunicación (P14 a 0 y P15 a 1).
Hay que tener en cuenta la siguiente lista de reglas:
  1. los valores que escribimos en P14 y P15 deben mantenerse por 5µs, y entre escrituras debemos poner P14 y P15 a 1 durante al menos 15µs. Teniendo en cuenta que un ciclo de reloj de Game Boy ya dura más de 23µs, ignoramos los tiempos, pero anotamos que debemos escribir un 1 en ambos puertos por cada bit enviado;
  2. entre el envío de un paquete y el siguiente debemos esperar un mínimo de 60 msec (unos 4 frames de Game Boy). La rutina "sgbpackettransfer_wait" se encargará de cumplir con esta espera.
Con todo esto presente, esta es nuestra rutina de envío de paquetes, que añadimos a main.asm.

La primera funcionalidad que va a servirse de esta rutina de envío es la de reconocer si nos encontramos o no en un Super Game Boy. Lo haremos de la siguiente manera (que viene a ser la forma recomendada en SGB Functions > Detecting SGB hardware):
  1. leeremos el identificador del registro P1, que además de servir para enviar información a través de los puertos es el registro que nos devuelve la información de los controles de la Game Boy. Por defecto, su lectura nos devuelve el identificador de los controles;
  2. seleccionamos el modo modo dos jugadores de Super Game Boy enviando el paquete de MLT_REQ con dos jugadores como parámetro;
  3. volvemos a leer el identificador del registro P1. Si es el mismo, significa que no se ha seleccionado el modo de dos jugadores y que por lo tanto no estamos en un SGB.
Ubicamos pues el siguiente código en main.asm.

La siguiente rutina se llamará "init_sgb_default", y no hace otra cosa que enviar los paquetes de inicialización recomendados por la doumentación (Game Boy Programming Manual > pág 178). La añadimos también a main.asm.

Los comandos de transferencia CHR_TRN, PCT_TRN, y PAL_TRN usan la transferencia de VRAM para copiar sus datos a la RAM de la SNES. Estos son los pasos que debemos seguir para realizar este tipo de transferencia (tal y como se explica en SGB Functions > SGB VRAM Transfers):
  1. si no queremos que los datos a enviar se visualicen en la pantalla de la Game Boy debemos haber configurado previamente una máscara para el LCD de la Game Boy haciendo uso del comando MASK_EN;
  2. deshabilitamos interrupciones y apagamos el LCD, para evitar que los gráficos que queremos enviar se corrompan;
  3. asignamos los valores por defecto a la paleta de los gráficos del fondo de la Game Boy, que se traduce a escribir el valor 0xE4 en el registro de la paleta que se encuentra en 0xFF47 (0 blanco, 1 gris claro, 2 gris oscuro, 3 negro);
  4. copiamos los 4KB de datos que queremos enviar al fondo visible del LCD de la Game Boy, la dirección a la que se deben copiar comienza en 0x9800;
  5. enviamos el comando de transferencia, ya sea CHR_TRN, PCT_TRN o PAL_TRN. Los datos desplegados en el fondo visible de la Game Boy se enviarán a la SNES.
Antes de mostrar el código de la rutina, un pequeño paréntesis sobre MASK_EN. Habitualmente se usa al comienzo del programa para ocultar la visualización real del LCD de la Game Boy durante la transferencia de datos.

(SGB Functions > SGB Command 17h - MASK_EN)

Existen 4 posibles valores para el byte 1 del comando, nosotros usamos el valor 1 para congelar la imagen de la pantalla y el 0 para descongelarla cuando termina el proceso. Como vemos en las etiquetas que tenemos definidas en sgb.z80.

Y cerrado el paréntesis, está es la rutina de transferencia de datos. La ubicaremos en main.asm.

Como se puede ver, tenemos una rutina adicional que se llama "parsesgbbordertiles". Esta rutina nos permite ahorrar memoria en el caso de que los datos que queramos copiar sean tiles 2bpp, ya que se dedica a rellenar con ceros los bit planes 3 y 4 (que no usamos). En nuestro caso, al tratarse de tiles 4bpp, no hacemos uso de ella.

Y por último, sirviéndonos de las rutinas que hemos elaborado hasta el momento, esta sería la descripción de la rutina principal de inicialización del Super Game Boy:
  1. comprobamos si nos encontramos en un Super Game Boy, si no lo estamos, volvemos y la rutina termina;
  2. congelamos la visualización del LCD de la Game Boy durante todo el proceso;
  3. enviamos los paquetes de inicialización recomendados por la documentación;
  4. copiamos los 256 tiles que usaremos en el marco en la VRAM de la SNES. En dos tandas de 128;
  5. copiamos la información del marco en la VRAM de la SNES;
  6. copiamos la información de las paletas a usar en el propio juego en la RAM de la SNES;
  7. asignamos la paleta previamente copiada como paleta a usar en el juego;
  8. despejamos la VRAM de la Game Boy y descongelamos la visualización del LCD de la Game Boy para finalizar el proceso.
Añadimos este código al fichero principal del programa main.asm (DESCARGAR EL ARCHIVO).

Si ahora ejecutamos el archivo assemble.bat del proyecto tendremos como resultado la ROM con el marco y las paletas personalizadas.

Doy por terminada la explicación de este sencillo prototipo. Naturalmente, quedan por aplicar muchas funcionalidades del Super Game Boy. Pero espero que este artículo sirva como punto de partida a la gente que se ha animado a desarrollar para Game Boy pero que no ha encontrado ningún recurso mínimamente guiado sobre el desarrollo para Super Game Boy.

Todo apunte o crítica de cualquier tipo será bienvenida, y cualquier parte de la entrada es susceptible de ser modificada en caso de ser necesario.

Así que sólo me queda daros ánimos. Ahora os toca implementar ese marco de Super Game Boy que siempre habéis querido diseñar.