|
1 | | -# gb-boilerplate |
| 1 | +# bgbtest.gb |
2 | 2 |
|
3 | | -A minimal, customizable, ready-to-compile boilerplate for Game Boy RGBDS projects. |
| 3 | +## What is it? |
4 | 4 |
|
5 | | -## Downloading |
| 5 | +  |
6 | 6 |
|
7 | | -You can simply clone the repository using Git, or if you just want to download this, click the `Clone or download` button up and to the right of this. This repo is also usable as a GitHub template for creating new repositories. |
| 7 | +This is the source code for the bgbtest.gb ROM that is shipped with beware's Gameboy emulator, [BGB](https://bgb.bircd.org/). It was made on request by beware and was designed to be a first ROM that a new user of BGB can open to confirm that the emulator is working correctly. It was created a few years ago now, but from memory, these are the design requirements given to me by beware: |
8 | 8 |
|
9 | | -## Setting up |
| 9 | +* **Should test graphics.** Needs to show some form of animation without requiring user input, to confirm that graphical output is working. |
| 10 | +* **Should test audio.** Needs to play some form of sound without requiring user input, to confirm that audio output is working. |
| 11 | +* **Should be able to test buttons.** Needs to detect when buttons are pressed and indicate which button is pressed, to confirm that input is working and configured as per the user's preference. Should also indicate on the screen that this a function. |
| 12 | +* **Should be 32 kiB.** Needs to use minimal disk space when stored and network traffic when being downloaded. (beware remains seemingly one of the few people who actually cares about these things in this day and age.) |
| 13 | +* **Should not be a "room heater".** Needs to use the CPU's `halt` mode when idle to preserve CPU time (if used in an emulator) or battery life (if used on real hardware). |
| 14 | +* **Should be branded BGB.** Needs to show the BGB name and application icon, as this is BGB's official test ROM. |
10 | 15 |
|
11 | | -Make sure you have [RGBDS](https://github.com/rednex/rgbds), at least version 0.4.0, and GNU Make installed. Python 3 is required for the PB16 compressor bundled as a usage example, but that script is optional. |
| 16 | +The original version of the code compiled by using a Windows batch file and the original Windows 95 compatible RGBDS binaries. |
12 | 17 |
|
13 | | -## Customizing |
| 18 | +This version of the code is... |
| 19 | +* slightly cleaned up and much more well commented. |
| 20 | +* changed to compile on modern RGBDS versions. Tested on 0.4.1 but should work a few versions back as well. This is mostly about replacing deprecated keywords like `HOME` and `BSS` with modern ones like `ROM0` and `WRAM0`. |
| 21 | +* adapted to use ISSOtm's [gb-boilerplate](https://github.com/ISSOtm/gb-boilerplate) for easier compilation. |
| 22 | +* adapted to use the IO register definitions from the modern [hardware.inc](https://github.com/gbdev/hardware.inc) file. |
14 | 23 |
|
15 | | -Edit `project.mk` to customize most things specific to the project (like the game name, file name and extension, etc.). Everything has accompanying doc comments. |
| 24 | +For now, it should however compile to the exact same file as is shipped with BGB. If I decide to fix bugs/add features in future, code compiling to the original version will be kept as a branch for posterity. The original version has the following hashes: |
16 | 25 |
|
17 | | -Everything in the `src` folder is the source, and can be freely modified however you want. The basic structure in place should hint you at how things are organized. If you want to create a new "module", you simply need to drop a `.asm` file in the `src` directory, name does not matter. All `.asm` files in that root directory will be individually compiled by RGBASM. |
| 26 | +* md5: d4dd708dd0de6ba003006004d53d21ac |
| 27 | +* sha1: 1ea7c76a76427d1c1a85427f3eacc16d142ffc56 |
18 | 28 |
|
19 | | -The file at `src/res/build_date.asm` is compiled individually to include a build date in your ROM. Always comes in handy. |
| 29 | +## Functionality |
20 | 30 |
|
21 | | -If you want to add resources, I recommend using the `src/res` folder. Add rules in the Makefile; an example is provided for compressing files using PB16 (a variation of [PackBits](https://wiki.nesdev.com/w/index.php/Tile_compression#PackBits)). |
| 31 | +When you run the ROM, it shows the BGB application icon and name, and a parallax starfield effect flying by vertically in the background. |
22 | 32 |
|
23 | | -## Compiling |
| 33 | +It's playing a (pseudo)random melody on the wave channel using a sawtooth wave. This melody can be turned off or on by holding select and pressing start. |
24 | 34 |
|
25 | | -Simply open you favorite command prompt / terminal, place yourself in this directory (the one the Makefile is located in), and run the command `make`. This should create a bunch of things, including the output in the `bin` folder. |
| 35 | +If you press any button, the button in question is indicated on the screen, and a tone unique to that button is played on one of the pulse channels. |
26 | 36 |
|
27 | | -If you get errors that you don't understand, try running `make clean`. If that gives the same error, try deleting the `deps` folder. If that still doesn't work, try deleting the `bin` and `obj` folders as well. If that still doesn't work, you probably did something wrong yourself. |
| 37 | +If you play all the notes in ascending order, an easter egg is unlocked: a sine wave effect that is applied to the BGB logo. |
28 | 38 |
|
29 | | -## See also |
| 39 | +It's shipped with BGB as a first ROM to try in the emulator. However, if you are a Gameboy modder or second hand buyer, it might be useful to put this ROM on a flash cartridge to test the buttons, sound output and graphics on a modded 'boy or a 'boy of unknown condition. It can also be a useful test in the very early stages of developing a GB emulator, as it's both not a completely trivial program, and not doing anything too crazy. |
30 | 40 |
|
31 | | -If you want something less barebones, already including some "base" code, check out [gb-starter-kit](https://github.com/ISSOtm/gb-starter-kit). |
| 41 | +## Trivia |
32 | 42 |
|
33 | | -[Here](https://gist.github.com/ISSOtm/a9057e7c66080f36afcd82ed2863fd62) are the naming conventions used in this code; maybe you'll find them useful. |
| 43 | +Sound trivia 1: All sound that's played (both the pseudorandom melody and the button sounds) is in the C mixolydian scale. That is to say, on a piano keyboard, it would be using all white keys in one octave, except B which is flattened to B♭. |
34 | 44 |
|
35 | | -I recommend the [BGB](https://bgb.bircd.org) emulator for developing ROMs on Windows and, via Wine, Linux and macOS (64-bit build available for Catalina). [SameBoy](https://github.com/LIJI32/SameBoy) is more accurate, but has a much worse interface except on macOS. |
| 45 | +Sound trivia 2: I didn't want to kill the previously playing note when the user pressed a new button, so I made it alternate between pulse channels 1 and 2. However, that created a new problem. Pressing the same button multiple times would create an ugly phased sound that was different each time due to the phase relation between the channels. The solution to this was to detune every second note which gives a much more pleasant sound. |
36 | 46 |
|
37 | | -### Libraries |
| 47 | +Graphics trivia: At the time I wrote this code, my own graphics conversion scripts were pretty dumb and used to use color 0 as the darkest color and color 3 as the lightest color, corresponding to the brightness order of regular RGB values. This means the palette set in BGP is effectively inverted compared to most GB software. |
38 | 48 |
|
39 | | -- [Variable-width font engine](https://github.com/ISSOtm/gb-vwf) |
40 | | -- [structs in RGBDS](https://github.com/ISSOtm/rgbds-structs) |
| 49 | +Data compression trivia: bgbtest.gb is using a simple decompression routine which can decode RLE as well as sequences. It was originally adapted from data compression used in LSDj which I had already written a decompression routine for in [LittleFM](https://blog.gg8.se/wordpress/gameboy-resources/littlefm-an-alternative-file-manager-for-lsdj/), an alternative file manager for [LSDj](https://www.littlesounddj.com/) which can be patched onto an LSDj ROM. But I expanded to use it more as a general purpose data encoding that's especially useful for tile data which are often either sequential or repeating in nature. In bgbtest.gb, it was used to manually specify data, rather than being generated by other tools. |
| 50 | + |
| 51 | +## Disassembly |
| 52 | + |
| 53 | +[CelestialAmber](https://github.com/CelestialAmber) made a [disassembly of bgbtest.gb](https://github.com/CelestialAmber/bgbtest). While still being a work in progress, it's interesting to see how another person interprets your code when disassembling it. |
0 commit comments