Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add getting-started to part 2 #21

Merged
merged 20 commits into from
Aug 13, 2022
Merged
Show file tree
Hide file tree
Changes from 2 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions src/SUMMARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@

# Part Ⅱ — Our first game

- [Getting started](part2/getting-started.md)
- [Work in progress](part2/wip.md)

# Part Ⅲ — Our second game
Expand Down
118 changes: 118 additions & 0 deletions src/part2/getting-started.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
# Getting started

In this lesson we will start a new project from scratch, a [Breakout](https://en.wikipedia.org/wiki/Breakout_%28video_game%29) (also known as [Arkanoid](https://en.wikipedia.org/wiki/Arkanoid)) clone called "Unbricked"! (Or any other name you like, as this is *your* project)

Open a terminal and make a new directory (`mkdir unbricked`), and then enter it (`cd unbricked`), just like you did for "Hello, world!".

Start by creating a file called `main.asm`, and include `hardware.inc` in your code.

```
line 1
```

Then create a header. Remember from part 1 that the header includes some information the Game Boy relies on, so you don't wanna accidentally leave it out.

```
lines 3-7
```

The header jumps to `EntryPoint`, so let's write that now:

```
lines 9-18
```

The next few lines wait until "VBlank".
VBlank basically means that the Game Boy's PPU has gone to sleep for a short time, during which we can do things like turning off the screen.

Turning off the screen is important because the PPU may wake back up at while we're still working.
By turning the screen off completely, we ensure that our code won't be interrupted.
You can only load new graphics while the PPU is sleeping, so this gives us as much time as we need to load our tiles.

Speaking of tiles, we're going to load some into VRAM next, using the following code:
```
lines 20-31
```

This loop might look familiar if you've read part 1.
It copies `Tiles` to `$9000`, which is the part of VRAM where tiles are stored.
Copy link
Member

@ISSOtm ISSOtm Jul 11, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
It copies `Tiles` to `$9000`, which is the part of VRAM where tiles are stored.
It copies [tile data](../part1/tiles.md) starting at `Tiles` to `$9000` onward, which is a part of VRAM where tiles are stored.

Copy link
Contributor Author

@evie-calico evie-calico Jul 11, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

which is a/the part of VRAM where tiles are stored.

This originally said "a" but @avivace suggested I change it, maybe he wants to give some input on this?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

$9000 is not the beginning of that area, so I think calling it "the" is wrong.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My suggestion meant to try to clarify what $9000 was (a choice in a range?)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

_VRAM + $1000?

To get the length of `Tiles` we use another label at the end, called `TilesEnd`, and subtract the two to find the difference.

Note that our code still doesn't have a lable called `Tiles`.
We'll get to that later!

We're almost done now.
Next, write another loop, this time for copying the tilemap, which will organize our tiles on the screen.

```
lines 33-44
```

You might notice that while this code is exactly the same, the 3 values loaded into `de`, `hl`, and `bc` are different.
These determine the source, destination, and size of the copy, respectively.

Finally, we are going to turn the screen back on and initialize a background palette.
hardware.inc provides the constants `LCDCF_ON` and `LCDCF_BGON`, which enable the screen and the background.
We must "combine" these together using `|` (the or operator).

```
lines 46-55
```

There's one last thing we need before we can build the rom, and that's our graphics.
We're going to be drawing the following screen:

![Layout of unbricked](https://github.com/ISSOtm/gb-asm-tutorial-part2/blob/main/tilemap.png?raw=true)

In the "Hello, world!" lesson, you saw graphics which were written out by hand in hexadecimal.
This time, we're going to write our graphics in a more friendly way; by assigning a character to each shade.
To do this, type `dw`, followed by a space, a backtick (\`) and a series of 8 characters; by default these are 0, 1, 2, and 3, going from lightest to darkest.
This defines a row of 8 pixels.

```rgbasm,linenos
; For example:
Tiles:
dw `01230123
```

(A note about OPT g could be added here?)

We already have tiles made for this project, so you can copy [this premade file](https://github.com/ISSOtm/gb-asm-tutorial-part2/raw/main/tileset.asm), and paste it at the end of your code.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The lines must be included inline (possibly with a max-height applied to the block), especially since there is a handy "copy to clipboard" button.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree, but I'm not sure how to do that >< so an example would be appreciated.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We'll have to figure out the details once #17 is resolved.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think #17 should be blocking, as it involves a large amount of work to set everything up. Please just start with the example code "imported"..


Then copy the tilemap from [this file](https://github.com/ISSOtm/gb-asm-tutorial-part2/raw/main/tilemap.asm), and paste it after the `TilesEnd` label.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same.


You can try building the rom at this point, using the following commands in your terminal:

```console
$ rgbasm -L -o main.o main.asm
$ rgblink -o unbricked.gb main.o
$ rgbfix -v -p 0xFF unbricked.gb
```

If you run this in your emulator, you should see the following:

(Screenshot pending :P)

That white square seems to be missing!
If you paid attention to your tiles earlier, you may have noticed this comment:

```
lines 135-140
```

The logo tiles were left intentionally blank so that you could customize this project.
If you feel up to it, you can try creating your own logo by hand, or you can copy one of the following logos into your code:

## RGBDS Logo
[Source](https://github.com/ISSOtm/gb-asm-tutorial-part2/raw/main/rgbds.asm)
![The RGBDS Logo](https://github.com/ISSOtm/gb-asm-tutorial-part2/blob/main/rgbds.png?raw=true)

## Duck
[Source](https://github.com/ISSOtm/gb-asm-tutorial-part2/raw/main/duck.asm)
![A pixel-art duck](https://github.com/ISSOtm/gb-asm-tutorial-part2/blob/main/duck.png?raw=true)

## Tail
[Source](https://github.com/ISSOtm/gb-asm-tutorial-part2/raw/main/tail.asm)
![A silhouette of a tail](https://github.com/ISSOtm/gb-asm-tutorial-part2/blob/main/tail.png?raw=true)

Build your game again and your logo of choice should appear in the bottom right!